Keymap Components

Collaboration diagram for Keymap Components:

Data Structures
struct	xkb_keymap_key_iterator
struct	xkb_keymap_key_iterator_config

Typedefs
typedef void(*	xkb_keymap::xkb_keymap_key_iter_t) (struct xkb_keymap *keymap, xkb_keycode_t key, void *data)

Enumerations
enum	xkb_keymap_key_iterator_flags {   XKB_KEYMAP_KEY_ITERATOR_NO_FLAGS = 0 ,   XKB_KEYMAP_KEY_ITERATOR_DESCENDING_ORDER = (1 << 0) ,   XKB_KEYMAP_KEY_ITERATOR_INCLUDE_UNBOUND = (1 << 1) }

Functions
XKB_EXPORT xkb_keycode_t	xkb_keymap::xkb_keymap_min_keycode (struct xkb_keymap *keymap)
XKB_EXPORT xkb_keycode_t	xkb_keymap::xkb_keymap_max_keycode (struct xkb_keymap *keymap)
XKB_EXPORT enum xkb_status	xkb_keymap_key_iterator::xkb_keymap_key_iterator_init (struct xkb_keymap_key_iterator *iter, const struct xkb_keymap *keymap, const struct xkb_keymap_key_iterator_config *config)
XKB_EXPORT xkb_keycode_t	xkb_keymap_key_iterator::xkb_keymap_key_iterator_next (struct xkb_keymap_key_iterator *iter)
XKB_EXPORT void	xkb_keymap::xkb_keymap_key_for_each (struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter, void *data)
XKB_EXPORT const char *	xkb_keymap::xkb_keymap_key_get_name (struct xkb_keymap *keymap, xkb_keycode_t key)
XKB_EXPORT xkb_keycode_t	xkb_keymap::xkb_keymap_key_by_name (struct xkb_keymap *keymap, const char *name)
XKB_EXPORT xkb_mod_index_t	xkb_keymap::xkb_keymap_num_mods (struct xkb_keymap *keymap)
XKB_EXPORT const char *	xkb_keymap::xkb_keymap_mod_get_name (struct xkb_keymap *keymap, xkb_mod_index_t idx)
XKB_EXPORT xkb_mod_index_t	xkb_keymap::xkb_keymap_mod_get_index (struct xkb_keymap *keymap, const char *name)
XKB_EXPORT xkb_mod_mask_t	xkb_keymap::xkb_keymap_mod_get_mask (struct xkb_keymap *keymap, const char *name)
XKB_EXPORT xkb_mod_mask_t	xkb_keymap::xkb_keymap_mod_get_mask2 (struct xkb_keymap *keymap, xkb_mod_index_t idx)
XKB_EXPORT xkb_layout_index_t	xkb_keymap::xkb_keymap_num_layouts (struct xkb_keymap *keymap)
XKB_EXPORT const char *	xkb_keymap::xkb_keymap_layout_get_name (struct xkb_keymap *keymap, xkb_layout_index_t idx)
XKB_EXPORT xkb_layout_index_t	xkb_keymap::xkb_keymap_layout_get_index (struct xkb_keymap *keymap, const char *name)
XKB_EXPORT xkb_led_index_t	xkb_keymap::xkb_keymap_num_leds (struct xkb_keymap *keymap)
XKB_EXPORT const char *	xkb_keymap::xkb_keymap_led_get_name (struct xkb_keymap *keymap, xkb_led_index_t idx)
XKB_EXPORT xkb_led_index_t	xkb_keymap::xkb_keymap_led_get_index (struct xkb_keymap *keymap, const char *name)
XKB_EXPORT xkb_layout_index_t	xkb_keymap::xkb_keymap_num_layouts_for_key (struct xkb_keymap *keymap, xkb_keycode_t key)
XKB_EXPORT xkb_level_index_t	xkb_keymap::xkb_keymap_num_levels_for_key (struct xkb_keymap *keymap, xkb_keycode_t key, xkb_layout_index_t layout)
XKB_EXPORT size_t	xkb_keymap::xkb_keymap_key_get_mods_for_level (struct xkb_keymap *keymap, xkb_keycode_t key, xkb_layout_index_t layout, xkb_level_index_t level, xkb_mod_mask_t *masks_out, size_t masks_size)
XKB_EXPORT int	xkb_keymap::xkb_keymap_key_get_syms_by_level (struct xkb_keymap *keymap, xkb_keycode_t key, xkb_layout_index_t layout, xkb_level_index_t level, const xkb_keysym_t **syms_out)
XKB_EXPORT int	xkb_keymap::xkb_keymap_key_repeats (struct xkb_keymap *keymap, xkb_keycode_t key)

