xkbcommon.h   xkbcommon.h 
skipping to change at line 106 skipping to change at line 106
* @file * @file
* Main libxkbcommon API. * Main libxkbcommon API.
*/ */
/** /**
* @struct xkb_context * @struct xkb_context
* Opaque top level library context object. * Opaque top level library context object.
* *
* The context contains various general library data and state, like * The context contains various general library data and state, like
* logging level and include paths. * logging level and include paths.
*
* Objects are created in a specific context, and multiple contexts may * 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. * 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; struct xkb_context;
/** /**
* @struct xkb_keymap * @struct xkb_keymap
* Opaque compiled keymap object. * Opaque compiled keymap object.
* *
* The keymap object holds all of the static keyboard information obtained * The keymap object holds all of the static keyboard information obtained
* from compiling XKB files. * from compiling XKB files.
* *
* A keymap is immutable after it is created (besides reference counts, etc .); * A keymap is immutable after it is created (besides reference counts, etc .);
* if you need to change it, you must create a new one. * 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; struct xkb_keymap;
/** /**
* @struct xkb_state * @struct xkb_state
* Opaque keyboard state object. * Opaque keyboard state object.
* *
* State objects contain the active state of a keyboard (or keyboards), suc h * State objects contain the active state of a keyboard (or keyboards), suc h
* 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, an d * simple state machine, wherein key presses and releases are the input, an d
* key symbols (keysyms) are the output. * key symbols (keysyms) are the output.
*
* A state object is created, accessed, manipulated and destroyed through t
he
* xkb_state_*() API.
*/ */
struct xkb_state; struct xkb_state;
/** /**
* A number used to represent a physical key on a keyboard. * A number used to represent a physical key on a keyboard.
* *
* A standard PC-compatible keyboard might have 102 keys. An appropriate * A standard PC-compatible keyboard might have 102 keys. An appropriate
* keymap would assign each of them a keycode, by which the user should * keymap would assign each of them a keycode, by which the user should
* refer to the key throughout the library. * refer to the key throughout the library.
* *
* Historically, the X11 protocol, and consequentially the XKB protocol, * Historically, the X11 protocol, and consequentially the XKB protocol,
* assign only 8 bits for keycodes. This limits the number of different * assign only 8 bits for keycodes. This limits the number of different
* keys that can be used simultaneously in a single keymap to 256 * keys that can be used simultaneously in a single keymap to 256
* (disregarding other limitations). This library does not share this limi t; * (disregarding other limitations). This library does not share this limi t;
* keycodes beyond 255 ('extended keycodes') are not treated specially. * keycodes beyond 255 ('extended keycodes') are not treated specially.
* Keymaps and applications which are compatible with X11 should not use * Keymaps and applications which are compatible with X11 should not use
* these keycodes. * 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() * @sa xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()
*/ */
typedef uint32_t xkb_keycode_t; typedef uint32_t xkb_keycode_t;
/** /**
* A number used to represent the symbols visible on the keycaps of a * A number used to represent the symbols generated from a key on a keyboar
* keyboard. d.
* *
* A key, represented by a keycode, may generate different symbols accordin g * A key, represented by a keycode, may generate different symbols accordin g
* to keyboard state. For example, on a QWERTY keyboard, pressing the key * to keyboard state. For example, on a QWERTY keyboard, pressing the key
* labled \<A\> generates the symbol 'a'. If the Shift key is held, it * labled \<A\> generates the symbol 'a'. If the Shift key is held, it
* generates the symbol 'A'. If a different layout is used, say Greek, * generates the symbol 'A'. If a different layout is used, say Greek,
* it generates the symbol 'α'. And so on. * it generates the symbol 'α'. And so on.
* *
* Each such symbol is represented by a keysym. Note that keysyms are * Each such symbol is represented by a keysym. Note that keysyms are
* somewhat more general, in that they can also represent some "function", * somewhat more general, in that they can also represent some "function",
* such as "Left" or "Right" for the arrow keys. For more information, * such as "Left" or "Right" for the arrow keys. For more information,
* see: * see:
* http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_enc oding * http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_enc oding
* *
* Specifically named keysyms can be found in the * Specifically named keysyms can be found in the
* xkbcommon/xkbcommon-keysyms.h header file. Their name does not include * xkbcommon/xkbcommon-keysyms.h header file. Their name does not include
* the XKB_KEY_ prefix. * the XKB_KEY_ prefix.
* *
* Besides those, any Unicode/ISO 10646 character in the range U0100 to * Besides those, any Unicode/ISO 10646 character in the range U0100 to
* U10FFFF can be represented by a keysym value in the range 0x01000100 to * U10FFFF can be represented by a keysym value in the range 0x01000100 to
* 0x0110FFFF. The name of Unicode keysyms is "U<codepoint>", e.g. "Ua1b2" . * 0x0110FFFF. The name of Unicode keysyms is "U<codepoint>", e.g. "UA1B2" .
* *
* The name of other unnamed keysyms is the hexadecimal representation of * The name of other unnamed keysyms is the hexadecimal representation of
* their value, e.g. "0xabcd1234". * their value, e.g. "0xabcd1234".
* *
* Keysym names are case-sensitive. * Keysym names are case-sensitive.
*/ */
typedef uint32_t xkb_keysym_t; 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. * 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. * Layout indexes are consecutive. The first layout has index 0.
* *
* Each layout is not required to have a name, and the names are not * Each layout is not required to have a name, and the names are not
* guarenteed to be unique (though they are usually provided and unique). * guaranteed to be unique (though they are usually provided and unique).
* Therefore, it is not safe to use the name as a unique identifier for a * Therefore, it is not safe to use the name as a unique identifier for a
* layout. Layout names are case-sensitive. * layout. Layout names are case-sensitive.
* *
* Layouts are also called "groups" by XKB. * Layouts are also called "groups" by XKB.
* *
* @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key() * @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
*/ */
typedef uint32_t xkb_layout_index_t; typedef uint32_t xkb_layout_index_t;
/** A mask of layout indexes. */ /** A mask of layout indexes. */
typedef uint32_t xkb_layout_mask_t; typedef uint32_t xkb_layout_mask_t;
/** /**
* Index of a shift level. * Index of a shift level.
* *
* @todo Explain what are shift levels. * @todo Explain what are shift levels.
*/ */
typedef uint32_t xkb_level_index_t; 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 name
s
* 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. * Index of a keyboard LED.
* *
* @todo Explain what are LEDs. * @todo Explain what are LEDs.
* *
* LED indexes are non-consecutive. The first LED has index 0. * 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, * 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. * @warning A given keymap may specify an exact index for a given LED.
* Therefore, LED indexing is not necessarily sequential, as opposed to * Therefore, LED indexing is not necessarily sequential, as opposed to
* modifiers and layouts. This means that when iterating over the LEDs * modifiers and layouts. This means that when iterating over the LEDs
* in a keymap using e.g. xkb_keymap_num_leds(), some indexes might be * in a keymap using e.g. xkb_keymap_num_leds(), some indexes might be
* invalid. Given such an index, functions like xkb_keymap_led_get_name() * invalid. Given such an index, functions like xkb_keymap_led_get_name()
* will return NULL, and xkb_state_led_index_is_active() will return -1. * will return NULL, and xkb_state_led_index_is_active() will return -1.
* *
* LEDs are also called "indicators" by XKB. * LEDs are also called "indicators" by XKB.
* *
* @sa xkb_keymap_num_leds() * @sa xkb_keymap_num_leds()
*/ */
typedef uint32_t xkb_led_index_t; typedef uint32_t xkb_led_index_t;
/** A mask of LED indexes. */ /** A mask of LED indexes. */
typedef uint32_t xkb_led_mask_t; typedef uint32_t xkb_led_mask_t;
#define XKB_MOD_INVALID (0xffffffff)
#define XKB_LAYOUT_INVALID (0xffffffff)
#define XKB_KEYCODE_INVALID (0xffffffff) #define XKB_KEYCODE_INVALID (0xffffffff)
#define XKB_LAYOUT_INVALID (0xffffffff)
#define XKB_LEVEL_INVALID (0xffffffff) #define XKB_LEVEL_INVALID (0xffffffff)
#define XKB_MOD_INVALID (0xffffffff)
#define XKB_LED_INVALID (0xffffffff) #define XKB_LED_INVALID (0xffffffff)
#define XKB_KEYCODE_MAX (0xffffffff - 1) #define XKB_KEYCODE_MAX (0xffffffff - 1)
/** /**
* Test whether a value is a valid extended keycode. * Test whether a value is a valid extended keycode.
* @sa xkb_keycode_t * @sa xkb_keycode_t
**/ **/
#define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX) #define xkb_keycode_is_legal_ext(key) (key <= XKB_KEYCODE_MAX)
skipping to change at line 300 skipping to change at line 310
* If any of the members is NULL or an empty string (""), a default value i s * If any of the members is NULL or an empty string (""), a default value i s
* used. It is recommended to use the system default by passing NULL for * used. It is recommended to use the system default by passing NULL for
* unspecified values, instead of providing your own defaults. * unspecified values, instead of providing your own defaults.
*/ */
struct xkb_rule_names { struct xkb_rule_names {
/** The rules file to use. The rules file describes how to interpret /** The rules file to use. The rules file describes how to interpret
* the values of the model, layout, variant and options fields. */ * the values of the model, layout, variant and options fields. */
const char *rules; const char *rules;
/** The keyboard model by which to interpret keycodes and LEDs. */ /** The keyboard model by which to interpret keycodes and LEDs. */
const char *model; const char *model;
/** A comma seperated list of layouts (languages) to include in the /** A comma separated list of layouts (languages) to include in the
* keymap. */ * keymap. */
const char *layout; const char *layout;
/** A comma seperated list of variants, one per layout, which may /** A comma separated list of variants, one per layout, which may
* modify or augment the respective layout in various ways. */ * modify or augment the respective layout in various ways. */
const char *variant; const char *variant;
/** A comma seprated list of options, through which the user specifies /** A comma separated list of options, through which the user specifies
* non-layout related preferences, like which key combinations are use d * non-layout related preferences, like which key combinations are use d
* for switching layouts, or which key is the Compose key. */ * for switching layouts, or which key is the Compose key. */
const char *options; const char *options;
}; };
/** /**
* @defgroup keysyms Keysyms * @defgroup keysyms Keysyms
* Utility functions related to keysyms. * Utility functions related to keysyms.
* *
* @{ * @{
skipping to change at line 334 skipping to change at line 344
* @param[in] keysym The keysym. * @param[in] keysym The keysym.
* @param[out] buffer A string buffer to write the name into. * @param[out] buffer A string buffer to write the name into.
* @param[in] size Size of the buffer. * @param[in] size Size of the buffer.
* *
* @warning If the buffer passed is too small, the string is truncated * @warning If the buffer passed is too small, the string is truncated
* (though still NUL-terminated); a size of at least 64 bytes is recommende d. * (though still NUL-terminated); a size of at least 64 bytes is recommende d.
* *
* @returns The number of bytes in the name, excluding the NUL byte. If * @returns The number of bytes in the name, excluding the NUL byte. If
* the keysym is invalid, returns -1. * the keysym is invalid, returns -1.
* *
* You may check if truncation has occured by comparing the return value * You may check if truncation has occurred by comparing the return value
* with the length of buffer, similarly to the snprintf(3) function. * with the length of buffer, similarly to the snprintf(3) function.
* *
* @sa xkb_keysym_t * @sa xkb_keysym_t
*/ */
int int
xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size); xkb_keysym_get_name(xkb_keysym_t keysym, char *buffer, size_t size);
/** Flags for xkb_keysym_from_name(). */ /** Flags for xkb_keysym_from_name(). */
enum xkb_keysym_flags { enum xkb_keysym_flags {
/** Find keysym by case-insensitive search. */ /** Find keysym by case-insensitive search. */
XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0), XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
}; };
/** /**
* Get a keysym from its name. * Get a keysym from its name.
* *
* @param name The name of a keysym. See remarks in xkb_keysym_get_name(); * @param name The name of a keysym. See remarks in xkb_keysym_get_name();
* this function will accept any name returned by that function. * this function will accept any name returned by that function.
* @param flags A set of flags controlling how the search is done. If * @param flags A set of flags controlling how the search is done. If
* invalid flags are passed, this will fail with XKB_KEY_NoSymbol. * invalid flags are passed, this will fail with XKB_KEY_NoSymbol.
* *
skipping to change at line 378 skipping to change at line 388
xkb_keysym_t xkb_keysym_t
xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags); xkb_keysym_from_name(const char *name, enum xkb_keysym_flags flags);
/** /**
* Get the Unicode/UTF-8 representation of a keysym. * Get the Unicode/UTF-8 representation of a keysym.
* *
* @param[in] keysym The keysym. * @param[in] keysym The keysym.
* @param[out] buffer A buffer to write the UTF-8 string into. * @param[out] buffer A buffer to write the UTF-8 string into.
* @param[in] size The size of buffer. Must be at least 7. * @param[in] size The size of buffer. Must be at least 7.
* *
* @returns The number of bytes written to the buffer. If the keysym does * @returns The number of bytes written to the buffer (including the
* not have a Unicode representation, returns 0. If the buffer is too smal * terminating byte). If the keysym does not have a Unicode
l, * representation, returns 0. If the buffer is too small, returns -1.
* returns -1.
*/ */
int int
xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size); xkb_keysym_to_utf8(xkb_keysym_t keysym, char *buffer, size_t size);
/** /**
* Get the Unicode/UTF-32 representation of a keysym. * Get the Unicode/UTF-32 representation of a keysym.
* *
* @returns The Unicode/UTF-32 representation of keysym, which is also * @returns The Unicode/UTF-32 representation of keysym, which is also
* compatible with UCS-4. If the keysym does not have a Unicode * compatible with UCS-4. If the keysym does not have a Unicode
* representation, returns 0. * representation, returns 0.
skipping to change at line 411 skipping to change at line 421
* Every keymap compilation request must have a context associated with * Every keymap compilation request must have a context associated with
* it. The context keeps around state such as the include path. * it. The context keeps around state such as the include path.
* *
* @{ * @{
*/ */
/** Flags for context creation. */ /** Flags for context creation. */
enum xkb_context_flags { enum xkb_context_flags {
/** Create this context with an empty include path. */ /** Create this context with an empty include path. */
XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0), XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
/** Don't take RMLVO names from the environment. */
XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1),
}; };
/** /**
* Create a new context. * Create a new context.
* *
* @param flags Optional flags for the context, or 0. * @param flags Optional flags for the context, or 0.
* *
* @returns A new context, or NULL on failure. * @returns A new context, or NULL on failure.
* *
* The user may set some environment variables to affect default values in * The user may set some environment variables to affect default values in
skipping to change at line 442 skipping to change at line 454
* @returns The passed in context. * @returns The passed in context.
* *
* @memberof xkb_context * @memberof xkb_context
*/ */
struct xkb_context * struct xkb_context *
xkb_context_ref(struct xkb_context *context); xkb_context_ref(struct xkb_context *context);
/** /**
* Release a reference on a context, and possibly free it. * Release a reference on a context, and possibly free it.
* *
* @param context The context. If it is NULL, this function does nothing.
*
* @memberof xkb_context * @memberof xkb_context
*/ */
void void
xkb_context_unref(struct xkb_context *context); xkb_context_unref(struct xkb_context *context);
/** /**
* Store custom user data in the context. * Store custom user data in the context.
* *
* This may be useful in conjuction with xkb_context_set_log_fn() or other * This may be useful in conjunction with xkb_context_set_log_fn() or other
* callbacks. * callbacks.
* *
* @memberof xkb_context * @memberof xkb_context
*/ */
void void
xkb_context_set_user_data(struct xkb_context *context, void *user_data); xkb_context_set_user_data(struct xkb_context *context, void *user_data);
/** /**
* Retrieves stored user data from the context. * Retrieves stored user data from the context.
* *
skipping to change at line 561 skipping to change at line 575
* *
* @{ * @{
*/ */
/** Specifies a logging level. */ /** Specifies a logging level. */
enum xkb_log_level { enum xkb_log_level {
XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */ XKB_LOG_LEVEL_CRITICAL = 10, /**< Log critical internal errors only. */
XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */ XKB_LOG_LEVEL_ERROR = 20, /**< Log all errors. */
XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */ XKB_LOG_LEVEL_WARNING = 30, /**< Log warnings and errors. */
XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors . */ XKB_LOG_LEVEL_INFO = 40, /**< Log information, warnings, and errors . */
XKB_LOG_LEVEL_DEBUG = 50, /**< Log everything. */ XKB_LOG_LEVEL_DEBUG = 50 /**< Log everything. */
}; };
/** /**
* Set the current logging level. * Set the current logging level.
* *
* @param context The context in which to set the logging level. * @param context The context in which to set the logging level.
* @param level The logging level to use. Only messages from this level * @param level The logging level to use. Only messages from this level
* and below will be logged. * and below will be logged.
* *
* The default level is XKB_LOG_LEVEL_ERROR. The environment variable * The default level is XKB_LOG_LEVEL_ERROR. The environment variable
skipping to change at line 630 skipping to change at line 644
* Set a custom function to handle logging messages. * Set a custom function to handle logging messages.
* *
* @param context The context in which to use the set logging function. * @param context The context in which to use the set logging function.
* @param log_fn The function that will be called for logging messages. * @param log_fn The function that will be called for logging messages.
* Passing NULL restores the default function, which logs to stderr. * Passing NULL restores the default function, which logs to stderr.
* *
* By default, log messages from this library are printed to stderr. This * By default, log messages from this library are printed to stderr. This
* function allows you to replace the default behavior with a custom * function allows you to replace the default behavior with a custom
* handler. The handler is only called with messages which match the * handler. The handler is only called with messages which match the
* current logging level and verbosity settings for the context. * current logging level and verbosity settings for the context.
* level is the logging level of the message. format and args are the * level is the logging level of the message. @a format and @a args are
* same as in the vprintf(3) function. * the same as in the vprintf(3) function.
* *
* You may use xkb_context_set_user_data() on the context, and then call * You may use xkb_context_set_user_data() on the context, and then call
* xkb_context_get_user_data() from within the logging function to provide * xkb_context_get_user_data() from within the logging function to provide
* it with additional private context. * it with additional private context.
* *
* @memberof xkb_context * @memberof xkb_context
*/ */
void void
xkb_context_set_log_fn(struct xkb_context *context, xkb_context_set_log_fn(struct xkb_context *context,
void (*log_fn)(struct xkb_context *context, void (*log_fn)(struct xkb_context *context,
skipping to change at line 657 skipping to change at line 671
/** /**
* @defgroup keymap Keymap Creation * @defgroup keymap Keymap Creation
* Creating and destroying keymaps. * Creating and destroying keymaps.
* *
* @{ * @{
*/ */
/** Flags for keymap compilation. */ /** Flags for keymap compilation. */
enum xkb_keymap_compile_flags { enum xkb_keymap_compile_flags {
/** Apparently you can't have empty enums. What a drag. */ /** Apparently you can't have empty enums. What a drag. */
XKB_MAP_COMPILE_PLACEHOLDER = 0, XKB_MAP_COMPILE_PLACEHOLDER = 0
}; };
/** /**
* Create a keymap from RMLVO names. * Create a keymap from RMLVO names.
* *
* The primary keymap entry point: creates a new XKB keymap from a set of * The primary keymap entry point: creates a new XKB keymap from a set of
* RMLVO (Rules + Model + Layouts + Variants + Options) names. * RMLVO (Rules + Model + Layouts + Variants + Options) names.
* *
* You should almost certainly be using this and nothing else to create * You should almost certainly be using this and nothing else to create
* keymaps. * keymaps.
* *
* @param context The context in which to create the keymap. * @param context The context in which to create the keymap.
* @param names The RMLVO names to use. * @param names The RMLVO names to use. In xkbcommon versions prior
* to 0.2.1, this field must be non-NULL. In later
* versions, passing NULL will use the default keymap.
* @param flags Optional flags for the keymap, or 0. * @param flags Optional flags for the keymap, or 0.
* *
* @returns A keymap compiled according to the RMLVO names, or NULL if * @returns A keymap compiled according to the RMLVO names, or NULL if
* the compilation failed. * the compilation failed.
* *
* @sa xkb_rule_names * @sa xkb_rule_names
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
struct xkb_keymap * struct xkb_keymap *
xkb_keymap_new_from_names(struct xkb_context *context, xkb_keymap_new_from_names(struct xkb_context *context,
const struct xkb_rule_names *names, const struct xkb_rule_names *names,
enum xkb_keymap_compile_flags flags); enum xkb_keymap_compile_flags flags);
/** The possible keymap text formats. */ /** The possible keymap formats. */
enum xkb_keymap_format { enum xkb_keymap_format {
/** The current/classic XKB text format, as generated by xkbcomp -xkb. */ /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
XKB_KEYMAP_FORMAT_TEXT_V1 = 1, XKB_KEYMAP_FORMAT_TEXT_V1 = 1
}; };
/** /**
* Create a keymap from a keymap file. * Create a keymap from a keymap file.
* *
* @param context The context in which to create the keymap. * @param context The context in which to create the keymap.
* @param file The keymap file to compile. * @param file The keymap file to compile.
* @param format The text format of the keymap file to compile. * @param format The text format of the keymap file to compile.
* @param flags Optional flags for the keymap, or 0. * @param flags Optional flags for the keymap, or 0.
* *
skipping to change at line 728 skipping to change at line 744
* *
* @see xkb_keymap_new_from_string() * @see xkb_keymap_new_from_string()
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
struct xkb_keymap * struct xkb_keymap *
xkb_keymap_new_from_string(struct xkb_context *context, const char *string, xkb_keymap_new_from_string(struct xkb_context *context, const char *string,
enum xkb_keymap_format format, enum xkb_keymap_format format,
enum xkb_keymap_compile_flags flags); enum xkb_keymap_compile_flags flags);
/** /**
* Create a keymap from a memory buffer.
*
* This is just like xkb_keymap_new_from_string(), but takes a length argum
ent
* so the input string does not have to be zero-terminated.
*
* @see xkb_keymap_new_from_string()
* @memberof xkb_keymap
*/
struct xkb_keymap *
xkb_keymap_new_from_buffer(struct xkb_context *context, const char *buffer,
size_t length, enum xkb_keymap_format format,
enum xkb_keymap_compile_flags flags);
/**
* Take a new reference on a keymap. * Take a new reference on a keymap.
* *
* @returns The passed in keymap. * @returns The passed in keymap.
* *
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
struct xkb_keymap * struct xkb_keymap *
xkb_keymap_ref(struct xkb_keymap *keymap); xkb_keymap_ref(struct xkb_keymap *keymap);
/** /**
* Release a reference on a keymap, and possibly free it. * Release a reference on a keymap, and possibly free it.
* *
* @param keymap The keymap. If it is NULL, this function does nothing.
*
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
void void
xkb_keymap_unref(struct xkb_keymap *keymap); xkb_keymap_unref(struct xkb_keymap *keymap);
/** /**
* Get the keymap as a string in the format from which it was created. * Get the keymap as a string in the format from which it was created.
* @sa xkb_keymap_get_as_string() * @sa xkb_keymap_get_as_string()
**/ **/
#define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1) #define XKB_KEYMAP_USE_ORIGINAL_FORMAT ((enum xkb_keymap_format) -1)
skipping to change at line 863 skipping to change at line 895
* *
* @sa xkb_layout_index_t * @sa xkb_layout_index_t
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
xkb_layout_index_t xkb_layout_index_t
xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key ); xkb_keymap_num_layouts_for_key(struct xkb_keymap *keymap, xkb_keycode_t key );
/** /**
* Get the number of shift levels for a specific key and layout. * Get the number of shift levels for a specific key and layout.
* *
* If @c layout is out of range for this key (that is, larger or equal to
* the value returned by xkb_keymap_num_layouts_for_key()), it is brought
* back into range in a manner consistent with xkb_state_key_get_layout().
*
* @sa xkb_level_index_t * @sa xkb_level_index_t
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
xkb_level_index_t xkb_level_index_t
xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key, xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
xkb_layout_index_t layout); xkb_layout_index_t layout);
/** /**
* Get the keysyms obtained from pressing a key in a given layout and * Get the keysyms obtained from pressing a key in a given layout and
* shift level. * shift level.
* *
* This function is like xkb_state_key_get_syms(), only the layout and * This function is like xkb_state_key_get_syms(), only the layout and
* shift level are not derived from the keyboard state but are instead * shift level are not derived from the keyboard state but are instead
* specified explicitly. * specified explicitly.
* *
* @param[in] keymap The keymap. * @param[in] keymap The keymap.
* @param[in] key The keycode of the key. * @param[in] key The keycode of the key.
* @param[in] layout The layout for which to get the keysyms. This must * @param[in] layout The layout for which to get the keysyms.
* be smaller than:
* @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
* Usually it would be:
* @code xkb_state_key_get_layout(state, key) @endcode
* @param[in] level The shift level in the layout for which to get the * @param[in] level The shift level in the layout for which to get the
* keysyms. This must be smaller than: * keysyms. This must be smaller than:
* @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode * @code xkb_keymap_num_layouts_for_key(keymap, key) @endcode
* usually it would be: * @param[out] syms_out An immutible array of keysyms corresponding to the
* @code xkb_state_key_get_level(state, key, layout) @endcode
* @param[out] syms_out An immutible array of keysyms corresponding the
* key in the given layout and shift level. * key in the given layout and shift level.
* *
* If @c layout is out of range for this key (that is, larger or equal to
* the value returned by xkb_keymap_num_layouts_for_key()), it is brought
* back into range in a manner consistent with xkb_state_key_get_layout().
*
* @returns The number of keysyms in the syms_out array. If no keysyms * @returns The number of keysyms in the syms_out array. If no keysyms
* are produced by the key in the given layout and shift level, returns 0 * are produced by the key in the given layout and shift level, returns 0
* and sets syms_out to NULL. * and sets syms_out to NULL.
* *
* @sa xkb_state_key_get_syms() * @sa xkb_state_key_get_syms()
* @memberof xkb_keymap * @memberof xkb_keymap
*/ */
int int
xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap, xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
xkb_keycode_t key, xkb_keycode_t key,
skipping to change at line 994 skipping to change at line 1028
* @returns The passed in object. * @returns The passed in object.
* *
* @memberof xkb_state * @memberof xkb_state
*/ */
struct xkb_state * struct xkb_state *
xkb_state_ref(struct xkb_state *state); xkb_state_ref(struct xkb_state *state);
/** /**
* Release a reference on a keybaord state object, and possibly free it. * Release a reference on a keybaord state object, and possibly free it.
* *
* @param state The state. If it is NULL, this function does nothing.
*
* @memberof xkb_state * @memberof xkb_state
*/ */
void void
xkb_state_unref(struct xkb_state *state); xkb_state_unref(struct xkb_state *state);
/** /**
* Get the keymap from which a keyboard state object was created. * Get the keymap from which a keyboard state object was created.
* *
* @returns The keymap which was used in xkb_state_new() to create this * @returns The keymap which was used in xkb_state_new() to create this
* state object. * state object.
skipping to change at line 1017 skipping to change at line 1053
* lifetime of the state. * lifetime of the state.
* *
* @memberof xkb_state * @memberof xkb_state
*/ */
struct xkb_keymap * struct xkb_keymap *
xkb_state_get_keymap(struct xkb_state *state); xkb_state_get_keymap(struct xkb_state *state);
/** Specifies the direction of the key (press / release). */ /** Specifies the direction of the key (press / release). */
enum xkb_key_direction { enum xkb_key_direction {
XKB_KEY_UP, /**< The key was released. */ XKB_KEY_UP, /**< The key was released. */
XKB_KEY_DOWN, /**< The key was pressed. */ XKB_KEY_DOWN /**< The key was pressed. */
}; };
/** /**
* Modifier and layout types for state objects. This enum is bitmaskable, * Modifier and layout types for state objects. This enum is bitmaskable,
* e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to * e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to
* exclude locked modifiers. * exclude locked modifiers.
* *
* In XKB, the DEPRESSED components are also known as 'base'. * In XKB, the DEPRESSED components are also known as 'base'.
*/ */
enum xkb_state_component { enum xkb_state_component {
skipping to change at line 1051 skipping to change at line 1087
/** Latched layout, i.e. will be unset after the next non-modifier /** Latched layout, i.e. will be unset after the next non-modifier
* key press. */ * key press. */
XKB_STATE_LAYOUT_LATCHED = (1 << 5), XKB_STATE_LAYOUT_LATCHED = (1 << 5),
/** Locked layout, i.e. will be unset after the key provoking the lock /** Locked layout, i.e. will be unset after the key provoking the lock
* has been pressed again. */ * has been pressed again. */
XKB_STATE_LAYOUT_LOCKED = (1 << 6), XKB_STATE_LAYOUT_LOCKED = (1 << 6),
/** Effective layout, i.e. currently active and affects key processing /** Effective layout, i.e. currently active and affects key processing
* (derived from the other state components). */ * (derived from the other state components). */
XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7), XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
/** LEDs (derived from the other state components). */ /** LEDs (derived from the other state components). */
XKB_STATE_LEDS = (1 << 8), XKB_STATE_LEDS = (1 << 8)
}; };
/** /**
* Update the keyboard state to reflect a given key being pressed or * Update the keyboard state to reflect a given key being pressed or
* released. * released.
* *
* @returns A mask of state components that have changed as a result of * @returns A mask of state components that have changed as a result of
* the update. If nothing in the state has changed, returns 0. * the update. If nothing in the state has changed, returns 0.
* *
* @memberof xkb_state * @memberof xkb_state
skipping to change at line 1077 skipping to change at line 1113
/** /**
* Get the keysyms obtained from pressing a particular key in a given * Get the keysyms obtained from pressing a particular key in a given
* keyboard state. * keyboard state.
* *
* Get the keysyms for a key according to the current active layout, * Get the keysyms for a key according to the current active layout,
* modifiers and shift level for the key, as determined by a keyboard * modifiers and shift level for the key, as determined by a keyboard
* state. * state.
* *
* @param[in] state The keyboard state object. * @param[in] state The keyboard state object.
* @param[in] key The keycode of the key. * @param[in] key The keycode of the key.
* @param[out] syms_out An immutible array of keysyms corresponding the * @param[out] syms_out An immutable array of keysyms corresponding the
* key in the given keyboard state. * key in the given keyboard state.
* *
* As an extension to XKB, this function can return more than one keysym. * As an extension to XKB, this function can return more than one keysym.
* If you do not want to handle this case, you can use * If you do not want to handle this case, you can use
* xkb_state_key_get_one_sym(). * xkb_state_key_get_one_sym().
* *
* @returns The number of keysyms in the syms_out array. If no keysyms * @returns The number of keysyms in the syms_out array. If no keysyms
* are produced by the key in the given keyboard state, returns 0 and sets * are produced by the key in the given keyboard state, returns 0 and sets
* syms_out to NULL. * syms_out to NULL.
* *
skipping to change at line 1167 skipping to change at line 1203
* successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with * successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with
* the other modes. * the other modes.
*/ */
enum xkb_state_match { enum xkb_state_match {
/** Returns true if any of the modifiers are active. */ /** Returns true if any of the modifiers are active. */
XKB_STATE_MATCH_ANY = (1 << 0), XKB_STATE_MATCH_ANY = (1 << 0),
/** Returns true if all of the modifiers are active. */ /** Returns true if all of the modifiers are active. */
XKB_STATE_MATCH_ALL = (1 << 1), XKB_STATE_MATCH_ALL = (1 << 1),
/** Makes matching non-exclusive, i.e. will not return false if a /** Makes matching non-exclusive, i.e. will not return false if a
* modifier not specified in the arguments is active. */ * modifier not specified in the arguments is active. */
XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16), XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16)
}; };
/** /**
* Update a keyboard state from a set of explicit masks. * Update a keyboard state from a set of explicit masks.
* *
* This entrypoint is really only for window systems and the like, where a * This entry point is really only for window systems and the like, where a
* master process holds an xkb_state, then serializes it over a wire * master process holds an xkb_state, then serializes it over a wire
* protocol, and clients then use the serialization to feed in to their own * protocol, and clients then use the serialization to feed in to their own
* xkb_state. * xkb_state.
* *
* All parameters must always be passed, or the resulting state may be * All parameters must always be passed, or the resulting state may be
* incoherent. * incoherent.
* *
* The serialization is lossy and will not survive round trips; it must onl y * The serialization is lossy and will not survive round trips; it must onl y
* be used to feed slave state objects, and must not be used to update the * be used to feed slave state objects, and must not be used to update the
* master state. * master state.
* *
* Please do not use this unless you fit the description above. * Please do not use this unless you fit the description above.
* *
* @returns A mask of state components that have changed as a result of * @returns A mask of state components that have changed as a result of
* the update. If nothing in the state has changed, returns 0. * the update. If nothing in the state has changed, returns 0.
* *
* @memberof xkb_state * @memberof xkb_state
*
* @sa xkb_state_component
*/ */
enum xkb_state_component enum xkb_state_component
xkb_state_update_mask(struct xkb_state *state, xkb_state_update_mask(struct xkb_state *state,
xkb_mod_mask_t depressed_mods, xkb_mod_mask_t depressed_mods,
xkb_mod_mask_t latched_mods, xkb_mod_mask_t latched_mods,
xkb_mod_mask_t locked_mods, xkb_mod_mask_t locked_mods,
xkb_layout_index_t depressed_layout, xkb_layout_index_t depressed_layout,
xkb_layout_index_t latched_layout, xkb_layout_index_t latched_layout,
xkb_layout_index_t locked_layout); xkb_layout_index_t locked_layout);
skipping to change at line 1233 skipping to change at line 1271
/** /**
* The counterpart to xkb_state_update_mask for layouts, to be used on * The counterpart to xkb_state_update_mask for layouts, to be used on
* the server side of serialization. * the server side of serialization.
* *
* @param state The keyboard state. * @param state The keyboard state.
* @param components A mask of the layout state components to serialize. * @param components A mask of the layout state components to serialize.
* State components other than XKB_STATE_LAYOUT_* are ignored. * State components other than XKB_STATE_LAYOUT_* are ignored.
* If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components ar e * If XKB_STATE_LAYOUT_EFFECTIVE is included, all other state components ar e
* ignored. * ignored.
* *
* @returns A xkb_layout_mask_t representing the given components of the * @returns A layout index representing the given components of the
* layout state. * layout state.
* *
* This function should not be used in regular clients; please use the * This function should not be used in regular clients; please use the
* xkb_state_layout_*_is_active API instead. * xkb_state_layout_*_is_active API instead.
* *
* @memberof xkb_state * @memberof xkb_state
*/ */
xkb_layout_index_t xkb_layout_index_t
xkb_state_serialize_layout(struct xkb_state *state, xkb_state_serialize_layout(struct xkb_state *state,
enum xkb_state_component components); enum xkb_state_component components);
skipping to change at line 1327 skipping to change at line 1365
* a key. * a key.
* *
* Some functions, like xkb_state_key_get_syms(), look at the state of * Some functions, like xkb_state_key_get_syms(), look at the state of
* the modifiers in the keymap and derive from it the correct shift level * the modifiers in the keymap and derive from it the correct shift level
* to use for the key. For example, in a US layout, pressing the key * to use for the key. For example, in a US layout, pressing the key
* labeled \<A\> while the Shift modifier is active, generates the keysym ' A'. * labeled \<A\> while the Shift modifier is active, generates the keysym ' A'.
* In this case, the Shift modifier is said to be consumed. However, the * In this case, the Shift modifier is said to be consumed. However, the
* Num Lock modifier does not affect this translation at all, even if it * Num Lock modifier does not affect this translation at all, even if it
* active, so it is not consumed by this translation. * active, so it is not consumed by this translation.
* *
* It may be desireable for some application to not reuse consumed modifier * It may be desirable for some application to not reuse consumed modifiers
s * for further processing, e.g. for hotkeys or keyboard shortcuts. To
* for further processing, e.g. for hotkeys or keyboard shortcuts. * understand why, consider some requirements from a standard shortcut
* mechanism, and how they are implemented:
*
* 1. The shortcut's modifiers must match exactly to the state. For example
,
* it is possible to bind separate actions to \<Alt\>\<Tab\> and to
* \<Alt\>\<Shift\>\<Tab\>. Further, if only \<Alt\>\<Tab\> is bound to
* an action, pressing \<Alt\>\<Shift\>\<Tab\> should not trigger the
* shortcut.
* Effectively, this means that the modifiers are compared using the
* equality operator (==).
* 2. Only relevant modifiers are considered for the matching. For example,
* Caps Lock and Num Lock should not generally affect the matching, e.g.
* when matching \<Alt\>\<Tab\> against the state, it does not matter
* whether Num Lock is active or not. These relevant, or significant,
* modifiers usually include Alt, Control, Shift, Super and similar.
* Effectively, this means that non-significant modifiers are masked out
,
* before doing the comparison as described above.
* 3. The matching must be independent of the layout/keymap. For example,
* the \<Plus\> (+) symbol is found on the first level on some layouts,
* and requires holding Shift on others. If you simply bind the action
* to the \<Plus\> keysym, it would work for the unshifted kind, but
* not for the others, because the match against Shift would fail. If
* you bind the action to \<Shift\>\<Plus\>, only the shifted kind would
* work. So what is needed is to recognize that Shift is used up in the
* translation of the keysym itself, and therefore should not be include
d
* in the matching.
* Effectively, this means that consumed modifiers (Shift in this exampl
e)
* are masked out as well, before doing the comparison.
*
* To summarize, this is how the matching would be performed:
* @code
* (keysym == shortcut_keysym) &&
* ((state_modifiers & ~consumed_modifiers & significant_modifiers) == sh
ortcut_modifiers)
* @endcode
*
* @c state_modifiers are the modifiers reported by
* xkb_state_mod_index_is_active() and similar functions.
* @c consumed_modifiers are the modifiers reported by
* xkb_state_mod_index_is_consumed().
* @c significant_modifiers are decided upon by the application/toolkit/use
r;
* it is up to them to decide whether these are configurable or hard-coded.
* *
* @returns 1 if the modifier is consumed, 0 if it is not. If the modifier * @returns 1 if the modifier is consumed, 0 if it is not. If the modifier
* index is not valid in the keymap, returns -1. * index is not valid in the keymap, returns -1.
* *
* @sa xkb_state_mod_mask_remove_consumend() * @sa xkb_state_mod_mask_remove_consumed()
* @memberof xkb_state * @memberof xkb_state
*/ */
int int
xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key, xkb_state_mod_index_is_consumed(struct xkb_state *state, xkb_keycode_t key,
xkb_mod_index_t idx); xkb_mod_index_t idx);
/** /**
* Remove consumed modifiers from a modifier mask for a key. * Remove consumed modifiers from a modifier mask for a key.
* *
* Takes the given modifier mask, and removes all modifiers which are * Takes the given modifier mask, and removes all modifiers which are
 End of changes. 49 change blocks. 
74 lines changed or deleted 159 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/