RedBear-OS/local/recipes/libs/libxkbcommon/source/doc/keymap-format-text-v1.md

The XKB keymap text format, V1

This document describes the XKB_KEYMAP_FORMAT_TEXT_V1 [keymap] format, as implemented by libxkbcommon.

@see For an overview of the role of this format, please see “@ref xkb-the-config ""”.

@see For examples of keymaps in this format, please see “@ref user-configuration ""”. For further examples see xkeyboard-config, the standard database of keyboard configuration data.

@note Due to the complexity of the format, this document is still is construction. Some additional resources are:

@note

• Ivan Pascal’s XKB documentation
• An Unreliable Guide to XKB Configuration
• The X Keyboard Extension: Protocol Specification
• How to enhance XKB configuration
• ArchWiki XKB page

@tableofcontents{html:2}

[terminology]: @ref terminology [introduction]: @ref introduction [xkb_keymap]: @ref the-xkb_keymap-block [xkb_keycodes]: @ref the-xkb_keycodes-section [xkb_types]: @ref the-xkb_types-section [xkb_compat]: @ref the-xkb_compat-section [xkb_symbols]: @ref the-xkb_symbols-section [virtual modifier statements]:@ref virtual-modifier-statements [modifiers bindings]: @ref modifiers-bindings [actions]: @ref key-actions

Terminology

Keycode

Code that identifies a physical key on a keyboard.

• Raw keycodes are the numeric identifiers used as input in XKB. They are the result of the low-level processing of the data that keyboards send to a computer. For instance 36 may represent the return key.
• XKB keycodes are symbolic names assigned to raw keycodes in order to facilitate their mapping to symbols. For instance the keycode for the return key is the abbreviation RTRN.

See [xkb_keycodes] for further details.

Symbols

A _keysym_ (short for “key symbol”) is a numeric encoding of a symbol on the cap of a key.

They have a canonical name for convenience. It can be:

• A character: e.g. 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.

• A [modifier]⁠: e.g. Shift_L, Control_R, Caps_Lock. See hereinafter.

• A system action: e.g. the arrow Left, Pause, Escape, F1.

The complete list of keysyms is defined in xkbcommon/xkbcommon-keysyms.h.

See [xkb_symbols] for further details on binding keysyms to keycodes.

Modifier

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:

Real modifiers

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][level]
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].
</dd>
<dt><a name="virtual-modifier-def">Virtual modifiers</a>
<dd>
They are the modifiers that are _not_ predefined.
</dd>

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	The usual [Shift]
Lock	Real	Lock	The usual [Caps Lock][Lock]
Control	Real	Control	The usual [Control]
Mod1	Real	Mod1	Not conventional
Mod2	Real	Mod2	Not conventional
Mod3	Real	Mod3	Not conventional
Mod4	Real	Mod4	Not conventional
Mod5	Real	Mod5	Not conventional
Alt	Virtual	Mod1	The usual [Alt]
Meta	Virtual	Mod1 or Mod4	The legacy [Meta] key
NumLock	Virtual	Mod2	The usual [NumLock]
Super	Virtual	Mod4	The usual [Super]/GUI
LevelThree	Virtual	Mod3	[ISO][ISO9995] level 3, aka [AltGr]
LevelFive	Virtual	Mod5	[ISO][ISO9995] level 5

[usual modifiers]: @ref usual-modifiers [Shift]: https://en.wikipedia.org/wiki/Control_key [Lock]: https://en.wikipedia.org/wiki/Caps_Lock [Control]: https://en.wikipedia.org/wiki/Control_key [Alt]: https://en.wikipedia.org/wiki/Alt_key [AltGr]: https://en.wikipedia.org/wiki/AltGr_key [NumLock]: https://en.wikipedia.org/wiki/Num_Lock [Meta]: https://en.wikipedia.org/wiki/Meta_key [Super]: https://en.wikipedia.org/wiki/Super_key_(keyboard_button)

A modifier key can report its state in one of the following 3 ways:

Depressed

Active while depressed; e.g. the usual Shift.

Latched

Activated when pressed and deactivated after the next non-modifier key press.

Locked

Activated when pressed and deactivated when pressed again; e.g. the usual Caps Lock.

See [modifiers bindings] for further details.

[depressed]: @ref depressed-mod-def [latched]: @ref latched-mod-def [locked]: @ref locked-mod-def

Shift Level

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).

Key type

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. - [`TWO_LEVEL`][TWO_LEVEL]: the key has two levels: - Level 1: default level, active when the `Shift` modifier is _not_ active. - Level 2: level activated with the `Shift` modifier. - [`FOUR_LEVEL`][FOUR_LEVEL]: see the example in the previous section.

See [xkb_types] for further details.

Layout

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][ISO9995].

Layouts are ordered and identified by their index. Example:

• Layout 1: Arabic
• Layout 2: English

Key Action

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:

• Change the state of a modifier.
• Change the active group.
• Move the mouse pointer.

See the section “[Key actions][actions]” for further details.

Indicator

A keyboard indicator is a mean to report a specific aspect of the keyboard state.

Physical indicator

Typically a labelled LED on the keyboard, e.g. “Caps Lock” and “Num Lock”.

