Graphics.Vty.Widgets.List

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

Documentation

data List a

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)

A list item. Each item contains an arbitrary internal identifier a and a Widget representing it.

List creation

mkList

Arguments

:: 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.

mkSimpleList

Arguments

:: 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 Strings as the internal identifiers and Text widgets to represent those strings.

listWidget :: List a -> Widget

List manipulation

scrollBy :: Int -> List a -> List a

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)

scrollUp :: List a -> List a

Scroll a list up by one position.

scrollDown :: List a -> List a

Scroll a list down by one position.

pageUp :: List a -> List a

Scroll a list up by one page from the current cursor position.

pageDown :: List a -> List a

Scroll a list down by one page from the current cursor position.

resize :: Int -> List a -> List a

Set the window size of the list. This automatically adjusts the window position to keep the selected item visible.

List inspection

listItems :: List a -> [ListItem a]

The items in the list.

getSelected :: List a -> ListItem a

Get the currently selected list item.

selectedIndex :: List a -> Int

The currently selected list index.

scrollTopIndex :: List a -> Int

The start index of the window of visible list items.

scrollWindowSize :: List a -> Int

The size of the window of visible list items.

getVisibleItems :: List a -> [(ListItem a, Bool)]

Given a List, return the items that are currently visible according to the state of the list. Returns the visible items and flags indicating whether each is selected.