diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ Brick changelog --------------- +0.24.2 +------ + +Miscellaneous: + * Minor documentation updates including a clarification for #135 + 0.24.1 ------ diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -70,9 +70,19 @@ $ .cabal-sandbox/bin/brick-???-demo ``` -To get started, see the [first few sections of the brick -user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst). +To get started, see the [user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst). +Documentation +------------- + +Documentation for `brick` comes in a variety of forms: + +* [The brick user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst) +* [Samuel Tay's brick tutorial](https://github.com/jtdaugherty/brick/blob/master/docs/samtay-tutorial.md) +* Haddock (all modules) +* [Demo programs](https://github.com/jtdaugherty/brick/blob/master/programs) +* [FAQ](https://github.com/jtdaugherty/brick/blob/master/FAQ.md) + Feature Overview ---------------- @@ -104,30 +114,18 @@ [https://groups.google.com/group/brick-users](https://groups.google.com/group/brick-users) -Documentation -------------- - -Your documentation options, in recommended order, are: - -* [FAQ](https://github.com/jtdaugherty/brick/blob/master/FAQ.md) -* [The brick user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst) -* [Samuel Tay's brick tutorial](https://github.com/jtdaugherty/brick/blob/master/docs/samtay-tutorial.md) -* Haddock (all modules) -* [Demo programs](https://github.com/jtdaugherty/brick/blob/master/programs) - Status ------ -`brick` is young and may be missing some essential features. There are -some places were I have deliberately chosen to worry about performance -later for the sake of spending more time on the design (and to wait on -performance issues to arise first). `brick` is also something of an -experimental project of mine and some aspects of the design involve -trade-offs that are not entirely settled. In addition you can expect -this library to follow a principle of fearless improvement: new versions -will make (sometimes substantial) API changes if those changes really do -make the library better. I will place more importance on getting the API -right than on maintaining backwards compatibility. +There are some places were I have deliberately chosen to worry about +performance later for the sake of spending more time on the design (and +to wait on performance issues to arise first). `brick` is also something +of an experimental project of mine and some aspects of the design +involve trade-offs that may are not entirely settled. In addition you +can expect this library to follow a principle of fearless improvement: +new versions will make (sometimes substantial) API changes if those +changes really do make the library better. I will place more importance +on getting the API right than on maintaining backwards compatibility. `brick` exports an extension API that makes it possible to make your own packages and widgets. If you use that, you'll also be helping to test diff --git a/brick.cabal b/brick.cabal --- a/brick.cabal +++ b/brick.cabal @@ -1,5 +1,5 @@ name: brick -version: 0.24.1 +version: 0.24.2 synopsis: A declarative terminal user interface library description: Write terminal applications painlessly with 'brick'! You write an @@ -97,19 +97,6 @@ template-haskell, deepseq >= 1.3 && < 1.5, word-wrap >= 0.2 - -executable brick-testing - if !flag(demos) - Buildable: False - hs-source-dirs: programs - ghc-options: -threaded -Wall -fno-warn-unused-do-bind -O3 - default-language: Haskell2010 - default-extensions: CPP - main-is: Testing.hs - build-depends: base, - brick, - vty, - text executable brick-readme-demo if !flag(demos) diff --git a/docs/guide.rst b/docs/guide.rst --- a/docs/guide.rst +++ b/docs/guide.rst @@ -605,7 +605,10 @@ How widgets use space when rendered is described in two pieces of information in each ``Widget``: the widget's horizontal and vertical growth policies. These fields have type ``Brick.Types.Size`` and can -have the values ``Fixed`` and ``Greedy``. +have the values ``Fixed`` and ``Greedy``. Note that these values are +merely *descriptive hints* about the behavior of the rendering function, +so it's important that they accurately describe the widget's use of +space. A widget advertising a ``Fixed`` size in a given dimension is a widget that will always consume the same number of rows or columns no @@ -651,6 +654,11 @@ When using widgets it is important to understand their horizontal and vertical space behavior by knowing their ``Size`` values. Those should be made clear in the Haddock documentation. + +The rendering context's specification of available space will also +govern how widgets get cropped, since all widgets are required to render +to an image no larger than the rendering context specifies. If they do, +they will be forcibly cropped. Limiting Rendering Area ----------------------- diff --git a/programs/Testing.hs b/programs/Testing.hs deleted file mode 100644 --- a/programs/Testing.hs +++ /dev/null @@ -1,78 +0,0 @@ -{-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE ViewPatterns #-} - -module Main where - -import Control.Monad (void) -import Data.Function ((&)) -import Data.Function (on) -import Data.List (transpose) - -import qualified Brick as B -import qualified Brick.Widgets.Core as B -import qualified Brick.Widgets.Border as B -import qualified Brick.Widgets.Center as B -import qualified Graphics.Vty as V - -type Name = () -data Tick -data Game - -app :: B.App Game Tick Name -app = B.App - { B.appDraw = drawUI - , B.appChooseCursor = B.neverShowCursor - , B.appHandleEvent = handleEvent - , B.appStartEvent = pure - , B.appAttrMap = const theMap - } - -theMap :: B.AttrMap -theMap = B.attrMap V.defAttr - [ (blackSquare, go V.withBackColor V.black) - , (redSquare, go V.withBackColor V.red) - ] - where - go a b = a V.defAttr b - -blackSquare, redSquare :: B.AttrName -blackSquare = "blackSquare" -redSquare = "redSquare" - -vkey :: B.BrickEvent Name Tick -> Maybe V.Key -vkey (B.VtyEvent (V.EvKey y [])) = Just y -vkey _ = Nothing - -handleEvent :: Game -> B.BrickEvent Name Tick -> B.EventM Name (B.Next Game) -handleEvent g (vkey -> Just (V.KChar 'q')) = g & B.halt -handleEvent g (vkey -> Just (V.KEsc)) = g & B.halt -handleEvent g (vkey -> Nothing) = g & B.continue -handleEvent g _ = g & B.continue - -drawUI :: Game -> [B.Widget Name] -drawUI = pure . drawBoard - -boardNumbers :: Game -> [[B.Widget Name]] -boardNumbers _ = - board - where - (.:) = (.) . (.) - - ap = take 8 .: zipC `on` repeat - - board = ap oddRows evenRows - oddRows = ap reds blacks - evenRows = ap blacks reds - - zipC = (concat . transpose) .: mappend `on` pure - - pattern p = B.withAttr p . B.center . B.str $ " " - - reds = pattern redSquare - blacks = pattern blackSquare - -drawBoard :: Game -> B.Widget Name -drawBoard = B.border . B.vBox . fmap B.hBox . boardNumbers - -main :: IO () -main = void $ B.defaultMain app undefined diff --git a/src/Brick/Widgets/Border.hs b/src/Brick/Widgets/Border.hs --- a/src/Brick/Widgets/Border.hs +++ b/src/Brick/Widgets/Border.hs @@ -91,6 +91,13 @@ -- | Put a border around the specified widget with the specified label -- widget placed in the middle of the top horizontal border. +-- +-- Note that a border will wrap its child widget as tightly as possible, +-- which means that if the child widget is narrower than the label +-- widget, the label widget will be truncated. If you want to avoid +-- this behavior, add a 'fill' or other space-filling wrapper to the +-- bordered widget so that it takes up enough room to make the border +-- horizontally able to avoid truncating the label. borderWithLabel :: Widget n -- ^ The label widget -> Widget n diff --git a/src/Brick/Widgets/Core.hs b/src/Brick/Widgets/Core.hs --- a/src/Brick/Widgets/Core.hs +++ b/src/Brick/Widgets/Core.hs @@ -90,7 +90,7 @@ import Data.Monoid ((<>), mempty) #endif -import Lens.Micro ((^.), (.~), (&), (%~), to, _1, _2, each, to, ix, Lens') +import Lens.Micro ((^.), (.~), (&), (%~), to, _1, _2, each, to, Lens') import Lens.Micro.Mtl (use, (%=)) import Control.Monad ((>=>),when) import Control.Monad.Trans.State.Lazy