| The xkb_keycodes section |
| ======================== |
| |
| This is the simplest section type, and is the first one to be |
| compiled. The purpose of this is mostly to map between the |
| hardware/evdev scancodes and xkb keycodes. Each key is given a name |
| by which it can be referred to later, e.g. in the symbols section. |
| |
| Keycode statements |
| ------------------ |
| Statements of the form: |
| |
| <TLDE> = 49; |
| <AE01> = 10; |
| |
| The above would let 49 and 10 be valid keycodes in the keymap, and |
| assign them the names TLDE and AE01 respectively. The format <WXYZ> is |
| always used to refer to a key by name. |
| |
| [The naming convention <AE01> just denoted the position of the key |
| in the main alphanumric section of the keyboard, with the two letters |
| specifying the row and the two digits specifying the column, from |
| the bottom left.] |
| |
| In the common case this just maps to the evdev scancodes from |
| /usr/include/linux/input.h, e.g. the following definitions: |
| |
| #define KEY_GRAVE 41 |
| #define KEY_1 2 |
| |
| correspond to the ones above. Similar definitions appear in the |
| xf86-input-keyboard driver. Note that in all current keymaps there's a |
| constant offset of 8 (for historical reasons). |
| |
| If there's a conflict, like the same name given to different keycodes, |
| or same keycode given different names, it is resolved according to the |
| merge mode which applies to the definitions. |
| |
| Alias statements |
| ---------------- |
| Statements of the form: |
| |
| alias <MENU> = <COMP>; |
| |
| Allows to refer to a previously defined key (here <COMP>) by another |
| name (here <MENU>). Conflicts are handled similarly to keycode |
| statements. |
| |
| LED name statements |
| ------------------- |
| Statements of the form: |
| |
| indicator 1 = "Caps Lock"; |
| indicator 2 = "Num Lock"; |
| indicator 3 = "Scroll Lock"; |
| |
| Assigns a name to the keyboard LED (a.k.a indicator) with the given |
| index. The LED may be referred by this name later in the compat section |
| and by the user. |
| |
| |
| The xkb_types section |
| ===================== |
| |
| This section is the second to be processesed, after xkb_keycodes. |
| However, it is completely independent and could have been the first |
| to be processed (it does not refer to specific keys as specified in |
| the xkb_keycodes section). |
| |
| This section defines key types, which, given a key and a keyboard |
| state (i.e. modifier state and group), determine the shift level to |
| be used in translating the key to keysyms. These types are assigned |
| to each group in each key, in the xkb_symbols section. |
| |
| Key types are called this way because, in a way, they really describe |
| the "type" of the key (or more correctly, a specific group of the |
| key). For example, an ordinary keymap will provide a type called |
| "KEYPAD", which consists of two levels, with the second level being |
| chosen according to the state of the Num Lock (or Shift) modifiers. |
| Another example is a type called "ONE_LEVEL", which is usually |
| assigned to keys such as Escape; these have just one level and are |
| not affected by the modifier state. Yet more common examples are |
| "TWO_LEVEL" (with Shift choosing the second level), "ALPHABETIC" |
| (where Caps Lock may also choose the second level), etc. |
| |
| Type definitions |
| ---------------- |
| Statements of the form: |
| |
| type "FOUR_LEVEL" { ... } |
| |
| The above would create a new type named "FOUR_LEVEL". |
| The body of the definition may include statements of the following |
| forms: |
| |
| - level_name statements (mandatory for each level in the type): |
| |
| level_name[Level1] = "Base"; |
| |
| Gives each level in this type a descriptive name. It isn't used |
| for anything. |
| Note: A level may be specified as Level[1-8] or just a number (can |
| be more than 8). |
| |
| - modifiers statement (mandatory, should be specified only once): |
| |
| modifiers = Shift+Lock+LevelThree; |
| |
| A mask of real and virtual modifiers. These are the only modifiers |
| being considered when matching the modifier state against the type. |
| The other modifiers, whether active or not, are masked out in the |
| calculation. |
| |
| - map entry statements (should have at least as many mappings as there |
| are levels in the type): |
| |
| map[Shift+LevelThree] = Level4; |
| |
| If the active modifiers, masked with the type's modifiers (as stated |
| above), match (i.e. equal) the modifiers inside the map[] statement, |
| then the level in the right hand side is chosen. For example, in the |
| above, if in the current keyboard state the Shift and LevelThree |
| modifiers are active, while the Lock modifier is not, then the |
| keysym(s) in the 4th level of the group will be returned to the |
| user. |
| |
| - preserve statements: |
| |
| map[Shift+Lock+LevelThree] = Level5; |
| preserve[Shift+Lock+LevelThree] = Lock; |
| |
| When a map entry matches the active modifiers and the level it |
| specified is chosen, then these modifiers are said to be "consumed"; |
| for example, in a simple US keymap where the "g" key is assigned an |
| ordinary ALPHABETIC key type, if the Lock (Caps Lock) modifier is |
| active and the key is pressed, then a "G" keysym is produced (as |
| opposed to lower-case "g"). This is because the type definition has |
| a map entry like the following: |
| |
| map[Lock] = Level2; |
| |
| And as such the Lock modifier is consumed. This information is |
| relevant for applications which further process the modifiers, |
| since by then the consumed modifiers have already "done their part" |
| and should be masked out. |
| |
| However, sometimes even if a modifier is actually used to choose |
| the shift level (as Lock above), it should *not* be reported as |
| consumed, for various reasons. In this case, a preserve[] statement |
| can be used to augment the map entry. The modifiers inside the square |
| brackets should match one of the map[] statements in the type. The |
| right hand side should consists of modifiers from the left hand |
| side; these modifiers are then "preserved" and not reported as |
| consumed. |
| |
| |
| The xkb_compat section |
| ====================== |
| |
| This section is the third to be processed, after xkb_keycodes and |
| xkb_types. |
| |
| Interpret statements |
| -------------------- |
| Statements of the form: |
| |
| interpret Num_Lock+Any { ... } |
| interpret Shift_Lock+AnyOf(Shift+Lock) { ... } |
| |
| The xkb_symbols section (see below) allows the keymap author to perform, |
| among other things, the following things for each key: |
| |
| - Bind an action, like SetMods or LockGroup, to the key. Actions, like |
| symbols, are specified for each level of each group in the key |
| separately. |
| |
| - Add a virtual modifier to the key's virtual modifier mapping (vmodmap). |
| |
| - Specify whether the key should repeat or not. |
| |
| However, doing this for each key (or level) is tedious and inflexible. |
| Interpret's are a mechanism to apply these settings to a bunch of |
| keys/levels at once. |
| |
| Each interpret specifies a condition by which it attaches to certain |
| levels. The condition consists of two parts: |
| |
| - A keysym. If the level has a different (or more than one) keysym, the |
| match fails. Leaving out the keysym is equivalent to using the NoSymbol |
| keysym, which always matches successfully. |
| |
| - A modifier predicate. The predicate consists of a matching operation |
| and a mask of (real) modifiers. The modifiers are matched against the |
| key's modifier map (modmap). The matching operation can be one of the |
| following: |
| |
| * AnyOfOrNone - The modmap must either be empty or include at least |
| one of the specified modifiers. |
| * AnyOf - The modmap must include at least one of the specified |
| modifiers. |
| * NoneOf - The modmap must not include any of the specified modifiers. |
| * AllOf - The modmap must include all of the specified modifiers (but |
| may include others as well). |
| * Exactly - The modmap must be exactly the same as the specified |
| modifiers. |
| |
| Leaving out the predicate is equivalent to using AnyOfOrNone while |
| specifying all modifiers. Leaving out just the matching condition |
| is equivalent to using Exactly. |
| |
| An interpret may also include "useModMapMods = level1;" - see below. |
| |
| If a level fulfils the conditions of several interpret's, only the |
| most specific one is used: |
| |
| - A specific keysym will always match before a generic NoSymbol |
| condition. |
| |
| - If the keysyms are the same, the interpret with the more specific |
| matching operation is used. The above list is sorted from least to |
| most specific. |
| |
| - If both the keysyms and the matching operations are the same (but the |
| modifiers are different), the first interpret is used. |
| |
| As described above, once an interpret "attaches" to a level, it can bind |
| an action to that level, add one virtual modifier to the key's vmodmap, |
| or set the key's repeat setting. You should note the following: |
| |
| - The key repeat is a property of the entire key; it is not level-specific. |
| In order to avoid confusion, it is only inspected for the first level of |
| the first group; the interpret's repeat setting is ignored when applied |
| to other levels. |
| |
| - If one of the above fields was set directly for a key in xkb_symbols, |
| the explicit setting takes precedence over the interpret. |
| |
| The body of the statement may include statements of the following |
| forms (all of which are optional): |
| |
| - useModMapMods statement: |
| |
| useModMapMods = level1; |
| |
| When set to 'level1', the interpret will only match levels which are |
| the first level of the first group of the keys. This can be useful in |
| conjunction with e.g. a virtualModifier statement. |
| |
| - action statement: |
| |
| action = LockMods(modifiers=NumLock); |
| |
| Bind this action to the matching levels. |
| |
| - virtual modifier statement: |
| |
| virtualModifier = NumLock; |
| |
| Add this virtual modifier to the key's vmodmap. The given virtual |
| modifier must be declared at the top level of the file with a |
| virtual_modifiers statement, e.g.: |
| |
| virtual_modifiers NumLock; |
| |
| - repeat statement: |
| |
| repeat = True; |
| |
| Set whether the key should repeat or not. Must be a boolean value. |
| |
| LED map statements |
| ------------------ |
| Statements of the form: |
| |
| indicator "Shift Lock" { ... } |
| |
| This statement specifies the behavior and binding of the LED (a.k.a |
| indicator) with the given name ("Shift Lock" above). The name should |
| have been declared previously in the xkb_keycodes section (see LED |
| name statement), and given an index there. If it wasn't, it is created |
| with the next free index. |
| The body of the statement describes the conditions of the keyboard |
| state which will cause the LED to be lit. It may include the following |
| statements: |
| |
| - modifiers statement: |
| |
| modifiers = ScrollLock; |
| |
| If the given modifiers are in the required state (see below), the |
| LED is lit. |
| |
| - whichModifierState statment: |
| |
| whichModState = Latched+Locked; |
| |
| Can be any combination of: |
| |
| * base, latched, locked, effective |
| * any (i.e. all of the above) |
| * none (i.e. none of the above) |
| * compat (legacy value, treated as effective) |
| |
| This will cause the respective portion of the modifer state (see |
| struct xkb_state) to be matched against the modifiers given in the |
| "modifiers" statement. |
| |
| Here's a simple example: |
| |
| indicator "Num Lock" { |
| modifiers = NumLock; |
| whichModState = Locked; |
| }; |
| |
| Whenever the NumLock modifier is locked, the Num Lock LED will light |
| up. |
| |
| - groups statment: |
| |
| groups = All - group1; |
| |
| If the given groups are in the required state (see below), the LED |
| is lit. |
| |
| - whichGroupState statment: |
| |
| whichGroupState = Effective; |
| |
| Can be any combination of: |
| |
| * base, latched, locked, effective |
| * any (i.e. all of the above) |
| * none (i.e. none of the above) |
| |
| This will cause the respective portion of the group state (see |
| struct xkb_state) to be matched against the groups given in the |
| "groups" statement. |
| |
| Note: the above conditions are disjunctive, i.e. if any of them are |
| satisfied the LED is lit. |
| |
| |
| The xkb_symbols section |
| ======================= |
| |
| This section is the fourth to be processed, after xkb_keycodes, |
| xkb_types and xkb_compat. |
| |
| TODO |
| |
| |
| Virtual modifier statements |
| =========================== |
| |
| Statements of the form: |
| virtual_modifiers LControl; |
| |
| Can appear in the xkb_types, xkb_compat, xkb_symbols sections. |
| TODO |