Menu UI element

from zpui_lib.ui import Menu
...
menu_contents = [
  ["Do this", do_this],
  ["Do this with 20", lambda: do_this(x=20)],
  ["Do nothing"],
  ["Do this with 30; right click for 40", lambda: do_this(x=30), lambda: do_this(x=40)],
  ["My submenu", submenu.activate]
]
Menu(menu_contents, i, o, "My menu").activate()

For Menu usage examples, tips, and tricks, see tutorial 1 and tutorial 2!

Menu always returns None, so you don’t need to check its return value.

Instantiating the Menu:

class zpui_lib.ui.Menu(*args, **kwargs)[source]

Implements a menu which can be used to navigate through your application, output a list of values or select actions to perform. Is one of the most used UI elements, used both in system core and in most of the applications.

__init__(*args, **kwargs)[source]

Initialises the Menu object.

Args:

contents: list of menu entries which was passed either to Menu constructor or to menu.set_contents().

Simplest Menu entry is a list, where:

entry[0] (entry label) is usually a string which will be displayed in the UI, such as “Menu entry 1”. If entry_height > 1, can be a list of strings, each of those strings will be shown on a separate display row.

entry[1] (entry callback) is a function which is called when the user presses Enter.

Can be omitted if you don’t need to have any actions taken upon activation of the entry.

You can supply ‘exit’ (a string, not a function) if you want a menu entry that exits the menu when the user presses Enter.

entry[2] (entry second callback) is a callback for the right key press.

You can also pass Entry objects as entries - text will be used as label, cb will be used as first callback and cb2 will be used as the second callback.

If you want to set contents after the initialisation, please, use set_contents() method.*

i, o: input&output device objects

Kwargs:

name: Menu name which can be used internally and for debugging.

entry_height: number of display rows one menu entry occupies.

append_exit: Appends an “Exit” element to menu contents.

catch_exit: If MenuExitException is received and catch_exit is False, it passes MenuExitException to the parent menu so that it exits, too. If catch_exit is True, MenuExitException is not passed along.

exitable: Decides if menu can exit by pressing KEY_LEFT. Set by default and disables KEY_LEFT callback if unset. Is used for ZPUI main menu, not advised to be used in other settings.

contents_hook: A function that is called every time menu goes in foreground that returns new menu contents. Allows to almost-dynamically update menu contents.

on_contents_hook_fail: A function that is called when contents_hook raises an exception or returns None. Will be passed two arguments: 1) arg self (Menu object) 2) kwarg exception=bool (True or False, whether contents_hook raised an exception or not).

activate(): A method which is called when the UI element needs to start operating. Is blocking, sets up input&output devices, refreshes the UI element, then calls the idle_loop method while the UI element is active. self.in_foreground is True, while callbacks are executed from the input device thread.

deactivate(): Deactivates the UI element, exiting it.

set_contents(contents): Sets the UI element contents and triggers pointer recalculation in the view.

More info:

class zpui_lib.ui.Menu(*args, **kwargs)[source]

Bases: BaseListUIElement

Implements a menu which can be used to navigate through your application, output a list of values or select actions to perform. Is one of the most used UI elements, used both in system core and in most of the applications.

view_mixin: alias of MenuRenderingMixin

activate(): A method which is called when the UI element needs to start operating. Is blocking, sets up input&output devices, refreshes the UI element, then calls the idle_loop method while the UI element is active. self.in_foreground is True, while callbacks are executed from the input device thread.

activate_input(): Sets up the input device if one was passed to the UI element - calling i.stop_listen, self.configure_input and i.listen. If an input element wasn’t passed, checks if one is expected.

after_activate(): Hook for child UI elements, is called each time before activate() returns - before get_return_value is called. Is the perfect place to, say, remove input streaming callbacks.

before_activate()[source]: Hook for child UI elements, meant to be called. For a start, resets the pointer to the start_pointer.

before_foreground()[source]: Hook for child UI elements. Is called each time to_foreground is called.

configure_input(): Configures the input device - you can set your keymap, streaming callbacks or both - abstracting away stop_listen and listen. Can be overridden by child elements.

deactivate(): Deactivates the UI element, exiting it.

determine_location(): Figures out the place in ZPUI where the UI element is summoned from. Pretty cool!

exec_contents_hook()[source]: Executes contents_hook and, if successful, sets new contents. If contents_hook failed to execute (or returned None), will see if on_contents_hook_fail attribute is callable and, if it is, calls it. Otherwise, deactivates the Menu. Returns True if successful. If failed at any step, returns False. If contents_hook is not set, returns None.

generate_keymap(): Makes the keymap dictionary for the input device.

