libxkbcommon 1.10.0
Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
This document describes the XKB_KEYMAP_FORMAT_TEXT_V1 keymap format, as implemented by libxkbcommon.
Code that identifies a physical key on a keyboard.
See xkb_keycodes for further details.
A keysym (short for “key symbol”) is a numeric encoding of a symbol on the cap of a key.
Some keysyms have a canonical name for convenience. The complete list of canonical names is defined in xkbcommon/xkbcommon-keysyms.h.
Common types of keysyms are:
A dead key: e.g. dead_grave and dead_diaeresis, corresponding respectively to the grave accent and the diaeresis diacritics.
A dead key is a special kind of key that does not generate a character by itself, but modifies the character generated by the key struck(s) immediately after.
A modifier key is a key that modifies the effect of other keys: e.g. Shift, Control, Caps Lock, etc.
The state of a modifier key (active/inactive) is encoded as a modifier index (or modifier bit or simply modifier) and has an associated unique name.
For historical reasons, modifiers are divided in two categories:
They are the 8 predefined (AKA core, X11) modifiers (see usual modifiers hereinafter).
Real modifiers ensure backward compatibility: indeed they are the actual bits used to compute the levels and are communicated via the API of xkbcommon.
Some are generic modifiers (Mod[1-5]) that do not have a conventional interpretation and are the motivation of the introduction of virtual modifiers.
Each modifier defines a mapping to one or multiple real modifier. Real modifiers map to themselves.
The following table lists the usual modifiers present in the standard keyboard configuration. Note that this is provided for information only, as it may change depending on the user configuration.
Modifier | Type | Usual mapping | Comment |
---|---|---|---|
Shift | Real | Shift (fixed) | The usual Shift |
Lock | Real | Lock (fixed) | The usual Caps Lock |
Control | Real | Control (fixed) | The usual Control |
Mod1 | Real | Mod1 (fixed) | Not conventional |
Mod2 | Real | Mod2 (fixed) | Not conventional |
Mod3 | Real | Mod3 (fixed) | Not conventional |
Mod4 | Real | Mod4 (fixed) | Not conventional |
Mod5 | Real | Mod5 (fixed) | Not conventional |
Alt | Virtual | Mod1 | The usual Alt |
Meta | Virtual | Mod1 | The legacy Meta key |
NumLock | Virtual | Mod2 | The usual NumLock |
Super | Virtual | Mod4 | The usual Super/GUI |
LevelThree | Virtual | Mod5 | ISO level 3, aka AltGr |
LevelFive | Virtual | Mod3 | ISO level 5 |
A modifier key can report its state in one of the following 3 ways:
See modifiers declaration and binding for further details.
A key may produce different results depending of the active modifiers: e.g. for a Latin script, pressing the key A produces “a” and holding Shift while pressing A produces “A”.
This various results are organized in an ordered list; the index of each entry is called a shift level or simply level. By convention the lowest level is the result when no modifier is active. Example for the key A on a latin script keyboard:
Level | Description | Keysym | Active key modifiers |
---|---|---|---|
1 | Lower case letters | a | None |
2 | Upper case letters. | A | Shift |
3 | Alternative lower case letters | ae | AltGr |
4 | Alternative upper case letters | AE | Shift + AltGr |
A key shift level is the logical state of a key corresponding to the current shift level it used.
Key shift levels are derived from the modifiers states, but not necessarily in the same way for all keys. For example, for Latin script the Caps Lock modifier selects the level 2 for alphabetic keys such as A but has no effect on a numeric key.
There are groups of keys with the same characteristics: letters, punctuation, numeric keypad, etc. The meaning of their levels is identical and thus can be shared: this generalization is called a key type (see hereinafter).
A key type defines the levels available for a key and how to derive the active level from the modifiers states. Examples:
See xkb_types for further details.
A mapping of keycodes to symbols, actions and key types.
A user who deals with multiple languages may need two or more different layouts: e.g. a layout for Arabic and another one for English. In this context, layouts are called groups in XKB, as defined in the standard ISO/IEC 9995.
Layouts are ordered and identified by their index. Example:
In XKB world, a key action defines the effect a key has on the state of the keyboard or the state of the display server. Examples:
See the section “Key actions” for further details.
A keyboard indicator is a mean to report a specific aspect of the keyboard state.
A customizable derived state of the keyboard. Its changes creates events that can be monitored.
There are two categories:
Real indicators are those associated to a physical indicator. For example, the “Caps Lock” logical modifier controls the corresponding physical LED.
Because indicators are customizable, if one misses a “Num Lock” LED, one could define instead the “Caps Lock” indicator to activate its LED when the “Num Lock” modifier is active.
Note that the meanings of real and virtual is slightly different than the one used for modifier.
See: xkb_keycodes
to define indicators and xkb_compat
to define their effects.
The complete definition of the mapping of raw keycodes to symbols and actions. It fully defines the behavior of a keyboard.
Depending of the context, a keymap may refer to:
See Keymap components and xkb_keymap for further details.
The XKB text format uses a syntax similar to the C programming language. Note that the similarity with C stops here: the XKB text format is only a configuration format and is not intended for programming.
The XKB text format is used to configure a keyboard keymap, which is introduced in “XKB the keyboard keymap configuration”. It has the following two main use cases, illustrated in the diagram hereinafter:
Server: Load a keymap from the keymap configuration database, then handle input events by updating the keyboard state. The keymap is assembled from an RMLVO configuration and its corresponding KcCGST components files.
Client: Load the active keymap from the server, then handle update events sent by the server. The complete keymap is directly available in a self-contained file.
There are two kinds of files for the XKB text format:
A file with the complete description of the keymap object. It is the kind of file that the server sends to the client (see the diagram above). Its top-level structure consists of the xkb_keymap block.
Keymap components are described with keymap sections. They are grouped in keymap component files to form a keyboard configuration database.
Component | Section in a keymap | Folder in a keymap configuration database | Description |
---|---|---|---|
Key codes | xkb_keycodes | keycodes | A translation of the raw key codes from the keyboard into symbolic names. |
Compatibility | xkb_compat | compat | A specification of what internal actions modifiers and various special-purpose keys produce. |
(Geometry) | xkb_geometry | geometry | A description of the physical layout of a keyboard.
|
Key symbols | xkb_symbols | symbols | A translation of symbolic key codes into actual key symbols (keysyms). |
Key types | xkb_types | types | Types describe how a pressed key is affected by active modifiers such as Shift, Control, Alt, etc. |
Comments are introduced following either // or # until the end of the line.
A string is surrounded by double quotes: “"
”. The following escape sequences are supported:
Escape sequence | Meaning |
---|---|
\\ | Backslash “\” |
\" | Double quote “"” |
\b | Backspace |
\e | Escape |
\f | Form feed |
\n | Line feed (newline) |
\r | Carriage return |
\t | Horizontal tabulation |
\v | Vertical tabulation |
\ + octal number | Corresponding ASCII character: \1 → SOH, \42 → ". Up to 4 octal digits 0‥7 are parsed. The result must fit into a byte. |
\u{ + hexadecimal number + } | \u{NNNN} produce the corresponding Unicode code point U+NNNN, encoded in UTF-8. Supported code points are in the range U+0001‥U+10FFFF. |
\"
and \u{NNNN} escape sequences.A number can be written in three forms:
Keysyms may be written in multiple ways:
Keysym names are defined in xkbcommon/xkbcommon-keysyms.h; remove the XKB_KEY_ prefix to get the name.
Example: the keysym 0xffbe = XKB_KEY_F1 has the name F1.
The Unicode syntax Unnnn denotes a keysym whose corresponding character is the Unicode code point U+nnnn, where nnnn is an hexadecimal number in the range 0x100 .. 0x10ffff. The resulting keysym value is 0x01000000 + nnnn.
Example: U1F3BA has value 0x0101F3BA and corresponds to the code point U+1F3BA: ‘🎺’ (TRUMPET).
A keysym or list of keysyms can be written as a string literal, with the following semantics:
Otherwise the string expands to a list { ... } with each Unicode code point converted via xkb_utf32_to_keysym.
Examples:
Keysym string | Keysym name | Keysym value |
---|
""
NoSymbol
0x0000
"a"
a
0x0061
"ü"
udiaeresis
0x00dc
"🎺"
U1F3BA
0x0101F3BA
"g̃"
{g, combining_tilde}
{0x0101F3BA, 0x01000303}
A keysym can be written directly with its numeric value: e.g. 0x61 is a.
The following table presents the keywords used in the format. They are case-sensitive.
Keyword | Use |
---|---|
action | Action of an interpret statement |
alias | Keycode alias |
alphanumeric_keys | Section flag |
alternate_group | Section flag |
alternate | Merge mode qualifier for include statements |
augment | Merge mode qualifier for include statements |
default | Section flag |
function_keys | Section flag |
group | TODO |
hidden | Section flag |
include | Include statement |
indicator | Indicator statement in either the keycode section or the compatibility section |
interpret | Interpret statement |
key | Key statement |
keypad_keys | Section flag |
keys | Legacy geometry element |
logo | Legacy geometry element |
mod_map | Alias of modifier_map |
modifier_keys | Section flag |
modmap | Alias of modifier_map |
modifier_map | Real modifier bindings |
outline | Legacy geometry element |
overlay | Legacy geometry element |
override | Merge mode qualifier for include statements |
partial | Section flag |
replace | Merge mode qualifier for include statements |
row | Legacy geometry element |
section | Legacy geometry element |
shape | Legacy geometry element |
solid | Legacy geometry element |
text | Legacy geometry element |
type | Key type statement |
virtual_modifiers | Virtual modifiers mappings |
virtual | Flag for the indicator statement |
xkb_compat_map | Alias of xkb_compatibility_map |
xkb_compat | Alias of xkb_compatibility_map |
xkb_compatibility_map | Declare a compatibility section |
xkb_compatibility | Alias of xkb_compatibility_map |
xkb_geometry | Declare a geometry section |
xkb_keycodes | Declare a keycodes section |
xkb_keymap | Declare a keymap block |
xkb_layout | Declare a legacy layout compound section |
xkb_semantics | Declare a legacy semantics compound section |
xkb_symbols | Declare a symbols section |
xkb_types | Declare a key types section |
There are many built-in settings; they are explained in the following relevant sections.
These settings are case-insensitive, e.g. the following strings denote the same key word: SETMODS, SetMods, setMods and setmods.
Each statement has a merge mode property that defines how to handle conflicts with previous statements. This property can be set explicitly by prefixing the statement with one of the merge modes presented hereinafter.
If two declarations conflict, update the properties which are explicitly defined in the new declaration, only if they were implicit in the old declaration.
If two declarations conflict, update only the properties which are explicitly defined in the new declaration.
If two declarations conflict, ignore the old declaration and use the new one.
Legacy merge mode for keycodes. Its purpose is to allow to assign the same key name to multiple key codes, which is not allowed otherwise. This is unfortunately poorly documented and not used in xkeyboard-config. The xkblib specification implies that this was part of the overlay functionality, which is currently not supported by libxkbcommon.
Statements of the form:
will merge data from another section of the same type, possibly located in another file. Note that the statement does not have a trailing semicolon.
If no section name is provided, the default map is looked up.
The path may be absolute or relative to its corresponding directory in a XKB configuration: e.g. given the configuration directory <XKB>, files of section type xkb_symbols are looked up in <XKB>/symbols.
The include keyword uses the default merge mode. The following keywords can be used instead to use the corresponding explicit merge modes:
Multiple files can be included using the same statement. They are separated using one of the following merge mode prefixes:
The following example illustrates the complete syntax:
The statement is processed as follow:
The current file path is searched sequentially in the [XKB configuration path list]:
Then if no match is found, raise an error; else go to the next step.
Let’s illustrate using the following XKB configuration path list:
The relevant directory structure is:
Then the following file:
is equivalent to:
Given the following files:
symbols/A
symbols/B
the resulting section in A will be:
Given the same file symbols/B of the previous example, the following section:
Input | Output |
---|
A keymap file consists of a single top-level xkb_keymap block, under which are nested the following sections:
xkb_keycodes
xkb_types
xkb_compat
xkb_symbols
Overview of a keymap file:
A section can have various flags applied to it, separated by whitespaces:
partial alphanumeric_keys xkb_symbols "basic" { ... }
The possible flags are:
partial
default
Marks the symbol map as the explicit default map in the file. If no map is marked as a default, the first map in the file is the implicit default. Only one section can be marked as the default in each file.
hidden
Additionally, xkb_symbols may also have the following flags:
alphanumeric_keys
modifier_keys
keypad_keys
function_keys
alternate_group
If no *_keys flags are supplied, then the symbols section is assumed to cover a complete keyboard.
At present, except for default (see: default map), none of the flags affect key processing in libxkbcommon, and only serve as metadata.
This is the simplest section type, and is the first one to be compiled. The purpose of this is mostly to map between the hardware/evdev scancodes and XKB keycodes. Each key is given a name by which it can be referred to later, e.g. in the symbols section.
Statements of the form:
<TLDE> = 49; <AE01> = 10;
The above would let 49 and 10 be valid keycodes in the keymap, and assign them the names TLDE and AE01 respectively. The format <WXYZ> is always used to refer to a key by name.
The naming convention <AE01> is based on the standard ISO/IEC 9995-1. It denotes the position of the key in the keyboard grid. It means: the main alphanumeric section (A), row E and column 01.
The following figure illustrates the grid on a staggered standard US QWERTY keyboard. <AE01> corresponds to the key 1.
In the common case this just maps to the evdev scancodes from /usr/include/linux/input.h, e.g. the following definitions:
#define KEY_GRAVE 41 #define KEY_1 2
correspond to the ones above. Similar definitions appear in the xf86-input-keyboard driver. Note that in all current keymaps there’s a constant offset of 8 (for historical reasons).
Note that contrary to xkbcommon, the X11 protocol supports keycodes only up to 255. Therefore, when interfacing with X11, keymaps and applications using keycodes beyond 255 should expect warnings.
If there’s a conflict, like the same name given to different keycodes, or same keycode given different names, it is resolved according to the merge mode which applies to the definitions.
Statements of the form:
alias <MENU> = <COMP>;
Allows to refer to a previously defined key (here <COMP>) by another name (here <MENU>). Conflicts are handled similarly to keycode statements.
Statements of the form:
indicator 1 = "Caps Lock"; indicator 2 = "Num Lock"; indicator 3 = "Scroll Lock";
Assigns a name to the keyboard LED (AKA indicator) with the given index. The LED may be referred by this name later in the compat section and by the user.
This section is the second to be processed, after xkb_keycodes. However, it is completely independent and could have been the first to be processed (it does not refer to specific keys as specified in the xkb_keycodes section).
This section defines key types, which, given a key and a keyboard state (i.e. modifier state and group), determine the shift level to be used in translating the key to keysyms. These types are assigned to each group in each key, in the xkb_symbols section.
Key types are called this way because, in a way, they really describe the “type” of the key (or more correctly, a specific group of the key). For example, an ordinary keymap will provide a type called KEYPAD, which consists of two levels, with the second level being chosen according to the state of the Num Lock (or Shift) modifiers. Another example is a type called ONE_LEVEL, which is usually assigned to keys such as Escape; these have just one level and are not affected by the modifier state. Yet more common examples are TWO_LEVEL (with Shift choosing the second level), ALPHABETIC (where Caps Lock may also choose the second level), etc.
Key types define a mapping between the modifiers and shift levels. Key types have four parameters:
Key types are used to compute:
The following diagram presents an overview of theses computations:
Statements of the form:
type "FOUR_LEVEL" { ... }
The above would create a new type named FOUR_LEVEL. The body of the definition may include statements of the following forms:
level_name[Level1] = "Base";
Mandatory for each level in the type.
Gives each level in this type a descriptive name. It isn’t used for anything.
Note: A level may be specified as Level[1-8] or just a number (can be more than 8).
modifiers = Shift+Lock+LevelThree;
Mandatory, should be specified only once.
A mask of real and virtual modifiers. These are the only modifiers being considered when matching the modifier state against the type. The other modifiers, whether active or not, are masked out in the calculation.
map[Shift+LevelThree] = Level4;
Should have at least as many mappings as there are levels in the type.
If the active modifiers, masked with the type’s modifiers (as stated above), match (i.e. equal) the modifiers inside the map[] statement, then the level in the right hand side is chosen. For example, in the above, if in the current keyboard state the Shift and LevelThree modifiers are active, while the Lock modifier is not, then the keysym(s) in the 4th level of the group will be returned to the user.
map[Shift+Lock+LevelThree] = Level5; preserve[Shift+Lock+LevelThree] = Lock;
When a key type is used for keysym translation, its modifiers are said to be consumed in this translation. For example, in a simple US keymap, the “G” key is assigned an ordinary ALPHABETIC key type, whose modifiers are Shift and Lock; then for the “G” key, these two modifiers are consumed by the translation. This information is relevant for applications which further process the modifiers, since by then the consumed modifiers have already “done their part” and should be masked out.
However, sometimes even if a modifier had already affected the key translation through the type, it should not be reported as consumed, for various reasons. In this case, a preserve[] statement can be used to augment the map entry. The modifiers inside the square brackets should match one of the map[] statements in the type (if there is no matching map entry, one mapping to Level1 is implicitly added). The right hand side should consists of modifiers from the type’s modifiers; these modifiers are then “preserved” and not reported as consumed.
The following examples compare two basic types with two levels: TWO_LEVEL and ALPHABETIC. They differ on their handling of the Lock modifier. See the next section for an illustration with concrete layouts.
Definition code (source)
Mapping test
Active modifiers | Filtered modifiers | Match? | Shift level |
---|---|---|---|
(none) | (none) | Yes | 1 |
Shift | Shift | Yes | 2 |
Lock | (none) | Yes | 1 |
Shift + Lock | Shift | Yes | 2 |
Definition code (source)
Mapping test
Active modifiers | Filtered modifiers | Match? | Shift level |
---|---|---|---|
(none) | (none) | Yes | 1 |
Shift | Shift | Yes | 2 |
Lock | Lock | Yes | 2 |
Shift + Lock | Shift + Lock | No | 1 |
The following examples compare basic types with four levels: FOUR_LEVEL, FOUR_LEVEL_SEMIALPHABETIC and FOUR_LEVEL_ALPHABETIC. They differ on their handling of the Lock modifier. See the next section for an illustration with concrete layouts.
Definition code (source)
Mapping test
Active modifiers | Filtered modifiers | Match? | Shift level |
---|---|---|---|
(none) | (none) | Yes | 1 |
Shift | Shift | Yes | 2 |
Lock | (none) | Yes | 1 |
Shift+Lock | Shift | Yes | 2 |
LevelThree | LevelThree | Yes | 3 |
LevelThree+Shift | LevelThree+Shift | Yes | 4 |
LevelThree+Lock | LevelThree | Yes | 3 |
LevelThree+Shift+Lock | LevelThree+Shift | Yes | 4 |
Definition code (source)
Mapping test
Active modifiers | Filtered modifiers | Match? | Shift level |
---|---|---|---|
(none) | (none) | Yes | 1 |
Shift | Shift | Yes | 2 |
Lock | Lock | Yes | 2 |
Shift+Lock | Shift+Lock | Yes | 1 |
LevelThree | LevelThree | Yes | 3 |
LevelThree+Shift | LevelThree+Shift | Yes | 4 |
LevelThree+Lock | LevelThree+Lock | Yes | 3 |
LevelThree+Shift+Lock | LevelThree+Shift+Lock | Yes | 4 |
Definition code (source)
Mapping test
Active modifiers | Filtered modifiers | Match? | Shift level |
---|---|---|---|
(none) | (none) | Yes | 1 |
Shift | Shift | Yes | 2 |
Lock | Lock | Yes | 2 |
Shift+Lock | Shift+Lock | Yes | 1 |
LevelThree | LevelThree | Yes | 3 |
LevelThree+Shift | LevelThree+Shift | Yes | 4 |
LevelThree+Lock | LevelThree+Lock | Yes | 4 |
LevelThree+Shift+Lock | LevelThree+Shift+Lock | Yes | 3 |
The following table compares the mappings of various key types for the modifiers Shift, Lock and LevelThree, using the standard layouts us (US English) and es (Spanish).
Key | Layout | Key type | Active modifiers | Level | Keysym | Comment |
---|---|---|---|---|---|---|
AE01 | us | TWO_LEVEL | (none) | 1 | 1 | |
Shift | 2 | exclam | ||||
Lock | 1 | 1 | Lock filtered out | |||
Shift + Lock | 2 | exclam | Lock filtered out | |||
LevelThree | 1 | 1 | LevelThree filtered out | |||
LevelThree + Shift | 2 | exclam | LevelThree filtered out | |||
LevelThree + Lock | 1 | 1 | Modifiers LevelThree and Lock filtered out | |||
LevelThree + Shift + Lock | 2 | exclam | Modifiers LevelThree and Lock filtered out | |||
es | FOUR_LEVEL | (none) | 1 | 1 | ||
Shift | 2 | exclam | ||||
Lock | 1 | 1 | Lock filtered out | |||
Shift + Lock | 2 | exclam | Lock filtered out | |||
LevelThree | 3 | bar | ||||
LevelThree + Shift | 4 | exclamdown | ||||
LevelThree + Lock | 3 | bar | Lock filtered out | |||
LevelThree + Shift + Lock | 4 | exclamdown | Lock filtered out | |||
AD01 | us | ALPHABETIC | (none) | 1 | q | |
Shift | 2 | Q | ||||
Lock | 2 | Q | ||||
Shift + Lock | 1 | q | Lock cancelled by Shift | |||
LevelThree | 1 | q | LevelThree filtered out | |||
LevelThree + Shift | 1 | q | LevelThree filtered out | |||
LevelThree + Lock | 2 | Q | LevelThree filtered out | |||
LevelThree + Shift + Lock | 1 | q | LevelThree filtered out, Lock cancelled by Shift | |||
es | FOUR_LEVEL_SEMIALPHABETIC | (none) | 1 | q | ||
Shift | 2 | Q | ||||
Lock | 2 | Q | ||||
Shift + Lock | 1 | q | Lock cancelled by Shift | |||
LevelThree | 3 | at | ||||
LevelThree + Shift | 4 | Greek_OMEGA | ||||
LevelThree + Lock | 3 | at | Lock does not affect LevelThree combos | |||
LevelThree + Shift + Lock | 4 | Greek_OMEGA | Lock does not affect LevelThree combos | |||
AD05 | us | ALPHABETIC | (none) | 1 | t | |
Shift | 2 | T | ||||
Lock | 2 | T | ||||
Shift + Lock | 1 | t | Lock cancelled by Shift | |||
LevelThree | 1 | t | LevelThree filtered out | |||
LevelThree + Shift | 1 | t | LevelThree filtered out | |||
LevelThree + Lock | 2 | T | LevelThree filtered out | |||
LevelThree + Shift + Lock | 1 | t | LevelThree filtered out, Lock cancelled by Shift | |||
es | FOUR_LEVEL_ALPHABETIC | (none) | 1 | t | ||
Shift | 2 | T | ||||
Lock | 2 | T | ||||
Shift + Lock | 1 | t | Lock cancelled by Shift | |||
LevelThree | 3 | tslash | ||||
LevelThree + Shift | 4 | Tslash | ||||
LevelThree + Lock | 4 | Tslash | ||||
LevelThree + Shift + Lock | 3 | tslash | Lock cancelled by Shift |
This section is the third to be processed, after xkb_keycodes and xkb_types.
Statements of the form:
interpret Num_Lock+Any { ... } interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
The xkb_symbols
section (see below) allows the keymap author to perform, among other things, the following things for each key:
However, doing this for each key (or level) is tedious and inflexible. Interpret’s are a mechanism to apply these settings to a bunch of keys/levels at once.
Each interpret specifies a condition by which it attaches to certain levels. The condition consists of two parts:
A modifier predicate. The predicate consists of:
A mask of real modifiers: a +-separated list of modifiers or the special value all, which denotes all the modifiers.
The modifiers are matched against the key’s modifier map (modmap).
Leaving out the predicate is equivalent to using AnyOfOrNone(all). Leaving out just the matching condition is equivalent to using Exactly.
An interpret may also include useModMapMods = level1; – see below.
If a level fulfils the conditions of several interprets, only the most specific one is used:
As described above, once an interpret “attaches” to a level, it can bind an action to that level, add one virtual modifier to the key’s vmodmap, or set the key’s repeat setting. You should note the following:
The body of the statement may include statements of the following forms (all of which are optional):
useModMapMods = level1;
When set to level1, the interpret will only match keysyms which are on the first level of the first group of the keys. This can be useful in conjunction with e.g. a virtualModifier statement, because virtualModifier is an attribute of the key rather than a specific level.
Note: the other possible value is any and is the default value.
See virtual modifier map for further information.
virtualModifier = NumLock;
Add this virtual modifier to the key’s vmodmap. The given virtual modifier must be declared at the top level of the file with a virtual_modifiers statement, e.g.:
virtual_modifiers NumLock;
See virtual modifier map for further information.
repeat = True;
Set whether the key should repeat or not. Must be a boolean value.
action = LockMods(modifiers=NumLock);
Bind this action to the matching levels. See key actions for the list of available key actions.
Since 1.9.0, it is also possible to assign a sequence of actions, mirroring the feature used in the key statement.
action = {SetMods(modifiers=NumLock),SetGroup(group=2)};
Statements of the form:
indicator "Shift Lock" { ... }
This statement specifies the behavior and binding of the LED (AKA indicator) with the given name (“Shift Lock” above). The name should have been declared previously in the xkb_keycodes section (see LED name statement), and given an index there. If it wasn’t, it is created with the next free index.
The body of the statement describes the conditions of the keyboard state which will cause the LED to be lit. It may include the following statements:
modifiers = ScrollLock;
If the given modifiers are in the required state (see below), the LED is lit.
whichModState = Latched+Locked;
Can be any combination of:
This will cause the respective portion of the modifier state (see struct xkb_state) to be matched against the modifiers given in the modifiers statement.
Here’s a simple example:
indicator "Num Lock" { modifiers = NumLock; whichModState = Locked; };
Whenever the NumLock modifier is locked, the Num Lock LED will light up.
groups = All - group1;
If the given groups are in the required state (see below), the LED is lit.
whichGroupState = Effective;
Can be any combination of:
This will cause the respective portion of the group state (see struct xkb_state) to be matched against the groups given in the groups statement.
Note: the above conditions are disjunctive, i.e. if any of them are satisfied the LED is lit.
One may change the default values of the following statements:
This section is the fourth to be processed, after xkb_keycodes, xkb_types and xkb_compat.
Statements of the form:
xkb_symbols "basic" { ... }
Declare a symbols map named basic. Statements inside the curly braces only affect the symbols map.
Statements of the form:
name[Group1] = "US/ASCII"; groupName[1] = "US/ASCII";
Gives the name “US/ASCII” to the first group of symbols. Other groups can be named using a different group index (ex: Group2), and with a different name. A group must be named.
group and groupName mean the same thing, and the Group in Group1 is optional.
Statements of the form:
key <AD01> { ... };
defines the key description of the keycode <AD01> and is the main type of record of the xkb_symbols section. The possible keycodes are defined in the xkb_keycodes section.
A key description consists of:
Each key may have one or more associated groups. Each group can be configured with the following parameters:
These attributes are usually set via the xkb_compat
section, but may be also set directly:
The main part of the key description is the symbols table. It maps shift levels to keysyms, e.g.:
Symbols are named using the symbolic names from the xkbcommon/xkbcommon-keysyms.h file. See the keysym syntax for further information. A group of symbols is enclosed in brackets and separated by commas. Each element of the symbol arrays corresponds to a different shift level. In this example, the symbol (keysym) XKB_KEY_q for level 1 and XKB_KEY_Q for level 2. These levels are configured by the key type, presented in the next section.
As an extension to the XKB legacy format, libxkbcommon supports multiple key symbols and actions per level (the latter since version 1.8.0):
In this example, the keycode <AD08> produces two symbols on level 1 (XKB_KEY_i and XKB_KEY_j) and one symbol (Unicode keysym U0132 for “IJ”) on level 2. <AD08> and <AD01> produce letters that have no precomposed code point in Unicode. Key <AB05> avoids the need of using Compose.
Since 1.9.0, UTF-8-encoded strings may be used to denote a list of keysyms corresponding to the encoded Unicode code points. E.g. the previous example can be also written more intuitively as:
When no actions are explicitly given, they are automatically filled thanks to interpretations from the compat section. In the following example,
key <LCTL> { [ { Control_L, ISO_Group_Shift } ] };
is equivalent to (given standard definitions from xkeyboard-config):
key <LCTL> { symbols[1] = [ { Control_L, ISO_Group_Shift } ], actions[1] = [ { SetMods(modifiers=Control), SetGroup(group=+1) } ] };
When using this example with e.g. two layouts fr,us (respectively Azerty and Qwerty layouts), typing Control + A in the first layout fr will in fact result in Control + Q, because the actions are run sequentially: first set the base modifiers to Control, then switch to the second layout while Control is pressed.
For now, at most one action of each following categories is allowed per level:
Some examples of actions combination:
Each key has a key type set per group. This key type is defined in the xkb_types
section. Its associated shift levels are used to index the symbols table presented in the previous section.
A key type is set using the following syntax:
The name of the key type is enclosed between double quotes.
The key type may be omitted and will default to:
Commented examples for inferred types:
xkb_compat
section.Example: Set the modifier action of the key <LALT> manually.
For further details see key actions.
Each group represents a list of symbols mapped to a keycode:
name[Group1]= "US/ASCII"; name[Group2]= "Russian"; ... key <AD01> { [ q, Q ], [ Cyrillic_shorti, Cyrillic_SHORTI ] };
A long-form syntax can also be used:
key <AD01> { symbols[Group1]= [ q, Q ], symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ] };
Groups can also be omitted, but the brackets must be present. The following statement only defines the Group3 of a mapping:
key <AD01> { [], [], [ q, Q ] };
xkb_compat
section.Example: Set the virtual modifier of the key <LALT> to Alt.
See virtual modifier map for further information.
xkb_compat
section.Example: make the <LALT> key not repeating.
Bind a real modifier to a key, e.g.:
See real modifier map for further information.
One may change the default values of the following statements:
Modifiers are a particularly tricky part of XKB and deserve their own section. For historical reasons they are divided in two categories:
They are the 8 predefined (AKA core, X11) modifiers:
Name | Description |
---|---|
Shift | Used to type upper case letters of bicameral scripts; keyboard shortcuts |
Lock | Used to type upper case letters of [bicameral scripts]: “Caps Lock” |
Control | Used in keyboard shortcuts |
Mod1 | Generic modifier 1 |
Mod2 | Generic modifier 2 |
Mod3 | Generic modifier 3 |
Mod4 | Generic modifier 4 |
Mod5 | Generic modifier 5 |
They are the modifiers defined in the core X11 protocol. They are qualified as “real”, because in the XKB protocol they denote the bits that encode the modifiers state. See Modifiers encoding for further information.
Since they are predefined, they require no explicit declaration and have a fixed encoding.
They are the modifiers that are not predefined. They require an explicit declaration and their encoding is user-defined.
Note that in X11, the maximum of virtual modifiers is 16 (see XkbNumVirtualMods), whereas up to 24 virtual modifiers can be defined in libxkbcommon.
Virtual modifiers must be declared before their first use with the virtual_modifiers statement:
Furthermore, it is possible to set the explicit modifier encoding with the following syntax:
This can be done in the xkb_types, xkb_compat and xkb_symbols sections.
Each key has two modifiers maps:
List the real modifiers associated to the key.
It is used as a compatibility layer for the X11 core protocol and to apply interpretations.
See Setting the real modifier map for further information.
List the virtual modifiers associated to the key.
It is used to set the implicit encoding of virtual modifiers.
See Setting the virtual modifier map for further information.
The real modifier map is set in the xkb_symbols section using the modifier_map statement:
Bind indirectly via a keysym, e.g.:
Indirect bindings require to be resolved to a single direct bindings. Given a keysym, there can be multiple keys that generate it, so the corresponding key is chosen following this order:
There is also a special entry, None, that enable deleting a previous entry:
The virtual modifier map can be set in 2 ways:
Each modifier has an associated 32 bit mask used to encode it in the keyboard state. The keyboard state represents active modifiers with the bitwise OR of the encoding of each active modifiers.
Virtual modifiers require to be encoded by the user, explicitly and/or implicitly, the combination resulting in their effective encoding.
Virtual modifiers can optionally define an initial mapping using the virtual_modifiers statements:
See Modifiers declarations for further information.
Virtual modifiers always compute their implicit encoding, which is defined for a given virtual modifier by the bitwise OR of all the real modifier maps where the virtual modifier is in the virtual modifier map of the corresponding key.
Example:
The effective encoding is the bitwise OR of the explicit modifier encoding and the implicit modifier encoding.
Example:
Encoding | Alt | Super | Hyper |
---|---|---|---|
Explicit | 0 | 0 | 0x400 |
Implicit | Mod1 | Mod4 + Mod5 | Mod3 |
Effecitve | Mod1 | Mod4 + Mod5 | 0x400 + Mod3 |
The following table summarizes the modifiers defined in xkeyboard-config 2.44:
Modifier | Type | Compat files | Associated keysyms |
---|---|---|---|
Shift | Real | compat/basic | Shift_L, Shift_R |
compat/iso9995 | Shift_L, Shift_R, ISO_Level2_Latch | ||
Lock | Real | compat/basic, | Caps_Lock |
compat/caps | |||
Control | Real | compat/basic | Control_L, Control_R |
Alt | Virtual | compat/misc, | Alt_L, Alt_R |
compat/pc | |||
Meta | Virtual | compat/misc | Meta_L, Meta_R |
Super | Virtual | compat/misc | Super_L, Super_R |
Hyper | Virtual | compat/misc | Hyper_L, Hyper_R |
ScrollLock | Virtual | compat/misc | Scroll_Lock |
NumLock | Virtual | compat/basic, | Num_Lock, |
compat/level5 | (ISO_Level5_Lock) | ||
LevelThree | Virtual | compat/iso9995 | ISO_Level3_Shift, ISO_Level3_Latch, ISO_Level3_Lock |
LevelFive | Virtual | compat/level5 | ISO_Level5_Shift, ISO_Level5_Latch, ISO_Level5_Lock |
Kana_Lock | Virtual | compat/japan | Kana_Lock |
Square | Virtual | compat/olpc | KP_Home |
Cross | Virtual | compat/olpc | KP_Next |
Circle | Virtual | compat/olpc | KP_End |
Triangle | Virtual | compat/olpc | KP_Prior |
Both X11 xkbcomp and libxkbcommon currently implement modifiers indices as follow:
Name | Index |
---|---|
Shift | 0 |
Lock | 1 |
Control | 2 |
Mod1 | 3 |
Mod2 | 4 |
Mod3 | 5 |
Mod4 | 6 |
Mod5 | 7 |
We will use the example of the real modifier Shift and the virtual modifier LevelThree in xkeyboard-config.
In order to define and use a modifier, one must:
Define its behavior and keysym binding in the xkb_compat
section:
Define key types that use it in the xkb_types
section:
Bind it to a keycode in the xkb_symbols
section:
Note: Only one key binding to real modifier is required. The corresponding keysym must then be on the first level of the first Group.
Note: One can optionally bind directly a virtual modifier to a key using virtualmodifiers instead of doing it in the xkb_compat section. But the recommended way is to use the xkb_compat section.
The following table provide an overview of the available actions:
Category | Action name | Alias | Description |
---|---|---|---|
Ineffectual action | NoAction | Default action: implicitly do nothing | |
VoidAction | Explicitly do nothing | ||
Modifier action | SetMods | Modifies the depressed modifiers | |
LatchMods | Modifies the latched modifiers | ||
LockMods | Modifies the locked modifiers | ||
Group action | SetGroup | Modifies the base group | |
LatchGroup | Modifies the latched group | ||
LockGroup | Modifies the locked group | ||
Legacy action | MovePointer | MovePtr | Move the mouse pointer |
PointerButton | PtrBtn | Simulate a mouse button press | |
LockPointerButton | LockPtrBtn | Simulate a mouse button press, locked until the action’s key is pressed again. | |
SetPointerDefault | SetPtrDflt | Set the default select button (???) | |
SetControls | Set the standard XKB controls | ||
LockControls | Lock the standard XKB controls | ||
TerminateServer | Terminate | Shut down the X server | |
SwitchScreen | Switch virtual X screen | ||
Private | Raw encoding of an action | ||
Unsupported legacy action | RedirectKey | Redirect | Emulate pressing a key with a different key code |
ISOLock | Convert ordinary modifier key actions into lock actions while this action is active | ||
DeviceButton | DevBtn | Emulate an event from an arbitrary input device such as a joystick | |
LockDeviceButton | LockDevBtn | Emulate an event from an arbitrary input device such as a joystick | |
DeviceValuator | DevVal | TODO | |
MessageAction | Message | Generate an arbitrary special-purpose XKB event |
Common syntax:
Default action: implicitly do nothing. Does not override previous actions and is dropped.
No parameters.
Explicitly do nothing. Does override previous actions and is not dropped.
No parameters.
There are 3 modifiers actions:
Modifies the depressed modifiers.
Name | Aliases | Data type | Default value | Description |
---|
modifiers
mods
Modifier mask
none (0)
The list of modifiers to modify, separated by +, or the special value modMapMods. The latter means the parameter value has to be read from the vmodmap attribute of the key.
clearLocks
boolean
false
See its use hereinafter
LatchMods Modifies the latched modifiers
Name | Aliases | Data type | Default value | Description |
---|
modifiers
mods
Modifier mask
none (0)
see SetMods.
clearLocks
boolean
false
See its use hereinafter
latchToLock
boolean
false
See its use hereinafter
LockMods Modifies the locked modifiers.
Name | Aliases | Data type | Default value | Description |
---|
modifiers
mods
Modifier mask
none (0)
see SetMods
affect
enumeration:
both
These actions perform different tasks on key press and on key release:
Action | On key press | On key release |
---|
clearLocks=yes
and no other key were operated simultaneously with this key, then the modifiers will be removed as well from the locked modifiers. clearLocks=yes
and no other key has been pressed since this key press, then the modifiers will be removed as well from the locked modifiers. latchToLock=yes
then the modifiers are added to the locked modifiers. There are 3 group actions:
group
Group index:
0
Target group or group delta
clearLocks
boolean
false
See its use hereinafter
LatchGroup Modifies the latched group.
Name | Data type | Default value | Description |
---|
group
Group index (see SetGroup)
0
Target group or group delta
clearLocks
boolean
false
See its use hereinafter
latchToLock
boolean
false
See its use hereinafter
LockGroup Modifies the locked group.
Name | Data type | Default value | Description |
---|
group
Group index (see SetGroup)
0
Target group or group delta
Action | On key press | On key release |
---|
In either case, the resulting effective keyboard group is brought back into range depending on the value of the GroupsWrap control for the keyboard.
If no keys were operated simultaneously with this key and the clearLocks parameter is set, key release also sets the locked keyboard group to Group1.
Same as SetGroup.
Same as SetGroup.
If no keys were operated simultaneously with the latching group key and the clearLocks parameter was not set or had no effect, key release has the following additional effects:
In either case, the resulting locked and effective group is brought back into range depending on the value of the GroupsWrap control for the keyboard.
Key release has no effect.
xkeyboard-config
for both X11 and Wayland.Move the mouse pointer
Simulate a mouse button press
Simulate a mouse button press, locked until this actiion’s key is pressed again
Set the default select button (???)
controls
ctrls
Mask of the following enumeration:
Plus 2 special values:
0
Standard XKB controls
LockControls Lock the standard XKB controls
Name | Alias | Data type | Default value | Description |
---|
controls
ctrls
Mask (see SetControls)
0
Standard XKB controls
affect
enumeration:
both
TODO
Shut down the X server
No parameters.
Raw encoding of an action. Aimed to support arbitrary action unknown to the XKB compiler.
Name | Data type | Default value | Description |
---|
type
integer
0
Action type, as encoded in the XKB protocol
data
byte array or a string of exactly 7 bytes
"0000000"
Raw byte encoding of the action following the XKB protocol
Examples:
RedirectKey emulates pressing a key with a different key code.
RedirectKey normally redirects to another key on the same device as the key or button which caused the event, else on the core keyboard device.
Name | Aliases | Data type | Default value | Description |
---|
key
keycode, kc
keycode
0
Target keycode to emulate
clearmodifiers
clearmods
modifier mask
none (0)
Modifiers to clear
modifiers
mods
modifier mask
none (0)
Modifiers to add
On key press | On key release |
---|---|
Key press causes a key press event for the key specified by the key parameter instead of for the actual key. The state reported in this event reports of the current effective modifiers changed as follow:
|
Key release causes a key release event for the key specified by the key parameter; the state field for this event consists of the effective modifiers at the time of the release, changed as described on the key press. |
This section aims to describe the physical layout of a keyboard and its main use case is to produce a picture of the keyboard via e.g. the xkbprint program.