Brick.Widgets.List

This module provides a scrollable list type and functions for manipulating and rendering it.

Documentation

data List n e

List state. Lists have an element type e that is the data stored by the list. Lists handle the following events by default:

• Up/down arrow keys: move cursor of selected item
• Page up / page down keys: move cursor of selected item by one page at a time (based on the number of items shown)
• Home/end keys: move cursor of selected item to beginning or end of list

Instances

Functor (List n)

Defined in Brick.Widgets.List

Methods

fmap :: (a -> b) -> List n a -> List n b

(<$) :: a -> List n b -> List n a

Foldable (List n)

Defined in Brick.Widgets.List

Methods

fold :: Monoid m => List n m -> m

foldMap :: Monoid m => (a -> m) -> List n a -> m

foldr :: (a -> b -> b) -> b -> List n a -> b

foldr' :: (a -> b -> b) -> b -> List n a -> b

foldl :: (b -> a -> b) -> b -> List n a -> b

foldl' :: (b -> a -> b) -> b -> List n a -> b

foldr1 :: (a -> a -> a) -> List n a -> a

foldl1 :: (a -> a -> a) -> List n a -> a

toList :: List n a -> [a]

null :: List n a -> Bool

length :: List n a -> Int

elem :: Eq a => a -> List n a -> Bool

maximum :: Ord a => List n a -> a

minimum :: Ord a => List n a -> a

sum :: Num a => List n a -> a

product :: Num a => List n a -> a

Traversable (List n)

Defined in Brick.Widgets.List

Methods

traverse :: Applicative f => (a -> f b) -> List n a -> f (List n b)

sequenceA :: Applicative f => List n (f a) -> f (List n a)

mapM :: Monad m => (a -> m b) -> List n a -> m (List n b)

sequence :: Monad m => List n (m a) -> m (List n a)

(Show e, Show n) => Show (List n e)

Defined in Brick.Widgets.List

Methods

showsPrec :: Int -> List n e -> ShowS

show :: List n e -> String

showList :: [List n e] -> ShowS

Named (List n e) n

Defined in Brick.Widgets.List

Methods

getName :: List n e -> n

Constructing a list

list

Arguments

:: n

The list name (must be unique)

-> Vector e

The initial list contents

-> Int

The list item height in rows (all list item widgets must be this high)

-> List n e

Construct a list in terms of an element type e.

Rendering a list

renderList

Arguments

:: (Ord n, Show n)

=> (Bool -> e -> Widget n)

Rendering function, True for the selected element

-> Bool

Whether the list has focus

-> List n e

The List to be rendered

-> Widget n

rendered widget

Turn a list state value into a widget given an item drawing function.

renderListWithIndex

Arguments

:: (Ord n, Show n)

=> (Int -> Bool -> e -> Widget n)

Rendering function, taking index, and True for the selected element

-> Bool

Whether the list has focus

-> List n e

The List to be rendered

-> Widget n

rendered widget

Like renderList, except the render function is also provided with the index of each element.

Handling events

handleListEvent :: Ord n => Event -> List n e -> EventM n (List n e)

handleListEventVi

Arguments

:: Ord n

=> (Event -> List n e -> EventM n (List n e))

Fallback event handler to use if none of the vi keys match.

-> Event

-> List n e

-> EventM n (List n e)

Enable list movement with the vi keys with a fallback if none match. Use (handleListEventVi handleListEvent) in place of handleListEvent to add the vi keys bindings to the standard ones. Movements handled include:

• Up (k)
• Down (j)
• Page Up (Ctrl-b)
• Page Down (Ctrl-f)
• Half Page Up (Ctrl-u)
• Half Page Down (Ctrl-d)
• Top (g)
• Bottom (G)

Lenses

listElementsL :: forall n e e. Lens (List n e) (List n e) (Vector e) (Vector e)

listSelectedL :: forall n e. Lens' (List n e) (Maybe Int)

listNameL :: forall n e n. Lens (List n e) (List n e) n n

listItemHeightL :: forall n e. Lens' (List n e) Int

Accessors

listElements :: List n e -> Vector e

The list's vector of elements.

listName :: List n e -> n

The list's name.

listSelectedElement :: List n e -> Maybe (Int, e)

Return a list's selected element, if any.

listSelected :: List n e -> Maybe Int

The list's selected element index, if any.

listItemHeight :: List n e -> Int

The height of the list items.

Manipulating a list

listMoveBy :: Int -> List n e -> List n e

Move the list selected index. If the index is `Just x`, adjust by the specified amount; if it is Nothing (i.e. there is no selection) and the direction is positive, set to `Just 0` (first element), otherwise set to `Just (length - 1)` (last element). Subject to validation.

listMoveTo :: Int -> List n e -> List n e

Set the selected index for a list to the specified index, subject to validation.

listMoveUp :: List n e -> List n e

Move the list selected index up by one. (Moves the cursor up, subtracts one from the index.)

listMoveDown :: List n e -> List n e

Move the list selected index down by one. (Moves the cursor down, adds one to the index.)

listMoveByPages :: (Ord n, RealFrac m) => m -> List n e -> EventM n (List n e)

Move the list selected index by some (fractional) number of pages.

listMovePageUp :: Ord n => List n e -> EventM n (List n e)

Move the list selected index up by one page.

listMovePageDown :: Ord n => List n e -> EventM n (List n e)

Move the list selected index down by one page.

listInsert

Arguments

:: Int

The position at which to insert (0 <= i <= size)

-> e

The element to insert

-> List n e

-> List n e

Insert an item into a list at the specified position.

listRemove

Arguments

:: Int

The position at which to remove an element (0 <= i < size)

-> List n e

-> List n e

Remove an element from a list at the specified position.

listReplace :: Vector e -> Maybe Int -> List n e -> List n e

Replace the contents of a list with a new set of elements and update the new selected index. If the list is empty, empty selection is used instead. Otherwise, if the specified selected index (via Just) is not in the list bounds, zero is used instead.

listClear :: List n e -> List n e

Remove all elements from the list and clear the selection.

listReverse :: List n e -> List n e

Reverse the list. The element selected before the reversal will again be the selected one.

listModify :: (e -> e) -> List n e -> List n e

Apply a function to the selected element. If no element is selected the list is not modified.

Attributes

listAttr :: AttrName

The top-level attribute used for the entire list.

listSelectedAttr :: AttrName

The attribute used only for the currently-selected list item when the list does not have focus. Extends listAttr.

listSelectedFocusedAttr :: AttrName

The attribute used only for the currently-selected list item when the list has focus. Extends listSelectedAttr.