Module textredux.core.list

The list module provides a text based item listing for Textadept, featuring advanced search capabilities and styling.

How to use

Create the list using new, specify items and other fields/callbacks (such as on_selection) and invoke list:show.

Please see also the various list examples in ./examples.

Features

• Support for multi-column table items, in addition to supporting the simpler case of just listing strings.
• Fully customizable styling. You can either specify individual styles for different columns, or specify styles for each item dynamically using a callback.
• Powerful search capabilities. The list class supports both exact matching and fuzzy matching, and will present best matches first. It also supports searching for multiple search strings (any text separated by whitespace is considered to be multiple search strings). Searches are done against all columns.
• Ctrl/Alt/Meta-Backspace resets the current search.

Functions

new (title, items, on_selection)	Creates a new list.
show ()	Shows the list.
get_current_selection ()	Returns the currently selected item if any, or nil otherwise.
close ()	Closes the list.
get_current_search ()	Returns the current user search if any, or nil otherwise.
set_current_search (search)	Sets the current user search.

Tables

column_styles

The default styles to use for different columns.

Fields

header_style	The default style to use for diplaying headers.
match_highlight_style	The style to use for indicating matches.
search_case_insensitive	Whether searches are case insensitive or not.
search_fuzzy	Whether fuzzy searching should be in addition to explicit matches.

List instance fields

headers	Optional headers for the list.
items	A table of items to display in the list.
on_selection	The handler/callback to call when the user has selected an item.
on_new_selection	The handler/callback to call when the user has typed in text which doesn't match any item, and presses <enter>.
buffer	The underlying textredux.core.buffer used by the list.
keys	A table of key commands for the list.
data	A general purpose table that can be used for storing state associated with the list.

Functions

new (title, items, on_selection)

Creates a new list.

Parameters:

• title The list title
• items The list items, see items. Not required, items can be set later using the items field.
• on_selection The on selection handler, see on_selection. Not required, this can be specified later using the on_selection field.

Returns:

The new list instance

show ()

Shows the list.

get_current_selection ()

Returns the currently selected item if any, or nil otherwise.

close ()

Closes the list.

get_current_search ()

Returns the current user search if any, or nil otherwise.

set_current_search (search)

Sets the current user search.

Parameters:

• search The search string to use

Tables

column_styles

The default styles to use for different columns. This can be specified individually for each list as well. Values can either be explicit styles, defined using textredux.core.style, or functions which returns explicit styles. In the latter case, the function will be invoked with the corresponding item and column index. The default styles contains styles for up to three columns, after which the default style will be used.

Fields:

• reduxstyle
• reduxstyle
• reduxstyle

Fields

header_style

The default style to use for diplaying headers. This is by default the style.list_header style. It's possible to override this for a specific list by assigning another value to the instance itself.

match_highlight_style

The style to use for indicating matches. You can turn off highlighing of matches by setting this to nil. It's possible to override this for a specific list by assigning another value to the instance itself. The default value is style.default.

search_case_insensitive

Whether searches are case insensitive or not. It's possible to override this for a specific list by assigning another value to the instance itself. The default value is true.

search_fuzzy

Whether fuzzy searching should be in addition to explicit matches. It's possible to override this for a specific list by assigning another value to the instance itself. The default value is true.

List instance fields

These can be set only for a list instance, and not globally for the module.

headers

Optional headers for the list. If set, the headers must be a table with the same number of columns as items.

items

A table of items to display in the list. Each table item can either be a table itself, in which case the list will be multi column, or a string in which case the list be single column.

on_selection

The handler/callback to call when the user has selected an item. The handler will be passed the following parameters:

• list: the list itself
• item: the item selected

on_new_selection

The handler/callback to call when the user has typed in text which doesn't match any item, and presses <enter>.

The handler will be passed the following parameters:

• list: the list itself
• search: the current search of the list

buffer

The underlying textredux.core.buffer used by the list.

keys

A table of key commands for the list. This functions almost exactly the same as textredux.core.buffer.keys. The one difference is that for function values, the parameter passed will be a reference to the list instead of a buffer reference.

data

A general purpose table that can be used for storing state associated with the list. Just like textredux.core.buffer.data, the data table is special in the way that it will automatically be cleared whenever the user closes the buffer associated with the list.