Detailed Description

Enumeration of state components in a keymap.

Typedef Documentation

xkb_keymap_key_iter_t

typedef void(* xkb_keymap_key_iter_t) (struct xkb_keymap *keymap, xkb_keycode_t key, void *data)

The iterator used by xkb_keymap_key_for_each().

See also

xkb_keymap_key_for_each()

Since

0.3.1

Enumeration Type Documentation

xkb_keymap_key_iterator_flags

enum xkb_keymap_key_iterator_flags

Flags for xkb_keymap_key_iterator_config::flags.

Since

1.14.0

Enumerator
XKB_KEYMAP_KEY_ITERATOR_NO_FLAGS	Do not apply any flags: iterate keys in ascending order; iterate only bound keys, i.e. keys with some group. Since 1.14.0
XKB_KEYMAP_KEY_ITERATOR_DESCENDING_ORDER	Iterate keys in descending order. Since 1.14.0
XKB_KEYMAP_KEY_ITERATOR_INCLUDE_UNBOUND	Iterate all keys, including unbound keys, i.e. keys with no groups. Since 1.14.0

Function Documentation

xkb_keymap_min_keycode()

XKB_EXPORT xkb_keycode_t xkb_keymap_min_keycode

(

struct xkb_keymap *

keymap

)

Get the minimum keycode in the keymap.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

See also

xkb_keycode_t

Since

0.3.1

xkb_keymap_max_keycode()

XKB_EXPORT xkb_keycode_t xkb_keymap_max_keycode

(

struct xkb_keymap *

keymap

)

Get the maximum keycode in the keymap.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

See also

xkb_keycode_t

Since

0.3.1

xkb_keymap_key_iterator_init()

XKB_EXPORT enum xkb_status xkb_keymap_key_iterator_init	(	struct xkb_keymap_key_iterator *	iter,
		const struct xkb_keymap *	keymap,
		const struct xkb_keymap_key_iterator_config *	config
	)

Initialize an iterator over a keymap’s keys.

Intended use

enum xkb_status status;
struct xkb_keymap_key_iterator_config config = {
    .size = sizeof(config),
    .flags = XKB_KEYMAP_KEY_ITERATOR_NO_FLAGS,
};
struct xkb_keymap_key_iterator iter;
status = xkb_keymap_key_iterator_init(&iter, keymap, &config);
switch(status) {
case XKB_SUCCESS:
    break;
// handle errors
// ...
default:
    exit(EXIT_FAILURE);
}
xkb_keycode_t kc;
while ((kc = xkb_keymap_key_iterator_next(&iter)) != XKB_KEYCODE_INVALID) {
    // ...
}

Parameters

[in,out]	iter	Pointer to the iterator to initialize.
[in]	keymap	The keymap to iterate over. Borrowed: iter keeps a pointer to this parameter without taking ownership.
[in]	config	Configuration to control the iterator behavior, or NULL for the defaults: an xkb_keymap_key_iterator_config struct with size set per Extensible structure ABI contract and all other fields zeroed.

Precondition

If config is not NULL, it must point to a zero-initialized struct with `config->size` set per Extensible structure ABI contract.

