asciimatics.widgets package

Submodules

asciimatics.widgets.baselistbox module

This is the baseclass for list box types

asciimatics.widgets.button module

This module defines a button widget

class asciimatics.widgets.button.Button(text, on_click, label=None, add_box=True, name=None, **kwargs)

Bases: Widget

A Button widget to be displayed in a Frame.

It is typically used to represent a desired action for te user to invoke (e.g. a submit button on a form).

Parameters:

• text – The text for the button.

• on_click – The function to invoke when the button is clicked.

• label – An optional label for the widget.

• add_box – Whether to wrap the text with chevrons.

• name – The name of this widget.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

property text

The current text for this Button.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this Button.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.checkbox module

This module defines a checkbox widget

class asciimatics.widgets.checkbox.CheckBox(text, label=None, name=None, on_change=None, **kwargs)

Bases: Widget

A CheckBox widget is used to ask for Boolean (i.e. yes/no) input.

It consists of an optional label (typically used for the first in a group of CheckBoxes), the box and a field name.

Parameters:

• text – The text to explain this specific field to the user.

• label – An optional label for the widget.

• name – The internal name for the widget.

• on_change – Optional function to call when text changes.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this Checkbox.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.datepicker module

This module defines a datepicker widget

class asciimatics.widgets.datepicker.DatePicker(label=None, name=None, year_range=None, on_change=None, **kwargs)

Bases: Widget

A DatePicker widget allows you to pick a date from a compact, temporary, pop-up Frame.

Parameters:

• label – An optional label for the widget.

• name – The name for the widget.

• on_change – Optional function to call when the selected time changes.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current selected date.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.divider module

This module defines a divider between widgets

class asciimatics.widgets.divider.Divider(draw_line=True, height=1, line_char=None)

Bases: Widget

A divider to break up a group of widgets.

Parameters:

• draw_line – Whether to draw a line in the centre of the gap.

• height – The required vertical gap.

• line_char – Optional character to use for drawing the line.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this Divider.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.dropdownlist module

This module defines a dropdown list widget

class asciimatics.widgets.dropdownlist.DropdownList(options, label=None, name=None, on_change=None, fit=None, **kwargs)

Bases: Widget

This widget allows you to pick an item from a temporary pop-up list.

Parameters:

• options – The options for each row in the widget.

• label – An optional label for the widget.

• name – The name for the widget.

• on_change – Optional function to call when the selected time changes.

• fit – Shrink width of dropdown to fit the width of options. Default False.

The options are a list of tuples, where the first value is the string to be displayed to the user and the second is an interval value to identify the entry to the program. For example:

options=[(“First option”, 1), (“Second option”, 2)]

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

property fit

Whether to shrink to largest element width or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

property options

The set of allowed options for the drop-down list.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this DropdownList.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.filebrowser module

This module defines a file browser selection

class asciimatics.widgets.filebrowser.FileBrowser(height, root, name=None, on_select=None, on_change=None, file_filter=None)

Bases: MultiColumnListBox

A FileBrowser is a widget for finding a file on the local disk.

Parameters:

• height – The desired height for this widget.

• root – The starting root directory to display in the widget.

• name – The name of this widget.

• on_select – Optional function that gets called when user selects a file (by pressing enter or double-clicking).

• on_change – Optional function that gets called on any movement of the selection.

• file_filter – Optional RegEx string that can be passed in to filter the files to be displayed.

Most people will want to use a filter to finx files with a particular extension. In this case, you must use a regex that matches to the end of the line - e.g. use “.*.txt$” to find files ending with “.txt”. This ensures that you don’t accidentally pick up files containing the filter.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

property options

The list of options available for user selection

This is a list of tuples ([<col 1 string>, …, <col n string>], <internal value>).

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

property start_line

The line that will be drawn at the top of the visible section of this list.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this list box.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.frame module

This module defines a class to display widgets

class asciimatics.widgets.frame.Frame(screen, height, width, data=None, on_load=None, has_border=True, hover_focus=False, name=None, title=None, x=None, y=None, has_shadow=False, reduce_cpu=False, is_modal=False, can_scroll=True)

