Safe Haskell | None |
---|---|
Language | Haskell2010 |
This module provides the core widget combinators and rendering routines. Everything this library does is in terms of these basic primitives.
- data Widget = Widget {}
- data Size
- emptyWidget :: Widget
- raw :: Image -> Widget
- txt :: Text -> Widget
- str :: String -> Widget
- fill :: Char -> Widget
- data Padding
- padLeft :: Padding -> Widget -> Widget
- padRight :: Padding -> Widget -> Widget
- padTop :: Padding -> Widget -> Widget
- padBottom :: Padding -> Widget -> Widget
- padLeftRight :: Int -> Widget -> Widget
- padTopBottom :: Int -> Widget -> Widget
- padAll :: Int -> Widget -> Widget
- (<=>) :: Widget -> Widget -> Widget
- (<+>) :: Widget -> Widget -> Widget
- hBox :: [Widget] -> Widget
- vBox :: [Widget] -> Widget
- hLimit :: Int -> Widget -> Widget
- vLimit :: Int -> Widget -> Widget
- withDefAttr :: AttrName -> Widget -> Widget
- withAttr :: AttrName -> Widget -> Widget
- forceAttr :: AttrName -> Widget -> Widget
- updateAttrMap :: (AttrMap -> AttrMap) -> Widget -> Widget
- withBorderStyle :: BorderStyle -> Widget -> Widget
- showCursor :: Name -> Location -> Widget -> Widget
- translateBy :: Location -> Widget -> Widget
- cropLeftBy :: Int -> Widget -> Widget
- cropRightBy :: Int -> Widget -> Widget
- cropTopBy :: Int -> Widget -> Widget
- cropBottomBy :: Int -> Widget -> Widget
- data ViewportType
- = Vertical
- | Horizontal
- | Both
- viewport :: Name -> ViewportType -> Widget -> Widget
- visible :: Widget -> Widget
- visibleRegion :: Location -> DisplayRegion -> Widget -> Widget
- type RenderM a = ReaderT Context (State RenderState) a
- getContext :: RenderM Context
- lookupAttrName :: AttrName -> RenderM Attr
- data Context
- attrL :: (Contravariant f, Functor f) => (Attr -> f Attr) -> Context -> f Context
- availWidthL :: Lens' Context Int
- availHeightL :: Lens' Context Int
- ctxAttrMapL :: Lens' Context AttrMap
- ctxAttrNameL :: Lens' Context AttrName
- ctxBorderStyleL :: Lens' Context BorderStyle
- data Result = Result {
- image :: Image
- cursors :: [CursorLocation]
- visibilityRequests :: [VisibilityRequest]
- imageL :: Lens' Result Image
- cursorsL :: Lens' Result [CursorLocation]
- visibilityRequestsL :: Lens' Result [VisibilityRequest]
- data VisibilityRequest = VR {
- vrPosition :: Location
- vrSize :: DisplayRegion
- vrPositionL :: Lens' VisibilityRequest Location
- vrSizeL :: Lens' VisibilityRequest DisplayRegion
- addResultOffset :: Location -> Result -> Result
- cropToContext :: Widget -> Widget
- data Direction
Documentation
The type of widgets.
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.
Basic rendering primitives
The empty widget.
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 all available space with the specified character. Grows both horizontally and vertically.
Padding
The type of padding.
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.
Box layout
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
.
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.
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. |
:: 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
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
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
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.
Result | |
|
Result lenses
Visibility requests
data VisibilityRequest Source
VR | |
|
vrSizeL :: Lens' VisibilityRequest DisplayRegion Source
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.