Widgets Module¶

The tacotui.widgets module has simple user interface widgets, such as message boxes, list selection boxes, and forms. These widgets are displayed one-at-a-time, creating a linear user interface.

All widgets use the Theme colors for coloring. To adjust the widget colors, the theme color must be changed.

Message box

tacotui.widgets.box(x, y, w, h)¶

Draw a box

Parameters:	x (int) – Left side of the box y (int) – Top side of the box w (int) – Width of the box h (int) – Height of the box

tacotui.widgets.message(s, buttons=None, **kwargs)¶

Show a message box with optional buttons

Keyword Arguments:
Parameters:	s (string) – Message to display buttons (list) – List of button names
	y (x,) – Coordinates of message box
Returns:	btn – Text of the selected button, or None if no buttons are defined.
Return type:	string

Geting values from the user¶

The line_edit function returns a string entered by the user. Other widgets get_int, get_float, get_char, and get_date restrict the input to a specific type, and print an error if an invalid value is entered.

Line Edit box

tacotui.widgets.line_edit(s='', prompt='', **kwargs)¶

Enter a line of text, with possible initial value

Keyword Arguments:
Parameters:	s (string) – Default value for line edit prompt (string) – Text to show in front of entry area
	y (x,) – Position of line edit
Returns:	value – Line entered by the user
Return type:	string

tacotui.widgets.get_int(prompt, **kwargs)¶

Get an integer value.

Keyword Arguments:
Parameters:	prompt (string) – Prompt to show the user
	y (x,) – Location to display prompt. An error message will display on the next line if a non-integer value is entered.
Returns:	value – Integer value entered by the user
Return type:	int

tacotui.widgets.get_float(prompt, **kwargs)¶

Get a float value.

Keyword Arguments:
Parameters:	prompt (string) – Prompt to show the user
	y (x,) – Position for the prompt. If invalid or out-of-range value is entered, error message is shown on the next line. fmin (float) – Minimum acceptable float value fmax (float) – Maximum acceptable float value
Returns:	value – Floating point value entered by the user
Return type:	float

tacotui.widgets.get_char(options=None, **kwargs)¶

Input a character.

Keyword Arguments:
	options (list, optional) – List of acceptable characters y (x,) – Location for showing error message if the entered character is not in options.
Returns:	value – Single-character string entered by the user
Return type:	string

tacotui.widgets.get_date(prompt, **kwargs)¶

Get a date-time (requires dateutil package)

Parameters:	prompt (string) – Prompt to show the user y (x,) – Position of prompt. If invalid date is entered, error message will show on next line.
Returns:	value – Date value entered by the user
Return type:	datetime

Selecting from a list¶

List select and multiselect allow selection from a predefined list of items.

List Select Widget

tacotui.widgets.list_select(options, prompt='', **kwargs)¶

Select an item from a list

Parameters:

options (list) – List of items for the list box
prompt (string) – Text to show just above the box

Keyword Arguments:

y (x,) – Position of the box. If not provided, will be centered on the screen.
h (w,) – Width and height of box. If not provided, will be determined based on the size of the options list.

Returns:

index (int) – Index of list item selected by the user
value (string) – String of list item selected by the user

tacotui.widgets.multi_select(options, prompt='', **kwargs)¶

Select multiple items from a list.

Parameters:

options (list) – List of options to show in the box
prompt (string) – Text to show just above the box

Keyword Arguments:

y (x,) – Position of the box. If not provided, will be centered on the screen.
h (w,) – Width and height of box. If not provided, will be determined based on the size of the options list.

Returns:

index (list of int) – List of all indexes selected by the user
values (list of string) – List of all strings values selected by the user

Selecting files and folders¶

The file_select widget can be used to select an existing file, name a new file, or select an existing folder.

File select widget

tacotui.widgets.file_select(path='.', mode='existing', **kwargs)¶

Select a file or folder.

Keyword Arguments:
Parameters:	path (string) – Starting folder location mode (string) – File selection mode. Either ‘existing’, ‘new’, or ‘folder’.
	y (x,) – Top-left position of the file selection box. Defaults to 0, 0. h (w,) – Width and height of file selection box. Defaults to fill the full screen. showhidden (bool) – Show hidden files (starting with dot) filt (iterable) – List of file extensions to show, example [‘py’, ‘pyc’, ‘pyo’]
Returns:	fname – File or folder name as entered by the user
Return type:	string

Progress and slider¶

Slider Widget

tacotui.widgets.slider(prompt='', **kwargs)¶

Make a slider widget

Parameters:	prompt (string) – Text to show above the widget y (x,) – Top-left position of the widget w (int) – Width in characters of the slider maxval (minval,) – Miniumum and Maximum value represented by the slider showval (bool) – Whether to print the represented value to the right of the slider char (string) – Character to represent slider indicator color (string) – Color of slider indicator barcolor (string) – Color of slider bar
Returns:	value – Slider value when user presses enter
Return type:	float

Progress bar

tacotui.widgets.progress(pct, prompt='', **kwargs)¶

Progress bar

Keyword Arguments:
Parameters:	pct (float) – Percent value to show (0-100 range) prompt (string) – Text to show above progress bar
	y (x,) – Position of top left corner w (int) – Width of the progress bar c (string) – Color of indicator ch (string) – Character for indicator showpct (bool) – Print the percent value to the right of the indicator

Forms¶

The form widget allows for multiple widgets at once in a single form. The form returns a list of responses for each item.

Form widget

tacotui.widgets.form(title='', *items, **kwargs)¶

Make a form for entry of multiple items.

Keyword Arguments:
Parameters:	title (string) – Show a title on the form items (tuples) – Each row in the form is defined by a tuple of (prompt, datatype, [default], [key]) prompt: string value to show in this line datatype: either int, float, str, or a list of option values (selectable by arrow keys in the form) default (optional): initial value to show.
	y (x,) – Top left position of the form w (int) – Width of the form
Returns:	values – List of all items entered in the form, in the same order they were defined, cast to the appropriate type.
Return type:	list

Notes

int and float datatypes will be validated. User cannot select DONE until they enter valid numbers (or leave them blank). floats in scientific notation are allowed.

Data visualization¶

Quick and dirty plotting is available in the command line. While limited, these functions provide basic line and bar plotting functionality without requiring large plotting packages.

Textplot

Bar plot

tacotui.widgets.textplot(*xypairs, **kwargs)¶

Plot x, y data as scatter plot

Parameters:

xypairs (tuples of lists) – Each xypair is a tuple of (x, y) data, where x and y are lists of values to plot.
y (x,) – Top-left position of plot
w (int) – Plot width in characters
h (int) – Plot height in characters
title (string) – Title to print above the plot
margin (int) – Size of left-side margin
colors (list of string) – List of color codes to cycle for the plot points
markers (list of string) – List of characters to cylce for the plot points

tacotui.widgets.barplot(*xypairs, **kwargs)¶

Make a horizontal bar plot

Keyword Arguments:
Parameters:	xypairs (tuples) – Tuples of (xlabel, yvalue)
	y (x,) – Top-left position of bar plot w (int) – Total width of bar plot char (string) – Character to use for bar segment showvals (bool) – Print the numeric value at the end of each bar colors (list) – List of colors to cycle

Widgets Module¶

Geting values from the user¶

Selecting from a list¶

Selecting files and folders¶

Progress and slider¶

Forms¶

Data visualization¶

tacotui

Navigation

Related Topics