Bases: Effect

A Frame is a special Effect for controlling and displaying Widgets.

It is similar to a window as used in native GUI applications. Widgets are text UI elements that can be used to create an interactive application within your Frame.

Parameters:

• screen – The Screen that owns this Frame.

• width – The desired width of the Frame.

• height – The desired height of the Frame.

• data – optional data dict to initialize any widgets in the frame.

• on_load – optional function to call whenever the Frame reloads.

• has_border – Whether the frame has a border box. Defaults to True.

• hover_focus – Whether hovering a mouse over a widget (i.e. mouse move events) should change the input focus. Defaults to false.

• name – Optional name to identify this Frame. This is used to reset data as needed from on old copy after the screen resizes.

• title – Optional title to display if has_border is True.

• x – Optional x position for the top left corner of the Frame.

• y – Optional y position for the top left corner of the Frame.

• has_shadow – Optional flag to indicate if this Frame should have a shadow when drawn.

• reduce_cpu – Whether to minimize CPU usage (for use on low spec systems).

• is_modal – Whether this Frame is “modal” - i.e. will stop all other Effects from receiving input events.

• can_scroll – Whether a scrollbar should be available on the border, or not.

add_effect(effect)

Add an Effect to the Frame.

Parameters:

effect – The Effect to be added.

add_layout(layout)

Add a Layout to the Frame.

Parameters:

layout – The Layout to be added.

blur()

Blur this Frame.

property border_box

Instance of BoxTool that specifies the characters used to draw the border to this frame. You can change the border character style by modifying the style property on this object. Allowed styles are defined in constants.

property canvas

The Canvas that backs this Frame.

clone(_, scene)

Create a clone of this Frame into a new Screen.

Parameters:

• _ – ignored.

• scene – The new Scene object to clone into.

property data

Data dictionary containing values from the contained widgets.

property delete_count

The number of frames before this Effect should be deleted.

find_widget(name)

Look for a widget with a specified name.

Parameters:

name – The name to search for.

Returns:

The widget that matches or None if one couldn’t be found.

fix()

Fix the layouts and calculate the locations of all the widgets.

This function should be called once all Layouts have been added to the Frame and all widgets added to the Layouts.

property focussed_widget

The widget that currently has the focus within this Frame.

property frame_update_count

The number of frames before this Effect should be updated.

get_scroll_pos()

Get current position for scroll bar.

move_to(x, y, h)

Make the specified location visible. This is typically used by a widget to scroll the canvas such that it is visible.

Parameters:

• x – The x location to make visible.

• y – The y location to make visible.

• h – The height of the location to make visible.

palette = {}

Colour palette for the widgets within the Frame. Each entry should be a 3-tuple of (foreground colour, attribute, background colour).

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

rebase_event(event)

Rebase the coordinates of the passed event to frame-relative coordinates.

Parameters:

event – The event to be rebased.

Returns:

A new event object appropriately re-based.

property reduce_cpu

Whether this Frame should try to optimize refreshes to reduce CPU.

register_scene(scene)

Register the Scene that owns this Effect.

Parameters:

scene – The Scene to be registered

reset()

Function to reset the effect when replaying the scene.

property safe_to_default_unhandled_input

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

save(validate=False)

Save the current values in all the widgets back to the persistent data storage.

Parameters:

validate – Whether to validate the data before saving.

Calling this while setting the data field (e.g. in a widget callback) will have no effect.

When validating data, it can throw an Exception for any

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

set_scroll_pos(pos)

Set current position for scroll bar.

set_theme(theme)

Pick a palette from the list of supported THEMES.

Parameters:

theme – The name of the theme to set.

property stop_frame

Last frame for this effect. A value of zero means no specific end.

switch_focus(layout, column, widget)

Switch focus to the specified widget.

Parameters:

• layout – The layout that owns the widget.

• column – The column the widget is in.

• widget – The index of the widget to take the focus.

property title

Title for this Frame.

update(frame_no)

Process the animation effect for the specified frame number.

Parameters:

frame_no – The index of the frame being generated.

asciimatics.widgets.label module

