# The Server Database of Keyboard Components

The X server maintains a database of keyboard components and common keyboard mappings. This database contains five kinds of components; when combined, these five components provide a complete description of a keyboard and its behavior.

The X Keyboard Extension provides requests to list the contents of this database, to assemble and complete keyboard descriptions by merging the current keyboard description with the contents of this database, or to replace the current keyboard description with a complete keyboard description assembled as described below.

## Component Names

Component and keymap names have the form " class ( member )" where class describes a subset of the available components for a particular type and the optional member identifies a specific component from that subset. For example, the name "atlantis(acme)" might specify the symbols used for the atlantis national keyboard layout by the vendor "acme." Each class has an optional default member — references which specify a class but not a member refer to the default member of the class, if one exists.

The class and member names are both specified using characters from the Latin-1 character set. XKB implementations must accept all alphanumeric characters, minus (‘-’) and underscore (‘_’) in class or member names, and must not accept parentheses, plus, vertical bar, percent sign, asterisk, question mark or white space. The use of other characters is implementation-dependent.

## Partial Components and Combining Multiple Components

Some of the elements in the server database contain describe only a piece of the corresponding keyboard component. These partial components should be combined with other components of the same type to be useful.

For example, a partial symbols map might describe the differences between a common ASCII keyboard and some national layout. Such a partial map is not useful on its own because it does not include those symbols that are the same on both the ASCII and national layouts (such as function keys). On the other hand, this partial map can configure any ASCII keyboard to use a national layout.

Two components can be combined in two ways:

- If the second component overrides the first, any definitions that are present in both components are taken from the second.

- If the second component augments the first, any definitions that are present in both components are taken from the first.

Applications can use a component expression to combine multiple components of some time into a complete description of some aspect of the keyboard. A component expression is a string which lists the components to be combined separated by operators which specify the rules for combining them. A complete description is assembled from the listed components, left to right, as follows:

- If the new elements are being merged with an existing map, the special component name ‘%’ refers to the unmodified value of the map.

- The ‘+’ operator specifies that the next specified component should override the current assembled definition.

- The ‘|’ operator specifies that the next specified component should augment the currently assembled definition.

- If the new elements are being merged with an existing map and the component expression begins with an operator, a leading ‘%’ is implied.

- If any unknown or illegal characters appear anywhere in the string, the entire expression is invalid and is ignored.

For example, the component expression "+de" specifies that the default element of the "de" map should be applied to the current keyboard mapping, overriding any existing definitions.

A slightly more involved example: the expression "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the ASCII keyboard supplied by the "acme" vendor. The new definition begins with the symbols for the default ASCII keyboard for Acme, overrides them with any keys that are defined for the default German keyboard layout and then applies the definitions from the iso9995-3 to any undefined keys or groups of keys (part three of the iso9995 standard defines a common set of bindings for the secondary group, but allows national layouts to override those definitions where necessary).

## Component Hints

Each component has a set of flags that provide some additional hints about that component. XKB provides these hints for clients that present the keyboard database to users and specifies their interpretation only loosely. Clients can use these hints to constrain the list of components or to control the way that components are presented to the user.

Hints for a component are reported with its name. The least significant byte of the hints field has the same meaning for all five types of keyboard components, and can contain any combination of the following values:

Flag | Meaning
--- | ---
LC_Hidden | Indicates a component that should not normally be presented to the user.
LC_Default | Indicates a component that is the default member of its class.
LC_Partial | Indicates a partial component.

The interpretation of the most significant byte of the hints field is dependent on the type of component. The hints defined for each kind of component are listed in the section below that describes that kind of component.

## Keyboard Components

The five types of components stored in the server database of keyboard components correspond to the symbols , geometry , keycodes , compat and types symbolic names associated with a keyboard.

## The Keycodes Component

The keycodes component of a keyboard mapping specifies the range and interpretation of the raw keycodes reported by the device. It sets the keycodes symbolic name, the minimum and maximum legal keycodes for the keyboard, and the symbolic name for each key. The keycodes component might also contain aliases for some keys, symbolic names for some indicators, and a description of which indicators are physically present.

The special keycodes component named "computed" indicates that XKB should assign unused keycodes to any unknown keys referenced by name by any of the other components. The computed keycodes component is useful primarily when browsing keymaps because it makes it possible to use the symbols and geometry components without having to find a set of keycodes that includes keycode definitions for all of the keys listed in the two components.

XKB defines no hints that are specific to the keycodes component.

### The Types Component

The types component of a keyboard mapping specifies the key types that can be associated with the various keyboard keys. It affects the types symbolic name and the list of types associated with the keyboard (see Key Types). The types component of a keyboard mapping can also optionally contain real modifier bindings and symbolic names for one or more virtual modifiers.

The special types component named "canonical" always contains the types and definitions listed in Canonical Key Types of this document.

XKB defines no hints that are specific to the types component.

### The Compatibility Map Component

The compatibility map component of a keyboard mapping primarily specifies the rules used to assign actions to keysyms. It affects the compat symbolic name, the symbol compatibility map and the group compatibility map. The compat component might also specify maps for some indicators and the real modifier bindings and symbolic names of some virtual modifiers.

XKB defines no hints that are specific to the compatibility map component.

### The Symbols Component

The symbols component of a keyboard mapping specifies primarily the symbols bound to each keyboard key. It affects the symbols symbolic name, a key symbol mapping for each key, they keyboard modifier mapping, and the symbolic names for the keyboard symbol groups. Optionally, the symbols component can contain explicit actions and behaviors for some keys, or the real modifier bindings and symbolic names for some virtual modifiers.

XKB defines the following additional hints for the symbols component:

Flag | Meaning
--- | ---
LC_AlphanumericKeys | Indicates a symbol component that contains bindings primarily for an alphanumeric section of the keyboard.
LC_ModifierKeys | Indicates a symbol component that contains bindings primarily for modifier keys.
LC_KeypadKeys | Indicates a symbol component that contains bindings primarily for numeric keypad keys.
LC_FunctionKeys | Indicates a symbol component that contains bindings primarily for function keys.
LC_AlternateGroup | Indicates a symbol component that contains bindings for an alternate keyboard group.

These hints only apply to partial symbols components; full symbols components are assumed to specify all of the pieces listed above.

The alphanumeric, modifier, keypad or function keys hints should describe the primary intent of the component designer and should not simply an exhaustive list of the kinds of keys that are affected. For example, national keyboard layouts affect primarily alphanumeric keys, but many affect a few modifier keys too; such mappings should set only LC_AlphanumericKeys hint. In general, symbol components should set only one of those four flags (though LC_AlternateGroup may be combined with any of the other flags).

### The Geometry Component

The geometry component of a keyboard mapping specifies primarily the geometry of the keyboard. It contains the geometry symbolic name and the keyboard geometry description. The geometry component might also contain aliases for some keys or symbolic names for some indicators and might affect the set of indicators that are physically present. Key aliases defined in the geometry component of a keyboard mapping override those defined in the keycodes component.

XKB defines no hints that are specific to the geometry component.

## Complete Keymaps

The X server also reports a set of fully specified keymaps. The keymaps specified in this list are usually assembled from the components stored in the rest of the database and typically represent the most commonly used keymaps for a particular system.

XKB defines no hints that are specific to complete keymaps.