Returns

XKB_SUCCESS on success, otherwise an error code corresponding to the failure. Possible errors are:

• Errors from ABI Version resolution
• XKB_ERROR_UNSUPPORTED_KEY_ITERATOR_FLAGS
• XKB_ERROR_INVALID_KEYCODE

See also

struct xkb_keymap_key_iterator

enum xkb_keymap_key_iterator_flags

xkb_keymap_key_iterator_next()

Since

1.14.0

xkb_keymap_key_iterator_next()

XKB_EXPORT xkb_keycode_t xkb_keymap_key_iterator_next

(

struct xkb_keymap_key_iterator *

iter

)

Get the next keycode from a keymap’s keys iterator.

The keycodes are returned in ascending order unless XKB_KEYMAP_KEY_ITERATOR_DESCENDING_ORDER was used to create the iterator.

If a keymap is sparse, this function may be called fewer than max_keycode - min_keycode + 1 times.

Parameters

[in,out]

iter

The iterator to use.

Returns

A valid keycode, otherwise XKB_KEYCODE_INVALID in case there are no more entries.

See also

xkb_keycode_t

xkb_keymap_key_iterator_init()

Since

1.14.0

xkb_keymap_key_for_each()

XKB_EXPORT void xkb_keymap_key_for_each	(	struct xkb_keymap *	keymap,
		xkb_keymap_key_iter_t	iter,
		void *	data
	)

Run a specified function for every valid keycode in the keymap.

Parameters

[in]

keymap

The keymap to iterate over. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]	iter	The pointer to the function to call on each valid keycode.
[in,out]	data	Private data to use inside iter.

If a keymap is sparse, this function may be called fewer than (max_keycode - min_keycode + 1) times with success.

See also

struct xkb_keymap_key_iterator, which offers more control on the iteration.

xkb_keymap_min_keycode()

xkb_keymap_max_keycode()

xkb_keycode_t

Since

0.3.1

xkb_keymap_key_get_name()

XKB_EXPORT const char * xkb_keymap_key_get_name	(	struct xkb_keymap *	keymap,
		xkb_keycode_t	key
	)

Find the name of the key with the given keycode.

This function always returns the canonical name of the key (see description in xkb_keycode_t).

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

key

The key to query.

Returns

The key name. If no key with this keycode exists, returns NULL.

See also

xkb_keycode_t

Since

0.6.0

xkb_keymap_key_by_name()

XKB_EXPORT xkb_keycode_t xkb_keymap_key_by_name	(	struct xkb_keymap *	keymap,
		const char *	name
	)

Find the keycode of the key with the given name.

The name can be either a canonical name or an alias.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

name

The key name to look up.

Returns

The matching keycode. If no key with this name exists, returns XKB_KEYCODE_INVALID.

See also

xkb_keycode_t

Since

0.6.0

xkb_keymap_num_mods()

XKB_EXPORT xkb_mod_index_t xkb_keymap_num_mods

(

struct xkb_keymap *

keymap

)

Get the number of modifiers in the keymap.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

See also

xkb_mod_index_t

xkb_keymap_mod_get_name()

XKB_EXPORT const char * xkb_keymap_mod_get_name	(	struct xkb_keymap *	keymap,
		xkb_mod_index_t	idx
	)

Get the name of a modifier by index.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

idx

The modifier index to look up.

Returns

The name. If the index is invalid, returns NULL.

See also

xkb_mod_index_t

xkb_keymap_mod_get_index()

XKB_EXPORT xkb_mod_index_t xkb_keymap_mod_get_index	(	struct xkb_keymap *	keymap,
		const char *	name
	)

Get the index of a modifier by name.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

name

The modifier name to look up.

Returns

The index. If no modifier with this name exists, returns XKB_MOD_INVALID.

See also

xkb_mod_index_t

xkb_keymap_mod_get_mask()