This mdoule implements a widget to give a text label

class asciimatics.widgets.label.Label(label, height=1, align='<', name=None)

Bases: Widget

A text label.

Parameters:

• label – The text to be displayed for the Label.

• height – Optional height for the label. Defaults to 1 line.

• align – Optional alignment for the Label. Defaults to left aligned. Options are “<” = left, “>” = right and “^” = centre

• name – The name of this widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

property text

The current text for this Label.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this Label.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.layout module

This module implements the displaying of widgets appropriately

class asciimatics.widgets.layout.Layout(columns, fill_frame=False, gutter=0)

Bases: object

Widget layout handler.

All Widgets must be contained within a Layout within a Frame.The Layout class is responsible for deciding the exact size and location of the widgets. The logic uses similar ideas as used in modern web frameworks and is as follows.

1. The Frame owns one or more Layouts. The Layouts stack one above each other when displayed - i.e. the first Layout in the Frame is above the second, etc.

2. Each Layout defines the horizontal constraints by defining columns as a percentage of the full canvas width.

3. The Widgets are assigned a column within the Layout that owns them.

4. The Layout then decides the exact size and location to make the Widget best fit the canvas as constrained by the above.

Parameters:

• columns – A list of numbers specifying the width of each column in this layout.

• fill_frame – Whether this Layout should attempt to fill the rest of the Frame. Defaults to False.

• gutter – gutter space between columns specified in characters, defaults to 0

The Layout will automatically normalize the units used for the columns, e.g. converting [2, 6, 2] to [20%, 60%, 20%] of the available canvas.

add_widget(widget, column=0)

Add a widget to this Layout.

If you are adding this Widget to the Layout dynamically after starting to play the Scene, don’t forget to ensure that the value is explicitly set before the next update.

Parameters:

• widget – The widget to be added.

• column – The column within the widget for this widget. Defaults to zero.

Returns:

The passed in widget (so you can store a reference if needed).

blur()

Call this to take the input focus from this Layout.

clear_widgets()

Clear all widgets from this Layout.

This method allows users of the Layout to dynamically recreate a new Layout. After calling this method, you can add new widgetsback into the Layout and then need to call fix to force the Frame to recalculate the resulting new overall layout.

disable(columns=None)

Disable all widgets in the specified columns of this Layout.

Parameters:

columns – The list of columns to disable. Defaults to all columns.

enable(columns=None)

Enable all widgets in the specified columns of this Layout.

Parameters:

columns – The list of columns to enable. Defaults to all columns.

property fill_frame

Whether this Layout is variable height or not.

find_widget(name)

Look for a widget with a specified name.

Parameters:

name – The name to search for.

Returns:

The widget that matches or None if one couldn’t be found.

fix(start_x, start_y, max_width, max_height)

Fix the location and size of all the Widgets in this Layout.

Parameters:

• start_x – The start column for the Layout.

• start_y – The start line for the Layout.

• max_width – Max width to allow this layout.

• max_height – Max height to allow this layout.

Returns:

The next line to be used for any further Layouts.

focus(force_first=False, force_last=False, force_column=None, force_widget=None)

Call this to give this Layout the input focus.

Parameters:

• force_first – Optional parameter to force focus to first widget.

• force_last – Optional parameter to force focus to last widget.

• force_column – Optional parameter to mandate the new column index.

• force_widget – Optional parameter to mandate the new widget index.

The force_column and force_widget parameters must both be set together or they will otherwise be ignored.

Raises:

IndexError – if a force option specifies a bad column or widget, or if the whole Layout is readonly.

property frame_update_count

The number of frames before this Layout should be updated.

get_current_widget()

Return the current widget with the focus, or None if there isn’t one.

get_nearest_widget(target_widget, direction)

Find the nearest enabled widget to the specified target widget, bearing in mind direction of travel.

Direction of travel is defined to be the movement from current Layout to next. This is important for the case where we wrap back to the beginning or end of the Layouts - and so should still only look for the widgets nearest the top/bottom (depending on direction of travel).

This function may return None if there is no match (e.g. all widgets are disabled).

Parameters:

• target_widget – the target widget to match.