generate_name_if_not_supplied(): Generating a random yet descriptive UI element name if one was not supplied. The name hasa to be random enough so that overlays can be applied properly. The name generated will include the directory where the app is called from.

get_default_view(): Decides on the view to use for a BaseListUIElement when config file has no information on it.

get_displayed_contents(): This function is to be used for views, in case an UI element wants to display entries differently than they’re stored (for example, this is used in NumberedMenu).

get_return_value()[source]: Can be overridden by child UI elements. Return value will be returned when UI element’s activate() exits.

get_views_dict(): Is called if you explicitly set up your UI element to accept views. Expected to return a list of all available views.

idle_loop(): Contains code which will be executed in UI element’s idle loop. By default, is just a 0.1 second sleep and a scroll() call.

key_deactivate(): A method to deactivate the menu specifically on key press. Is mostly useful for making key callbacks easily patchable.

move_down(): Moves the pointer one entry down, if possible. Is typically used as a callback from input event processing thread.

move_to_end(): Goes to the last entry if not already there.

move_to_start(counter=None): Goes to the first entry if not already there.

move_up(): Moves the pointer one entry up, if possible. Is typically used as a callback from input event processing thread.

on_pointer_update(): Lets you do things every time the pointer has been updated. Undefined by default. You’d benefit from making sure you keep calling it every time you update the pointer!

page_down(counter=None): Scrolls up a full screen of entries, if possible. If not possible, moves as far as it can.

page_up(counter=None): Scrolls down a full screen of UI entries, if possible. If not possible, moves as far as it can.

print_contents(): A debug method. Useful for hooking up to an input event so that you can see the representation of current UI element’s contents.

print_keymap(): A debug method. Useful for hooking up to an input event so that you can see what’s the keymap of a currently active UI element.

print_name(): A debug method. Useful for hooking up to an input event so that you can see which UI element is currently active.

process_callback(func): Decorates a function so that during its execution the UI element stops being in foreground. Is typically used as a wrapper for a callback from input event processing thread. After callback’s execution is finished, sets the keymap again and refreshes the UI element.

process_contents()

Processes contents for custom callbacks. Currently, only ‘exit’ calbacks are supported.

If self.append_exit is set, it goes through the menu and removes every callback which either is self.deactivate or is just a string ‘exit’. Then, it appends a single “Exit” entry at the end of menu contents. It makes dynamically appending entries to menu easier and makes sure there’s only one “Exit” callback, at the bottom of the menu.

process_keymap(keymap): Processes the keymap, wrapping all callbacks using the process_callback method. If a string is supplied instead of a callable, it looks it up from methods - if a method is not found, raises ValueError. Also, sets KEY_LEFT to deactivate unless self.override_left is set to False (override with caution).

process_right_press()[source]: Calls the second callback on the right button press.

refresh(): A placeholder to be used for BaseUIElement.

select_entry(callback_number=1, entry_index=None)[source]: Gets the currently specified entry’s description from self.contents and executes the callback, if set. Is typically used as a callback from input event processing thread. After callback’s execution is finished, sets the keymap again and refreshes the screen. If MenuExitException is returned from the callback, exits menu.

set_contents(contents): Sets the UI element contents and triggers pointer recalculation in the view.

set_default_keymap(): Sets the default keymap, getting it straight from the generate_keymap.

set_keymap(keymap): Receives and processes UI element’s keymap (filtered using process_keymap before setting).

set_views_dict(): Sets the views dict and adds view mixins to views if mixins are available and adding one is appropriate.

to_background(): Signals activate to finish executing.

to_foreground(): Is called when UI element’s activate() method is used, sets flags and performs all the actions so that UI element can display its contents and receive keypresses. Also, refreshes the screen.

trigger_contents_hook()[source]: External method to trigger Menu contents update if the contents_hook is set. If contents_hook is not set, raises an AttributeError.

update_keymap(new_keymap): Updates the UI element’s keymap with a new one (filtered using process_keymap before updating).

validate_contents(contents): A hook to validate contents before they’re set. If validation is unsuccessful, raise exceptions (it’s better if exception message contains the faulty entry). Does not check if the contents are falsey.

in_background = False: flag which indicates whether menu is currently active, either being displayed or just waiting in background (for example, when you go into a sub-menu, the parent menu will still be considered active).

in_foreground = False: flag which indicates whether menu is currently displayed.

property is_active: A condition to be checked by activate to see when the UI element is active. Can be overridden by child elements if necessary. By default returns self.in_background, so if you only have a single UI element without external callback processing, it might make sense to check in_foreground instead.

pointer = 0: number of currently selected menu entry, starting from 0.

exception zpui_lib.ui.MenuExitException[source]

Bases: Exception

An exception that you can throw from a menu callback to exit the menu that the callback was called from (and underlying menus, if necessary)