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