Documentation

Events.

A display attribute defines the Color and Style of all the characters rendered after the attribute is applied.

At most 256 colors, picked from a 240 and 16 color palette, are possible for the background and foreground. The 240 colors and 16 colors are points in different palettes. See Color for more information.

Build a widget from markup.

Build a piece of markup from text with an assigned attribute name. When the markup is rendered, the attribute name will be looked up in the rendering context's AttrMap to determine the attribute to use for this piece of text.

A type class for types that provide access to an attribute in the rendering monad. You probably won't need to instance this.

Extract the text from markup, discarding the markup metadata.

Markup with metadata type a assigned to each character.

Return a list's selected element, if any.

Only evaluates as much of the container as needed.

Complexity: same as splitAt for the container type.

listSelectedElement for List: O(1)
listSelectedElement for Seq: O(log(min(i, n - i)))

Replace the contents of a list with a new set of elements and update the new selected index. If the list is empty, empty selection is used instead. Otherwise, if the specified selected index (via Just) is not in the list bounds, zero is used instead.

Complexity: same as splitAt for the container type.

Like renderList, except the render function is also provided with the index of each element.

Has the same evaluation characteristics as renderList.

Render a list using the specified item drawing function.

Evaluates the underlying container up to, and a bit beyond, the selected element. The exact amount depends on available height for drawing and listItemHeight. At most, it will evaluate up to element (i + h + 1) where i is the selected index and h is the available height.

Note that this function renders the list with the listAttr as the default attribute and then uses listSelectedAttr as the default attribute for the selected item if the list is not focused or listSelectedFocusedAttr otherwise. This is provided as a convenience so that the item rendering function doesn't have to be concerned with attributes, but if those attributes are undesirable for your purposes, forceAttr can always be used by the item rendering function to ensure that another attribute is used instead.

Construct a list in terms of container t with element type e.

The attribute used only for the currently-selected list item when the list does not have focus. Extends listAttr.

The top-level attribute used for the entire list.

Enable list movement with the vi keys with a fallback handler if none match. Use handleListEventVi handleListEvent in place of handleListEvent to add the vi keys bindings to the standard ones. Movements handled include:

• Up (k)
• Down (j)
• Page Up (Ctrl-b)
• Page Down (Ctrl-f)
• Half Page Up (Ctrl-u)
• Half Page Down (Ctrl-d)
• Go to first element (g)
• Go to last element (G)

Handle events for list cursor movement. Events handled are:

• Up (up arrow key)
• Down (down arrow key)
• Page Up (PgUp)
• Page Down (PgDown)
• Go to first element (Home)
• Go to last element (End)

An alias for GenericList specialized to use a Vector as its container type.

List state. Lists have a container t of element type e that is the data stored by the list. Internally, Lists handle the following events by default:

• Up/down arrow keys: move cursor of selected item
• Page up / page down keys: move cursor of selected item by one page at a time (based on the number of items shown)
• Home/end keys: move cursor of selected item to beginning or end of list

The List type synonym fixes t to Vector for compatibility with previous versions of this library.

For a container type to be usable with GenericList, it must have instances of Traversable and Splittable. The following functions impose further constraints:

• listInsert: Applicative and Semigroup
• listRemove: Semigroup
• listClear: Monoid
• listReverse: Reversible

Suspend the event loop, save the terminal state, and run the specified action. When it returns an application state value, restore the terminal state, empty the rendering cache, redraw the application from the new state, and resume the event loop.

Note that any changes made to the terminal's input state are ignored when Brick resumes execution and are not preserved in the final terminal input state after the Brick application returns the terminal to the user.

Halt the event loop and return the specified application state as the final state value.

Continue running the event loop with the specified application state.

Build a viewport scroller for the viewport with the specified name.

Show the cursor with the specified resource name, if such a cursor location has been reported.

Always show the first cursor, if any, returned by the rendering process. This is a convenience function useful as an appChooseCursor value when a simple program has zero or more widgets that advertise a cursor position.

Ignore all requested cursor positions returned by the rendering process. This is a convenience function useful as an appChooseCursor value when a simple application has no need to position the cursor.

Invalidate the entire rendering cache.

Invalidate the rendering cache entry with the specified resource name.

Get the Vty handle currently in use.

Given a mouse click location, return the extents intersected by the click. The returned extents are sorted such that the first extent in the list is the most specific extent and the last extent is the most generic (top-level). So if two extents A and B both intersected the mouse click but A contains B, then they would be returned [B, A].

Given a resource name, get the most recent rendering extent for the name (if any).

Did the specified mouse coordinates (column, row) intersect the specified extent?

Given a viewport name, get the viewport's size and offset information from the most recent rendering. Returns Nothing if no such state could be found, either because the name was invalid or because no rendering has occurred (e.g. in an appStartEvent handler).

