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()

class ui.menu.Menu(contents, i, o, name='Menu', entry_height=1, append_exit=True, catch_exit=True, exitable=True, contents_hook=None, scrolling=True)[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 elements, used both in system core and in most of the applications.

Attributes:

contents: list of menu elements which was passed either to Menu constructor or to menu.set_contents().
Menu element structure is a list, where:
- element[0] (element’s representation) is either a string, which simply has the element’s value as it’ll be displayed, such as “Menu element 1”, or, in case of entry_height > 1, can be a list of strings, each of which represents a corresponding display row occupied by the element.
- element[1] (element’s callback) is a function which is called when menu’s element is activated (such as pressing ENTER button when menu’s element is selected). * Can be omitted if you don’t need to have any actions taken upon activation of the element. * Can be specified as ‘exit’ if you want a menu element that exits the menu upon activation.
If you want to set contents after the initalisation, please, use set_contents() method.
_contents: “Working copy” of menu contents, basically, a contents attribute which has been processed by self.process_contents.
pointer: currently selected menu element’s number in self._contents.
in_background: a flag which indicates if menu is currently active, either if being displayed or being in background (for example, if a sub-menu of this menu is currently active)
in_foreground : a flag which indicates if menu is currently displayed. If it’s not active, inhibits any of menu’s actions which can interfere with other menu or UI element being displayed.
first_displayed_entry : Internal pointer which points to the number of self._contents element which is at the topmost position of the menu as it’s currently displayed on the screen
last_displayed_entry : Internal pointer which points to the number of self._contents element which is at the lowest position of the menu as it’s currently displayed on the screen
no_entry_message : The entry displayed in case menu has no elements

__init__(contents, i, o, name='Menu', entry_height=1, append_exit=True, catch_exit=True, exitable=True, contents_hook=None, scrolling=True)[source]¶

Initialises the Menu object.

Args:

contents: a list of values, which can be constructed as described in the Menu object’s docstring.

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 element occupies.

append_exit: Appends an “Exit” alement to menu elements. Doesn’t do it if any of elements has callback set as ‘exit’.

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 at all by pressing KEY_LEFT. Set by default and disables KEY_LEFT callback if unset. Is used for pyLCI main menu, not advised to be used in other settings.

activate()[source]¶: A method which is called when menu needs to start operating. Is blocking, sets up input&output devices, renders the menu and waits until self.in_background is False, while menu callbacks are executed from the input device thread. This method also raises MenuExitException if menu exited due to it and catch_exit is set to False.

deactivate()[source]¶: Deactivates the menu completely, exiting it. As for now, pointer state is preserved through menu activations/deactivations

generate_keymap()[source]¶: Sets the keymap. In future, will allow per-system keycode-to-callback tweaking using a config file.

print_contents()[source]¶: A debug method. Useful for hooking up to an input event so that you can see the representation of menu’s contents.

print_name()[source]¶: A debug method. Useful for hooking up to an input event so that you can see which menu is currently processing input events.

set_contents(contents)[source]¶: Sets the menu contents, as well as additionally re-sets last & first_displayed_entry pointers and calculates the value for last_displayed_entry pointer.

class ui.menu.MenuExitException[source]¶: An exception that you can throw from a menu callback to exit the menu that callback was called from