peng3d.keybind - Dynamic Keybinding System

class peng3d.keybind.KeybindHandler(peng: peng3d.Peng)

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 if controls.keybinds.strict is set to False.

add(keybind: str, kbname: str, handler: Callable[[int, int, bool], Any], mod: bool = True) → None

Adds a keybind to the internal registry.

Keybind names should be of the format namespace:category.subcategory.namee.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

Changes a keybind of a specific keybindname.

Parameters:

• kbname (str) – Same as kbname of add()
• combo (str) – New key combination

handle_combo(combo: str, symbol: int, modifiers: int, release: bool = False, mod: bool = True) → None

Handles a key combination and dispatches associated events.

First, all keybind handlers registered via add() will be handled, then the pyglet event on_key_combo with params (combo,symbol,modifiers,release,mod) is sent to the Peng() 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

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

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 and on_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.