This module provides a List
widget for rendering a list of
arbitrary widgets. A List
shows a number of elements and
highlights the currently-selected widget. It supports key events
to navigate the list and will automatically scroll based on the
space available to the list along with the size of the widgets in
the list.
- data List a b
- type ListItem a b = (a, Widget b)
- data ListError
- data NewItemEvent a b = NewItemEvent Int a (Widget b)
- data RemoveItemEvent a b = RemoveItemEvent Int a (Widget b)
- data SelectionEvent a b
- = SelectionOn Int a (Widget b)
- | SelectionOff
- data ActivateItemEvent a b = ActivateItemEvent Int a (Widget b)
- newStringList :: MonadIO m => Attr -> [String] -> m (Widget (List String FormattedText))
- newList :: (MonadIO m, Show b) => Attr -> (a -> IO (Widget b)) -> m (Widget (List a b))
- addToList :: (MonadIO m, Show b) => Widget (List a b) -> a -> m (ListItem a b)
- removeFromList :: MonadIO m => Widget (List a b) -> Int -> m (ListItem a b)
- scrollBy :: MonadIO m => Widget (List a b) -> Int -> m ()
- scrollUp :: MonadIO m => Widget (List a b) -> m ()
- scrollDown :: MonadIO m => Widget (List a b) -> m ()
- pageUp :: MonadIO m => Widget (List a b) -> m ()
- pageDown :: MonadIO m => Widget (List a b) -> m ()
- onSelectionChange :: MonadIO m => Widget (List a b) -> (SelectionEvent a b -> IO ()) -> m ()
- onItemAdded :: MonadIO m => Widget (List a b) -> (NewItemEvent a b -> IO ()) -> m ()
- onItemRemoved :: MonadIO m => Widget (List a b) -> (RemoveItemEvent a b -> IO ()) -> m ()
- onItemActivated :: MonadIO m => Widget (List a b) -> (ActivateItemEvent a b -> IO ()) -> m ()
- activateCurrentItem :: MonadIO m => Widget (List a b) -> m ()
- clearList :: MonadIO m => Widget (List a b) -> m ()
- getListSize :: MonadIO m => Widget (List a b) -> m Int
- getSelected :: MonadIO m => Widget (List a b) -> m (Maybe (Int, ListItem a b))
Documentation
The list widget type. Lists are parameterized over the internal
value type a
, the type of internal values used to refer to the
visible representations of the list contents, and the widget type
b
, the type of widgets used to represent the list visually.
type ListItem a b = (a, Widget b)Source
A list item. Each item contains an arbitrary internal value a
and a Widget
representing it.
BadItemIndex Int | The specified position could not be used to remove an item from the list. |
ResizeError | |
BadListWidgetSizePolicy | The type of widgets added to the list grow vertically, which is not permitted. |
data NewItemEvent a b Source
A new item was added to the list at the specified position with the specified value and widget.
NewItemEvent Int a (Widget b) |
data RemoveItemEvent a b Source
An item was removed from the list at the specified position with the specified value and widget.
RemoveItemEvent Int a (Widget b) |
data SelectionEvent a b Source
SelectionOn Int a (Widget b) | An item at the specified position with the specified internal value and widget was selected. |
SelectionOff | No item was selected, which means the list is empty. |
data ActivateItemEvent a b Source
An item in the list was activated at the specified position with the specified value and widget.
ActivateItemEvent Int a (Widget b) |
List creation
:: MonadIO m | |
=> Attr | The attribute of the selected item |
-> [String] | The list items |
-> m (Widget (List String FormattedText)) |
A convenience function to create a new list using String
s as the
internal values and FormattedText
widgets to represent those
strings.
:: (MonadIO m, Show b) | |
=> Attr | The attribute of the selected item |
-> (a -> IO (Widget b)) | Constructor for new item widgets |
-> m (Widget (List a b)) |
Create a new list using the specified attribute for the currently-selected element when the list does NOT have focus. Use the specified constructor function to create widgets for new items in the list.
addToList :: (MonadIO m, Show b) => Widget (List a b) -> a -> m (ListItem a b)Source
Add an item to the list. Its widget will be constructed from the
specified internal value using the widget constructor passed to
newList
.
removeFromList :: MonadIO m => Widget (List a b) -> Int -> m (ListItem a b)Source
Remove an element from the list at the specified position. May
throw BadItemIndex
.
List manipulation
scrollBy :: MonadIO m => Widget (List a b) -> Int -> m ()Source
Scroll a list up or down by the specified number of positions. Scrolling by a positive amount scrolls downward and scrolling by a negative amount scrolls upward. This automatically takes care of managing internal list state and invoking event handlers.
pageUp :: MonadIO m => Widget (List a b) -> m ()Source
Scroll a list up by one page from the current cursor position.
pageDown :: MonadIO m => Widget (List a b) -> m ()Source
Scroll a list down by one page from the current cursor position.
onSelectionChange :: MonadIO m => Widget (List a b) -> (SelectionEvent a b -> IO ()) -> m ()Source
Register event handlers to be invoked when the list's selected item changes.
onItemAdded :: MonadIO m => Widget (List a b) -> (NewItemEvent a b -> IO ()) -> m ()Source
Register event handlers to be invoked when a new item is added to the list.
onItemRemoved :: MonadIO m => Widget (List a b) -> (RemoveItemEvent a b -> IO ()) -> m ()Source
Register event handlers to be invoked when an item is removed from the list.
onItemActivated :: MonadIO m => Widget (List a b) -> (ActivateItemEvent a b -> IO ()) -> m ()Source
Register event handlers to be invoked when an item is activated, which happens when the user presses Enter on a selected element while the list has the focus.
activateCurrentItem :: MonadIO m => Widget (List a b) -> m ()Source
Programmatically activate the currently-selected item in the list, if any.
clearList :: MonadIO m => Widget (List a b) -> m ()Source
Clear the list, removing all elements. Does not invoke any handlers.