-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A declarative terminal user interface library
--
-- Write terminal applications painlessly with brick! You write an
-- event handler and a drawing function and the library does the rest.
--
--
-- module Main where
--
-- import Brick
--
-- ui :: Widget ()
-- ui = str "Hello, world!"
--
-- main :: IO ()
-- main = simpleMain ui
--
--
-- To get started, see:
--
--
--
-- This package deprecates vty-ui.
@package brick
@version 0.39
-- | This module provides types and functions for managing an attribute map
-- which maps attribute names (AttrName) to attributes
-- (Attr). This module is designed to be used with the
-- OverloadedStrings language extension to permit easy
-- construction of AttrName values and you should also use
-- mappend (<>) to combine names.
--
-- Attribute maps work by mapping hierarchical attribute names to
-- attributes and inheriting parent names' attributes when child names
-- specify partial attributes. Hierarchical names are created with
-- mappend:
--
--
-- let n = attrName "parent" <> attrName "child"
--
--
-- Attribute names are mapped to attributes, but some attributes may be
-- partial (specify only a foreground or background color). When
-- attribute name lookups occur, the attribute corresponding to a more
-- specific name ('parent <> child' as above) is sucessively merged
-- with the parent attribute (parent as above) all the way to
-- the "root" of the attribute map, the map's default attribute. In this
-- way, more specific attributes inherit what they don't specify from
-- more general attributes in the same hierarchy. This allows more
-- modularity and less repetition in specifying how elements of your user
-- interface take on different attributes.
module Brick.AttrMap
-- | An attribute map which maps AttrName values to Attr
-- values.
data AttrMap
-- | An attribute name. Attribute names are hierarchical; use
-- mappend (<>) to assemble them. Hierarchy in an
-- attribute name is used to represent increasing levels of specificity
-- in referring to the attribute you want to use for a visual element,
-- with names to the left being general and names to the right being more
-- specific. For example:
--
--
-- "window" <> "border"
-- "window" <> "title"
-- "header" <> "clock" <> "seconds"
--
data AttrName
-- | Create an attribute map.
attrMap :: Attr -> [(AttrName, Attr)] -> AttrMap
-- | Create an attribute map in which all lookups map to the same
-- attribute.
forceAttrMap :: Attr -> AttrMap
-- | Create an attribute name from a string.
attrName :: String -> AttrName
-- | Get the components of an attribute name.
attrNameComponents :: AttrName -> [String]
-- | Look up the specified attribute name in the map. Map lookups proceed
-- as follows. If the attribute map is forcing all lookups to a specific
-- attribute, that attribute is returned. If the attribute name is empty,
-- the map's default attribute is returned. If the attribute name is
-- non-empty, very subsequence of names from the specified name are used
-- to perform a lookup, and the results are combined as in
-- mergeWithDefault, with more specific results taking precedence
-- over less specific ones.
--
-- For example:
--
--
-- attrMapLookup ("foo" <> "bar") (attrMap a []) == a
-- attrMapLookup ("foo" <> "bar") (attrMap (bg blue) [("foo" <> "bar", fg red)]) == red `on` blue
-- attrMapLookup ("foo" <> "bar") (attrMap (bg blue) [("foo" <> "bar", red on cyan)]) == red `on` cyan
-- attrMapLookup ("foo" <> "bar") (attrMap (bg blue) [("foo" <> "bar", fg red), ("foo", bg cyan)]) == red `on` cyan
-- attrMapLookup ("foo" <> "bar") (attrMap (bg blue) [("foo", fg red)]) == red `on` blue
--
attrMapLookup :: AttrName -> AttrMap -> Attr
-- | Set the default attribute value in an attribute map.
setDefaultAttr :: Attr -> AttrMap -> AttrMap
-- | Get the default attribute value in an attribute map.
getDefaultAttr :: AttrMap -> Attr
-- | Insert a set of attribute mappings to an attribute map.
applyAttrMappings :: [(AttrName, Attr)] -> AttrMap -> AttrMap
-- | Given an attribute and a map, merge the attribute with the map's
-- default attribute. If the map is forcing all lookups to a specific
-- attribute, the forced attribute is returned without merging it with
-- the one specified here. Otherwise the attribute given here is merged
-- with the attribute map's default attribute in that any aspect of the
-- specified attribute that is not provided falls back to the map
-- default. For example,
--
--
-- mergeWithDefault (fg blue) $ attrMap (bg red) []
--
--
-- returns
--
--
-- blue `on` red
--
mergeWithDefault :: Attr -> AttrMap -> Attr
-- | Update an attribute map such that a lookup of ontoName
-- returns the attribute value specified by fromName. This is
-- useful for composite widgets with specific attribute names mapping
-- those names to the sub-widget's expected name when calling that
-- sub-widget's rendering function. See the ProgressBarDemo for an
-- example usage, and overrideAttr for an alternate syntax.
mapAttrName :: AttrName -> AttrName -> AttrMap -> AttrMap
-- | Map several attributes to return the value associated with an
-- alternate name. Applies mapAttrName across a list of mappings.
mapAttrNames :: [(AttrName, AttrName)] -> AttrMap -> AttrMap
instance GHC.Show.Show Brick.AttrMap.AttrMap
instance GHC.Classes.Ord Brick.AttrMap.AttrName
instance GHC.Classes.Eq Brick.AttrMap.AttrName
instance GHC.Read.Read Brick.AttrMap.AttrName
instance GHC.Show.Show Brick.AttrMap.AttrName
instance GHC.Base.Semigroup Brick.AttrMap.AttrName
instance GHC.Base.Monoid Brick.AttrMap.AttrName
instance Data.String.IsString Brick.AttrMap.AttrName
module Brick.BChan
-- | BChan is an abstract type representing a bounded FIFO
-- channel.
data BChan a
-- | Builds and returns a new instance of BChan.
newBChan :: Int -> IO (BChan a)
-- | Writes a value to a BChan; blocks if the channel is full.
writeBChan :: BChan a -> a -> IO ()
-- | Reads the next value from the BChan; blocks if necessary.
readBChan :: BChan a -> IO a
-- | Reads the next value from either BChan, prioritizing the
-- first BChan; blocks if necessary.
readBChan2 :: BChan a -> BChan b -> IO (Either a b)
-- | Support for representing attribute themes and loading and saving theme
-- customizations in INI-style files.
--
-- The file format is as follows:
--
-- Customization files are INI-style files with two sections, both
-- optional: "default" and "other".
--
-- The "default" section specifies three optional fields:
--
--
-- - "default.fg" - a color specification
-- - "default.bg" - a color specification
-- - "default.style" - a style specification
--
--
-- A color specification can be any of the strings black,
-- red, green, yellow, blue,
-- magenta, cyan, white, brightBlack,
-- brightRed, brightGreen, brightYellow,
-- brightBlue, brightMagenta, brightCyan,
-- brightWhite, or default.
--
-- We also support color specifications in the common hex format
-- #RRGGBB, but note that this specification is lossy: terminals
-- can only display 256 colors, but hex codes can specify 256^3 =
-- 16777216 colors.
--
-- A style specification can be either one of the following values
-- (without quotes) or a comma-delimited list of one or more of the
-- following values (e.g. "[bold,underline]") indicating that
-- all of the specified styles be used. Valid styles are
-- standout, underline, reverseVideo,
-- blink, dim, italic, and bold.
--
-- The other section specifies for each attribute name in the
-- theme the same fg, bg, and style settings
-- as for the default attribute. Furthermore, if an attribute name has
-- multiple components, the fields in the INI file should use periods as
-- delimiters. For example, if a theme has an attribute name ("foo"
-- <> "bar"), then the file may specify three fields:
--
--
-- - foo.bar.fg - a color specification
-- - foo.bar.bg - a color specification
-- - foo.bar.style - a style specification
--
--
-- Any color or style specifications omitted from the file mean that
-- those attribute or style settings will use the theme's default value
-- instead.
--
-- Attribute names with multiple components (e.g. attr1 <>
-- attr2) can be referenced in customization files by separating the
-- names with a dot. For example, the attribute name "list" <>
-- "selected" can be referenced by using the string "list.selected".
module Brick.Themes
-- | An attribute customization can specify which aspects of an attribute
-- to customize.
data CustomAttr
CustomAttr :: Maybe (MaybeDefault Color) -> Maybe (MaybeDefault Color) -> Maybe Style -> CustomAttr
-- | The customized foreground, if any.
[customFg] :: CustomAttr -> Maybe (MaybeDefault Color)
-- | The customized background, if any.
[customBg] :: CustomAttr -> Maybe (MaybeDefault Color)
-- | The customized style, if any.
[customStyle] :: CustomAttr -> Maybe Style
customFgL :: Lens' CustomAttr (Maybe (MaybeDefault Color))
customBgL :: Lens' CustomAttr (Maybe (MaybeDefault Color))
customStyleL :: Lens' CustomAttr (Maybe Style)
-- | A theme provides a set of default attribute mappings, a default
-- attribute, and a set of customizations for the default mapping and
-- default attribute. The idea here is that the application will always
-- need to provide a complete specification of its attribute mapping, but
-- if the user wants to customize any aspect of that default mapping, it
-- can be contained here and then built into an AttrMap (see
-- themeToAttrMap). We keep the defaults separate from
-- customizations to permit users to serialize themes and their
-- customizations to, say, disk files.
data Theme
Theme :: Attr -> Map AttrName Attr -> Maybe CustomAttr -> Map AttrName CustomAttr -> Theme
-- | The default attribute to use.
[themeDefaultAttr] :: Theme -> Attr
-- | The default attribute mapping to use.
[themeDefaultMapping] :: Theme -> Map AttrName Attr
-- | Customization for the theme's default attribute.
[themeCustomDefaultAttr] :: Theme -> Maybe CustomAttr
-- | Customizations for individual entries of the default mapping. Note
-- that this will only affect entries in the default mapping; any
-- attributes named here that are not present in the default mapping will
-- not be considered.
[themeCustomMapping] :: Theme -> Map AttrName CustomAttr
-- | Create a new theme with the specified default attribute and attribute
-- mapping. The theme will have no customizations.
newTheme :: Attr -> [(AttrName, Attr)] -> Theme
themeDefaultAttrL :: Lens' Theme Attr
themeDefaultMappingL :: Lens' Theme (Map AttrName Attr)
themeCustomMappingL :: Lens' Theme (Map AttrName CustomAttr)
themeCustomDefaultAttrL :: Lens' Theme (Maybe CustomAttr)
-- | Documentation for a theme's attributes.
data ThemeDocumentation
ThemeDocumentation :: Map AttrName Text -> ThemeDocumentation
-- | The per-attribute documentation for a theme so e.g. documentation for
-- theme customization can be generated mechanically.
[themeDescriptions] :: ThemeDocumentation -> Map AttrName Text
themeDescriptionsL :: Lens' ThemeDocumentation (Map AttrName Text)
-- | Build an AttrMap from a Theme. This applies all
-- customizations in the returned AttrMap.
themeToAttrMap :: Theme -> AttrMap
-- | Apply customizations using a custom lookup function. Customizations
-- are obtained for each attribute name in the theme. Any customizations
-- already set are lost.
applyCustomizations :: Maybe CustomAttr -> (AttrName -> Maybe CustomAttr) -> Theme -> Theme
-- | Load an INI file containing theme customizations. Use the specified
-- theme to determine which customizations to load. Return the specified
-- theme with customizations set. See the module documentation for the
-- theme file format.
loadCustomizations :: FilePath -> Theme -> IO (Either String Theme)
-- | Save an INI file containing theme customizations. Use the specified
-- theme to determine which customizations to save. See the module
-- documentation for the theme file format.
saveCustomizations :: FilePath -> Theme -> IO ()
-- | Save an INI file containing all attributes from the specified theme.
-- Customized attributes are saved, but if an attribute is not
-- customized, its default is saved instead. The file can later be
-- re-loaded as a customization file.
saveTheme :: FilePath -> Theme -> IO ()
instance GHC.Generics.Generic Brick.Themes.Theme
instance GHC.Show.Show Brick.Themes.Theme
instance GHC.Read.Read Brick.Themes.Theme
instance GHC.Classes.Eq Brick.Themes.Theme
instance GHC.Generics.Generic Brick.Themes.ThemeDocumentation
instance GHC.Show.Show Brick.Themes.ThemeDocumentation
instance GHC.Read.Read Brick.Themes.ThemeDocumentation
instance GHC.Classes.Eq Brick.Themes.ThemeDocumentation
instance GHC.Generics.Generic Brick.Themes.CustomAttr
instance GHC.Show.Show Brick.Themes.CustomAttr
instance GHC.Read.Read Brick.Themes.CustomAttr
instance GHC.Classes.Eq Brick.Themes.CustomAttr
instance GHC.Base.Semigroup Brick.Themes.CustomAttr
instance GHC.Base.Monoid Brick.Themes.CustomAttr
-- | This module provides styles for borders as used in terminal
-- applications. Your mileage may vary on some of the fancier styles due
-- to varying support for some border characters in the fonts your users
-- may be using. Because of this, we provide the ascii style in
-- addition to the Unicode styles. The unicode style is also a
-- safe bet.
--
-- To use these in your widgets, see withBorderStyle. By default,
-- widgets rendered without a specified border style use unicode
-- via the Default instance provided by BorderStyle.
module Brick.Widgets.Border.Style
-- | A border style for use in any widget that needs to render borders in a
-- consistent style.
data BorderStyle
BorderStyle :: Char -> Char -> Char -> Char -> Char -> Char -> Char -> Char -> Char -> Char -> Char -> BorderStyle
-- | Top-left corner character
[bsCornerTL] :: BorderStyle -> Char
-- | Top-right corner character
[bsCornerTR] :: BorderStyle -> Char
-- | Bottom-right corner character
[bsCornerBR] :: BorderStyle -> Char
-- | Bottom-left corner character
[bsCornerBL] :: BorderStyle -> Char
-- | Full intersection (cross)
[bsIntersectFull] :: BorderStyle -> Char
-- | Left side of a horizontal border intersecting a vertical one
[bsIntersectL] :: BorderStyle -> Char
-- | Right side of a horizontal border intersecting a vertical one
[bsIntersectR] :: BorderStyle -> Char
-- | Top of a vertical border intersecting a horizontal one
[bsIntersectT] :: BorderStyle -> Char
-- | Bottom of a vertical border intersecting a horizontal one
[bsIntersectB] :: BorderStyle -> Char
-- | Horizontal border character
[bsHorizontal] :: BorderStyle -> Char
-- | Vertical border character
[bsVertical] :: BorderStyle -> Char
-- | Make a border style using the specified character everywhere.
borderStyleFromChar :: Char -> BorderStyle
-- | An ASCII border style which will work in any terminal.
ascii :: BorderStyle
-- | A unicode border style with real corner and intersection characters.
unicode :: BorderStyle
-- | A unicode border style in a bold typeface.
unicodeBold :: BorderStyle
-- | A unicode border style with rounded corners.
unicodeRounded :: BorderStyle
defaultBorderStyle :: BorderStyle
instance GHC.Classes.Eq Brick.Widgets.Border.Style.BorderStyle
instance GHC.Read.Read Brick.Widgets.Border.Style.BorderStyle
instance GHC.Show.Show Brick.Widgets.Border.Style.BorderStyle
module Data.IMap
-- | Semantically, IMap and IntMap are identical; but
-- IMap is more efficient when large sequences of contiguous keys
-- are mapped to the same value.
data IMap a
-- | Run n a represents n copies of the value a.
data Run a
Run :: !Int -> !a -> Run a
[len] :: Run a -> !Int
[val] :: Run a -> !a
empty :: IMap a
null :: IMap a -> Bool
singleton :: Int -> Run a -> IMap a
insert :: Int -> Run a -> IMap a -> IMap a
delete :: Int -> Run ignored -> IMap a -> IMap a
-- | Given a range of keys (as specified by a starting key and a length for
-- consistency with other functions in this module), restrict the map to
-- keys in that range. restrict k r m is equivalent to
-- intersectionWith const m (insert k r empty) but potentially
-- more efficient.
restrict :: Int -> Run ignored -> IMap a -> IMap a
lookup :: Int -> IMap a -> Maybe a
-- | splitLE n m produces a tuple (le, gt) where
-- le has all the associations of m where the keys are
-- <= n and gt has all the associations of
-- m where the keys are > n.
splitLE :: Int -> IMap a -> (IMap a, IMap a)
intersectionWith :: (a -> b -> c) -> IMap a -> IMap b -> IMap c
mapMaybe :: (a -> Maybe b) -> IMap a -> IMap b
-- | Increment all keys by the given amount. This is like
-- mapKeysMonotonic, but restricted to partially-applied addition.
addToKeys :: Int -> IMap a -> IMap a
-- | This function is unsafe because it assumes there is no overlap between
-- its arguments. That is, in the call unsafeUnion a b, the
-- caller must guarantee that if lookup k a = Just v then
-- lookup k b = Nothing and vice versa.
unsafeUnion :: IMap a -> IMap a -> IMap a
fromList :: [(Int, Run a)] -> IMap a
-- | This function is unsafe because IMaps that compare equal may
-- split their runs into different chunks; consumers must promise that
-- they do not treat run boundaries specially.
unsafeRuns :: IMap a -> IntMap (Run a)
-- | This function is unsafe because IMaps that compare equal may
-- split their runs into different chunks; consumers must promise that
-- they do not treat run boundaries specially.
unsafeToAscList :: IMap a -> [(Int, Run a)]
instance GHC.Base.Functor Data.IMap.IMap
instance GHC.Show.Show a => GHC.Show.Show (Data.IMap.IMap a)
instance GHC.Base.Functor Data.IMap.Run
instance GHC.Show.Show a => GHC.Show.Show (Data.IMap.Run a)
instance GHC.Read.Read a => GHC.Read.Read (Data.IMap.Run a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.IMap.Run a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.IMap.Run a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.IMap.IMap a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.IMap.IMap a)
instance GHC.Base.Applicative Data.IMap.IMap
instance Data.Foldable.Foldable Data.IMap.Run
instance Data.Traversable.Traversable Data.IMap.Run
module Brick.BorderMap
-- | A BorderMap a is like a Map Location a, except that
-- there is a rectangle, and only Locations on the border of this
-- rectangle are retained. The BorderMap can be queried for the
-- position and size of the rectangle. There are also efficient bulk
-- query and bulk update operations for adjacent positions on the border.
data BorderMap a
data Edges a
Edges :: a -> Edges a
[eTop, eBottom, eLeft, eRight] :: Edges a -> a
eTopL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
eBottomL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
eRightL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
eLeftL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
-- | An empty BorderMap that only tracks the point (0,0).
empty :: BorderMap a
-- | Given a rectangle (specified as the coordinates of the top, left,
-- bottom, and right sides), initialize an empty BorderMap.
emptyCoordinates :: Edges Int -> BorderMap a
-- | A BorderMap that tracks only the given the point (and initially
-- maps it to the given value).
singleton :: Location -> a -> BorderMap a
-- | Bulk insertion of horizontally-adjacent values. The Location
-- gives the start point, and the Run extends in the "larger
-- columns" direction.
insertH :: Location -> Run a -> BorderMap a -> BorderMap a
-- | Bulk insertion of vertically-adjacent values. The Location
-- gives the start point, and the Run extends in the "larger rows"
-- direction.
insertV :: Location -> Run a -> BorderMap a -> BorderMap a
-- | Insert a single value at the given location.
insert :: Location -> a -> BorderMap a -> BorderMap a
-- | Assumes the two BorderMaps are tracking the same rectangles,
-- but have disjoint keys. This property is not checked.
unsafeUnion :: BorderMap a -> BorderMap a -> BorderMap a
-- | The positions of the edges of the rectangle whose border is retained
-- in a BorderMap. For example, if coordinates m = e,
-- then the top border contains the Locations on row eTop
-- e and between columns eLeft e to eRight e
-- inclusive.
coordinates :: BorderMap a -> Edges Int
-- | A complementary way to query the edges of the rectangle whose border
-- is retained in a BorderMap. For example, if bounds m =
-- b, then a 'Location'\'s column must be between fst (eTop
-- b) and snd (eTop b) to be retained. See also
-- coordinates, which is in most cases a more natural border
-- query.
bounds :: BorderMap a -> Edges (Int, Int)
-- | Maps giving the values along each edge. Corner values are replicated
-- in all relevant edges.
values :: BorderMap a -> Edges (IMap a)
-- | Look up all values on a given row. The IMap returned maps
-- columns to values.
lookupRow :: Int -> BorderMap a -> IMap a
-- | Look up all values on a given column. The IMap returned maps
-- rows to values.
lookupCol :: Int -> BorderMap a -> IMap a
-- | Bulk lookup of horizontally-adjacent values. The Location gives
-- the starting point, and the Run extends in the "larger columns"
-- direction. The IMap returned maps columns to values.
lookupH :: Location -> Run ignored -> BorderMap a -> IMap a
-- | Bulk lookup of vertically-adjacent values. The Location gives
-- the starting point, and the Run extends in the "larger rows"
-- direction. The IMap returned maps rows to values.
lookupV :: Location -> Run ignored -> BorderMap a -> IMap a
-- | Look up a single position.
lookup :: Location -> BorderMap a -> Maybe a
-- | Set the rectangle being tracked by this BorderMap, throwing
-- away any values that do not lie on this new rectangle.
setCoordinates :: Edges Int -> BorderMap a -> BorderMap a
-- | Ensure that the rectangle being tracked by this BorderMap
-- extends no farther than the given one.
crop :: Edges Int -> BorderMap a -> BorderMap a
-- | Ensure that the rectangle being tracked by this BorderMap
-- extends at least as far as the given one.
expand :: Edges Int -> BorderMap a -> BorderMap a
-- | Move a BorderMap by adding the given Location to all
-- keys in the map.
translate :: Location -> BorderMap a -> BorderMap a
instance GHC.Base.Functor Brick.BorderMap.BorderMap
instance GHC.Show.Show a => GHC.Show.Show (Brick.BorderMap.BorderMap a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Brick.BorderMap.BorderMap a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Brick.BorderMap.BorderMap a)
-- | Utility functions.
module Brick.Util
-- | Given a minimum value and a maximum value, clamp a value to that range
-- (values less than the minimum map to the minimum and values greater
-- than the maximum map to the maximum).
--
--
-- >>> clamp 1 10 11
-- 10
--
-- >>> clamp 1 10 2
-- 2
--
-- >>> clamp 5 10 1
-- 5
--
clamp :: (Ord a) => a -> a -> a -> a
-- | Build an attribute from a foreground color and a background color.
-- Intended to be used infix.
on :: Color -> Color -> Attr
-- | Create an attribute from the specified foreground color (the
-- background color is the "default").
fg :: Color -> Attr
-- | Create an attribute from the specified background color (the
-- background color is the "default").
bg :: Color -> Attr
-- | Add a Location offset to the specified CursorLocation.
clOffset :: CursorLocation n -> Location -> CursorLocation n
-- | Basic types used by this library.
module Brick.Types
-- | The type of widgets.
data Widget n
Widget :: Size -> Size -> RenderM n (Result n) -> Widget n
-- | This widget's horizontal growth policy
[hSize] :: Widget n -> Size
-- | This widget's vertical growth policy
[vSize] :: Widget n -> Size
-- | This widget's rendering function
[render] :: Widget n -> RenderM n (Result n)
-- | A terminal screen location.
data Location
Location :: (Int, Int) -> Location
-- | (Column, Row)
[loc] :: Location -> (Int, Int)
locL :: Lens' Location (Int, Int)
-- | The class of types that behave like terminal locations.
class TerminalLocation a
-- | Get the column out of the value
locationColumnL :: TerminalLocation a => Lens' a Int
locationColumn :: TerminalLocation a => a -> Int
-- | Get the row out of the value
locationRowL :: TerminalLocation a => Lens' a Int
locationRow :: TerminalLocation a => a -> Int
-- | A cursor location. These are returned by the rendering process.
data CursorLocation n
CursorLocation :: !Location -> !(Maybe n) -> CursorLocation n
-- | The location
[cursorLocation] :: CursorLocation n -> !Location
-- | The name of the widget associated with the location
[cursorLocationName] :: CursorLocation n -> !(Maybe n)
cursorLocationL :: forall n_azMC. Lens' (CursorLocation n_azMC) Location
cursorLocationNameL :: forall n_azMC n_aAIi. Lens (CursorLocation n_azMC) (CursorLocation n_aAIi) (Maybe n_azMC) (Maybe n_aAIi)
-- | Describes the state of a viewport as it appears as its most recent
-- rendering.
data Viewport
VP :: Int -> Int -> DisplayRegion -> Viewport
-- | The column offset of left side of the viewport.
[_vpLeft] :: Viewport -> Int
-- | The row offset of the top of the viewport.
[_vpTop] :: Viewport -> Int
-- | The size of the viewport.
[_vpSize] :: Viewport -> DisplayRegion
-- | The type of viewports that indicates the direction(s) in which a
-- viewport is scrollable.
data ViewportType
-- | Viewports of this type are scrollable only vertically.
Vertical :: ViewportType
-- | Viewports of this type are scrollable only horizontally.
Horizontal :: ViewportType
-- | Viewports of this type are scrollable vertically and horizontally.
Both :: ViewportType
vpSize :: Lens' Viewport DisplayRegion
vpTop :: Lens' Viewport Int
vpLeft :: Lens' Viewport Int
-- | The monad in which event handlers run. Although it may be tempting to
-- dig into the reader value yourself, just use lookupViewport.
newtype EventM n a
EventM :: ReaderT (EventRO n) (StateT (EventState n) IO) a -> EventM n a
[runEventM] :: EventM n a -> ReaderT (EventRO n) (StateT (EventState n) IO) a
-- | The type of actions to take upon completion of an event handler.
data Next a
-- | The type of events.
data BrickEvent n e
-- | The event was a Vty event.
VtyEvent :: Event -> BrickEvent n e
-- | The event was an application event.
AppEvent :: e -> BrickEvent n e
-- | A mouse-down event on the specified region was received. The
-- n value is the resource name of the clicked widget (see
-- clickable).
MouseDown :: n -> Button -> [Modifier] -> Location -> BrickEvent n e
-- | A mouse-up event on the specified region was received. The n
-- value is the resource name of the clicked widget (see
-- clickable).
MouseUp :: n -> (Maybe Button) -> Location -> BrickEvent n e
-- | A convenience function for handling events intended for values that
-- are targets of lenses in your application state. This function obtains
-- the target value of the specified lens, invokes handleEvent
-- on it, and stores the resulting transformed value back in the state
-- using the lens.
handleEventLensed :: a -> Lens' a b -> (e -> b -> EventM n b) -> e -> EventM n a
-- | 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.
type RenderM n a = ReaderT Context (State (RenderState n)) a
-- | Get the current rendering context.
getContext :: RenderM n 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 bordering style should be used, and the attribute map
-- available for rendering.
data Context
-- | The rendering context's current drawing attribute.
attrL :: forall r. Getting r Context Attr
availWidthL :: Lens' Context Int
availHeightL :: Lens' Context Int
ctxAttrMapL :: Lens' Context AttrMap
ctxAttrNameL :: Lens' Context AttrName
ctxBorderStyleL :: Lens' Context BorderStyle
ctxDynBordersL :: Lens' Context Bool
-- | 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.
data Result n
Result :: Image -> [CursorLocation n] -> [VisibilityRequest] -> [Extent n] -> BorderMap DynBorder -> Result n
-- | The final rendered image for a widget
[image] :: Result n -> Image
-- | The list of reported cursor positions for the application to choose
-- from
[cursors] :: Result n -> [CursorLocation n]
-- | The list of visibility requests made by widgets rendered while
-- rendering this one (used by viewports)
[visibilityRequests] :: Result n -> [VisibilityRequest]
[extents] :: Result n -> [Extent n]
-- | Places where we may rewrite the edge of the image when placing this
-- widget next to another one.
[borders] :: Result n -> BorderMap DynBorder
emptyResult :: Result n
-- | Given an attribute name, obtain the attribute for the attribute name
-- by consulting the context's attribute map.
lookupAttrName :: AttrName -> RenderM n Attr
-- | An extent of a named area: its size, location, and origin.
data Extent n
Extent :: n -> Location -> (Int, Int) -> Location -> Extent n
[extentName] :: Extent n -> n
[extentUpperLeft] :: Extent n -> Location
[extentSize] :: Extent n -> (Int, Int)
[extentOffset] :: Extent n -> Location
imageL :: forall n_aAmL. Lens' (Result n_aAmL) Image
cursorsL :: forall n_aAmL. Lens' (Result n_aAmL) [CursorLocation n_aAmL]
visibilityRequestsL :: forall n_aAmL. Lens' (Result n_aAmL) [VisibilityRequest]
extentsL :: forall n_aAmL. Lens' (Result n_aAmL) [Extent n_aAmL]
data VisibilityRequest
VR :: Location -> DisplayRegion -> VisibilityRequest
[vrPosition] :: VisibilityRequest -> Location
[vrSize] :: VisibilityRequest -> DisplayRegion
vrPositionL :: Lens' VisibilityRequest Location
vrSizeL :: Lens' VisibilityRequest DisplayRegion
-- | A template haskell function to build lenses for a record type. This
-- function differs from the makeLenses function in that it does
-- not require the record fields to be prefixed with underscores and it
-- adds an L suffix to lens names to make it clear that they are
-- lenses.
suffixLenses :: Name -> DecsQ
bordersL :: forall n_aAmL. Lens' (Result n_aAmL) (BorderMap DynBorder)
-- | Information about how to redraw a dynamic border character when it
-- abuts another dynamic border character.
data DynBorder
DynBorder :: BorderStyle -> Attr -> Edges BorderSegment -> DynBorder
-- | The Chars to use when redrawing the border. Also used to filter
-- connections: only dynamic borders with equal BorderStyles will
-- connect to each other.
[dbStyle] :: DynBorder -> BorderStyle
-- | What Attr to use to redraw the border character. Also used to
-- filter connections: only dynamic borders with equal Attrs will
-- connect to each other.
[dbAttr] :: DynBorder -> Attr
[dbSegments] :: DynBorder -> Edges BorderSegment
dbStyleL :: Lens' DynBorder BorderStyle
dbAttrL :: Lens' DynBorder Attr
dbSegmentsL :: Lens' DynBorder (Edges BorderSegment)
-- | A border character has four segments, one extending in each direction
-- (horizontally and vertically) from the center of the character.
data BorderSegment
BorderSegment :: Bool -> Bool -> Bool -> BorderSegment
-- | Would this segment be willing to be drawn if a neighbor wanted to
-- connect to it?
[bsAccept] :: BorderSegment -> Bool
-- | Does this segment want to connect to its neighbor?
[bsOffer] :: BorderSegment -> Bool
-- | Should this segment be represented visually?
[bsDraw] :: BorderSegment -> Bool
bsAcceptL :: Lens' BorderSegment Bool
bsOfferL :: Lens' BorderSegment Bool
bsDrawL :: Lens' BorderSegment Bool
data Edges a
Edges :: a -> Edges a
[eTop, eBottom, eLeft, eRight] :: Edges a -> a
eTopL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
eBottomL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
eRightL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
eLeftL :: forall a_adTJ. Lens' (Edges a_adTJ) a_adTJ
-- | 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.
data Size
-- | Fixed widgets take up the same amount of space no matter how much they
-- are given (non-greedy).
Fixed :: Size
-- | Greedy widgets take up all the space they are given.
Greedy :: Size
-- | The type of padding.
data Padding
-- | Pad by the specified number of rows or columns.
Pad :: Int -> Padding
-- | Pad up to the number of available rows or columns.
Max :: Padding
-- | Scrolling direction.
data Direction
-- | Up/left
Up :: Direction
-- | Down/right
Down :: Direction
instance Brick.Types.Internal.TerminalLocation (Brick.Types.Internal.CursorLocation n)
instance GHC.Classes.Ord Brick.Types.Size
instance GHC.Classes.Eq Brick.Types.Size
instance GHC.Show.Show Brick.Types.Size
instance Control.Monad.IO.Class.MonadIO (Brick.Types.EventM n)
instance GHC.Base.Monad (Brick.Types.EventM n)
instance GHC.Base.Applicative (Brick.Types.EventM n)
instance GHC.Base.Functor (Brick.Types.EventM n)
-- | This module provides the core widget combinators and rendering
-- routines. Everything this library does is in terms of these basic
-- primitives.
module Brick.Widgets.Core
-- | The class of text types that have widths measured in terminal columns.
-- NEVER use length etc. to measure the length of a string if you
-- need to compute how much screen space it will occupy; always use
-- textWidth.
class TextWidth a
textWidth :: TextWidth a => a -> Int
-- | The empty widget.
emptyWidget :: Widget n
-- | Build a widget directly from a raw Vty image.
raw :: Image -> Widget n
-- | Build a widget from a Text value. Behaves the same as
-- str when the input contains multiple lines.
--
-- The input string must not contain tab characters. If it does,
-- interface corruption will result since the terminal will likely render
-- it as taking up more than a single column. The caller should replace
-- tabs with the appropriate number of spaces as desired. The reinput
-- text should not contain escapes.
txt :: Text -> Widget n
-- | Make a widget from text, but wrap the words in the input's lines at
-- the available width using the default wrapping settings. The input
-- text should not contain escapes.
txtWrap :: Text -> Widget n
-- | Make a widget from text, but wrap the words in the input's lines at
-- the available width using the specified wrapping settings. The input
-- text should not contain escapes.
txtWrapWith :: WrapSettings -> Text -> Widget n
-- | Build a widget from a String. Breaks newlines up and space-pads
-- short lines out to the length of the longest line.
--
-- The input string must not contain tab characters. If it does,
-- interface corruption will result since the terminal will likely render
-- it as taking up more than a single column. The caller should replace
-- tabs with the appropriate number of spaces as desired. The reinput
-- string should not contain escapes.
str :: String -> Widget n
-- | Make a widget from a string, but wrap the words in the input's lines
-- at the available width using the default wrapping settings. The input
-- string should not contain escapes.
strWrap :: String -> Widget n
-- | Make a widget from a string, but wrap the words in the input's lines
-- at the available width using the specified wrapping settings. The
-- input string should not contain escapes.
strWrapWith :: WrapSettings -> String -> Widget n
-- | Fill all available space with the specified character. Grows both
-- horizontally and vertically.
fill :: Char -> Widget n
-- | Hyperlink the given widget to the specified URL. Not all terminal
-- emulators support this. In those that don't, this should have no
-- discernible effect.
hyperlink :: Text -> Widget n -> Widget n
-- | Pad the specified widget on the left. If max padding is used, this
-- grows greedily horizontally; otherwise it defers to the padded widget.
padLeft :: Padding -> Widget n -> Widget n
-- | Pad the specified widget on the right. If max padding is used, this
-- grows greedily horizontally; otherwise it defers to the padded widget.
padRight :: Padding -> Widget n -> Widget n
-- | Pad the specified widget on the top. If max padding is used, this
-- grows greedily vertically; otherwise it defers to the padded widget.
padTop :: Padding -> Widget n -> Widget n
-- | Pad the specified widget on the bottom. If max padding is used, this
-- grows greedily vertically; otherwise it defers to the padded widget.
padBottom :: Padding -> Widget n -> Widget n
-- | Pad a widget on the left and right. Defers to the padded widget for
-- growth policy.
padLeftRight :: Int -> Widget n -> Widget n
-- | Pad a widget on the top and bottom. Defers to the padded widget for
-- growth policy.
padTopBottom :: Int -> Widget n -> Widget n
-- | Pad a widget on all sides. Defers to the padded widget for growth
-- policy.
padAll :: Int -> Widget n -> Widget n
-- | 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.
(<=>) :: Widget n -> Widget n -> Widget n
-- | 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.
(<+>) :: Widget n -> Widget n -> Widget n
-- | 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 the contained widgets (if any are greedy, so is the
-- box).
hBox :: [Widget n] -> Widget n
-- | 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 the contained widgets (if any are greedy, so is the
-- box).
vBox :: [Widget n] -> Widget n
-- | 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. This is non-greedy horizontally
-- and defers to the limited widget vertically.
hLimit :: Int -> Widget n -> Widget n
-- | 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. This is non-greedy vertically and defers
-- to the limited widget horizontally.
vLimit :: Int -> Widget n -> Widget n
-- | Set the rendering context height and width for this widget. This is
-- useful for relaxing the rendering size constraints on e.g. layer
-- widgets where cropping to the screen size is undesirable.
setAvailableSize :: (Int, Int) -> Widget n -> Widget n
-- | 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.
withDefAttr :: AttrName -> Widget n -> Widget n
-- | 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 and then modifying it with the
-- specified function.
modifyDefAttr :: (Attr -> Attr) -> Widget n -> Widget n
-- | 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.
withAttr :: AttrName -> Widget n -> Widget n
-- | When rendering the specified widget, force all attribute lookups in
-- the attribute map to use the value currently assigned to the specified
-- attribute name.
forceAttr :: AttrName -> Widget n -> Widget n
-- | Override the lookup of targetName to return the attribute
-- value associated with fromName when rendering the specified
-- widget. See also mapAttrName.
overrideAttr :: AttrName -> AttrName -> Widget n -> Widget n
-- | When rendering the specified widget, update the attribute map with the
-- specified transformation.
updateAttrMap :: (AttrMap -> AttrMap) -> Widget n -> Widget n
-- | When rendering the specified widget, use the specified border style
-- for any border rendering.
withBorderStyle :: BorderStyle -> Widget n -> Widget n
-- | When rendering the specified widget, create borders that respond
-- dynamically to their neighbors to form seamless connections.
joinBorders :: Widget n -> Widget n
-- | When rendering the specified widget, use static borders. This may be
-- marginally faster, but will introduce a small gap between neighboring
-- orthogonal borders.
--
-- This is the default for backwards compatibility.
separateBorders :: Widget n -> Widget n
-- | After the specified widget has been rendered, freeze its borders. A
-- frozen border will not be affected by neighbors, nor will it affect
-- neighbors. Compared to separateBorders, freezeBorders
-- will not affect whether borders connect internally to a widget
-- (whereas separateBorders prevents them from connecting).
--
-- Frozen borders cannot be thawed.
freezeBorders :: Widget n -> Widget n
-- | When rendering the specified widget, also register a cursor
-- positioning request using the specified name and location.
showCursor :: n -> Location -> Widget n -> Widget n
-- | The class of types that store interface element names.
class Named a n
-- | Get the name of the specified value.
getName :: Named a n => a -> n
-- | Translate the specified widget by the specified offset amount. Defers
-- to the translated widget for growth policy.
translateBy :: Location -> Widget n -> Widget n
-- | Crop the specified widget on the left by the specified number of
-- columns. Defers to the cropped widget for growth policy.
cropLeftBy :: Int -> Widget n -> Widget n
-- | Crop the specified widget on the right by the specified number of
-- columns. Defers to the cropped widget for growth policy.
cropRightBy :: Int -> Widget n -> Widget n
-- | Crop the specified widget on the top by the specified number of rows.
-- Defers to the cropped widget for growth policy.
cropTopBy :: Int -> Widget n -> Widget n
-- | Crop the specified widget on the bottom by the specified number of
-- rows. Defers to the cropped widget for growth policy.
cropBottomBy :: Int -> Widget n -> Widget n
-- | Render the specified widget and record its rendering extent using the
-- specified name (see also lookupExtent).
reportExtent :: n -> Widget n -> Widget n
-- | Request mouse click events on the specified widget.
clickable :: n -> Widget n -> Widget n
-- | 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, then the
-- visibility requests are merged with the inner visibility request
-- taking preference. If a viewport receives more than one scrolling
-- request from EventM, all are honored in the order in which they
-- are received.
viewport :: (Ord n, Show n) => n -> ViewportType -> Widget n -> Widget n
-- | 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.
visible :: Widget n -> Widget n
-- | 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.
visibleRegion :: Location -> DisplayRegion -> Widget n -> Widget n
-- | Given a name, obtain the viewport for that name by consulting the
-- viewport map in the rendering monad. NOTE! Some care must be taken
-- when calling this function, since it only returns useful values after
-- the viewport in question has been rendered. If you call this function
-- during rendering before a viewport has been rendered, you may get
-- nothing or you may get a stale version of the viewport. This is
-- because viewports are updated during rendering and the one you are
-- interested in may not have been rendered yet. So if you want to use
-- this, be sure you know what you are doing.
unsafeLookupViewport :: (Ord n) => n -> RenderM n (Maybe Viewport)
-- | Render the specified widget. If the widget has an entry in the
-- rendering cache using the specified name as the cache key, use the
-- rendered version from the cache instead. If not, render the widget and
-- update the cache.
--
-- See also invalidateCacheEntry.
cached :: (Ord n) => n -> Widget n -> Widget n
-- | Add an offset to all cursor locations, visbility requests, and extents
-- 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.
addResultOffset :: Location -> Result n -> Result n
-- | After rendering the specified widget, crop its result image to the
-- dimensions in the rendering context.
cropToContext :: Widget n -> Widget n
instance Brick.Widgets.Core.TextWidth Data.Text.Internal.Text
instance Data.Foldable.Foldable f => Brick.Widgets.Core.TextWidth (f GHC.Types.Char)
-- | This module provides a progress bar widget.
module Brick.Widgets.ProgressBar
-- | Draw a progress bar with the specified (optional) label and progress
-- value. This fills available horizontal space and is one row high.
progressBar :: Maybe String -> Float -> Widget n
-- | The attribute of the completed portion of the progress bar.
progressCompleteAttr :: AttrName
-- | The attribute of the incomplete portion of the progress bar.
progressIncompleteAttr :: AttrName
-- | This module provides a basic text editor widget. You'll need to embed
-- an Editor in your application state and transform it with
-- handleEditorEvent when relevant events arrive. To get the
-- contents of the editor, just use getEditContents. To modify it,
-- use the TextZipper interface with applyEdit.
--
-- The editor's handleEditorEvent function handles a set of basic
-- input events that should suffice for most purposes; see the source for
-- a complete list.
--
-- Bear in mind that the editor provided by this module is intended to
-- provide basic input support for brick applications but it is not
-- intended to be a replacement for your favorite editor such as Vim or
-- Emacs. It is also not suitable for building sophisticated editors. If
-- you want to build your own editor, I suggest starting from scratch.
module Brick.Widgets.Edit
-- | Editor state. Editors support the following events by default:
--
--
-- - Ctrl-a: go to beginning of line
-- - Ctrl-e: go to end of line
-- - Ctrl-d, Del: delete character at cursor position
-- - Backspace: delete character prior to cursor position
-- - Ctrl-k: delete all from cursor to end of line
-- - Ctrl-u: delete all from cursor to beginning of line
-- - Arrow keys: move cursor
-- - Enter: break the current line at the cursor position
--
data Editor t n
-- | Construct an editor over String values
editor :: GenericTextZipper a => n -> Maybe Int -> a -> Editor a n
-- | Construct an editor over Text values
editorText :: n -> Maybe Int -> Text -> Editor Text n
-- | Get the contents of the editor.
getEditContents :: Monoid t => Editor t n -> [t]
handleEditorEvent :: (Eq t, Monoid t) => Event -> Editor t n -> EventM n (Editor t n)
-- | Apply an editing operation to the editor's contents. Bear in mind that
-- you should only apply zipper operations that operate on the current
-- line; the editor will only ever render the first line of text.
applyEdit :: (TextZipper t -> TextZipper t) -> Editor t n -> Editor t n
editContentsL :: forall t_aXRq n_aXRr t_aXSa. Lens (Editor t_aXRq n_aXRr) (Editor t_aXSa n_aXRr) (TextZipper t_aXRq) (TextZipper t_aXSa)
-- | Turn an editor state value into a widget. This uses the editor's name
-- for its scrollable viewport handle and the name is also used to report
-- mouse events.
renderEditor :: (Ord n, Show n, Monoid t, TextWidth t, GenericTextZipper t) => ([t] -> Widget n) -> Bool -> Editor t n -> Widget n
-- | The attribute assigned to the editor when it does not have focus.
editAttr :: AttrName
-- | The attribute assigned to the editor when it has focus. Extends
-- editAttr.
editFocusedAttr :: AttrName
instance (GHC.Show.Show t, GHC.Show.Show n) => GHC.Show.Show (Brick.Widgets.Edit.Editor t n)
instance Brick.Widgets.Core.Named (Brick.Widgets.Edit.Editor t n) n
-- | This module provides combinators for centering other widgets.
module Brick.Widgets.Center
-- | Center the specified widget horizontally. Consumes all available
-- horizontal space.
hCenter :: Widget n -> Widget n
-- | Center the specified widget horizontally. Consumes all available
-- horizontal space. Uses the specified character to fill in the space to
-- either side of the centered widget (defaults to space).
hCenterWith :: Maybe Char -> Widget n -> Widget n
-- | Center the specified widget horizontally using a Vty image
-- translation. Consumes all available horizontal space. Unlike hCenter,
-- this does not fill the surrounding space so it is suitable for use as
-- a layer. Layers underneath this widget will be visible in regions
-- surrounding the centered widget.
hCenterLayer :: Widget n -> Widget n
-- | Center a widget vertically. Consumes all vertical space.
vCenter :: Widget n -> Widget n
-- | Center a widget vertically. Consumes all vertical space. Uses the
-- specified character to fill in the space above and below the centered
-- widget (defaults to space).
vCenterWith :: Maybe Char -> Widget n -> Widget n
-- | Center the specified widget vertically using a Vty image translation.
-- Consumes all available vertical space. Unlike vCenter, this does not
-- fill the surrounding space so it is suitable for use as a layer.
-- Layers underneath this widget will be visible in regions surrounding
-- the centered widget.
vCenterLayer :: Widget n -> Widget n
-- | Center a widget both vertically and horizontally. Consumes all
-- available vertical and horizontal space.
center :: Widget n -> Widget n
-- | Center a widget both vertically and horizontally. Consumes all
-- available vertical and horizontal space. Uses the specified character
-- to fill in the space around the centered widget (defaults to space).
centerWith :: Maybe Char -> Widget n -> Widget n
-- | Center a widget both vertically and horizontally using a Vty image
-- translation. Consumes all available vertical and horizontal space.
-- Unlike center, this does not fill in the surrounding space with a
-- character so it is usable as a layer. Any widget underneath this one
-- will be visible in the region surrounding the centered widget.
centerLayer :: Widget n -> Widget n
-- | Center the widget horizontally and vertically about the specified
-- origin.
centerAbout :: Location -> Widget n -> Widget n
-- | This module provides border widgets: vertical borders, horizontal
-- borders, and a box border wrapper widget. All functions in this module
-- use the rendering context's active BorderStyle; to change the
-- BorderStyle, use withBorderStyle.
module Brick.Widgets.Border
-- | Put a border around the specified widget.
border :: Widget n -> Widget n
-- | Put a border around the specified widget with the specified label
-- widget placed in the middle of the top horizontal border.
--
-- Note that a border will wrap its child widget as tightly as possible,
-- which means that if the child widget is narrower than the label
-- widget, the label widget will be truncated. If you want to avoid this
-- behavior, add a fill or other space-filling wrapper to the
-- bordered widget so that it takes up enough room to make the border
-- horizontally able to avoid truncating the label.
borderWithLabel :: Widget n -> Widget n -> Widget n
-- | A horizontal border. Fills all horizontal space.
hBorder :: Widget n
-- | A horizontal border with a label placed in the center of the border.
-- Fills all horizontal space.
hBorderWithLabel :: Widget n -> Widget n
-- | A vertical border. Fills all vertical space.
vBorder :: Widget n
-- | Draw the specified border element using the active border style using
-- borderAttr.
--
-- Does not participate in dynamic borders (due to the difficulty of
-- introspecting on the first argument); consider using
-- joinableBorder instead.
borderElem :: (BorderStyle -> Char) -> Widget n
-- | The top-level border attribute name.
borderAttr :: AttrName
-- | A single-character dynamic border that will react to neighboring
-- borders, initially connecting in the given directions.
joinableBorder :: Edges Bool -> Widget n
-- | This module provides a simple dialog widget. You get to pick the
-- dialog title, if any, as well as its body and buttons.
--
-- Note that this dialog is really for simple use cases where you want to
-- get the user's answer to a question, such as "Would you like to save
-- changes before quitting?" If you require something more sophisticated,
-- you'll need to build it yourself. You might also consider seeing the
-- Forms module for help with input management, and see the
-- implementation of this module to see how to reproduce a dialog-style
-- UI.
module Brick.Widgets.Dialog
-- | Dialogs present a window with a title (optional), a body, and buttons
-- (optional). Dialog buttons are labeled with strings and map to values
-- of type a, which you choose.
--
-- Dialogs handle the following events by default with handleDialogEvent:
--
--
-- - Tab or Right Arrow: select the next button
-- - Shift-tab or Left Arrow: select the previous button
--
data Dialog a
-- | The dialog title
dialogTitle :: Dialog a -> Maybe String
-- | The dialog button labels and values
dialogButtons :: Dialog a -> [(String, a)]
-- | The currently selected dialog button index (if any)
dialogSelectedIndex :: Dialog a -> Maybe Int
-- | The maximum width of the dialog
dialogWidth :: Dialog a -> Int
-- | Create a dialog.
dialog :: Maybe String -> Maybe (Int, [(String, a)]) -> Int -> Dialog a
-- | Render a dialog with the specified body widget. This renders the
-- dialog as a layer, which makes this suitable as a top-level layer in
-- your rendering function to be rendered on top of the rest of your
-- interface.
renderDialog :: Dialog a -> Widget n -> Widget n
handleDialogEvent :: Event -> Dialog a -> EventM n (Dialog a)
-- | Obtain the value associated with the dialog's currently-selected
-- button, if any. This function is probably what you want when someone
-- presses Enter in a dialog.
dialogSelection :: Dialog a -> Maybe a
-- | The default attribute of the dialog
dialogAttr :: AttrName
-- | The default attribute for all dialog buttons
buttonAttr :: AttrName
-- | The attribute for the selected dialog button (extends
-- dialogAttr)
buttonSelectedAttr :: AttrName
dialogButtonsL :: forall a_a12ep a_a12f6. Lens (Dialog a_a12ep) (Dialog a_a12f6) [(String, a_a12ep)] [(String, a_a12f6)]
dialogSelectedIndexL :: forall a_a12ep. Lens' (Dialog a_a12ep) (Maybe Int)
dialogWidthL :: forall a_a12ep. Lens' (Dialog a_a12ep) Int
dialogTitleL :: forall a_a12ep. Lens' (Dialog a_a12ep) (Maybe String)
-- | This module provides a type and functions for handling focus rings of
-- values.
--
-- This interface is experimental.
module Brick.Focus
-- | A focus ring containing a sequence of resource names to focus and a
-- currently-focused name.
data FocusRing n
-- | Construct a focus ring from the list of resource names.
focusRing :: [n] -> FocusRing n
-- | Advance focus to the next value in the ring.
focusNext :: FocusRing n -> FocusRing n
-- | Advance focus to the previous value in the ring.
focusPrev :: FocusRing n -> FocusRing n
-- | Get the currently-focused resource name from the ring. If the ring is
-- emtpy, return Nothing.
focusGetCurrent :: FocusRing n -> Maybe n
-- | Set the currently-focused resource name in the ring, provided the name
-- is in the ring. Otherwise return the ring unmodified.
focusSetCurrent :: (Eq n) => n -> FocusRing n -> FocusRing n
-- | Cursor selection convenience function for use as an
-- appChooseCursor value.
focusRingCursor :: (Eq n) => (a -> FocusRing n) -> a -> [CursorLocation n] -> Maybe (CursorLocation n)
-- | This function is a convenience function to look up a widget state
-- value's resource name in a focus ring and set its focus setting
-- according to the focus ring's state. This function determines whether
-- a given widget state value is the focus of the ring and passes the
-- resulting boolean to a rendering function, along with the state value
-- (a), to produce whatever comes next (b).
--
-- Focus-aware widgets have rendering functions that should be usable
-- with this combinator; see List and Edit.
withFocusRing :: (Eq n, Named a n) => FocusRing n -> (Bool -> a -> b) -> a -> b
-- | Modify the internal circular list structure of a focus ring directly.
-- This function permits modification of the circular list using the rich
-- Data.CircularList API.
focusRingModify :: (CList n -> CList n) -> FocusRing n -> FocusRing n
module Brick.Main
-- | The library application abstraction. Your application's operations are
-- represented here and passed to one of the various main functions in
-- this module. An application is in terms of an application state type
-- s, an application event type e, and a resource name
-- type n. In the simplest case e is unused (left
-- polymorphic or set to '()'), but you may define your own event type
-- and use customMain to provide custom events. The state type is
-- the type of application state to be provided by you and iteratively
-- modified by event handlers. The resource name type is the type of
-- names you can assign to rendering resources such as viewports and
-- cursor locations.
data App s e n
App :: s -> [Widget n] -> s -> [CursorLocation n] -> Maybe (CursorLocation n) -> s -> BrickEvent n e -> EventM n (Next s) -> s -> EventM n s -> s -> AttrMap -> App s e n
-- | This function turns your application state into a list of widget
-- layers. The layers are listed topmost first.
[appDraw] :: App s e n -> s -> [Widget n]
-- | This function chooses which of the zero or more cursor locations
-- reported by the rendering process should be selected as the one to use
-- to place the cursor. If this returns Nothing, no cursor is
-- placed. The rationale here is that many widgets may request a cursor
-- placement but your application state is what you probably want to use
-- to decide which one wins.
[appChooseCursor] :: App s e n -> s -> [CursorLocation n] -> Maybe (CursorLocation n)
-- | This function takes the current application state and an event and
-- returns an action to be taken and a corresponding transformed
-- application state. Possible options are continue,
-- suspendAndResume, and halt.
[appHandleEvent] :: App s e n -> s -> BrickEvent n e -> EventM n (Next s)
-- | This function gets called once just prior to the first drawing of your
-- application. Here is where you can make initial scrolling requests,
-- for example.
[appStartEvent] :: App s e n -> s -> EventM n s
-- | The attribute map that should be used during rendering.
[appAttrMap] :: App s e n -> s -> AttrMap
-- | The default main entry point which takes an application and an initial
-- state and returns the final state returned by a halt operation.
defaultMain :: (Ord n) => App s e n -> s -> IO s
-- | The custom event loop entry point to use when the simpler ones don't
-- permit enough control.
customMain :: (Ord n) => IO Vty -> Maybe (BChan e) -> App s e n -> s -> IO s
-- | A simple main entry point which takes a widget and renders it. This
-- event loop terminates when the user presses any key, but terminal
-- resize events cause redraws.
simpleMain :: (Ord n) => Widget n -> IO ()
-- | An event-handling function which continues execution of the event loop
-- only when resize events occur; all other types of events trigger a
-- halt. This is a convenience function useful as an
-- appHandleEvent value for simple applications using the
-- Event type that do not need to get more sophisticated user
-- input.
resizeOrQuit :: s -> BrickEvent n e -> EventM n (Next s)
-- | A simple application with reasonable defaults to be overridden as
-- desired:
--
--
-- - Draws only the specified widget
-- - Quits on any event other than resizes
-- - Has no start event handler
-- - Provides no attribute map
-- - Never shows any cursors
--
simpleApp :: Widget n -> App s e n
-- | Continue running the event loop with the specified application state.
continue :: s -> EventM n (Next s)
-- | Halt the event loop and return the specified application state as the
-- final state value.
halt :: s -> EventM n (Next s)
-- | Suspend the event loop, save the terminal state, and run the specified
-- action. When it returns an application state value, restore the
-- terminal state, redraw the application from the new state, and resume
-- the event loop.
suspendAndResume :: IO s -> EventM n (Next s)
-- | Given a viewport name, get the viewport's size and offset information
-- from the most recent rendering. Returns Nothing if no such
-- state could be found, either because the name was invalid or because
-- no rendering has occurred (e.g. in an appStartEvent handler).
lookupViewport :: (Ord n) => n -> EventM n (Maybe Viewport)
-- | Given a resource name, get the most recent rendering extent for the
-- name (if any).
lookupExtent :: (Eq n) => n -> EventM n (Maybe (Extent n))
-- | Given a mouse click location, return the extents intersected by the
-- click. The returned extents are sorted such that the first extent in
-- the list is the most specific extent and the last extent is the most
-- generic (top-level). So if two extents A and B both intersected the
-- mouse click but A contains B, then they would be returned [B, A].
findClickedExtents :: (Int, Int) -> EventM n [Extent n]
-- | Did the specified mouse coordinates (column, row) intersect the
-- specified extent?
clickedExtent :: (Int, Int) -> Extent n -> Bool
-- | Get the Vty handle currently in use.
getVtyHandle :: EventM n Vty
-- | Build a viewport scroller for the viewport with the specified name.
viewportScroll :: n -> ViewportScroll n
-- | A viewport scrolling handle for managing the scroll state of
-- viewports.
data ViewportScroll n
-- | Scroll the viewport vertically by the specified number of rows or
-- columns depending on the orientation of the viewport.
vScrollBy :: ViewportScroll n -> Int -> EventM n ()
-- | Scroll the viewport vertically by one page in the specified direction.
vScrollPage :: ViewportScroll n -> Direction -> EventM n ()
-- | Scroll vertically to the beginning of the viewport.
vScrollToBeginning :: ViewportScroll n -> EventM n ()
-- | Scroll vertically to the end of the viewport.
vScrollToEnd :: ViewportScroll n -> EventM n ()
-- | Scroll the viewport horizontally by the specified number of rows or
-- columns depending on the orientation of the viewport.
hScrollBy :: ViewportScroll n -> Int -> EventM n ()
-- | Scroll the viewport horizontally by one page in the specified
-- direction.
hScrollPage :: ViewportScroll n -> Direction -> EventM n ()
-- | Scroll horizontally to the beginning of the viewport.
hScrollToBeginning :: ViewportScroll n -> EventM n ()
-- | Scroll horizontally to the end of the viewport.
hScrollToEnd :: ViewportScroll n -> EventM n ()
-- | Set the top row offset of the viewport.
setTop :: ViewportScroll n -> Int -> EventM n ()
-- | Set the left column offset of the viewport.
setLeft :: ViewportScroll n -> Int -> EventM n ()
-- | Ignore all requested cursor positions returned by the rendering
-- process. This is a convenience function useful as an
-- appChooseCursor value when a simple application has no need to
-- position the cursor.
neverShowCursor :: s -> [CursorLocation n] -> Maybe (CursorLocation n)
-- | Always show the first cursor, if any, returned by the rendering
-- process. This is a convenience function useful as an
-- appChooseCursor value when a simple program has zero or more
-- widgets that advertise a cursor position.
showFirstCursor :: s -> [CursorLocation n] -> Maybe (CursorLocation n)
-- | Show the cursor with the specified resource name, if such a cursor
-- location has been reported.
showCursorNamed :: (Eq n) => n -> [CursorLocation n] -> Maybe (CursorLocation n)
-- | Invalidate the rendering cache entry with the specified resource name.
invalidateCacheEntry :: (Ord n) => n -> EventM n ()
-- | Invalidate the entire rendering cache.
invalidateCache :: (Ord n) => EventM n ()
-- | This module provides a scrollable list type and functions for
-- manipulating and rendering it.
module Brick.Widgets.List
-- | List state. Lists have an element type e that is the data
-- stored by the list. Lists handle the following events by default:
--
--
-- - Up/down arrow keys: move cursor of selected item
-- - Page up / page down keys: move cursor of selected item by one page
-- at a time (based on the number of items shown)
-- - Home/end keys: move cursor of selected item to beginning or end of
-- list
--
data List n e
-- | Construct a list in terms of an element type e.
list :: n -> Vector e -> Int -> List n e
-- | Turn a list state value into a widget given an item drawing function.
renderList :: (Ord n, Show n) => (Bool -> e -> Widget n) -> Bool -> List n e -> Widget n
-- | Like renderList, except the render function is also provided
-- with the index of each element.
renderListWithIndex :: (Ord n, Show n) => (Int -> Bool -> e -> Widget n) -> Bool -> List n e -> Widget n
handleListEvent :: (Ord n) => Event -> List n e -> EventM n (List n e)
-- | Enable list movement with the vi keys with a fallback if none match.
-- Use (handleListEventVi handleListEvent) in place of handleListEvent to
-- add the vi keys bindings to the standard ones. Movements handled
-- include:
--
--
-- - Up (k)
-- - Down (j)
-- - Page Up (Ctrl-b)
-- - Page Down (Ctrl-f)
-- - Half Page Up (Ctrl-u)
-- - Half Page Down (Ctrl-d)
-- - Top (g)
-- - Bottom (G)
--
handleListEventVi :: (Ord n) => (Event -> List n e -> EventM n (List n e)) -> Event -> List n e -> EventM n (List n e)
listElementsL :: forall n_a16L8 e_a16L9 e_a16UQ. Lens (List n_a16L8 e_a16L9) (List n_a16L8 e_a16UQ) (Vector e_a16L9) (Vector e_a16UQ)
listSelectedL :: forall n_a16L8 e_a16L9. Lens' (List n_a16L8 e_a16L9) (Maybe Int)
listNameL :: forall n_a16L8 e_a16L9 n_a16UR. Lens (List n_a16L8 e_a16L9) (List n_a16UR e_a16L9) n_a16L8 n_a16UR
listItemHeightL :: forall n_a16L8 e_a16L9. Lens' (List n_a16L8 e_a16L9) Int
-- | The list's vector of elements.
listElements :: List n e -> (Vector e)
-- | The list's name.
listName :: List n e -> n
-- | Return a list's selected element, if any.
listSelectedElement :: List n e -> Maybe (Int, e)
-- | The list's selected element index, if any.
listSelected :: List n e -> (Maybe Int)
-- | The height of the list items.
listItemHeight :: List n e -> Int
-- | Move the list selected index. If the index is `Just x`, adjust by the
-- specified amount; if it is Nothing (i.e. there is no selection)
-- and the direction is positive, set to `Just 0` (first element),
-- otherwise set to `Just (length - 1)` (last element). Subject to
-- validation.
listMoveBy :: Int -> List n e -> List n e
-- | Set the selected index for a list to the specified index, subject to
-- validation.
listMoveTo :: Int -> List n e -> List n e
-- | Move the list selected index up by one. (Moves the cursor up,
-- subtracts one from the index.)
listMoveUp :: List n e -> List n e
-- | Move the list selected index down by one. (Moves the cursor down, adds
-- one to the index.)
listMoveDown :: List n e -> List n e
-- | Move the list selected index by some (fractional) number of pages.
listMoveByPages :: (Ord n, RealFrac m) => m -> List n e -> EventM n (List n e)
-- | Move the list selected index up by one page.
listMovePageUp :: (Ord n) => List n e -> EventM n (List n e)
-- | Move the list selected index down by one page.
listMovePageDown :: (Ord n) => List n e -> EventM n (List n e)
-- | Insert an item into a list at the specified position.
listInsert :: Int -> e -> List n e -> List n e
-- | Remove an element from a list at the specified position.
listRemove :: Int -> List n e -> List n e
-- | Replace the contents of a list with a new set of elements and update
-- the new selected index. If the list is empty, empty selection is used
-- instead. Otherwise, if the specified selected index (via Just)
-- is not in the list bounds, zero is used instead.
listReplace :: Vector e -> Maybe Int -> List n e -> List n e
-- | Remove all elements from the list and clear the selection.
listClear :: List n e -> List n e
-- | Reverse the list. The element selected before the reversal will again
-- be the selected one.
listReverse :: List n e -> List n e
-- | Apply a function to the selected element. If no element is selected
-- the list is not modified.
listModify :: (e -> e) -> List n e -> List n e
-- | The top-level attribute used for the entire list.
listAttr :: AttrName
-- | The attribute used only for the currently-selected list item when the
-- list does not have focus. Extends listAttr.
listSelectedAttr :: AttrName
-- | The attribute used only for the currently-selected list item when the
-- list has focus. Extends listSelectedAttr.
listSelectedFocusedAttr :: AttrName
instance Brick.Widgets.Core.Named (Brick.Widgets.List.List n e) n
instance (GHC.Show.Show e, GHC.Show.Show n) => GHC.Show.Show (Brick.Widgets.List.List n e)
instance Data.Traversable.Traversable (Brick.Widgets.List.List n)
instance Data.Foldable.Foldable (Brick.Widgets.List.List n)
instance GHC.Base.Functor (Brick.Widgets.List.List n)
-- | This module is provided as a convenience to import the most important
-- parts of the API all at once. Note that the Haddock documentation for
-- this library is for reference usage; if you are looking for an
-- introduction or tutorial, see the README for links to plenty of
-- material!
module Brick
-- | NOTE: This API is experimental and will probably change. Please try it
-- out! Feedback is very much appreciated, and your patience in the face
-- of breaking API changes is also appreciated!
--
-- For a fuller introduction to this API, see the "Input Forms" section
-- of the Brick User Guide. Also see the demonstration programs for
-- examples of forms in action.
--
-- This module provides an input form API. This API allows you to
-- construct an input interface based on a data type of your choice. Each
-- input in the form corresponds to a field in your data type. This API
-- then automatically dispatches keyboard and mouse input events to each
-- form input field, manages rendering of the form, notifies the user
-- when a form field's value is invalid, and stores valid inputs in your
-- data type when possible.
--
-- This module provides the API to create forms, populate them with some
-- basic input field types, render forms, handle form events, and create
-- custom input field types.
--
-- A form has both a visual representation and a corresponding data
-- structure representing the latest valid values for that form (referred
-- to as the "state" of the form). A FormField is a single input
-- component in the form and a FormFieldState defines the linkage
-- between that visual input and the corresponding portion of the state
-- represented by that visual; there may be multiple FormFields
-- combined for a single FormFieldState (e.g. a radio button
-- sequence).
--
-- Also note that, by default, forms and their field inputs are
-- concatenated together in a vBox. This can be customized on a
-- per-field basis and for the entire form by using the functions
-- setFieldConcat and setFormConcat, respectively.
--
-- Bear in mind that for most uses, the FormField and
-- FormFieldState types will not be used directly. Instead, the
-- constructors for various field types (such as editTextField)
-- will be used instead.
module Brick.Forms
-- | A form: a sequence of input fields that manipulate the fields of an
-- underlying state that you choose.
--
-- Type variables are as follows:
--
--
-- - s - the data type of your choosing containing the values
-- manipulated by the fields in this form.
-- - e - your application's event type
-- - n - your application's resource name type
--
data Form s e n
-- | A form field state accompanied by the fields that manipulate that
-- state. The idea is that some record field in your form state has one
-- or more form fields that manipulate that value. This data type maps
-- that state field (using a lens into your state) to the form input
-- fields responsible for managing that state field, along with a current
-- value for that state field and an optional function to control how the
-- form inputs are rendered.
--
-- Most form fields will just have one input, such as text editors, but
-- others, such as radio button collections, will have many, which is why
-- this type supports more than one input corresponding to a state field.
--
-- Type variables are as follows:
--
--
-- - s - the data type containing the value manipulated by
-- these form fields.
-- - e - your application's event type
-- - n - your application's resource name type
--
data FormFieldState s e n
[FormFieldState] :: {formFieldState :: b The current state value associated with the field collection. Note that this type is existential. All form fields in the collection must validate to this type., formFieldLens :: Lens' s a A lens to extract and store a successfully-validated form input back into your form state., formFields :: [FormField a b e n] The form fields, in order, that the user will interact with to manipulate this state value., formFieldRenderHelper :: Widget n -> Widget n A helper function to augment the rendered representation of this collection of form fields. It receives the default representation and can augment it, for example, by adding a label on the left., formFieldConcat :: [Widget n] -> Widget n Concatenation function for this field's input renderings.} -> FormFieldState s e n
-- | A form field. This represents an interactive input field in the form.
-- Its user input is validated and thus converted into a type of your
-- choosing.
--
-- Type variables are as follows:
--
--
-- - a - the type of the field in your form state that this
-- field manipulates
-- - b - the form field's internal state type
-- - e - your application's event type
-- - n - your application's resource name type
--
data FormField a b e n
FormField :: n -> b -> Maybe a -> Bool -> Bool -> b -> Widget n -> BrickEvent n e -> b -> EventM n b -> FormField a b e n
-- | The name identifying this form field.
[formFieldName] :: FormField a b e n -> n
-- | A validation function converting this field's state into a value of
-- your choosing. Nothing indicates a validation failure. For
-- example, this might validate an Editor state value by parsing
-- its text contents s aan integer and return Maybe Int.
-- This is for pure avalue validation; if additional validation is
-- required a(e.g. via IO), use this field's state value in an
-- aexternal validation routine and use setFieldValid to afeed the
-- result back into the form.
[formFieldValidate] :: FormField a b e n -> b -> Maybe a
-- | Whether the field is valid according to an external validation source.
-- Defaults to always being True and can be set with
-- setFieldValid. The value of this field also affects the
-- behavior of allFieldsValid and getInvalidFields.
[formFieldExternallyValid] :: FormField a b e n -> Bool
-- | A function to render this form field. Parameters are whether the field
-- is currently focused, followed by the field state.
[formFieldRender] :: FormField a b e n -> Bool -> b -> Widget n
-- | An event handler for this field. This receives the event and the field
-- state and returns a new field state.
[formFieldHandleEvent] :: FormField a b e n -> BrickEvent n e -> b -> EventM n b
-- | Create a new form with the specified input fields and an initial form
-- state. The fields are initialized from the state using their state
-- lenses and the first form input is focused initially.
newForm :: [s -> FormFieldState s e n] -> s -> Form s e n
-- | The focus ring for the form, indicating which form field has input
-- focus.
formFocus :: Form s e n -> FocusRing n
-- | The current state of the form. Forms guarantee that only valid inputs
-- ever get stored in the state, and that after each input event on a
-- form field, if that field contains a valid state value then the value
-- is immediately saved to its corresponding field in this state value
-- using the form field's lens over s.
formState :: Form s e n -> s
-- | Dispatch an event to the appropriate form field and return a new form.
-- This handles the following events in this order:
--
--
-- - On Tab keypresses, this changes the focus to the next
-- field in the form.
-- - On Shift-Tab keypresses, this changes the focus to the
-- previous field in the form.
-- - On mouse button presses (regardless of button or modifier), the
-- focus is changed to the clicked form field and the event is forwarded
-- to the event handler for the clicked form field.
-- - On Left or Up, if the currently-focused field is
-- part of a collection (e.g. radio buttons), the previous entry in the
-- collection is focused.
-- - On Right or Down, if the currently-focused field
-- is part of a collection (e.g. radio buttons), the next entry in the
-- collection is focused.
-- - All other events are forwarded to the currently focused form
-- field.
--
--
-- In all cases where an event is forwarded to a form field, validation
-- of the field's input state is performed immediately after the event
-- has been handled. If the form field's input state succeeds validation
-- using the field's validator function, its value is immediately stored
-- in the form state using the form field's state lens. The external
-- validation flag is ignored during this step to ensure that external
-- validators have a chance to get the intermediate validated value.
handleFormEvent :: (Eq n) => BrickEvent n e -> Form s e n -> EventM n (Form s e n)
-- | Render a form.
--
-- For each form field, each input for the field is rendered using the
-- implementation provided by its FormField. The inputs are then
-- concatenated with the field's concatenation function (see
-- setFieldConcat) and are then augmented using the form field's
-- rendering augmentation function (see @@=). Fields with invalid
-- inputs (either due to built-in validator failure or due to external
-- validation failure via setFieldValid) will be displayed using
-- the invalidFormInputAttr attribute.
--
-- Finally, all of the resulting field renderings are concatenated with
-- the form's concatenation function (see setFormConcat).
renderForm :: (Eq n) => Form s e n -> Widget n
-- | Render a single form field collection. This is called internally by
-- renderForm but is exposed in cases where a form field state
-- needs to be rendered outside of a Form, so renderForm is
-- probably what you want.
renderFormFieldState :: (Eq n) => FocusRing n -> FormFieldState s e n -> Widget n
-- | Compose a new rendering augmentation function with the one in the form
-- field collection. For example, we might put a label on the left side
-- of a form field:
--
--
-- (str "Please check: " <+>) @@= checkboxField alive AliveField "Alive?"
--
--
-- This can also be used to add multiple augmentations and associates
-- right:
--
--
-- (withDefAttr someAttribute) @@=
-- (str "Please check: " <+>) @@=
-- checkboxField alive AliveField "Alive?"
--
(@@=) :: (Widget n -> Widget n) -> (s -> FormFieldState s e n) -> s -> FormFieldState s e n
infixr 5 @@=
-- | Returns whether all form fields in the form currently have valid
-- values according to the fields' validation functions. This is useful
-- when we need to decide whether the form state is up to date with
-- respect to the form input fields.
allFieldsValid :: Form s e n -> Bool
-- | Returns the resource names associated with all form input fields that
-- currently have invalid inputs. This is useful when we need to force
-- the user to repair invalid inputs before moving on from a form editing
-- session.
invalidFields :: Form s e n -> [n]
-- | Manually indicate that a field has invalid contents. This can be
-- useful in situations where validation beyond the form element's
-- validator needs to be performed and the result of that validation
-- needs to be fed back into the form state.
setFieldValid :: (Eq n) => Bool -> n -> Form s e n -> Form s e n
-- | Set a form's concatenation function.
setFormConcat :: ([Widget n] -> Widget n) -> Form s e n -> Form s e n
-- | Set a form field's concatenation function.
setFieldConcat :: ([Widget n] -> Widget n) -> FormFieldState s e n -> FormFieldState s e n
-- | A form field using an editor to edit a text value. Since the value is
-- free-form text, it is always valid.
--
-- This field responds to all events handled by editor, including
-- mouse events.
editTextField :: (Ord n, Show n) => Lens' s Text -> n -> Maybe Int -> s -> FormFieldState s e n
-- | A form field using a single-line editor to edit the Show
-- representation of a state field value of type a. This
-- automatically uses its Read instance to validate the input.
-- This field is mostly useful in cases where the user-facing
-- representation of a value matches the Show representation
-- exactly, such as with Int.
--
-- This field responds to all events handled by editor, including
-- mouse events.
editShowableField :: (Ord n, Show n, Read a, Show a) => Lens' s a -> n -> s -> FormFieldState s e n
-- | A form field using a single-line editor to edit a free-form text value
-- represented as a password. The value is always considered valid and is
-- always represented with one asterisk per password character.
--
-- This field responds to all events handled by editor, including
-- mouse events.
editPasswordField :: (Ord n, Show n) => Lens' s Text -> n -> s -> FormFieldState s e n
-- | A form field for selecting a single choice from a set of possible
-- choices. Each choice has an associated value and text label.
--
-- This field responds to Space keypresses to select a radio
-- button option and to mouse clicks.
radioField :: (Ord n, Show n, Eq a) => Lens' s a -> [(a, n, Text)] -> s -> FormFieldState s e n
-- | A form field for manipulating a boolean value. This represents
-- True as [X] label and False as [ ]
-- label.
--
-- This field responds to Space keypresses to toggle the
-- checkbox and to mouse clicks.
checkboxField :: (Ord n, Show n) => Lens' s Bool -> n -> Text -> s -> FormFieldState s e n
-- | A form field for using an editor to edit the text representation of a
-- value. The other editing fields in this module are special cases of
-- this function.
--
-- This field responds to all events handled by editor, including
-- mouse events.
editField :: (Ord n, Show n) => Lens' s a -> n -> Maybe Int -> (a -> Text) -> ([Text] -> Maybe a) -> ([Text] -> Widget n) -> (Widget n -> Widget n) -> s -> FormFieldState s e n
-- | The namespace for the other form attributes.
formAttr :: AttrName
-- | The attribute for form input fields with invalid values.
invalidFormInputAttr :: AttrName
-- | The attribute for form input fields that have the focus.
focusedFormInputAttr :: AttrName
-- | This module provides an API for "marking up" text with arbitrary
-- values. A piece of markup can then be converted to a list of pairs
-- representing the sequences of characters assigned the same markup
-- value.
--
-- This interface is experimental. Don't use this for your full-file
-- syntax highlighter just yet!
module Data.Text.Markup
-- | Markup with metadata type a assigned to each character.
data Markup a
-- | Convert markup to a list of lines. Each line is represented by a list
-- of pairs in which each pair contains the longest subsequence of
-- characters having the same metadata.
markupToList :: (Eq a) => Markup a -> [[(Text, a)]]
-- | Set the metadata for a range of character positions in a piece of
-- markup. This is useful for, e.g., syntax highlighting.
markupSet :: (Eq a) => (Int, Int) -> a -> Markup a -> Markup a
-- | Convert a list of text and metadata pairs into markup.
fromList :: [(Text, a)] -> Markup a
-- | Build markup from text with the default metadata.
fromText :: (Monoid a) => Text -> Markup a
-- | Extract the text from markup, discarding the markup metadata.
toText :: (Eq a) => Markup a -> Text
-- | Build a piece of markup; assign the specified metadata to every
-- character in the specified text.
(@@) :: Text -> a -> Markup a
instance GHC.Show.Show a => GHC.Show.Show (Data.Text.Markup.Markup a)
instance GHC.Base.Semigroup (Data.Text.Markup.Markup a)
instance GHC.Base.Monoid (Data.Text.Markup.Markup a)
instance GHC.Base.Monoid a => Data.String.IsString (Data.Text.Markup.Markup a)
-- | This module provides an API for turning "markup" values into widgets.
-- This module uses the Data.Text.Markup interface in this package
-- to assign attributes to substrings in a text string; to manipulate
-- markup using (for example) syntax highlighters, see that module.
module Brick.Markup
-- | Markup with metadata type a assigned to each character.
data Markup a
-- | Build a widget from markup.
markup :: (Eq a, GetAttr a) => Markup a -> Widget n
-- | Build a piece of markup from text with an assigned attribute name.
-- When the markup is rendered, the attribute name will be looked up in
-- the rendering context's AttrMap to determine the attribute to
-- use for this piece of text.
(@?) :: Text -> AttrName -> Markup AttrName
-- | A type class for types that provide access to an attribute in the
-- rendering monad. You probably won't need to instance this.
class GetAttr a
-- | Where to get the attribute for this attribute metadata.
getAttr :: GetAttr a => a -> RenderM n Attr
instance Brick.Markup.GetAttr Graphics.Vty.Attributes.Attr
instance Brick.Markup.GetAttr Brick.AttrMap.AttrName