doc/keymap-format-text-v1.txt

   1 The xkb_keycodes section
   2 ========================
   3
   4 This is the simplest section type, and is the first one to be
   5 compiled. The purpose of this is mostly to map between the
   6 hardware/evdev scancodes and xkb keycodes. Each key is given a name
   7 by which it can be referred to later, e.g. in the symbols section.
   8
   9 Keycode statements
  10 ------------------
  11 Statements of the form:
  12
  13     <TLDE> = 49;
  14     <AE01> = 10;
  15
  16 The above would let 49 and 10 be valid keycodes in the keymap, and
  17 assign them the names TLDE and AE01 respectively. The format <WXYZ> is
  18 always used to refer to a key by name.
  19
  20 [The naming convention <AE01> just denoted the position of the key
  21 in the main alphanumric section of the keyboard, with the two letters
  22 specifying the row and the two digits specifying the column, from
  23 the bottom left.]
  24
  25 In 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
  31 correspond to the ones above. Similar definitions appear in the
  32 xf86-input-keyboard driver. Note that in all current keymaps there's a
  33 constant offset of 8 (for historical reasons).
  34
  35 If there's a conflict, like the same name given to different keycodes,
  36 or same keycode given different names, it is resolved according to the
  37 merge mode which applies to the definitions.
  38
  39 Alias statements
  40 ----------------
  41 Statements of the form:
  42
  43     alias <MENU> = <COMP>;
  44
  45 Allows to refer to a previously defined key (here <COMP>) by another
  46 name (here <MENU>). Conflicts are handled similarly to keycode
  47 statements.
  48
  49 LED name statements
  50 -------------------
  51 Statements of the form:
  52
  53     indicator 1 = "Caps Lock";
  54     indicator 2 = "Num Lock";
  55     indicator 3 = "Scroll Lock";
  56
  57 Assigns a name to the keyboard LED (a.k.a indicator) with the given
  58 index. The LED may be referred by this name later in the compat section
  59 and by the user.
  60
  61
  62 The xkb_types section
  63 =====================
  64
  65 This section is the second to be processesed, after xkb_keycodes.
  66 However, it is completely independent and could have been the first
  67 to be processed (it does not refer to specific keys as specified in
  68 the xkb_keycodes section).
  69
  70 This section defines key types, which, given a key and a keyboard
  71 state (i.e. modifier state and group), determine the shift level to
  72 be used in translating the key to keysyms. These types are assigned
  73 to each group in each key, in the xkb_symbols section.
  74
  75 Key types are called this way because, in a way, they really describe
  76 the "type" of the key (or more correctly, a specific group of the
  77 key). For example, an ordinary keymap will provide a type called
  78 "KEYPAD", which consists of two levels, with the second level being
  79 chosen according to the state of the Num Lock (or Shift) modifiers.
  80 Another example is a type called "ONE_LEVEL", which is usually
  81 assigned to keys such as Escape; these have just one level and are
  82 not 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
  86 Type definitions
  87 ----------------
  88 Statements of the form:
  89
  90     type "FOUR_LEVEL" { ... }
  91
  92 The above would create a new type named "FOUR_LEVEL".
  93 The body of the definition may include statements of the following
  94 forms:
  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
 157 The xkb_compat section
 158 ======================
 159
 160 This section is the third to be processed, after xkb_keycodes and
 161 xkb_types.
 162
 163 Interpret statements
 164 --------------------
 165 Statements of the form:
 166
 167     interpret Num_Lock+Any { ... }
 168     interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
 169
 170 The xkb_symbols section (see below) allows the keymap author to perform,
 171 among 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
 181 However, doing this for each key (or level) is tedious and inflexible.
 182 Interpret's are a mechanism to apply these settings to a bunch of
 183 keys/levels at once.
 184
 185 Each interpret specifies a condition by which it attaches to certain
 186 levels. 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
 211 An interpret may also include "useModMapMods = level1;" - see below.
 212
 213 If a level fulfils the conditions of several interpret's, only the
 214 most 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
 226 As described above, once an interpret "attaches" to a level, it can bind
 227 an action to that level, add one virtual modifier to the key's vmodmap,
 228 or 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
 238 The body of the statement may include statements of the following
 239 forms (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
 271 LED map statements
 272 ------------------
 273 Statements of the form:
 274
 275     indicator "Shift Lock" { ... }
 276
 277 This statement specifies the behavior and binding of the LED (a.k.a
 278 indicator) with the given name ("Shift Lock" above). The name should
 279 have been declared previously in the xkb_keycodes section (see LED
 280 name statement), and given an index there. If it wasn't, it is created
 281 with the next free index.
 282 The body of the statement describes the conditions of the keyboard
 283 state which will cause the LED to be lit. It may include the following
 284 statements:
 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
 343 The xkb_symbols section
 344 =======================
 345
 346 This section is the fourth to be processed, after xkb_keycodes,
 347 xkb_types and xkb_compat.
 348
 349 TODO
 350
 351
 352 Virtual modifier statements
 353 ===========================
 354
 355 Statements of the form:
 356     virtual_modifiers LControl;
 357
 358 Can appear in the xkb_types, xkb_compat, xkb_symbols sections.
 359 TODO