• direction – The direction of travel across Layouts.

process_event(event, hover_focus)

Process any input event.

Parameters:

• event – The event that was triggered.

• hover_focus – Whether to trigger focus change on mouse moves.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

reset()

Reset this Layout and the Widgets it contains.

save(validate)

Save the current values in all the widgets back to the persistent data storage.

Parameters:

validate – whether to validate the saved data or not.

Raises:

InvalidFields if any invalid data is found.

update(frame_no)

Redraw the widgets inside this Layout.

Parameters:

frame_no – The current frame to be drawn.

update_widgets(new_frame=None)

Reset the values for any Widgets in this Layout based on the current Frame data store.

Parameters:

new_frame – optional old Frame - used when cloning scenes.

asciimatics.widgets.listbox module

This module implements the listbox widget

class asciimatics.widgets.listbox.ListBox(height, options, centre=False, label=None, name=None, add_scroll_bar=False, parser=None, on_change=None, on_select=None, validator=None)

Bases: _BaseListBox

A ListBox is a widget that displays a list from which the user can select one option.

Parameters:

• height – The required number of input lines for this ListBox.

• options – The options for each row in the widget.

• centre – Whether to centre the selected line in the list.

• label – An optional label for the widget.

• name – The name for the ListBox.

• parser – Optional parser to colour text.

• on_change – Optional function to call when selection changes.

• on_select – Optional function to call when the user actually selects an entry from

• validator – Optional function to validate selection for this widget.

The options are a list of tuples, where the first value is the string to be displayed to the user and the second is an interval value to identify the entry to the program. For example:

options=[(“First option”, 1), (“Second option”, 2)]

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

property options

The list of options available for user selection

This is a list of tuples (<human readable string>, <internal value>).

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

property start_line

The line that will be drawn at the top of the visible section of this list.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this list box.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.multicolumnlistbox module

This module implements the widget for a multiple column list box

class asciimatics.widgets.multicolumnlistbox.MultiColumnListBox(height, columns, options, titles=None, label=None, name=None, add_scroll_bar=False, parser=None, on_change=None, on_select=None, space_delimiter=' ')

Bases: _BaseListBox

A MultiColumnListBox is a widget for displaying tabular data.

It displays a list of related data in columns, from which the user can select a line.

Parameters:

• height – The required number of input lines for this ListBox.

• columns – A list of widths and alignments for each column.

• options – The options for each row in the widget.

• titles – Optional list of titles for each column. Must match the length of columns.

• label – An optional label for the widget.

• name – The name for the ListBox.

• add_scroll_bar – Whether to add optional scrollbar for large lists.

• parser – Optional parser to colour options and titles text.

• on_change – Optional function to call when selection changes.

• on_select – Optional function to call when the user actually selects an entry from

• space_delimiter – Optional parameter to define the delimiter between columns. The default value is blank space.

The columns parameter is a list of integers or strings. If it is an integer, this is the absolute width of the column in characters. If it is a string, it must be of the format “[<align>]<width>[%]” where:

• <align> is the alignment string (“<” = left, “>” = right, “^” = centre)

• <width> is the width in characters

• % is an optional qualifier that says the number is a percentage of the width of the widget.

Column widths need to encompass any space required between columns, so for example, if your column is 5 characters, allow 6 for an extra space at the end. It is not possible to do this when you have a right-justified column next to a left-justified column, so this widget will automatically space them for you.

An integer value of 0 is interpreted to be use whatever space is left available after the rest of the columns have been calculated. There must be only one of these columns.

The number of columns is for this widget is determined from the number of entries in the columns parameter. The options list is then a list of tuples of the form ([val1, val2, … , valn], index). For example, this data provides 2 rows for a 3 column widget:

options=[([“One”, “row”, “here”], 1), ([“Second”, “row”, “here”], 2)]

The options list may be None and then can be set later using the options property on this widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

property options

The list of options available for user selection

This is a list of tuples ([<col 1 string>, …, <col n string>], <internal value>).

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

property start_line

The line that will be drawn at the top of the visible section of this list.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this list box.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.popupdialog module