XKB_EXPORT xkb_mod_mask_t xkb_keymap_mod_get_mask	(	struct xkb_keymap *	keymap,
		const char *	name
	)

Get the encoding of a modifier by name.

In X11 terminology it corresponds to the mapping to the real modifiers.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

name

The modifier name to look up.

Returns

The encoding of a modifier. Note that it may be 0 if the name does not exist or if the modifier is not mapped.

See also

xkb_keymap_mod_get_mask2()

Since

1.10.0

xkb_keymap_mod_get_mask2()

XKB_EXPORT xkb_mod_mask_t xkb_keymap_mod_get_mask2	(	struct xkb_keymap *	keymap,
		xkb_mod_index_t	idx
	)

Get the encoding of a modifier by index.

In X11 terminology it corresponds to the mapping to the real modifiers.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

idx

The modifier index to look up.

Returns

The encoding of a modifier. Note that it may be 0 if the modifier is not mapped.

See also

xkb_keymap_mod_get_mask()

Since

1.11.0

xkb_keymap_num_layouts()

XKB_EXPORT xkb_layout_index_t xkb_keymap_num_layouts

(

struct xkb_keymap *

keymap

)

Get the number of layouts in the keymap.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Returns

The keymap layout count.

See also

xkb_layout_index_t

struct xkb_rule_names

xkb_keymap_num_layouts_for_key()

xkb_keymap_layout_get_name()

XKB_EXPORT const char * xkb_keymap_layout_get_name	(	struct xkb_keymap *	keymap,
		xkb_layout_index_t	idx
	)

Get the name of a layout by index.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

idx

The layout index to look up.

Returns

The name. If the index is invalid, or the layout does not have a name, returns NULL.

See also

xkb_layout_index_t for notes on layout names.

xkb_keymap_layout_get_index()

XKB_EXPORT xkb_layout_index_t xkb_keymap_layout_get_index	(	struct xkb_keymap *	keymap,
		const char *	name
	)

Get the index of a layout by name.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

name

The layout name to look up.

Returns

The index. If no layout exists with this name, returns XKB_LAYOUT_INVALID. If more than one layout in the keymap has this name, returns the lowest index among them.

See also

xkb_layout_index_t for notes on layout names.

xkb_keymap_num_leds()

XKB_EXPORT xkb_led_index_t xkb_keymap_num_leds

(

struct xkb_keymap *

keymap

)

Get the number of LEDs in the keymap.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Returns

The keymap LED count.

Warning

The range [ 0...xkb_keymap_num_leds() ) includes all of the LEDs in the keymap, but may also contain inactive LEDs. When iterating over this range, you need the handle this case when calling functions such as xkb_keymap_led_get_name() or xkb_state::xkb_state_led_index_is_active().

See also

xkb_led_index_t

xkb_keymap_led_get_name()

XKB_EXPORT const char * xkb_keymap_led_get_name	(	struct xkb_keymap *	keymap,
		xkb_led_index_t	idx
	)

Get the name of a LED by index.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

idx

The LED index to look up.

Returns

The name. If the index is invalid, returns NULL.

xkb_keymap_led_get_index()

XKB_EXPORT xkb_led_index_t xkb_keymap_led_get_index	(	struct xkb_keymap *	keymap,
		const char *	name
	)

Get the index of a LED by name.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

name

The LED name to look up.

Returns

The index. If no LED with this name exists, returns XKB_LED_INVALID.

xkb_keymap_num_layouts_for_key()

XKB_EXPORT xkb_layout_index_t xkb_keymap_num_layouts_for_key	(	struct xkb_keymap *	keymap,
		xkb_keycode_t	key
	)

Get the number of layouts for a specific key.

This number can be different from xkb_keymap_num_layouts(), but is always smaller. It is the appropriate value to use when iterating over the layouts of a key.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

key

The key to query.

Returns

The number of layouts corresponding to the given key if it is valid in the given keymap, otherwise 0 if the key is undefined or unbound.