Logical indicator

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.
- _Virtual_ indicators are not associated to a physical indicator.
  Their effect is only visible for programs monitoring them.

Note that the meanings of _real_ and _virtual_ is slightly
different than the one used for [modifier].
</dd>

See: [xkb_keycodes][indicator name] to define indicators and [xkb_compat][indicator effect] to define their effects.

Keymap

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:

• the software object defined and managed by libxkbcommon;
• the text configuration used to create this software object.

See @ref keymap-components-intro and [xkb_keymap] for further details.

Keyboard configuration database @anchor database-def

A database that provides the [keymap components](@ref keymap-components-intro). \*nix OSs uses the _standard_ database [xkeyboard-config]. One may extend this database with _custom_ layouts: see “@ref user-configuration ""” for further details.

[keycode]: @ref keycode-def [keysym]: @ref keysym-def [keysyms]: @ref keysym-def [modifier]: @ref modifier-def [modifiers]: @ref modifier-def [real modifier]: @ref real-modifier-def [real modifiers]: @ref real-modifier-def [virtual modifier]: @ref virtual-modifier-def [virtual modifiers]: @ref virtual-modifier-def [level]: @ref level-def [shift level]: @ref level-def [level index]: @ref level-index-def [key type]: @ref key-type-def [key types]: @ref key-type-def [layout]: @ref layout-def [action]: @ref key-action-def [indicator]: @ref indicator-def [keymap]: @ref keymap-def [database]: @ref database-def [ISO9995]: https://en.wikipedia.org/wiki/ISO/IEC_9995

Introduction to the XKB text format

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 “@ref xkb-the-config ""”. It has the following two main use cases, illustrated in the [diagram hereinafter](@ref xkb-keymap-components-diagram):

• 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][RMLVO] and its corresponding [KcCGST components][KcCGST] files.

  @see xkb_keymap::xkb_keymap_new_from_names

  @see xkeyboard-config for the implementation of the standard keymap configuration database.

  @see “@ref user-configuration ""” to add a custom layout or option.

• 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.

  @see xkb_keymap::xkb_keymap_new_from_string

@anchor xkb-keymap-components-diagram @dotfile xkb-keymap-components "XKB text format use cases"

[RMLVO]: @ref RMLVO-intro [KcCGST]: @ref KcCGST-intro [complete keymap]: @ref keymap-intro

XKB file

There are two kinds of files for the XKB text format:

Keymap file @anchor keymap-file-def

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](@ref xkb-keymap-components-diagram) above). Its top-level structure consists of the [xkb_keymap] block.

Keymap _component_ file @anchor keymap-component-file-def

A file with the description of a _particular_ [KcCGST component][KcCGST]. It is the kind of file that the server uses to assemble a [keymap file]. Its top-level structure consists of a _single type_ of [keymap sections]. A component file may contain multiple such sections.

[keymap file]: @ref keymap-file-def [keymap component file]: @ref keymap-component-file-def [keymap sections]: @ref keymap-section-def [section]: @ref keymap-section-def [keymap components]: @ref keymap-component-def

Keymap components

[Keymap components][keymap components] are described with [keymap sections]. They are grouped in [keymap component files][keymap component file] to form a [keyboard configuration database][database].

Keymap _component_ @anchor keymap-component-def

A part of the keymap _object_. The set of keymap components is referred as [KcCGST]. They are presented in the [table hereinafter][keymap components table].

Keymap _section_ @anchor keymap-section-def

A part of the keymap _text configuration_ dedicated to one of the [keymap components][keymap components table].

Component _folder_

A folder in the [keymap configuration database][database], dedicated to files with partial definitions of the same keymap section.

[keymap components table]: @ref keymap-components-table

@anchor keymap-components-table

Keymap components

[Component](@ref keymap-component-def)	[Section][section] in a [keymap][xkb_keymap]	Folder in a keymap configuration database	Description
Key codes	[xkb_keycodes]	`keycodes`	A translation of the raw [key codes][keycode] 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. @attention This legacy feature is [not supported](@ref geometry-support) by _xkbcommon_. </td>
Key symbols	[xkb_symbols]	`symbols`	A translation of symbolic [key codes][keycode] into actual [key symbols][keysyms] (keysyms).
Key types	[xkb_types]	`types`	Types describe how a pressed key is affected by active [modifiers] such as Shift, Control, Alt, etc.

Comments

Comments are introduced following either // or # until the end of the line.

Literals

String literal

A string is surrounded by double quotes: “"”. The following _escape sequences_ are supported:

Escape sequence	Meaning
\\	Backslash “\”
\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: \0 → NULL, \42 → "

@note The string encoding is unspecified and not validated, but for best results, stick to ASCII.

Number literal

A number can be written in three forms:

• decimal integer: 1, 123, etc.
• decimal floating-point number: 1.23, etc.
• hexadecimal integer: prefixed with 0x: 0x123, 0xff, 0xAB, etc.

Keywords

The following table presents the keywords used in the format. They are case-sensitive.