Like customMain, except the last Vty handle used by the application is returned without being shut down with shutdown. This allows the caller to re-use the Vty handle for something else, such as another Brick application.

The custom event loop entry point to use when the simpler ones don't permit enough control. Returns the final application state after the application halts.

Note that this function guarantees that the terminal input state prior to the first Vty initialization is the terminal input state that is restored on shutdown (regardless of exceptions).

An event-handling function which continues execution of the event loop only when resize events occur; all other types of events trigger a halt. This is a convenience function useful as an appHandleEvent value for simple applications using the Event type that do not need to get more sophisticated user input.

A simple application with reasonable defaults to be overridden as desired:

• Draws only the specified widget
• Quits on any event other than resizes
• Has no start event handler
• Provides no attribute map
• Never shows any cursors

A simple main entry point which takes a widget and renders it. This event loop terminates when the user presses any key, but terminal resize events cause redraws.

The default main entry point which takes an application and an initial state and returns the final state returned by a halt operation.

The library application abstraction. Your application's operations are provided in an App and then the App is provided to one of the various main functions in this module. An application App s e n is in terms of an application state type s, an application event type e, and a resource name type n. In the simplest case e is unused (left polymorphic or set to ()), but you may define your own event type and use customMain to provide custom events. The state type s is the type of application state to be provided by you and iteratively modified by event handlers. The resource name type n is the type of names you can assign to rendering resources such as viewports and cursor locations. Your application must define this type.

A viewport scrolling handle for managing the scroll state of viewports.

A vertical border. Fills all vertical space.

A horizontal border. Fills all horizontal space.

Put a border around the specified widget.

The top-level border attribute name.

Center a widget both vertically and horizontally. Consumes all available vertical and horizontal space.

Center a widget vertically. Consumes all vertical space.

Turn an editor state value into a widget. This uses the editor's name for its scrollable viewport handle and the name is also used to report mouse events.

Get the contents of the editor.

Apply an editing operation to the editor's contents. Bear in mind that you should only apply zipper operations that operate on the current line; the editor will only ever render the first line of text.

Construct an editor over String values

Construct an editor over Text values

Editor state. Editors support the following events by default:

• Ctrl-a: go to beginning of line
• Ctrl-e: go to end of line
• Ctrl-d, Del: delete character at cursor position
• Backspace: delete character prior to cursor position
• Ctrl-k: delete all from cursor to end of line
• Ctrl-u: delete all from cursor to beginning of line
• Arrow keys: move cursor
• Enter: break the current line at the cursor position
• Paste: Bracketed Pastes from the terminal will be pasted, provided the incoming data is UTF-8-encoded.

Vertical box layout: put the specified widgets one above the other in the specified order. Defers growth policies to the growth policies of both widgets. This operator is a binary version of vBox.

Horizontal box layout: put the specified widgets next to each other in the specified order. Defers growth policies to the growth policies of both widgets. This operator is a binary version of hBox.

Similar to visible, request that a region (with the specified Location as its origin and DisplayRegion as its size) be made visible when it is rendered inside a viewport. The Location is relative to the specified widget's upper-left corner of (0, 0).

This does nothing if not rendered in a viewport.

Request that the specified widget be made visible when it is rendered inside a viewport. This permits widgets (whose sizes and positions cannot be known due to being embedded in arbitrary layouts) to make a request for a parent viewport to locate them and scroll enough to put them in view. This, together with viewport, is what makes the text editor and list widgets possible without making them deal with the details of scrolling state management.

This does nothing if not rendered in a viewport.

Given a name, obtain the viewport for that name by consulting the viewport map in the rendering monad. NOTE! Some care must be taken when calling this function, since it only returns useful values after the viewport in question has been rendered. If you call this function during rendering before a viewport has been rendered, you may get nothing or you may get a stale version of the viewport. This is because viewports are updated during rendering and the one you are interested in may not have been rendered yet. So if you want to use this, be sure you know what you are doing.

Render the specified widget in a named viewport with the specified type. This permits widgets to be scrolled without being scrolling-aware. To make the most use of viewports, the specified widget should use the visible combinator to make a "visibility request". This viewport combinator will then translate the resulting rendering to make the requested region visible. In addition, the EventM monad provides primitives to scroll viewports created by this function if visible is not what you want.

If a viewport receives more than one visibility request, then the visibility requests are merged with the inner visibility request taking preference. If a viewport receives more than one scrolling request from EventM, all are honored in the order in which they are received.

Some caution should be advised when using this function. The viewport renders its contents anew each time the viewport is drawn; in many cases this is prohibitively expensive, and viewports should not be used to display large contents for scrolling. This function is best used when the contents are not too large OR when the contents are large and render-cacheable.

