Numeric input UI elements

from zpui_lib.ui import IntegerAdjustInput
start_from = 0
number = IntegerAdjustInput(start_from, i, o).activate()
if number is None: #Input cancelled
    return
#process the number

Instantiating the IntegerAdjustInput:

class zpui_lib.ui.IntegerAdjustInput(number, i, o, message='Pick a number:', interval=1, name='IntegerAdjustInput', mode='normal', max=None, min=None, config=None)

Implements a simple number input dialog which allows you to increment/decrement a number using 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:

• number: The number being changed.

• initial_number: The number sent to the constructor. Used by reset() method.

• selected_number: A flag variable to be returned by activate().

• in_foreground : a flag which indicates if UI element is currently displayed. If it’s not active, inhibits any of element’s actions which can interfere with other UI element being displayed.

__init__(number, i, o, message='Pick a number:', interval=1, name='IntegerAdjustInput', mode='normal', max=None, min=None, config=None)

Initialises the IntegerAdjustInput object.

Args:

• number: number to be operated on

• i, o: input&output device objects

Kwargs:

• message: Message to be shown on the first line of the screen while UI element is active.

• interval: Value by which the number is incremented and decremented.

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

• mode: Number display mode, either “normal” (default) or “hex” (“float” will be supported eventually)

• min: minimum value, will not go lower than that.

• max: maximum value, will not go higher than that.

print_number()

A debug method. Useful for hooking up to an input event so that you can see current number value.

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.

print_name()

A debug method. Useful for hooking up to an input event so that you can see which UI element is currently active.

More info:

class zpui_lib.ui.IntegerAdjustInput(number, i, o, message='Pick a number:', interval=1, name='IntegerAdjustInput', mode='normal', max=None, min=None, config=None)

Bases: BaseUIElement

Implements a simple number input dialog which allows you to increment/decrement a number using 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:

• number: The number being changed.

• initial_number: The number sent to the constructor. Used by reset() method.

• selected_number: A flag variable to be returned by activate().

• in_foreground : a flag which indicates if UI element is currently displayed. If it’s not active, inhibits any of element’s 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, 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.

clamp()

Clamps the number if either min or max are set.

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.

decrement(multiplier=1)

Decrements the number by selected interval

determine_location()

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

exit()

Exits discarding all the changes to the number.

generate_keymap()

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

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

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.

increment(multiplier=1)

Increments the number by selected interval

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.

print_number()

A debug method. Useful for hooking up to an input event so that you can see current number value.

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

A placeholder to be used for BaseUIElement.

reset()

Resets the number, setting it to the number passed to the constructor.

select_number()

Selects the currently active number value, making activate() return it.

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

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.