pyglet decouples the keys that the user presses from the Unicode text that is input. There are several benefits to this:
The actual source of input (i.e., which keys were pressed, or what input method was used) should be considered outside of the scope of the application -- the operating system provides the necessary services.
When text is entered into a window, the on_text event is fired:
def on_text(text): pass
The only parameter provided is a Unicode string. For keyboard input this will usually be one character long, however more complex input methods such as an input palette may provide an entire word or phrase at once.
You should always use the on_text event when you need to determine a string from a sequence of keystrokes. Conversely, you never use on_text when you require keys to be pressed (for example, to control the movement of the player in a game).
In addition to entering text, users press keys on the keyboard to navigate around text widgets according to well-ingrained conventions. For example, pressing the left arrow key moves the cursor one character to the left.
While you might be tempted to use the on_key_press event to capture these events, there are a couple of problems:
pyglet windows provide the on_text_motion event, which takes care of these problems by abstracting away the key presses and providing your application only with the intended cursor motion:
def on_text_motion(motion): pass
motion is an integer which is a constant defined in pyglet.window.key. The following table shows the defined text motions and their keyboard mapping on each operating system.
Constant Behaviour Windows/Linux Mac OS X MOTION_UP Move the cursor up Up Up MOTION_DOWN Move the cursor down Down Down MOTION_LEFT Move the cursor left Left Left MOTION_RIGHT Move the cursor right Right Right MOTION_PREVIOUS_WORD Move the cursor to the previuos word Ctrl + Left Option + Left MOTION_NEXT_WORD Move the cursor to the next word Ctrl + Right Option + Right MOTION_BEGINNING_OF_LINE Move the cursor to the beginning of the current line Home Command + Left MOTION_END_OF_LINE Move the cursor to the end of the current line End Command + Right MOTION_PREVIOUS_PAGE Move to the previous page Page Up Page Up MOTION_NEXT_PAGE Move to the next page Page Down Page Down MOTION_BEGINNING_OF_FILE Move to the beginning of the document Ctrl + Home Home MOTION_END_OF_FILE Move to the end of the document Ctrl + End End MOTION_BACKSPACE Delete the previous character Backspace Backspace MOTION_DELETE Delete the next character, or the current character Delete Delete