Keyword	Use
action	TODO
alias	TODO
alphanumeric_keys	TODO
alternate_group	TODO
alternate	TODO
augment	Mode qualifier for [include] statements
default	TODO
function_keys	TODO
group	TODO
hidden	TODO
include	[Include statement][include]
indicator	TODO
interpret	TODO
key	TODO
keypad_keys	TODO
keys	TODO
logo	TODO
mod_map	Alias of modifier_map
modifier_keys	TODO
modmap	Alias of modifier_map
modifier_map	TODO
outline	TODO
overlay	TODO
override	Mode qualifier for [include] statements
partial	TODO
replace	Mode qualifier for [include] statements
row	TODO
section	TODO
shape	TODO
solid	TODO
text	TODO
type	TODO
virtual_modifiers	TODO
virtual	TODO
xkb_compat_map	Alias of xkb_compatibility_map
xkb_compat	Alias of xkb_compatibility_map
xkb_compatibility_map	Declare a [compatibility section][xkb_compat]
xkb_compatibility	Alias of xkb_compatibility_map
xkb_geometry	Declare a geometry section (TODO: legacy)
xkb_keycodes	Declare a [keycodes section][xkb_keycodes]
xkb_keymap	Declare a [keymap block][xkb_keymap]
xkb_layout	TODO
xkb_semantics	TODO
xkb_symbols	Declare a [symbols section][xkb_symbols]
xkb_types	Declare a [key types section ][xkb_types]

[include]: @ref xkb-include

Built-in settings

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.

The include mechanism

@todo the import mechanism, its qualifiers

The “xkb_keymap” block

A [keymap file] consists of a single top-level xkb_keymap block, under which are nested the following sections:

[xkb_keycodes]

A translation of the hardware/evdev scancodes from the keyboard into XKB symbolic keycodes.

[xkb_types]

A specification of the modifier mask, target level and preserved modifiers various modifiers combination produce.

[xkb_compat]

A specification of what actions various special-purpose keys produce.

[xkb_symbols]

A translation of symbolic key codes into actual symbols and actions.

Overview of a keymap file:

xkb_keymap {
  xkb_keycodes "XXX" {
    // ...
  }
  xkb_types "XXX" {
    // ...
  };
  xkb_compatibility "XXX" {
    // ...
  };
  xkb_symbols "XXX" {
    // ...
  };
};

The “xkb_keycodes” section

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][keycode]. Each key is given a name by which it can be referred to later, e.g. in the symbols section.

Keycode statements

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.

   \ 99 \ 00 \ 01 \ 02 \ 03 \ 04 \ 05…
    \    \    \    \    \    \    \
-----------------------------------------
E     \    \ ^  \ 1  \ 2  \ 3  \ 4  \ 5…
------------------------------------------
D      \     Tab \ Q  \ W  \ E  \ R  \ T…
-------------------------------------------
C       \Caps     \ A  \ S  \ D  \ F  \ G…
--------------------------------------------
B        \Shift    \ Z  \ X  \ C  \ V  \ B…
---------------------------------------------
A         \Ctrl\GUI \Alt \Space…
----------------------------------------------

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.

Alias statements

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.

LED name statements

[indicator name]: @ref indicator-name

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.

The “xkb_types” section

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][TWO_LEVEL] (with Shift choosing the second level), [ALPHABETIC][ALPHABETIC] (where Caps Lock may also choose the second level), etc.

How key types work

Key types define a mapping between the [modifiers] and [shift levels]. Key types have four parameters:

@ref key-type-level-name "Shift level names"

Declare [shift levels]. Mainly for documentation.

@ref key-type-modifiers "Modifiers filter"

Declare what modifiers should be taken into account in the mapping.

@ref key-type-map "Modifiers mapping"

Lookup table to translate modifiers combinations into shift levels.

@ref key-type-preserve "Modifiers preservation"

Tweak the computation of [consumed modifiers].

[consumed modifiers]: @ref consumed-modifiers [shift levels]: @ref level-def

Key types are used to compute:

• the [shift level][]: see xkb_state::xkb_state_key_get_level().
• the [consumed modifiers][]: see xkb_state::xkb_state_key_get_consumed_mods() and xkb_state::xkb_state_key_get_consumed_mods2().

The following diagram presents an overview of theses computations:

@anchor xkb-types-explanation-diagram @dotfile xkb-types-explanation "Use of key types to compute shift level and consumed modifiers"

Type definitions

Statements of the form:

type "FOUR_LEVEL" { ... }

The above would create a new type named [FOUR_LEVEL][FOUR_LEVEL]. The body of the definition may include statements of the following forms:

“level_name” statements

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” statement

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” entry statements

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.