This module implements a Pop up dialog message box

class asciimatics.widgets.popupdialog.PopUpDialog(screen, text, buttons, on_close=None, has_shadow=False, theme='warning')

Bases: Frame

A fixed implementation Frame that provides a standard message box dialog.

Parameters:

• screen – The Screen that owns this dialog.

• text – The message text to display.

• buttons – A list of button names to display. This may be an empty list.

• on_close – Optional function to invoke on exit.

• has_shadow – optional flag to specify if dialog should have a shadow when drawn.

• theme – optional colour theme for this pop-up. Defaults to the warning colours.

The on_close method (if specified) will be called with one integer parameter that corresponds to the index of the button passed in the array of available buttons.

Note that on_close must be a static method to work across screen resizing. Either it is static (and so the dialog will be cloned) or it is not (and the dialog will disappear when the screen is resized).

add_effect(effect)

Add an Effect to the Frame.

Parameters:

effect – The Effect to be added.

add_layout(layout)

Add a Layout to the Frame.

Parameters:

layout – The Layout to be added.

blur()

Blur this Frame.

property border_box

Instance of BoxTool that specifies the characters used to draw the border to this frame. You can change the border character style by modifying the style property on this object. Allowed styles are defined in constants.

property canvas

The Canvas that backs this Frame.

clone(screen, scene)

Create a clone of this Dialog into a new Screen.

Parameters:

• screen – The new Screen object to clone into.

• scene – The new Scene object to clone into.

property data

Data dictionary containing values from the contained widgets.

property delete_count

The number of frames before this Effect should be deleted.

find_widget(name)

Look for a widget with a specified name.

Parameters:

name – The name to search for.

Returns:

The widget that matches or None if one couldn’t be found.

fix()

Fix the layouts and calculate the locations of all the widgets.

This function should be called once all Layouts have been added to the Frame and all widgets added to the Layouts.

property focussed_widget

The widget that currently has the focus within this Frame.

property frame_update_count

The number of frames before this Effect should be updated.

get_scroll_pos()

Get current position for scroll bar.

move_to(x, y, h)

Make the specified location visible. This is typically used by a widget to scroll the canvas such that it is visible.

Parameters:

• x – The x location to make visible.

• y – The y location to make visible.

• h – The height of the location to make visible.

palette = {}

Colour palette for the widgets within the Frame. Each entry should be a 3-tuple of (foreground colour, attribute, background colour).

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

rebase_event(event)

Rebase the coordinates of the passed event to frame-relative coordinates.

Parameters:

event – The event to be rebased.

Returns:

A new event object appropriately re-based.

property reduce_cpu

Whether this Frame should try to optimize refreshes to reduce CPU.

register_scene(scene)

Register the Scene that owns this Effect.

Parameters:

scene – The Scene to be registered

reset()

Function to reset the effect when replaying the scene.

property safe_to_default_unhandled_input

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

save(validate=False)

Save the current values in all the widgets back to the persistent data storage.

Parameters:

validate – Whether to validate the data before saving.

Calling this while setting the data field (e.g. in a widget callback) will have no effect.

When validating data, it can throw an Exception for any

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

set_scroll_pos(pos)

Set current position for scroll bar.

set_theme(theme)

Pick a palette from the list of supported THEMES.

Parameters:

theme – The name of the theme to set.

property stop_frame

Last frame for this effect. A value of zero means no specific end.

switch_focus(layout, column, widget)

Switch focus to the specified widget.

Parameters:

• layout – The layout that owns the widget.

• column – The column the widget is in.

• widget – The index of the widget to take the focus.

property title

Title for this Frame.

update(frame_no)

Process the animation effect for the specified frame number.

Parameters:

frame_no – The index of the frame being generated.

asciimatics.widgets.popupmenu module

This module implements a pop up menu widget

class asciimatics.widgets.popupmenu.PopupMenu(screen, menu_items, x, y, has_border=False)

Bases: Frame

A widget for displaying a menu.

Parameters:

• screen – The Screen being used for this pop-up.

• menu_items – a list of items to be displayed in the menu.

• x – The X coordinate for the desired pop-up.

