This module provides a List
widget for rendering a list of
arbitrary widgets. A List
has the following features:
- A style for the list elements
- A styled cursor indicating which element is selected
- A window size indicating how many elements should be visible to the user
- An internal pointer to the start of the visible window, which automatically shifts as the list is scrolled
- data List a
- type ListItem a = (a, Widget)
- mkList :: Attr -> Attr -> Int -> [ListItem a] -> List a
- mkSimpleList :: Attr -> Attr -> Int -> [String] -> List String
- listWidget :: List a -> Widget
- scrollBy :: Int -> List a -> List a
- scrollUp :: List a -> List a
- scrollDown :: List a -> List a
- pageUp :: List a -> List a
- pageDown :: List a -> List a
- resize :: Int -> List a -> List a
- listItems :: List a -> [ListItem a]
- getSelected :: List a -> ListItem a
- selectedIndex :: List a -> Int
- scrollTopIndex :: List a -> Int
- scrollWindowSize :: List a -> Int
- getVisibleItems :: List a -> [(ListItem a, Bool)]
Documentation
The list widget type. Lists are parameterized over the internal
identifier type a
, the type of internal identifiers 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 = (a, Widget)Source
A list item. Each item contains an arbitrary internal identifier
a
and a Widget
representing it.
List creation
:: Attr | The attribute of normal, non-selected items |
-> Attr | The attribute of the selected item |
-> Int | The scrolling window size, i.e., the number of items which should be visible to the user at any given time |
-> [ListItem a] | The list items |
-> List a |
Create a new list. Emtpy lists and empty scrolling windows are not allowed.
:: Attr | The attribute of normal, non-selected items |
-> Attr | The attribute of the selected item |
-> Int | The scrolling window size, i.e., the number of items which should be visible to the user at any given time |
-> [String] | The list items |
-> List String |
A convenience function to create a new list using String
s as the
internal identifiers and Text
widgets to represent those strings.
listWidget :: List a -> WidgetSource
List manipulation
scrollBy :: Int -> List a -> List aSource
Scroll a list up or down by the specified number of positions and return the new scrolled list. Scrolling by a positive amount scrolls downward and scrolling by a negative amount scrolls upward. This automatically takes care of managing internal list state:
- Moves the cursor by the specified amount and clamps the cursor position to the beginning or the end of the list where appropriate
- Moves the scrolling window position if necessary (i.e., if the cursor moves to an item not currently in view)
scrollDown :: List a -> List aSource
Scroll a list down by one position.
resize :: Int -> List a -> List aSource
Set the window size of the list. This automatically adjusts the window position to keep the selected item visible.
List inspection
getSelected :: List a -> ListItem aSource
Get the currently selected list item.
selectedIndex :: List a -> IntSource
The currently selected list index.
scrollTopIndex :: List a -> IntSource
The start index of the window of visible list items.
scrollWindowSize :: List a -> IntSource
The size of the window of visible list items.