“preserve” statements

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](@ref consumed-modifiers) in this translation. For example, in a simple US keymap, the “G” key is assigned an ordinary [ALPHABETIC][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.

@attention Consuming a locked modifier does not unlock it and it can be consumed again in further keysym translations.

@note Remember that @ref keysym-transformations may affect the resulting keysym when some modifiers are not [consumed](@ref consumed-modifiers).

@remark preserve statements may be used to tweak keyboard shorcuts. @remark@figure @figcaption Example of use of preserve to tweak Control shortcuts. Note it would require further work in order to support other modifiers. @endfigcaption

xkb_types {
    // ...
    type "TWO_LEVEL_PLUS_CONTROL" {
        modifiers = Shift + Control;
        map[None]          = Level1;
        map[Shift]         = Level2;
        map[Control]       = Level3;
        map[Control+Shift] = Level4;
        // Using preserve will make Control not consumed and allow
        // applications to detect keyboard shortcuts with alternative
        // keysyms in levels 3 and 4 rather than the levels 1 and 2.
        preserve[Control]       = Control;
        preserve[Control+Shift] = Control;
        level_name[Level1] = "Base";
        level_name[Level2] = "Shift";
        level_name[Level3] = "Tweaked Control";
        level_name[Level4] = "Tweaked Control + Shift";
    };
};
xkb_symbols {
    // ...
    // The following key would produce Greek keysym on Base and Shift levels,
    // but will produce the corresponding ASCII Latin keysyms when using Control.
    key <AC01> {
        type[Group1]="TWO_LEVEL_PLUS_CONTROL",
        [Greek_alpha, Greek_ALPHA, a, A]
    };
};

@endfigure

Key types examples

Definitions examples

@note The convention is that 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.

Two levels

The following examples compare two basic types with two levels: [TWO_LEVEL][TWO_LEVEL] and [ALPHABETIC][ALPHABETIC]. They differ on their handling of the Lock modifier. See the [next section](@ref key-type-mappings-examples) for an illustration with concrete layouts.

[TWO_LEVEL]: @ref TWO_LEVEL [ALPHABETIC]: @ref ALPHABETIC

`TWO_LEVEL` @anchor TWO_LEVEL

@figure@figcaption Definition code ([source][two-type-src]) @endfigcaption ```c type "TWO_LEVEL" { // Only care about Shift; Lock will be filter out modifiers = Shift; // Define mapping map[None] = Level1; // No modifier -> level 1 map[Shift] = Level2; // Exactly Shift -> level 2 // (no map entry with Lock) // Define level names level_name[Level1] = "Base"; level_name[Level2] = "Shift"; }; ``` @endfigcaption @figure@figcaption Mapping test @endfigcaption | *Active* modifiers | *Filtered* modifiers | Match? | Shift level | | ------------------ | -------------------- | ------ | ----------- | | (none) | (none) | Yes | 1 | | `Shift` | `Shift` | Yes | 2 | | `Lock` | (none) | Yes | 1           | | `Shift + Lock` | `Shift` | Yes | 2 | @endfigcaption

`ALPHABETIC` @anchor ALPHABETIC

@figure@figcaption Definition code ([source][alphabetic-type-src]) @endfigcaption ```c type "ALPHABETIC" { // Only care about Shift and Lock modifiers = Shift + Lock; // Define mapping map[None] = Level1; // No modifier -> level 1 map[Shift] = Level2; // Exactly Shift -> level 2 map[Lock] = Level2; // Exactly Lock -> level 2 // Define level names level_name[Level1] = "Base"; level_name[Level2] = "Caps"; }; ``` @endfigcaption @figure@figcaption Mapping test @endfigcaption | *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 | @endfigcaption

Four levels

The following examples compare basic types with four levels: [FOUR_LEVEL][FOUR_LEVEL], [FOUR_LEVEL_SEMIALPHABETIC][FOUR_LEVEL_SEMIALPHABETIC] and [FOUR_LEVEL_ALPHABETIC][FOUR_LEVEL_ALPHABETIC]. They differ on their handling of the Lock modifier. See the [next section](@ref key-type-mappings-examples) for an illustration with concrete layouts.

[FOUR_LEVEL]: @ref FOUR_LEVEL [FOUR_LEVEL_SEMIALPHABETIC]: @ref FOUR_LEVEL_SEMIALPHABETIC [FOUR_LEVEL_ALPHABETIC]: @ref FOUR_LEVEL_ALPHABETIC

`FOUR_LEVEL` @anchor FOUR_LEVEL

@figure@figcaption Definition code ([source][four-level-src]) @endfigcaption ```c type "FOUR_LEVEL" { modifiers = Shift + LevelThree; map[None] = Level1; map[Shift] = Level2; // (no map entry with Lock) // (no map entry with Lock) map[LevelThree] = Level3; map[Shift+LevelThree] = Level4; // (no map entry with Lock) // (no map entry with Lock) // (no preserve entry with Lock) // (no preserve entry with Lock) level_name[Level1] = "Base"; level_name[Level2] = "Shift"; level_name[Level3] = "AltGr"; level_name[Level4] = "Shift AltGr"; }; ``` @endfigcaption @figure@figcaption Mapping test @endfigcaption | *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 | @endfigcaption

`FOUR_LEVEL_SEMIALPHABETIC` @anchor FOUR_LEVEL_SEMIALPHABETIC

@figure@figcaption Definition code ([source][four-level-semialphabetic-src]) @endfigcaption ```c type "FOUR_LEVEL_SEMIALPHABETIC" { modifiers = Shift + Lock + LevelThree; map[None] = Level1; map[Shift] = Level2; map[Lock] = Level2; map[Shift+Lock] = Level1; map[LevelThree] = Level3; map[Shift+LevelThree] = Level4; map[Lock+LevelThree] = Level3; map[Shift+Lock+LevelThree] = Level4; preserve[Lock+LevelThree] = Lock; preserve[Shift+Lock+LevelThree] = Lock; level_name[Level1] = "Base"; level_name[Level2] = "Shift"; level_name[Level3] = "AltGr"; level_name[Level4] = "Shift AltGr"; }; ``` @endfigcaption @figure@figcaption Mapping test @endfigcaption | *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 | @endfigcaption

`FOUR_LEVEL_ALPHABETIC` @anchor FOUR_LEVEL_ALPHABETIC

@figure@figcaption Definition code ([source][four-level-alphabetic-src]) @endfigcaption ```c type "FOUR_LEVEL_ALPHABETIC" { modifiers = Shift + Lock + LevelThree; map[None] = Level1; map[Shift] = Level2; map[Lock] = Level2; map[Shift+Lock] = Level1; map[LevelThree] = Level3; map[Shift+LevelThree] = Level4; map[Lock+LevelThree] = Level4; map[Shift+Lock+LevelThree] = Level3; // (no preserve entry with Lock) // (no preserve entry with Lock) level_name[Level1] = "Base"; level_name[Level2] = "Shift"; level_name[Level3] = "AltGr"; level_name[Level4] = "Shift AltGr"; }; ``` @endfigcaption @figure@figcaption Mapping test @endfigcaption | *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 | @endfigcaption

Examples with standard keyboard layouts

See the detailed table of mappings

The following table compares the mappings of various key types for the modifiers `Shift`, `Lock` and `LevelThree`, using the standard layouts [`us`][us-layout] (US English) and [`es`][es-layout] (Spanish).

Key	Layout	Key type	Active modifiers	Level	Keysym	Comment
AE01	us	[TWO_LEVEL][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][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][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][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][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][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

The “xkb_compat” section

This [section] is the third to be processed, after xkb_keycodes and xkb_types.

Interpret statements

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:

• Bind an [action], like SetMods or LockGroup, to the key. Actions, like symbols, are specified for each level of each group in the key separately.

• Add a [virtual modifier] to the key’s virtual modifier mapping (vmodmap).

• Specify whether the key should repeat or not.

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.

@anchor interpret-mechanism Each interpret specifies a condition by which it attaches to certain levels. The condition consists of two parts:

• A [keysym]. If the level has a different (or more than one) keysym, the match fails. Leaving out the keysym is equivalent to using the special value 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).

  • A matching operation, that is one of the following:

    • 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.

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:

• A specific keysym will always match before a generic NoSymbol condition.

• If the keysyms are the same, the interpret with the more specific matching operation is used. The above list is sorted from least to most specific.

• If both the keysyms and the matching operations are the same (but the modifiers are different), the first interpret 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 key repeat is a property of the entire key; it is not level-specific. In order to avoid confusion, it is only inspected for the first level of the first group; the interpret’s repeat setting is ignored when applied to other levels.

• If one of the above fields was set directly for a key in xkb_symbols, the explicit setting takes precedence over the interpret.

The body of the statement may include statements of the following forms (all of which are optional):

“useModMapMods” statement

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.

“action” statement

action = LockMods(modifiers=NumLock);

Bind this action to the matching levels. See [key actions][actions] for the list of available key actions.

“virtualModifier” statement

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;

“repeat” statement

repeat = True;

Set whether the key should repeat or not. Must be a boolean value.

LED map statements

[indicator effect]: @ref indicator-effect

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][indicator 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” statement

modifiers = ScrollLock;

If the given [modifiers] are in the required state (see below), the LED is lit.

“whichModState” statement

whichModState = Latched+Locked;

Can be any combination of:

• base, latched, locked, effective
• any (i.e. all of the above)
• none (i.e. none of the above)
• compat (legacy value, treated as effective)

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” statement

groups = All - group1;

If the given groups are in the required state (see below), the LED is lit.

“whichGroupState” statement

whichGroupState = Effective;

Can be any combination of:

• base, latched, locked, effective
• any (i.e. all of the above)
• none (i.e. none of the above)

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.

Default values

@todo e.g. setMods.clearLocks= True;

The “xkb_symbols” section

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.

A map can have various flags applied to it above the statement, separated by whitespace:

partial alphanumeric_keys
xkb_symbols "basic" {
    ...
}

The possible flags are:

• partial - Indicates that the map doesn’t cover a complete keyboard.
• default - Marks the symbol map as the default map in the file when no explicit map is specified. If no map is marked as a default, the first map in the file is the default.
• hidden - Variant that can only be used internally
• alphanumeric_keys - Indicates that the map contains alphanumeric keys
• modifier_keys - Indicates that the map contains modifier keys
• keypad_keys - Indicates that the map contains keypad keys
• function_keys - Indicates that the map contains function keys
• alternate_group - Indicates that the map contains keys for an alternate group

If no *_keys flags are supplied, then the map is assumed to cover a complete keyboard.

At present, except for default, none of the flags affect key processing in libxkbcommon, and only serve as metadata.

Name statements

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.

Include statements

Statements of the form:

include "nokia_vndr/rx-51(nordic_base)"

Will include data from another xkb_symbols section, possibly located in another file. Here it would include the xkb_symbols section called nordic_base, from the file rx-51 located in the nokia_vndr folder, itself located in an XKB include path.

Key statement

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](@ref the-xkb_keycodes-section) section.