• y – The Y coordinate for the desired pop-up.

• has_border – Whether the menu has a border box. Defaults to False.

The menu_items parameter is a list of 2-tuples, which define the text to be displayed in the menu and the function to call when that menu item is clicked. For example:

menu_items = [(“Open”, file_open), (“Save”, file_save), (“Close”, file_close)]

add_effect(effect)

Add an Effect to the Frame.

Parameters:

effect – The Effect to be added.

add_layout(layout)

Add a Layout to the Frame.

Parameters:

layout – The Layout to be added.

blur()

Blur this Frame.

property border_box

Instance of BoxTool that specifies the characters used to draw the border to this frame. You can change the border character style by modifying the style property on this object. Allowed styles are defined in constants.

property canvas

The Canvas that backs this Frame.

clone(_, scene)

Create a clone of this Frame into a new Screen.

Parameters:

• _ – ignored.

• scene – The new Scene object to clone into.

property data

Data dictionary containing values from the contained widgets.

property delete_count

The number of frames before this Effect should be deleted.

find_widget(name)

Look for a widget with a specified name.

Parameters:

name – The name to search for.

Returns:

The widget that matches or None if one couldn’t be found.

fix()

Fix the layouts and calculate the locations of all the widgets.

This function should be called once all Layouts have been added to the Frame and all widgets added to the Layouts.

property focussed_widget

The widget that currently has the focus within this Frame.

property frame_update_count

The number of frames before this Effect should be updated.

get_scroll_pos()

Get current position for scroll bar.

move_to(x, y, h)

Make the specified location visible. This is typically used by a widget to scroll the canvas such that it is visible.

Parameters:

• x – The x location to make visible.

• y – The y location to make visible.

• h – The height of the location to make visible.

palette = {'focus_button': (6, 2, 7)}

Colour palette for the widgets within the Frame. Each entry should be a 3-tuple of (foreground colour, attribute, background colour).

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

rebase_event(event)

Rebase the coordinates of the passed event to frame-relative coordinates.

Parameters:

event – The event to be rebased.

Returns:

A new event object appropriately re-based.

property reduce_cpu

Whether this Frame should try to optimize refreshes to reduce CPU.

register_scene(scene)

Register the Scene that owns this Effect.

Parameters:

scene – The Scene to be registered

reset()

Function to reset the effect when replaying the scene.

property safe_to_default_unhandled_input

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

save(validate=False)

Save the current values in all the widgets back to the persistent data storage.

Parameters:

validate – Whether to validate the data before saving.

Calling this while setting the data field (e.g. in a widget callback) will have no effect.

When validating data, it can throw an Exception for any

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

set_scroll_pos(pos)

Set current position for scroll bar.

set_theme(theme)

Pick a palette from the list of supported THEMES.

Parameters:

theme – The name of the theme to set.

property stop_frame

Last frame for this effect. A value of zero means no specific end.

switch_focus(layout, column, widget)

Switch focus to the specified widget.

Parameters:

• layout – The layout that owns the widget.

• column – The column the widget is in.

• widget – The index of the widget to take the focus.

property title

Title for this Frame.

update(frame_no)

Process the animation effect for the specified frame number.

Parameters:

frame_no – The index of the frame being generated.

asciimatics.widgets.radiobuttons module

This module implements the widget for radio buttons

class asciimatics.widgets.radiobuttons.RadioButtons(options, label=None, name=None, on_change=None, **kwargs)

Bases: Widget

A RadioButtons widget is used to ask for one of a list of values to be selected by the user.

It consists of an optional label and then a list of selection bullets with field names.

Parameters:

• options – A list of (text, value) tuples for each radio button.

• label – An optional label for the widget.

• name – The internal name for the widget.

• on_change – Optional function to call when text changes.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for these RadioButtons.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.scrollbar module

This module implements a scroll bar capability for widgets

asciimatics.widgets.temppopup module

This module implements a base class for popups

asciimatics.widgets.text module

This widget implements a text based input field

class asciimatics.widgets.text.Text(label=None, name=None, on_change=None, validator=None, hide_char=None, max_length=None, readonly=False, **kwargs)

