Module documentation for 0.18
brick is a Haskell terminal user interface programming library in the
style of gloss. This means
you write a function that describes how your user interface should look,
but the library takes care of a lot of the book-keeping that so commonly
goes into writing such programs.
brick exposes a declarative API. Unlike most GUI toolkits which
require you to write a long and tedious sequence of “create a widget,
now bind an event handler”,
brick just requires you to describe your
interface using a set of declarative combinators. Then you provide a
function to transform your application state when input or other kinds
of events arrive.
Under the hood, this library builds upon vty, so some knowledge of Vty will be helpful in using this library.
This library deprecates vty-ui.
Here’s an example interface (see
withBorderStyle unicode $ borderWithLabel (str "Hello!") $ (center (str "Left") <+> vBorder <+> center (str "Right"))
┌─────────Hello!─────────┐ │ │ │ │ │ │ │ Left │ Right │ │ │ │ │ │ │ └────────────────────────┘
$ cabal sandbox init $ cabal install -j -f demos $ .cabal-sandbox/bin/brick-???-demo
To get started, see the first few sections of the brick user guide.
brick comes with a bunch of widget types to get you started:
- Vertical and horizontal box layout widgets
- Basic single- and multi-line text editor widgets
- List widget
- Progress bar widget
- Simple dialog box widget
- Border-drawing widgets (put borders around or in between things)
- Generic scrollable viewports
- Extensible widget-building API
- (And many more general-purpose layout control combinators)
In addition, some of
brick’s more powerful features may not be obvious
- All widgets can be arranged in predictable layouts so you don’t have to worry about terminal resizes.
- Attribute management is flexible and can be customized at runtime on a per-widget basis.
brick-users Google Group / e-mail list is a place to discuss
library changes, give feedback, and ask questions. You can subscribe at:
Your documentation options, in recommended order, are:
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.
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
whether the exported interface is usable and complete!
Please file bug reports as GitHub issues. For best results:
Include the versions of relevant software packages: your terminal emulator,
vtywill be the most important ones.
Clearly describe the behavior you expected …
… and include a minimal demonstration program that exhibits the behavior you actually observed.
If you decide to contribute, that’s great! Here are some guidelines you should consider to make submitting patches easier for all concerned:
- If you want to take on big things, talk to me first; let’s have a design/vision discussion before you start coding. Create a GitHub issue and we can use that as the place to hash things out.
- Please make changes consistent with the conventions I’ve used in the codebase.
- Please adjust or provide Haddock and/or user guide documentation relevant to any changes you make.
- Added a dependency on data-clist.
- Brick.Focus: removed the Functor instance for FocusRing.
- Brick.Focus: re-implemented FocusRing in terms of the circular list data structure from data-clist. In addition, this change introduced “focusRingModify”, which permits the user to use the data-clist API to directly manipulate the FocusRing’s internals. This way brick doesn’t have to re-invent the wheel on the focus ring behavior.
- Added programs/ReadmeDemo.hs and featured its output and code in the README to provide an early demonstration
- centerAbout now right- and bottom-pads its operand to behave consistently with h/vCenter
- Use Extra-Doc-Files instead of Data-Files for documentation files
- List: correctly update selected index in listInsert
- Update example program in brick.cabal (thanks @timbod7)
- Updated to depend on Vty 5.15.
- Updated to remove dependency on data-default.
- Discontinued support for GHC versions prior to 7.10.1.
- Removed Data.Default instances for AttrName, AttrMap, Result, and BorderStyle (use Monoid instances instead where possible).
- Added defaultBorderStyle :: BorderStyle.
- Added emptyResult :: Result n.
This release includes a breaking API change:
- Brick now uses bounded channels (Brick.BChan.BChan) for event communication rather than Control.Concurrent.Chan’s unbounded channels to improve memory consumption for programs with runaway event production (thanks Joshua Chia)
Other API changes:
- Brick.List got a new function, listModify, for modifying the selected element (thanks @diegospd)
- hBox and vBox now use the more efficient DList data structure when rendering to improve performance for boxes with many elements (thanks Mitsutoshi Aoe)
- viewport: do not cull cursor locations on empty viewport contents (fixes #105)
- User guide CounterEvent type fix (thanks @diegospd)
- List: fixed empty list validation in listReplace (thanks Joshua Chia)
- MouseDemo: add an editor and use mouse events to move the cursor
- MouseDemo: Enhance MouseDemo to show interaction between ‘clickable’ and viewports (thanks Kevin Quick)
- Editors now report mouse click events
- Rename TerminalLocation row/column fields to avoid commonplace name clashes; rename row/column to locationRow/locationColumn (fixes #96)
- Core: make cropToContext also crop extents (fixes #101)
- viewport: if the sub-widget is not rendered, also cull all extents and cursor locations
- User Guide updates: minor fixes, updates to content on custom widgets, wide character support, and examples (thanks email@example.com, Kevin Quick)
This release added support for wide characters. In particular, wide characters can now be entered into the text editor widget and used in ‘str’ and ‘txt’ widgets.
- Mouse mode is no longer enabled by default.
- customMain’s event channel parameter is now optional
- FocusRing now provides a Functor instance (thanks Ian Jeffries)
This release primarily adds support for mouse interaction. For details, see the Mouse Support section of the User Guide. This release also includes breaking API changes for the App type. Here’s a migration guide:
- Event handlers now take “BrickEvent n e” instead of “e”, where “e” was the custom event type used before this change. To recover your own custom events, pattern-match on “AppEvent”; to recover Vty input events, pattern-match on “VtyEvent”.
- appLiftVtyEvent went away and can just be removed from your App record constructor.
- If you aren’t using the custom event type or were just using Vty’s “Event” type as your App’s event type, you can set your event type to just “e” because you’ll now be able to get Vty events regardless of whether you use a custom event type.
- Added the Widget combinator “clickable” to indicate that a widget should generate mouse click events
- Added the Extent data type and the “reportExtent” widget combinator to report the positions and sizes of widgets
- Rendering “Result” values now include reported extents and update their offsets (adds “extents” field and “extentsL” lens)
- Added “lookupExtent”, “findClickedExtents”, and “clickedExtent” in EventM to find extents and check them for mouse clicks
- Removed appLiftVtyEvent. Instead of wrapping Vty’s events in your own type, you now get a “BrickEvent” that always contains Vty events but has the ability to embed your custom events. See the User Guide for details.
- Added demo program MouseDemo.hs
- Added demo program ProgressBarDemo.hs (thanks Kevin Quick)
- Added mapAttrname, mapAttrNames, and overrideAttr functions (thanks Kevin Quick)
- Make handleEventLensed polymorphic over event type to allow use with custom events (thanks Kevin Quick)
- Added Ord constraint to some library startup functions
- Added Show instance for Editor, List (fixes #63)
- Updated documentation to use new “resource name” terminology to reduce confusion and better explain the purpose of names.
- Updated user guide with sections on mouse support, the rendering cache, resource names, paste mode, and extents
- Depend on Vty 5.11.3 to get mouse mode support
- Added getVtyHandle in EventM for obtaining the current Vty context. It returns Nothing when calling the appStartEvent handler but after that a context is always available.
- Added a rendering cache. To use the rendering cache, use the ‘cached’ widget combinator. This causes drawings of the specified widget to re-use a cached rendering until the rendering cache is invalidated with ‘invalidateCacheEntry’ or ‘invalidateCache’. This change also includes programs/CacheDemo.hs. This change introduced an Ord constraint on the name type variable ‘n’.
- Added setTop and setLeft for setting viewport offsets directly in EventM.
- Dialog event handlers now support left and right arrow keys (thanks Grégoire Charvet)
- On resizes brick now draws the application twice before handling the resize event. This change makes it possible for event handlers to get the latest viewport states on a resize rather than getting the most recent (but stale) versions as before, at the cost of a second redraw.
- We now use the most recent rendering state when setting up event handler viewport data. This mostly won’t matter to anyone except in cases where a viewport name was expected to be in the viewport map but wasn’t due to using stale rendering state to set up EventM.
- Depend on text-zipper 0.7.1
- The editor widget state value is now polymorphic over the type of “string” value that can be edited, so you can now create editors over Text values as well as Strings. This is a breaking change but it only requires the addition of the string type variable to any uses of Editor. (thanks Jason Dagit and Getty Ritter)
- Added some missing Eq and Show instances (thanks Grégoire Charvet)
- The editor now binds Control-U to delete to beginning of line (thanks Hans-Peter Deifel)
- List: avoid runtime exception by ensuring item height is always at least 1
- Center: added layer-friendly centering functions centerLayer, hCenterLayer, and vCenterLayer.
- Dialog now uses new layer-friendly centering functions. This makes it possible to overlay a Dialog on top of your UI when you use a Dialog rendering as a separate layer.
- Updated the LayerDemo to demonstrate a centered layer.
- The renderer now uses a default Vty Picture background of spaces with the default attribute, rather than using ClearBackground (the Vty default). This is to compensate for an unexpected attribute behavior in Vty when ClearBackgrounds (see https://github.com/coreyoconnor/vty/issues/95)
NOTE: this release includes many API changes. Please see the “Widget Names” section of the Brick User Guide for details on the fundamentals!
- The “Name” type was removed. In its place we now have a name type
variable (“n”) attached to many types (including EventM,
CursorLocation, App, Editor, List, and FocusRing). This change makes
it possible to:
- Avoid runtime errors due to name typos
- Achieve compile-time guarantees about name matching and usage
- Force widget functions to be name-agnostic by being polymorphic in their name type
- Clean up focus handling by making it possible to pattern-match on cursor location names
- The EditDemo demonstration program was updated to use a FocusRing.
- Added the “Named” type class to Brick.Widgets.Core for types that store names. This type class is used to streamline the Focus interface; see Brick.Focus.withFocusRing and EditDemo.hs.
- The List and Editor types are now parameterized on names.
- The List widget is now focus-aware; its rendering function now takes
a boolean indicating whether it should be rendered with focus. The
List uses the following attributes now:
- When not focused, the cursor is rendered with listSelectedAttr.
- When focused, the cursor is rendered with listSelectedFocusedAttr.
- The Editor widget is now focus-aware; its rendering function now
takes a boolean indicating whether it should be rendered with focus.
The Editor uses the following attributes now:
- When not focused, the widget is rendered with editAttr.
- When focused, the widget is rendered with editFocusedAttr.
- The Dialog’s name constructor parameter and lens were removed.
- The ‘viewport’ function was modified to raise a runtime exception if the widget name it receives is used more than once during the rendering of a single frame.
- Many modules now use conditional imports to silence redundancy warnings on GHCs with newer Preludes (e.g. including Monoid, Foldable, Traversable, Applicative, etc.)
- Add missing Functor instance for Next type (thanks Markus Hauck)
- List: the list now properly renders when the available height is not a multiple of the item height. Previously the list size would decrease relative to the available height. Now the list renders enough items to fill the space even if the top-most or bottom-most item is partially visible, which is the expected behavior.
- Editor: the ‘editor’ initial content parameter is now correctly split on newlines to ensure that the underlying editor zipper is initialized properly. (fixes #56; thanks @listx)
- Added lower bound for microlens >= 0.3.0.0 to fix build failure due to Field1 not being defined (thanks Markus Hauck)
- Updated user guide and README to link to and mention microlens instead of lens
- Fixed a qualified import in the List demo to avoid ambiguity (thanks Alan Gilbert)
- Brick now uses the microlens family of packages instead of lens. This version of brick also depends on vty 5.5.0, which was modified to use microlens instead of lens. This change shouldn’t impact functionality but will greatly reduce build times.
- Fix negative cropping in hCenter, vCenter, and cropResultToContext (fixes #52)
- Remove unnecessary Eq constraint from listReplace (fixes #48; thanks sifmelcara)
- Mention Google Group in README
- Markup: make markup support multi-line strings (fixes #41)
- brick-edit-demo: support shift-tab to switch editors
- Core: improve box layout algorithm (when rendering boxes, track remaining space while rendering high-priority children to use successively more constrained primary dimensions)
- Core: make fixed padding take precedence over padded widgets (fixes #42) Prior to this commit, padding a widget meant that if there was room after rendering the widget, the specified amount of padding would be added. This meant that under tight layout constraints padding would disappear before a padded widget would. This is often a desirable outcome but it also led to unexpected behavior when adding padding to a widget that grows greedily: fixed padding would never show up because it was placed in a box adjacent to the widget in question, and boxes always render greedy children before fixed ones. As a result fixed padding would disappear under these conditions. Instead, in the case of fixed padding, since we often intend to guarantee that padding is present, all of the padding combinators have been modified so that when the padded widget is rendered with fixed padding in the amount V, the widget is given V fewer rows/columns when it is rendered so that the padding always has room.
- Fixed a bug in the ‘visible’ combinator: If the size of the visibility request was larger than the available space, then the rendering of a viewport was toggling between two states, one with aligning on the end of the visibility request, and another one aligning on the start. This commit fixes it so that a visibility request is always aligned on the start if not enough space is available. (thanks Thomas Strobel firstname.lastname@example.org)
- Honor multiple ‘visible’ markers in a single viewport with preference on the innermost request (thanks Thomas Strobel email@example.com)
- Added Brick.Widgets.Core.unsafeLookupViewport to make certain kinds of custom widget implementations easier when viewport states are needed (thanks Markus Hauck firstname.lastname@example.org)
- List: added listClear and listReverse functions (thanks Markus Hauck)
- List: Derive instances for Functor, Foldable, Traversable (thanks Markus Hauck)
- Hyperlink “Data.Text.Markup” inside Brick.Markup haddock (thanks Markus Hauck)
- Fix typo in ‘Attribute Management’ section of user guide (thanks Markus Hauck)
- EventM newtype again instances MonadIO (thanks Andrew Rademacher)
- Made EventM a newtype instead of a type alias
- List: listReplace now takes the new selected index and no longer does element diffing
- Removed the dependency on the Diff package
- Applied some hlint hints (thanks Markus Hauck email@example.com)
- Fixed a typo in the README (thanks Markus Hauck firstname.lastname@example.org)
- Improved the renderList documentation (thanks Profpatsch email@example.com)
- Types: added an explicit import of Applicative for older GHCs
- Fixed viewport behavior when the image in a viewport reduces its size enough to render the viewport offsets invalid. Before, this behavior caused a crash during image croppin in vty; now the behavior is handled sanely (fixes #22; reported by Hans-Peter Deifel)
- Improved the list demo by using characters instead of integers in the demo list and cleaned up item-adding code (thanks Jøhannes Lippmann firstname.lastname@example.org)
- Fixed size policy of lists so that rather than being Fixed/Fixed, they are Greedy/Greedy. This resolves issues that arise when the box layout widget renders a list widget alongside a Fixed/Fixed one. (Closes issue #17, thanks Karl Voelker)
- vScrollPage actually scrolls vertically now rather than horizontally (Thanks Hans-Peter Deifel email@example.com)
- Added top-level
Brickmodule that re-exports the most important modules in the library.
- Now instead of passing the item-drawing function to the
liststate constructor, it is passed to
renderListnow takes the row height of the list’s item widgets. The list item-drawing function must respect this in order for scrolling to work properly. This change made it possible to optimize the list so that it only draws widgets visible in the viewport rather than rendering all of the list’s items (even the ones off-screen). But to do this we must be able to tell in advance how high each one is, so we require this parameter. In addition this change means that lists no longer support items of different heights.
- The list now uses Data.Vector instead of [a] to store items; this permits efficient slicing so we can do the optimized rendering described above.
- Now instead of passing the item-drawing function to the
handleEventmethod now runs in
EventM. This permits event-handling code implemented in terms of
HandleEventto do get access to viewport state and to run IO code, making it just as powerful as code in the top-level
- Many types were moved from
Brick.Types, making the former module merely a home for
Widgetconstructors and combinators.
Widgetwas removed; this might be reinstated later, but this package provides enough
IsStringinstances that things can get confusing.
EventMis now reader monad over the most recent rendering pass’s viewport state, in addition to being a state monad over viewport requests for the renderer. Added the
lookupViewportfunction to provide access to the most recent viewport state. Exported the
Viewporttype and lenses.
- Now that
handleEventis now an
EventMaction, composition with
continueet al got a little messier when using lenses to update the application state. To help with this, there is now
- Lists now perform well with 10 items or a million (see above; fixes #7, thanks Simon Michael)
- Added more haddock notes to
Brick.Widgets.Coreabout growth policies.
- Forced evaluation of render states to address a space leak in the renderer (fixes #14, thanks Sebastian Reuße firstname.lastname@example.org)
- str: only reference string content that can be shown (eliminates a space leak, fixes #14, thanks Sebastian Reuße email@example.com)
- Added a makefile for the user guide.
- List: added support for Home and End keys (thanks Simon Michael)
- Viewports: when rendering viewports, scroll requests from
EventMare processed before visibility requests from the rendering process; this reverses this previous order of operations but permits user-supplied event handlers to reset viewports when desired.