Picker

Picker

Note: This wiki is still in construction and is incomplete

The Picker class is a versatile, terminal-based table picker component built on curses. It provides interactive selection, filtering, pagination, sorting, and customizable UI features. This guide documents all configuration options available in the constructor. It is the heart of the listpick library.

In this page I will go through all of the options that can be given for a Picker object. This a basic template for setting up the environment and starting the Picker:

from listpick.listpick_app import Picker, close_curses, start_curses

l = [["1", "2"], ["3", "4"]]
header=["H1", "H2"]

stdscr = start_curses()
x = Picker(
        stdscr = stdscr,
        items = l,
        title="Test Picker",
        header=header,
        highlights=highlights,
    )
selected_indices, opts, picker_data = x.run()

close_curses(stdscr)

Core parameters

Name	Type	Default	Description
stdscr	curses.window	Required	The main curses screen object.
items	list[list[str]]	[]	List of rows, where each row is a list of string values.
cursor_pos	int	0	Initial cursor position.
colours	dict	get_colours(0)	A mapping of colour names to curses colour pairs.
colour_theme_number	int	0	Theme index for selecting colour schemes.
max_selected	int	-1	Maximum number of items that can be selected (-1 = no limit).
top_gap	int	0	Empty lines to show at the top of the display.
title	str	"Picker"	Title displayed at the top of the screen.
header	list	[]	Column headers.
max_column_width	int	70	Maximum width for any column.
clear_on_start	bool	False	Whether to clear the screen before rendering.
display_only	bool	False	View-only mode (no input).

Refresh function

Name	Type	Default	Description
auto_refresh	bool	False	Enable periodic refreshing.
timer	float	5	Time interval (in seconds) between refreshes.
get_new_data	bool	False	Whether new data can be fetched.
refresh_function	Callable	lambda: []	Function used to get updated data.
get_data_startup	bool	False	Whether to fetch data on startup.
track_entries_upon_refresh	bool	True	Preserve selections between refreshes.
id_column	int	0	Column used to identify rows across refreshes.

Visual options

Name	Type	Default	Description
highlight_full_row	bool	False	Highlight the full row instead of specific cells.
number_columns	bool	True	Display numbered columns.
paginate	bool	False	Enable pagination view.
scroll_bar	int	True	Display a scroll bar.
separator	str	"    "	Separator between columns.
centre_in_terminal	bool	False	Center the picker horizontally.
centre_in_terminal_vertical	bool	False	Center vertically.
centre_in_cols	bool	False	Center within available columns.

Highlights

Name	Type	Default	Description
unselectable_indices	list	[]	Indices of rows that cannot be selected.
highlights	list	[]	Indices of rows or values to highlight.
highlights_hide	bool	False	Hide highlights if enabled.

Navigation State

Name	Type	Default	Description
current_row	int	0	Row index currently selected.
current_page	int	0	Current page number. Relevant for pagination.
is_selecting	bool	False	Whether in visual selection mode.
is_deselecting	int	False	Whether in visual deselection mode.
start_selection, end_selection	int	-1	For multi-row selection.
selections	dict	{}	Initially selected items.
startup_notification	str	""	Message shown when picker starts.

Data state

Name	Type	Default	Description
indexed_items	list[Tuple[int, list[str]]]	[]	Currently visible rows with their original indices.
sort_method	int	0	Sort algorithm (custom defined).
sort_reverse	list[bool]	[False]	Reversal flags per column.
sort_column	int	0	Column used for sorting.
columns_sort_method	list[int]	[0]	Per-column sort methods.

User interatction

Name	Type	Default	Description
user_opts, user_settings	str	""	User input metadata or preferences.
search_query, filter_query	str	""	Search and filter text.
search_count, search_index	int	0	Track search results and positions.
hidden_columns	list	[]	Columns to hide from view.

Input Handling

Name	Type	Default	Description
key_chain	str	""	Sequence of pressed keys.
last_key	Optional[str]	None	Last key pressed.
keys_dict	dict	picker_keys	Keybindings dictionary.
key_remappings	dict	{}	Custom key remappings.
disabled_keys	list	[]	List of disabled keys.
cancel_is_back	bool	False	Cancel key (escape) acts like "back". Useful for options and notifications.

Name	Type	Default	Description
mode_index	int	0	Active mode index.
modes	list[dict]	[{}]	Mode definitions.
display_modes	bool	False	Show available modes.

Options

Name	Type	Default	Description
require_option	list	[]	List of indices that cannot be submutted until an option is specified.
option_functions	list[Callable]	[]	Functions executed when options are selected. Default option function is user input. You can also pass a list to options dialogue to ensure that only one of a specific subset is given.

Footer

Name	Type	Default	Description
show_footer	bool	True	Display footer area.
footer_string	str	""	Static footer text.
footer_string_auto_refresh	bool	False	Auto-refresh footer content.
footer_string_refresh_function	Optional[Callable]	None	Function for footer string refresh.
footer_timer	float	1	Refresh rate for footer string.
get_footer_string_startup	bool	False	Whether to fetch footer string on startup.

Infobox

Name	Type	Default	Description
display_infobox	bool	False	Show side infobox.
infobox_items	list[list[str]]	[]	Items in the infobox.
infobox_title	str	""	Title of the infobox.

---

Not yet documented

Name	Type	Default	Description
column_widths	list	[]	Custom widths for each column.
column_indices	list	[]	Visible column indices.
items_per_page	int	-1	Items to show per page (-1 = fit to screen).
colours_start, colours_end	int	0, -1	Colour range for display.
editable_columns	list[int]	[]	Columns editable by user.