vty-ui-0.4: A user interface composition library for Vty




This module provides a basic infrastructure for modelling a user interface widget and converting it to Vty's Image type.



data Widget Source

The type of user interface widgets. A Widget provides several properties:

  • Growth properties which provide information about how to allocate space to widgets depending on their propensity to consume available space
  • A primary attribute which is the attribute most easily identifiable with the widget's visual presentation
  • An attribute override which allows the widget and its children to be rendered using a single attribute specified by the caller
  • A rendering routine which converts the widget's internal state into a Render value.

Of primary concern is the rendering routine, render. The rendering routine takes one parameter: the size of the space in which the widget should be rendered. The space is important because it provides a maximum size for the widget. For widgets that consume all available space, the size of the resulting Render will be equal to the supplied size. For smaller widgets (e.g., a simple string of text), the size of the Render will likely be much smaller than the supplied size. In any case, any Widget implementation must obey the rule that the resulting Render must not exceed the supplied DisplayRegion in size. If it does, there's a good chance your interface will be garbled.

If the widget has child widgets, the supplied size should be subdivided to fit the child widgets as appropriate. How the space is subdivided may depend on the growth properties of the children or it may be a matter of policy.




render :: DisplayRegion -> Render

Render the widget with the given dimensions. The result must not be larger than the specified dimensions, but may be smaller.

growHorizontal :: Bool

Will this widget expand to take advantage of available horizontal space?

growVertical :: Bool

Will this widget expand to take advantage of available vertical space?

primaryAttribute :: Attr

The primary attribute of this widget, used when composing widgets. For example, if you want to compose a widget A with a space-filling widget B, you probably want B's text attributes to be identical to those of A.

withAttribute :: Attr -> Widget

Apply the specified attribute to this widget.

mkImage :: Vty -> Widget -> IO (Image, RenderState)Source

Given a Widget and a Vty object, render the widget using the current size of the terminal controlled by Vty. Returns the rendered Widget as an Image along with the RenderState containing the Addresses of addressable widgets.

Rendering process

Widgets are ultimately converted to Vty Images, but this library uses an intermediate type, Render, to represent the physical layout of the images. A Render represents the various primitive rendering constructs which support vertical and horizontal concatenation and Image addressing. Once a Widget has been rendered (see render), the resulting Render is then put through a positioning pass in which the sizes and positions of any addressable image regions are stored (see RenderState). The result is a single Image suitable for use with Vty's Graphics.Vty.pic_for_image function.

type RenderState = Map String AddressSource

The collection of widget names (see addressable) and their rendering addresses as a result of render.

data Render Source

An intermediate type used in the rendering process. Widgets are converted into collections of Images and represented with this type, using a few primitive rendering instructions to determine how the rendered images are combined to form a complete terminal window image. See render.

renderImg :: Image -> RenderSource

Create a Render containing a single Image.



:: String

The identifier of the widget that this Render represents. Should be the same identifier that was passed to addressable.

-> Render

The Render to identify.

-> Render 

Create a Render representing a render together with an identifier. This type of Render is used with addressable to locate a widget's position and dimensions in the final Image.

renderMany :: Orientation -> [Render] -> RenderSource

Create a Render representing a collection of renders which should be combined in the specified Orientation.

renderWidth :: Render -> WordSource

Compute the width, in columns, of a Render.

renderHeight :: Render -> WordSource

Compute the height, in rows, of a Render.

Widget addressing

Some widgets, such as editable widgets, require that their on-screen representations be known after rendering; this library supports a notion of widget addressing in which a Widget is marked as addressable (see addressable). Addressable widgets' position and size information (Address) will be recorded in the RenderState during rendering in mkImage.

data Address Source

Information about the rendered state of a widget.


address :: String -> RenderState -> Maybe AddressSource

Retrieve the rendering address for a given widget. To annotate a widget to induce storage of its address, use addressable.



:: String

The identifier of the widget to be used in the RenderState.

-> Widget

The widget whose rendering address (Address) should be stored.

-> Widget 

Annotate a widget with a rendering identifier so that its rendering address will be stored by the rendering process. Once the widget has been rendered, its address will be found in the resulting RenderState. To retrieve the address of such an identifier, use address.

addrSize :: Address -> DisplayRegionSource

The rendered size of a widget.

addrPosition :: Address -> DisplayRegionSource

The rendered position of a widget.



:: String

The Address identifier.

-> DisplayRegion

The position of the image.

-> Image

The image whose size should be stored.

-> State RenderState () 

Add an address for the specified identifier, position, and Image to the RenderState.


data Orientation Source

A simple orientation type.



withWidth :: DisplayRegion -> Word -> DisplayRegionSource

Modify the width component of a DisplayRegion.

withHeight :: DisplayRegion -> Word -> DisplayRegionSource

Modify the height component of a DisplayRegion.