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.
Available input drivers:
InputProxy¶
The i
variable you have supplied by 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.
-
class
input.input.
InputProxy
(context_alias)[source]¶ -
-
set_streaming
(callback)[source]¶ 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
()[source]¶ 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)[source]¶ Sets a single callback.
>>> i = InputProxy("test") >>> i.clear_keymap() >>> i.set_callback("KEY_ENTER", lambda: None) >>> "KEY_ENTER" in i.keymap True
-
check_special_callback
(key_name)[source]¶ Raises exceptions upon setting of a special callback on a reserved/taken keyname.
-
set_maskable_callback
(key_name, callback)[source]¶ 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)[source]¶ Sets a single nonmaskable callback. Raises
CallbackException
if the callback is one of the reserved keys or already is in maskable/nonmaskable keymap.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 thekeymap
won’t be called).
-
set_keymap
(new_keymap)[source]¶ Sets all the callbacks supplied, removing the previously set keymap completely.
-
update_keymap
(new_keymap)[source]¶ 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
>>> 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
-
__weakref__
¶ list of weak references to the object (if defined)
-
Sample 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()