|
libxkbcommon 1.13.0
Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
This document describes the following keymap formats, as implemented by libxkbcommon:
XKB_KEYMAP_FORMAT_TEXT_V1 The classic XKB text format, as generated by xkbcomp -xkb. See XKB Compatibility for further information.
XKB_KEYMAP_FORMAT_TEXT_V2 Xkbcommon extensions of the classic XKB text format, incompatible with X11. See XKB Compatibility for further information.
Code that identifies a physical key on a keyboard.
36 may represent the return key.RTRN.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 and A for Latin scripts, alpha “α” and ALPHA “Α” for Greek, etc.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.
Shift_L, Control_R, Caps_Lock. See hereinafter.Left, Pause, Escape, F1.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 has an associated encoding. In keymaps compatible with X11, the encoding can be interpreted as a mapping to one or multiple real modifier. Real modifiers map to themselves: they are canonical modifiers. See the “Modifiers encoding” section for further information.
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:
ONE_LEVEL: the key has only one level, i.e. it is not affected by any modifiers. Example: the modifiers themselves.Shift modifier is not active.Shift modifier.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:
1, 123, etc.1.23, etc.0x: 0x123, 0xff, 0xAB, etc. 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:
NoSymbol.xkb_utf32_to_keysym.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.
This syntax is mostly useful in the following use cases:
0 .. 9 have a special treatment because they are interpreted as names, not values. E.g. 1 is the keysym with name 1 and value 0x31.0 .. 9 that are written with 2+ characters: e.g. 01 and 0x1 are both interpreted as the unnamed keysym with value 0x01, not the keysym named 1 and with value 0x31.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 is usually 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. Since 1.11, the paths can also be absolute or use %-expansion:
%% %H $HOME environment variable. %S The main system-installed XKB directory of the corresponding component (usually /usr/share/X11/xkb/<component>).
This enables e.g. to override a system file using User-configuration with the exact same name:
%E /etc/xkb/<component>). %-expansion are supported by libxkbcommon but not by the legacy X11 tools.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:
@important Since xkbcommon 1.9.0 the included files are processed in isolation and are not affected by the parent file (e.g. defaults), except for the virtual modifiers indices.
@important Since xkbcommon 1.9.0 local merge modes are not propagated outside the section scope, i.e. an included file does not leaks its local merge modes to its parent.
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:
/home/<USER>/.config/xkb: user configuration directory (see User-configuration)./usr/share/X11/xkb: system directory.The relevant directory structure is:
/home/<USER>/.config/xkbsymbolsesmy_own_file/usr/share/X11/xkbsymbolsesitThen 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 |
|---|---|
|
xkb_symbols {
key <A> { [a, A, ae, AE] };
augment "B(S2)"
};
|
xkb_symbols {
// Key unchanged
key <A> { [a, A, ae, AE] };
// New key
key <B> { [Greek_beta , Greek_BETA] };
};
|
|
xkb_symbols {
key <A> { [a, A, ae, AE] };
replace "B(S2)"
};
|
xkb_symbols {
// Key replaced
key <A> { Greek_alpha, Greek_ALPHA] };
// New key
key <B> { [Greek_beta , Greek_BETA ] };
};
|
|
xkb_symbols {
key <A> { [a, A, ae, AE] };
// Two files merged together with the merge mode
// augment, then the result is merged this the
// statement above using the override merge mode
include "B(S1)|B(S2)"
};
|
xkb_symbols {
// Key overridden: mix of old + new
key <A> { [Greek_alpha, Greek_ALPHA, ae, AE] };
// New key; "B(2)" had no effect with the
// merge mode augment "|"
key <B> { [b, B] };
};
|
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:
xkb_semantics:must contain a xkb_compat section and can contain a xkb_types section.xkb_layout:must contain xkb_keycodes, xkb_types and xkb_symbols sections and can contain xkb_geometry section.xkb_keymap: must contain xkb_keycodes, xkb_compat, xkb_types and xkb_symbols sections and can contain xkb_geometry section. Since such distinction is purely semantic and would have niche use cases lost to history, these compound sections are treated equally as xkb_keymap in libxkbcommon.partial alphanumeric_keys
xkb_symbols "basic" {
...
}
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 xkb_symbols may also have the following flags:alphanumeric_keys modifier_keys keypad_keys function_keys alternate_group *_keys flags are supplied, then the symbols section is assumed to cover a complete keyboard.default (see: default map), none of the flags affect key processing in libxkbcommon, and only serve as metadata.<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.<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.<AE01> corresponds to the key 1./usr/include/linux/input.h, e.g. the following definitions: #define KEY_GRAVE 41 #define KEY_1 2correspond 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).
255. Therefore, when interfacing with X11, keymaps and applications using keycodes beyond 255 should expect warnings.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.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.
virtual flagxkb_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).xkb_symbols section.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.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.
modifiers = Shift+Lock+LevelThree;Mandatory, should be specified only once.
map[Shift+LevelThree] = Level4;Should have at least as many mappings as there are levels in the type.
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.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.preserve statements may be used to tweak keyboard shortcuts. preserve to tweak Control shortcuts. Note it would require further work in order to support other modifiers. Lock affect only “alphabetic” types. For such types, Lock “cancels” Shift by default, i.e. Shift+Lock has the same result as neither modifier. “semi-alphabetic” types have an asymmetry: their first two levels are alphabetic while the next are not.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 |
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 |
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:SetMods or LockGroup, to the key. Actions, like symbols, are specified for each level of each group in the key separately.vmodmap).Any or the NoSymbol keysym, which always matches successfully.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).
AnyOfOrNone – The modmap must either be empty or include at least one of the specified modifiers.AnyOf – The modmap must include at least one of the specified modifiers.Any – Alias for AnyOf(all).NoneOf – The modmap must not include any of the specified modifiers.AllOf – The modmap must include all of the specified modifiers (but may include others as well).Exactly – The modmap must be exactly the same as the specified modifiers.Leaving out the predicate is equivalent to using AnyOfOrNone(all). Leaving out just the matching condition is equivalent to using Exactly.
useModMapMods = level1; – see below.NoSymbol condition.xkb_symbols, the explicit setting takes precedence over the interpret.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.any and is the default value.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.
action = {SetMods(modifiers=NumLock),SetGroup(group=2)};
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.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:
base, latched, locked, effectiveany (i.e. all of the above)none (i.e. none of the above)compat (legacy value, treated as effective)struct xkb_state) to be matched against the modifiers given in the modifiers statement.indicator "Num Lock" {
modifiers = NumLock;
whichModState = Locked;
};
Whenever the NumLock modifier is locked, the Num Lock LED will light up.groups = All - group1;This is a mask of group indices.
GroupN Group3 is 0x4 = 1 << (3 - 1). First Denotes the first group and always equals to 0x1.
Last Denotes the last group and depends on the keymap setup: e.g. with 3 layouts it is to 0x4 = 1 << (3 - 1).
whichGroupState = Effective;Can be any combination of:
base, latched, locked, effectiveany (i.e. all of the above)none (i.e. none of the above)struct xkb_state) to be matched against the groups given in the groups statement.interpret: use interpret.FIELD = VALUE;indicator: use indicator.FIELD = VALUE;ACTION_NAME.FIELD = VALUE;. E.g. setMods.clearLocks= True;.xkb_symbols "basic" {
...
}
Declare a symbols map named basic. Statements inside the curly braces only affect the symbols map.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.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.Each key may have one or more associated groups. Each group can be configured with the following parameters:
Key behavior enables to alter the key events processing before running the actions filters. Key behavior is independent of keyboard modifier or group state.
Each key has exactly one behavior, described hereinafter.
Key behaviors are used to simulate any of these types of keys.
permanent to indicate an unmodifiable physical, electrical or software driver characteristic of a key. permanent flag indicates a characteristic of the underlying system that libxkbcommon cannot affect, so libxkbcommon treats all permanent behaviors as if they were *default* and ignore the corresponding parameters.A keyboard overlay allows some subset of the keyboard to report alternate keycodes when the corresponding overlay control is enabled.
For example a keyboard overlay can be used to simulate a numeric or editing keypad on keyboard that does not actually have one. This technique is very common on laptop computers and embedded systems with small keyboards, see an example hereinafter.
Numeric keypad hardware overlay example.
The keys with a thick border and a blue background can be overlaid by using the Fn key. When the overlay is enabled, they produce alternative numeric keypad keycodes corresponding to their bottom-right label. E.g.:
<AD07> and labelled U produces the keycode <KP4> (numpad 4),<AD10> and labelled P produces the keycode <KPMU> (numpad multiplication). libxkbcommon supports effectful keyboard overlays since version 1.14.0. The differences between keymap formats is presented in the table hereinafter:
| Feature | XKB_KEYMAP_FORMAT_TEXT_V1 | XKB_KEYMAP_FORMAT_TEXT_V2 |
|---|---|---|
| Number of overlays | 2 | 8 |
| Corresponding keyboard controls | `Overlay1` and `Overlay2` | `Overlay1` to `Overlay8` |
| Overlapping | Disjoint overlays: no overlap is allowed, i.e. each key can be part of at most one overlay. | A key may be assigned to any overlay without restriction, enabling overlapping overlays. There is no limitation on which overlay a given key may belong to, and a key may be assigned to more than one overlay. When multiple overlays are active at the same time and a key belongs to more than one of them, the effective mapping for that key is determined by activation order: the mapping defined by the most recently activated overlay takes precedence over all previously activated ones, regardless of the indices of the overlays involved. @important This behavior differs from classic X11 overlay semantics, where activation order carries no significance. Example of 2 overlapping overlaysExample of overlay overlap Assume xkb_symbols {
key <AD07> {
[u, U],
overlay1=<KP6>, // numpad overlay
overlay2=<INS> // edit overlay
};
};
Given the following activation sequence:
|
locks / locking: boolean
radiogroup: positive integerallownone: boolean
These attributes are usually set via the xkb_compat section, but may be also set directly:
group wrap control
groupsWrap, groupsClamp, groupsRedirectxkb_symbols section only affect a single group. It is fine with a keymap file though.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.NoSymbol are dropped.<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.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:
SetMods, LatchMods, LockMods;SetGroup, LatchGroup, LockGroup.Some examples of actions combination:
SetMods + SetGroup: okSetMods + SetMods: errorSetMods + LockMods: errorSetMods + LockGroup: okNoSymbol and NoAction() are dropped in order to normalize the levels: NoSymbol and NoAction() are dropped in groups: {} and {a}. {} is equivalent to the corresponding NoSymbol or NoAction().setxkbmap, xkbcomp, etc.).xkb_types section. Its associated shift levels are used to index the symbols table presented in the previous section.key.type global defaults, if set.ONE_LEVELKEYPAD else `TWO_LEVEL`.NoSymbol):FOUR_LEVEL_KEYPAD;xkb_compat section.<LALT> manually. NoAction() are dropped.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_symbols section only affect a single group. It is fine with a keymap file though.xkb_compat section.<LALT> to Alt. xkb_compat section.<LALT> key not repeating. key: use key.FIELD = VALUE;. E.g. key.type = "ALPHABETIC";.action: use ACTION_NAME.FIELD = VALUE;. E.g. setMods.clearLocks= True;.They are the 8 predefined (AKA core, X11) modifiers:
| Name | Index/Bit | Mask | Description |
|---|---|---|---|
Shift | 0 | 0x01 | Used to type upper case letters of bicameral scripts; keyboard shortcuts |
Lock | 1 | 0x02 | Used to type upper case letters of [bicameral scripts]: “Caps Lock” |
Control | 2 | 0x04 | Used in keyboard shortcuts |
Mod1 | 3 | 0x08 | Generic modifier 1 |
Mod2 | 4 | 0x10 | Generic modifier 2 |
Mod3 | 5 | 0x20 | Generic modifier 3 |
Mod4 | 6 | 0x40 | Generic modifier 4 |
Mod5 | 7 | 0x80 | 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, for a total of 32 modifiers (real + virtual).
virtual_modifiers statement:none, an alias for 0: 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.
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:
None, that enable deleting a previous entry:None must use the exact same target (keycode or keysym) in order to delete the corresponding previous entry: virtualModifiers key property: 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:
Virtual modifiers can optionally define an initial mapping using the `virtual_modifiers` statements:
See Modifiers declarations for further information.
The effective encoding is the bitwise OR of the explicit modifier encoding and the implicit modifier encoding.
XKB_KEYMAP_FORMAT_TEXT_V2, virtual modifiers that were not mapped either implicitly using the virtualModifier/modifier_map feature hereinabove or *explicitly*, then they are mapped to their *canonical* mapping.Example:
| Modifier | Index | Encoding | ||||
|---|---|---|---|---|---|---|
| Canonical | Explicit | Implicit | Effective | |||
| (xkbcommon) | XKB_KEYMAP_FORMAT_TEXT_V1 | XKB_KEYMAP_FORMAT_TEXT_V2 | ||||
| Alt | 8 | 0x100 | Mod1 | Mod1 | Mod1 | |
| Meta | 9 | 0x200 | 0 (unmapped) | 0x200 (canonical, xkbcommon value) | ||
| Super | 10 | 0x400 | 0 | Mod4 + Mod5 | Mod4 + Mod5 | Mod4 + Mod5 |
| Hyper | 11 | 0x800 | 0x1000 | 0x1000 | 0x1000 | |
| Useless | 12 | 0x1000 | 0 | 0 (unmapped) | 0 (explicit mapping) | |
1 << mod_index, where mod_index is: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 |
| Name | Index |
|---|---|
Shift | 0 |
Lock | 1 |
Control | 2 |
Mod1 | 3 |
Mod2 | 4 |
Mod3 | 5 |
Mod4 | 6 |
Mod5 | 7 |
Shift and the virtual modifier LevelThree in xkeyboard-config.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:
xkb_compat section hereinabove.modifier_map.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.
| 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 | ||
| Keyboard controls action | `SetControls` | Set the standard XKB controls | |
| `LockControls` | Lock the standard XKB controls | ||
| Keyboard emulation action | `RedirectKey` | Redirect | Emulate pressing a key with a different key code |
| 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 (???) | |
| `TerminateServer` | Terminate | Shut down the X server | |
SwitchScreen | Switch virtual X screen | ||
| `Private` | Raw encoding of an action | ||
| Unsupported legacy action | 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 |
true, yes, onfalse, no, offNoAction Default action: implicitly do nothing. Does not override previous actions and is dropped.
No parameters.
VoidAction Explicitly do nothing. Does override previous actions and is not dropped.
No parameters.
LockControls(controls=none,affect=neither).SetMods 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 | |
unlockOnPress | boolean | false | Control whether locked modifiers are unlocked on key press or release (default). See hereinafter for further details.
|
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 | |
latchOnPress | boolean | false | Control whether latched modifiers are latched on key press or release (default). See hereinafter for further details.
| |
unlockOnPress | boolean | false | Control whether locked modifiers are unlocked on key press or release (default). See hereinafter for further details.
|
LockMods Modifies the locked modifiers.
| Name | Aliases | Data type | Default value | Description |
|---|---|---|---|---|
modifiers | mods | Modifier mask | none (0) | see `SetMods` |
affect | enumeration:
| both |
| |
unlockOnPress | boolean | false | Control whether locked modifiers are unlocked on key press or release. See hereinafter for further details.
|
| Action | On key press | On key release |
|---|---|---|
SetMods |
|
|
LatchMods |
| |
LockMods |
SetGroup Modifies the base group.
| Name | Data type | Default value | Description |
|---|---|---|---|
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 |
lockOnRelease | boolean | false | Control whether to trigger the group change on key press (default) or release. See further details hereinafter
|
SetControls Set the standard XKB controls
| Name | Alias | Data type | Default value | Description |
|---|---|---|---|---|
controls | ctrls | Mask of the following enumeration:
Plus 2 special values:
| 0 | Standard XKB boolean controls |
LockControls Lock the standard XKB controls
| Name | Alias | Data type | Default value | Description |
|---|---|---|---|---|
controls | ctrls | Mask (see `SetControls`) | 0 | Standard XKB boolean controls |
affect | enumeration:
| both |
|
xkb_keyboard_control_flags for further details.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.| On key press | On key release |
|---|---|
|
Key press causes a key press event for the key specified by the
|
Key release causes a key release event for the key specified by the |
xkeyboard-config for both X11 and Wayland.MovePointerMovePtr Move the mouse pointer
PointerButton PtrBtn Simulate a mouse button press
LockPointerButton LockPointerBtn LockPtrButton LockPtrBtn Simulate a mouse button press, locked until this actiion’s key is pressed again
SetPointerDefault SetPtrDflt Set the default select button (???)
TerminateServer Shut down the X server
No parameters.
SwitchScreen struct is laid out in memory exactly as described in the XKB specification and libraries. However, libxkbcommon have changed these structs in various ways, so this assumption is no longer true and the actions defined in the XKB protocol are unsupported.| 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 |
Private(type=123, data="abcdefg");Private(type=123, data[1]=0, data[2]=100, data[3]=12);ISOLockActionMessagexkbprint program. 1.9.8