libxkbcommon  0.3.2
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_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)
 
#define xkb_keycode_is_legal_ext(key)   (key <= XKB_KEYCODE_MAX)
 Test whether a value is a valid extended keycode. More...
 
#define xkb_keycode_is_legal_x11(key)   (key >= 8 && key <= 255)
 Test whether a value is a valid X11 keycode. More...
 
#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. More...
 

Typedefs

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

Enumerations

enum  xkb_keysym_flags {
  XKB_KEYSYM_NO_FLAGS = 0,
  XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0)
}
 Flags for xkb_keysym_from_name(). More...
 
enum  xkb_context_flags {
  XKB_CONTEXT_NO_FLAGS = 0,
  XKB_CONTEXT_NO_DEFAULT_INCLUDES = (1 << 0),
  XKB_CONTEXT_NO_ENVIRONMENT_NAMES = (1 << 1)
}
 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_NO_FLAGS = 0,
  XKB_MAP_COMPILE_PLACEHOLDER = 0
}
 Flags for keymap compilation. More...
 
enum  xkb_keymap_format { XKB_KEYMAP_FORMAT_TEXT_V1 = 1 }
 The possible keymap 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. More...
 
xkb_keysym_t xkb_keysym_from_name (const char *name, enum xkb_keysym_flags flags)
 Get a keysym from its name. More...
 
int xkb_keysym_to_utf8 (xkb_keysym_t keysym, char *buffer, size_t size)
 Get the Unicode/UTF-8 representation of a keysym. More...
 
uint32_t xkb_keysym_to_utf32 (xkb_keysym_t keysym)
 Get the Unicode/UTF-32 representation of a keysym. More...
 

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.

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:

* xkb_keycode_t keycode_A = KEY_A + 8;
*
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 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 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_layout_index_t

Index of a keyboard layout.

The layout index is a state component which detemines which keyboard layout is active. These may be different alphabets, different key arrangements, etc.

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

Each layout is not required to have a name, and the names are not 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 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 indices.

typedef uint32_t xkb_level_index_t

Index of a shift level.

Any key, in any layout, can have several shift levels. Each shift level can assign different keysyms to the key. The shift level to use is chosen according to the current keyboard state; for example, if no keys are pressed, the first level may be used; if the Left Shift key is pressed, the second; if Num Lock is pressed, the third; and many such combinations are possible (see xkb_mod_index_t).

Level indices are consecutive. The first level has index 0.

typedef uint32_t xkb_mod_index_t

Index of a modifier.

A 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 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 indices 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.

See Also
xkb_keymap_num_mods()
typedef uint32_t xkb_mod_mask_t

A mask of modifier indices.

typedef uint32_t xkb_led_index_t

Index of a keyboard LED.

LEDs are logical objects which may be active or inactive. They typically correspond to the lights on the keyboard. Their state is determined by the current keyboard state.

LED indices are non-consecutive. The first LED has index 0.

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. 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 modifiers and layouts. This means that when iterating over the LEDs in a keymap using e.g. xkb_keymap_num_leds(), some indices 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 indices.