vty-ui-1.3.1: An interactive terminal user interface library for Vty




This module provides functionality for rendering Strings as Widgets, including functionality to make structural and/or visual changes at rendering time. To get started, turn your ordinary String into a Widget with plainText; for more control, use textWidget.



data FormattedText Source

The type of formatted text widget state. Stores the text itself and the formatter used to apply attributes to the text.


Constructing Text Widgets

plainText :: String -> IO (Widget FormattedText)Source

Construct a Widget directly from a String. This is recommended if you don't need to use a Formatter.

plainTextWithAttrs :: [(String, Attr)] -> IO (Widget FormattedText)Source

Construct a Widget directly from a list of strings and their attributes.

textWidget :: Formatter -> String -> IO (Widget FormattedText)Source

Construct a text widget formatted with the specified formatters and initial content. The formatters will be applied in the order given here (and, depending on the formatter, order might matter).

Setting Widget Contents

setText :: Widget FormattedText -> String -> IO ()Source

Set the text value of a FormattedText widget. The specified string will be tokenized.

setTextWithAttrs :: Widget FormattedText -> [(String, Attr)] -> IO ()Source

Set the text value of a FormattedText widget directly, in case you have done formatting elsewhere and already have text with attributes. The specified strings will each be tokenized, and tokens resulting from each tokenize operation will be given the specified attribute in the tuple.

setTextFormatter :: Widget FormattedText -> Formatter -> IO ()Source

Set the formatter for the text.

setTextAppearFocused :: Widget FormattedText -> Bool -> IO ()Source

Set whether a text widget can appear focused by using the context-specific focus attribute when the widget has the focus. This setting defaults to False; some widgets which embed text widgets may need to turn this on.


type Formatter = DisplayRegion -> TextStream Attr -> IO (TextStream Attr)Source

A formatter makes changes to text at rendering time. Some formatting use cases involve knowing the size of the rendering area, which is not known until render time (e.g., text wrapping). Thus, a formatter takes a DisplayRegion which indicates the size of screen area available for formatting.

getTextFormatter :: Widget FormattedText -> IO FormatterSource

Get the formatter for the text.

(&.&) :: Formatter -> Formatter -> FormatterSource

Formatter composition: a &.& b applies a followed by b.

highlight :: RegexLike r String => r -> Attr -> FormatterSource

A highlight formatter takes a regular expression used to scan the text and an attribute to assign to matches. The regular expression is only applied to individual string tokens (individual words, whitespace strings, etc.); it is NOT applied to whole lines, paragraphs, or text spanning multiple lines. If you have need of that kind of functionality, apply your own attributes with your own regular expression prior to calling setTextWithAttrs.

nullFormatter :: FormatterSource

The null formatter which has no effect on text streams.

wrap :: FormatterSource

A formatter for wrapping text into the available space. This formatter will insert line breaks where appropriate so if you want to use other structure-sensitive formatters, run this formatter last.