Listbox UI element

from zpui_lib.ui import Listbox
...
lbc = [
["Option1", "option_1"],
["option_2"], # will be used as both name and value
]
choice = Listbox(lbc, i, o, name="My listbox of my app").activate()
if choice: # user didn't cancel and selected something
    # do things

Listbox will return the selected option’s value (element[1]), or name (element[0]) if no value was passed. Otherwise, if the user exited Listbox by pressing LEFT, returns None.

Instantiating the Listbox:

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

Implements a listbox to choose one thing from many.

Attributes:

contents: list of listbox entries
Listbox entry is a list, where:
- entry[0] (entry’s label) is usually a string which will be displayed in the UI, such as “Option 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’s value) is the value to be returned when entry is selected. If it’s not supplied, entry’s label is returned instead.
You can also pass Entry objects as entries - text will be used as label and name will be used as name.

If you want to set contents after the initalisation, please, use set_contents() method.
pointer: currently selected entry’s number in self.contents.
in_foreground : a flag which indicates if listbox is currently displayed. If it’s not set, inhibits any of listboxes actions which can interfere with other UI element being displayed.

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

Initialises the Listbox object.

Args:

contents: listbox contents

i, o: input&output device objects

Kwargs:

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

selected: value (that is, entry[1]) of the element to be selected. If no element with this value is found, this is ignored.

entry_height: number of display rows one listbox entry occupies.

append_exit: appends an “Exit” entry to listbox.

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.Listbox(*args, **kwargs)[source]

Bases: BaseListUIElement

Implements a listbox to choose one thing from many.

Attributes:

contents: list of listbox entries
Listbox entry is a list, where:
- entry[0] (entry’s label) is usually a string which will be displayed in the UI, such as “Option 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’s value) is the value to be returned when entry is selected. If it’s not supplied, entry’s label is returned instead.
You can also pass Entry objects as entries - text will be used as label and name will be used as name.

If you want to set contents after the initalisation, please, use set_contents() method.
pointer: currently selected entry’s number in self.contents.
in_foreground : a flag which indicates if listbox is currently displayed. If it’s not set, inhibits any of listboxes actions which can interfere with other UI element being displayed.

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(): Hook for child UI elements, meant to be called. For a start, resets the pointer to the start_pointer.

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

go_to_value(value)[source]: Moves the pointer to the first entry which has the value passed.

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()[source]

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(): To be overridden by child UI elements. Is executed when RIGHT is pressed in UI element.

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

select_entry()[source]: Gets the currently specified entry’s index and sets it as selected_entry attribute. |Is typically used as a callback from input event processing thread.

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.

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.

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.