Bases: Widget

A Text widget is a single line input field.

It consists of an optional label and an entry box.

Parameters:

• label – An optional label for the widget.

• name – The name for the widget.

• on_change – Optional function to call when text changes.

• validator – Optional definition of valid data for this widget. This can be a function (which takes the current value and returns True for valid content) or a regex string (which must match the entire allowed value).

• hide_char – Character to use instead of what the user types - e.g. to hide passwords.

• max_length – Optional maximum length of the field. If set, the widget will limit data entry to this length.

• readonly – Whether the widget prevents user input to change values. Default is False.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

property readonly

Whether this widget is readonly or not.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this Text.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.textbox module

This module implements a multi line editing text box

class asciimatics.widgets.textbox.TextBox(height, label=None, name=None, as_string=False, line_wrap=False, parser=None, on_change=None, readonly=False, **kwargs)

Bases: Widget

A TextBox is a widget for multi-line text editing.

It consists of a framed box with option label.

Parameters:

• height – The required number of input lines for this TextBox.

• label – An optional label for the widget.

• name – The name for the TextBox.

• as_string – Use string with newline separator instead of a list for the value of this widget.

• line_wrap – Whether to wrap at the end of the line.

• parser – Optional parser to colour text.

• on_change – Optional function to call when text changes.

• readonly – Whether the widget prevents user input to change values. Default is False.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

property auto_scroll

When set to True the TextBox will scroll to the bottom when created or next text is added. When set to False, the current scroll position will remain even if the contents are changed.

Defaults to True.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

property hide_cursor

Set to True to stop the cursor from showing. Defaults to False.

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

property readonly

Whether this widget is readonly or not.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this TextBox.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.timepicker module

This module implements a time picker widget

class asciimatics.widgets.timepicker.TimePicker(label=None, name=None, seconds=False, on_change=None, **kwargs)

Bases: Widget

A TimePicker widget allows you to pick a time from a compact, temporary, pop-up Frame.

Parameters:

• label – An optional label for the widget.

• name – The name for the widget.

• seconds – Whether to include selection of seconds or not.

• on_change – Optional function to call when the selected time changes.

Also see the common keyword arguments in Widget.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current selected time.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.utilities module

This module defines commonly used pieces for widgets

asciimatics.widgets.utilities.THEMES = {'bright': {'control': (3, 1, 0), 'disabled': (0, 1, 0), 'focus_button': (3, 1, 0), 'focus_control': (3, 1, 0), 'focus_edit_text': (3, 1, 0), 'invalid': (0, 2, 1), 'label': (2, 1, 0), 'selected_focus_control': (3, 1, 0), 'selected_focus_field': (3, 1, 0)}, 'default': {'background': (7, 2, 4), 'borders': (0, 1, 4), 'button': (7, 2, 4), 'control': (3, 2, 4), 'disabled': (0, 1, 4), 'edit_text': (7, 2, 4), 'field': (7, 2, 4), 'focus_button': (7, 1, 6), 'focus_control': (3, 2, 4), 'focus_edit_text': (7, 1, 6), 'focus_field': (7, 2, 4), 'focus_readonly': (0, 1, 6), 'invalid': (3, 1, 1), 'label': (2, 1, 4), 'readonly': (0, 1, 4), 'scroll': (6, 2, 4), 'selected_control': (3, 1, 4), 'selected_field': (3, 1, 4), 'selected_focus_control': (3, 1, 6), 'selected_focus_field': (7, 1, 6), 'shadow': (0, None, 0), 'title': (7, 1, 4)}, 'green': {'disabled': (0, 1, 0), 'focus_button': (2, 1, 0), 'focus_edit_text': (2, 1, 0), 'invalid': (0, 2, 1), 'label': (2, 1, 0), 'selected_focus_control': (2, 1, 0), 'selected_focus_field': (2, 1, 0), 'title': (2, 1, 0)}, 'monochrome': {'disabled': (0, 1, 0), 'focus_button': (7, 1, 0), 'focus_edit_text': (7, 1, 0), 'invalid': (0, 2, 1), 'label': (7, 1, 0), 'selected_focus_control': (7, 1, 0), 'selected_focus_field': (7, 1, 0), 'title': (7, 1, 0)}, 'tlj256': {'disabled': (8, 0, 15), 'focus_button': (15, 0, 88), 'focus_edit_text': (15, 0, 88), 'invalid': (0, 0, 196), 'label': (88, 0, 15), 'selected_focus_control': (15, 0, 88), 'selected_focus_field': (15, 0, 88), 'title': (88, 0, 15)}, 'warning': {'disabled': (7, 1, 1), 'focus_button': (7, 1, 3), 'focus_control': (7, 1, 1), 'focus_edit_text': (7, 1, 1), 'focus_field': (7, 1, 1), 'label': (7, 1, 1), 'shadow': (0, None, 0), 'title': (7, 1, 1)}}

