# Text and motion events

pyglet decouples the keys that the user presses from the Unicode text that is input. There are several benefits to this:

- The complex task of mapping modifiers and key symbols to Unicode characters is taken care of automatically and correctly.
- Key repeat is applied to keys held down according to the user's operating system preferences.
- Dead keys and compose keys are automatically interpreted to produce diacritic marks or combining characters.
- Keyboard input can be routed via an input palette, for example to input characters from Asian languages.
- Text input can come from other user-defined sources, such as handwriting or voice recognition.

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).

# Motion events

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:

- Key repeat events are not generated for on_key_press, yet users expect that holding down the left arrow key will eventually move the character to the beginning of the line.
- Different operating systems have different conventions for the behaviour of keys. For example, on Windows it is customary for the Home key to move the cursor to the beginning of the line, whereas on Mac OS X the same key moves to the beginning of the document.

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