1 # The XKB keymap text format, V1 {#keymap-text-format-v1}
5 • The Markdown supported in Doxygen is limited and buggy.
6 Current issues and solutions:
7 • In headers, only plain text is supported.
8 • Use the language tag “c” for block code to give them a nice (approximated)
12 This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` keymap format,
13 as implemented by libxkbcommon.
15 The standard database of keyboard configuration data is
18 @note Due to the complexity of the format, this document is still is construction.
19 Some additional resources are:
22 - [Ivan Pascal's XKB documentation][ivan-pascal]
23 - [An Unreliable Guide to XKB Configuration][unreliable-guide]
24 - [The X Keyboard Extension: Protocol Specification][XKB Protocol]
25 - [How to enhance XKB configuration][xkeyboard-config doc]
26 - [ArchWiki XKB page][arch-wiki]
28 [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
29 [ivan-pascal]: https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/
30 [unreliable-guide]: https://www.charvolant.org/doug/xkb/html/index.html
31 [XKB Protocol]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html
32 [xkeyboard-config doc]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/blob/master/docs/README.enhancing
33 [arch-wiki]: https://wiki.archlinux.org/index.php/X_keyboard_extension
36 @tableofcontents{html:2}
41 1. [Terminology][terminology]
42 2. [Introduction to the XKB text format][introduction]
43 3. [The xkb_keymap block][xkb_keymap]
44 4. [The xkb_keycodes section][xkb_keycodes]
45 5. [The xkb_types section][xkb_types]
46 6. [The xkb_compat section][xkb_compat]
47 7. [The xkb_symbols section][xkb_symbols]
48 8. [Virtual modifier statements][virtual modifier statements]
49 9. [Modifiers bindings][modifiers bindings]
50 10. [Key actions][actions]
53 [terminology]: @ref terminology
54 [introduction]: @ref introduction
55 [xkb_keymap]: @ref the-xkb_keymap-block
56 [xkb_keycodes]: @ref the-xkb_keycodes-section
57 [xkb_types]: @ref the-xkb_types-section
58 [xkb_compat]: @ref the-xkb_compat-section
59 [xkb_symbols]: @ref the-xkb_symbols-section
60 [virtual modifier statements]:@ref virtual-modifier-statements
61 [modifiers bindings]: @ref modifiers-bindings
62 [actions]: @ref key-actions
64 ## Terminology {#terminology}
67 <dt><a name="keycode-def">Keycode</a><dt>
69 Code that identifies a physical key on a keyboard.
71 - _Raw_ keycodes are the numeric identifiers used as input in XKB.
72 They are the result of the low-level processing of the data that
73 keyboards send to a computer. For instance `36` may represent
75 - _XKB_ keycodes are _symbolic_ names assigned to raw keycodes in
76 order to facilitate their mapping to symbols. For instance the
77 keycode for the return key is the abbreviation `RTRN`.
79 See [xkb_keycodes] for further details.
81 <dt><a name="keysym-def">Symbols</a></dt>
83 A _keysym_ (short for “key symbol”) is a numeric encoding of a
84 symbol on the cap of a key.
86 They have a canonical name for convenience. It can be:
88 - A _character:_ e.g. `a` and `A` for Latin scripts,
89 `alpha` “α” and `ALPHA` “Α” for Greek, etc.
90 - A _dead key:_ e.g. `dead_grave` and `dead_diaeresis`, corresponding
91 respectively to the [grave accent](https://en.wikipedia.org/wiki/Grave_accent)
92 and the [diaeresis](https://en.wikipedia.org/wiki/Diaeresis_%28diacritic%29)
95 A [dead key](https://en.wikipedia.org/wiki/Dead_key) is a special kind of key
96 that does not generate a character by itself, but modifies the character
97 generated by the key struck(s) immediately after.
98 - A <em>[modifier]:</em> e.g. `Shift_L`, `Control_R`, `Caps_Lock`.
100 - A _system action:_ e.g. the arrow `Left`, `Pause`, `Escape`, `F1`.
102 The complete list of keysyms is defined in `xkbcommon/xkbcommon-keysyms.h`.
104 See [xkb_symbols] for further details on binding keysyms to keycodes.
106 <dt><a name="modifier-def">Modifier</a></dt>
108 A _modifier key_ is a key that modifies the effect of other keys:
109 e.g. Shift, Control, Caps Lock, etc.
111 The state of a modifier key (active/inactive) is encoded as a
112 _modifier index_ (or modifier bit or simply modifier) and has
113 an associated _unique name_.
115 For historical reasons, modifiers are divided in two categories:
118 <dt><a name="real-modifier-def">Real modifiers</a></dt>
120 They are the 8 _predefined_ (AKA core, X11) modifiers
121 (see [usual modifiers] hereinafter).
123 Real modifiers ensure backward compatibility: indeed
124 they are the actual bits used to compute the [levels][level]
125 and are communicated via the API of xkbcommon.
127 Some are generic modifiers (`Mod[1-5]`) that do not have a
128 conventional interpretation and are the motivation of the
129 introduction of [virtual modifiers].
131 <dt><a name="virtual-modifier-def">Virtual modifiers</a>
133 They are the modifiers that are _not_ predefined.
137 Each modifier defines a _mapping_ to one or multiple
138 _real_ modifier. Real modifiers map to themselves.
140 The following table lists the
141 <a name="usual-modifiers">usual modifiers</a>
142 present in the [standard keyboard configuration][xkeyboard-config].
143 Note that this is provided for information only, as it may change
144 depending on the user configuration.
146 | Modifier | Type | Usual mapping | Comment |
147 | ------------ | ------- | ------------- | --------------------------- |
148 | `Shift` | Real | `Shift` | The usual [Shift] |
149 | `Lock` | Real | `Lock` | The usual [Caps Lock][Lock] |
150 | `Control` | Real | `Control` | The usual [Control] |
151 | `Mod1` | Real | `Mod1` | Not conventional |
152 | `Mod2` | Real | `Mod2` | Not conventional |
153 | `Mod3` | Real | `Mod3` | Not conventional |
154 | `Mod4` | Real | `Mod4` | Not conventional |
155 | `Mod5` | Real | `Mod5` | Not conventional |
156 | `Alt` | Virtual | `Mod1` | The usual [Alt] |
157 | `Meta` | Virtual | `Mod1` or `Mod4` | The legacy [Meta] key |
158 | `NumLock` | Virtual | `Mod2` | The usual [NumLock] |
159 | `Super` | Virtual | `Mod4` | The usual [Super]/GUI |
160 | `LevelThree` | Virtual | `Mod3` | [ISO][ISO9995] level 3, aka [AltGr] |
161 | `LevelFive` | Virtual | `Mod5` | [ISO][ISO9995] level 5 |
163 [usual modifiers]: @ref usual-modifiers
164 [Shift]: https://en.wikipedia.org/wiki/Control_key
165 [Lock]: https://en.wikipedia.org/wiki/Caps_Lock
166 [Control]: https://en.wikipedia.org/wiki/Control_key
167 [Alt]: https://en.wikipedia.org/wiki/Alt_key
168 [AltGr]: https://en.wikipedia.org/wiki/AltGr_key
169 [NumLock]: https://en.wikipedia.org/wiki/Num_Lock
170 [Meta]: https://en.wikipedia.org/wiki/Meta_key
171 [Super]: https://en.wikipedia.org/wiki/Super_key_(keyboard_button)
173 A modifier key can report its state in one of the following 3 ways:
176 <dt><a name="depressed-mod-def">Depressed</a></dt>
177 <dd>Active while depressed; e.g. the usual Shift.</dd>
178 <dt><a name="latched-mod-def">Latched</a></dt>
180 Activated when pressed and deactivated after the next
181 non-modifier key press.
183 <dt><a name="locked-mod-def">Locked</a></dt>
185 Activated when pressed and deactivated when pressed again;
186 e.g. the usual Caps Lock.
190 See [modifiers bindings] for further details.
193 [depressed]: @ref depressed-mod-def
194 [latched]: @ref latched-mod-def
195 [locked]: @ref locked-mod-def
197 <dt><a name="level-def">Shift Level</a></dt>
199 A key may produce different
200 results depending of the active modifiers: e.g. for a Latin script,
201 pressing the key A produces “a” and holding Shift while pressing A
204 This various results are organized in an ordered list; the _index_
205 of each entry is called a <a name="level-index-def">shift level</a>
206 or simply level. By convention the lowest level is the result when
207 no modifier is active.
208 Example for the key `A` on latin script keyboard:
210 | Level | Description | Keysym | Active key modifiers |
211 |-------|--------------------------------|--------|----------------------|
212 | 1 | Lower case letters | `a` | None |
213 | 2 | Upper case letters. | `A` | `Shift` |
214 | 3 | Alternative lower case letters | `ae` | `AltGr` |
215 | 4 | Alternative upper case letters | `AE` | `Shift` + `AltGr` |
217 A key shift level is the logical _state_ of a key corresponding to
218 the current shift level it used.
220 Key shift levels are derived from the modifiers states, but not
221 necessarily in the same way for all keys. For example, for Latin
222 script the Caps Lock modifier selects the level 2 for alphabetic
223 keys such as `A` but has no effect on a numeric key.
225 There are groups of keys with the same characteristics: letters,
226 punctuation, numeric keypad, etc. The meaning of their levels is
227 identical and thus can be shared: this generalization is called
228 a _key type_ (see hereinafter).
230 <dt><a name="key-type-def">Key type</a></dt>
232 A key type defines the levels available for a key and
233 how to derive the active level from the modifiers states. Examples:
234 - `ONE_LEVEL`: the key has only one level, i.e. it is not affected
235 by any modifiers. Example: the modifiers themselves.
236 - `TWO_LEVEL`: the key has two levels:
237 - Level 1: default level, active when the `Shift` modifier is _not_ active.
238 - Level 2: level activated with the `Shift` modifier.
239 - `FOUR_LEVEL`: see the example in the previous section.
241 See [xkb_types] for further details.
243 <dt><a name="layout-def">Layout</a></dt>
245 A mapping of keycodes to symbols, actions and key types.
247 A user who deals with multiple languages may need two or more
248 different layouts: e.g. a layout for Arabic and another one for
249 English. In this context, layouts are called _groups_ in XKB,
250 as defined in the [standard ISO/IEC 9995][ISO9995].
252 Layouts are ordered and identified by their index. Example:
258 <dt><a name="key-action-def">Key Action</a></dt>
260 In XKB world, a key action defines the effect a key
261 has on the state of the keyboard or the state of the display server.
264 - Change the state of a modifier.
265 - Change the active group.
266 - Move the mouse pointer.
268 See the section “[Key actions][actions]” for further details.
270 <dt><a name="indicator-def">Indicator</a></dt>
272 A keyboard indicator is a mean to report a specific aspect of the
276 <dt><em>Physical</em> indicator</dt>
278 Typically a labelled LED on the keyboard, e.g. “Caps Lock” and
281 <dt><em>Logical</em> indicator</dt>
283 A customizable derived state of the keyboard.
284 Its changes creates events that can be monitored.
286 There are two categories:
288 - _Real_ indicators are those associated to a physical indicator.
289 For example, the “Caps Lock” logical modifier controls the
290 corresponding physical LED.
292 Because indicators are customizable, if one misses a “Num Lock”
293 LED, one could define instead the “Caps Lock” _indicator_ to
294 activate its LED when the “Num Lock” _modifier_ is active.
295 - _Virtual_ indicators are not associated to a physical indicator.
296 Their effect is only visible for programs monitoring them.
298 Note that the meanings of _real_ and _virtual_ is slightly
299 different than the one used for [modifier].
303 See: <code>[xkb_keycodes][indicator name]</code> to define indicators and
304 <code>[xkb_compat][indicator effect]</code> to define their effects.
306 <dt><a name="keymap-def">Keymap</a></dt>
308 The _complete_ definition of the
309 mapping of raw keycodes to symbols and actions.
310 It fully defines the behavior of a keyboard.
312 See [xkb_keymap] for further details.
316 [keycode]: @ref keycode-def
317 [keysym]: @ref keysym-def
318 [keysyms]: @ref keysym-def
319 [modifier]: @ref modifier-def
320 [modifiers]: @ref modifier-def
321 [real modifier]: @ref real-modifier-def
322 [real modifiers]: @ref real-modifier-def
323 [virtual modifier]: @ref virtual-modifier-def
324 [virtual modifiers]: @ref virtual-modifier-def
325 [level]: @ref level-def
326 [shift level]: @ref level-def
327 [level index]: @ref level-index-def
328 [key type]: @ref key-type-def
329 [key types]: @ref key-type-def
330 [layout]: @ref layout-def
331 [action]: @ref key-action-def
332 [indicator]: @ref indicator-def
333 [keymap]: @ref keymap-def
334 [ISO9995]: https://en.wikipedia.org/wiki/ISO/IEC_9995
337 ## Introduction to the XKB text format {#introduction}
339 The XKB text format uses a syntax similar to the [C programming language][C].
341 @todo general comment on syntax: section, values, etc.
343 @todo the import mechanism
345 @todo recommended ways to feed xkbcommon
347 [C]: https://en.wikipedia.org/wiki/C_(programming_language)#Syntax
351 @todo keywords, other settings such as “SetMods”
354 TODO: SetMods is not a keyword, but how call it for using-facing doc?
356 There are many keywords
358 The key words are _case-insensitive_, e.g. the following strings denote
359 the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`.
365 <dt>String literal</dt>
367 A string is surrounded by double quotes: “<code>"</code>”.
368 The following _escape sequences_ are supported:
370 | Escape sequence | Meaning |
371 | ------------------ | ------------------------------------------------------- |
372 | `\\` | Backslash “`\`” |
376 | `\n` | Line feed (newline) |
377 | `\r` | Carriage return |
378 | `\t` | Horizontal tabulation |
379 | `\v` | Vertical tabulation |
380 | `\` + octal number | Corresponding ASCII character: `\0` → NULL, `\42` → `"` |
382 @note The string _encoding_ is unspecified and not validated, but for best
383 results, stick to ASCII.
385 <!-- TODO: check UTF-8 encoding result -->
388 <dt>Number literal</dt>
390 A number can be written in three forms:
392 - _decimal integer:_ `1`, `123`, etc.
393 - _decimal floating-point number:_ `1.23`, etc.
394 - _hexadecimal integer:_ prefixed with `0x`: `0x123`, `0xff`, `0xAB`, etc.
399 ## The “xkb_keymap” block {#the-xkb_keymap-block}
401 A <strong>[keymap]</strong> consists of a single top-level `xkb_keymap`
402 block, under which are nested the following sections:
405 <dt><code>[xkb_keycodes]</code></dt>
407 A translation of the hardware/evdev scancodes from the keyboard into
408 XKB symbolic keycodes.
410 <dt><code>[xkb_types]</code></dt>
412 A specification of the modifier mask, target level and preserved
413 modifiers various modifiers combination produce.
415 <dt><code>[xkb_compat]</code></dt>
417 A specification of what actions various special-purpose keys produce.
419 <dt><code>[xkb_symbols]</code></dt>
421 A translation of symbolic key codes into actual symbols and actions.
425 Overview of a keymap file:
435 xkb_compatibility "XXX" {
444 ## The “xkb_keycodes” section {#the-xkb_keycodes-section}
446 This is the simplest section type, and is the first one to be
447 compiled. The purpose of this is mostly to map between the
448 hardware/evdev scancodes and XKB [keycodes]. Each key is given a name
449 by which it can be referred to later, e.g. in the symbols section.
451 ### Keycode statements
453 Statements of the form:
458 The above would let 49 and 10 be valid keycodes in the keymap, and
459 assign them the names `TLDE` and `AE01` respectively. The format
460 `<WXYZ>` is always used to refer to a key by name.
462 The naming convention `<AE01>` is based on the
463 [standard ISO/IEC 9995-1][ISO9995-1]. It denotes the position of the
464 key in the keyboard grid. It means: the main alphanumeric section
465 (`A`), row `E` and column `01`.
467 The following figure illustrates the grid on a staggered standard
468 US QWERTY keyboard. `<AE01>` corresponds to the key `1`.
471 \ 99 \ 00 \ 01 \ 02 \ 03 \ 04 \ 05…
473 -----------------------------------------
474 E \ \ ^ \ 1 \ 2 \ 3 \ 4 \ 5…
475 ------------------------------------------
476 D \ Tab \ Q \ W \ E \ R \ T…
477 -------------------------------------------
478 C \Caps \ A \ S \ D \ F \ G…
479 --------------------------------------------
480 B \Shift \ Z \ X \ C \ V \ B…
481 ---------------------------------------------
482 A \Ctrl\GUI \Alt \Space…
483 ----------------------------------------------
486 [ISO9995-1]: https://en.wikipedia.org/wiki/ISO/IEC_9995#ISO/IEC_9995-1
488 In the common case this just maps to the evdev scancodes from
489 `/usr/include/linux/input.h`, e.g. the following definitions:
494 correspond to the ones above. Similar definitions appear in the
495 xf86-input-keyboard driver. Note that in all current keymaps there's a
496 constant offset of 8 (for historical reasons).
498 Note that contrary to xkbcommon, the X11 protocol supports keycodes
499 only up to `255`. Therefore, when interfacing with X11, keymaps and applications
500 using keycodes beyond `255` should expect warnings.
502 If there's a conflict, like the same name given to different keycodes,
503 or same keycode given different names, it is resolved according to the
504 merge mode which applies to the definitions.
508 Statements of the form:
510 alias <MENU> = <COMP>;
512 Allows to refer to a previously defined key (here `<COMP>`) by another
513 name (here `<MENU>`). Conflicts are handled similarly to keycode
516 ### LED name statements {#indicator-name}
518 [indicator name]: @ref indicator-name
520 Statements of the form:
522 indicator 1 = "Caps Lock";
523 indicator 2 = "Num Lock";
524 indicator 3 = "Scroll Lock";
526 Assigns a name to the keyboard LED (AKA [indicator]) with the given
527 index. The LED may be referred by this name later in the compat
528 section and by the user.
531 ## The “xkb_types” section {#the-xkb_types-section}
533 This section is the second to be processed, after `xkb_keycodes`.
534 However, it is completely independent and could have been the first to
535 be processed (it does not refer to specific keys as specified in the
536 `xkb_keycodes` section).
538 This section defines [key types], which, given a key and a keyboard
539 state (i.e. modifier state and group), determine the [shift level] to
540 be used in translating the key to [keysyms]. These types are assigned to
541 each group in each key, in the `xkb_symbols` section.
543 Key types are called this way because, in a way, they really describe
544 the "type" of the key (or more correctly, a specific group of the
545 key). For example, an ordinary keymap will provide a type called
546 `KEYPAD`, which consists of two levels, with the second level being
547 chosen according to the state of the Num Lock (or Shift) modifiers.
548 Another example is a type called `ONE_LEVEL`, which is usually
549 assigned to keys such as Escape; these have just one level and are not
550 affected by the modifier state. Yet more common examples are
551 `TWO_LEVEL` (with Shift choosing the second level), `ALPHABETIC`
552 (where Caps Lock may also choose the second level), etc.
556 Statements of the form:
558 type "FOUR_LEVEL" { ... }
560 The above would create a new type named `FOUR_LEVEL`.
561 The body of the definition may include statements of the following
564 #### “level_name” statements
566 level_name[Level1] = "Base";
568 Mandatory for each level in the type.
570 Gives each level in this type a descriptive name. It isn't used
573 Note: A level may be specified as Level\[1-8\] or just a number (can
576 #### “modifiers” statement
578 modifiers = Shift+Lock+LevelThree;
580 Mandatory, should be specified only once.
582 A mask of real and virtual [modifiers]. These are the only modifiers
583 being considered when matching the modifier state against the type.
584 The other modifiers, whether active or not, are masked out in the
587 #### “map” entry statements
589 map[Shift+LevelThree] = Level4;
591 Should have at least as many mappings as there are levels in the type.
593 If the active modifiers, masked with the type's modifiers (as stated
594 above), match (i.e. equal) the modifiers inside the `map[]` statement,
595 then the level in the right hand side is chosen. For example, in the
596 above, if in the current keyboard state the `Shift` and `LevelThree`
597 modifiers are active, while the `Lock` modifier is not, then the
598 keysym(s) in the 4th level of the group will be returned to the user.
600 #### “preserve” statements
602 map[Shift+Lock+LevelThree] = Level5;
603 preserve[Shift+Lock+LevelThree] = Lock;
605 When a key type is used for keysym translation, its modifiers are said
606 to be "consumed". For example, in a simple US keymap, the "g" "g" key
607 is assigned an ordinary `ALPHABETIC` key type, whose modifiers are
608 Shift and Lock; then for the "g" key, these two modifiers are consumed
609 by the translation. This information is relevant for applications
610 which further process the modifiers, since by then the consumed
611 modifiers have already "done their part" and should be masked out.
613 However, sometimes even if a modifier had already affected the key
614 translation through the type, it should *not* be reported as consumed,
615 for various reasons. In this case, a `preserve[]` statement can be
616 used to augment the map entry. The modifiers inside the square
617 brackets should match one of the map[] statements in the type (if
618 there is no matching map entry, one mapping to Level1 is implicitly
619 added). The right hand side should consists of modifiers from the
620 type's modifiers; these modifiers are then "preserved" and not
621 reported as consumed.
624 ## The “xkb_compat” section {#the-xkb_compat-section}
626 This section is the third to be processed, after `xkb_keycodes` and
629 ### Interpret statements {#interpret-statements}
631 Statements of the form:
633 interpret Num_Lock+Any { ... }
634 interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
636 The <code>[xkb_symbols]</code> section (see below)
637 allows the keymap author to perform, among other things, the following
640 - Bind an [action], like `SetMods` or `LockGroup`, to the key.
641 Actions, like symbols, are specified for each level of each group
642 in the key separately.
644 - Add a [virtual modifier] to the key's virtual modifier mapping
647 - Specify whether the key should repeat or not.
649 However, doing this for each key (or level) is tedious and inflexible.
650 Interpret's are a mechanism to apply these settings to a bunch of
653 Each interpret specifies a condition by which it attaches to certain
654 levels. The condition consists of two parts:
656 - A <strong>[keysym]</strong>. If the level has a different (or more than one)
657 keysym, the match fails. Leaving out the keysym is equivalent to using the
658 special value `Any` or the `NoSymbol` keysym, which always matches
661 - A <strong>[modifier] predicate</strong>. The predicate consists of:
662 - A __mask__ of _real_ modifiers: a `+`-separated list of modifiers or
663 the special value `all`, which denotes all the modifiers.
665 The modifiers are matched against the key's modifier map (`modmap`).
666 - A __matching operation__, that is one of the following:
668 * `AnyOfOrNone` – The modmap must either be empty or include at
669 least one of the specified modifiers.
670 * `AnyOf` – The modmap must include at least one of the specified
672 * `Any` – Alias for `AnyOf(all)`.
673 * `NoneOf` – The modmap must not include any of the specified
675 * `AllOf` – The modmap must include all of the specified modifiers
676 (but may include others as well).
677 * `Exactly` – The modmap must be exactly the same as the specified
680 Leaving out the predicate is equivalent to using `AnyOfOrNone(all)`.
681 Leaving out just the matching condition is equivalent to using
684 An interpret may also include `useModMapMods = level1;` – see below.
686 If a [level] fulfils the conditions of several interprets, only the
687 most specific one is used:
689 - A specific keysym will always match before a generic `NoSymbol`
692 - If the keysyms are the same, the interpret with the more specific
693 matching operation is used. The above list is sorted from least to
696 - If both the keysyms and the matching operations are the same (but the
697 modifiers are different), the first interpret is used.
699 As described above, once an interpret "attaches" to a level, it can bind
700 an action to that level, add one virtual modifier to the key's vmodmap,
701 or set the key's repeat setting. You should note the following:
703 - The key repeat is a property of the entire key; it is not
704 level-specific. In order to avoid confusion, it is only inspected
705 for the first level of the first group; the interpret's repeat
706 setting is ignored when applied to other levels.
708 - If one of the above fields was set directly for a key in
709 `xkb_symbols`, the explicit setting takes precedence over the
712 The body of the statement may include statements of the following
713 forms (all of which are optional):
715 #### “useModMapMods” statement
717 useModMapMods = level1;
719 When set to `level1`, the interpret will only match keysyms which are
720 on the first level of the first group of the keys. This can be useful
721 in conjunction with e.g. a `virtualModifier` statement, because
722 `virtualModifier` is an attribute of the key rather than a specific
725 Note: the other possible value is `any` and is the default value.
727 #### “action” statement
729 action = LockMods(modifiers=NumLock);
731 Bind this action to the matching levels. See [key actions][actions]
732 for the list of available key actions.
734 #### “virtualModifier” statement
736 virtualModifier = NumLock;
738 Add this virtual modifier to the key's `vmodmap`. The given virtual
739 modifier must be declared at the top level of the file with a
740 `virtual_modifiers` statement, e.g.:
742 virtual_modifiers NumLock;
744 #### “repeat” statement
748 Set whether the key should repeat or not. Must be a boolean value.
750 ### LED map statements {#indicator-effect}
752 [indicator effect]: @ref indicator-effect
754 Statements of the form:
756 indicator "Shift Lock" { ... }
758 This statement specifies the behavior and binding of the LED (AKA
759 [indicator]) with the given name ("Shift Lock" above). The name should
760 have been declared previously in the `xkb_keycodes` section (see
761 [LED name][indicator name] statement), and given an index there.
762 If it wasn't, it is created with the next free index.
764 The body of the statement describes the conditions of the keyboard
765 state which will cause the LED to be lit. It may include the following
768 #### “modifiers” statement
770 modifiers = ScrollLock;
772 If the given [modifiers] are in the required state (see below), the
775 #### “whichModState” statement
777 whichModState = Latched+Locked;
779 Can be any combination of:
781 * `base`, `latched`, `locked`, `effective`
782 * `any` (i.e. all of the above)
783 * `none` (i.e. none of the above)
784 * `compat` (legacy value, treated as effective)
786 This will cause the respective portion of the modifier state (see
787 `struct xkb_state`) to be matched against the modifiers given in the
788 `modifiers` statement.
790 Here's a simple example:
792 indicator "Num Lock" {
794 whichModState = Locked;
797 Whenever the NumLock modifier is locked, the Num Lock LED will light
800 #### “groups” statement
802 groups = All - group1;
804 If the given groups are in the required state (see below), the LED is
807 #### “whichGroupState” statement
809 whichGroupState = Effective;
811 Can be any combination of:
813 * `base`, `latched`, `locked`, `effective`
814 * `any` (i.e. all of the above)
815 * `none` (i.e. none of the above)
817 This will cause the respective portion of the group state (see
818 `struct xkb_state`) to be matched against the groups given in the
821 Note: the above conditions are disjunctive, i.e. if any of them are
822 satisfied the LED is lit.
826 @todo e.g. `setMods.clearLocks= True;`
829 ## The “xkb_symbols” section {#the-xkb_symbols-section}
831 @todo complete this section.
833 This section is the fourth to be processed, after `xkb_keycodes`,
834 `xkb_types` and `xkb_compat`.
836 Statements of the form:
838 xkb_symbols "basic" {
842 Declare a symbols map named `basic`. Statements inside the curly braces only
843 affect the symbols map.
845 A map can have various flags applied to it above the statement, separated by
848 partial alphanumeric_keys
849 xkb_symbols "basic" {
853 The possible flags are:
855 * `partial` - Indicates that the map doesn't cover a complete keyboard.
856 * `default` - Marks the symbol map as the default map in the file when no
857 explicit map is specified. If no map is marked as a default, the first map
858 in the file is the default.
859 * `hidden` - Variant that can only be used internally
860 * `alphanumeric_keys` - Indicates that the map contains alphanumeric keys
861 * `modifier_keys` - Indicates that the map contains modifier keys
862 * `keypad_keys` - Indicates that the map contains keypad keys
863 * `function_keys` - Indicates that the map contains function keys
864 * `alternate_group` - Indicates that the map contains keys for an alternate
867 If no `*_keys` flags are supplied, then the map is assumed to cover a complete
870 At present, except for `default`, none of the flags affect key processing in
871 libxkbcommon, and only serve as metadata.
875 Statements of the form:
877 name[Group1] = "US/ASCII";
878 groupName[1] = "US/ASCII";
880 Gives the name "US/ASCII" to the first group of symbols. Other groups can be
881 named using a different group index (ex: `Group2`), and with a different name.
882 A group must be named.
884 `group` and `groupName` mean the same thing, and the `Group` in `Group1` is
887 ### Include statements
889 Statements of the form:
891 include "nokia_vndr/rx-51(nordic_base)"
893 Will include data from another `xkb_symbols` section, possibly located in
894 another file. Here it would include the `xkb_symbols` section called
895 `nordic_base`, from the file `rx-51` located in the `nokia_vndr` folder, itself
896 located in an XKB include path.
900 Statements of the form:
902 key <AD01> { [ q, Q ] };
904 Describes the mapping of a keycode `<AD01>` to a given group of symbols. The
905 possible keycodes are the keycodes defined in the `xkb_keycodes` section.
907 Symbols are named using the symbolic names from the
908 `xkbcommon/xkbcommon-keysyms.h` file. A group of symbols is enclosed in brackets
909 and separated by commas. Each element of the symbol arrays corresponds to a
910 different modifier level. In this example, the symbol (keysym) `XKB_KEY_q` for
911 level 1 and `XKB_KEY_Q` for level 2.
915 @todo how to bind key actions
917 For further details see [key actions][actions].
921 Each group represents a list of symbols mapped to a keycode:
923 name[Group1]= "US/ASCII";
924 name[Group2]= "Russian";
926 key <AD01> { [ q, Q ],
927 [ Cyrillic_shorti, Cyrillic_SHORTI ] };
929 A long-form syntax can also be used:
932 symbols[Group1]= [ q, Q ],
933 symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
936 Groups can also be omitted, but the brackets must be present. The following
937 statement only defines the Group3 of a mapping:
939 key <AD01> { [], [], [ q, Q ] };
941 #### Additional attributes
943 @todo virtualmodifiers, repeats
945 ## Virtual modifier statements {#virtual-modifier-statements}
947 @todo rework this section
949 Statements of the form:
951 virtual_modifiers LControl;
953 Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections.
955 ## Modifiers bindings {#modifiers-bindings}
957 ### Real and virtual modifiers
959 Modifiers are a particularly tricky part of XKB. For historical reasons they are
960 divided in two categories: [real modifiers] and [virtual modifiers].
962 Note that in X11, the maximum of virtual modifiers is 16
963 (see `XkbNumVirtualMods`).
965 The following table summarizes the modifiers defined
966 in <code>[xkeyboard-config]</code> (this is subject to change).
968 | Modifier | Type | Compat files | Associated keysyms |
969 |--------------|---------|------------------|----------------------|
970 | `Shift` | Real | `compat/basic` | `Shift_L`, `Shift_R` |
971 | ″ | ″ | `compat/iso9995` | `Shift_L`, `Shift_R`, `ISO_Level2_Latch` |
972 | `Lock` | Real | `compat/basic`, | `Caps_Lock` |
973 | ″ | ″ | `compat/caps` | ″ |
974 | `Control` | Real | `compat/basic` | `Control_L`, `Control_R` |
975 | `Alt` | Virtual | `compat/misc`, | `Alt_L`, `Alt_R` |
976 | ″ | ″ | `compat/pc` | ″ |
977 | `Meta` | Virtual | `compat/misc` | `Meta_L`, `Meta_R` |
978 | `Super` | Virtual | `compat/misc` | `Super_L`, `Super_R` |
979 | `Hyper` | Virtual | `compat/misc` | `Hyper_L`, `Hyper_R` |
980 | `ScrollLock` | Virtual | `compat/misc` | `Scroll_Lock` |
981 | `NumLock` | Virtual | `compat/basic`, | `Num_Lock`, |
982 | ″ | ″ | `compat/level5` | (`ISO_Level5_Lock`) |
983 | `LevelThree` | Virtual | `compat/iso9995` | `ISO_Level3_Shift`, `ISO_Level3_Latch`, `ISO_Level3_Lock` |
984 | `LevelFive` | Virtual | `compat/level5` | `ISO_Level5_Shift`, `ISO_Level5_Latch`, `ISO_Level5_Lock` |
985 | `Kana_Lock` | Virtual | `compat/japan` | `Kana_Lock` |
986 | `Square` | Virtual | `compat/olpc` | `KP_Home` |
987 | `Cross` | Virtual | `compat/olpc` | `KP_Next` |
988 | `Circle` | Virtual | `compat/olpc` | `KP_End` |
989 | `Triangle` | Virtual | `compat/olpc` | `KP_Prior` |
991 ### Define and use a modifier
993 We will use the example of the _real_ modifier `Shift` and the virtual
994 modifier `LevelThree` in `xkeyboard-config`.
996 In order to define and use a modifier, one must:
998 1. Define its behavior and [keysym] binding in the
999 <code>[xkb_compat]</code> section:
1002 // Declare virtual modifiers. Shift being real modifier,
1003 // we do not need to add it here.
1004 virtual_modifiers LevelThree;
1006 // Set defaults. They are overridden if set directly in the xkb_symbols.
1007 interpret.repeat= False; // only applied on first level
1008 setMods.clearLocks= True;
1009 latchMods.clearLocks= True;
1010 latchMods.latchToLock= True;
1012 // Default statement for real modifiers: any key bound to a real
1013 // modifier via modifier_map will set this modifier at all its
1015 // Here only to illustrate: do not add it!
1016 interpret Any + Any {
1017 action= SetMods(modifiers=modMapMods);
1020 // Shift being real modifier, we do not need a corresponding
1021 // interpret statement because the previous one suffices.
1023 // Let’s associate LevelThree to the keysym ISO_Level3_Shift
1025 // First, match the keys and their levels with the
1026 // ISO_Level3_Shift keysym and with any real modifier
1027 // (Any = AnyOf(all)) in its modmap.
1028 interpret ISO_Level3_Shift+Any {
1029 // Only match the first level of the first group
1030 useModMapMods= level1;
1031 // Add the virtual modifier to the key’s vmodmap
1032 virtualModifier= LevelThree;
1033 // Activate the LevelThree modifier (depressed mode)
1034 action= SetMods(modifiers=LevelThree);
1037 // Then for keys and their levels with the
1038 // ISO_Level3_Shift keysym but with either no real modifier
1039 // in its modmap or a level higher than 1.
1041 // • In case the level is higher than 1 there is no match
1042 // in the previous statement.
1043 // • The condition is equivalent to
1044 // ISO_Level3_Shift+AnyOfOrNone(all), but since
1045 // the previous statement ISO_Level3_Shift+Any is more
1046 // specific, it will be matched before this one.
1047 interpret ISO_Level3_Shift {
1048 // Activate the LevelThree modifier (depressed mode)
1049 action= SetMods(modifiers=LevelThree);
1053 2. Define [key types] that use it in the
1054 <code>[xkb_types]</code> section:
1057 // Declare virtual modifiers. Shift being real modifier,
1058 // we do not need to add it here.
1059 virtual_modifiers LevelThree;
1062 // Key type modifier mask: all the modifiers used in the key type
1063 modifiers = Shift + LevelThree;
1065 map[Shift] = Level2;
1066 map[LevelThree] = Level3;
1067 map[Shift+LevelThree] = Level4;
1068 level_name[Level1] = "Base";
1069 level_name[Level2] = "Shift";
1070 level_name[Level3] = "AltGr";
1071 level_name[Level4] = "Shift AltGr";
1075 3. Bind it to a [keycode] in the
1076 <code>[xkb_symbols]</code> section:
1078 1. Map [keysyms] used in the `xkb_compat` section hereinabove.
1079 2. Bind [real modifiers] to keys using these keysyms with
1082 _Note:_ Only one key binding to real modifier is required.
1083 The corresponding keysym must then be on the first level of
1086 _Note:_ One can optionally bind directly a virtual modifier to a
1087 key using `virtualmodifiers` instead of doing it in the
1088 `xkb_compat` section. But the recommended way is to use the
1089 `xkb_compat` section.
1092 // Shift: defined in pc symbols
1093 key <LFSH> {[ Shift_L ]};
1094 key <RTSH> {[ Shift_R ]};
1095 modifier_map Shift { Shift_L, Shift_R };
1096 // The previous will resolve to:
1097 // modifier_map Shift { <LFSH>, <RTSH> };
1098 // Thus the real modifier Shift is added to the modmap of
1099 // <LFSH> and <RTSH>.
1100 // The “Any + Any” interpret statement matches <LFSH> and <RTSH>,
1101 // therefore these keys set the Shift modifier.
1103 // LevelThree: defined in pc symbols
1104 // With the following 2 lines:
1105 // 1. The modifier keysym is on the first level of the first group.
1106 // 2. The real modifier Mod5 is bound to <LVL3>,
1107 // i.e. Mod5 is added to its modmap.
1108 // 3. It matches the interpret statement “ISO_Level3_Shift+Any”,
1109 // which adds the LevelThree modifier to the vmodmap of <LVL3>.
1110 // 4. The mapping of LevelThree to real modifiers is the union
1111 // of modmaps with corresponding vmodmaps containing
1112 // LevelThree. In our case there is only one: therefore
1113 // LevelThree maps to Mod5.
1114 key <LVL3> {[ ISO_Level3_Shift ]};
1115 modifier_map Mod5 { <LVL3> };
1117 // LevelThree: defined in level3 symbols
1118 // Not bound to a real modifier, so interpret statement
1119 // “ISO_Level3_Shift” applies.
1120 key <RALT> {[ISO_Level3_Shift], type[group1]="ONE_LEVEL" };
1122 // Note: we could have the following line, but it is not necessary
1123 // because we have the mappings of <LVL3>.
1124 // modifier_map Mod5 { <RALT> };
1126 // Warning: if we had the for example the following line, the
1127 // mapping of LevelThree to real modifiers would be “Mod1+Mod5”.
1128 // modifier_map Mod1 { <RALT> };
1130 // Alternative definitions, without using interpret statements
1131 virtual_modifiers LevelThree;
1132 key <LVL3> { virtualmodifiers=LevelThree
1134 , symbols[Group1] = [ISO_Level3_Shift]
1135 , actions[Group1] = [SetMods(modifiers=LevelThree)] };
1136 modifier_map Mod5 { <LVL3> };
1137 key <RALT> { repeat=False
1138 , symbols[Group1] = [ISO_Level3_Shift]
1139 , actions[Group1] = [SetMods(modifiers=LevelThree)]
1140 , type[group1]="ONE_LEVEL" };
1142 // FOUR_LEVEL key type example from latin symbols
1143 key <AB05> {[b, B, leftdoublequotemark, leftsinglequotemark]};
1146 ## Key actions {#key-actions}
1148 @todo list of all actions and their parameters
1150 The following table provide an overview of the available actions:
1152 | Category | Action | Alias | Description |
1153 |----------|---------------------|------------------|------------------------------------|
1154 | | `NoAction` | | Do nothing. |
1155 | [Modifier action] | `SetMods` | | Modifies the _depressed_ modifiers |
1156 | ^ | `LatchMods` | | Modifies the _latched_ modifiers |
1157 | ^ | `LockMods` | | Modifies the _locked_ modifiers |
1158 | [Group action] | `SetGroup` | | <span class="todo">TODO</span> |
1159 | ^ | `LatchGroup` | | <span class="todo">TODO</span> |
1160 | ^ | `LockGroup` | | <span class="todo">TODO</span> |
1161 | [Legacy action] | `MovePointer` | `MovePtr` | <span class="todo">TODO</span> |
1162 | ^ | `PointerButton` | `PtrBtn` | <span class="todo">TODO</span> |
1163 | ^ | `LockPointerButton` | `LockPtrBtn` | <span class="todo">TODO</span> |
1164 | ^ | `SetPointerDefault` | `SetPtrDflt` | <span class="todo">TODO</span> |
1165 | ^ | `SetControls` | | <span class="todo">TODO</span> |
1166 | ^ | `LockControls` | | <span class="todo">TODO</span> |
1167 | ^ | `TerminateServer` | `Terminate` | <span class="todo">TODO</span> |
1168 | ^ | `SwitchScreen` | | <span class="todo">TODO</span> |
1169 | ^ | `Private` | | <span class="todo">TODO</span> |
1173 - `true`, `yes`, `on`
1174 - `false`, `no`, `off`
1176 ### Modifiers actions {#modifiers-actions}
1178 [modifier action]: @ref modifiers-actions
1180 @todo default values
1182 There are 3 modifiers actions:
1187 Modifies the _depressed_ modifiers.
1190 - `modifiers` or `mods`: the list of modifiers to modify,
1191 separated by `+`, or the special value `modMapMods`. The latter
1192 means the parameter value has to be read from the `vmodmap`
1193 attribute of the key.
1194 - `clearLocks`: boolean (see its use hereinafter).
1196 <dt>`LatchMods`</dt>
1198 Modifies the _latched_ modifiers
1201 - `modifiers` or `mods`: see `SetMods`.
1202 - `clearLocks`: boolean (see its use hereinafter).
1203 - `latchToLock`: boolean (see its use hereinafter).
1207 Modifies the _locked_ modifiers.
1210 - `modifiers` or `mods`: see `SetMods`.
1212 - `lock`: the action only locks the modifier, but cannot unlock it.
1213 - `unlock`: the action only unlocks modifier, but cannot lock it.
1214 - `both`: the first key press locks the modifier and the second key
1215 press releases the modifier. It is a default mode.
1216 - `neither`: do not lock nor unlock, i.e. do nothing.
1220 @todo highlight that there is reference counting for
1221 the modifiers, e.g. to manage multiple physical keys for the same modifier.
1223 These actions perform different tasks on key press and on key release:
1227 Effects of modifiers actions
1232 <th>On key press</th>
1233 <th>On key release</th>
1238 <th><code>SetMods</code></th>
1241 <li>Adds modifiers to <em>depressed</em> modifiers</li>
1247 Removes modifiers from <em>depressed</em> modifiers,
1248 provided that no other key which affects the same
1249 modifiers is logically down.
1252 If <code>clearLocks=yes</code> and no other key
1253 were operated simultaneously with this key,
1254 then the modifiers will be removed as well from
1255 the <em>locked</em> modifiers.
1261 <th><code>LatchMods</code></th>
1264 <li>Adds modifiers to <em>latched</em> modifiers.</li>
1269 <li>Removes modifiers from <em>latched</em> modifiers.</li>
1271 If <code>clearLocks=yes</code> and no other key
1272 has been pressed since this key press, then the
1273 modifiers will be removed as well from the
1274 <em>locked</em> modifiers.
1277 If <code>latchToLock=yes</code> then the modifiers
1278 are added to the <em>locked</em> modifiers.
1285 <code>LockMods</code>
1289 <li>Adds modifiers to <em>depressed</em> modifiers.</li>
1291 Toggle these modifiers in <em>locked</em> modifiers.</li>
1297 <li>Removes modifiers from <em>depressed</em> modifiers.</li>
1298 <li><em>Locked</em> modifiers stay unchanged.</li>
1307 ### Group actions {#group-actions}
1309 [group action]: @ref group-actions
1311 There are 3 group actions:
1316 <span class="todo">TODO</span>
1320 <span class="todo">TODO</span>
1324 <span class="todo">TODO</span>
1328 @todo Describe each action
1330 ### Unsupported legacy actions {#legacy-actions}
1332 [legacy action]: @ref legacy-actions
1334 @attention The following legacy actions are kept for compatibility only: they are parsed
1335 and validated but have no effect. This allows to use keymaps defined in
1336 <code>[xkeyboard-config]</code> for both X11 and Wayland.
1338 #### Pointer actions
1340 | Action | Alias | Description |
1342 | `MovePointer` | `MovePtr` | |
1343 | `PointerButton` | `PtrBtn` | |
1344 | `LockPtrButton` | `LockPtrBtn` | |
1345 | `LockPointerButton` | `LockPointerBtn` | |
1346 | `SetPointerDefault` | `SetPtrDflt` | |
1348 @todo Describe each action
1350 #### Control flags actions
1352 @todo `SetControls`, `LockControls`
1356 @todo `TerminateServer`, `SwitchScreen`