The Window.on_key_press and Window.on_key_release events are fired when any key on the keyboard is pressed or released, respectively. These events are not affected by "key repeat" -- once a key is pressed there are no more events for that key until it is released.
Both events are parameterised by the same arguments:
def on_key_press(symbol, modifiers): pass def on_key_release(symbol, modifiers): pass
The symbol argument is an integer that represents a "virtual" key code. It does //not// correspond to any particular numbering scheme; in particular the symbol is //not// an ASCII character code.
pyglet has key symbols that are hardware and platform independent for many types of keyboard. These are defined in pyglet.window.key as constants. For example, the Latin-1 alphabet is simply the letter itself:
key.A
key.B
key.C
...
The numeric keys have an underscore to make them valid identifiers:
key._1
key._2
key._3
...
Various control and directional keys are identified by name:
key.ENTER or key.RETURN key.SPACE key.BACKSPACE key.DELETE key.MINUS key.EQUAL key.BACKSLASH key.LEFT key.RIGHT key.UP key.DOWN key.HOME key.END key.PAGEUP key.PAGEDOWN key.F1 key.F2 ...
Keys on the number pad have separate symbols:
key.NUM_1
key.NUM_2
...
key.NUM_EQUAL
key.NUM_DIVIDE
key.NUM_MULTIPLY
key.NUM_MINUS
key.NUM_PLUS
key.NUM_DECIMAL
key.NUM_ENTER
Some modifier keys have separate symbols for their left and right sides (however they cannot all be distinguished on all platforms):
key.LCTRL
key.RCTRL
key.LSHIFT
key.RSHIFT
...
Key symbols are independent of any modifiers being held down. For example, lower-case and upper-case letters both generate the A symbol. This is also true of the number keypad.
The modifiers that are held down when the event is generated are combined in a bitwise fashion and provided in the modifiers parameter. The modifier constants defined in pyglet.window.key are:
MOD_SHIFT
MOD_CTRL
MOD_ALT Not available on Mac OS X
MOD_WINDOWS Available on Windows only
MOD_COMMAND Available on Mac OS X only
MOD_OPTION Available on Mac OS X only
MOD_CAPSLOCK
MOD_NUMLOCK
MOD_SCROLLLOCK
MOD_ACCEL Equivalent to MOD_CTRL, or MOD_COMMAND on Mac OS X.
For example, to test if the shift key is held down:
if modifiers & MOD_SHIFT: pass
Unlike the corresponding key symbols, it is not possible to determine whether the left or right modifier is held down (though you could emulate this behaviour by keeping track of the key states yourself).
pyglet does not define key symbols for every keyboard ever made. For example, non-Latin languages will have many keys not recognised by pyglet (however, their Unicode representation will still be valid, see Text and motion events). Even English keyboards often have additional so-called "OEM" keys added by the manufacturer, which might be labelled "Media", "Volume" or "Shopping", for example.
In these cases pyglet will create a key symbol at runtime based on the hardware scancode of the key. This is guaranteed to be unique for that model of keyboard, but may not be consistent across other keyboards with the same labelled key.
The best way to use these keys is to record what the user presses after a prompt, and then check for that same key symbol. Many commercial games have similar functionality in allowing players to set up their own key bindings.
pyglet provides the convenience class KeyStateHandler for storing the current keyboard state. This can be pushed onto the event handler stack of any window and subsequently queried as a dict:
from pyglet.window import key window = pyglet.window.Window() keys = key.KeyStateHandler() window.push_handlers(keys) # Check if the spacebar is currently pressed: if keys[key.SPACE]: pass