peng3d.keybind
- Dynamic Keybinding System¶
-
class
peng3d.keybind.
KeybindHandler
(peng: peng3d.Peng)[source]¶ Handler class that automatically converts incoming key events to key combo events.
A keybinding always is of format
[MOD1-[MOD2-]]KEY
with potentially more modifiers.See
MODNAME2MODIFIER
for more information about existing modifiers.Note that the order in which modifiers are listed also is the order of the above listing.
Keybindings are matched exactly, and optionally a second time without the modifiers listed in
OPTIONAL_MODNAMES
ifcontrols.keybinds.strict
is set to False.-
add
(keybind: str, kbname: str, handler: Callable[[int, int, bool], Any], mod: bool = True) → None[source]¶ Adds a keybind to the internal registry.
Keybind names should be of the format
namespace:category.subcategory.name
e.g.peng3d:actor.player.controls.forward
for the forward key combo for the player actor.Parameters: - keybind (str) – Keybind string, as described above
- kbname (str) – Name of the keybind, may be used to later change the keybinding without re-registering
- handler (function) – Function or any other callable called with the positional arguments
(symbol,modifiers,release)
if the keybind is pressed or released - mod (int) – If the keybind should respect modifiers
-
changeKeybind
(kbname: str, combo: str) → None[source]¶ Changes a keybind of a specific keybindname.
Parameters:
-
handle_combo
(combo: str, symbol: int, modifiers: int, release: bool = False, mod: bool = True) → None[source]¶ Handles a key combination and dispatches associated events.
First, all keybind handlers registered via
add()
will be handled, then the pyglet eventon_key_combo
with params(combo,symbol,modifiers,release,mod)
is sent to thePeng()
instance.Also sends the events
peng3d:keybind.combo
,peng3d:keybind.combo.press
and :peng3d:event`peng3d:keybind.combo.release`.Params str combo: Key combination pressed Params int symbol: Key pressed, passed from the same argument within pyglet Params int modifiers: Modifiers held while the key was pressed Params bool release: If the combo was released Params bool mod: If the combo was sent without mods
-
mod_is_held
(modname: str, modifiers: int) → bool[source]¶ Helper method to simplify checking if a modifier is held.
Parameters: - modname (str) – Name of the modifier, see
MODNAME2MODIFIER
- modifiers (int) – Bitmask to check in, same as the modifiers argument of the on_key_press etc. handlers
- modname (str) – Name of the modifier, see
-
-
peng3d.keybind.
KeybindHandlerFunc
= typing.Callable[[int, int, bool], typing.Any]¶ Custom type for a keybind handler function.
See
KeybindHandler.add()
for more details regarding the signature.
-
peng3d.keybind.
MODNAME2MODIFIER
¶ Ordered Bidict that maps between user-friendly names and internal constants.
Note that since this is a bidict, you can query the reverse mapping by accessing
MODNAME2MODIFIER.inv
. The non-inverse mapping maps from user-friendly name to internal constant.This mapping is used by the Keybind system to convert the modifier constants to names.
The Mapping is as follows:
Name Pyglet constant Notes ctrl key.MOD_ACCEL
alt key.MOD_ALT
1 shift key.MOD_SHIFT
option key.MOD_OPTION
capslock key.MOD_CAPSLOCK
numlock key.MOD_NUMLOCK
scrollock key.MOD_SCROLLOCK
1: automatically replaced by MOD_CTRL on Darwin/OSX
-
peng3d.keybind.
MOD_RELEASE
= 32768¶ Fake modifier applied when a key is released instead of pressed.
This modifier internally has the value of
1<<15
and should thus be safe from any added modifiers in the future.Note that this modifier is only applied within keybinds, not in regular
on_key_down
andon_key_up
handlers.
-
peng3d.keybind.
OPTIONAL_MODNAMES
= ['capslock', 'numlock', 'scrollock']¶ List of modifiers that are not substantial to a key combo.
If the
controls.keybinds.strict
option is disabled, every key combo is emitted with and without the modifiers in this list. Else, only the combo with these modifiers is emitted.This may cause no more combos to get through if numlock or capslock are activated.