1# The XKB keymap text format, V1
2
3This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` keymap format,
4as implemented by libxkbcommon.
5
6A keymap consists of a single top-level `xkb_keymap` block, underwhich
7are nested the following sections.
8
9
10## The `xkb_keycodes` section
11
12This is the simplest section type, and is the first one to be
13compiled. The purpose of this is mostly to map between the
14hardware/evdev scancodes and xkb keycodes. Each key is given a name
15by which it can be referred to later, e.g. in the symbols section.
16
17### Keycode statements
18
19Statements of the form:
20
21    <TLDE> = 49;
22    <AE01> = 10;
23
24The above would let 49 and 10 be valid keycodes in the keymap, and
25assign them the names `TLDE` and `AE01` respectively. The format
26`<WXYZ>` is always used to refer to a key by name.
27
28[The naming convention `<AE01>` just denotes the position of the key
29in the main alphanumric section of a standard QWERTY keyboard, with
30the two letters specifying the row and the two digits specifying the
31column, from the bottom left.]
32
33In the common case this just maps to the evdev scancodes from
34`/usr/include/linux/input.h`, e.g. the following definitions:
35
36     #define KEY_GRAVE            41
37     #define KEY_1                2
38
39correspond to the ones above. Similar definitions appear in the
40xf86-input-keyboard driver. Note that in all current keymaps there's a
41constant offset of 8 (for historical reasons).
42
43If there's a conflict, like the same name given to different keycodes,
44or same keycode given different names, it is resolved according to the
45merge mode which applies to the definitions.
46
47### Alias statements
48
49Statements of the form:
50
51    alias <MENU> = <COMP>;
52
53Allows to refer to a previously defined key (here `<COMP>`) by another
54name (here `<MENU>`). Conflicts are handled similarly to keycode
55statements.
56
57### LED name statements
58
59Statements of the form:
60
61    indicator 1 = "Caps Lock";
62    indicator 2 = "Num Lock";
63    indicator 3 = "Scroll Lock";
64
65Assigns a name to the keyboard LED (AKA indicator) with the given
66index. The LED may be referred by this name later in the compat
67section and by the user.
68
69
70## The `xkb_types` section
71
72This section is the second to be processesed, after `xkb_keycodes`.
73However, it is completely independent and could have been the first to
74be processed (it does not refer to specific keys as specified in the
75`xkb_keycodes` section).
76
77This section defines key types, which, given a key and a keyboard
78state (i.e. modifier state and group), determine the shift level to be
79used in translating the key to keysyms. These types are assigned to
80each group in each key, in the `xkb_symbols` section.
81
82Key types are called this way because, in a way, they really describe
83the "type" of the key (or more correctly, a specific group of the
84key). For example, an ordinary keymap will provide a type called
85`KEYPAD`, which consists of two levels, with the second level being
86chosen according to the state of the Num Lock (or Shift) modifiers.
87Another example is a type called `ONE_LEVEL`, which is usually
88assigned to keys such as Escape; these have just one level and are not
89affected 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.
92
93### Type definitions
94
95Statements of the form:
96
97    type "FOUR_LEVEL" { ... }
98
99The above would create a new type named `FOUR_LEVEL`.
100The body of the definition may include statements of the following
101forms:
102
103#### `level_name` statements
104
105    level_name[Level1] = "Base";
106
107Mandatory for each level in the type.
108
109Gives each level in this type a descriptive name. It isn't used
110for anything.
111
112Note: A level may be specified as Level[1-8] or just a number (can
113be more than 8).
114
115#### `modifiers` statement
116
117    modifiers = Shift+Lock+LevelThree;
118
119Mandatory, should be specified only once.
120
121A mask of real and virtual modifiers. These are the only modifiers
122being considered when matching the modifier state against the type.
123The other modifiers, whether active or not, are masked out in the
124calculation.
125
126#### `map` entry statements
127
128    map[Shift+LevelThree] = Level4;
129
130Should have at least as many mappings as there are levels in the type.
131
132If the active modifiers, masked with the type's modifiers (as stated
133above), match (i.e. equal) the modifiers inside the `map[]` statement,
134then the level in the right hand side is chosen. For example, in the
135above, if in the current keyboard state the `Shift` and `LevelThree`
136modifiers are active, while the `Lock` modifier is not, then the
137keysym(s) in the 4th level of the group will be returned to the user.
138
139#### `preserve` statements
140
141    map[Shift+Lock+LevelThree] = Level5;
142    preserve[Shift+Lock+LevelThree] = Lock;
143
144When a key type is used for keysym translation, its modifiers are said
145to be "consumed". For example, in a simple US keymap, the "g" "g" key
146is assigned an ordinary `ALPHABETIC` key type, whose modifiers are
147Shift and Lock; then for the "g" key, these two modifiers are consumed
148by the translation. This information is relevant for applications
149which further process the modifiers, since by then the consumed
150modifiers have already "done their part" and should be masked out.
151
152However, sometimes even if a modifier had already affected the key
153translation through the type, it should *not* be reported as consumed,
154for various reasons. In this case, a `preserve[]` statement can be
155used to augment the map entry. The modifiers inside the square
156brackets should match one of the map[] statements in the type (if
157there is no matching map entry, one mapping to Level1 is implicitly
158added). The right hand side should consists of modifiers from the
159type's modifiers; these modifiers are then "preserved" and not
160reported as consumed.
161
162
163## The `xkb_compat` section
164
165This section is the third to be processed, after `xkb_keycodes` and
166`xkb_types`.
167
168### Interpret statements
169
170Statements of the form:
171
172    interpret Num_Lock+Any { ... }
173    interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
174
175The `xkb_symbols` section (see below) allows the keymap author to
176perform, among other things, the following things for each key:
177
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
180  separately.
181
182- Add a virtual modifier to the key's virtual modifier mapping
183  (vmodmap).
184
185- Specify whether the key should repeat or not.
186
187However, doing this for each key (or level) is tedious and inflexible.
188Interpret's are a mechanism to apply these settings to a bunch of
189keys/levels at once.
190
191Each interpret specifies a condition by which it attaches to certain
192levels. The condition consists of two parts:
193
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.
197
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
201  of the following:
202
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
206    modifiers.
207  * `NoneOf` - The modmap must not include any of the specified
208    modifiers.
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
212    modifiers.
213
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`.
217
218An interpret may also include `useModMapMods = level1;` - see below.
219
220If a level fulfils the conditions of several interprets, only the
221most specific one is used:
222
223- A specific keysym will always match before a generic `NoSymbol`
224  condition.
225
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
228  most specific.
229
230- If both the keysyms and the matching operations are the same (but the
231  modifiers are different), the first interpret is used.
232
233As described above, once an interpret "attaches" to a level, it can bind
234an action to that level, add one virtual modifier to the key's vmodmap,
235or set the key's repeat setting. You should note the following:
236
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.
241
242- If one of the above fields was set directly for a key in
243  `xkb_symbols`, the explicit setting takes precedence over the
244  interpret.
245
246The body of the statement may include statements of the following
247forms (all of which are optional):
248
249#### `useModMapMods` statement
250
251    useModMapMods = level1;
252
253When set to `level1`, the interpret will only match levels which are
254the first level of the first group of the keys. This can be useful in
255conjunction with e.g. a `virtualModifier` statement.
256
257#### `action` statement
258
259    action = LockMods(modifiers=NumLock);
260
261Bind this action to the matching levels.
262
263#### `virtualModifier` statement
264
265    virtualModifier = NumLock;
266
267Add this virtual modifier to the key's vmodmap. The given virtual
268modifier must be declared at the top level of the file with a
269`virtual_modifiers` statement, e.g.:
270
271    virtual_modifiers NumLock;
272
273#### `repeat` statement
274
275    repeat = True;
276
277Set whether the key should repeat or not. Must be a boolean value.
278
279### LED map statements
280
281Statements of the form:
282
283    indicator "Shift Lock" { ... }
284
285This statement specifies the behavior and binding of the LED (AKA
286indicator) with the given name ("Shift Lock" above). The name should
287have been declared previously in the `xkb_keycodes` section (see LED
288name statement), and given an index there. If it wasn't, it is created
289with the next free index.
290
291The body of the statement describes the conditions of the keyboard
292state which will cause the LED to be lit. It may include the following
293statements:
294
295#### `modifiers` statement
296
297    modifiers = ScrollLock;
298
299If the given modifiers are in the required state (see below), the
300LED is lit.
301
302#### `whichModState` statment
303
304    whichModState = Latched+Locked;
305
306Can be any combination of:
307
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)
312
313This 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.
316
317Here's a simple example:
318
319indicator "Num Lock" {
320    modifiers = NumLock;
321    whichModState = Locked;
322};
323
324Whenever the NumLock modifier is locked, the Num Lock LED will light
325up.
326
327#### `groups` statement
328
329    groups = All - group1;
330
331If the given groups are in the required state (see below), the LED is
332lit.
333
334#### `whichGroupState` statement
335
336    whichGroupState = Effective;
337
338Can be any combination of:
339
340* `base`, `latched`, `locked`, `effective`
341* `any` (i.e. all of the above)
342* `none` (i.e. none of the above)
343
344This will cause the respective portion of the group state (see
345`struct xkb_state`) to be matched against the groups given in the
346`groups` statement.
347
348Note: the above conditions are disjunctive, i.e. if any of them are
349satisfied the LED is lit.
350
351
352## The `xkb_symbols` section
353
354This section is the fourth to be processed, after `xkb_keycodes`,
355`xkb_types` and `xkb_compat`.
356
357TODO
358
359
360## Virtual modifier statements
361
362Statements of the form:
363
364    virtual_modifiers LControl;
365
366Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections.
367
368TODO
369