Keymap Serialization

Collaboration diagram for Keymap Serialization:

Modules
	Keymap formats

Data Structures
struct	xkb_keymap_serialize_config
struct	xkb_keymap_serialize_result

Macros
#define	XKB_KEYMAP_USE_ORIGINAL_FORMAT   ((enum xkb_keymap_format) -1)

Enumerations
enum	xkb_keymap_serialize_flags {   XKB_KEYMAP_SERIALIZE_NO_FLAGS = 0 ,   XKB_KEYMAP_SERIALIZE_PRETTY = (1 << 0) ,   XKB_KEYMAP_SERIALIZE_KEEP_UNUSED = (1 << 1) ,   XKB_KEYMAP_SERIALIZE_STRICT_MODE = (1 << 2) ,   XKB_KEYMAP_SERIALIZE_EXPLICIT_DEFAULT_VALUES = (1 << 3) ,   XKB_KEYMAP_SERIALIZE_EXPLICIT_VMODS = (1 << 4) ,   XKB_KEYMAP_SERIALIZE_EXPLICIT_KEY_VALUES = (1 << 5) }

Functions
XKB_EXPORT enum xkb_error_code	xkb_keymap::xkb_keymap_serialize (const struct xkb_keymap *keymap, const struct xkb_keymap_serialize_config *config, struct xkb_keymap_serialize_result *result)
XKB_EXPORT char *	xkb_keymap::xkb_keymap_get_as_string (struct xkb_keymap *keymap, enum xkb_keymap_format format)
XKB_EXPORT char *	xkb_keymap::xkb_keymap_get_as_string2 (struct xkb_keymap *keymap, enum xkb_keymap_format format, enum xkb_keymap_serialize_flags flags)

Detailed Description

Serializing keymaps.

Macro Definition Documentation

XKB_KEYMAP_USE_ORIGINAL_FORMAT

#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.

See also

xkb_keymap::xkb_keymap_get_as_string()

Enumeration Type Documentation

xkb_keymap_serialize_flags

enum xkb_keymap_serialize_flags

Flags to control keymap serialization.

Since

1.12.0

Enumerator
XKB_KEYMAP_SERIALIZE_NO_FLAGS	Do not apply any flags. Since 1.12.0
XKB_KEYMAP_SERIALIZE_PRETTY	Enable pretty-printing. Since 1.12.0
XKB_KEYMAP_SERIALIZE_KEEP_UNUSED	Do not drop unused bits (key types, compatibility entries) Since 1.12.0
XKB_KEYMAP_SERIALIZE_STRICT_MODE	Make the serializer operate in strict mode. This is useful mainly for debugging. When this flag is set, the following will raise an error: Exceeded layout count for the corresponding format (see XKB_ERROR_LAYOUT_COUNT_LIMIT_EXCEEDED) Since 1.14.0
XKB_KEYMAP_SERIALIZE_EXPLICIT_DEFAULT_VALUES	Force default values to be explicit. This is useful mainly for debugging. Since 1.14.0
XKB_KEYMAP_SERIALIZE_EXPLICIT_VMODS	Force [virtual modifier] encoding to be explicit. This is useful mainly for debugging. Since 1.14.0
XKB_KEYMAP_SERIALIZE_EXPLICIT_KEY_VALUES	Force key values to be explicit. This is useful mainly for debugging, as it may increase considerably the size of the serialization. This is useful mainly for debugging. Since 1.14.0

Function Documentation

xkb_keymap_serialize()

XKB_EXPORT enum xkb_error_code xkb_keymap_serialize	(	const struct xkb_keymap *	keymap,
		const struct xkb_keymap_serialize_config *	config,
		struct xkb_keymap_serialize_result *	result
	)

Serialize a compiled keymap to a string.

On success, returns a newly allocated serialized keymap in `result->serialized`, together with additional metadata. It is suitable to use with xkb_keymap_new_from_string2().

Use this function instead of xkb_keymap_get_as_string() or xkb_keymap_get_as_string2() when more control on serializing or its result is required.

Note

This function enables to serialize an X11-incompatible keymap with more than 4 layouts to an X11-compatible keymap with up to 4 layouts:

• set `config->format` to XKB_KEYMAP_FORMAT_TEXT_V1,
• set up to 4 bits in `config->layouts` to select a subset of layouts to serialized.

Parameters

[in]	keymap	The keymap to serialize.
[in]	config	Configuration guiding the serialization.
[in,out]	result	Result of the serialization.

Precondition

config must point to a zero-initialized struct with `size` set to sizeof(*config).

result must point to a zero-initialized struct with `size` set to sizeof(*result).

Invariant

The library writes only to fields of result that fall within result->size.

Postcondition

If the return value is XKB_SUCCESS, the caller is responsible for freeing `result->serialized`.

Otherwise, `result->serialized` is set to NULL and all fields of result beyond it are left unspecified.

Returns

XKB_SUCCESS on success; otherwise an error code.

Since

1.14.0

xkb_keymap_get_as_string()

XKB_EXPORT char * xkb_keymap_get_as_string	(	struct xkb_keymap *	keymap,
		enum xkb_keymap_format	format
	)

Get the compiled keymap as a string.

Same as xkb_keymap::xkb_keymap_get_as_string2() using XKB_KEYMAP_SERIALIZE_NO_FLAGS.

Since

1.12.0: Drop unused types and compatibility entries and do not pretty-print.

See also

xkb_keymap::xkb_keymap_serialize()

xkb_keymap::xkb_keymap_get_as_string2()

xkb_keymap_get_as_string2()

XKB_EXPORT char * xkb_keymap_get_as_string2	(	struct xkb_keymap *	keymap,
		enum xkb_keymap_format	format,
		enum xkb_keymap_serialize_flags	flags
	)

Get the compiled keymap as a string.

Parameters

[in]	keymap	The keymap to get as a string.
[in]	format	The keymap format to use for the string. You can pass in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format from which the keymap was originally created. When used as an interchange format such as Wayland xkb_v1, the format should be explicit.
[in]	flags	Optional flags to control the serialization, or 0.

Returns

The keymap as a NULL-terminated string, or NULL if unsuccessful.

The returned string may be fed back into xkb_keymap_new_from_string() to get the exact same keymap (possibly in another process, etc.).

The returned string is dynamically allocated and should be freed by the caller.

Since

1.12.0

See also

xkb_keymap_serialize()

xkb_keymap_get_as_string()

xkb_keymap_new_from_string()