User Interfaces =============== Introduction ------------ 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 contact_list.py sample provided - which will look a bit like this: .. image:: contacts.png :alt: 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. =================== ============================================================================== .. warning:: 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! .. container:: toggle .. container:: header **Show/hide code** .. code-block:: python class ContactModel(): def __init__(self): # Create a database in RAM self._db = sqlite3.connect(':memory:') self._db.row_factory = sqlite3.Row # Create the basic contact table. self._db.cursor().execute(''' CREATE TABLE contacts( id INTEGER PRIMARY KEY, name TEXT, phone TEXT, address TEXT, email TEXT, notes TEXT) ''') self._db.commit() # Current contact when editing. self.current_id = None def add(self, contact): self._db.cursor().execute(''' INSERT INTO contacts(name, phone, address, email, notes) VALUES(:name, :phone, :address, :email, :notes)''', contact) self._db.commit() 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": ""} else: return self.get_contact(self.current_id) def update_current_contact(self, details): if self.current_id is None: self.add(details) else: self._db.cursor().execute(''' UPDATE contacts SET name=:name, phone=:phone, address=:address, email=:email, notes=:notes WHERE id=:id''', details) self._db.commit() def delete_contact(self, contact_id): self._db.cursor().execute(''' DELETE FROM contacts WHERE id=:id''', {"id": contact_id}) self._db.commit() 2. `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. .. container:: toggle .. container:: header **Show/hide code** .. code-block:: python class ListView(Frame): def __init__(self, screen, model): super(ListView, self).__init__(screen, screen.height * 2 // 3, screen.width * 2 // 3, on_load=self._reload_list, hover_focus=True, 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( Widget.FILL_FRAME, 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) self.add_layout(layout) layout.add_widget(self._list_view) layout.add_widget(Divider()) layout2 = Layout([1, 1, 1, 1]) self.add_layout(layout2) 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) self.fix() 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.save() self._model.current_id = self.data["contacts"] raise NextScene("Edit Contact") def _delete(self): self.save() self._model.delete_contact(self.data["contacts"]) self._reload_list() @staticmethod def _quit(): raise StopApplication("User pressed quit") 3. `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. .. container:: toggle .. container:: header **Show/hide code** .. code-block:: python class ContactView(Frame): def __init__(self, screen, model): super(ContactView, self).__init__(screen, screen.height * 2 // 3, screen.width * 2 // 3, hover_focus=True, 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) self.add_layout(layout) 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]) self.add_layout(layout2) layout2.add_widget(Button("OK", self._ok), 0) layout2.add_widget(Button("Cancel", self._cancel), 3) self.fix() def reset(self): # Do standard reset to clear out form, then populate with new data. super(ContactView, self).reset() self.data = self._model.get_current_contact() def _ok(self): self.save() self._model.update_current_contact(self.data) raise NextScene("Main") @staticmethod 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 ============================= ===================================================================== :py:obj:`.Button` Action buttons - e.g. ok/cancel/etc. :py:obj:`.CheckBox` Simple yes/no tick boxes. :py:obj:`.DatePicker` A single-line widget for selecting a date (using a pop-up list). :py:obj:`.Divider` A spacer between widgets (for aesthetics). :py:obj:`.DropdownList` A single-line widget that pops up a list from which the user can select a single value. :py:obj:`.FileBrowser` A multi-line widget for listing the local file system. :py:obj:`.Label` A label for a group of related widgets. :py:obj:`.ListBox` A list of possible options from which users can select one value. :py:obj:`.MultiColumnListBox` Like a ListBox, but for displaying tabular data. :py:obj:`.RadioButtons` A list of radio buttons. These allow users to select one value from a list of options. :py:obj:`.Text` A single line of editable text. :py:obj:`.TextBox` A multi-line box of editable text. :py:obj:`.TimePicker` A single-line widget for selecting a time (using a pop-up list). :py:obj:`.VerticalDivider` A vertical line divider - useful for providing a visual marker between columns in a Layout. ============================= ===================================================================== .. note:: 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: .. code-block:: python frame = Frame(screen, 80, 20, has_border=False) layout = Layout([1, 1, 1, 1]) frame.add_layout(layout) 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: .. code-block:: python 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: .. code-block:: python layout = Layout([100]) frame.add_layout(layout) 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 :py:obj:`.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 :py:obj:`.Label` widget. If you need something a little more advanced - e.g. a pre-formatted multi-line status bar, use a :py:obj:`.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: .. code-block:: python layout1 = Layout([100]) frame.add_layout(layout1) layout1.add_widget(Text(label="Search:", name="search_string")) layout2 = Layout([100]) frame.add_layout(layout2) 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 :ref:`custom-colours-ref`. For an example of such a widget, see the top.py 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:: +------------------------------------------------------------------------+ |Screen..................................................................| |........................................................................| |...+----------------------------------------------------------------+...| |...|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). To get spacing between columns, you can just use a small empty column between your active content. This size will be proportional to the other columns and so will change as the screen is resized. If you want to avoid this resizing, you can use the `gutter` option on the `Layout`, which will always provide an exact character count between columns for all screen sizes. 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 :py:obj:`.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. .. warning:: 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: .. code-block:: python (Screen.COLOUR_GREEN, Screen.A_BOLD, Screen.COLOUR_BLUE) 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 :py:meth:`~.Frame.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 :py:obj:`~.widgets.THEMES` .. _custom-colours-ref: 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 :py:obj:`~.Widget.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 :py:obj:`.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 (:py:obj:`~.AsciimaticsParser` or :py:obj:`~.AnsiTerminalParser`) and pass in values containing the associated control codes to change colours where needed. Check out the latest code in forms.py and top.py 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 :py:obj:`~.Widget.value` property. 2. You can set the value for all Widgets in a `Frame` by setting at the :py:obj:`~.Frame.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 :py:meth:`~.Frame.save`, so you need to call this method to refresh the cache before accessing it. For example: .. code-block:: python # Form definition layout = Layout([100]) frame.add_layout(layout) layout.add_widget(Text("Name:", "name")) layout.add_widget(Text("Address:", "address")) layout.add_widget(TextBox(5, "Notes:", "notes", as_string=True)) # Sample frame.data 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 :py:meth:`~.Frame.save` specifying `validate=True`, asciimatics will check all fields and throw an :py:obj:`.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. Modal Frames ~~~~~~~~~~~~ When constructing a Frame, you can specify whether it is modal or not using the `is_modal` parameter. Modal Frames will not allow any input to filter through to other Effects in the Scene, so when one is on top of all other Effects, this means that only it will see the user input. This is commonly used for, but not limited to, notifications to the user that must be acknowledged (as implemented by :py:obj:`.PopUpDialog`). 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 .. code-block:: python # 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... screen.play(scenes, unhandled_input=global_shortcuts) .. warning:: 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 :py:meth:`.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 :ref:`ctrl-s-issues-ref` 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. Callbacks ~~~~~~~~~ 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. Exceptions ~~~~~~~~~~ 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. :py:obj:`.StopApplication` - This exception will stop the animation engine and return flow to the function that called into the Screen. 2. :py:obj:`.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 round robin to the next available Scene. Note that the above logic requires each Scene to be given a unique name on construction. For example: .. code-block:: python # Given this scene list... scenes = [ Scene([ListView(screen, contacts)], -1, name="Main"), Scene([ContactView(screen, contacts)], -1, name="Edit Contact") ] screen.play(scenes) # 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 with a 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: .. code-block:: python scenes = [] effects = [ Julia(screen), InputFormFrame(screen) ] scenes.append(Scene(effects, -1)) screen.play(scenes) 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 :py:obj:`.Background` Effect to set a background colour for the whole screen behind your Frames. See the forms.py demo for an example of this use case. Pop-up dialogs ~~~~~~~~~~~~~~ Along a similar line, you can also add a :py:obj:`.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 :py:obj:`.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. .. code-block:: python def main(screen, scene): # Define your Scenes here scenes = ... # Run your program screen.play(scenes, stop_on_resize=True, start_scene=scene) last_scene = None while True: try: Screen.wrapper(main, arguments=[last_scene]) sys.exit(0) 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 :py:obj:`~.Frame.data` is restored in the new `Scene`. 2. To duplicate any dynamically added :py:obj:`.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. .. code-block:: python 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 contact_list.py for an example of this. Custom widgets -------------- To develop your own widget, you need to define a new class that inherits from :py:obj:`.Widget`. You then have to implement the following functions. 1. :py:meth:`~.Widget.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. :py:meth:`~.Widget.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. :py:meth:`~.Widget.process_event` - This is where you should put your code to handle mouse and keyboard events. 4. :py:obj:`~.Widget.value` - This must return the current value for the widget. 5. :py:meth:`~.Widget.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.