Checkbox UI element

from zpui_lib.ui import Checkbox
contents = [
    ["Apples", 'apples'], #"Apples" will not be checked on activation
    ["Oranges", 'oranges', True], #"Oranges" will be checked on activation
    ["Bananas", 'bananas']
]
selected_fruits = Checkbox(checkbox_contents, i, o).activate()
class zpui_lib.ui.Checkbox(*args, **kwargs)[source]

Implements a checkbox which can be used to enable or disable some functions in your application.

Attributes:

  • contents: list of checkbox entries which was passed either to Checkbox constructor or to checkbox.set_contents().

    Checkbox entry structure is a list, where:

    • entry[0] (entry label) is usually a string which will be displayed in the UI, such as “Option 1”. In case of entry_height > 1, can be a list of strings, each of which represents a corresponding display row occupied by the entry.

    • entry[1] (entry name) is a name returned by the checkbox upon its exit in a dictionary along with its boolean value.

    • entry[2] (entry state) is the default state of the entry (checked or not checked). If not present, assumed to be`` default_state``.

    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 menu element’s number in self.contents.

  • in_foreground : a flag which indicates if checkbox 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.

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

Args:

  • contents: a list of element descriptions, which can be constructed as described in the Checkbox object’s docstring.

  • i, o: input&output device objects

Kwargs:

  • name: Checkbox name which can be used internally and for debugging.

  • entry_height: number of display rows that one checkbox element occupies.

  • default_state: default state for each entry that doesn’t have a state (entry[2]) specified in contents (default: False)

  • final_button_name: label for the last button that confirms the selection (default: "Accept")

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

Bases: BaseListUIElement

Implements a checkbox which can be used to enable or disable some functions in your application.

Attributes:

  • contents: list of checkbox entries which was passed either to Checkbox constructor or to checkbox.set_contents().

    Checkbox entry structure is a list, where:

    • entry[0] (entry label) is usually a string which will be displayed in the UI, such as “Option 1”. In case of entry_height > 1, can be a list of strings, each of which represents a corresponding display row occupied by the entry.

    • entry[1] (entry name) is a name returned by the checkbox upon its exit in a dictionary along with its boolean value.

    • entry[2] (entry state) is the default state of the entry (checked or not checked). If not present, assumed to be`` default_state``.

    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 menu element’s number in self.contents.

  • in_foreground : a flag which indicates if checkbox 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.

view_mixin

alias of CheckboxRenderingMixin

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

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.

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]

Changes the current element’s state to the opposite. Is typically used as a callback from input event processing thread. Afterwards, refreshes the screen.

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

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.