brick-0.1: A declarative terminal user interface library

Safe HaskellNone
LanguageHaskell2010

Brick.Widgets.Core

Contents

Description

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

Synopsis

Documentation

data Widget Source

The type of widgets.

Constructors

Widget 

Fields

hSize :: Size

This widget's horizontal growth policy

vSize :: Size

This widget's vertical growth policy

render :: RenderM Result

This widget's rendering function

Instances

data Size Source

Widget growth policies. These policies communicate to layout algorithms how a widget uses space when being rendered. These policies influence rendering order and space allocation in the box layout algorithm.

Constructors

Fixed

Fixed widgets take up the same amount of space no matter how much they are given (non-greedy).

Greedy

Greedy widgets take up all the space they are given.

Instances

Basic rendering primitives

emptyWidget :: Widget Source

The empty widget.

raw :: Image -> Widget Source

Build a widget directly from a raw Vty image.

txt :: Text -> Widget Source

Build a widget from a Text value. Behaves the same as str.

str :: String -> Widget Source

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

fill :: Char -> Widget Source

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

Padding

data Padding Source

The type of padding.

Constructors

Pad Int

Pad by the specified number of rows or columns.

Max

Pad up to the number of available rows or columns.

padLeft :: Padding -> Widget -> Widget Source

Pad the specified widget on the left.

padRight :: Padding -> Widget -> Widget Source

Pad the specified widget on the right.

padTop :: Padding -> Widget -> Widget Source

Pad the specified widget on the top.

padBottom :: Padding -> Widget -> Widget Source

Pad the specified widget on the bottom.

padLeftRight :: Int -> Widget -> Widget Source

Pad a widget on the left and right.

padTopBottom :: Int -> Widget -> Widget Source

Pad a widget on the top and bottom.

padAll :: Int -> Widget -> Widget Source

Pad a widget on all sides.

Box layout

(<=>) Source

Arguments

:: Widget

Top

-> Widget

Bottom

-> Widget 

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.

(<+>) Source

Arguments

:: Widget

Left

-> Widget

Right

-> Widget 

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] -> Widget Source

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 both widgets.

vBox :: [Widget] -> Widget Source

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 both widgets.

Limits

hLimit :: Int -> Widget -> Widget Source

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.

vLimit :: Int -> Widget -> Widget Source

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.

Attribute mangement

withDefAttr :: AttrName -> Widget -> Widget Source

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.

withAttr :: AttrName -> Widget -> Widget Source

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 -> Widget Source

When rendering the specified widget, force all attribute lookups in the attribute map to use the value currently assigned to the specified attribute name.

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

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

Border style management

withBorderStyle :: BorderStyle -> Widget -> Widget Source

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

Cursor placement

showCursor :: Name -> Location -> Widget -> Widget Source

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

Translation

translateBy :: Location -> Widget -> Widget Source

Translate the specified widget by the specified offset amount.

Cropping

cropLeftBy :: Int -> Widget -> Widget Source

Crop the specified widget on the left by the specified number of columns.

cropRightBy :: Int -> Widget -> Widget Source

Crop the specified widget on the right by the specified number of columns.

cropTopBy :: Int -> Widget -> Widget Source

Crop the specified widget on the top by the specified number of rows.

cropBottomBy :: Int -> Widget -> Widget Source

Crop the specified widget on the bottom by the specified number of rows.

Scrollable viewports

data ViewportType Source

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

Constructors

Vertical

Viewports of this type are scrollable only vertically.

Horizontal

Viewports of this type are scrollable only horizontally.

Both

Viewports of this type are scrollable vertically and horizontally.

Instances

viewport Source

Arguments

:: Name

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

-> ViewportType

The type of viewport (indicates the permitted scrolling direction)

-> Widget

The widget to be rendered in the scrollable viewport

-> Widget 

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, only the first is honored. If a viewport receives more than one scrolling request from EventM, all are honored in the order in which they are received.

visible :: Widget -> Widget Source

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 -> Widget Source

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.

Rendering infrastructure

type RenderM a = ReaderT Context (State RenderState) a Source

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.

getContext :: RenderM Context Source

Get the current rendering context.

lookupAttrName :: AttrName -> RenderM Attr Source

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

The rendering context

data Context Source

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 bordring style should be used, and the attribute map available for rendering.

attrL :: (Contravariant f, Functor f) => (Attr -> f Attr) -> Context -> f Context Source

The rendering context's current drawing attribute.

Rendering results

data Result Source

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.

Constructors

Result 

Fields

image :: Image

The final rendered image for a widget

cursors :: [CursorLocation]

The list of reported cursor positions for the application to choose from

visibilityRequests :: [VisibilityRequest]

The list of visibility requests made by widgets rendered while rendering this one (used by viewports)

Result lenses

Visibility requests

data VisibilityRequest Source

Constructors

VR 

Fields

vrPosition :: Location
 
vrSize :: DisplayRegion
 

Adding offsets to cursor positions and visibility requests

addResultOffset :: Location -> Result -> Result Source

Add an offset to all cursor locations and visbility requests 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 -> Widget Source

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

Misc

data Direction Source

Scrolling direction.

Constructors

Up

Up/left

Down

Down/right