Menu UI element¶

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

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

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

Bases: ui.base_list_ui.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.

__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.

class ui.MenuExitException[source]¶

Bases: exceptions.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)