User Interfaces


Asciimatics provides a widgets sub-package that allows you to create interactive text user interfaces. At its heart, the logic is quite simple, reusing concepts from standard web and desktop GUI frameworks.

  1. The basic building block for your text UI is a Widget. There is a set of standard ones provided by asciimatics, but you can create a custom set if needed. The basic set has strong parallels with simple web input forms - e.g. buttons, check boxes, etc.
  2. The Widgets need to be arranged on the Screen and rearranged whenever it is resized. The Layout class handles this for you. You just need to add your Widgets to one.
  3. You then need to display the Layouts. To do this, you must add them to a Frame. This class is an Effect and so can be used in any Scene alongside any other Effect. The Frame will draw any parts of the Layouts it contains that are visible within its boundaries. The net result is that it begins to look a bit like a window in GUI frameworks.

And that’s it! You can set various callbacks to get triggered when key events occur - e.g. changes to values, buttons get clicked, etc. - and use these to trigger your application processing. For an example, see the sample provided - which will look a bit like this:

Screen shot of the contacts list sample

Common keys

When navigating around a Frame, you can normally use the following keys.

Key Action
Tab Move to the next Widget in the Frame
Backtab (shift+tab) Move to the previous Widget in the Frame
Up arrow Move to the nearest Widget above the current focus.
Down arrow Move to the nearest Widget below the current focus.
Left arrow Move to the nearest Widget to the left of the current focus.
Right arrow Move to the nearest Widget to the right of the current focus.
Space or Return Select the current Widget - e.g. click a Button, or pop-up a list of options.


Please note that asciimatics will not allow you to navigate to a disabled widget. Instead it will select the next enabled widget when traversing the Frame.

However, some widgets (e.g. text editing widgets) have their own logic for handling the cursor key actions, which override the common navigation. In such cases, tab/backtab will still navigate out of the Widgets.

In addition you can also use the following extra keys inside text editing widgets.

Key Action
Home/End Move to the start/end of the current line.
Delete Delete the character under the cursor.
Backspace Delete the character before the cursor.

Model/View Design

Before we jump into exactly what all the objects are and what they do for you, it is important to understand how you must put them together to make the best use of them.

The underlying Screen/Scene/Effect design of asciimatics means that objects regularly get thrown away and recreated - especially when the Screen is resized. It is therefore vital to separate your data model from your code to display it on the screen.

This split is often (wrongly) termed the MVC model, but a more accurate description is Separated Presentation. No matter what term you use, the concept is easy: use a separate class to handle your persistent data storage.

In more concrete terms, let’s have a closer look at the contact_list sample. This consists of 3 basic classes:

  1. ContactModel: This is the model. It stores simple contact details in a sqlite in-memory database and provides a simple create/read/update/delete interface to manipulate any contact. Note that you don’t have to be this heavy-weight with the data storage; a simple class to wrap a list of dictionaries would also suffice - but doesn’t look as professional for a demo!
