*
* The context contains various general library data and state, like
* logging level and include paths.
+ *
* Objects are created in a specific context, and multiple contexts may
- * coexist simultaneously. Objects from different contexts are completely
+ * coexist simultaneously. Objects from different contexts are completely
* separated and do not share any memory or state.
- * A context is created, accessed, manipulated and destroyed through the
- * xkb_context_*() API.
*/
struct xkb_context;
*
* A keymap is immutable after it is created (besides reference counts, etc.);
* if you need to change it, you must create a new one.
- *
- * A keymap object is created, accessed and destroyed through the
- * xkb_keymap_*() API.
*/
struct xkb_keymap;
* Opaque keyboard state object.
*
* State objects contain the active state of a keyboard (or keyboards), such
- * as the currently effective layout and the active modifiers. It acts as a
+ * as the currently effective layout and the active modifiers. It acts as a
* simple state machine, wherein key presses and releases are the input, and
* key symbols (keysyms) are the output.
- *
- * A state object is created, accessed, manipulated and destroyed through the
- * xkb_state_*() API.
*/
struct xkb_state;
* Keymaps and applications which are compatible with X11 should not use
* these keycodes.
*
- * @todo Explain how keycodes are mapped to scancodes.
+ * The values of specific keycodes are determined by the keymap and the
+ * underlying input system. For example, with an X11-compatible keymap
+ * and Linux evdev scan codes (see linux/input.h), a fixed offset is used:
+ *
+ * @code
+ * xkb_keycode_t keycode_A = KEY_A + 8;
+ * @endcode
*
* @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
*/
typedef uint32_t xkb_keycode_t;
/**
- * A number used to represent the symbols visible on the keycaps of a
- * keyboard.
+ * A number used to represent the symbols generated from a key on a keyboard.
*
* A key, represented by a keycode, may generate different symbols according
* to keyboard state. For example, on a QWERTY keyboard, pressing the key
typedef uint32_t xkb_keysym_t;
/**
- * Index of a modifier.
- *
- * @todo Explain what are modifiers.
- *
- * Modifier indexes are consecutive. The first modifier has index 0.
- *
- * Each modifier must have a name, and the names are unique. Therefore, it
- * is safe to use the name as a unique identifier for a modifier. Modifier
- * names are case-sensitive.
- *
- * @sa xkb_keymap_num_mods()
- */
-typedef uint32_t xkb_mod_index_t;
-/** A mask of modifier indexes. */
-typedef uint32_t xkb_mod_mask_t;
-
-/**
* Index of a keyboard layout.
*
- * @todo Explain what are layouts.
+ * The layout index is a state component which detemines which <em>keyboard
+ * layout</em> is active. These may be different alphabets, different key
+ * arrangements, etc.
*
* Layout indexes are consecutive. The first layout has index 0.
*
typedef uint32_t xkb_level_index_t;
/**
+ * Index of a modifier.
+ *
+ * A @e modifier is a state component which changes the way keys are
+ * interpreted. A keymap defines a set of modifiers, such as Alt, Shift,
+ * Num Lock or Meta, and specifies which keys may @e activate which
+ * modifiers (in a many-to-many relationship, i.e. a key can activate
+ * several modifiers, and a modifier may be activated by several keys.
+ * Different keymaps do this differently).
+ *
+ * When retrieving the keysyms for a key, the active modifier set is
+ * consulted; this detemines the correct shift level to use within the
+ * currently active layout (see xkb_level_index_t).
+ *
+ * Modifier indexes are consecutive. The first modifier has index 0.
+ *
+ * Each modifier must have a name, and the names are unique. Therefore, it
+ * is safe to use the name as a unique identifier for a modifier. The names
+ * of some common modifiers are provided in the xkbcommon/xkbcommon-names.h
+ * header file. Modifier names are case-sensitive.
+ *
+ * @sa xkb_keymap_num_mods()
+ */
+typedef uint32_t xkb_mod_index_t;
+/** A mask of modifier indexes. */
+typedef uint32_t xkb_mod_mask_t;
+
+/**
* Index of a keyboard LED.
*
* @todo Explain what are LEDs.
*
* LED indexes are non-consecutive. The first LED has index 0.
*
- * LED names are case-sensitive.
- *
* Each LED must have a name, and the names are unique. Therefore,
- * it is safe to use the name as a unique identifier for a LED.
+ * it is safe to use the name as a unique identifier for a LED. The names
+ * of some common LEDs are provided in the xkbcommon/xkbcommon-names.h
+ * header file. LED names are case-sensitive.
*
* @warning A given keymap may specify an exact index for a given LED.
* Therefore, LED indexing is not necessarily sequential, as opposed to
/** A mask of LED indexes. */
typedef uint32_t xkb_led_mask_t;
-#define XKB_MOD_INVALID (0xffffffff)
-#define XKB_LAYOUT_INVALID (0xffffffff)
#define XKB_KEYCODE_INVALID (0xffffffff)
+#define XKB_LAYOUT_INVALID (0xffffffff)
#define XKB_LEVEL_INVALID (0xffffffff)
+#define XKB_MOD_INVALID (0xffffffff)
#define XKB_LED_INVALID (0xffffffff)
#define XKB_KEYCODE_MAX (0xffffffff - 1)
* function allows you to replace the default behavior with a custom
* handler. The handler is only called with messages which match the
* current logging level and verbosity settings for the context.
- * level is the logging level of the message. \c format and \c args are
+ * level is the logging level of the message. @a format and @a args are
* the same as in the vprintf(3) function.
*
* You may use xkb_context_set_user_data() on the context, and then call
const struct xkb_rule_names *names,
enum xkb_keymap_compile_flags flags);
-/** The possible keymap text formats. */
+/** The possible keymap formats. */
enum xkb_keymap_format {
/** The current/classic XKB text format, as generated by xkbcomp -xkb. */
XKB_KEYMAP_FORMAT_TEXT_V1 = 1
* the update. If nothing in the state has changed, returns 0.
*
* @memberof xkb_state
+ *
+ * @sa xkb_state_component
*/
enum xkb_state_component
xkb_state_update_mask(struct xkb_state *state,
projects / platform / upstream / libxkbcommon.git / commitdiff