mmeson.tui module

Module implementing the urwid TUI (terminal user interface).

If you are unfamilir with urwid, take a look at the excellent documentation at http://urwid.org/.

The basic design consits of a urwid.Frame with Header as header and Footer as footer. The body consits of OptionList, which is a urwid.ListBox containing the OptionRow widgets. The urwid.ListBox widget requires a urwid.SimpleFocusListWalker, which emits a modified signal when the focused OptionRow changes. This is used to update the information in the Footer.

The OptionRow is a urwid.Columns with a urwid.Text showing the option name on the left and a custom MesonEdit widget on the to change the option value.

Currently, the MesonEdit class is a subclass of urwid.AttrMap to force the colored output, but this is a just an ugly workaround, in theory using TextMarkup (http://urwid.org/manual/displayattributes.html#text-markup) should suffice.

mmeson.tui.PALETTE = [('true', 'dark green', ''), ('false', 'dark red', ''), ('choice', 'light blue', ''), ('enabled', 'dark green', ''), ('disabled', 'dark red', ''), ('string', 'yellow', ''), ('integer', 'light magenta', ''), ('array', 'brown', '')]: Color Palette, see urwid’s manual for details.

class mmeson.tui.MesonEdit(widget: Widget, attr_map: dict)

Bases: AttrMap

Virtual widget class for editing option values.

Parameters

widget¶ – urwid.Widget to
attr_map¶ – dict or str for urwid.AttrMap. Workaround to change the color of the widget.

signals = ['changed']: list of urwid signal names the class can emit.

attr_map_from_str(color_name: str)

Creates an attribute map from a string to color the widget in a given color from PALETTE. This is a workaround to get colors working, there are urwid examples that do not need this for colored widgets.

Parameters: color_name¶ – Color name as in PALETTE.
Returns: dict formatted as {None: 'color_name'}.

get_value(): Virtual function to return the value contained in the widget.

class mmeson.tui.StringEdit(value: str, widget_color_name: str = 'string')

Bases: MesonEdit

MesonEdit widget to modify Option of type STRING. Uses urwid.Edit as base.

Parameters

value¶ – Initial value of the widget.
widget_color_name¶ – Text color from PALETTE as str (mainly for ArrayEdit).

activated: bool that control whether input is used for editing or not. See keypress().

get_value() → str

Returns: Value of the widget as str.

keypress(size, key)

Keypress handler for this widget.

The widget needs to be activated to forward keypresses. This is handled via the activated member, which is toggled when enter is pressed. If the activated is True, keypresses are forwarded to the containing widget (urwid.Edit). Additionally, when the activated member is changed from True to False, a changed signal is emitted. If activated is False, key is returned. This tells urwid that it is not used by the widget.

Parameters

size¶ – unused (given from urwid).
key¶ – key name (given from urwid).

class mmeson.tui.BooleanEdit(init_state: bool)

Bases: MesonEdit

MesonEdit widget to modify Option of type BOOLEAN. Uses urwid.SelectableIcon as base.

Parameters: init_state¶ – value for the initial value of state.

state: bool of the current value.

set_state(state: bool) → None

Set a new state, change color of the urwid.AttrMap and emit a changed signal.

Parameters: state¶ – bool of the new state.

get_value() → bool

Returns: Value of the widget as bool.

toggle_state() → None: Toggle the current state.

keypress(size, key)

Keypress handler for this widget. Taken from urwid.CheckBox.

Parameters

size¶ – unused (given from urwid).
key¶ – key name (given from urwid).

class mmeson.tui.ComboEdit(init_choice: str, choices: list[str])

Bases: MesonEdit

MesonEdit widget to modify Option of type COMBO. Uses urwid.SelectableIcon as base.

Parameters

init_choice¶ – Value used for the initial value of choice_index.
choices¶ – List of valid choices.

choice_index: int refering to the index of the currently selected choice.

choices: List of valid choices.

create_attr_map(choice: str) → dict

Creates an attribute map for the widget. Workaround to adjust the color of the widget depending on the choice. For enabled, true, disabled and false the color is defined in PALETTE, for other choices use the choice color defined in PALETTE.

Parameters: choice¶ – choice to return color / attribute dict for.
Returns: dict formatted as {None: 'color_name'}.

set_choice(choice_index: int) → None

Set a new choice, change color of the urwid.AttrMap and emit a changed signal.

Parameters: choice_index¶ – int new choice index for choice_index.

get_choice() → str

Returns: Current selected choice as str.

get_value() → str

Returns: Value of the widget as str.

rotate_choice() → None: Select next choice in choices list.

keypress(size, key): Keypress handler for this widget. Same as BooleanEdit.keypress().

class mmeson.tui.IntegerEdit(value: int)

Bases: MesonEdit

MesonEdit widget to modify Option of type INTEGER. Uses urwid.IntEdit as base.

Parameters: value¶ – Initial value of the widget.

activated: See StringEdit.activated.

get_value() → int

Returns: Value of the widget as int.

keypress(size, key): Keypress handler for this widget. Similar to StringEdit.keypress().

class mmeson.tui.ArrayEdit(value: list[str])

Bases: StringEdit

MesonEdit widget to modify Option of type ARRAY. Uses StringEdit as base.

Parameters: value¶ – Initial value of the widget.

get_value() → list[str]

Returns: Value of the widget as list of str.

class mmeson.tui.OptionRow(option: Option)

Bases: Columns

Widget for a single row in the OptionList, consiting of a urwid.Text widget on the left (40% width) and a MesonEdit widget on the right (60% width).

Parameters: option¶ – Option to build the widget for.

changed: bool that will be set to True in set_changed().

name_widget: urwid.Text containing the option name on the left.

value_widget: MesonEdit for changing the option value on the right.

build_value_widget(option: Option) → MesonEdit

Build the corresponding MesonEdit subclass depending in the option type.

Parameters: option¶ – Option to create the widget for.

set_changed() → None: Adds a * in front of the option name to indicate the option was changed.

get_value()

Returns: Value of the widget (in the option’s type).

class mmeson.tui.OptionList

Bases: ListBox

Body of the main frame. urwid.ListBox containing a OptionRow for every Option.

option_rows: list of OptionRow contained in the widget.

walker: urwid.SimpleFocusListWalker managing the focusing of the contained widgets.

signals = ['focus-modified']: list of urwid signal names the class can emit.

build_option_rows() → list[mmeson.tui.OptionRow]

Creates an OptionRow for every Option from the OptionsManager and connects their changed signal to entry_modified_callback() with the widget and index as arguments.

Returns: list of OptionRow.

focus_modified_callback() → None: Callback for the modified signal from walker. Forwards the signal as focus-modified signal with the index of the currently focused OptionRow.

entry_modified_callback(option_row: OptionRow, option_index: int) → None: Callback for the changed signal from an OptionRow. Sets the Option as modified in the OptionsManager with the new value via MesonEdit.get_value().

class mmeson.tui.Header(project_name: str, project_version: str, meson_version: str)

Bases: Text

Header of the main frame. urwid.Text containing the project name, version and the Meson version used to configure the project.

Parameters

project_name¶ – Name of the Meson project.
project_version¶ – Project version as str.
meson_version¶ – Meson version as str.

class mmeson.tui.Footer

Bases: Pile

Footer of the main frame. urwid.Pile a one line divider, a three line info text and a single line help text containing the keyboard controls. The third line of the text_info is only filled when choices are available.

text_info: urwid.Text containing the option meta info (see option_list_callback()).

option_list_callback(option_index: int) → None

Callback changing the option meta information in the footer.

Parameters: option_index¶ – index of the option for the OptionsManager.

mmeson.tui.build_ui(project_name: str, project_version: str, meson_version: str) → Widget

Build the TUI tree and returns the top-level widget.

Parameters

project_name¶ – Name of the Meson project.
project_version¶ – Project version as str.
meson_version¶ – Meson version as str.

Returns

Top-level widget of the urwid TUI.

mmeson.tui.global_key_handler(key: str) → None

Global key handler for unhandled key presses.

Parameters: key¶ – key name (given from urwid).

mmeson.tui.main_loop(top_level_widget: Widget) → int

Creates and runs the urwid.MainLoop object. After the loop exists, it run the ExitAction from the MesonManager.

Parameters: top_level_widget¶ – top-level urwid widget for the urwid.MainLoop object.
Returns: Exit code from run_exit_action().