A key description consists of:

Groups

Each key may have one or more associated [groups]. Each group can be configured with the following parameters:

    - @ref key-type-setting "Type"</dt>
    - @ref key-symbols-table "Symbols"</dt>
    - @ref key-actions-table "Actions"</dt>
</dd>
<dt>Additional attributes</dt>
<dd>
    These attributes are usually set via the <code>[xkb_compat]</code>
    section, but may be also set directly:

    - @ref key-virtual-modifiers "Virtual modifiers"
    - @ref key-repeat "Repeat"
</dd>

@warning Using multiple groups in symbols files is not recommended, because some tools rely on the assumption that an xkb_symbols section only affect a single group. It is fine with a keymap file though.

@note In what follows we assume the common use case with a single group, which benefits from a special syntax. See the section @ref key-groups "Multiple groups" for the general syntax.

[groups]: @ref layout-def

Symbols

The main part of the key description is the symbols table. It maps shift levels to keysyms, e.g.:

key <AD01> { [ q, Q ] }; // Level 1 → `q`, Level 2 → `Q`

Symbols are named using the symbolic names from the xkbcommon/xkbcommon-keysyms.h file. 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 @ref key-type-setting "key type", presented in the next section.

@remark Remember that @ref keysym-transformations may affect the resulting keysym when some modifiers are not [consumed](@ref consumed-modifiers).

