# Symbolic Names

The core protocol does not provide any information to clients other than that actually used to interpret events. This makes it difficult to write a client which presents the keyboard to a user in an easy-to-understand way. Such applications have to examine the vendor string and keycodes to determine the type of keyboard connected to the server and have to examine keysyms and modifier mappings to determine the effects of most modifiers (the Shift , Lock and Control modifiers are defined by the core protocol but no semantics are implied for any other modifiers).

This extension provides such applications with symbolic names for most components of the keyboard extension and a description of the physical layout of the keyboard.

The keycodes name describes the range and meaning of the keycodes returned by the keyboard in question; the keyboard geometry name describes the physical location, size and shape of the various keys on the keyboard. As an example to distinguish between these two names, consider function keys on PC-compatible keyboards. Function keys are sometimes above the main keyboard and sometimes to the left of the main keyboard, but the same keycode is used for the key that is logically F1 regardless of physical position. Thus, all PC-compatible keyboards might share a keycodes name but different geometry names.

The keycodes name is intended to be a very general description of the keycodes returned by a keyboard; A single keycodes name might cover keyboards with differing numbers of keys provided that the keys that all keys have the same semantics when present. For example, 101 and 102 key PC keyboards might use the same name. Applications can use the keyboard geometry to determine which subset of the named keyboard type is in use.

The symbols name identifies the symbols bound to the keys. The symbols name is a human or application-readable description of the intended locale or usage of the keyboard with these symbols. The physical symbols name describes the symbols actually engraved on the keyboard, which might be different than the symbols currently being used.

The types name provides some information about the set of key types that can be associated with the keyboard keys. The compat name provides some information about the rules used to bind actions to keys changed using core protocol requests.

The compat , types , keycodes , symbols and geometry names typically correspond to the keyboard components from which the current keyboard description was assembled. These components are stored individually in the server’s database of keyboard components, described in The Server Database of Keyboard Components, and can be combined to assemble a complete keyboard description.

Each key has a four-byte symbolic name. The key name links keys with similar functions or in similar positions on keyboards that report different scan codes. Key aliases allow the keyboard layout designer to assign multiple names to a single key, to make it easier to refer to keys using either their position or their "function."

For example, consider the common keyboard customizations:

- Set the "key to the left of the letter a" to be a control key.

- Change the "caps lock" key, wherever it might be, to a control key.

If we specify key names by position, the first customization is simple but the second is impossible; if we specify key names by function, the second customization is simple but the first is impossible. Using key aliases, we can specify both function and position for "troublesome" keys, and both customizations are straightforward.

Key aliases can be specified both in the symbolic names component and in the keyboard geometry (see Keyboard Geometry). Both sets of aliases are always valid, but key alias definitions in the keyboard geometry have priority; if both symbolic names and geometry include aliases, applications should consider the definitions from the geometry before considering the definitions from the symbolic names section.

XKB provides symbolic names for each of the four keyboard groups, sixteen virtual modifiers, thirty-two keyboard indicators, and up to MaxRadioGroups (32) radio groups.

XKB allows keyboard layout designers or editors to assign names to each key type and to each of the levels in a key type. For example, the second position on an alphabetic key might be called the "Caps" level while the second position on a numeric keypad key might be called the "Num Lock" level.