DialogBox UI element

This UI element allows you to make sure the user actually wants to proceed with some kind of action/decision.

from zpui_lib.ui import DialogBox
...
choice = DialogBox("ync", i, o, name="My dialogbox of my app").activate()
if choice: # "Yes" was selected
    # do things

By default, you can pass string values like “ync” (or “yn”, or “yc”, or “cy”), where the “y”, “n” and “c” characters will be parsed as “Yes” (True), “No” (False) and “Cancel” (None) options respectively (True, False and None being return values). Exiting by using LEFT will also result in None being returned.

You can also pass custom labels/return values like this:

choice = DialogBox([["Abort", "abort"], ["Retry", "retry"], ["Ignore", "ignore"]], i, o, name="My dialogbox of my app").activate()

Instantiating the DialogBox:

class zpui_lib.ui.DialogBox(values, i, o, message='Are you sure?', name='DialogBox', **kwargs)[source]

Implements a dialog box with given values (or some default ones if chosen).

__init__(values, i, o, message='Are you sure?', name='DialogBox', **kwargs)[source]

Initialises the DialogBox object.

Args:

values: values to be used. Should be a list of [label, returned_value] pairs.

You can also pass a string “yn” to get “Yes(True), No(False)” options, or “ync” to get “Yes(True), No(False), Cancel(None)” options.

Values put together with spaces between them shouldn’t be longer than the screen’s width.

i, o: input&output device objects

Kwargs:

message: Message to be shown on the first line of the screen when UI element is activated

name: UI element name which can be used internally and for debugging.

set_start_option(option_number)[source]: Allows you to set position of the option that’ll be selected upon DialogBox activation.

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

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.

More info:

class zpui_lib.ui.DialogBox(values, i, o, message='Are you sure?', name='DialogBox', **kwargs)[source]

Bases: BaseUIElement

Implements a dialog box with given values (or some default ones if chosen).

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, is called each time activate() is called. Is the perfect place to clear any flags that you don’t want to persist between multiple activations of a single instance of an UI element.

before_foreground(): 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()[source]: Deactivates the UI element, exiting it.

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

generate_keymap()[source]: Returns the default keymap for the UI element. To be implemented by a child object.

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_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()[source]: A method that will be called all the time while the UI element is in background (regardless of whether it’s in foreground or not). To be implemented by a child object.

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

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_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).

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

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_start_option(option_number)[source]: Allows you to set position of the option that’ll be selected upon DialogBox activation.

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(): A method that is called once in activate to set all the variables, activates the input device and draw the first image on the display.

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

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.