From c548c815296465f3ce41d8171e9f9cc50607213f Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 28 Jul 2012 12:10:44 +0300 Subject: [PATCH] keycodes: add a general overview Signed-off-by: Ran Benita --- src/xkbcomp/keycodes.c | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/src/xkbcomp/keycodes.c b/src/xkbcomp/keycodes.c index fa93da5..f7d873c 100644 --- a/src/xkbcomp/keycodes.c +++ b/src/xkbcomp/keycodes.c @@ -28,6 +28,94 @@ #include "expr.h" #include "parseutils.h" +/* + * 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 + * of up to 4 letters, by which it can be referred to later, e.g. in the + * symbols section. + * + * Minimum/Maximum keycode + * ----------------------- + * Statements of the form: + * minimum = 8; + * maximum = 255; + * + * The file may explicitly declare the minimum and/or maximum keycode + * contained therein (traditionally 8-255, inherited from old xfree86 + * keycodes). If these are stated explicitly, they are enforced. If + * they are not stated, they are computed automatically. + * + * Keycode statements + * ------------------ + * Statements of the form: + * = 49; + * = 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 is + * always used to refer to a key by name. + * + * [ The naming convention just denoted the position of the key + * in the main alphanumric section of the keyboard, with the top left key + * (usually "~") acting as origin. is the key in the first row + * second column (which is usually "1"). ] + * + * 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 + * 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. + * + * The reason for the 4 characters limit is that the name is sometimes + * converted to an unsigned long (in a direct mapping), instead of a char + * array (see KeyNameToLong, LongToKeyName). + * + * Alias statements + * ---------------- + * Statements of the form: + * alias = ; + * + * Allows to refer to a previously defined key (here ) by another + * name (here ). Conflicts are handled similarly. + * + * Indicator name statements + * ------------------------- + * Statements of the form: + * indicator 1 = "Caps Lock"; + * indicator 2 = "Num Lock"; + * indicator 3 = "Scroll Lock"; + * + * Assigns a name the indicator (i.e. keyboard LED) with the given index. + * The amount of possible indicators is predetermined (XkbNumIndicators). + * The indicator may be referred by this name later in the compat section + * and by the user. + * + * Effect on the keymap + * -------------------- + * After all of keycodes sections have been compiled, the following members + * of struct xkb_keymap are finalized: + * xkb_keycode_t min_key_code; + * xkb_keycode_t max_key_code; + * darray(struct xkb_key_alias) key_aliases; + * const char *indicator_names[XkbNumIndicators]; + * char *keycodes_section_name; + * Further, the array of keys: + * darray(struct xkb_key) keys; + * had been resized to its final size (i.e. all of the xkb_key objects are + * referable by their keycode). However the objects themselves do not + * contain any useful information besides the key name at this point. + */ + typedef struct _AliasInfo { enum merge_mode merge; unsigned file_id; -- 2.7.4