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