1 # The XKB keymap text format, V1
5 • The Markdown supported in doxygen is limitated 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 [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
20 NOTE: Due to the complexity of the format, this document is still is construction.
21 Some additional resources are:
23 - [Ivan Pascal's XKB documentation](https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/)
24 - [An Unreliable Guide to XKB Configuration](https://www.charvolant.org/doug/xkb/html/index.html)
25 - [The X Keyboard Extension: Protocol Specification](https://www.x.org/releases/current/doc/kbproto/xkbproto.html)
26 - [ArchWiki XKB page](https://wiki.archlinux.org/index.php/X_keyboard_extension)
30 1. [Terminology][terminology]
31 2. [Introduction to the XKB text format][introduction]
32 3. [The xkb_keymap block][xkb_keymap]
33 4. [The xkb_keycodes section][xkb_keycodes]
34 5. [The xkb_types section][xkb_types]
35 6. [The xkb_compat section][xkb_compat]
36 7. [The xkb_symbols section][xkb_symbols]
37 8. [Virtual modifier statements][virtual modifier statements]
38 9. [Modifiers bindings][modifiers bindings]
39 10. [Key actions][actions]
41 [terminology]: @ref terminology
42 [introduction]: @ref introduction
43 [xkb_keymap]: @ref the-xkb_keymap-block
44 [xkb_keycodes]: @ref the-xkb_keycodes-section
45 [xkb_types]: @ref the-xkb_types-section
46 [xkb_compat]: @ref the-xkb_compat-section
47 [xkb_symbols]: @ref the-xkb_symbols-section
48 [virtual modifier statements]:@ref virtual-modifier-statements
49 [modifiers bindings]: @ref modifiers-bindings
50 [actions]: @ref key-actions
52 ## Terminology {#terminology}
55 <dt><a name="keycode-def">Keycode</a><dt>
57 Code that identifies a physical key on a keyboard.
59 - _Raw_ keycodes are the numeric identifiers used as input in XKB.
60 They are the result of the low-level processing of the data that
61 keyboards send to a computer. For instance `36` may represent
63 - _XKB_ keycodes are _symbolic_ names assigned to raw keycodes in
64 order to facilitate their mapping to symbols. For instance the
65 keycode for the return key is the abbreviation `RTRN`.
67 See [xkb_keycodes] for further details.
69 <dt><a name="keysym-def">Symbols</a></dt>
71 A _keysym_ (short for “key symbol”) is a numeric encoding of a
72 symbol on the cap of a key.
74 They have a canonical name for convenience. It can be:
76 - A _character:_ e.g. `a` and `A` for Latin scripts,
77 `alpha` “α” and `ALPHA` “Α” for Greek, etc.
78 - A _dead key:_ e.g. `dead_grave` and `dead_diaeresis`, corresponding repectively
79 to the [grave accent](https://en.wikipedia.org/wiki/Grave_accent)
80 and the [diaeresis](https://en.wikipedia.org/wiki/Diaeresis_%28diacritic%29)
83 A [dead key](https://en.wikipedia.org/wiki/Dead_key) is a special kind of key
84 that does not generate a character by itself, but modifies the character
85 generated by the key struck(s) immediately after.
86 - A <em>[modifier]:</em> e.g. `Shift_L`, `Control_R`, `Caps_Lock`.
88 - A _system action:_ e.g. the arrow `Left`, `Pause`, `Escape`, `F1`.
90 The complete list of keysyms is defined in `xkbcommon/xkbcommon-keysyms.h`.
92 See [xkb_symbols] for further details on binding keysyms to keycodes.
94 <dt><a name="modifier-def">Modifier</a></dt>
96 A _modifier key_ is a key that modifies the effect of other keys:
97 e.g. Shift, Control, Caps Lock, etc.
99 The state of a modifier key (active/inactive) is encoded as a
100 _modifier index_ (or modifier bit or simply modifier) and has
101 an associated _unique name_.
103 For historical reasons, modifiers are divided in two categories:
106 <dt><a name="real-modifier-def">Real modifiers</a></dt>
108 They are the 8 _predefined_ (AKA core, X11) modifiers
109 (see [usual modifiers] hereinafter).
111 Real modifiers ensure backward compatibility: indeed
112 they are the actual bits used to compute the [levels][level]
113 and are communicated via the API of xkbcommon.
115 Some are generic modifiers (`Mod[1-5]`) that do not have a
116 conventional interpretation and are the motivation of the
117 introduction of [virtual modifiers].
119 <dt><a name="virtual-modifier-def">Virtual modifiers</a>
121 They are the modifiers that are _not_ predefined.
125 Each modifier defines a _mapping_ to one or multiple
126 _real_ modifier. Real modifiers map to themselves.
128 The following table lists the
129 <a name="usual-modifiers">usual modifiers</a>
130 present in the [standard keyboard configuration][xkeyboard-config].
131 Note that this is provided for information only, as it may change
132 depending on the user configuration.
134 | Modifier | Type | Usual mapping | Comment |
135 | ------------ | ------- | ------------- | --------------------------- |
136 | `Shift` | Real | `Shift` | The usual [Shift] |
137 | `Lock` | Real | `Lock` | The usual [Caps Lock][Lock] |
138 | `Control` | Real | `Control` | The usual [Control] |
139 | `Mod1` | Real | `Mod1` | Not conventional |
140 | `Mod2` | Real | `Mod2` | Not conventional |
141 | `Mod3` | Real | `Mod3` | Not conventional |
142 | `Mod4` | Real | `Mod4` | Not conventional |
143 | `Mod5` | Real | `Mod5` | Not conventional |
144 | `Alt` | Virtual | `Mod1` | The usual [Alt] |
145 | `Meta` | Virtual | `Mod1` or `Mod4` | The legacy [Meta] key |
146 | `NumLock` | Virtual | `Mod2` | The usual [NumLock] |
147 | `Super` | Virtual | `Mod4` | The usual [Super]/GUI |
148 | `LevelThree` | Virtual | `Mod3` | [ISO][ISO9995] level 3, aka [AltGr] |
149 | `LevelFive` | Virtual | `Mod5` | [ISO][ISO9995] level 5 |
151 [usual modifiers]: @ref usual-modifiers
152 [Shift]: https://en.wikipedia.org/wiki/Control_key
153 [Lock]: https://en.wikipedia.org/wiki/Caps_Lock
154 [Control]: https://en.wikipedia.org/wiki/Control_key
155 [Alt]: https://en.wikipedia.org/wiki/Alt_key
156 [AltGr]: https://en.wikipedia.org/wiki/AltGr_key
157 [NumLock]: https://en.wikipedia.org/wiki/Num_Lock
158 [Meta]: https://en.wikipedia.org/wiki/Meta_key
159 [Super]: https://en.wikipedia.org/wiki/Super_key_(keyboard_button)
161 A modifier key can report its state in one of the following 3 ways:
164 <dt><a name="depressed-mod-def">Depressed</a></dt>
165 <dd>Active while depressed; e.g. the usual Shift.</dd>
166 <dt><a name="latched-mod-def">Latched</a></dt>
168 Actived when pressed and deactivated after the next
169 non-modifier key press.
171 <dt><a name="locked-mod-def">Locked</a></dt>
173 Actived when pressed and deactivated when pressed again;
174 e.g. the usual Caps Lock.
178 See [modifiers bindings] for further details.
181 [depressed]: @ref depressed-mod-def
182 [latched]: @ref latched-mod-def
183 [locked]: @ref locked-mod-def
185 <dt><a name="level-def">Shift Level</a></dt>
187 A key may produce different
188 results depending of the active modifiers: e.g. for a Latin script,
189 pressing the key A produces “a” and holding Shift while pressing A
192 This various results are organized in an ordered list; the _index_
193 of each entry is called a <a name="level-index-def">shift level</a>
194 or simply level. By convention the lowest level is the result when
195 no modifier is active.
196 Example for the key `A` on latin script keyboard:
198 | Level | Description | Keysym | Active key modifiers |
199 |-------|--------------------------------|--------|----------------------|
200 | 1 | Lower case letters | `a` | None |
201 | 2 | Upper case letters. | `A` | `Shift` |
202 | 3 | Alternative lower case letters | `ae` | `AltGr` |
203 | 4 | Alternative upper case letters | `AE` | `Shift` + `AltGr` |
205 A key shift level is the logical _state_ of a key corresponding to
206 the current shift level it used.
208 Key shift levels are derived from the modifiers states, but not
209 necessarily in the same way for all keys. For example, for Latin
210 script the Caps Lock modifier selects the level 2 for alphabetic
211 keys such as `A` but has no effect on a numeric key.
213 There are groups of keys with the same characteristics: letters,
214 punctuation, numeric keypad, etc. The meaning of their levels is
215 identical and thus can be shared: this generalization is called
216 a _key type_ (see hereinafter).
218 <dt><a name="key-type-def">Key type</a></dt>
220 A key type defines the levels available for a key and
221 how to derive the active level from the modifiers states. Examples:
222 - `ONE_LEVEL`: the key has only one level, i.e. it is not affected
223 by any modifiers. Example: the modifiers themselves.
224 - `TWO_LEVEL`: the key has two levels:
225 - Level 1: default level, active when the `Shift` modifier is _not_ active.
226 - Level 2: level activated with the `Shift` modifier.
227 - `FOUR_LEVEL`: see the example in the previous section.
229 See [xkb_types] for further details.
231 <dt><a name="layout-def">Layout</a></dt>
233 A mapping of keycodes to symbols, actions and key types.
235 A user who deals with multiple languages may need two or more
236 different layouts: e.g. a layout for Arabic and another one for
237 English. In this context, layouts are called _groups_ in XKB,
238 as defined in the [standard ISO/IEC 9995][ISO9995].
240 Layouts are ordered and identified by their index. Example:
246 <dt><a name="key-action-def">Key Action</a></dt>
248 In XKB world, a key action defines the effect a key
249 has on the state of the keyboard or the state of the display server.
252 - Change the state of a modifier.
253 - Change the active group.
254 - Move the mouse pointer.
256 See the section “[Key actions][actions]” for further details.
258 <dt><a name="indicator-def">Indicator</a></dt>
260 A keyboard indicator is a mean to report a specific aspect of the
264 <dt><em>Physical</em> indicator</dt>
266 Typcally a labelled LED on the keyboard, e.g. “Caps Lock” and
269 <dt><em>Logical</em> indicator</dt>
271 A customizable derived state of the keyboard.
272 Its changes creates events that can be monitored.
274 There are two categories:
276 - _Real_ indicators are those associated to a physical indicator.
277 For example, the “Caps Lock” logical modifier controls the
278 corresponding physical LED.
280 Because indicators are customizable, if one misses a “Num Lock”
281 LED, one could define instead the “Caps Lock” _indicator_ to
282 activate its LED when the “Num Lock” _modifier_ is active.
283 - _Virtual_ indicators are not assiociated to a physical indicator.
284 Their effect is only visible for programs monitoring them.
286 Note that the meanings of _real_ and _virtual_ is slightly
287 different than the one used for [modifier].
291 See: <code>[xkb_keycodes][indicator name]</code> to define indicators and
292 <code>[xkb_compat][indicator effect]</code> to define their effects.
294 <dt><a name="keymap-def">Keymap</a></dt>
296 The _complete_ definition of the
297 mapping of raw keycodes to symbols and actions.
298 It fully defines the behaviour of a keyboard.
300 See [xkb_keymap] for further details.
304 [keycode]: @ref keycode-def
305 [keysym]: @ref keysym-def
306 [keysyms]: @ref keysym-def
307 [modifier]: @ref modifier-def
308 [modifiers]: @ref modifier-def
309 [real modifier]: @ref real-modifier-def
310 [real modifiers]: @ref real-modifier-def
311 [virtual modifier]: @ref virtual-modifier-def
312 [virtual modifiers]: @ref virtual-modifier-def
313 [level]: @ref level-def
314 [shift level]: @ref level-def
315 [level index]: @ref level-index-def
316 [key type]: @ref key-type-def
317 [key types]: @ref key-type-def
318 [layout]: @ref layout-def
319 [action]: @ref key-action-def
320 [indicator]: @ref indicator-def
321 [keymap]: @ref keymap-def
322 [ISO9995]: https://en.wikipedia.org/wiki/ISO/IEC_9995
325 ## Introduction to the XKB text format {#introduction}
327 The XKB text format uses a language similar to the C program language.
329 <span class="TODO">TODO:</span> general comment on syntax: section,
332 <span class="TODO">TODO:</span> the import mecanism
334 <span class="TODO">TODO:</span> recommended ways to feed xkbcommon
337 ## The “xkb_keymap” block {#the-xkb_keymap-block}
339 A <strong>[keymap]</strong> consists of a single top-level `xkb_keymap`
340 block, underwhich are nested the following sections:
343 <dt><code>[xkb_keycodes]</code></dt>
345 A translation of the hardware/evdev scancodes from the keyboard into
346 XKB symbolic keycodes.
348 <dt><code>[xkb_types]</code></dt>
350 A specification of the modifier mask, target level and preserved
351 modifiers various modifiers combination produce.
353 <dt><code>[xkb_compat]</code></dt>
355 A specification of what actions various special-purpose keys produce.
357 <dt><code>[xkb_symbols]</code></dt>
359 A translation of symbolic key codes into actual symbols and actions.
363 Overview of a keymap file:
373 xkb_compatibility "XXX" {
382 ## The “xkb_keycodes” section {#the-xkb_keycodes-section}
384 This is the simplest section type, and is the first one to be
385 compiled. The purpose of this is mostly to map between the
386 hardware/evdev scancodes and XKB [keycodes]. Each key is given a name
387 by which it can be referred to later, e.g. in the symbols section.
389 ### Keycode statements
391 Statements of the form:
396 The above would let 49 and 10 be valid keycodes in the keymap, and
397 assign them the names `TLDE` and `AE01` respectively. The format
398 `<WXYZ>` is always used to refer to a key by name.
400 The naming convention `<AE01>` is based on the
401 [standard ISO/IEC 9995-1][ISO9995-1]. It denotes the position of the
402 key in the keyboard grid. It means: the main alphanumeric section
403 (`A`), row `E` and column `01`.
405 The following figure illustrates the grid on a staggered standard
406 US QWERTY keyboard. `<AE01>` corresponds to the key `1`.
409 \ 99 \ 00 \ 01 \ 02 \ 03 \ 04 \ 05…
411 -----------------------------------------
412 E \ \ ^ \ 1 \ 2 \ 3 \ 4 \ 5…
413 ------------------------------------------
414 D \ Tab \ Q \ W \ E \ R \ T…
415 -------------------------------------------
416 C \Caps \ A \ S \ D \ F \ G…
417 --------------------------------------------
418 B \Shift \ Z \ X \ C \ V \ B…
419 ---------------------------------------------
420 A \Ctrl\GUI \Alt \Space…
421 ----------------------------------------------
424 [ISO9995-1]: https://en.wikipedia.org/wiki/ISO/IEC_9995#ISO/IEC_9995-1
426 In the common case this just maps to the evdev scancodes from
427 `/usr/include/linux/input.h`, e.g. the following definitions:
432 correspond to the ones above. Similar definitions appear in the
433 xf86-input-keyboard driver. Note that in all current keymaps there's a
434 constant offset of 8 (for historical reasons).
436 Note that contrary to xkbcommon, the X11 protocol supports keycodes
437 only up to `255`. Therefore, when interfacing with X11, keymaps and applications
438 using keycodes beyond `255` should expect warnings.
440 If there's a conflict, like the same name given to different keycodes,
441 or same keycode given different names, it is resolved according to the
442 merge mode which applies to the definitions.
446 Statements of the form:
448 alias <MENU> = <COMP>;
450 Allows to refer to a previously defined key (here `<COMP>`) by another
451 name (here `<MENU>`). Conflicts are handled similarly to keycode
454 ### LED name statements {#indicator-name}
456 [indicator name]: @ref indicator-name
458 Statements of the form:
460 indicator 1 = "Caps Lock";
461 indicator 2 = "Num Lock";
462 indicator 3 = "Scroll Lock";
464 Assigns a name to the keyboard LED (AKA [indicator]) with the given
465 index. The LED may be referred by this name later in the compat
466 section and by the user.
469 ## The “xkb_types” section {#the-xkb_types-section}
471 This section is the second to be processed, after `xkb_keycodes`.
472 However, it is completely independent and could have been the first to
473 be processed (it does not refer to specific keys as specified in the
474 `xkb_keycodes` section).
476 This section defines [key types], which, given a key and a keyboard
477 state (i.e. modifier state and group), determine the [shift level] to
478 be used in translating the key to [keysyms]. These types are assigned to
479 each group in each key, in the `xkb_symbols` section.
481 Key types are called this way because, in a way, they really describe
482 the "type" of the key (or more correctly, a specific group of the
483 key). For example, an ordinary keymap will provide a type called
484 `KEYPAD`, which consists of two levels, with the second level being
485 chosen according to the state of the Num Lock (or Shift) modifiers.
486 Another example is a type called `ONE_LEVEL`, which is usually
487 assigned to keys such as Escape; these have just one level and are not
488 affected by the modifier state. Yet more common examples are
489 `TWO_LEVEL` (with Shift choosing the second level), `ALPHABETIC`
490 (where Caps Lock may also choose the second level), etc.
494 Statements of the form:
496 type "FOUR_LEVEL" { ... }
498 The above would create a new type named `FOUR_LEVEL`.
499 The body of the definition may include statements of the following
502 #### “level_name” statements
504 level_name[Level1] = "Base";
506 Mandatory for each level in the type.
508 Gives each level in this type a descriptive name. It isn't used
511 Note: A level may be specified as Level\[1-8\] or just a number (can
514 #### “modifiers” statement
516 modifiers = Shift+Lock+LevelThree;
518 Mandatory, should be specified only once.
520 A mask of real and virtual [modifiers]. These are the only modifiers
521 being considered when matching the modifier state against the type.
522 The other modifiers, whether active or not, are masked out in the
525 #### “map” entry statements
527 map[Shift+LevelThree] = Level4;
529 Should have at least as many mappings as there are levels in the type.
531 If the active modifiers, masked with the type's modifiers (as stated
532 above), match (i.e. equal) the modifiers inside the `map[]` statement,
533 then the level in the right hand side is chosen. For example, in the
534 above, if in the current keyboard state the `Shift` and `LevelThree`
535 modifiers are active, while the `Lock` modifier is not, then the
536 keysym(s) in the 4th level of the group will be returned to the user.
538 #### “preserve” statements
540 map[Shift+Lock+LevelThree] = Level5;
541 preserve[Shift+Lock+LevelThree] = Lock;
543 When a key type is used for keysym translation, its modifiers are said
544 to be "consumed". For example, in a simple US keymap, the "g" "g" key
545 is assigned an ordinary `ALPHABETIC` key type, whose modifiers are
546 Shift and Lock; then for the "g" key, these two modifiers are consumed
547 by the translation. This information is relevant for applications
548 which further process the modifiers, since by then the consumed
549 modifiers have already "done their part" and should be masked out.
551 However, sometimes even if a modifier had already affected the key
552 translation through the type, it should *not* be reported as consumed,
553 for various reasons. In this case, a `preserve[]` statement can be
554 used to augment the map entry. The modifiers inside the square
555 brackets should match one of the map[] statements in the type (if
556 there is no matching map entry, one mapping to Level1 is implicitly
557 added). The right hand side should consists of modifiers from the
558 type's modifiers; these modifiers are then "preserved" and not
559 reported as consumed.
562 ## The “xkb_compat” section {#the-xkb_compat-section}
564 This section is the third to be processed, after `xkb_keycodes` and
567 ### Interpret statements {#interpret-statements}
569 Statements of the form:
571 interpret Num_Lock+Any { ... }
572 interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
574 The <code>[xkb_symbols]</code> section (see below)
575 allows the keymap author to perform, among other things, the following
578 - Bind an [action], like `SetMods` or `LockGroup`, to the key.
579 Actions, like symbols, are specified for each level of each group
580 in the key separately.
582 - Add a [virtual modifier] to the key's virtual modifier mapping
585 - Specify whether the key should repeat or not.
587 However, doing this for each key (or level) is tedious and inflexible.
588 Interpret's are a mechanism to apply these settings to a bunch of
591 Each interpret specifies a condition by which it attaches to certain
592 levels. The condition consists of two parts:
594 - A <strong>[keysym]</strong>. If the level has a different (or more than one)
595 keysym, the match fails. Leaving out the keysym is equivalent to using the
596 special value `Any` or the `NoSymbol` keysym, which always matches
599 - A <strong>[modifier] predicate</strong>. The predicate consists of:
600 - A __mask__ of _real_ modifiers: a `+`-separated list of modifiers or
601 the special value `all`, which denotes all the modifiers.
603 The modifiers are matched against the key's modifier map (`modmap`).
604 - A __matching operation__, that is one of the following:
606 * `AnyOfOrNone` – The modmap must either be empty or include at
607 least one of the specified modifiers.
608 * `AnyOf` – The modmap must include at least one of the specified
610 * `Any` – Alias for `AnyOf(all)`.
611 * `NoneOf` – The modmap must not include any of the specified
613 * `AllOf` – The modmap must include all of the specified modifiers
614 (but may include others as well).
615 * `Exactly` – The modmap must be exactly the same as the specified
618 Leaving out the predicate is equivalent to using `AnyOfOrNone(all)`.
619 Leaving out just the matching condition is equivalent to using
622 An interpret may also include `useModMapMods = level1;` – see below.
624 If a [level] fulfils the conditions of several interprets, only the
625 most specific one is used:
627 - A specific keysym will always match before a generic `NoSymbol`
630 - If the keysyms are the same, the interpret with the more specific
631 matching operation is used. The above list is sorted from least to
634 - If both the keysyms and the matching operations are the same (but the
635 modifiers are different), the first interpret is used.
637 As described above, once an interpret "attaches" to a level, it can bind
638 an action to that level, add one virtual modifier to the key's vmodmap,
639 or set the key's repeat setting. You should note the following:
641 - The key repeat is a property of the entire key; it is not
642 level-specific. In order to avoid confusion, it is only inspected
643 for the first level of the first group; the interpret's repeat
644 setting is ignored when applied to other levels.
646 - If one of the above fields was set directly for a key in
647 `xkb_symbols`, the explicit setting takes precedence over the
650 The body of the statement may include statements of the following
651 forms (all of which are optional):
653 #### “useModMapMods” statement
655 useModMapMods = level1;
657 When set to `level1`, the interpret will only match keysyms which are
658 on the first level of the first group of the keys. This can be useful
659 in conjunction with e.g. a `virtualModifier` statement, because
660 `virtualModifier` is an attribute of the key rather than a specific
663 Note: the other possible value is `any` and is the default value.
665 #### “action” statement
667 action = LockMods(modifiers=NumLock);
669 Bind this action to the matching levels. See [key actions][actions]
670 for the list of available key actions.
672 #### “virtualModifier” statement
674 virtualModifier = NumLock;
676 Add this virtual modifier to the key's `vmodmap`. The given virtual
677 modifier must be declared at the top level of the file with a
678 `virtual_modifiers` statement, e.g.:
680 virtual_modifiers NumLock;
682 #### “repeat” statement
686 Set whether the key should repeat or not. Must be a boolean value.
688 ### LED map statements {#indicator-effect}
690 [indicator effect]: @ref indicator-effect
692 Statements of the form:
694 indicator "Shift Lock" { ... }
696 This statement specifies the behavior and binding of the LED (AKA
697 [indicator]) with the given name ("Shift Lock" above). The name should
698 have been declared previously in the `xkb_keycodes` section (see
699 [LED name][indicator name] statement), and given an index there.
700 If it wasn't, it is created with the next free index.
702 The body of the statement describes the conditions of the keyboard
703 state which will cause the LED to be lit. It may include the following
706 #### “modifiers” statement
708 modifiers = ScrollLock;
710 If the given [modifiers] are in the required state (see below), the
713 #### “whichModState” statement
715 whichModState = Latched+Locked;
717 Can be any combination of:
719 * `base`, `latched`, `locked`, `effective`
720 * `any` (i.e. all of the above)
721 * `none` (i.e. none of the above)
722 * `compat` (legacy value, treated as effective)
724 This will cause the respective portion of the modifier state (see
725 `struct xkb_state`) to be matched against the modifiers given in the
726 `modifiers` statement.
728 Here's a simple example:
730 indicator "Num Lock" {
732 whichModState = Locked;
735 Whenever the NumLock modifier is locked, the Num Lock LED will light
738 #### “groups” statement
740 groups = All - group1;
742 If the given groups are in the required state (see below), the LED is
745 #### “whichGroupState” statement
747 whichGroupState = Effective;
749 Can be any combination of:
751 * `base`, `latched`, `locked`, `effective`
752 * `any` (i.e. all of the above)
753 * `none` (i.e. none of the above)
755 This will cause the respective portion of the group state (see
756 `struct xkb_state`) to be matched against the groups given in the
759 Note: the above conditions are disjunctive, i.e. if any of them are
760 satisfied the LED is lit.
764 <span class="TODO">TODO:</span> e.g. `setMods.clearLocks= True;`
767 ## The “xkb_symbols” section {#the-xkb_symbols-section}
769 <span class="TODO">TODO:</span> complete this section.
771 This section is the fourth to be processed, after `xkb_keycodes`,
772 `xkb_types` and `xkb_compat`.
774 Statements of the form:
776 xkb_symbols "basic" {
780 Declare a symbols map named `basic`. Statements inside the curly braces only
781 affect the symbols map.
783 A map can have various flags applied to it above the statement, separated by
786 partial alphanumeric_keys
787 xkb_symbols "basic" {
791 The possible flags are:
793 * `partial` - Indicates that the map doesn't cover a complete keyboard.
794 * `default` - Marks the symbol map as the default map in the file when no
795 explicit map is specified. If no map is marked as a default, the first map
796 in the file is the default.
797 * `hidden` - Variant that can only be used internally
798 * `alphanumeric_keys` - Indicates that the map contains alphanumeric keys
799 * `modifier_keys` - Indicates that the map contains modifier keys
800 * `keypad_keys` - Indicates that the map contains keypad keys
801 * `function_keys` - Indicates that the map contains function keys
802 * `alternate_group` - Indicates that the map contains keys for an alternate
805 If no `*_keys` flags are supplied, then the map is assumed to cover a complete
808 At present, except for `default`, none of the flags affect key processing in
809 libxkbcommon, and only serve as metadata.
813 Statements of the form:
815 name[Group1] = "US/ASCII";
816 groupName[1] = "US/ASCII";
818 Gives the name "US/ASCII" to the first group of symbols. Other groups can be
819 named using a different group index (ex: `Group2`), and with a different name.
820 A group must be named.
822 `group` and `groupName` mean the same thing, and the `Group` in `Group1` is
825 ### Include statements
827 Statements of the form:
829 include "nokia_vndr/rx-51(nordic_base)"
831 Will include data from another `xkb_symbols` section, possibly located in
832 another file. Here it would include the `xkb_symbols` section called
833 `nordic_base`, from the file `rx-51` located in the `nokia_vndr` folder, itself
834 located in an XKB include path.
838 Statements of the form:
840 key <AD01> { [ q, Q ] };
842 Describes the mapping of a keycode `<AD01>` to a given group of symbols. The
843 possible keycodes are the keycodes defined in the `xkb_keycodes` section.
845 Symbols are named using the symbolic names from the
846 `xkbcommon/xkbcommon-keysyms.h` file. A group of symbols is enclosed in brackets
847 and separated by commas. Each element of the symbol arrays corresponds to a
848 different modifier level. In this example, the symbol (keysym) `XKB_KEY_q` for
849 level 1 and `XKB_KEY_Q` for level 2.
853 <span class="TODO">TODO:</span> how to bind key actions
855 For further details see [key actions][actions].
859 Each group represents a list of symbols mapped to a keycode:
861 name[Group1]= "US/ASCII";
862 name[Group2]= "Russian";
864 key <AD01> { [ q, Q ],
865 [ Cyrillic_shorti, Cyrillic_SHORTI ] };
867 A long-form syntax can also be used:
870 symbols[Group1]= [ q, Q ],
871 symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
874 Groups can also be omitted, but the brackets must be present. The following
875 statement only defines the Group3 of a mapping:
877 key <AD01> { [], [], [ q, Q ] };
879 #### Additional attributes
881 <span class="TODO">TODO:</span> virtualmodifiers, repeats
883 ## Virtual modifier statements {#virtual-modifier-statements}
885 <span class="TODO">TODO:</span> rework this section
887 Statements of the form:
889 virtual_modifiers LControl;
891 Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections.
893 ## Modifiers bindings {#modifiers-bindings}
895 ### Real and virtual modifiers
897 Modifiers are a particularly tricky part of XKB. For historical reasons they are
898 divided in two categories: [real modifiers] and [virtual modifiers].
900 Note that in X11, the maximum of virtual modifiers is 16
901 (see `XkbNumVirtualMods`).
903 The following table summarizes the modifiers defined
904 in <code>[xkeyboard-config]</code> (this is subject to change).
906 | Modifier | Type | Compat files | Associated keysyms |
907 |--------------|---------|------------------|----------------------|
908 | `Shift` | Real | `compat/basic` | `Shift_L`, `Shift_R` |
909 | ″ | ″ | `compat/iso9995` | `Shift_L`, `Shift_R`, `ISO_Level2_Latch` |
910 | `Lock` | Real | `compat/basic`, | `Caps_Lock` |
911 | ″ | ″ | `compat/caps` | ″ |
912 | `Control` | Real | `compat/basic` | `Control_L`, `Control_R` |
913 | `Alt` | Virtual | `compat/misc`, | `Alt_L`, `Alt_R` |
914 | ″ | ″ | `compat/pc` | ″ |
915 | `Meta` | Virtual | `compat/misc` | `Meta_L`, `Meta_R` |
916 | `Super` | Virtual | `compat/misc` | `Super_L`, `Super_R` |
917 | `Hyper` | Virtual | `compat/misc` | `Hyper_L`, `Hyper_R` |
918 | `ScrollLock` | Virtual | `compat/misc` | `Scroll_Lock` |
919 | `NumLock` | Virtual | `compat/basic`, | `Num_Lock`, |
920 | ″ | ″ | `compat/level5` | (`ISO_Level5_Lock`) |
921 | `LevelThree` | Virtual | `compat/iso9995` | `ISO_Level3_Shift`, `ISO_Level3_Latch`, `ISO_Level3_Lock` |
922 | `LevelFive` | Virtual | `compat/level5` | `ISO_Level5_Shift`, `ISO_Level5_Latch`, `ISO_Level5_Lock` |
923 | `Kana_Lock` | Virtual | `compat/japan` | `Kana_Lock` |
924 | `Square` | Virtual | `compat/olpc` | `KP_Home` |
925 | `Cross` | Virtual | `compat/olpc` | `KP_Next` |
926 | `Circle` | Virtual | `compat/olpc` | `KP_End` |
927 | `Triangle` | Virtual | `compat/olpc` | `KP_Prior` |
929 ### Define and use a modifier
931 We will use the example of the _real_ modifier `Shift` and the virtual
932 modifier `LevelThree` in `xkeyboard-config`.
934 In order to define and use a modifier, one must:
936 1. Define its behaviour and [keysym] binding in the
937 <code>[xkb_compat]</code> section:
940 // Declare virtual modifiers. Shift being real modifier,
941 // we do not need to add it here.
942 virtual_modifiers LevelThree;
944 // Set defaults. They are overriden if set directly in the xkb_symbols.
945 interpret.repeat= False; // only applied on first level
946 setMods.clearLocks= True;
947 latchMods.clearLocks= True;
948 latchMods.latchToLock= True;
950 // Default statement for real modifiers: any key bound to a real
951 // modifier via modifier_map will set this modifier at all its
953 // Here only to illustrate: do not add it!
954 interpret Any + Any {
955 action= SetMods(modifiers=modMapMods);
958 // Shift being real modifier, we do not need a corresponding
959 // interpret statement because the previous one suffices.
961 // Let’s associate LevelThree to the keysym ISO_Level3_Shift
963 // First, match the keys and their levels with the
964 // ISO_Level3_Shift keysym and with any real modifier
965 // (Any = AnyOf(all)) in its modmap.
966 interpret ISO_Level3_Shift+Any {
967 // Only match the first level of the first group
968 useModMapMods= level1;
969 // Add the virtual modifier to the key’s vmodmap
970 virtualModifier= LevelThree;
971 // Activate the LevelThree modifier (depressed mode)
972 action= SetMods(modifiers=LevelThree);
975 // Then for keys and their levels with the
976 // ISO_Level3_Shift keysym but with either no real modifier
977 // in its modmap or a level higher than 1.
979 // • In case the level is higher than 1 there is no match
980 // in the previous statement.
981 // • The condition is equivalent to
982 // ISO_Level3_Shift+AnyOfOrNone(all), but since
983 // the previous statement ISO_Level3_Shift+Any is more
984 // specififc, it will be matched before this one.
985 interpret ISO_Level3_Shift {
986 // Activate the LevelThree modifier (depressed mode)
987 action= SetMods(modifiers=LevelThree);
991 2. Define [key types] that use it in the
992 <code>[xkb_types]</code> section:
995 // Declare virtual modifiers. Shift being real modifier,
996 // we do not need to add it here.
997 virtual_modifiers LevelThree;
1000 // Key type modifier mask: all the modifiers used in the key type
1001 modifiers = Shift + LevelThree;
1003 map[Shift] = Level2;
1004 map[LevelThree] = Level3;
1005 map[Shift+LevelThree] = Level4;
1006 level_name[Level1] = "Base";
1007 level_name[Level2] = "Shift";
1008 level_name[Level3] = "AltGr";
1009 level_name[Level4] = "Shift AltGr";
1013 3. Bind it to a [keycode] in the
1014 <code>[xkb_symbols]</code> section:
1016 1. Map [keysyms] used in the `xkb_compat` section hereinabove.
1017 2. Bind [real modifiers] to keys using these keysyms with
1020 _Note:_ Only one key binding to real modifier is required.
1021 The corresponding keysym must then be on the first level of
1024 _Note:_ One can optionally bind directly a virtual modifier to a
1025 key using `virtualmodifiers` instead of doing it in the
1026 `xkb_compat` section. But the recommended way is to use the
1027 `xkb_compat` section.
1030 // Shift: defined in pc symbols
1031 key <LFSH> {[ Shift_L ]};
1032 key <RTSH> {[ Shift_R ]};
1033 modifier_map Shift { Shift_L, Shift_R };
1034 // The previous will resolve to:
1035 // modifier_map Shift { <LFSH>, <RTSH> };
1036 // Thus the real modifier Shift is added to the modmap of
1037 // <LFSH> and <RTSH>.
1038 // The “Any + Any” interpret statement matches <LFSH> and <RTSH>,
1039 // therefore these keys set the Shift modifier.
1041 // LevelThree: defined in pc symbols
1042 // With the following 2 lines:
1043 // 1. The modifier keysym is on the first level of the first group.
1044 // 2. The real modifier Mod5 is bound to <LVL3>,
1045 // i.e. Mod5 is added to its modmap.
1046 // 3. It matches the interpret statement “ISO_Level3_Shift+Any”,
1047 // which adds the LevelThree modifier to the vmodmap of <LVL3>.
1048 // 4. The mapping of LevelThree to real modifiers is the union
1049 // of modmaps with corresponding vmodmaps containing
1050 // LevelThree. In our case there is only one: therefore
1051 // LevelThree maps to Mod5.
1052 key <LVL3> {[ ISO_Level3_Shift ]};
1053 modifier_map Mod5 { <LVL3> };
1055 // LevelThree: defined in level3 symbols
1056 // Not bound to a real modifier, so interpret statement
1057 // “ISO_Level3_Shift” applies.
1058 key <RALT> {[ISO_Level3_Shift], type[group1]="ONE_LEVEL" };
1060 // Note: we could have the following line, but it is not necessary
1061 // because we have the mappings of <LVL3>.
1062 // modifier_map Mod5 { <RALT> };
1064 // Warning: if we had the for example the following line, the
1065 // mapping of LevelThree to real modifiers would be “Mod1+Mod5”.
1066 // modifier_map Mod1 { <RALT> };
1068 // Alternative definitions, without using interpret statements
1069 virtual_modifiers LevelThree;
1070 key <LVL3> { virtualmodifiers=LevelThree
1072 , symbols[Group1] = [ISO_Level3_Shift]
1073 , actions[Group1] = [SetMods(modifiers=LevelThree)] };
1074 modifier_map Mod5 { <LVL3> };
1075 key <RALT> { repeat=False
1076 , symbols[Group1] = [ISO_Level3_Shift]
1077 , actions[Group1] = [SetMods(modifiers=LevelThree)]
1078 , type[group1]="ONE_LEVEL" };
1080 // FOUR_LEVEL key type example from latin symbols
1081 key <AB05> {[b, B, leftdoublequotemark, leftsinglequotemark]};
1084 ## Key actions {#key-actions}
1086 <span class="TODO">TODO:</span> list of all actions and their parameters
1088 The following table provide an overview of the available actions:
1090 | Category | Action | Alias | Description |
1091 |----------|---------------------|------------------|------------------------------------|
1092 | | `NoAction` | | Do nothing. |
1093 | [Modifier action] | `SetMods` | | Modifies the _depressed_ modifiers |
1094 | ^ | `LatchMods` | | Modifies the _latched_ modifiers |
1095 | ^ | `LockMods` | | Modifies the _locked_ modifiers |
1096 | [Group action] | `SetGroup` | | <span class="TODO">TODO</span> |
1097 | ^ | `LatchGroup` | | <span class="TODO">TODO</span> |
1098 | ^ | `LockGroup` | | <span class="TODO">TODO</span> |
1099 | [Legacy action] | `MovePointer` | `MovePtr` | <span class="TODO">TODO</span> |
1100 | ^ | `PointerButton` | `PtrBtn` | <span class="TODO">TODO</span> |
1101 | ^ | `LockPointerButton` | `LockPtrBtn` | <span class="TODO">TODO</span> |
1102 | ^ | `SetPointerDefault` | `SetPtrDflt` | <span class="TODO">TODO</span> |
1103 | ^ | `SetControls` | | <span class="TODO">TODO</span> |
1104 | ^ | `LockControls` | | <span class="TODO">TODO</span> |
1105 | ^ | `TerminateServer` | `Terminate` | <span class="TODO">TODO</span> |
1106 | ^ | `SwitchScreen` | | <span class="TODO">TODO</span> |
1107 | ^ | `Private` | | <span class="TODO">TODO</span> |
1111 - `true`, `yes`, `on`
1112 - `false`, `no`, `off`
1114 ### Modifiers actions {#modifiers-actions}
1116 [modifier action]: @ref modifiers-actions
1118 <span class="TODO">TODO:</span> default values
1120 There are 3 modifiers actions:
1125 Modifies the _depressed_ modifiers.
1128 - `modifiers` or `mods`: the list of modifiers to modify,
1129 separated by `+`, or the special value `modMapMods`. The latter
1130 means the parameter value has to be read from the `vmodmap`
1131 attribute of the key.
1132 - `clearLocks`: boolean (see its use hereinafter).
1134 <dt>`LatchMods`</dt>
1136 Modifies the _latched_ modifiers
1139 - `modifiers` or `mods`: see `SetMods`.
1140 - `clearLocks`: boolean (see its use hereinafter).
1141 - `latchToLock`: boolean (see its use hereinafter).
1145 Modifies the _locked_ modifiers.
1148 - `modifiers` or `mods`: see `SetMods`.
1150 - `lock`: the action only locks the modifier, but cannot unlock it.
1151 - `unlock`: the action only unlocks modifier, but cannot lock it.
1152 - `both`: the first key press locks the modifier and the second key
1153 press releases the modifier. It is a default mode.
1154 - `neither`: do not lock nor unlock, i.e. do nothing.
1158 <span class="TODO">TODO:</span> highlight that there is reference counting for
1159 the modifiers, e.g. to manage multiple physical keys for the same modifier.
1161 These actions perform different tasks on key press and on key release:
1165 Effects of modifiers actions
1170 <th>On key press</th>
1171 <th>On key release</th>
1176 <th><code>SetMods</code></th>
1179 <li>Adds modifiers to <em>depressed</em> modifiers</li>
1185 Removes modifiers from <em>depressed</em> modifiers,
1186 provided that no other key which affects the same
1187 modifiers is logically down.
1190 If <code>clearLocks=yes</code> and no other key
1191 were operated simultaneously with this key,
1192 then the modifiers will be removed as well from
1193 the <em>locked</em> modifiers.
1199 <th><code>LatchMods</code></th>
1202 <li>Adds modifiers to <em>latched</em> modifiers.</li>
1207 <li>Removes modifiers from <em>latched</em> modifiers.</li>
1209 If <code>clearLocks=yes</code> and no other key
1210 has been pressed since this key press, then the
1211 modifiers will be removed as well from the
1212 <em>locked</em> modifiers.
1215 If <code>latchToLock=yes</code> then the modifiers
1216 are added to the <em>locked</em> modifiers.
1223 <code>LockMods</code>
1227 <li>Adds modifiers to <em>depressed</em> modifiers.</li>
1229 Toggle these modifiers in <em>locked</em> modifiers.</li>
1235 <li>Removes modifiers from <em>depressed</em> modifiers.</li>
1236 <li><em>Locked</em> modifiers stay unchanged.</li>
1243 <span class="TODO">TODO:</span> Finish
1245 ### Group actions {#group-actions}
1247 [group action]: @ref group-actions
1249 There are 3 group actions:
1254 <span class="TODO">TODO</span>
1258 <span class="TODO">TODO</span>
1262 <span class="TODO">TODO</span>
1266 <span class="TODO">TODO:</span> Describe each action
1268 ### Unsupported legacy actions {#legacy-actions}
1270 [legacy action]: @ref legacy-actions
1272 The following legacy actions are kept for compatibility only: they are parsed
1273 and validated but have no effect. This allows to use keymaps defined in
1274 <code>[xkeyboard-config]</code> for both X11 and Wayland.
1276 #### Pointer actions
1278 | Action | Alias | Description |
1280 | `MovePointer` | `MovePtr` | |
1281 | `PointerButton` | `PtrBtn` | |
1282 | `LockPtrButton` | `LockPtrBtn` | |
1283 | `LockPointerButton` | `LockPointerBtn` | |
1284 | `SetPointerDefault` | `SetPtrDflt` | |
1286 <span class="TODO">TODO:</span> Describe each action
1288 #### Control flags actions
1290 <span class="TODO">TODO:</span> `SetControls`, `LockControls`
1294 <span class="TODO">TODO:</span> `TerminateServer`, `SwitchScreen`
1298 <span class="TODO">TODO:</span> `Private`