See also

xkb_layout_index_t

xkb_keymap_num_levels_for_key()

XKB_EXPORT xkb_level_index_t xkb_keymap_num_levels_for_key	(	struct xkb_keymap *	keymap,
		xkb_keycode_t	key,
		xkb_layout_index_t	layout
	)

Get the number of shift levels for a specific key and layout.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]	key	The key to query.
[in]	layout	The layout index to query. If 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::xkb_state_key_get_layout().

Returns

The number of shift levels corresponding to the given key and layout if they are valid in the given keymap, otherwise 0 if the key is undefined or unbound.

See also

xkb_level_index_t

xkb_keymap_key_get_mods_for_level()

XKB_EXPORT size_t xkb_keymap_key_get_mods_for_level	(	struct xkb_keymap *	keymap,
		xkb_keycode_t	key,
		xkb_layout_index_t	layout,
		xkb_level_index_t	level,
		xkb_mod_mask_t *	masks_out,
		size_t	masks_size
	)

Retrieves every possible modifier mask that produces the specified shift level for a specific key and layout.

This API is useful for inverse key transformation; i.e. finding out which modifiers need to be active in order to be able to type the keysym(s) corresponding to the specific key code, layout and level.

Warning

It returns only up to masks_size modifier masks. If the buffer passed is too small, some of the possible modifier combinations will not be returned.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]	key	The keycode of the key.
[in]	layout	The layout for which to get modifiers.
[in]	level	The shift level in the layout for which to get the modifiers. This should be smaller than: xkb_keymap_num_levels_for_key(keymap, key).
[out]	masks_out	A buffer in which the requested masks should be stored.
[in]	masks_size	The capacity of the buffer pointed to by masks_out.

If 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::xkb_state_key_get_layout().

Returns

The number of modifier masks stored in the masks_out array. If the key is not in the keymap or if the specified shift level cannot be reached it returns 0 and does not modify the masks_out buffer.

See also

xkb_level_index_t

xkb_mod_mask_t

Since

1.0.0

xkb_keymap_key_get_syms_by_level()

XKB_EXPORT int xkb_keymap_key_get_syms_by_level	(	struct xkb_keymap *	keymap,
		xkb_keycode_t	key,
		xkb_layout_index_t	layout,
		xkb_level_index_t	level,
		const xkb_keysym_t **	syms_out
	)

Get the keysyms obtained from pressing a key in a given layout and shift level.

This function is like xkb_state::xkb_state_key_get_syms(), only the layout and shift level are not derived from the keyboard state but are instead specified explicitly.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]	key	The keycode of the key.
[in]	layout	The layout for which to get the keysyms.
[in]	level	The shift level in the layout for which to get the keysyms. This should be smaller than: xkb_keymap_num_levels_for_key(keymap, key).
[out]	syms_out	An immutable array of keysyms corresponding to the key in the given layout and shift level.

If 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::xkb_state_key_get_layout().

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 and sets syms_out to NULL.

See also

xkb_state::xkb_state_key_get_syms()

xkb_keymap_key_repeats()

XKB_EXPORT int xkb_keymap_key_repeats	(	struct xkb_keymap *	keymap,
		xkb_keycode_t	key
	)

Determine whether a key should repeat or not.

A keymap may specify different repeat behaviors for different keys. Most keys should generally exhibit repeat behavior; for example, holding the a key down in a text editor should normally insert a single ‘a’ character every few milliseconds, until the key is released. However, there are keys which should not or do not need to be repeated. For example, repeating modifier keys such as Left/Right Shift or Caps Lock is not generally useful or desired.

Parameters

[in]

keymap

The keymap to query. Borrowed for the duration of the function call. The parameter is semantically const-qualified; however the signature cannot be fixed due to backward-compatibility.

Parameters

[in]

key

The keycode of the key.

Returns

1 if the key should repeat, 0 otherwise.