-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A declarative terminal user interface library
--
-- Write terminal user interfaces (TUIs) 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.73
-- | 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 successively
-- 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. This is functionally equivalent to AttrMap attr
-- [].
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 along with its style settings.
-- If the attribute name is empty, the map's default attribute is
-- returned. If the attribute name is non-empty, every 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. As attributes are
-- merged, styles are also merged. If a more specific attribute name
-- introduces a style (underline, say) and a less specific attribute name
-- introduces an additional style (bold, say) then the final result will
-- include both styles.
--
-- 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 Control.DeepSeq.NFData Brick.AttrMap.AttrName
instance GHC.Generics.Generic Brick.AttrMap.AttrName
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 Control.DeepSeq.NFData Brick.AttrMap.AttrMap
instance GHC.Generics.Generic Brick.AttrMap.AttrMap
instance GHC.Show.Show Brick.AttrMap.AttrMap
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 ()
-- | Attempts to write a value to a BChan. If the channel has
-- room, the value is written and this returns True. Otherwise
-- this returns False and returns immediately.
writeBChanNonBlocking :: BChan a -> a -> IO Bool
-- | 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, strikethrough,
-- 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 Control.DeepSeq.NFData Brick.Themes.CustomAttr
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 Control.DeepSeq.NFData Brick.Themes.ThemeDocumentation
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 Control.DeepSeq.NFData Brick.Themes.Theme
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.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
-- style.
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 Control.DeepSeq.NFData Brick.Widgets.Border.Style.BorderStyle
instance GHC.Generics.Generic Brick.Widgets.Border.Style.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 Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.IMap.Run a)
instance GHC.Generics.Generic (Data.IMap.Run 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 Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.IMap.IMap a)
instance GHC.Generics.Generic (Data.IMap.IMap a)
instance GHC.Read.Read a => GHC.Read.Read (Data.IMap.IMap a)
instance GHC.Base.Functor Data.IMap.IMap
instance GHC.Show.Show a => GHC.Show.Show (Data.IMap.IMap 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_acLe. Lens' (Edges a_acLe) a_acLe
eBottomL :: forall a_acLe. Lens' (Edges a_acLe) a_acLe
eRightL :: forall a_acLe. Lens' (Edges a_acLe) a_acLe
eLeftL :: forall a_acLe. Lens' (Edges a_acLe) a_acLe
-- | An empty BorderMap that does not track any points.
empty :: BorderMap a
-- | An empty BorderMap that tracks the same points as the input.
clear :: BorderMap a -> BorderMap b
-- | 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 Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Brick.BorderMap.BorderMap a)
instance GHC.Generics.Generic (Brick.BorderMap.BorderMap a)
instance GHC.Read.Read a => GHC.Read.Read (Brick.BorderMap.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 -> !Bool -> CursorLocation n
-- | The location
[cursorLocation] :: CursorLocation n -> !Location
-- | The name of the widget associated with the location
[cursorLocationName] :: CursorLocation n -> !Maybe n
-- | Whether the cursor should actually be visible
[cursorLocationVisible] :: CursorLocation n -> !Bool
cursorLocationL :: forall n_awEv. Lens' (CursorLocation n_awEv) Location
cursorLocationNameL :: forall n_awEv n_ayOD. Lens (CursorLocation n_awEv) (CursorLocation n_ayOD) (Maybe n_awEv) (Maybe n_ayOD)
-- | Describes the state of a viewport as it appears as its most recent
-- rendering.
data Viewport
VP :: Int -> Int -> DisplayRegion -> 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 size of the contents of the viewport.
[_vpContentSize] :: 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
vpContentSize :: Lens' Viewport DisplayRegion
-- | Orientations for vertical scroll bars.
data VScrollBarOrientation
OnLeft :: VScrollBarOrientation
OnRight :: VScrollBarOrientation
-- | Orientations for horizontal scroll bars.
data HScrollBarOrientation
OnBottom :: HScrollBarOrientation
OnTop :: HScrollBarOrientation
-- | A scroll bar renderer.
data ScrollbarRenderer n
ScrollbarRenderer :: Widget n -> Widget n -> Widget n -> Widget n -> ScrollbarRenderer n
-- | How to render the body of the scroll bar. This should provide a widget
-- that expands in whatever direction(s) this renderer will be used for.
-- So, for example, if this was used to render vertical scroll bars, this
-- widget would need to be one that expands vertically such as
-- fill. The same goes for the trough widget.
[renderScrollbar] :: ScrollbarRenderer n -> Widget n
-- | How to render the "trough" of the scroll bar (the area to either side
-- of the scroll bar body). This should expand as described in the
-- documentation for the scroll bar field.
[renderScrollbarTrough] :: ScrollbarRenderer n -> Widget n
-- | How to render the handle that appears at the top or left of the
-- scrollbar. The result should be at most one row high for horizontal
-- handles and one column wide for vertical handles.
[renderScrollbarHandleBefore] :: ScrollbarRenderer n -> Widget n
-- | How to render the handle that appears at the bottom or right of the
-- scrollbar. The result should be at most one row high for horizontal
-- handles and one column wide for vertical handles.
[renderScrollbarHandleAfter] :: ScrollbarRenderer n -> Widget n
-- | Clickable elements of a scroll bar.
data ClickableScrollbarElement
-- | The handle at the beginning (left/top) of the scroll bar.
SBHandleBefore :: ClickableScrollbarElement
-- | The handle at the end (right/bottom) of the scroll bar.
SBHandleAfter :: ClickableScrollbarElement
-- | The scroll bar itself.
SBBar :: ClickableScrollbarElement
-- | The trough before the scroll bar.
SBTroughBefore :: ClickableScrollbarElement
-- | The trough after the scroll bar.
SBTroughAfter :: ClickableScrollbarElement
-- | 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 n) (State (RenderState n)) a
-- | Get the current rendering context.
getContext :: RenderM n (Context n)
-- | 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 n
-- | The rendering context's current drawing attribute.
attrL :: forall r n. Getting r (Context n) Attr
availWidthL :: forall n_awEq. Lens' (Context n_awEq) Int
availHeightL :: forall n_awEq. Lens' (Context n_awEq) Int
windowWidthL :: forall n_awEq. Lens' (Context n_awEq) Int
windowHeightL :: forall n_awEq. Lens' (Context n_awEq) Int
ctxVScrollBarOrientationL :: forall n_awEq. Lens' (Context n_awEq) (Maybe VScrollBarOrientation)
ctxVScrollBarRendererL :: forall n_awEq. Lens' (Context n_awEq) (Maybe (ScrollbarRenderer n_awEq))
ctxHScrollBarOrientationL :: forall n_awEq. Lens' (Context n_awEq) (Maybe HScrollBarOrientation)
ctxHScrollBarRendererL :: forall n_awEq. Lens' (Context n_awEq) (Maybe (ScrollbarRenderer n_awEq))
ctxAttrMapL :: forall n_awEq. Lens' (Context n_awEq) AttrMap
ctxAttrNameL :: forall n_awEq. Lens' (Context n_awEq) AttrName
ctxBorderStyleL :: forall n_awEq. Lens' (Context n_awEq) BorderStyle
ctxDynBordersL :: forall n_awEq. Lens' (Context n_awEq) 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) -> Extent n
[extentName] :: Extent n -> n
[extentUpperLeft] :: Extent n -> Location
[extentSize] :: Extent n -> (Int, Int)
imageL :: forall n_awEu. Lens' (Result n_awEu) Image
cursorsL :: forall n_awEu. Lens' (Result n_awEu) [CursorLocation n_awEu]
visibilityRequestsL :: forall n_awEu. Lens' (Result n_awEu) [VisibilityRequest]
extentsL :: forall n_awEu. Lens' (Result n_awEu) [Extent n_awEu]
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
-- | A more general version of suffixLenses that allows
-- customization of the lens-building rules and allows customization of
-- the suffix.
suffixLensesWith :: String -> LensRules -> Name -> DecsQ
bordersL :: forall n_awEu. Lens' (Result n_awEu) (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_acLe. Lens' (Edges a_acLe) a_acLe
eBottomL :: forall a_acLe. Lens' (Edges a_acLe) a_acLe
eRightL :: forall a_acLe. Lens' (Edges a_acLe) a_acLe
eLeftL :: forall a_acLe. Lens' (Edges a_acLe) a_acLe
-- | Widget size policies. These policies communicate how a widget uses
-- space when being rendered. These policies influence rendering order
-- and space allocation in the box layout algorithm for hBox and
-- vBox.
data Size
-- | Widgets advertising this size policy should take up the same amount of
-- space no matter how much they are given, i.e. their size depends on
-- their contents alone rather than on the size of the rendering area.
Fixed :: Size
-- | Widgets advertising this size policy must 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
data RenderState n
instance Control.Monad.Fail.MonadFail (Brick.Types.EventM n)
instance Control.Monad.Catch.MonadMask (Brick.Types.EventM n)
instance Control.Monad.Catch.MonadCatch (Brick.Types.EventM n)
instance Control.Monad.Catch.MonadThrow (Brick.Types.EventM n)
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)
instance Brick.Types.Internal.TerminalLocation (Brick.Types.Internal.CursorLocation 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 input text
-- should not contain escape sequences or carriage returns.
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 escape sequences or carriage returns.
--
-- Unlike txt, this is greedy horizontally.
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 escape sequences or carriage returns.
--
-- Unlike txt, this is greedy horizontally.
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 input
-- string should not contain escape sequences or carriage returns.
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 escape sequences or carriage returns.
--
-- Unlike str, this is greedy horizontally.
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 escape sequences or carriage returns.
--
-- Unlike str, this is greedy horizontally.
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
-- percentage of available width, as a value between 0 and 100 inclusive.
-- Values outside the valid range will be clamped to the range endpoints.
-- This is important for constraining the horizontal growth of
-- otherwise-greedy widgets. This is non-greedy horizontally and defers
-- to the limited widget vertically.
hLimitPercent :: 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
-- | Limit the space available to the specified widget to the specified
-- percentage of available height, as a value between 0 and 100
-- inclusive. Values outside the valid range will be clamped to the range
-- endpoints. This is important for constraining the vertical growth of
-- otherwise-greedy widgets. This is non-greedy vertically and defers to
-- the limited widget horizontally.
vLimitPercent :: 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 used while rendering the specified widget
-- (and any sub-widgets): set its new *default* attribute (i.e. the
-- attribute components that will be applied if not overridden by any
-- more specific attributes) to the one that we get by looking up the
-- specified attribute name in the map.
--
-- For example:
--
--
-- ...
-- appAttrMap = attrMap (white on blue) [ ("highlight", fg yellow)
-- , ("warning", bg magenta)
-- , ("good", white on green) ]
-- ...
--
-- renderA :: (String, String) -> [Widget n]
-- renderA (a,b) = hBox [ withAttr "good" (str a)
-- , str " is "
-- , withAttr "highlight" (str b) ]
--
-- render1 = renderA (Brick, "fun")
-- render2 = withDefAttr "warning" render1
--
--
-- In the above, render1 will show "Brick is fun" where the first word is
-- white on a green background, the middle word is white on a blue
-- background, and the last word is yellow on a blue background. However,
-- render2 will show the first word in the same colors but the middle
-- word will be shown in whatever the terminal's normal foreground is on
-- a magenta background, and the third word will be yellow on a magenta
-- background.
withDefAttr :: AttrName -> Widget n -> Widget n
-- | Update the attribute map while rendering the specified widget: set the
-- map's default attribute to the one that we get by applying the
-- specified function to the current map's default attribute. This is a
-- variant of withDefAttr; see the latter for more information.
modifyDefAttr :: (Attr -> Attr) -> Widget n -> Widget n
-- | When drawing the specified widget, set the attribute used for drawing
-- to the one with the specified name. Note that the widget may use
-- further calls to withAttr to change the active drawing
-- attribute, so this only takes effect if nothing in the specified
-- widget invokes withAttr. If you 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.
--
-- For example:
--
--
-- appAttrMap = attrMap (white on blue) [ ("highlight", fg yellow)
-- , ("warning", bg magenta)
-- ]
--
-- renderA :: (String, String) -> [Widget n]
-- renderA (a,b) = hBox [ str a
-- , str " is "
-- , withAttr "highlight" (str b)
-- ]
--
-- render1 = renderA (Brick, "fun")
-- render2 = withAttr "warning" render1
--
--
-- In the example above, render1 will show Brick is fun
-- where the first two words are white on a blue background and the last
-- word is yellow on a blue background. However, render2 will
-- show the first two words in white on magenta although the last word is
-- still rendered in yellow on blue.
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. This means that the attribute lookups will behave as
-- if they all used the name specified here. That further means that the
-- resolved attribute will still inherit from its parent entry in the
-- attribute map as would normally be the case. If you want to have more
-- control over the resulting attribute, consider modifyDefAttr.
--
-- For example:
--
--
-- ...
-- appAttrMap = attrMap (white on blue) [ ("highlight", fg yellow)
-- , ("notice", fg red) ]
-- ...
--
-- renderA :: (String, String) -> [Widget n]
-- renderA (a,b) = hBox [ withAttr "highlight" (str a)
-- , str " is "
-- , withAttr "highlight" (str b)
-- ]
--
-- render1 = renderA (Brick, "fun")
-- render2 = forceAttr "notice" render1
--
--
-- In the above, render1 will show "Brick is fun" where the first and
-- last words are yellow on a blue background and the middle word is
-- white on a blue background. However, render2 will show all words in
-- red on a blue background. In both versions, the middle word will be in
-- white on a blue background.
forceAttr :: AttrName -> Widget n -> Widget n
-- | Override the lookup of the attribute name targetName to
-- return the attribute value associated with fromName when
-- rendering the specified widget.
--
-- For example:
--
--
-- appAttrMap = attrMap (white on blue) [ ("highlight", fg yellow)
-- , ("notice", fg red)
-- ]
--
-- renderA :: (String, String) -> [Widget n]
-- renderA (a, b) = str a + str " is " + withAttr "highlight" (str b)
--
-- render1 = withAttr "notice" $ renderA (Brick, "fun")
-- render2 = overrideAttr "highlight" "notice" render1
--
--
-- In the example above, render1 will show Brick is fun
-- where the first two words are red on a blue background, but
-- fun is yellow on a blue background. However, render2
-- will show all three words in red on a blue background.
overrideAttr :: AttrName -> AttrName -> Widget n -> Widget n
-- | While rendering the specified widget, use a transformed version of the
-- current attribute map. This is a very general function with broad
-- capabilities: you probably want a more specific function such as
-- withDefAttr or withAttr.
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
-- | When rendering the specified widget, also register a cursor
-- positioning request using the specified name and location. The cursor
-- will only be positioned but not made visible.
putCursor :: 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
-- | Given a widget, translate it to position it relative to the upper-left
-- coordinates of a reported extent with the specified positioning
-- offset. If the specified name has no reported extent, this just draws
-- the specified widget with no special positioning.
--
-- This is only useful for positioning something in a higher layer
-- relative to a reported extent in a lower layer. Any other use is
-- likely to result in the specified widget being rendered as-is with no
-- translation. This is because this function relies on information about
-- lower layer renderings in order to work; using it with a resource name
-- that wasn't rendered in a lower layer will result in this being
-- equivalent to id.
--
-- For example, if you have two layers topLayer and
-- bottomLayer, then a widget drawn in bottomLayer with
-- reportExtent Foo can be used to relatively position a widget
-- in topLayer with topLayer = relativeTo Foo ....
relativeTo :: Ord n => n -> 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
-- | Crop the specified widget to the specified size from the left. Defers
-- to the cropped widget for growth policy.
cropLeftTo :: Int -> Widget n -> Widget n
-- | Crop the specified widget to the specified size from the right. Defers
-- to the cropped widget for growth policy.
cropRightTo :: Int -> Widget n -> Widget n
-- | Crop the specified widget to the specified size from the top. Defers
-- to the cropped widget for growth policy.
cropTopTo :: Int -> Widget n -> Widget n
-- | Crop the specified widget to the specified size from the bottom.
-- Defers to the cropped widget for growth policy.
cropBottomTo :: Int -> Widget n -> Widget n
-- | Render the specified widget and record its rendering extent using the
-- specified name (see also lookupExtent).
--
-- This function is the counterpart to makeVisible; any
-- visibility requests made with makeVisible must have a
-- corresponding reportExtent in order to work. The
-- clickable function will also work for this purpose to tell the
-- renderer about the clickable region.
reportExtent :: Ord n => n -> Widget n -> Widget n
-- | Request mouse click events on the specified widget.
--
-- Regions used with clickable can be scrolled into view with
-- makeVisible.
clickable :: Ord n => 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.
--
-- This function can automatically render vertical and horizontal scroll
-- bars if desired. To enable scroll bars, wrap your call to
-- viewport with a call to withVScrollBars and/or
-- withHScrollBars. If you don't like the appearance of the
-- resulting scroll bars (defaults: verticalScrollbarRenderer and
-- horizontalScrollbarRenderer), you can customize how they are
-- drawn by making your own ScrollbarRenderer and using
-- withVScrollBarRenderer and/or withHScrollBarRenderer.
-- Note that when you enable scrollbars, the content of your viewport
-- will lose one column of available space if vertical scroll bars are
-- enabled and one row of available space if horizontal scroll bars are
-- enabled.
--
-- 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.
--
-- Some caution should be advised when using this function. The viewport
-- renders its contents anew each time the viewport is drawn; in many
-- cases this is prohibitively expensive, and viewports should not be
-- used to display large contents for scrolling. This function is best
-- used when the contents are not too large OR when the contents are
-- large and render-cacheable.
--
-- Also, be aware that there is a rich API for accessing viewport
-- information from within the EventM monad; check the docs for
-- Brick.Main to learn more about ways to get information about
-- viewports after they're drawn.
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)
-- | If the specified resource name has an entry in the rendering cache,
-- use the rendered version from the cache. If not, render the specified
-- widget and update the cache with the result.
--
-- To ensure that mouse events are emitted correctly for cached widgets,
-- in addition to the rendered widget, we also cache (the names of) any
-- clickable extents that were rendered and restore that when utilizing
-- the cache.
--
-- See also invalidateCacheEntry.
cached :: Ord n => n -> Widget n -> Widget n
-- | Enable vertical scroll bars on all viewports in the specified widget
-- and draw them with the specified orientation.
withVScrollBars :: VScrollBarOrientation -> Widget n -> Widget n
-- | Enable horizontal scroll bars on all viewports in the specified widget
-- and draw them with the specified orientation.
withHScrollBars :: HScrollBarOrientation -> Widget n -> Widget n
-- | Enable mouse click reporting on horizontal scroll bars in the
-- specified widget. This must be used with withHScrollBars. The
-- provided function is used to build a resource name containing the
-- scroll bar element clicked and the viewport name associated with the
-- scroll bar. It is usually a data constructor of the n type.
withClickableHScrollBars :: (ClickableScrollbarElement -> n -> n) -> Widget n -> Widget n
-- | Enable mouse click reporting on vertical scroll bars in the specified
-- widget. This must be used with withVScrollBars. The provided
-- function is used to build a resource name containing the scroll bar
-- element clicked and the viewport name associated with the scroll bar.
-- It is usually a data constructor of the n type.
withClickableVScrollBars :: (ClickableScrollbarElement -> n -> n) -> Widget n -> Widget n
-- | Enable scroll bar handles on all vertical scroll bars in the specified
-- widget. Handles appear at the ends of the scroll bar, representing the
-- "handles" that are typically clickable in graphical UIs to move the
-- scroll bar incrementally. Vertical scroll bars are also clickable if
-- mouse mode is enabled and if withClickableVScrollBars is used.
--
-- This will only have an effect if withVScrollBars is also
-- called.
withVScrollBarHandles :: Widget n -> Widget n
-- | Enable scroll bar handles on all horizontal scroll bars in the
-- specified widget. Handles appear at the ends of the scroll bar,
-- representing the "handles" that are typically clickable in graphical
-- UIs to move the scroll bar incrementally. Horizontal scroll bars are
-- also clickable if mouse mode is enabled and if
-- withClickableHScrollBars is used.
--
-- This will only have an effect if withHScrollBars is also
-- called.
withHScrollBarHandles :: Widget n -> Widget n
-- | Render vertical viewport scroll bars in the specified widget with the
-- specified renderer. This is only needed if you want to override the
-- use of the default renderer, verticalScrollbarRenderer.
withVScrollBarRenderer :: ScrollbarRenderer n -> Widget n -> Widget n
-- | Render horizontal viewport scroll bars in the specified widget with
-- the specified renderer. This is only needed if you want to override
-- the use of the default renderer, horizontalScrollbarRenderer.
withHScrollBarRenderer :: ScrollbarRenderer n -> Widget n -> Widget n
-- | A scroll bar renderer.
data ScrollbarRenderer n
ScrollbarRenderer :: Widget n -> Widget n -> Widget n -> Widget n -> ScrollbarRenderer n
-- | How to render the body of the scroll bar. This should provide a widget
-- that expands in whatever direction(s) this renderer will be used for.
-- So, for example, if this was used to render vertical scroll bars, this
-- widget would need to be one that expands vertically such as
-- fill. The same goes for the trough widget.
[renderScrollbar] :: ScrollbarRenderer n -> Widget n
-- | How to render the "trough" of the scroll bar (the area to either side
-- of the scroll bar body). This should expand as described in the
-- documentation for the scroll bar field.
[renderScrollbarTrough] :: ScrollbarRenderer n -> Widget n
-- | How to render the handle that appears at the top or left of the
-- scrollbar. The result should be at most one row high for horizontal
-- handles and one column wide for vertical handles.
[renderScrollbarHandleBefore] :: ScrollbarRenderer n -> Widget n
-- | How to render the handle that appears at the bottom or right of the
-- scrollbar. The result should be at most one row high for horizontal
-- handles and one column wide for vertical handles.
[renderScrollbarHandleAfter] :: ScrollbarRenderer n -> Widget n
-- | The default renderer for vertical viewport scroll bars. Override with
-- withVScrollBarRenderer.
verticalScrollbarRenderer :: ScrollbarRenderer n
-- | The default renderer for horizontal viewport scroll bars. Override
-- with withHScrollBarRenderer.
horizontalScrollbarRenderer :: ScrollbarRenderer n
-- | The base attribute for scroll bars.
scrollbarAttr :: AttrName
-- | The attribute for scroll bar troughs. This attribute is a
-- specialization of scrollbarAttr.
scrollbarTroughAttr :: AttrName
-- | The attribute for scroll bar handles. This attribute is a
-- specialization of scrollbarAttr.
scrollbarHandleAttr :: AttrName
-- | Build a vertical scroll bar using the specified render and settings.
--
-- You probably don't want to use this directly; instead, use
-- viewport, withVScrollBars, and, if needed,
-- withVScrollBarRenderer. This is exposed so that if you want
-- to render a scroll bar of your own, you can do so outside the
-- viewport context.
verticalScrollbar :: Ord n => ScrollbarRenderer n -> n -> Maybe (ClickableScrollbarElement -> n -> n) -> Bool -> Int -> Int -> Int -> Widget n
-- | Build a horizontal scroll bar using the specified render and settings.
--
-- You probably don't want to use this directly; instead, use
-- viewport, withHScrollBars, and, if needed,
-- withHScrollBarRenderer. This is exposed so that if you want
-- to render a scroll bar of your own, you can do so outside the
-- viewport context.
horizontalScrollbar :: Ord n => ScrollbarRenderer n -> n -> Maybe (ClickableScrollbarElement -> n -> n) -> Bool -> Int -> Int -> Int -> 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:
--
--
-- - Meta-<: go to beginning of file
-- - Meta->: go to end of file
-- - Ctrl-a, Home: go to beginning of line
-- - Ctrl-e, End: go to end of line
-- - Ctrl-d, Del: delete character at cursor position
-- - Meta-d: delete word 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
-- - Ctrl-t: transpose character before cursor with the one at cursor
-- position
-- - Meta-b: move one word to the left
-- - Ctrl-b: move one character to the left
-- - Meta-f: move one word to the right
-- - Ctrl-f: move one character to the right
-- - Arrow keys: move cursor
-- - Enter: break the current line at the cursor position
-- - Paste: Bracketed Pastes from the terminal will be pasted, provided
-- the incoming data is UTF-8-encoded.
--
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]
-- | Get the cursor position of the editor (row, column).
getCursorPosition :: Editor t n -> (Int, Int)
handleEditorEvent :: (Eq n, DecodeUtf8 t, Eq t, GenericTextZipper t) => BrickEvent n e -> 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_a19Y9 n_a19Ya t_a19YO. Lens (Editor t_a19Y9 n_a19Ya) (Editor t_a19YO n_a19Ya) (TextZipper t_a19Y9) (TextZipper t_a19YO)
-- | 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
-- | Values that can be constructed by decoding bytestrings in UTF-8
-- encoding.
class DecodeUtf8 t
-- | Decode a bytestring assumed to be text in UTF-8 encoding. If the
-- decoding fails, return Left. This must not raise exceptions.
decodeUtf8 :: DecodeUtf8 t => ByteString -> Either String t
instance Brick.Widgets.Edit.DecodeUtf8 Data.Text.Internal.Text
instance Brick.Widgets.Edit.DecodeUtf8 GHC.Base.String
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 table widget that can draw other widgets in a
-- table layout, draw borders between rows and columns, and allow
-- configuration of row and column alignment. To get started, see
-- table.
module Brick.Widgets.Table
-- | A table data structure for widgets of type Widget n.
-- Create a table with table.
data Table n
-- | Column alignment modes. Use these modes with the alignment functions
-- in this module to configure column alignment behavior.
data ColumnAlignment
-- | Align all cells to the left.
AlignLeft :: ColumnAlignment
-- | Center the content horizontally in all cells in the column.
AlignCenter :: ColumnAlignment
-- | Align all cells to the right.
AlignRight :: ColumnAlignment
-- | Row alignment modes. Use these modes with the alignment functions in
-- this module to configure row alignment behavior.
data RowAlignment
-- | Align all cells to the top.
AlignTop :: RowAlignment
-- | Center the content vertically in all cells in the row.
AlignMiddle :: RowAlignment
-- | Align all cells to the bottom.
AlignBottom :: RowAlignment
-- | A table creation exception.
data TableException
-- | Rows did not all have the same number of cells.
TEUnequalRowSizes :: TableException
-- | Some cells in the table did not use the Fixed size policy for
-- both horizontal and vertical sizing.
TEInvalidCellSizePolicy :: TableException
-- | Construct a new table.
--
-- The argument is the list of rows with the topmost row first, with each
-- element of the argument list being the contents of the cells in in
-- each column of the respective row, with the leftmost cell first.
--
-- Each row's height is determined by the height of the tallest cell in
-- that row, and each column's width is determined by the width of the
-- widest cell in that column. This means that control over row and
-- column dimensions is a matter of controlling the size of the
-- individual cells, such as by wrapping cell contents in padding,
-- fill and hLimit or vLimit, etc. This also means
-- that it is not necessary to explicitly set the width of most table
-- cells because the table will determine the per-row and per-column
-- dimensions by looking at the largest cell contents. In particular,
-- this means that the table's alignment logic only has an effect when a
-- given cell's contents are smaller than the maximum for its row and
-- column, thus giving the table some way to pad the contents to result
-- in the desired alignment.
--
-- By default:
--
--
-- - All columns are left-aligned. Use the alignment functions in this
-- module to change that behavior.
-- - All rows are top-aligned. Use the alignment functions in this
-- module to change that behavior.
-- - The table will draw borders between columns, between rows, and
-- around the outside of the table. Border-drawing behavior can be
-- configured with the API in this module. Note that tables always draw
-- with joinBorders enabled. If a cell's contents has smart
-- borders but you don't want those borders to connect to the surrounding
-- table borders, wrap the cell's contents with
-- freezeBorders.
--
--
-- All cells of all rows MUST use the Fixed growth policy for both
-- horizontal and vertical growth. If the argument list contains any
-- cells that use the Greedy policy, this function will raise a
-- TableException.
--
-- All rows MUST have the same number of cells. If not, this function
-- will raise a TableException.
table :: [[Widget n]] -> Table n
-- | Align the specified column to the left. The argument is the column
-- index, starting with zero. Silently does nothing if the index is out
-- of range.
alignLeft :: Int -> Table n -> Table n
-- | Align the specified column to the right. The argument is the column
-- index, starting with zero. Silently does nothing if the index is out
-- of range.
alignRight :: Int -> Table n -> Table n
-- | Align the specified column to center. The argument is the column
-- index, starting with zero. Silently does nothing if the index is out
-- of range.
alignCenter :: Int -> Table n -> Table n
-- | Align the specified row to the top. The argument is the row index,
-- starting with zero. Silently does nothing if the index is out of
-- range.
alignTop :: Int -> Table n -> Table n
-- | Align the specified row to the middle. The argument is the row index,
-- starting with zero. Silently does nothing if the index is out of
-- range.
alignMiddle :: Int -> Table n -> Table n
-- | Align the specified row to bottom. The argument is the row index,
-- starting with zero. Silently does nothing if the index is out of
-- range.
alignBottom :: Int -> Table n -> Table n
-- | Set the alignment for the specified column index (starting at zero).
-- Silently does nothing if the index is out of range.
setColAlignment :: ColumnAlignment -> Int -> Table n -> Table n
-- | Set the alignment for the specified row index (starting at zero).
-- Silently does nothing if the index is out of range.
setRowAlignment :: RowAlignment -> Int -> Table n -> Table n
-- | Set the default column alignment for columns with no explicitly
-- configured alignment.
setDefaultColAlignment :: ColumnAlignment -> Table n -> Table n
-- | Set the default row alignment for rows with no explicitly configured
-- alignment.
setDefaultRowAlignment :: RowAlignment -> Table n -> Table n
-- | Configure whether the table draws a border on its exterior.
surroundingBorder :: Bool -> Table n -> Table n
-- | Configure whether the table draws borders between its rows.
rowBorders :: Bool -> Table n -> Table n
-- | Configure whether the table draws borders between its columns.
columnBorders :: Bool -> Table n -> Table n
-- | Render the table.
renderTable :: Table n -> Widget n
instance GHC.Read.Read Brick.Widgets.Table.ColumnAlignment
instance GHC.Show.Show Brick.Widgets.Table.ColumnAlignment
instance GHC.Classes.Eq Brick.Widgets.Table.ColumnAlignment
instance GHC.Read.Read Brick.Widgets.Table.RowAlignment
instance GHC.Show.Show Brick.Widgets.Table.RowAlignment
instance GHC.Classes.Eq Brick.Widgets.Table.RowAlignment
instance GHC.Read.Read Brick.Widgets.Table.TableException
instance GHC.Show.Show Brick.Widgets.Table.TableException
instance GHC.Classes.Eq Brick.Widgets.Table.TableException
instance GHC.Exception.Type.Exception Brick.Widgets.Table.TableException
-- | 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_a1fTP a_a1fUt. Lens (Dialog a_a1fTP) (Dialog a_a1fUt) [(String, a_a1fTP)] [(String, a_a1fUt)]
dialogSelectedIndexL :: forall a_a1fTP. Lens' (Dialog a_a1fTP) (Maybe Int)
dialogWidthL :: forall a_a1fTP. Lens' (Dialog a_a1fTP) Int
dialogTitleL :: forall a_a1fTP. Lens' (Dialog a_a1fTP) (Maybe String)
-- | This module provides a type and functions for handling focus rings of
-- values.
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
-- empty, 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
-- | Get the size of the FocusRing.
focusRingLength :: FocusRing n -> Int
-- | Return all of the entries in the focus ring, starting with the
-- currently-focused entry and wrapping around the ring.
--
-- For example, if a ring contains A, B, C, and D, and the current entry
-- is B, the result will be [B, C, D, A].
focusRingToList :: FocusRing n -> [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
-- provided in an App and then the App is provided to
-- one of the various main functions in this module. An application
-- App s e n 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 s is the type of application state to be provided by you
-- and iteratively modified by event handlers. The resource name type
-- n is the type of names you can assign to rendering resources
-- such as viewports and cursor locations. Your application must define
-- this type.
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,
-- continueWithoutRedraw, 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. Returns the final application state after the
-- application halts.
--
-- Note that this function guarantees that the terminal input state prior
-- to the first Vty initialization is the terminal input state that is
-- restored on shutdown (regardless of exceptions).
customMain :: Ord n => Vty -> IO Vty -> Maybe (BChan e) -> App s e n -> s -> IO s
-- | Like customMain, except the last Vty handle used by the
-- application is returned without being shut down with shutdown.
-- This allows the caller to re-use the Vty handle for something
-- else, such as another Brick application.
customMainWithVty :: Ord n => Vty -> IO Vty -> Maybe (BChan e) -> App s e n -> s -> IO (s, Vty)
-- | 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)
-- | Continue running the event loop with the specified application state
-- without redrawing the screen. This is faster than continue
-- because it skips the redraw, but the drawback is that you need to be
-- really sure that you don't want a screen redraw. If your state changed
-- in a way that needs to be reflected on the screen, use
-- continue. This function is for cases where you know that you
-- did something that won't have an impact on the screen state and you
-- want to save on redraw cost.
continueWithoutRedraw :: 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, empty the rendering cache, redraw the application from
-- the new state, and resume the event loop.
--
-- Note that any changes made to the terminal's input state are ignored
-- when Brick resumes execution and are not preserved in the final
-- terminal input state after the Brick application returns the terminal
-- to the user.
suspendAndResume :: IO s -> EventM n (Next s)
-- | Request that the specified UI element be made visible on the next
-- rendering. This is provided to allow event handlers to make visibility
-- requests in the same way that the visible function does at
-- rendering time.
makeVisible :: Ord n => n -> EventM n ()
-- | 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).
-- An important consequence of this behavior is that if this function is
-- called before a viewport is rendered for the first time, no state will
-- be found because the renderer only knows about viewports it has
-- rendered in the most recent rendering. As a result, if you need to
-- make viewport transformations before they are drawn for the first
-- time, you may need to use viewportScroll and its associated
-- functions without relying on this function. Those functions queue up
-- scrolling requests that can be made in advance of the next rendering
-- to affect the viewport.
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 ()
renderFinal :: Ord n => AttrMap -> [Widget n] -> DisplayRegion -> ([CursorLocation n] -> Maybe (CursorLocation n)) -> RenderState n -> (RenderState n, Picture, Maybe (CursorLocation n), [Extent n])
getRenderState :: EventM n (RenderState n)
resetRenderState :: RenderState n -> RenderState n
-- | This function provides a simplified interface to rendering a list of
-- Widgets as a Picture outside of the context of an
-- App. This can be useful in a testing setting but isn't
-- intended to be used for normal application rendering. The API is
-- deliberately narrower than the main interactive API and is not yet
-- stable. Use at your own risk.
--
-- Consult the Vty library documentation for details on how to
-- output the resulting Picture.
renderWidget :: Ord n => Maybe AttrMap -> [Widget n] -> DisplayRegion -> Picture
-- | This module provides a scrollable list type and functions for
-- manipulating and rendering it.
--
-- Note that lenses are provided for direct manipulation purposes, but
-- lenses are *not* safe and should be used with care. (For example,
-- listElementsL permits direct manipulation of the list container
-- without performing bounds checking on the selected index.) If you need
-- a safe API, consider one of the various functions for list
-- manipulation. For example, instead of listElementsL, consider
-- listReplace.
module Brick.Widgets.List
-- | List state. Lists have a container t of element type
-- e that is the data stored by the list. Internally, 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
--
--
-- The List type synonym fixes t to Vector for
-- compatibility with previous versions of this library.
--
-- For a container type to be usable with GenericList, it must
-- have instances of Traversable and Splittable. The
-- following functions impose further constraints:
--
--
data GenericList n t e
-- | An alias for GenericList specialized to use a Vector
-- as its container type.
type List n e = GenericList n Vector e
-- | Construct a list in terms of container t with element type
-- e.
list :: Foldable t => n -> t e -> Int -> GenericList n t e
-- | Render a list using the specified item drawing function.
--
-- Evaluates the underlying container up to, and a bit beyond, the
-- selected element. The exact amount depends on available height for
-- drawing and listItemHeight. At most, it will evaluate up to
-- element (i + h + 1) where i is the selected index
-- and h is the available height.
--
-- Note that this function renders the list with the listAttr as
-- the default attribute and then uses listSelectedAttr as the
-- default attribute for the selected item if the list is not focused or
-- listSelectedFocusedAttr otherwise. This is provided as a
-- convenience so that the item rendering function doesn't have to be
-- concerned with attributes, but if those attributes are undesirable for
-- your purposes, forceAttr can always be used by the item
-- rendering function to ensure that another attribute is used instead.
renderList :: (Traversable t, Splittable t, Ord n, Show n) => (Bool -> e -> Widget n) -> Bool -> GenericList n t e -> Widget n
-- | Like renderList, except the render function is also provided
-- with the index of each element.
--
-- Has the same evaluation characteristics as renderList.
renderListWithIndex :: (Traversable t, Splittable t, Ord n, Show n) => (Int -> Bool -> e -> Widget n) -> Bool -> GenericList n t e -> Widget n
-- | Handle events for list cursor movement. Events handled are:
--
--
-- - Up (up arrow key)
-- - Down (down arrow key)
-- - Page Up (PgUp)
-- - Page Down (PgDown)
-- - Go to first element (Home)
-- - Go to last element (End)
--
handleListEvent :: (Foldable t, Splittable t, Ord n) => Event -> GenericList n t e -> EventM n (GenericList n t e)
-- | Enable list movement with the vi keys with a fallback handler 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)
-- - Go to first element (g)
-- - Go to last element (G)
--
handleListEventVi :: (Foldable t, Splittable t, Ord n) => (Event -> GenericList n t e -> EventM n (GenericList n t e)) -> Event -> GenericList n t e -> EventM n (GenericList n t e)
listElementsL :: forall n_a1l2A t_a1l2B e_a1l2C t_a1lgG e_a1lgH. Lens (GenericList n_a1l2A t_a1l2B e_a1l2C) (GenericList n_a1l2A t_a1lgG e_a1lgH) (t_a1l2B e_a1l2C) (t_a1lgG e_a1lgH)
listSelectedL :: forall n_a1l2A t_a1l2B e_a1l2C. Lens' (GenericList n_a1l2A t_a1l2B e_a1l2C) (Maybe Int)
listNameL :: forall n_a1l2A t_a1l2B e_a1l2C n_a1lgI. Lens (GenericList n_a1l2A t_a1l2B e_a1l2C) (GenericList n_a1lgI t_a1l2B e_a1l2C) n_a1l2A n_a1lgI
listItemHeightL :: forall n_a1l2A t_a1l2B e_a1l2C. Lens' (GenericList n_a1l2A t_a1l2B e_a1l2C) Int
-- | The list's sequence of elements.
listElements :: GenericList n t e -> t e
-- | The list's name.
listName :: GenericList n t e -> n
-- | Return a list's selected element, if any.
--
-- Only evaluates as much of the container as needed.
--
-- Complexity: same as splitAt for the container type.
--
--
-- listSelectedElement for List: O(1)
-- listSelectedElement for Seq: O(log(min(i, n - i)))
--
listSelectedElement :: (Splittable t, Foldable t) => GenericList n t e -> Maybe (Int, e)
-- | The list's selected element index, if any.
listSelected :: GenericList n t e -> Maybe Int
-- | The height of an individual item in the list.
listItemHeight :: GenericList n t e -> Int
-- | Move the list selected index.
--
-- If the current selection is Just x, the selection is adjusted
-- by the specified amount. The value is clamped to the extents of the
-- list (i.e. the selection does not "wrap").
--
-- If the current selection 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).
--
-- Complexity: same as splitAt for the container type.
--
--
-- listMoveBy for List: O(1)
-- listMoveBy for Seq: O(log(min(i,n-i)))
--
listMoveBy :: (Foldable t, Splittable t) => Int -> GenericList n t e -> GenericList n t e
-- | Set the selected index for a list to the specified index, subject to
-- validation.
--
-- If pos >= 0, indexes from the start of the list (which
-- gets evaluated up to the target index)
--
-- If pos < 0, indexes from the end of the list (which
-- evaluates length of the list).
--
-- Complexity: same as splitAt for the container type.
--
--
-- listMoveTo for List: O(1)
-- listMoveTo for Seq: O(log(min(i,n-i)))
--
listMoveTo :: (Foldable t, Splittable t) => Int -> GenericList n t e -> GenericList n t e
-- | Set the selected index for a list to the index of the first occurrence
-- of the specified element if it is in the list, or leave the list
-- unmodified otherwise.
--
-- O(n). Only evaluates as much of the container as needed.
listMoveToElement :: (Eq e, Foldable t, Splittable t) => e -> GenericList n t e -> GenericList n t e
-- | Starting from the currently-selected position, attempt to find and
-- select the next element matching the predicate. If there are no
-- matches for the remainder of the list or if the list has no selection
-- at all, the search starts at the beginning. If no matching element is
-- found anywhere in the list, leave the list unmodified.
--
-- O(n). Only evaluates as much of the container as needed.
listFindBy :: (Foldable t, Splittable t) => (e -> Bool) -> GenericList n t e -> GenericList n t e
-- | Move the list selected index up by one. (Moves the cursor up,
-- subtracts one from the index.)
listMoveUp :: (Foldable t, Splittable t) => GenericList n t e -> GenericList n t e
-- | Move the list selected index down by one. (Moves the cursor down, adds
-- one to the index.)
listMoveDown :: (Foldable t, Splittable t) => GenericList n t e -> GenericList n t e
-- | Move the list selected index by some (fractional) number of pages.
listMoveByPages :: (Foldable t, Splittable t, Ord n, RealFrac m) => m -> GenericList n t e -> EventM n (GenericList n t e)
-- | Move the list selected index up by one page.
listMovePageUp :: (Foldable t, Splittable t, Ord n) => GenericList n t e -> EventM n (GenericList n t e)
-- | Move the list selected index down by one page.
listMovePageDown :: (Foldable t, Splittable t, Ord n) => GenericList n t e -> EventM n (GenericList n t e)
-- | Move the list selection to the first element in the list.
listMoveToBeginning :: (Foldable t, Splittable t) => GenericList n t e -> GenericList n t e
-- | Move the list selection to the last element in the list.
listMoveToEnd :: (Foldable t, Splittable t) => GenericList n t e -> GenericList n t e
-- | Insert an item into a list at the specified position.
--
-- Complexity: the worse of splitAt and <> for the
-- container type.
--
--
-- listInsert for List: O(n)
-- listInsert for Seq: O(log(min(i, length n - i)))
--
listInsert :: (Splittable t, Applicative t, Semigroup (t e)) => Int -> e -> GenericList n t e -> GenericList n t e
-- | Remove an element from a list at the specified position.
--
-- Applies splitAt two times: first to split the structure at the
-- given position, and again to remove the first element from the tail.
-- Consider the asymptotics of splitAt for the container type when
-- using this function.
--
-- Complexity: the worse of splitAt and <> for the
-- container type.
--
--
-- listRemove for List: O(n)
-- listRemove for Seq: O(log(min(i, n - i)))
--
listRemove :: (Splittable t, Foldable t, Semigroup (t e)) => Int -> GenericList n t e -> GenericList n t 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.
--
-- Complexity: same as splitAt for the container type.
listReplace :: (Foldable t, Splittable t) => t e -> Maybe Int -> GenericList n t e -> GenericList n t e
-- | Remove all elements from the list and clear the selection.
--
-- O(1)
listClear :: Monoid (t e) => GenericList n t e -> GenericList n t e
-- | Reverse the list. The element selected before the reversal will again
-- be the selected one.
--
-- Complexity: same as reverse for the container type.
--
--
-- listReverse for List: O(n)
-- listReverse for Seq: O(n)
--
listReverse :: (Reversible t, Foldable t) => GenericList n t e -> GenericList n t e
-- | Apply a function to the selected element. If no element is selected
-- the list is not modified.
--
-- Complexity: same as traverse for the container type (typically
-- O(n)).
listModify :: Traversable t => (e -> e) -> GenericList n t e -> GenericList n t 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
-- | Ordered container types that can be split at a given index. An
-- instance of this class is required for a container type to be usable
-- with GenericList.
class Splittable t
-- | Split at the given index. Equivalent to (take n xs, drop n
-- xs) and therefore total.
splitAt :: Splittable t => Int -> t a -> (t a, t a)
-- | Slice the structure. Equivalent to (take n . drop i) xs and
-- therefore total.
--
-- The default implementation applies splitAt two times: first to
-- drop elements leading up to the slice, and again to drop elements
-- after the slice.
slice :: Splittable t => Int -> Int -> t a -> t a
-- | Ordered container types where the order of elements can be reversed.
-- Only required if you want to use listReverse.
class Reversible t
reverse :: Reversible t => t a -> t a
instance Brick.Widgets.List.Reversible Data.Vector.Vector
instance Brick.Widgets.List.Reversible Data.Sequence.Internal.Seq
instance Brick.Widgets.List.Splittable Data.Vector.Vector
instance Brick.Widgets.List.Splittable Data.Sequence.Internal.Seq
instance Brick.Widgets.Core.Named (Brick.Widgets.List.GenericList n t e) n
instance GHC.Generics.Generic (Brick.Widgets.List.GenericList n t e)
instance (GHC.Show.Show n, GHC.Show.Show (t e)) => GHC.Show.Show (Brick.Widgets.List.GenericList n t e)
instance Data.Traversable.Traversable t => Data.Traversable.Traversable (Brick.Widgets.List.GenericList n t)
instance Data.Foldable.Foldable t => Data.Foldable.Foldable (Brick.Widgets.List.GenericList n t)
instance GHC.Base.Functor t => GHC.Base.Functor (Brick.Widgets.List.GenericList n t)
-- | This module provides a file browser widget that allows users to
-- navigate directory trees, search for files and directories, and select
-- entries of interest. For a complete working demonstration of this
-- module, see programs/FileBrowserDemo.hs.
--
-- To use this module:
--
--
--
-- File browsers have a built-in user-configurable function to limit the
-- entries displayed that defaults to showing all files. For example, an
-- application might want to limit the browser to just directories and
-- XML files. That is accomplished by setting the filter with
-- setFileBrowserEntryFilter and some examples are provided in
-- this module: fileTypeMatch and fileExtensionMatch.
--
-- File browsers are styled using the provided collection of attribute
-- names, so add those to your attribute map to get the appearance you
-- want. File browsers also make use of a List internally, so the
-- List attributes will affect how the list appears.
--
-- File browsers catch IOExceptions when changing directories.
-- If a call to setWorkingDirectory triggers an
-- IOException while reading the working directory, the
-- resulting IOException is stored in the file browser and is
-- accessible with fileBrowserException. The
-- setWorkingDirectory function clears the exception field if the
-- working directory is read successfully. The caller is responsible for
-- deciding when and whether to display the exception to the user. In the
-- event that an IOException is raised as described here, the
-- file browser will always present .. as a navigation option to
-- allow the user to continue navigating up the directory tree. It does
-- this even if the current or parent directory does not exist or cannot
-- be read, so it is always safe to present a file browser for any
-- working directory. Bear in mind that the .. entry is always
-- subjected to filtering and searching.
module Brick.Widgets.FileBrowser
-- | A file browser's state. Embed this in your application state and
-- transform it with handleFileBrowserEvent and the functions
-- included in this module.
data FileBrowser n
-- | Information about a file entry in the browser.
data FileInfo
FileInfo :: String -> String -> FilePath -> Either IOException FileStatus -> Maybe FileType -> FileInfo
-- | The filename of this entry, without its path. This is not for display
-- purposes; for that, use fileInfoSanitizedFilename.
[fileInfoFilename] :: FileInfo -> String
-- | The filename of this entry with out its path, sanitized of
-- non-printable characters (replaced with ?). This is for
-- display purposes only.
[fileInfoSanitizedFilename] :: FileInfo -> String
-- | The full path to this entry's file.
[fileInfoFilePath] :: FileInfo -> FilePath
-- | The file status if it could be obtained, or the exception that was
-- caught when attempting to read the file's status.
[fileInfoFileStatus] :: FileInfo -> Either IOException FileStatus
-- | If this entry is a symlink, this indicates the type of file the
-- symlink points to, if it could be obtained.
[fileInfoLinkTargetType] :: FileInfo -> Maybe FileType
-- | File status information.
data FileStatus
FileStatus :: Int64 -> Maybe FileType -> FileStatus
-- | The size, in bytes, of this entry's file.
[fileStatusSize] :: FileStatus -> Int64
-- | The type of this entry's file, if it could be determined.
[fileStatusFileType] :: FileStatus -> Maybe FileType
-- | The type of file entries in the browser.
data FileType
-- | A regular disk file.
RegularFile :: FileType
-- | A block device.
BlockDevice :: FileType
-- | A character device.
CharacterDevice :: FileType
-- | A named pipe.
NamedPipe :: FileType
-- | A directory.
Directory :: FileType
-- | A symbolic link.
SymbolicLink :: FileType
-- | A Unix socket.
UnixSocket :: FileType
-- | Make a new file browser state. The provided resource name will be used
-- to render the List viewport of the browser.
--
-- By default, the browser will show all files and directories in its
-- working directory. To change that behavior, see
-- setFileBrowserEntryFilter.
newFileBrowser :: (FileInfo -> Bool) -> n -> Maybe FilePath -> IO (FileBrowser n)
-- | A file entry selector that permits selection of all file entries
-- except directories. Use this if you want users to be able to navigate
-- directories in the browser. If you want users to be able to select
-- only directories, use selectDirectories.
selectNonDirectories :: FileInfo -> Bool
-- | A file entry selector that permits selection of directories only. This
-- prevents directory navigation and only supports directory selection.
selectDirectories :: FileInfo -> Bool
-- | Set the working directory of the file browser. This scans the new
-- directory and repopulates the browser while maintaining any active
-- search string and/or entry filtering.
--
-- If the directory scan raises an IOException, the exception is
-- stored in the browser and is accessible with
-- fileBrowserException. If no exception is raised, the exception
-- field is cleared. Regardless of whether an exception is raised,
-- .. is always presented as a valid option in the browser.
setWorkingDirectory :: FilePath -> FileBrowser n -> IO (FileBrowser n)
-- | Get the working directory of the file browser.
getWorkingDirectory :: FileBrowser n -> FilePath
-- | Modify the file browser's active search string. This causes the
-- browser's displayed entries to change to those in its current
-- directory that match the search string, if any. If a search string is
-- provided, it is matched case-insensitively anywhere in file or
-- directory names.
updateFileBrowserSearch :: (Maybe Text -> Maybe Text) -> FileBrowser n -> FileBrowser n
-- | Set the filtering function used to determine which entries in the
-- browser's current directory appear in the browser. Nothing
-- indicates no filtering, meaning all entries will be shown. Just
-- indicates a function that should return True for entries that
-- should be permitted to appear.
--
-- Note that this applies the filter after setting it by updating the
-- listed entries to reflect the result of the filter. That is unlike
-- setting the filter with the fileBrowserEntryFilterL lens
-- directly, which just sets the filter but does not (and cannot) update
-- the listed entries.
setFileBrowserEntryFilter :: Maybe (FileInfo -> Bool) -> FileBrowser n -> FileBrowser n
-- | Handle a Vty input event. Note that event handling can cause a
-- directory change so the caller should be aware that
-- fileBrowserException may need to be checked after handling an
-- event in case an exception was triggered while scanning the working
-- directory.
--
-- Events handled regardless of mode:
--
--
--
-- Events handled only in normal mode:
--
--
--
-- Events handled only in search mode:
--
--
-- - Esc, Ctrl-C: cancel search mode
-- - Text input: update search string
--
actionFileBrowserBeginSearch :: FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserSelectEnter :: FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserSelectCurrent :: FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListPageUp :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListPageDown :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListHalfPageUp :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListHalfPageDown :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListTop :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListBottom :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListNext :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
actionFileBrowserListPrev :: Ord n => FileBrowser n -> EventM n (FileBrowser n)
handleFileBrowserEvent :: Ord n => Event -> FileBrowser n -> EventM n (FileBrowser n)
-- | If the browser's current entry is selectable according to
-- fileBrowserSelectable, add it to the selection set and
-- return. If not, and if the entry is a directory or a symlink targeting
-- a directory, set the browser's current path to the selected directory.
--
-- Otherwise, return the browser state unchanged.
maybeSelectCurrentEntry :: FileBrowser n -> EventM n (FileBrowser n)
-- | Render a file browser. This renders a list of entries in the working
-- directory, a cursor to select from among the entries, a header
-- displaying the working directory, and a footer displaying information
-- about the selected entry.
--
-- Note that if the most recent file browser operation produced an
-- exception in fileBrowserException, that exception is not
-- rendered by this function. That exception needs to be rendered (if at
-- all) by the calling application.
--
-- The file browser is greedy in both dimensions.
renderFileBrowser :: (Show n, Ord n) => Bool -> FileBrowser n -> Widget n
-- | Get the file information for the file under the cursor, if any.
fileBrowserCursor :: FileBrowser n -> Maybe FileInfo
-- | Returns whether the file browser is in search mode, i.e., the mode in
-- which user input affects the browser's active search string and
-- displayed entries. This is used to aid in event dispatching in the
-- calling program.
fileBrowserIsSearching :: FileBrowser n -> Bool
-- | Get the entries chosen by the user, if any. Entries are chosen by an
-- Enter or Space keypress; if you want the entry under
-- the cursor, use fileBrowserCursor.
fileBrowserSelection :: FileBrowser n -> [FileInfo]
-- | The exception status of the latest directory change. If
-- Nothing, the latest directory change was successful and all
-- entries were read. Otherwise, this contains the exception raised by
-- the latest directory change in case the calling application needs to
-- inspect or present the error to the user.
fileBrowserException :: FileBrowser n -> Maybe IOException
-- | The function that determines what kinds of entries are selectable with
-- in the event handler. Note that if this returns True for an
-- entry, an Enter or Space keypress selects that entry
-- rather than doing anything else; directory changes can only occur if
-- this returns False for directories.
--
-- Note that this is a record field so it can be used to change the
-- selection function.
fileBrowserSelectable :: FileBrowser n -> FileInfo -> Bool
-- | Get the file type for this file info entry. If the file type could not
-- be obtained due to an IOException, return Nothing.
fileInfoFileType :: FileInfo -> Maybe FileType
-- | The base attribute for all file browser attributes.
fileBrowserAttr :: AttrName
-- | The attribute used for the current directory displayed at the top of
-- the browser.
fileBrowserCurrentDirectoryAttr :: AttrName
-- | The attribute used for the entry information displayed at the bottom
-- of the browser.
fileBrowserSelectionInfoAttr :: AttrName
-- | The attribute used for selected entries in the file browser.
fileBrowserSelectedAttr :: AttrName
-- | The attribute used to render directory entries.
fileBrowserDirectoryAttr :: AttrName
-- | The attribute used to render block device entries.
fileBrowserBlockDeviceAttr :: AttrName
-- | The attribute used to render regular file entries.
fileBrowserRegularFileAttr :: AttrName
-- | The attribute used to render character device entries.
fileBrowserCharacterDeviceAttr :: AttrName
-- | The attribute used to render named pipe entries.
fileBrowserNamedPipeAttr :: AttrName
-- | The attribute used to render symbolic link entries.
fileBrowserSymbolicLinkAttr :: AttrName
-- | The attribute used to render Unix socket entries.
fileBrowserUnixSocketAttr :: AttrName
-- | A file type filter for use with setFileBrowserEntryFilter. This
-- filter permits entries whose file types are in the specified list.
fileTypeMatch :: [FileType] -> FileInfo -> Bool
-- | A filter that matches any directory regardless of name, or any regular
-- file with the specified extension. For example, an extension argument
-- of "xml" would match regular files test.xml and
-- TEST.XML and it will match directories regardless of name.
--
-- This matcher also matches symlinks if and only if their targets are
-- directories. This is intended to make it possible to use this matcher
-- to find files with certain extensions, but also support directory
-- traversal via symlinks.
fileExtensionMatch :: String -> FileInfo -> Bool
fileBrowserSelectableL :: forall n_a1qes. Lens' (FileBrowser n_a1qes) (FileInfo -> Bool)
fileInfoFilenameL :: Lens' FileInfo String
fileInfoSanitizedFilenameL :: Lens' FileInfo String
fileInfoFilePathL :: Lens' FileInfo FilePath
fileInfoFileStatusL :: Lens' FileInfo (Either IOException FileStatus)
fileInfoLinkTargetTypeL :: Lens' FileInfo (Maybe FileType)
fileStatusSizeL :: Lens' FileStatus Int64
fileStatusFileTypeL :: Lens' FileStatus (Maybe FileType)
fileBrowserEntryFilterG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) (Maybe (FileInfo -> Bool))
fileBrowserWorkingDirectoryG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) FilePath
fileBrowserEntriesG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) (List n_a1qes FileInfo)
fileBrowserLatestResultsG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) [FileInfo]
fileBrowserSelectedFilesG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) (Set String)
fileBrowserNameG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) n_a1qes
fileBrowserSearchStringG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) (Maybe Text)
fileBrowserExceptionG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) (Maybe IOException)
fileBrowserSelectableG :: forall n_a1qes. SimpleGetter (FileBrowser n_a1qes) (FileInfo -> Bool)
-- | Generate a textual abbreviation of a file size, e.g. "10.2M" or "12
-- bytes".
prettyFileSize :: Int64 -> Text
-- | Build a list of file info entries for the specified directory. This
-- function does not catch any exceptions raised by calling
-- makeAbsolute or listDirectory, but it does catch
-- exceptions on a per-file basis. Any exceptions caught when inspecting
-- individual files are stored in the fileInfoFileStatus field of
-- each FileInfo.
--
-- The entries returned are all entries in the specified directory except
-- for . and ... Directories are always given first.
-- Entries are sorted in case-insensitive lexicographic order.
--
-- This function is exported for those who want to implement their own
-- file browser using the types in this module.
entriesForDirectory :: FilePath -> IO [FileInfo]
-- | Build a FileInfo for the specified file and path. If an
-- IOException is raised while attempting to get the file
-- information, the fileInfoFileStatus field is populated with the
-- exception. Otherwise it is populated with the FileStatus for
-- the file.
getFileInfo :: String -> FilePath -> IO FileInfo
instance GHC.Classes.Eq Brick.Widgets.FileBrowser.FileType
instance GHC.Show.Show Brick.Widgets.FileBrowser.FileType
instance GHC.Read.Read Brick.Widgets.FileBrowser.FileType
instance GHC.Classes.Eq Brick.Widgets.FileBrowser.FileStatus
instance GHC.Show.Show Brick.Widgets.FileBrowser.FileStatus
instance GHC.Classes.Eq Brick.Widgets.FileBrowser.FileInfo
instance GHC.Show.Show Brick.Widgets.FileBrowser.FileInfo
-- | This module is provided as a convenience to import the most important
-- parts of the API all at once. If you are new to Brick and are looking
-- to learn it, the best place to start is the Brick User Guide.
-- The README also has links to other learning resources. Unlike most
-- Haskell libraries that only have API documentation, Brick is best
-- larned by reading the User Guide and other materials and referring to
-- the API docs only as needed. Enjoy!
module Brick
-- | Note - this API is designed to support a narrow (but common!) set of
-- use cases. If you find that you need more customization than this
-- offers, then you will need to consider building your own layout and
-- event handling for input fields.
--
-- 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.
--
-- 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).
--
-- To use a Form, you must include it within your application
-- state type. You can use formState to access the underlying
-- state whenever you need it. See programs/FormDemo.hs for a
-- complete working example.
--
-- 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. This value must be stored in the
-- Brick application's state.
--
-- 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.", formFieldUpdate :: a -> b -> b " Given a new form state value, update the form field state in place.", 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 as an integer and return Maybe Int.
-- This is for pure value validation; if additional validation is
-- required (e.g. via IO), use this field's state value in an
-- external validation routine and use setFieldValid to feed 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
-- | Set the focused field of a form.
setFormFocus :: Eq n => n -> Form s e n -> Form s e n
-- | Update the state contained in a form.
--
-- This updates all form fields to be consistent with the new form state.
-- Where possible, this attempts to maintain other input state, such as
-- text editor cursor position.
--
-- Note that since this updates the form fields, this means that any
-- field values will be completely overwritten! This may or may not be
-- what you want, since a user actively using the form could get confused
-- if their edits go away. Use carefully.
updateFormState :: s -> Form s e n -> Form 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 the Show
-- representation of a state field value of type a. This
-- automatically uses its Read instance to validate the input, and
-- also accepts an additional user-defined pass for validation. This
-- field is mostly useful in cases where the user-facing representation
-- of a value matches the Show representation exactly, such as
-- with Int, but you don't want to accept just any
-- Int.
--
-- This field responds to all events handled by editor, including
-- mouse events.
editShowableFieldWithValidate :: (Ord n, Show n, Read a, Show a) => Lens' s a -> n -> (a -> Bool) -> 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 selecting a single choice from a set of possible
-- choices in a scrollable list. This uses a List internally.
--
-- This field responds to the same input events that a List does.
listField :: forall s e n a. (Ord n, Show n, Eq a) => (s -> Vector a) -> Lens' s (Maybe a) -> (Bool -> a -> Widget n) -> Int -> n -> 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
-- | A form field for selecting a single choice from a set of possible
-- choices. Each choice has an associated value and text label. This
-- function permits the customization of the [*] notation
-- characters.
--
-- This field responds to Space keypresses to select a radio
-- button option and to mouse clicks.
radioCustomField :: (Ord n, Show n, Eq a) => Char -> Char -> Char -> 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 function permits the customization of the
-- [X] notation characters.
--
-- This field responds to Space keypresses to toggle the
-- checkbox and to mouse clicks.
checkboxCustomField :: (Ord n, Show n) => Char -> Char -> Char -> Lens' s Bool -> n -> Text -> 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