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.
- command_lines¶
Provides the command line interface.
- Type:
- scroller¶
Adds scrolling functionality to
command_lines
.- Type:
- arrow_up¶
An arrow button that can be clicked to scroll the screen up.
- Type:
- arrow_down¶
An arrow button that can be clicked to scroll the screen down.
- Type:
- __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:
- edit¶
This widget provides the functionality for displaying and editing text.
- Type:
- __init__(inputfile, outputfile)¶
Initialize a new
CommandLines
object.The arguments set the values of
inputfile
andoutputfile
.
- 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 givehistory
andtemp_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 (throughupdate_command()
), the modified versions are saved here, whilehistory
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]
andindex
to0
.
- 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:
- 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:
- render(size, focus=False)¶
Render the visible portion of the scrollable widget, update
position
and return anurwid.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
orrelative
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:
- visible_rows¶
Like
total_rows
, but only counts the rows visible on the screen.- Type:
- relative¶
A relative scroll position between
0
(scrolled to the top) and1
(scrolled to the bottom). Changing this also changes the value ofabsolute
. Values below0
are set to0
and values above1
to1
.- Type:
- 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 below0
are set to0
and values abovemax_absolute
tomax_absolute
.- Type:
- 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.
- 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
andbackground_char
.
- render(size, focus=False)¶
Generate the scroll bar and render it.
- 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:
- __init__(symbol, step, position)¶
Initialize a new
ScrollButton
.