Brick.Widgets.List

List state. Lists have a container t of element type e that is the data stored by the list. When using the event-handling functions provided by this module, Lists handle the following events:

• Up/down arrow keys: move cursor of selected item

• Page up / page down keys: move cursor of selected item by one page at a time (based on the number of items shown)

• Home/end keys: move cursor of selected item to beginning or end of list

Movement key behaviors (and their corresponding list transformation functions) are subject to wrapping if the list's wrapping is enabled; in that case, attempts to move the selection beyond either end of the list will wrap the selection to the opposite end of the list. When wrapping is disabled, attempts to move beyond either end of the list will move the selection as far as possible without wrapping around to the opposite end. To control whether wrapping is enabled, see setScrollWrap.

The List type synonym fixes t to Vector for compatibility with previous versions of this library.

For a container type to be usable with GenericList, it must have instances of Traversable and Splittable. The following functions impose further constraints:

• listInsert: Applicative and Semigroup

• listRemove: Semigroup

• listClear: Monoid

• listReverse: Reversible

An alias for GenericList specialized to use a Vector as its container type.

Construct a list, with wrapping initially disabled, in terms of container t with element type e.

Sets the list's wrapping behavior; wrapping is enabled if given True, or disabled if given False.

Returns the list's wrapping setting; returns True if wrapping is enabled or False otherwise.

Render a list using the specified item drawing function.

Evaluates the underlying container up to, and a bit beyond, the selected element. The exact amount depends on available height for drawing and listItemHeight. At most, it will evaluate up to element (i + h + 1) where i is the selected index and h is the available height.

Note that this function renders the list with the listAttr as the default attribute and then uses listSelectedAttr as the default attribute for the selected item if the list is not focused or listSelectedFocusedAttr otherwise. This is provided as a convenience so that the item rendering function doesn't have to be concerned with attributes, but if those attributes are undesirable for your purposes, forceAttr can always be used by the item rendering function to ensure that another attribute is used instead.

Like renderList, except the render function is also provided with the index of each element.

Has the same evaluation characteristics as renderList.

Handle events for list cursor movement. Events handled are:

• Up (up arrow key)

• Down (down arrow key)

• Page Up (PgUp)

• Page Down (PgDown)

• Go to first element (Home)

• Go to last element (End)

Enable list movement with the vi keys with a fallback handler if none match. Use handleListEventVi in place of handleListEvent to add the vi keys bindings to the standard ones. Movements handled include:

• Up (k)

• Down (j)

• Page Up (Ctrl-b)

• Page Down (Ctrl-f)

• Half Page Up (Ctrl-u)

• Half Page Down (Ctrl-d)

• Go to first element (g)

• Go to last element (G)

Traversal that targets the selected element, if any.

Complexity: depends on usage as well as the list's container type.

listSelectedElementL for List: O(1) -- preview, fold
                               O(n) -- set, modify, traverse
listSelectedElementL for Seq: O(log(min(i, n - i)))  -- all operations

The list's sequence of elements.

The list's name.

Return a list's selected element, if any.

Only evaluates as much of the container as needed.

Complexity: same as splitAt for the container type.

listSelectedElement for List: O(1)
listSelectedElement for Seq: O(log(min(i, n - i)))

The list's selected element index, if any.

The height of an individual item in the list.

Move the list selected index.

If the current selection is Just x, the selection is adjusted by the specified amount. Whether the value is clamped to the extents of the list or not (i.e. whether the selection doesn't wrap around the list or it does), is determined by the list itself (see GenericList for more info).

If the current selection is Nothing (i.e. there is no selection) and the direction is positive, set to Just 0 (first element), otherwise set to Just (length - 1) (last element).

Complexity: same as splitAt for the container type.

listMoveBy for List: O(1)
listMoveBy for Seq: O(log(min(i,n-i)))

Set the selected index for a list to the specified index, subject to validation.

If pos >= 0, indexes from the start of the list (which gets evaluated up to the target index)

If pos < 0, indexes from the end of the list (which evaluates length of the list).

Complexity: same as splitAt for the container type.

listMoveTo for List: O(1)
listMoveTo for Seq: O(log(min(i,n-i)))

Set the selected index for a list to the index of the first occurrence of the specified element if it is in the list, or leave the list unmodified otherwise.

O(n). Only evaluates as much of the container as needed.

Starting from the currently-selected position, attempt to find and select the next element matching the predicate. If there are no matches for the remainder of the list or if the list has no selection at all, the search starts at the beginning. If no matching element is found anywhere in the list, leave the list unmodified.

O(n). Only evaluates as much of the container as needed.

Move the list selected index up by one (moves the cursor up, subtracts one from the index), subject to wrapping.

Move the list selected index down by one (moves the cursor down, adds one to the index), subject to wrapping.

Move the list selected index by some (fractional) number of pages, subject to wrapping.

Move the list selected index up by one page.

Move the list selected index down by one page.

Move the list selection to the first element in the list.

Move the list selection to the last element in the list.

Insert an item into a list at the specified position.

Complexity: the worse of splitAt and <> for the container type.

listInsert for List: O(n)
listInsert for Seq: O(log(min(i, length n - i)))

Remove an element from a list at the specified position.

Applies splitAt two times: first to split the structure at the given position, and again to remove the first element from the tail. Consider the asymptotics of splitAt for the container type when using this function.

Complexity: the worse of splitAt and <> for the container type.

listRemove for List: O(n)
listRemove for Seq: O(log(min(i, n - i)))

Replace the contents of a list with a new set of elements and update the new selected index. If the list is empty, empty selection is used instead. Otherwise, if the specified selected index (via Just) is not in the list bounds, zero is used instead.

Complexity: same as splitAt for the container type.

Remove all elements from the list and clear the selection.

O(1)

Reverse the list. The element selected before the reversal will again be the selected one.

Complexity: same as reverse for the container type.

listReverse for List: O(n)
listReverse for Seq: O(n)

Apply a function to the selected element. If no element is selected, the list is not modified.

Complexity: same as traverse for the container type (typically O(n)).

Complexity: same as listSelectedElementL for the list's container type.

listModify for List: O(n)
listModify for Seq: O(log(min(i, n - i)))

Find the first element in the list that satisfies the specified predicate. If such an element is found, return the resulting index and element.

O(n).

The top-level attribute used for the entire list.

The attribute used only for the currently-selected list item when the list does not have focus. Extends listAttr.

The attribute used only for the currently-selected list item when the list has focus. Extends listSelectedAttr.

Ordered container types that can be split at a given index. An instance of this class is required for a container type to be usable with GenericList.

Ordered container types where the order of elements can be reversed. Only required if you want to use listReverse.