TextUI

• Index

Contents

• Functions
• Fields
• List instance fields

Modules

• _M.textui
• _M.textui.buffer
• _M.textui.indicator
• _M.textui.list
• _M.textui.style

Examples

• basic_list.lua
• buffer_actions.lua
• buffer_indicators.lua
• buffer_styling.lua
• list_commands.lua
• multi_column_list.lua
• styled_list.lua

Module _M.textui.list

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

It's a convenient way of presenting lists to the user for simple selection, but is equally well suited for creating advanced list based interfaces.

Features at a glance

• 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. If you do neither, you will automatically get sane defaults.
• 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.

How to use

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

Please see the various list examples for more hands on instructions.

Functions

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

Fields

header_style	The default style to use for diplaying headers.
match_highlight_style	The style to use for indicating matches.
column_styles	The default styles to use for different columns.
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 _M.textui.buffer used by the list
keys	A table of key commands for the list.
on_keypress	Callback invoked whenever the list receives a keypress.
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

list:show ()

Shows the list.

list:close ()

Closes the list.

list:get_current_selection ()

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

list:get_current_search ()

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

list:set_current_search (search)

Sets the current user search.

Parameters:

• search: The search string to use

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.

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 _M.textui.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.

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
• shift: True if the Shift key was held down.
• ctrl: True if the Control/Command key was held down.
• alt: True if the Alt/option key was held down.
• meta: True if the Control key on Mac OSX was held down.

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
• shift: True if the Shift key was held down.
• ctrl: True if the Control/Command key was held down.
• alt: True if the Alt/option key was held down.
• meta: True if the Control key on Mac OSX was held down.

buffer

The underlying _M.textui.buffer used by the list

keys

A table of key commands for the list. This functions almost exactly the same as _M.textui.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.

on_keypress

Callback invoked whenever the list receives a keypress. This functions almost exactly the sames as _M.textui.buffer.on_keypress. The one difference is that for function values, the first parameter passed will be a reference to the list instead of a buffer reference.

Please note that by overriding this it's possible to block any key presses from ever reaching the list itself.

see also:

keys

data

A general purpose table that can be used for storing state associated with the list. Just like _M.textui.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.