Standard palettes for use with set_theme(). Each entry in THEMES contains a colour palette for use by the widgets within a Frame. Each colour palette is a dictionary mapping a colour key to a 3-tuple of (foreground colour, attribute, background colour). The “default” theme defines all the required keys for a palette.

asciimatics.widgets.verticaldivider module

This module implements a vertical division between widgets

class asciimatics.widgets.verticaldivider.VerticalDivider(height=-135792467)

Bases: Widget

A vertical divider for separating columns.

This widget should be put into a column of its own in the Layout.

Parameters:

height – The required height for this divider.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

property value

The current value for this VerticalDivider.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

asciimatics.widgets.widget module

This module allows you to create interactive text user interfaces. For more details see http://asciimatics.readthedocs.io/en/latest/widgets.html

class asciimatics.widgets.widget.Widget(name, tab_stop=True, disabled=False, on_focus=None, on_blur=None)

Bases: object

A Widget is a re-usable component that can be used to create a simple GUI.

Parameters:

• name – The name of this Widget.

• tab_stop – Whether this widget should take focus or not when tabbing around the Frame.

• disabled – Whether this Widget should be disabled or not.

• on_focus – Optional callback whenever this widget gets the focus.

• on_blur – Optional callback whenever this widget loses the focus.

FILL_COLUMN = -135792467

Widgets with this constant for the required height will be re-sized to fit the maximum space used by any other column in the Layout.

FILL_FRAME = -135792468

Widgets with this constant for the required height will be re-sized to fit the available vertical space in the Layout.

blur()

Call this to take the input focus from this Widget.

property custom_colour

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

property disabled

Whether this widget is disabled or not.

focus()

Call this to give this Widget the input focus.

property frame

The Frame that contains this Widget.

property frame_update_count

The number of frames before this Widget should be updated.

get_location()

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:

A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)

Check if the specified mouse event is over this widget.

Parameters:

• event – The MouseEvent to check.

• include_label – Include space reserved for the label when checking.

• width_modifier – Adjustment to width (e.g. for scroll bars).

Returns:

True if the mouse is over the active parts of the widget.

property is_tab_stop

Whether this widget is a valid tab stop for keyboard navigation.

property is_valid

Whether this widget has passed its data validation or not.

property is_visible

Whether this widget is visible on the Canvas or not.

property label

The label for this widget. Can be None.

property name

The name for this widget (for reference in the persistent data). Can be None.

abstract process_event(event)

Process any input event.

Parameters:

event – The event that was triggered.

Returns:

None if the Effect processed the event, else the original event.

register_frame(frame)

Register the Frame that owns this Widget.

Parameters:

frame – The owning Frame.

abstract required_height(offset, width)

Calculate the minimum required height for this widget.

Parameters:

• offset – The allowed width for any labels.

• width – The total width of the widget, including labels.

abstract reset()

The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:

• x – The x position of the widget.

• y – The y position of the widget.

• offset – The allowed label size for the widget.

• w – The width of the widget.

• h – The height of the widget.

abstract update(frame_no)

The update method is called whenever this widget needs to redraw itself.

Parameters:

frame_no – The frame number for this screen update.

abstract property value

The value to return for this widget based on the user’s input.

property width

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

Module contents

This is the module initialization for widgets