Brick.Widgets.Core

This module provides the core widget combinators and rendering routines. Everything this library does is in terms of these basic primitives.

Basic rendering primitives

class TextWidth a where

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.

Methods

textWidth :: a -> Int

Instances

TextWidth Text

Defined in Brick.Widgets.Core

Methods

textWidth :: Text -> Int

Foldable f => TextWidth (f Char)

Defined in Brick.Widgets.Core

Methods

textWidth :: f Char -> Int

emptyWidget :: Widget n

The empty widget.

raw :: Image -> Widget n

Build a widget directly from a raw Vty image.

txt :: Text -> Widget n

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.

txtWrap :: Text -> Widget n

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.

txtWrapWith :: WrapSettings -> Text -> Widget n

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.

str :: String -> Widget n

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.

strWrap :: String -> Widget n

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.

strWrapWith :: WrapSettings -> String -> Widget n

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.

fill :: Char -> Widget n

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

hyperlink :: Text -> Widget n -> Widget n

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.

Padding

padLeft :: Padding -> Widget n -> Widget n

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

padRight :: Padding -> Widget n -> Widget n

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

padTop :: Padding -> Widget n -> Widget n

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

padBottom :: Padding -> Widget n -> Widget n

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

padLeftRight :: Int -> Widget n -> Widget n

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

padTopBottom :: Int -> Widget n -> Widget n

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

padAll :: Int -> Widget n -> Widget n

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

Box layout

(<=>)

Arguments

:: Widget n

Top

-> Widget n

Bottom

-> Widget n

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.

(<+>)

Arguments

:: Widget n

Left

-> Widget n

Right

-> Widget n

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.

hBox :: [Widget n] -> Widget n

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).

vBox :: [Widget n] -> Widget n

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).

Limits

hLimit :: Int -> Widget n -> Widget n

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.

hLimitPercent :: Int -> Widget n -> Widget n

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.

vLimit :: Int -> Widget n -> Widget n

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.

vLimitPercent :: Int -> Widget n -> Widget n

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.

setAvailableSize :: (Int, Int) -> Widget n -> Widget n

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.

Attribute management

withDefAttr :: AttrName -> Widget n -> Widget n

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.

modifyDefAttr :: (Attr -> Attr) -> Widget n -> Widget n

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.

withAttr :: AttrName -> Widget n -> Widget n

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.

forceAttr :: AttrName -> Widget n -> Widget n

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.

overrideAttr :: AttrName -> AttrName -> Widget n -> Widget n

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

updateAttrMap :: (AttrMap -> AttrMap) -> Widget n -> Widget n

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

Border style management

withBorderStyle :: BorderStyle -> Widget n -> Widget n

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

joinBorders :: Widget n -> Widget n

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

separateBorders :: Widget n -> Widget n

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.

freezeBorders :: Widget n -> Widget n

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.

Cursor placement

showCursor :: n -> Location -> Widget n -> Widget n

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

Naming

class Named a n where

The class of types that store interface element names.

Methods

getName :: a -> n

Get the name of the specified value.

Instances

Named (Editor t n) n

Defined in Brick.Widgets.Edit

Methods

getName :: Editor t n -> n

Named (GenericList n t e) n

Defined in Brick.Widgets.List

Methods

getName :: GenericList n t e -> n

Translation

translateBy :: Location -> Widget n -> Widget n

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

Cropping

cropLeftBy :: Int -> Widget n -> Widget n

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

cropRightBy :: Int -> Widget n -> Widget n

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

cropTopBy :: Int -> Widget n -> Widget n

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

cropBottomBy :: Int -> Widget n -> Widget n

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

Extent reporting

reportExtent :: n -> Widget n -> Widget n

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

clickable :: n -> Widget n -> Widget n

Request mouse click events on the specified widget.

Scrollable viewports

viewport

Arguments

:: (Ord n, Show n)

=> n

The name of the viewport (must be unique and stable for reliable behavior)

-> ViewportType

The type of viewport (indicates the permitted scrolling direction)

-> Widget n

The widget to be rendered in the scrollable viewport

-> Widget n

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.

visible :: Widget n -> Widget n

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.

visibleRegion :: Location -> DisplayRegion -> Widget n -> Widget n

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.

unsafeLookupViewport :: Ord n => n -> RenderM n (Maybe 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.

cached :: Ord n => n -> Widget n -> Widget n

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.

Adding offsets to cursor positions and visibility requests

addResultOffset :: Location -> Result n -> Result n

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.

Cropping results

cropToContext :: Widget n -> Widget n

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