widgets

This module uses the urwid library to create widgets (see urwid.Widget) for a text-based user interface containing a scrollable command line interface below a text screen.

The docstring of each widget defined here tells whether it is a box, flow or fixed widget. The differences between these widget types are explained here.

class turboctl.ui.widgets.ScrollableCommandLines(inputfile, outputfile)

A widget consisting of a scrollable command line interface and a scroll bar with two arrow buttons for scrolling it.

This is a box widget; its container sets it height and width.

position

Keeps track of how far the screen is scrolled.

Type:

Position

command_lines

Provides the command line interface.

Type:

CommandLines

scroller

Adds scrolling functionality to command_lines.

Type:

Scroller

scrollbar

The scroll bar.

Type:

ScrollBar

arrow_up

An arrow button that can be clicked to scroll the screen up.

Type:

ScrollButton

arrow_down

An arrow button that can be clicked to scroll the screen down.

Type:

ScrollButton

__init__(inputfile, outputfile)

Initialize a new ScrollableCommandLines.

The arguments are passed to the initializer of command_lines.

class turboctl.ui.widgets.CommandLines(inputfile, outputfile)

This widget provides a terminal-like command line interface.

Entering commands scrolls the screen automatically so that the latest command is always visible on the screen, but the functionality to scroll up to view old commands is provided by the Scroller class instead of this class.

This is a flow widget; its container sets it height but not width.

inputfile

Input entered into the command-line interface by the user is written to this object.

Type:

file-like object

outputfile

The command-line interface reads its output from this object and prints it on the screen.

Type:

file-like object

history

This object stores previously given commands.

Type:

CommandHistory

edit

This widget provides the functionality for displaying and editing text.

Type:

urwid.Edit

__init__(inputfile, outputfile)

Initialize a new CommandLines object.

The arguments set the values of inputfile and outputfile.

move_cursor_to_end()

Move the cursor to the end of the editable string.

update()

Print the string returned by outputfile.read() to the screen.

history_up()

Scroll command history up one step.

Calling this function has approximately the same effect as pressing the up arrow button in a Linux terminal.

history_down()

Scroll command history down one step.

Calling this function has approximately the same effect as pressing the down arrow button in a Linux terminal.

enter()

Enter the current editable string as a command.

keypress(size, key)

Handle key presses.

The up and down arrow keys are used to browse command history. Enter enters a command.

Returns:

None if the key press was handled by this widget, key if it was not.

class turboctl.ui.widgets.CommandHistory

A class to store command history.

This class emulates the command history browsing behaviour of a typical Linux terminal.

history

A list of previously entered commands. Index 0 is set to None to give history and temp_history the same length.

temp_history

The same as history, but includes the newest command (the one that is currently being written) at index 0. If any previously given commands are modified (through update_command()), the modified versions are saved here, while history contains the original ones.

index

The index of the currently selected command. 0 is the command currently being written; 1 is the previous one etc.

__init__()

Initialize history to [], temp_history to [None] and index to 0.

up()

Increase index by 1 (i.e. select a command that is older than the current one).

If the current command is the oldest one, nothing is done.

down()

Decrease index by 1 (i.e. select a command that is newer than the current one).

If the current command is the newest one, nothing is done.

get_command()

Return the currently selected command as a string.

update_command(string)

Change the currently selected command into string.

enter_command()

Enter the currently selected command.

This saves the command into memory and and resets index to 0. If the command was created by modifying a previous command, that command’s history entry will be reset into its original form. If multiple identical commands are entered consecutively, only one is saved; empty commands are not saved at all.

class turboctl.ui.widgets.Scroller(widget, position)

A container widget that makes a flow widget scrollable.

This is a box widget; its container sets it height and width.

widget

The widget to be made scrollable. This should be a flow widget.

Type:

urwid.Widget

position

An object to keep track of how far the widget is scrolled. The same Position object should be shared among all objects that can scroll the widget (e.g. the scroll bar).

Type:

Position

__init__(widget, position)

Initialize a new Scroller.

The arguments set the values of widget and position.

render(size, focus=False)

Render the visible portion of the scrollable widget, update position and return an urwid.Canvas object.

mouse_event(size, event, button, col, row, focus)

Handle mouse events.

The mouse wheel scrolls the terminal up and down.

Returns:

True if the event was handled by this widget, False otherwise.

keypress(size, key)

Handle key presses.

Pressing any key scrolls the terminal to the bottom so that the current command can be edited.

Returns:

None if the key press was handled by this widget, key if it was not.

class turboctl.ui.widgets.Position(listeners=None)

A class to keep track of the position to which a widget made scrollable with Scroller has been scrolled.

listeners

The widgets that should be re-rendered whenever absolute or relative is changed.

Type:

iterable

total_rows

The height of the scrollable widget in rows, including those that are not currently visible on the screen. Empty rows are also included. The Scroller widget should update this attribute whenever it is rendered.

Type:

int

visible_rows

Like total_rows, but only counts the rows visible on the screen.

Type:

int

relative

A relative scroll position between 0 (scrolled to the top) and 1 (scrolled to the bottom). Changing this also changes the value of absolute. Values below 0 are set to 0 and values above 1 to 1.

Type:

float

absolute

An absolute scroll position given as the number of invisible rows that are located above the top edge of the widget. Changing this also changes the value of relative. Values below 0 are set to 0 and values above max_absolute to max_absolute.

Type:

int

__init__(listeners=None)

Initialize a new Position object.

Parameters:

listeners (iterable) – The initial value for listeners. This may be changed later. If no value is given, listeners is initialized to set().

property max_absolute

The maximum value of absolute, equal to total_rows - visible_rows.

class turboctl.ui.widgets.ScrollBar(position, scroller_char='█', background_char='░')

A widget that provides a vertical scroll bar.

This is a box widget; its container sets it height and width.

position

An object used to keep track of how far the screen is scrolled.

Type:

Position

scroller_char

The character used to draw the moving part of the scroll bar.

Type:

single-character str

background_char

The character used to draw the other parts of the scroll bar.

Type:

single-character str

__init__(position, scroller_char='█', background_char='░')

Initialize a new scrollbar.

The arguments set the values of position, scroller_char and background_char.

render(size, focus=False)

Generate the scroll bar and render it.

mouse_event(size, event, button, col, row, focus)

Handle mouse events.

Mouse button 1 moves the scroller so that clicking the scroll bar at a point X % from its top will set position.relative to X / 100.

Returns:

True if the event was handled by this widget, False otherwise.

class turboctl.ui.widgets.ScrollButton(symbol, step, position)

A widget that can be clicked with the mouse to scroll another widget.

This is a box widget; its container sets it height and width.

step

The amount of rows scrolled when this widget is clicked. Negative values are used to scroll towards the top of the scrollable widget, positive values towards the bottom.

Type:

int

position

An object used to keep track of how far the scrollable widget is scrolled.

Type:

Position

__init__(symbol, step, position)

Initialize a new ScrollButton.

Parameters:

• symbol (str) – The character or string that is displayed on the button.

• step – The value of step.

• position – The value of position.

mouse_event(size, event, button, col, row, focus)

Handle mouse events.

A left click scrolls the scrollable widget by step rows.

Returns:

True if the event was handled by this widget, False otherwise.