If the specified resource name has an entry in the rendering cache, use the rendered version from the cache. If not, render the specified widget and update the cache with the result.

To ensure that mouse events are emitted correctly for cached widgets, in addition to the rendered widget, we also cache (the names of) any clickable extents that were rendered and restore that when utilizing the cache.

See also invalidateCacheEntry.

When rendering the specified widget, also register a cursor positioning request using the specified name and location.

Crop the specified widget to the specified size from the bottom. Defers to the cropped widget for growth policy.

Crop the specified widget on the bottom by the specified number of rows. Defers to the cropped widget for growth policy.

Crop the specified widget to the specified size from the top. Defers to the cropped widget for growth policy.

Crop the specified widget on the top by the specified number of rows. Defers to the cropped widget for growth policy.

Crop the specified widget to the specified size from the right. Defers to the cropped widget for growth policy.

Crop the specified widget on the right by the specified number of columns. Defers to the cropped widget for growth policy.

Crop the specified widget to the specified size from the left. Defers to the cropped widget for growth policy.

Crop the specified widget on the left by the specified number of columns. Defers to the cropped widget for growth policy.

Translate the specified widget by the specified offset amount. Defers to the translated widget for growth policy.

Build a widget directly from a raw Vty image.

Override the lookup of targetName to return the attribute value associated with fromName when rendering the specified widget. See also mapAttrName.

When rendering the specified widget, force all attribute lookups in the attribute map to use the value currently assigned to the specified attribute name. This means that the attribute lookups will behave as if they all used the name specified here. That further means that the resolved attribute will still inherit from its parent entry in the attribute map as would normally be the case. If you want to have more control over the resulting attribute, consider modifyDefAttr.

When rendering the specified widget, update the attribute map with the specified transformation.

Update the attribute map while rendering the specified widget: set its new default attribute to the one that we get by looking up the specified attribute name in the map.

Update the attribute map while rendering the specified widget: set its new default attribute to the one that we get by looking up the specified attribute name in the map and then modifying it with the specified function.

When drawing the specified widget, set the current attribute used for drawing to the one with the specified name. Note that the widget may use further calls to withAttr to override this; if you really want to prevent that, use forceAttr. Attributes used this way still get merged hierarchically and still fall back to the attribute map's default attribute. If you want to change the default attribute, use withDefAttr.

Set the rendering context height and width for this widget. This is useful for relaxing the rendering size constraints on e.g. layer widgets where cropping to the screen size is undesirable.

Limit the space available to the specified widget to the specified percentage of available height, as a value between 0 and 100 inclusive. Values outside the valid range will be clamped to the range endpoints. This is important for constraining the vertical growth of otherwise-greedy widgets. This is non-greedy vertically and defers to the limited widget horizontally.

Limit the space available to the specified widget to the specified number of rows. This is important for constraining the vertical growth of otherwise-greedy widgets. This is non-greedy vertically and defers to the limited widget horizontally.

Limit the space available to the specified widget to the specified percentage of available width, as a value between 0 and 100 inclusive. Values outside the valid range will be clamped to the range endpoints. This is important for constraining the horizontal growth of otherwise-greedy widgets. This is non-greedy horizontally and defers to the limited widget vertically.

Limit the space available to the specified widget to the specified number of columns. This is important for constraining the horizontal growth of otherwise-greedy widgets. This is non-greedy horizontally and defers to the limited widget vertically.

Horizontal box layout: put the specified widgets next to each other in the specified order (leftmost first). Defers growth policies to the growth policies of the contained widgets (if any are greedy, so is the box).

Vertical box layout: put the specified widgets one above the other in the specified order (uppermost first). Defers growth policies to the growth policies of the contained widgets (if any are greedy, so is the box).

Fill all available space with the specified character. Grows both horizontally and vertically.

Pad a widget on all sides. Defers to the padded widget for growth policy.

Pad a widget on the top and bottom. Defers to the padded widget for growth policy.

Pad a widget on the left and right. Defers to the padded widget for growth policy.

Pad the specified widget on the bottom. If max padding is used, this grows greedily vertically; otherwise it defers to the padded widget.

Pad the specified widget on the top. If max padding is used, this grows greedily vertically; otherwise it defers to the padded widget.

Pad the specified widget on the right. If max padding is used, this grows greedily horizontally; otherwise it defers to the padded widget.

Pad the specified widget on the left. If max padding is used, this grows greedily horizontally; otherwise it defers to the padded widget.

Hyperlink the given widget to the specified URL. Not all terminal emulators support this. In those that don't, this should have no discernible effect.

Build a widget from a Text value. Behaves the same as str when the input contains multiple lines.

