X Window System Core Protocol - Mappings

Mappings

In the X Window System, every individual, physical key is associated a number in the range 8–255, called its keycode. A keycode only identifies a key, not a particular character or term (e.g., "Page Up") among the ones that may be printed on the key. Each one of these characters or terms is instead identified by a keysym. While a keycode only depends on the actual key that is pressed, a keysym may depend, for example, on whether the Shift key or another modifier was also pressed.

When a key is pressed or released, the server sends events of type KeyPress or KeyRelease to the appropriate clients. These events contain:

1. the keycode of the pressed key
2. the current state of the modifiers (Shift, Control, etc.) and mouse buttons

The server therefore sends the keycode and the modifier state without attempting to translate them into a specific character. It is a responsibility of the client to do this conversion. For example, a client may receive an event stating that a given key has been pressed while the Shift modifier was down. If this key would normally generate the character "a", the client (and not the server) associates this event to the character "A".

While the translation from keycodes to keysyms is done by the client, the table that represents this association is maintained by the server. Storing this table in a centralized place makes it accessible to all clients. Typical clients only request this mapping and use it for decoding the keycode and modifiers field of a key event into a keysym. However, clients can also change this mapping at will.

A modifier is a key that, when pressed, changes the interpretation of other keys. A common modifier is the Shift key: when the key that normally produces a lowercase "a" is pressed together with Shift, it produces an uppercase "A". Other common modifiers are "Control", "Alt", and "Meta".

The X server works with at most eight modifiers. However, each modifier can be associated with more than one key. This is necessary because many keyboards have duplicated keys for some modifiers. For example, many keyboards have two "Shift" keys (one on the left and one on the right). These two keys produce two different keycodes when pressed, but the X server associates both with the "Shift" modifier.

For each of the eight modifiers, the X server maintains a list of the keycodes that it consider to be that modifier. As an example, if the list of the first modifier (the "Shift" modifier) contains the keycode 0x37, then the key that produces the keycode 0x37 is considered a shift key by the X server.

The lists of modifier mappings is maintained by the X server but can be changed by every client. For example, a client can request the "F1 key" to be added to the list of "Shift" modifiers. From this point on, this key behaves like another shift modifier. However, the keycode corresponding to F1 is still generated when this key is pressed. As a result, F1 operates as it did before (for example, a help window may be opened when it is pressed), but also operates like the shift key (pressing "a" in a text editor while F1 is down adds "A" to the current text).

The X server maintains and uses a modifier mapping for the mouse buttons. However, the buttons can only be permuted. This is mostly useful for exchanging the leftmost and rightmost button for left-handed users.

The xmodmap program shows and changes the key, modifier, and mouse button mappings.