From e43f53a6986a1870bd75a58a82bde2fc957ed3f5 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Thu, 11 Oct 2012 14:03:03 +0200 Subject: [PATCH] compat: add documentation for interpret's Signed-off-by: Ran Benita --- src/xkbcomp/compat.c | 81 ++++++++++++++++++++++++++++++++++++++++++++++---- src/xkbcomp/keycodes.c | 2 +- 2 files changed, 76 insertions(+), 7 deletions(-) diff --git a/src/xkbcomp/compat.c b/src/xkbcomp/compat.c index bb64ec8..176a4ef 100644 --- a/src/xkbcomp/compat.c +++ b/src/xkbcomp/compat.c @@ -57,28 +57,97 @@ /* * The xkb_compat section * ===================== - * This section is the third to be processesed, after xkb_keycodes and + * 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 symbols.c) allows the keymap author to do, + * among other things, the following 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 failes. 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 modifers 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 usign AnyOfOrNone while + * specifying all modifiers. Leaving out just the matching condtition + * 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 statment may include statements of the following - * forms: + * 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 + * conjuction 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; * - * - useModMapMods statement: - * useModMapMods = level1; + * Set whether the key should repeat or not. Must be a boolean value. * * Indicator map statements * ------------------------ @@ -107,7 +176,7 @@ * base, latched, locked, effective * any (i.e. all of the above) * none (i.e. none of the above) - * compat (this is legal, but unused) + * 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. @@ -153,7 +222,7 @@ * After all of the xkb_compat sections have been compiled, the following * members of struct xkb_keymap are finalized: * darray(struct xkb_sym_interpret) sym_interpret; - * struct xkb_indicator_map indicators[XKB_NUM_INDICATORS]; + * darray(struct xkb_indicator_map) indicators; * char *compat_section_name; * TODO: virtual modifiers. */ diff --git a/src/xkbcomp/keycodes.c b/src/xkbcomp/keycodes.c index f2a5e09..91e2368 100644 --- a/src/xkbcomp/keycodes.c +++ b/src/xkbcomp/keycodes.c @@ -95,7 +95,7 @@ * darray(struct xkb_key_alias) key_aliases; * char *keycodes_section_name; * The 'name' field of indicators declared in xkb_keycodes: - * struct xkb_indicator_map indicators[XKB_NUM_INDICATORS]; + * darray(struct xkb_indicator_map) indicators; * Further, the array of keys: * struct xkb_key *keys; * had been resized to its final size (i.e. all of the xkb_key objects are -- 2.7.4