vty-ui-1.6: An interactive terminal user interface library for Vty

Safe HaskellNone

Graphics.Vty.Widgets.List

Contents

Description

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.

Synopsis

Documentation

data List a b Source

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.

Instances

Show (List a b) 

type ListItem a b = (a, Widget b)Source

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

data ListError Source

Constructors

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.

Constructors

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.

Constructors

RemoveItemEvent Int a (Widget b) 

data SelectionEvent a b Source

Constructors

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.

Constructors

ActivateItemEvent Int a (Widget b) 

List creation

newTextListSource

Arguments

:: Attr

The attribute of the selected item

-> [Text]

The list items

-> IO (Widget (List Text FormattedText)) 

A convenience function to create a new list using Text values as the internal values and FormattedText widgets to represent those strings.

newListSource

Arguments

:: Show b 
=> Attr

The attribute of the selected item

-> IO (Widget (List a b)) 

Create a new list using the specified attribute for the currently-selected element when the list does NOT have focus.

addToList :: Show b => Widget (List a b) -> a -> Widget b -> IO ()Source

Add an item to the list. Its widget will be constructed from the specified internal value using the widget constructor passed to newList.

insertIntoList :: Show b => Widget (List a b) -> a -> Widget b -> Int -> IO ()Source

Insert an element into the list at the specified position. If the position exceeds the length of the list, it is inserted at the end.

removeFromList :: Widget (List a b) -> Int -> IO (ListItem a b)Source

Remove an element from the list at the specified position. May throw BadItemIndex.

List manipulation

scrollBy :: Widget (List a b) -> Int -> IO ()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.

scrollUp :: Widget (List a b) -> IO ()Source

Scroll a list up by one position.

scrollDown :: Widget (List a b) -> IO ()Source

Scroll a list down by one position.

pageUp :: Widget (List a b) -> IO ()Source

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

pageDown :: Widget (List a b) -> IO ()Source

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

onSelectionChange :: Widget (List a b) -> (SelectionEvent a b -> IO ()) -> IO ()Source

Register event handlers to be invoked when the list's selected item changes.

onItemAdded :: Widget (List a b) -> (NewItemEvent a b -> IO ()) -> IO ()Source

Register event handlers to be invoked when a new item is added to the list.

onItemRemoved :: Widget (List a b) -> (RemoveItemEvent a b -> IO ()) -> IO ()Source

Register event handlers to be invoked when an item is removed from the list.

onItemActivated :: Widget (List a b) -> (ActivateItemEvent a b -> IO ()) -> IO ()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 :: Widget (List a b) -> IO ()Source

Programmatically activate the currently-selected item in the list, if any.

clearList :: Widget (List a b) -> IO ()Source

Clear the list, removing all elements. Does not invoke any handlers.

setSelected :: Widget (List a b) -> Int -> IO ()Source

Set the currently-selected list index.

List inspection

getListSize :: Widget (List a b) -> IO IntSource

Get the length of the list in elements.

getSelected :: Widget (List a b) -> IO (Maybe (Int, ListItem a b))Source

Get the currently-selected list item.

getListItem :: Widget (List a b) -> Int -> IO (Maybe (ListItem a b))Source

Get the list item at the specified position.