1 # The XKB keymap text format, V1
3 This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` keymap format,
4 as implemented by libxkbcommon.
6 A keymap consists of a single top-level `xkb_keymap` block, underwhich
7 are nested the following sections.
10 ## The `xkb_keycodes` section
12 This is the simplest section type, and is the first one to be
13 compiled. The purpose of this is mostly to map between the
14 hardware/evdev scancodes and xkb keycodes. Each key is given a name
15 by which it can be referred to later, e.g. in the symbols section.
17 ### Keycode statements
19 Statements of the form:
24 The above would let 49 and 10 be valid keycodes in the keymap, and
25 assign them the names `TLDE` and `AE01` respectively. The format
26 `<WXYZ>` is always used to refer to a key by name.
28 [The naming convention `<AE01>` just denotes the position of the key
29 in the main alphanumric section of a standard QWERTY keyboard, with
30 the two letters specifying the row and the two digits specifying the
31 column, from the bottom left.]
33 In the common case this just maps to the evdev scancodes from
34 `/usr/include/linux/input.h`, e.g. the following definitions:
39 correspond to the ones above. Similar definitions appear in the
40 xf86-input-keyboard driver. Note that in all current keymaps there's a
41 constant offset of 8 (for historical reasons).
43 If there's a conflict, like the same name given to different keycodes,
44 or same keycode given different names, it is resolved according to the
45 merge mode which applies to the definitions.
49 Statements of the form:
51 alias <MENU> = <COMP>;
53 Allows to refer to a previously defined key (here `<COMP>`) by another
54 name (here `<MENU>`). Conflicts are handled similarly to keycode
57 ### LED name statements
59 Statements of the form:
61 indicator 1 = "Caps Lock";
62 indicator 2 = "Num Lock";
63 indicator 3 = "Scroll Lock";
65 Assigns a name to the keyboard LED (AKA indicator) with the given
66 index. The LED may be referred by this name later in the compat
67 section and by the user.
70 ## The `xkb_types` section
72 This section is the second to be processesed, after `xkb_keycodes`.
73 However, it is completely independent and could have been the first to
74 be processed (it does not refer to specific keys as specified in the
75 `xkb_keycodes` section).
77 This section defines key types, which, given a key and a keyboard
78 state (i.e. modifier state and group), determine the shift level to be
79 used in translating the key to keysyms. These types are assigned to
80 each group in each key, in the `xkb_symbols` section.
82 Key types are called this way because, in a way, they really describe
83 the "type" of the key (or more correctly, a specific group of the
84 key). For example, an ordinary keymap will provide a type called
85 `KEYPAD`, which consists of two levels, with the second level being
86 chosen according to the state of the Num Lock (or Shift) modifiers.
87 Another example is a type called `ONE_LEVEL`, which is usually
88 assigned to keys such as Escape; these have just one level and are not
89 affected by the modifier state. Yet more common examples are
90 `TWO_LEVEL` (with Shift choosing the second level), `ALPHABETIC`
91 (where Caps Lock may also choose the second level), etc.
95 Statements of the form:
97 type "FOUR_LEVEL" { ... }
99 The above would create a new type named `FOUR_LEVEL`.
100 The body of the definition may include statements of the following
103 #### `level_name` statements
105 level_name[Level1] = "Base";
107 Mandatory for each level in the type.
109 Gives each level in this type a descriptive name. It isn't used
112 Note: A level may be specified as Level[1-8] or just a number (can
115 #### `modifiers` statement
117 modifiers = Shift+Lock+LevelThree;
119 Mandatory, should be specified only once.
121 A mask of real and virtual modifiers. These are the only modifiers
122 being considered when matching the modifier state against the type.
123 The other modifiers, whether active or not, are masked out in the
126 #### `map` entry statements
128 map[Shift+LevelThree] = Level4;
130 Should have at least as many mappings as there are levels in the type.
132 If the active modifiers, masked with the type's modifiers (as stated
133 above), match (i.e. equal) the modifiers inside the `map[]` statement,
134 then the level in the right hand side is chosen. For example, in the
135 above, if in the current keyboard state the `Shift` and `LevelThree`
136 modifiers are active, while the `Lock` modifier is not, then the
137 keysym(s) in the 4th level of the group will be returned to the user.
139 #### `preserve` statements
141 map[Shift+Lock+LevelThree] = Level5;
142 preserve[Shift+Lock+LevelThree] = Lock;
144 When a key type is used for keysym translation, its modifiers are said
145 to be "consumed". For example, in a simple US keymap, the "g" "g" key
146 is assigned an ordinary `ALPHABETIC` key type, whose modifiers are
147 Shift and Lock; then for the "g" key, these two modifiers are consumed
148 by the translation. This information is relevant for applications
149 which further process the modifiers, since by then the consumed
150 modifiers have already "done their part" and should be masked out.
152 However, sometimes even if a modifier had already affected the key
153 translation through the type, it should *not* be reported as consumed,
154 for various reasons. In this case, a `preserve[]` statement can be
155 used to augment the map entry. The modifiers inside the square
156 brackets should match one of the map[] statements in the type (if
157 there is no matching map entry, one mapping to Level1 is implicitly
158 added). The right hand side should consists of modifiers from the
159 type's modifiers; these modifiers are then "preserved" and not
160 reported as consumed.
163 ## The `xkb_compat` section
165 This section is the third to be processed, after `xkb_keycodes` and
168 ### Interpret statements
170 Statements of the form:
172 interpret Num_Lock+Any { ... }
173 interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
175 The `xkb_symbols` section (see below) allows the keymap author to
176 perform, among other things, the following things for each key:
178 - Bind an action, like SetMods or LockGroup, to the key. Actions, like
179 symbols, are specified for each level of each group in the key
182 - Add a virtual modifier to the key's virtual modifier mapping
185 - Specify whether the key should repeat or not.
187 However, doing this for each key (or level) is tedious and inflexible.
188 Interpret's are a mechanism to apply these settings to a bunch of
191 Each interpret specifies a condition by which it attaches to certain
192 levels. The condition consists of two parts:
194 - A keysym. If the level has a different (or more than one) keysym,
195 the match fails. Leaving out the keysym is equivalent to using the
196 `NoSymbol` keysym, which always matches successfully.
198 - A modifier predicate. The predicate consists of a matching operation
199 and a mask of (real) modifiers. The modifiers are matched against
200 the key's modifier map (modmap). The matching operation can be one
203 * `AnyOfOrNone` - The modmap must either be empty or include at
204 least one of the specified modifiers.
205 * `AnyOf` - The modmap must include at least one of the specified
207 * `NoneOf` - The modmap must not include any of the specified
209 * `AllOf` - The modmap must include all of the specified modifiers
210 (but may include others as well).
211 * `Exactly` - The modmap must be exactly the same as the specified
214 Leaving out the predicate is equivalent to using `AnyOfOrNone` while
215 specifying all modifiers. Leaving out just the matching condition is
216 equivalent to using `Exactly`.
218 An interpret may also include `useModMapMods = level1;` - see below.
220 If a level fulfils the conditions of several interprets, only the
221 most specific one is used:
223 - A specific keysym will always match before a generic `NoSymbol`
226 - If the keysyms are the same, the interpret with the more specific
227 matching operation is used. The above list is sorted from least to
230 - If both the keysyms and the matching operations are the same (but the
231 modifiers are different), the first interpret is used.
233 As described above, once an interpret "attaches" to a level, it can bind
234 an action to that level, add one virtual modifier to the key's vmodmap,
235 or set the key's repeat setting. You should note the following:
237 - The key repeat is a property of the entire key; it is not
238 level-specific. In order to avoid confusion, it is only inspected
239 for the first level of the first group; the interpret's repeat
240 setting is ignored when applied to other levels.
242 - If one of the above fields was set directly for a key in
243 `xkb_symbols`, the explicit setting takes precedence over the
246 The body of the statement may include statements of the following
247 forms (all of which are optional):
249 #### `useModMapMods` statement
251 useModMapMods = level1;
253 When set to `level1`, the interpret will only match levels which are
254 the first level of the first group of the keys. This can be useful in
255 conjunction with e.g. a `virtualModifier` statement.
257 #### `action` statement
259 action = LockMods(modifiers=NumLock);
261 Bind this action to the matching levels.
263 #### `virtualModifier` statement
265 virtualModifier = NumLock;
267 Add this virtual modifier to the key's vmodmap. The given virtual
268 modifier must be declared at the top level of the file with a
269 `virtual_modifiers` statement, e.g.:
271 virtual_modifiers NumLock;
273 #### `repeat` statement
277 Set whether the key should repeat or not. Must be a boolean value.
279 ### LED map statements
281 Statements of the form:
283 indicator "Shift Lock" { ... }
285 This statement specifies the behavior and binding of the LED (AKA
286 indicator) with the given name ("Shift Lock" above). The name should
287 have been declared previously in the `xkb_keycodes` section (see LED
288 name statement), and given an index there. If it wasn't, it is created
289 with the next free index.
291 The body of the statement describes the conditions of the keyboard
292 state which will cause the LED to be lit. It may include the following
295 #### `modifiers` statement
297 modifiers = ScrollLock;
299 If the given modifiers are in the required state (see below), the
302 #### `whichModState` statment
304 whichModState = Latched+Locked;
306 Can be any combination of:
308 * `base`, `latched`, `locked`, `effective`
309 * `any` (i.e. all of the above)
310 * `none` (i.e. none of the above)
311 * `compat` (legacy value, treated as effective)
313 This will cause the respective portion of the modifier state (see
314 `struct xkb_state`) to be matched against the modifiers given in the
315 `modifiers` statement.
317 Here's a simple example:
319 indicator "Num Lock" {
321 whichModState = Locked;
324 Whenever the NumLock modifier is locked, the Num Lock LED will light
327 #### `groups` statement
329 groups = All - group1;
331 If the given groups are in the required state (see below), the LED is
334 #### `whichGroupState` statement
336 whichGroupState = Effective;
338 Can be any combination of:
340 * `base`, `latched`, `locked`, `effective`
341 * `any` (i.e. all of the above)
342 * `none` (i.e. none of the above)
344 This will cause the respective portion of the group state (see
345 `struct xkb_state`) to be matched against the groups given in the
348 Note: the above conditions are disjunctive, i.e. if any of them are
349 satisfied the LED is lit.
352 ## The `xkb_symbols` section
354 NOTE: This section is incomplete.
356 This section is the fourth to be processed, after `xkb_keycodes`, `xkb_types`
359 Statements of the form:
361 xkb_symbols "basic" {
365 Declare a symbols map named `basic`. Statements inside the curly braces will
366 affect only affect the symbols map.
368 A map can have various flags applied to it above the statement, separated by
371 partial alphanumeric_keys
372 xkb_symbols "basic" {
376 The possible flags are the following:
378 * `partial` - Indicates that the map doesn't cover a complete keyboard
379 * `default` - Marks the symbol map as the default map in the file when no
380 explicit map is specified. If no map is marked as a default, the first map in
381 the file is the default.
382 * `hidden` - Variant that can only be used internally
383 * `alphanumeric_keys` - Indicates that the map contains alphanumeric keys
384 * `modifier_keys` - Indicates that the map contains modifier keys
385 * `keypad_keys` - Indicates that the map contains keypad keys
386 * `function_keys` - Indicates that the map contains function keys
387 * `alternate_group` - Indicates that the map contains keys for an alternate
390 If no `*_keys` flags are supplied, then the map is assumed to cover a complete
393 At present, except for `default`, none of the flags affect key processing in
394 libxkbcommon, and only serve as metadata.
398 Statements of the form:
400 name[Group1] = "US/ASCII";
401 groupName[1] = "US/ASCII";
403 Gives the name "US/ASCII" to the first group of symbols. Other groups can be
404 named using a different group index (ex: `Group2`), and with a different name.
405 A group must be named.
407 `group` and `groupName` mean the same thing, and the `Group` in `Group1` is
410 ### Include statements
412 Statements of the form:
414 include "nokia_vndr/rx-51(nordic_base)
416 Will include data from another `xkb_symbols` section, possibly located in
417 another file. Here it would include the `xkb_symbols` section called
418 `nordic_base`, from the file `rx-51` located in the `nokia_vndr` folder, itself
419 located in an XKB include path.
423 Statements of the form:
425 key <AD01> { [ q, Q ] };
427 Describes the mapping of a keycode `<AD01>` to a given group of symbols. The
428 symbols are `q` and `Q` in this example.
430 The possible keycodes are the keycodes defined in the `xkb_keycodes` section.
432 Symbols are named using the symbolic names from the
433 `xkbcommon/xkbcommon-keysyms.h` file. A group of symbols is enclosed in brackets
434 and separated by commas. Each element of the symbol arrays corresponds to a
435 different modifier level.
439 Each group represents a list of symbols mapped to a keycode:
441 name[Group1]= "US/ASCII";
442 name[Group2]= "Russian";
444 key <AD01> { [ q, Q ],
445 [ Cyrillic_shorti, Cyrillic_SHORTI ] };
447 The long-form syntax can also be used to represent groups:
450 symbols[Group1]= [ q, Q ],
451 symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
454 Groups can also be omitted, but the brackets must be present. The following
455 statement only defines the Group3 of a mapping:
457 key <AD01> { [], [], [ q, Q ] };
459 ## Virtual modifier statements
461 Statements of the form:
463 virtual_modifiers LControl;
465 Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections.