This module provides a basic infrastructure for modelling a user
interface widget and converting it to Vty's Image
type.
- data Widget = Widget {
- render :: DisplayRegion -> Render
- growHorizontal :: Bool
- growVertical :: Bool
- primaryAttribute :: Attr
- withAttribute :: Attr -> Widget
- mkImage :: Vty -> Widget -> IO (Image, RenderState)
- type RenderState = Map String Address
- data Render
- renderImg :: Image -> Render
- renderAddr :: String -> Render -> Render
- renderMany :: Orientation -> [Render] -> Render
- renderWidth :: Render -> Word
- renderHeight :: Render -> Word
- data Address
- address :: String -> RenderState -> Maybe Address
- addressable :: String -> Widget -> Widget
- addrSize :: Address -> DisplayRegion
- addrPosition :: Address -> DisplayRegion
- addAddress :: String -> DisplayRegion -> Image -> State RenderState ()
- data Orientation
- = Horizontal
- | Vertical
- withWidth :: DisplayRegion -> Word -> DisplayRegion
- withHeight :: DisplayRegion -> Word -> DisplayRegion
Documentation
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.
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 Address
es of addressable
widgets.
Rendering process
Widget
s are ultimately converted to Vty Image
s, 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
.
:: String | The identifier of the widget that this
|
-> Render | The |
-> 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
.
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
|
-> Widget | The widget whose rendering address ( |
-> 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 |
-> 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
.
Miscellaneous
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
.