Show/hide code
class ContactModel(object):
    def __init__(self):
        # Create a database in RAM
        self._db = sqlite3.connect(':memory:')
        self._db.row_factory = sqlite3.Row

        # Create the basic contact table.
            CREATE TABLE contacts(
                id INTEGER PRIMARY KEY,
                name TEXT,
                phone TEXT,
                address TEXT,
                email TEXT,
                notes TEXT)

        # Current contact when editing.
        self.current_id = None

    def add(self, contact):
            INSERT INTO contacts(name, phone, address, email, notes)
            VALUES(:name, :phone, :address, :email, :notes)''',

    def get_summary(self):
        return self._db.cursor().execute(
            "SELECT name, id from contacts").fetchall()

    def get_contact(self, contact_id):
        return self._db.cursor().execute(
            "SELECT * from contacts where id=?", str(contact_id)).fetchone()

    def get_current_contact(self):
        if self.current_id is None:
            return {"name": "", "address": "", "phone": "", "email": "", "notes": ""}
            return self.get_contact(self.current_id)

    def update_current_contact(self, details):
        if self.current_id is None:
                UPDATE contacts SET name=:name, phone=:phone, address=:address,
                email=:email, notes=:notes WHERE id=:id''',

    def delete_contact(self, contact_id):
            DELETE FROM contacts WHERE id=:id''', {"id": contact_id})
  1. ListView: This is the main view. It queries the ContactModel for the list of known contacts and displays them in a list, complete with some extra buttons to add/edit/delete contacts.
Show/hide code
class ListView(Frame):
    def __init__(self, screen, model):
        super(ListView, self).__init__(screen,
                                       screen.height * 2 // 3,
                                       screen.width * 2 // 3,
                                       title="Contact List")
        # Save off the model that accesses the contacts database.
        self._model = model

        # Create the form for displaying the list of contacts.
        self._list_view = ListBox(
            model.get_summary(), name="contacts", on_select=self._on_pick)
        self._edit_button = Button("Edit", self._edit)
        self._delete_button = Button("Delete", self._delete)
        layout = Layout([100], fill_frame=True)
        layout2 = Layout([1, 1, 1, 1])
        layout2.add_widget(Button("Add", self._add), 0)
        layout2.add_widget(self._edit_button, 1)
        layout2.add_widget(self._delete_button, 2)
        layout2.add_widget(Button("Quit", self._quit), 3)

    def _on_pick(self):
        self._edit_button.disabled = self._list_view.value is None
        self._delete_button.disabled = self._list_view.value is None

    def _reload_list(self):
        self._list_view.options = self._model.get_summary()
        self._model.current_id = None

    def _add(self):
        self._model.current_id = None
        raise NextScene("Edit Contact")

    def _edit(self):
        self._model.current_id =["contacts"]
        raise NextScene("Edit Contact")

    def _delete(self):

    def _quit():
        raise StopApplication("User pressed quit")
  1. ContactView: This is the detailed view. It queries the ContactModel for the current contact to be displayed when it is reset (note: there may be no contact if the user is adding a contact) and writes any changes back to the model when the user clicks OK.
Show/hide code
class ContactView(Frame):
    def __init__(self, screen, model):
        super(ContactView, self).__init__(screen,
                                          screen.height * 2 // 3,
                                          screen.width * 2 // 3,
                                          title="Contact Details")
        # Save off the model that accesses the contacts database.
        self._model = model

        # Create the form for displaying the list of contacts.
        layout = Layout([100], fill_frame=True)
        layout.add_widget(Text("Name:", "name"))
        layout.add_widget(Text("Address:", "address"))
        layout.add_widget(Text("Phone number:", "phone"))
        layout.add_widget(Text("Email address:", "email"))
        layout.add_widget(TextBox(5, "Notes:", "notes", as_string=True))
        layout2 = Layout([1, 1, 1, 1])
        layout2.add_widget(Button("OK", self._ok), 0)
        layout2.add_widget(Button("Cancel", self._cancel), 3)

    def reset(self):
        # Do standard reset to clear out form, then populate with new data.
        super(ContactView, self).reset() = self._model.get_current_contact()

    def _ok(self):
        raise NextScene("Main")

    def _cancel():
        raise NextScene("Main")

Displaying your UI

OK, so you want to do something a little more interactive with your user. The first thing you need to decide is what information you want to get from them and how you’re going to achieve that. In short:

  1. What data you want them to be able to enter - e.g. their name.
  2. How you want to break that down into fields - e.g. first name, last name.
  3. What the natural representation of those fields would be - e.g. text strings.

At this point, you can now decide which Widgets you want to use. The standard selection is as follows.

Widget type Description
Button Action buttons - e.g. ok/cancel/etc.
CheckBox Simple yes/no tick boxes.
DatePicker A single-line widget for selecting a date (using a pop-up list).
Divider A spacer between widgets (for aesthetics).
DropdownList A single-line widget that pops up a list from which the user can select a single value.
FileBrowser A multi-line widget for listing the local file system.
Label A label for a group of related widgets.
ListBox A list of possible options from which users can select one value.
MultiColumnListBox Like a ListBox, but for displaying tabular data.
RadioButtons A list of radio buttons. These allow users to select one value from a list of options.
Text A single line of editable text.
TextBox A multi-line box of editable text.
TimePicker A single-line widget for selecting a time (using a pop-up list).
VerticalDivider A vertical line divider - useful for providing a visual marker between columns in a Layout.


You can use the hide_char option on Text widgets to hide sensitive data - e.g. for passwords.

Asciimatics will automatically arrange these for you with just a little extra help. All you need to do is decide how many columns you want for your fields and which fields should be in which columns. To tell asciimatics what to do you create a Layout (or more than one if you want a more complex structure where different parts of the screen need differing column counts) and associate it with the Frame where you will display it.

For example, this will create a Frame that is 80x20 characters and define 4 columns that are each 20 columns wide:

frame = Frame(screen, 80, 20, has_border=False)
layout = Layout([1, 1, 1, 1])

Once you have a Layout, you can add Widgets to the relevant column. For example, this will add a button to the first and last columns:

layout.add_widget(Button("OK", self._ok), 0)
layout.add_widget(Button("Cancel", self._cancel), 3)

If you want to put a standard label on all your input fields, that’s fine too; asciimatics will decide how big your label needs to be across all fields in the same column and then indent them all to create a more aesthetically pleasing layout. For example, this will provide a single column with labels for each field, indenting all of the fields to the same depth:

layout = Layout([100])
layout.add_widget(Text("Name:", "name"))
layout.add_widget(Text("Address:", "address"))
layout.add_widget(Text("Phone number:", "phone"))
layout.add_widget(Text("Email address:", "email"))
layout.add_widget(TextBox(5, "Notes:", "notes", as_string=True))

If you want more direct control of your labels, you could use the Label widget to place them anywhere in the Layout as well as control the justification (left, centre or right) of the text.

Or maybe you just want some static text in your UI? The simplest thing to do there is to use the Label widget. If you need something a little more advanced - e.g. a pre-formatted multi-line status bar, use a TextBox and disable it as described below.

In some cases, you may want to have different alignments for various blocks of Widgets. You can use multiple Layouts in one Frame to handle this case.

For example, if you want a search page, which allows you to enter data at the top and a list of results at the bottom of the Frame, you could use code like this:

layout1 = Layout([100])
layout1.add_widget(Text(label="Search:", name="search_string"))

layout2 = Layout([100])
layout1.add_widget(TextBox(Widget.FILL_FRAME, name="results"))

Disabling widgets

Any widget can be disabled by setting the disabled property. When this is True, asciimatics will redraw the widget using the ‘disabled’ colour palette entry and prevent the user from selecting it or editing it.

It is still possible to change the widget programmatically, though. For example, you can still change the value of a disabled widget.

This is the recommended way of getting a piece of non-interactive data (e.g. a status bar) into your UI. If the disabled colour is the incorrect choice for your UI, you can override it as explained in Custom widget colours. For an example of such a widget, see the sample.

Layouts in more detail

If you need to do something more complex, you can use multiple Layouts. Asciimatics uses the following logic to determine the location of Widgets.

  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 some horizontal constraints by defining columns as a proportion of the full Frame 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 each Widget best fit the visible space as constrained by the above.

For example:

|...|Frame                                                           |...|
|...||Layout 1                                                      ||...|
|...||Layout 2                      |                               ||...|
|...|| - Column 1                   | - Column 2                    ||...|
|...||Layout 3     | < Widget 1 >                    |              ||...|
|...||             | ...                             |              ||...|
|...||             | < Widget N >                    |              ||...|

This consists of a single Frame with 3 Layouts. The first is a single, full-width column, the second has two 50% width columns and the third consists of 3 columns of relative size 25:50:25. The last actually contains some Widgets in the second column (though this is just for illustration purposes as we’d expect most Layouts to have some Widgets in them).

Filling the space

Once you’ve got the basic rows and columns for your UI sorted, you may want to use some strategic spacing. At the simplest level, you can use the previously mentioned Divider widget to create some extra vertical space or insert a visual section break.

Moving up the complexity, you can pick different sizes for your Frames based on the size of your current Screen. The Frame will be recreated when the screen is resized and so you will use more or less real estate appropriately.

Finally, you could also tell asciimatics to use an object to fill any remaining space. This allows for the sort of UI like you’d see in applications like top where you have a fixed header or footer, but then a variably sized part that contains the data to be displayed.

You can achieve this in 2 ways:

  1. You can tell a Layout to fill any remaining space in the Frame using fill_frame=True on construction.
  2. You can tell some Widgets to fill any remaining space in the Frame using a height of Widget.FILL_FRAME on construction.

These two methods can be combined to tell a Layout to fill the Frame and a Widget to fill this Layout. See the ListView class in the contact_list demo code.


Note that you can only have one Layout and/or Widget that fills the Frame. Trying to set more than one will be rejected.

Full-screen Frames

By default, asciimatics assumes that you are putting multiple Frames into one Scene and so provides defaults (e.g. borders) to optimize this type of UI. However, some UIs only need a single full-screen Frame. This can easily be achieved by declaring a Frame the full width and height of the screen and then specifying has_border=False.

Large forms

If you have a very large form, you may find it is too big to fit into a standard screen. This is not a problem. You can keep adding your Widgets to your Layout and asciimatics will automatically clip the content to the space available and scroll the content as required.

If you do this, it is recommended that you set has_border=True on the Frame so that the user can use the scroll bar provided to move around the form.

Colour schemes

The colours for any Widget are determined by the palette property of the Frame that contains the Widget. If desired, it is possible to have a different palette for every Frame, however your users may prefer a more consistent approach.

The palette is just a simple dictionary to map Widget components to a colour tuple. A colour tuple is simply the foreground colour, attribute and background colour. For example:


The following table shows the required keys for the palette.

Key Usage
“background” Frame background
“borders” Frame border and Divider Widget
“button” Buttons
“control” Checkboxes and RadioButtons
“disabled” Any disabled Widget
“edit_text” Text and TextBox
“field” Value of an option for a Checkbox, RadioButton or Listbox
“focus_button” Buttons with input focus
“focus_control” Checkboxes and RadioButtons with input focus
“focus_edit_text” Text and TextBox with input focus
“focus_field” As above with input focus
“invalid” The widget contains invalid data
“label” Widget labels
“scroll” Frame scroll bar
“selected_control” Checkboxes and RadioButtons when selected
“selected_field” As above when selected
“selected_focus_control” Checkboxes and RadioButtons with both
“selected_focus_field” As above with both
“title” Frame title

In addition to the default colour scheme for all your widgets, asciimatics provides some other pre-defined colour schemes (or themes) that you can use for your widgets using set_theme(). These themes are as follows.

Name Description
“monochrome” Simple black and white colour scheme.
“green” A classic green terminal.
“bright” Black background, green and yellow scheme.
“tlj256” Shades of black white and red - 256 colour terminals only.

You can add your own theme to this list by defining a new entry in the THEMES

Custom widget colours

In some cases, a single palette for the entire Frame is not sufficient. If you need a more fine-grained approach to the colouring, you can customize the colour for any Widget by setting the custom_colour for that Widget. The only constraint on this property is that it must still be the value of one of the keys within the owning Frame’s palette.

Changing colours inline

The previous options should be enough for most UIs. However, sometimes it is useful to be able to change the colour of some text inside the value for some widgets, e.g. to provide syntax highlighting in a TextBox. You can do this using a Parser object for those widgets that support it.

By passing in a parser that understands extra control codes or the need to highlight certain characters differently, you can control colours on a letter by letter basis. Out of the box, asciimatics provides 2 parsers, which can handle the ${c,a,b} format used by its Renderers, or the ANSI standard terminal escape codes (used by many Linux terminals). Simply use the relevant parser (AsciimaticsParser or AnsiTerminalParser) and pass in values containing the associated control codes to change colours where needed.

Check out the latest code in and for examples of how this works.

Setting values

By this stage, you should have a basic User Interface up and running, but how do you set the values in each of the Widgets - e.g. to pre-populate known values in a form? There are 2 ways to handle this:

  1. You can set the value directly on each Widget using the value property.
  2. You can set the value for all Widgets in a Frame by setting at the data property. This is a simple key/value dictionary, using the name property for each Widget as the keys.

The latter is a preferred as a symmetrical solution is provided to access all the data for each Widget, thus giving you a simple way to read and then replay the data back into your Frame.

Getting values

Now that you have a Frame with some Widgets in it and the user is filling them in, how do you find out what they entered? There are 2 basic ways to do this:

  1. You can query each Widget directly, using the value property. This returns the current value the user has entered at any time (even when the Frame is not active). Note that it may be None for those Widgets where there is no value - e.g. buttons.
  2. You can query the Frame`by looking at the `data property. This will return the value for every Widget in the former as a dictionary, using the Widget name properties for the keys. Note that data is just a cache, which only gets updated when you call save(), so you need to call this method to refresh the cache before accessing it.

For example:

# Form definition
layout = Layout([100])
layout.add_widget(Text("Name:", "name"))
layout.add_widget(Text("Address:", "address"))
layout.add_widget(TextBox(5, "Notes:", "notes", as_string=True))

# Sample after user has filled it in.
    "name": "Peter",
    "address": "Somewhere on earth",
    "notes": "Some multi-line\ntext from the user."

Validating text data

Free-form text input sometimes needs validating to make sure that the user has entered the right thing - e.g. a valid email address - in a form. Asciimatics makes this easy by adding the validator parameter to Text widgets.

This parameter takes either a regular expression string or a function (taking a single parameter of the current widget value). Asciimatics will use it to determine if the widget contains valid data. It uses this information in 2 places.

  1. Whenever the Frame is redrawn, asciimatics will check the state and flag any invalid values using the invalid colour palette selection.
  2. When your program calls save() specifying validate=True, asciimatics will check all fields and throw an InvalidFields exception if it finds any invalid data.

Input focus

As mentioned in the explanation of colour palettes, asciimatics has the concept of an input focus. This is the Widget that will take any input from the keyboard. Assuming you are using the default palette, the Widget with the input focus will be highlighted. You can move the focus using the cursor keys, tab/backtab or by using the mouse.

The exact way that the mouse affects the focus depends on a combination of the capabilities of your terminal/console and the settings of your Frame. At a minimum, clicking on the Widget will always work. If you specify hover_focus=True and your terminal supports reporting mouse move events, just hovering over the Widget with the mouse pointer will move the focus.

Global key handling

In addition to mouse control to switch focus, you can also set up a global event handler to navigate your forms. This is useful for keyboard shortcuts - e.g. Ctrl+Q to quit your program.

To set up this handler, you need to pass it into your screen on the play() Method. For example

# Event handler for global keys
def global_shortcuts(event):
    if isinstance(event, KeyboardEvent):
        c = event.key_code
        # Stop on ctrl+q or ctrl+x
        if c in (17, 24):
            raise StopApplication("User terminated app")

# Pass this to the screen..., unhandled_input=global_shortcuts)


Note that the global handler is only called if the focus does not process the event. Some widgets - e.g. TextBox - take any printable text and so the only keys that always get to this handler are the control codes. Others will sometimes get here depending on the type of Widget in focus and whether the Frame is modal or not..

By default, the global handler will do nothing if you are playing any Scenes containing a Frame. Otherwise it contains the top-level logic for skipping to the next Scene (on space or enter), or exiting the program (on Q or X).

Dealing with Ctrl+C and Ctrl+Z

A lot of modern UIs want to be able to use Ctrl+C/Z to do something other than kill the application. The problem for Python is that this normally triggers a KeyboardInterrupt - which typically kills the application - or causes the operating system to suspend the process (on UNIX variants).

If you want to prevent this and use Ctrl+C/Z for another purpose, you can tell asciimatics to catch the low-level signals to prevent these interrupts from being generated (and so return the keypress to your application). This is done by specifying catch_interrupt=True when you create the Screen by calling wrapper().

Dealing with Ctrl+S

Back in the days when terminals really were separate machines connected over wires to a computer, it was necessary to be able to signal that the terminal needed time to catch up. This was done using software flow control, using the Ctrl+S/Ctrl+Q control codes to tell the computer to stop/restart sending text.

These days, it’s not really necessary, but is still a supported feature on most terminals. On some systems you can switch this off so you get access to Ctrl+S, but it is not possible on them all. See Ctrl+S does not work for details on how to fix this.

Flow of control

By this stage you should have a program with some Frames and can extract what your user has entered into any of them. But how do you know when to act and move between Frames? The answer is callbacks and exceptions.


A callback is just a function that you pass into another function to be called when the associated event occurs. In asciimatics, they can usually be identified by the fact that they start with on and correspond to a significant input action from the user, e.g. on_click.

When writing your application, you simply need to decide which events you want to use to trigger some processing and create appropriate callbacks. The most common pattern is to use a Button and define an on_click callback.

In addition, there are other events that can be triggered when widget values change. These can be used to provide dynamic effects like enabling/disabling Buttons based on the current value of another Widget.


Asciimatics uses exceptions to tell the animation engine to move to a new Scene or stop the whole
process. Other exceptions are not caught and so can still be used as normal. The details for the new exceptions are as follows:
  1. StopApplication - This exception will stop the animation engine and return flow to the function that called into the Screen.
  2. NextScene - This exception tells the animation engine to move to a new Scene. The precise Scene is determined by the name passed into the exception. If none is specified, the engine will simply roundi robin to the next available Scene.

Note that the above logic requires each Scene to be given a unique name on construction. For example:

# Given this scene list...
scenes = [
    Scene([ListView(screen, contacts)], -1, name="Main"),
    Scene([ContactView(screen, contacts)], -1, name="Edit Contact")

# You can use this code to move back to the first scene at any time...
raise NextScene("Main")

Data handling

By this stage you should have everything you need for a fully functional UI. However, it may not be quite clear how to pass data around all your component parts because asciimatics doesn’t provide any classes to do it for you. Why? Because we don’t want to tie you down to a specific implementation. You should be able to pick your own!

Look back at the earlier explanation of model/view design. The model can be any class you like! All you need to do is:

  1. Define a model class to store any state and provide suitable APIs to access it as needed from your UI (a.k.a. views).
  2. Define your own views (based on an Effect or Frame) to define your UI and store a reference to the model (typically as a parameter on construction).
  3. Use that saved reference to the model to handle updates as needed inside your view’s callbacks or methods.

For a concrete example of how to do this check out the contact list sample and look at how it defines and uses the ContactModel. Alternatively, the quick_model sample shows how the same forms would work witha simple list of dictionaries instead.

Dynamic scenes

That done, there are just a few more final touches to consider. These all touch on dynamically changing or reconstructing your Scene.

At a high level, you need to decide what you want to achieve. The basic options are as follows.

  1. If you just want to have some extra Frames on the same Screen - e.g. pop-up windows - that’s fine. Just use the existing classes (see below)!
  2. If you want to be able to draw other content outside of your existing Frame(s), you probably want to use other Effects.
  3. If you want to be able to add something inside your Frame(s), you almost certainly want to create a custom Widget for that new content.

The rest of this section goes through those options (and a couple more related changes) in a little more detail.

Adding other effects

Since Frames are just another Effect, they can be combined with any other Effect in a Scene. For example, this will put a simple input form over the top of the animated Julia set Effect:

scenes = []
effects = [
scenes.append(Scene(effects, -1))

The ordering is important. The effects at the bottom of the list are at the top of the screen Z order and so will be displayed in preference to those lower in the Z order (i.e. those earlier in the list).

The most likely reason you will want to use this is to use the Background Effect to set a background colour for the whole screen behind your Frames. See the demo for an example of this use case.

Pop-up dialogs

Along a similar line, you can also add a PopUpDialog to your Scenes at any time. These consist of a single text message and a set of buttons that you can define when creating the dialog.

Owing to restrictions on how objects need to be rebuilt when the screen is resized, these should be limited to simple are confirmation or error cases - e.g. “Are you sure you want to quit?” For more details on the restrictions, see the section on restoring state.

Pop-up menus

You can also add a PopupMenu to your Scenes in the same way. These allow you to create a simple temporary list of options from which the user has to select just one entry (by clicking on it or moving the focus and pressing Enter) or dismiss the whole list (by pressing Escape or clicking outside of the menu).

Owing to their temporary nature, they are not maintained over screen resizing.

Screen resizing

If you follow the standard application mainline logic as found in all the sample code, your application will want to resize all your Effects and Widgets whenever the user resizes the terminal. To do this you need to get a new Screen then rebuild a new set of objects to use that Screen.

Sound like a bit of a drag, huh? This is why it is recommended that you separate your presentation from the rest of your application logic. If you do it right you will find that it actually just means you go through exactly the same initialization path as you did before to create your Scenes in the first place. There are a couple of gotchas, though.

First, you need to make sure that asciimatics will exit and recreate a new Screen when the terminal is resized. You do that with this boilerplate code that is in most of the samples.

def main(screen, scene):
    # Define your Scenes here
    scenes = ...

    # Run your program, stop_on_resize=True, start_scene=scene)

last_scene = None
while True:
        Screen.wrapper(main, arguments=[last_scene])
    except ResizeScreenError as e:
        last_scene = e.scene
This will allow you to decide how all your UI should look whenever the screen is resized and will
restart at the Scene that was playing at the time of the resizing.

Restoring state

Recreating your view is only half the story. Now you need to ensure that you have restored any state inside your application - e.g. any dynamic effects are added back in, your new Scene has the same internal state as the old, etc. Asciimatics provides a standard interface (the clone method) to help you out here.

When the running Scene is resized (and passed back into the Screen as the start scene), the new Scene will run through all the Effects in the old copy looking for any with a clone method. If it finds one, it will call it with 2 parameters: the new Screen and the new Scene to own the cloned Effect. This allows you to take full control of how the new Effect is recreated. Asciimatics uses this interface in 2 ways by default:

  1. To ensure that any data is restored in the new Scene.
  2. To duplicate any dynamically added PopUpDialog objects in the new Scene.

You could override this processing to handle your own custom cloning logic. The formal definition of the API is defined as follows.

def clone(self, screen, scene):
    Create a clone of this Effect into a new Screen.

    :param screen: The new Screen object to clone into.
    :param scene: The new Scene object to clone into.

Reducing CPU usage

It is the nature of text UIs that they don’t need to refresh anywhere near as often as a full-blown animated Scene. Asciimatics therefore optimizes the refresh rate when only Frames are being displayed on the Screen.

However, there are some widgets that can reduce the need for animation even further by not requesting animation updates (e.g. for a blinking cursor). If this is an issue for your application, you can specify reduce_cpu=True when constructing your Frames. See for an example of this.

Custom widgets

To develop your own widget, you need to define a new class that inherits from Widget. You then have to implement the following functions.

  1. reset() - This is where you should reset any state for your widget. It gets called whenever the owning Frame is initialised, which can be when it is first displayed, when the user moves to a new Scene or when the screen is resized.
  2. update() - This is where you should put the logic to draw your widget. It gets called every time asciimatics needs to redraw the screen (and so should always draw the entire widget).
  3. process_event() - This is where you should put your code to handle mouse and keyboard events.
  4. value - This must return the current value for the widget.
  5. required_height() - This returns the minimum required height for your widget. It is used by the owning Layout to determine the size and location of your widget.

With these all defined, you should now be able to add your new custom widget to a Layout like any of the standard ones delivered in this package.