As an extension to the XKB format, libxkbcommon supports multiple key symbols per level.

key <AD01> { [ {a, b}, Q ] };

In this example, the keycode <AD01> produces two symbols on level 1 (XKB_KEY_a and XKB_KEY_b) and one symbol (XKB_KEY_Q) on level 2.

@warning Keymaps containing multiple key symbols per level are not supported by the various X11-related tools (setxkbmap, xkbcomp, etc.).

[symbols table]: @ref key-symbols-table

Type

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:

key <AD01> {
    type[Group1] = "TWO_LEVEL", // Type
    [q, Q]                      // Symbols
};

The name of the key type is enclosed between double quotes.

The key type may be omitted and will default to:

• key.type global defaults, if set.
• a standard type using the following heuristic:
  • 1 keysym: ONE_LEVEL
  • 2 keysyms:
    • if the two keysyms are letter and the first is lower case and the other upper case, then [ALPHABETIC][ALPHABETIC];
    • if one of the keysyms is numpad, then KEYPAD else [TWO_LEVEL][TWO_LEVEL].
  • 3 or 4 keysyms (a missing 4th keysym is set to NoSymbol):
    • if the first two keysyms are letters and the first is lower case and the other upper case:
      • if the last two keysyms are letters and the first is lower case and the other upper case then [FOUR_LEVEL_ALPHABETIC][FOUR_LEVEL_ALPHABETIC];
      • else [FOUR_LEVEL_SEMIALPHABETIC][FOUR_LEVEL_SEMIALPHABETIC].
    • if one of the first two keysyms is numpad, then FOUR_LEVEL_KEYPAD;
    • else [FOUR_LEVEL][FOUR_LEVEL].

@figure@figcaption Commented examples for inferred types: @endfigcaption

// 1 to 2 keysyms
key <LFSH> { [Shift_L] };                    // Type: ONE_LEVEL
key <AE01> { [1, exclam] };                  // Type: TWO_LEVEL
key <AD01> { [q, Q] };                       // Type: ALPHABETIC
key <KP1>  { [KP_End, KP_1] };               // Type: KEYPAD
// Edge case: this is consider alphabetic, although
// the lower case does not correspond to the upper case.
key <AD01> { [q, N] };                       // Type: ALPHABETIC

// 3 to 4 keysyms
key <AE01> { [1, exclam, bar] };             // Type: FOUR_LEVEL
key <AE01> { [1, exclam, bar, exclamdown] }; // Type: FOUR_LEVEL
key <AD01> { [q, Q, at] };                   // Type: FOUR_LEVEL_SEMIALPHABETIC
key <AD01> { [q, Q, at, Greek_OMEGA] };      // Type: FOUR_LEVEL_SEMIALPHABETIC
key <AD05> { [t, T, tslash, Tslash] };       // Type: FOUR_LEVEL_ALPHABETIC

// The inferred type is `FOUR_LEVEL`, but using `LevelThree+Lock`
// will produce `Q`, because of the keysyms transformations and
// the corresponding internal capitalization processing.
key <AE01> { [1, exclam, q, Q] };            // Type: FOUR_LEVEL

// Won’t work, because there is no heuristic for more than 4 keysyms
// It will trigger the warnings XKB-183 and XKB-516 and default to ONE_LEVEL,
// ignoring all the keysyms but the first one.
key <AD01> {[q, Q, at, any, masculine, U2642]};
// Will work as expected
key <AD01> {
    type[Group1] = "EIGHT_LEVEL_SEMIALPHABETIC",
    [q, Q, at, any, masculine, U2642]
};

@endfigure

Actions

@note This is usually not set explicitly but via the [interpret mechanism] by using the [action](@ref interpret-action) statement in the [xkb_compat] section.

@figure@figcaption Example: Set the modifier action of the key <LALT> manually. @endfigcaption

key <LALT> {
    symbols[Group1]=[Alt_L],
    actions[Group1]=[SetMods(modifiers=modMapMods)]
};

@endfigure

For further details see [key actions][actions].

Multiple groups

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 ] };