The input string must not contain tab characters. If it does, interface corruption will result since the terminal will likely render it as taking up more than a single column. The caller should replace tabs with the appropriate number of spaces as desired. The input text should not contain escape sequences or carriage returns.

Build a widget from a String. Breaks newlines up and space-pads short lines out to the length of the longest line.

The input string must not contain tab characters. If it does, interface corruption will result since the terminal will likely render it as taking up more than a single column. The caller should replace tabs with the appropriate number of spaces as desired. The input string should not contain escape sequences or carriage returns.

Make a widget from text, but wrap the words in the input's lines at the available width using the specified wrapping settings. The input text should not contain escape sequences or carriage returns.

Unlike txt, this is greedy horizontally.

Make a widget from text, but wrap the words in the input's lines at the available width using the default wrapping settings. The input text should not contain escape sequences or carriage returns.

Unlike txt, this is greedy horizontally.

Make a widget from a string, but wrap the words in the input's lines at the available width using the specified wrapping settings. The input string should not contain escape sequences or carriage returns.

Unlike str, this is greedy horizontally.

Make a widget from a string, but wrap the words in the input's lines at the available width using the default wrapping settings. The input string should not contain escape sequences or carriage returns.

Unlike str, this is greedy horizontally.

Request mouse click events on the specified widget.

Render the specified widget and record its rendering extent using the specified name (see also lookupExtent).

Add an offset to all cursor locations, visbility requests, and extents in the specified rendering result. This function is critical for maintaining correctness in the rendering results as they are processed successively by box layouts and other wrapping combinators, since calls to this function result in converting from widget-local coordinates to (ultimately) terminal-global ones so they can be used by other combinators. You should call this any time you render something and then translate it or otherwise offset it from its original origin.

The empty widget.

After the specified widget has been rendered, freeze its borders. A frozen border will not be affected by neighbors, nor will it affect neighbors. Compared to separateBorders, freezeBorders will not affect whether borders connect internally to a widget (whereas separateBorders prevents them from connecting).

Frozen borders cannot be thawed.

When rendering the specified widget, use static borders. This may be marginally faster, but will introduce a small gap between neighboring orthogonal borders.

This is the default for backwards compatibility.

When rendering the specified widget, create borders that respond dynamically to their neighbors to form seamless connections.

When rendering the specified widget, use the specified border style for any border rendering.

The class of text types that have widths measured in terminal columns. NEVER use length etc. to measure the length of a string if you need to compute how much screen space it will occupy; always use textWidth.

The class of types that store interface element names.

After rendering the specified widget, crop its result image to the dimensions in the rendering context.

Given an attribute name, obtain the attribute for the attribute name by consulting the context's attribute map.

The rendering context's current drawing attribute.

Get the current rendering context.

A convenience function for handling events intended for values that are targets of lenses in your application state. This function obtains the target value of the specified lens, invokes handleEvent on it, and stores the resulting transformed value back in the state using the lens.

The type of padding.

The monad in which event handlers run. Although it may be tempting to dig into the reader value yourself, just use lookupViewport.

Widget size policies. These policies communicate how a widget uses space when being rendered. These policies influence rendering order and space allocation in the box layout algorithm for hBox and vBox.

The type of widgets.

The type of the rendering monad. This monad is used by the library's rendering routines to manage rendering state and communicate rendering parameters to widgets' rendering functions.

Add a Location offset to the specified CursorLocation.

Create an attribute from the specified background color (the background color is the "default").

Create an attribute from the specified foreground color (the background color is the "default").

Build an attribute from a foreground color and a background color. Intended to be used infix.

Given a minimum value and a maximum value, clamp a value to that range (values less than the minimum map to the minimum and values greater than the maximum map to the maximum).

>>> clamp 1 10 11
10
>>> clamp 1 10 2
2
>>> clamp 5 10 1
5

The type of events.

The rendering context. This tells widgets how to render: how much space they have in which to render, which attribute they should use to render, which bordering style should be used, and the attribute map available for rendering.

The type of result returned by a widget's rendering function. The result provides the image, cursor positions, and visibility requests that resulted from the rendering process.

Information about how to redraw a dynamic border character when it abuts another dynamic border character.

Describes the state of a viewport as it appears as its most recent rendering.

The type of viewports that indicates the direction(s) in which a viewport is scrollable.

An extent of a named area: its size, location, and origin.

The type of actions to take upon completion of an event handler.

Scrolling direction.

The class of types that behave like terminal locations.

A cursor location. These are returned by the rendering process.

A border character has four segments, one extending in each direction (horizontally and vertically) from the center of the character.

A unicode border style with rounded corners.

A unicode border style in a bold typeface.

A unicode border style with real corner and intersection characters.

An ASCII border style which will work in any terminal.