diff options
Diffstat (limited to 'xkbcommon/doc/keymap-format-text-v1.txt')
| -rw-r--r-- | xkbcommon/doc/keymap-format-text-v1.txt | 359 |
1 files changed, 0 insertions, 359 deletions
diff --git a/xkbcommon/doc/keymap-format-text-v1.txt b/xkbcommon/doc/keymap-format-text-v1.txt deleted file mode 100644 index 95849fc..0000000 --- a/xkbcommon/doc/keymap-format-text-v1.txt +++ /dev/null @@ -1,359 +0,0 @@ -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 |