@warning Using multiple groups in symbols files is not recommended, because some tools rely on the assumption that an xkb_symbols section only affect a single group. It is fine with a keymap file though.

Virtual modifiers

@note This is usually not set explicitly but via the [interpret mechanism] by using the [virtualModifier](@ref interpret-virtualModifier) statement from the [xkb_compat] section.

@remarks When setting a [modifier action](@ref modifiers-actions), it is required to declare the corresponding virtual modifier using a [virtual_modifiers](@ref virtual-modifier-statements) statement.

@figure@figcaption Example: Set the virtual modifier of the key <LALT> to Alt. @endfigcaption

// Declare the virtual modifier that will be used
virtual_modifiers Alt;

key  <LALT> {
    virtualModifiers = Alt,
    [ Alt_L ]
};

@endfigure

[interpret mechanism]: @ref interpret-mechanism

Repeat

@note This is usually not set explicitly but via the [interpret mechanism] by using the [repeat](@ref interpret-repeat) statement in the [xkb_compat] section.

@figure@figcaption Example: make the <LALT> key not repeating. @endfigcaption

key  <LALT> {
    repeat = False,
    [ Alt_L ]
};

@endfigure

Virtual modifier statements

Statements of the form:

virtual_modifiers LControl;

Can appear in the xkb_types, xkb_compat, xkb_symbols sections.

Modifiers bindings

Real and virtual modifiers

Modifiers are a particularly tricky part of XKB. For historical reasons they are divided in two categories: [real modifiers] and [virtual modifiers].

Note that in X11, the maximum of virtual modifiers is 16 (see XkbNumVirtualMods).

The following table summarizes the modifiers defined in xkeyboard-config (this is subject to change).

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

Define and use a modifier

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:

1. Define its behavior and [keysym] binding in the [xkb_compat] section:

   // Declare virtual modifiers. Shift being real modifier,
   // we do not need to add it here.
   virtual_modifiers LevelThree;
   
   // Set defaults. They are overridden if set directly in the xkb_symbols.
   interpret.repeat= False; // only applied on first level
   setMods.clearLocks= True;
   latchMods.clearLocks= True;
   latchMods.latchToLock= True;
   
   // Default statement for real modifiers: any key bound to a real
   // modifier via modifier_map will set this modifier at all its
   // levels.
   // Here only to illustrate: do not add it!
   interpret Any + Any {
       action= SetMods(modifiers=modMapMods);
   };
   
   // Shift being real modifier, we do not need a corresponding
   // interpret statement because the previous one suffices.
   
   // Let’s associate LevelThree to the keysym ISO_Level3_Shift
   
   // First, match the keys and their levels with the
   // ISO_Level3_Shift keysym and with any real modifier
   // (Any = AnyOf(all)) in its modmap.
   interpret ISO_Level3_Shift+Any {
       // Only match the first level of the first group
       useModMapMods= level1;
       // Add the virtual modifier to the key’s vmodmap
       virtualModifier= LevelThree;
       // Activate the LevelThree modifier (depressed mode)
       action= SetMods(modifiers=LevelThree);
   };
   
   // Then for keys and their levels with the
   // ISO_Level3_Shift keysym but with either no real modifier
   // in its modmap or a level higher than 1.
   // Indeed:
   // • In case the level is higher than 1 there is no match
   //   in the previous statement.
   // • The condition is equivalent to
   //   ISO_Level3_Shift+AnyOfOrNone(all), but since
   //   the previous statement ISO_Level3_Shift+Any is more
   //   specific, it will be matched before this one.
   interpret ISO_Level3_Shift {
       // Activate the LevelThree modifier (depressed mode)
       action= SetMods(modifiers=LevelThree);
   };
   

2. Define [key types] that use it in the [xkb_types] section:

   // Declare virtual modifiers. Shift being real modifier,
   // we do not need to add it here.
   virtual_modifiers LevelThree;
   
   type "FOUR_LEVEL" {
       // Key type modifier mask: all the modifiers used in the key type
       modifiers = Shift + LevelThree;
       map[None] = Level1;
       map[Shift] = Level2;
       map[LevelThree] = Level3;
       map[Shift+LevelThree] = Level4;
       level_name[Level1] = "Base";
       level_name[Level2] = "Shift";
       level_name[Level3] = "AltGr";
       level_name[Level4] = "Shift AltGr";
   };
   

