howl.ui.List
Overview
List provides support for showing and updating a selection list in given buffer. It displays a list of options with one option highlighted - the selected item. The List component provides native support for optional filtering the items as it’s built around the concept of a ‘matcher’, which provides matching items given a search string.
See also:
- The ListWidget widget
- The spec for List
Constructor
List (matcher, opts={})
Creates a new List.
matcher
is a function that accepts a string and returns an table. Each element in this table represents one select-able option and can be either a string for a single column list, or a table for a multiple column list. When each item is a table, it contains a list of items, one each for each column. Each item can be either a string, a StyledText object, or something that can be converted to one of those two.
It is also possible to request that particular segments of an item are
highlighted for a particular item as it’s displayed, by defining a
.item_highlights
table on the item itself (see the Item
highlights section at the end of this section).
The matcher
is called on initialization and whenever the
update() function is called. The search_text
argument provided in
update()
is passed to the matcher
and the displayed items are replaced with
the new list of items returned from the matcher
.
opts
is a table of options which can contain the following fields:explain
: [optional] A callable object used for providing highlighting information. The object is invoked with the search text and the full text of the list item’s line. It should return a list of highlight segments. Each segment is expected to itself be a list of two numbers: The first number should indicate the start position of the highlight, and the second number the number of characters to highlight.filler_text
: [optional, default:‘~’] The text displayed to fill up extra space below the list of items, when the number of displayed list items are fewer than.min_rows
.on_selection_change
: [optional] A callback function that is invoked whenver the currently selected item changes. The callback is called with the newly selected item as the only argument.reverse
: [optional, default:false] Whentrue
, displays the items in reverse order, with the first item shown at the bottom and subsequent items above it.
Item highlights
Certain segments of an item can be highlighted as they are displayed, if a
item_highlights
table is specified for the item. Such a table should have one
sub table for each list column for which highlights should be applied,
containing one or more highlighting specifications indicating the start and end
position of the highlight, relative to the item column.
Start positions can be specified by using one of the below:
start_column
: The starting column of the highlightbyte_start_column
: The starting byte-oriented column of the highlightEnd positions can be specified by using one of the below:
end_column
: The ending column of the highlightbyte_end_column
: The ending byte-oriented column of the highlightcount
: The end position iscount
characters away from the start position
Properties
columns
A table specifying a header and styles for each column. The schema of this table
is identical to the columns
argument in the
StyledText.for_table function.
Read/write.
items
A table containing the items currently displayed. Read-only.
max_rows
The maximum number of total rows occupied by the list. This includes any header and status rows. Should the size be small enough that not all items can be shown the list will show a sub set of items along with a pagination indicator at the bottom. Read/write.
min_rows
The minimum number of total rows occupied by the list. If the number of items aren’t sufficient to fill up the number of rows, filler text is displayed on each line to fill the extra space. Read/write.
offset
The index of the first item currently shown. Always 1 unless the list is constrained by max_rows.
page_size
The number of items currently shown. Always equal to the number of items unless the list is constrained by max_rows.
rows_shown
The number of rows used by the list in the buffer.
selected
The currently selected item. Read/write.
Methods
draw ()
“Draws” the list into the associated buffer, i.e. inserts or updates the list in the buffer.
insert (buffer)
Associates the list with the specified buffer
. Any subsequent calls to
draw or update will cause the list to be drawn into the
given buffer.
next_page ()
Displays the next page of the list’s item.
on_refresh (listener)
Adds a listener to the list. The listener will be invoked every time the list is redrawn in the associated buffer, and will be passed the list as the sole argument.
prev_page ()
Displays the previous page of the list’s item.
select_next ()
Selects the next item in the list. Causes the list to scroll if neccessary.
select_prev ()
Selects the previous item in the list. Causes the list to scroll if neccessary.
update (search_text, preserve_position = false)
Updates the list of displayed items to the items returned by calling
matcher(search_text)
. See matcher
in the constructor above.
If preserve_position
is true, the current position in the list is maintained
if possible.