Input subsystem

These are the devices that receive key commands from some external source and route them to your applications. At the input system core, there’s InputListener. It receives key events from drivers you use and routes them to currently active application.

Some of the available input drivers (non-exhaustive, look in ZPUI input/drivers/ directory to see more):

• HID input driver

• PCF8574 input driver

• Raspberry Pi GPIO input driver

InputProxy

The i variable you have supplied by app.py or main.py load_app() in your applications is an InputProxy instance. It’s operating on key names, such as “KEY_ENTER” or “KEY_UP”. You can assign callback once a keypress with a matching keyname is received, which is as simple as i.set_callback(key_name, callback). You can also set a dictionary of "keyname":callback_function mappings, this would be called a keymap. The InputProxy only receives events when your app is in foreground.

class input.input.InputProxy(context_alias)

__init__(context_alias)

set_streaming(callback)

Sets a callback for streaming key events. This callback will be called each time a key is pressed that doesn’t belong to one of the three keymaps.

The callback will be called with key_name as first argument but should support arbitrary number of keyword arguments if compatibility with future versions is desired. (basically, add **kwargs to it).

If a callback was set before, replaces it. The callbacks set will not be restored after being replaced by other callbacks. Care must be taken to make sure that the callback is only executed when the app or UI element that set it is active.

remove_streaming()

Removes a callback for streaming key events, if previously set by any app/UI element. This is more of a convenience function, to avoid your callback being called when your app or UI element is not active.

set_callback(key_name, callback, silent=False)

Sets a single callback. The silent kwarg can be set so that the callback is not sanity checked (warnings shown in the logs).

>>> i = InputProxy("test")
>>> i.clear_keymap()
>>> i.set_callback("KEY_ENTER", lambda: None)
>>> "KEY_ENTER" in i.keymap
True

sanity_check_cb(key_name, callback)

Checks the keyname and callback. Can be turned off by silent=True passed to set_keymap/set_callback/etc.

check_special_callback(key_name)

Raises exceptions upon setting of a special callback on a reserved/taken keyname.

set_maskable_callback(key_name, callback, silent=False)

Sets a single maskable callback. Raises CallbackException if the callback is one of the reserved keys or already is in maskable/nonmaskable keymap.

A maskable callback is global (can be cleared) and will be called upon a keypress unless a callback for the same keyname is already set in keymap.

set_nonmaskable_callback(key_name, callback, silent=False)

Sets a single nonmaskable callback. Raises CallbackException if the callback is one of the reserved keys or already is in maskable/nonmaskable keymap. The silent kwarg can be set so that the callback is not sanity checked (warnings shown in the logs).

A nonmaskable callback is global (never cleared) and will be called upon a keypress even if a callback for the same keyname is already set in keymap (callback from the keymap won’t be called).

remove_callback(key_name)

Removes a single callback.

remove_maskable_callback(key_name)

Removes a single maskable callback.

get_keymap()

Returns the current keymap.

set_keymap(new_keymap, silent=False)

Sets all the callbacks supplied, removing the previously set keymap completely. The silent kwarg can be set so that the callback is not sanity checked (warnings shown in the logs).

update_keymap(new_keymap, silent=False)

Updates the InputProxy keymap with entries from another keymap. Will add/replace callbacks for keys in the new keymap, but will leave the existing keys that are not in new keymap intact. The silent kwarg can be set so that the callback is not sanity checked (warnings shown in the logs).

>>> i = InputProxy("test")
>>> i.set_keymap({"KEY_LEFT":lambda:1, "KEY_DOWN":lambda:2})
>>> i.keymap["KEY_LEFT"]()
1
>>> i.keymap["KEY_DOWN"]()
2
>>> i.update_keymap({"KEY_LEFT":lambda:3, "KEY_1":lambda:4})
>>> i.keymap["KEY_LEFT"]()
3
>>> i.keymap["KEY_DOWN"]()
2
>>> i.keymap["KEY_1"]()
4

clear_keymap()

Removes all the callbacks set.

__weakref__

list of weak references to the object (if defined)

Example usage - it should rarely be necessary for you to set callbacks directly, as this is mostly taken care of by the UI elements.

i.stop_listen()
i.clear_keymap() #Useful because there might be callbacks left from whatever your function was called by
#... Set your callbacks
i.set_callback("KEY_ENTER", my_function)
i.listen()

Drivers:

These are only some of the drivers:

• HID input driver
  • InputDevice
• PCF8574 input driver
  • InputDevice
• Raspberry Pi GPIO input driver
  • InputDevice