3. Bind it to a [keycode] in the [xkb_symbols] section:

   1. Map [keysyms] used in the xkb_compat section hereinabove.
   2. Bind [real modifiers] to keys using these keysyms with 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.

   // Shift: defined in pc symbols
   key <LFSH> {[  Shift_L    ]};
   key <RTSH> {[  Shift_R    ]};
   modifier_map Shift { Shift_L, Shift_R };
   // The previous will resolve to:
   // modifier_map Shift { <LFSH>, <RTSH> };
   // Thus the real modifier Shift is added to the modmap of
   // <LFSH> and <RTSH>.
   // The “Any + Any” interpret statement matches <LFSH> and <RTSH>,
   // therefore these keys set the Shift modifier.
   
   // LevelThree: defined in pc symbols
   // With the following 2 lines:
   // 1. The modifier keysym is on the first level of the first group.
   // 2. The real modifier Mod5 is bound to <LVL3>,
   //    i.e. Mod5 is added to its modmap.
   // 3. It matches the interpret statement “ISO_Level3_Shift+Any”,
   //    which adds the LevelThree modifier to the vmodmap of <LVL3>.
   // 4. The mapping of LevelThree to real modifiers is the union
   //    of modmaps with corresponding vmodmaps containing
   //    LevelThree. In our case there is only one: therefore
   //    LevelThree maps to Mod5.
   key <LVL3> {[  ISO_Level3_Shift  ]};
   modifier_map Mod5  { <LVL3> };
   
   // LevelThree: defined in level3 symbols
   // Not bound to a real modifier, so interpret statement
   // “ISO_Level3_Shift” applies.
   key <RALT> {[ISO_Level3_Shift], type[group1]="ONE_LEVEL" };
   
   // Note: we could have the following line, but it is not necessary
   // because we have the mappings of <LVL3>.
   // modifier_map Mod5  { <RALT> };
   
   // Warning: if we had the for example the following line, the
   // mapping of LevelThree to real modifiers would be “Mod1+Mod5”.
   // modifier_map Mod1  { <RALT> };
   
   // Alternative definitions, without using interpret statements
   virtual_modifiers LevelThree;
   key <LVL3> { virtualmodifiers=LevelThree
              , repeats=False
              , symbols[Group1] = [ISO_Level3_Shift]
              , actions[Group1] = [SetMods(modifiers=LevelThree)] };
   modifier_map Mod5  { <LVL3> };
   key <RALT> { repeat=False
              , symbols[Group1] = [ISO_Level3_Shift]
              , actions[Group1] = [SetMods(modifiers=LevelThree)]
              , type[group1]="ONE_LEVEL" };
   
   // FOUR_LEVEL key type example from latin symbols
   key <AB05> {[b, B, leftdoublequotemark, leftsinglequotemark]};
   

Key actions

@todo list of all actions and their parameters

The following table provide an overview of the available actions:

Category	Action	Alias	Description
	NoAction		Do nothing.
[Modifier action]	SetMods		Modifies the depressed modifiers
^	LatchMods		Modifies the latched modifiers
^	LockMods		Modifies the locked modifiers
[Group action]	SetGroup		TODO
^	LatchGroup		TODO
^	LockGroup		TODO
[Legacy action]	MovePointer	MovePtr	TODO
^	PointerButton	PtrBtn	TODO
^	LockPointerButton	LockPtrBtn	TODO
^	SetPointerDefault	SetPtrDflt	TODO
^	SetControls		TODO
^	LockControls		TODO
^	TerminateServer	Terminate	TODO
^	SwitchScreen		TODO
^	Private		TODO

Common syntax:

• Boolean values:
  • true, yes, on
  • false, no, off

Modifiers actions

[modifier action]: @ref modifiers-actions

@todo default values

There are 3 modifiers actions:

`SetMods`

Modifies the _depressed_ modifiers.

Parameters:

• modifiers or mods: 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 (see its use hereinafter).

`LatchMods`

Modifies the _latched_ modifiers

Parameters:

• modifiers or mods: see SetMods.
• clearLocks: boolean (see its use hereinafter).
• latchToLock: boolean (see its use hereinafter).

`LockMods`

Modifies the _locked_ modifiers.

Parameters:

• modifiers or mods: see SetMods.
• affect:
  • lock: the action only locks the modifier, but cannot unlock it.
  • unlock: the action only unlocks modifier, but cannot lock it.
  • both: the first key press locks the modifier and the second key press releases the modifier. It is a default mode.
  • neither: do not lock nor unlock, i.e. do nothing.

@todo highlight that there is reference counting for the modifiers, e.g. to manage multiple physical keys for the same modifier.

These actions perform different tasks on key press and on key release:

Effects of modifiers actions

Action	On key press	On key release
SetMods	Adds modifiers to depressed modifiers	Removes modifiers from depressed modifiers, provided that no other key which affects the same modifiers is logically down. If clearLocks=yes and no other key were operated simultaneously with this key, then the modifiers will be removed as well from the locked modifiers.
LatchMods	Adds modifiers to latched modifiers.	Removes modifiers from latched modifiers. If 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. If latchToLock=yes then the modifiers are added to the locked modifiers.
LockMods	Adds modifiers to depressed modifiers. Toggle these modifiers in locked modifiers.	Removes modifiers from depressed modifiers. Locked modifiers stay unchanged.

@todo Finish

Group actions

[group action]: @ref group-actions

There are 3 group actions:

SetGroup

TODO

LatchGroup

TODO

LockGroup

TODO

@todo Describe each action

Unsupported legacy actions

[legacy action]: @ref legacy-actions

@attention The following legacy actions are kept for compatibility only: they are parsed and validated but have no effect. This allows to use keymaps defined in xkeyboard-config for both X11 and Wayland.

Pointer actions

Action	Alias	Description
MovePointer	MovePtr
PointerButton	PtrBtn
LockPtrButton	LockPtrBtn
LockPointerButton	LockPointerBtn
SetPointerDefault	SetPtrDflt

@todo Describe each action

Control flags actions

@todo SetControls, LockControls

Server actions

@todo TerminateServer, SwitchScreen

Private action

@todo Private