Refresher UI element

from zpui_lib.ui import Refresher
counter = 0
def get_data():
    counter += 1
    return [str(counter), str(1000-counter)] #Return value will be sent directly to output.display_data
Refresher(get_data, i, o, 1, name="Counter view").activate()

Instantiating the Refresher:

class zpui_lib.ui.Refresher(refresh_function, i, o, refresh_interval=1, keymap=None, name='Refresher', **kwargs)

A Refresher allows you to update the screen on a regular interval. All you need is to provide a function that’ll return the text/image you want to display; that function will then be called with the desired frequency and the display will be updated with whatever it returns.

__init__(refresh_function, i, o, refresh_interval=1, keymap=None, name='Refresher', **kwargs)

Initialises the Refresher object.

Args:

• refresh_function: a function which returns data to be displayed on the screen upon being called, in the format accepted by screen.display_data() or screen.display_image(). To be exact, supported return values are:

  • Tuples and lists - are converted to lists and passed to display_data()

  • Strings - are converted to a single-element list and passed to display_data()

  • PIL.Image objects - are passed to display_image()

• i, o: input&output device objects

Kwargs:

• refresh_interval: Time between display refreshes (and, accordingly, refresh_function calls).

• keymap: Keymap entries you want to set while Refresher is active. * By default, KEY_LEFT deactivates the Refresher, if you want to override it, make sure that user can still exit the Refresher.

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

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.Refresher(refresh_function, i, o, refresh_interval=1, keymap=None, name='Refresher', **kwargs)

Bases: BaseUIElement

A Refresher allows you to update the screen on a regular interval. All you need is to provide a function that’ll return the text/image you want to display; that function will then be called with the desired frequency and the display will be updated with whatever it returns.

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.

background_if_inactive()

If the UI element hasn’t been launched yet, launches it in background and waits until it’s fully running. Otherwise, resumes the UI element.

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.

calculate_intervals()

Calculates the sleep intervals of the refresher, so that no matter the refresh_interval, the refresher is responsive. Also, sets the counter to zero.

change_interval()

A helper function to adjust the Refresher’s refresh interval while it’s running

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

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.

key_deactivate()

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

pause()

Pauses the refresher, not allowing it to print anything on the screen while it’s paused.

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

A placeholder to be used for BaseUIElement.

resume()

Resumes the refresher after it’s been paused, allowing it to continue printing things on the screen. Refreshes the screen when it’s called.

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

Allows setting Refresher’s refresh intervals after it’s been initialized

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

wait_for_active(timeout=100)

If the UI element hasn’t been launched yet, launches it in background and waits until it’s fully running.

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.