X keyboard extension

Original author(s)	X.Org Foundation
Stable release	1.0 / 1996; 28 years ago (1996)
Website	www.x.org/wiki/XKB/

In human–computer interfaces, the X keyboard extension or XKB is a part of the X Window System that extends the ability to control the keyboard over what is offered by the X Window System core protocol, and allows to use multiple keyboard layouts.

Its main features are:

• enhanced support for modifiers (Alt, ⇧ Shift, etc.);
• better treatment of key groups (typically keyboard layouts);
• extended control of keyboard indicators (LEDs) and bells;
• various new keyboard parameters (controls);
• association of actions (of a particular kind) to keys.

XKB is composed of two parts: a server extension and a client library. Modern versions of Xlib contain XKB, which is active by default. Client programs not using this extension can deactivate it before connecting with the server, or can simply work normally as the extension simulates the core protocol by default.

XKB is also used by Wayland compositors and kmscon.

Latched and locked modifiers

XKB allows a modifier to be locked or latched, other than being in its regular state. Normally, a modifier is active exactly when it is pressed, like the Shift. However, a modifier may also be locked, like the Caps Lock modifier. When a modifier is locked, it remains active until it is explicitly deactivated. An intermediate condition between regular and locked is the latched state: When a modifier is latched, it remains active, but only until the next non-modifier key is pressed.

XKB allows a client application to explicitly latch or lock a modifier. Moreover, an application can bind a key press or release to a modifier state change. This way, a modifier may automatically become latched or locked whenever a key is pressed or released.

Key groups

XKB allows for the keyboard to switch between any of four different character groups. This is usually done for making a keyboard behave like a keyboard of a different language. In this context, the set of characters that is generated by the keyboard is called a group, and a keyboard can switch to a different group at any time.

XKB defines some group selectors (which are simply called groups in the specification). As with modifiers, a group selector can be associated with a key, but can also be latched or locked.

Controls

The behavior of the keyboard depends on a number of parameters that can be changed by the clients. These parameters are called controls. For example, the SlowKey control can be used to ignore short keypresses. Another control is the MouseKeys, which makes some keypresses to simulate mouse movements. The control only indicates whether this simulation is active or not; which keys produce the movement is not considered a part of the control, but is specified by attaching actions to these keys.

The above two controls are boolean: they are either active or not. The PerKeyRepeat is a control that is not boolean. Namely, it is a mask that says which keys are in autorepeat mode. According to the specification, non-boolean controls are "always active": that means that they always depends on a set of parameters (in this case, the mask), but that there is no single bit that can be used to deactivate the effects of the control completely.

Other than being boolean or non-boolean, controls also classifies as affecting the behavior of the server and affecting the behavior of the client library. The two above are server controls. Client library controls affect the translation of a keycode or a sequence of keycodes into a string (XLookupString) and event delivery.

Actions

XKB allows for associating actions with key presses, which moves some of the burden of input event processing from client applications to the X server. However, the actions that can be associated with keys are limited to the following:

1. Change the state of a modifier, making it active, inactive, latched or locked
2. Change the state of the group selectors (same as modifiers)
3. Simulate a mouse event (movement or button activity)
4. Change the active screen (this kind of action is optional, that is, not necessarily supported by the server)
5. Change the state of boolean controls
6. Generate a message event (that is, a packet that is sent to the client)
7. Generate a different keycode

Moreover, there are some actions related to devices that are available if the server supports the X Input extension.

Compatibility problems

The X keyboard extension is incompatible with core keyboard handling and as a result several modifier keys are not working or require workarounds inside emulated environments such as VNC or Xephyr.

Other

XKB allows better handling of the keyboard indicators (LEDs). In particular, XKB provides symbolic names for indicators, which allows binding indicators to keyboard activity and checking which indicators are actually present on the keyboard.

XKB also improves upon the core protocol's handling of bells; the core protocol only supports one bell, and the only action a client can perform is to ring the bell. XKB supports multiple named bells and allows a client to deactivate some of them and to be informed when a bell is rung.

XKB allows a client to query the physical shape of the keyboard, including the shapes of individual keys. In particular, keys are arranged into sections, possibly rotated (as an example, the numeric keypad is typically considered a section). Within a section, keys are arranged into rows. Keys and sections have a geometry, which comprise the approximate outline of the key, its bounding box, and the precise form. Other than keys, the geometry also includes doodads, which are elements on the keyboard that are not keys. The overall shape of the keyboard is a doodad. Information provided about doodads includes their color and any text printed on them (including the font used).