vty-ui-0.4: A user interface composition library for Vty

Graphics.Vty.Widgets.List

Contents

Description

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

Synopsis

Documentation

data List a Source

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

mkListSource

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.

mkSimpleListSource

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.

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)

scrollUp :: List a -> List aSource

Scroll a list up by one position.

scrollDown :: List a -> List aSource

Scroll a list down by one position.

pageUp :: List a -> List aSource

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

pageDown :: List a -> List aSource

Scroll a list down by one page from the current cursor 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

listItems :: List a -> [ListItem a]Source

The items in the list.

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.

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

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.