xkbcommon.h File Reference

Main libxkbcommon API. More...

#include <stdint.h>
#include <stdio.h>
#include <stdarg.h>
#include <xkbcommon/xkbcommon-names.h>
#include <xkbcommon/xkbcommon-keysyms.h>
#include <xkbcommon/xkbcommon-compat.h>

Go to the source code of this file.

Data Structures
struct	xkb_rule_names
	Names to compile a keymap with, also known as RMLVO. More...

Macros
#define	XKB_MOD_INVALID   (0xffffffff)
#define	XKB_LAYOUT_INVALID   (0xffffffff)
#define	XKB_KEYCODE_INVALID   (0xffffffff)
#define	XKB_LEVEL_INVALID   (0xffffffff)
#define	XKB_LED_INVALID   (0xffffffff)
#define	XKB_KEYCODE_MAX   (0xffffffff - 1)
#define	xkb_keycode_is_legal_ext(key)   (key <= XKB_KEYCODE_MAX)
	Test whether a value is a valid extended keycode.
#define	xkb_keycode_is_legal_x11(key)   (key >= 8 && key <= 255)
	Test whether a value is a valid X11 keycode.
#define	XKB_KEYMAP_USE_ORIGINAL_FORMAT   ((enum xkb_keymap_format) -1)
	Get the keymap as a string in the format from which it was created.

Typedefs
typedef uint32_t	xkb_keycode_t
	A number used to represent a physical key on a keyboard.
typedef uint32_t	xkb_keysym_t
	A number used to represent the symbols visible on the keycaps of a keyboard.
typedef uint32_t	xkb_mod_index_t
	Index of a modifier.
typedef uint32_t	xkb_mod_mask_t
	A mask of modifier indexes.
typedef uint32_t	xkb_layout_index_t
	Index of a keyboard layout.
typedef uint32_t	xkb_layout_mask_t
	A mask of layout indexes.
typedef uint32_t	xkb_level_index_t
	Index of a shift level.
typedef uint32_t	xkb_led_index_t
	Index of a keyboard LED.
typedef uint32_t	xkb_led_mask_t
	A mask of LED indexes.

Enumerations
enum	xkb_keysym_flags { XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0) }
	Flags for xkb_keysym_from_name(). More...
enum	xkb_context_flags { XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0) }
	Flags for context creation. More...
enum	xkb_log_level {   XKB_LOG_LEVEL_CRITICAL = 10,   XKB_LOG_LEVEL_ERROR = 20,   XKB_LOG_LEVEL_WARNING = 30,   XKB_LOG_LEVEL_INFO = 40,   XKB_LOG_LEVEL_DEBUG = 50 }
	Specifies a logging level. More...
enum	xkb_keymap_compile_flags { XKB_MAP_COMPILE_PLACEHOLDER = 0 }
	Flags for keymap compilation. More...
enum	xkb_keymap_format { XKB_KEYMAP_FORMAT_TEXT_V1 = 1 }
	The possible keymap text formats. More...
enum	xkb_key_direction {   XKB_KEY_UP,   XKB_KEY_DOWN }
	Specifies the direction of the key (press / release). More...
enum	xkb_state_component {   XKB_STATE_MODS_DEPRESSED = (1 << 0),   XKB_STATE_MODS_LATCHED = (1 << 1),   XKB_STATE_MODS_LOCKED = (1 << 2),   XKB_STATE_MODS_EFFECTIVE = (1 << 3),   XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),   XKB_STATE_LAYOUT_LATCHED = (1 << 5),   XKB_STATE_LAYOUT_LOCKED = (1 << 6),   XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),   XKB_STATE_LEDS = (1 << 8) }
	Modifier and layout types for state objects. More...
enum	xkb_state_match {   XKB_STATE_MATCH_ANY = (1 << 0),   XKB_STATE_MATCH_ALL = (1 << 1),   XKB_STATE_MATCH_NON_EXCLUSIVE = (1 << 16) }
	Match flags for xkb_state_mod_indices_are_active and xkb_state_mod_names_are_active, specifying how the conditions for a successful match. More...

Functions
int	xkb_keysym_get_name (xkb_keysym_t keysym, char *buffer, size_t size)
	Get the name of a keysym.
xkb_keysym_t	xkb_keysym_from_name (const char *name, enum xkb_keysym_flags flags)
	Get a keysym from its name.
int	xkb_keysym_to_utf8 (xkb_keysym_t keysym, char *buffer, size_t size)
	Get the Unicode/UTF-8 representation of a keysym.
uint32_t	xkb_keysym_to_utf32 (xkb_keysym_t keysym)
	Get the Unicode/UTF-32 representation of a keysym.

Detailed Description

Main libxkbcommon API.

Macro Definition Documentation

#define xkb_keycode_is_legal_ext

(

key

)

(key <= XKB_KEYCODE_MAX)

Test whether a value is a valid extended keycode.

See Also

xkb_keycode_t

#define xkb_keycode_is_legal_x11

(

key

)

(key >= 8 && key <= 255)

Test whether a value is a valid X11 keycode.

See Also

xkb_keycode_t

Typedef Documentation

typedef uint32_t xkb_keycode_t

A number used to represent a physical key on a keyboard.

A standard PC-compatible keyboard might have 102 keys. An appropriate keymap would assign each of them a keycode, by which the user should refer to the key throughout the library.

Historically, the X11 protocol, and consequentially the XKB protocol, assign only 8 bits for keycodes. This limits the number of different keys that can be used simultaneously in a single keymap to 256 (disregarding other limitations). This library does not share this limit; keycodes beyond 255 ('extended keycodes') are not treated specially. Keymaps and applications which are compatible with X11 should not use these keycodes.

Todo:

Explain how keycodes are mapped to scancodes.

See Also

xkb_keycode_is_legal_ext() xkb_keycode_is_legal_x11()

typedef uint32_t xkb_keysym_t

A number used to represent the symbols visible on the keycaps of 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 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, it generates the symbol 'α'. And so on.

Each such symbol is represented by a keysym. Note that keysyms are somewhat more general, in that they can also represent some "function", such as "Left" or "Right" for the arrow keys. For more information, see: http://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#keysym_encoding

Specifically named keysyms can be found in the xkbcommon/xkbcommon-keysyms.h header file. Their name does not include the XKB_KEY_ prefix.

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 0x0110FFFF. The name of Unicode keysyms is "U<codepoint>", e.g. "Ua1b2".

The name of other unnamed keysyms is the hexadecimal representation of their value, e.g. "0xabcd1234".

Keysym names are case-sensitive.

typedef uint32_t xkb_mod_index_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.

See Also

xkb_keymap_num_mods()

typedef uint32_t xkb_mod_mask_t

A mask of modifier indexes.

typedef uint32_t xkb_layout_index_t

Index of a keyboard layout.

Todo:

Explain what are layouts.

Layout indexes are consecutive. The first layout has index 0.

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). Therefore, it is not safe to use the name as a unique identifier for a layout. Layout names are case-sensitive.

Layouts are also called "groups" by XKB.

See Also

xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()

typedef uint32_t xkb_layout_mask_t

A mask of layout indexes.

typedef uint32_t xkb_level_index_t

Index of a shift level.

Todo:

Explain what are shift levels.

typedef uint32_t xkb_led_index_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.

Warning

A given keymap may specify an exact index for a given LED. Therefore, LED indexing is not necessarily sequential, as opposed to 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 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.

LEDs are also called "indicators" by XKB.

See Also

xkb_keymap_num_leds()

typedef uint32_t xkb_led_mask_t

A mask of LED indexes.