libxkbcommon: Keymap Creation

libxkbcommon 1.13.1 Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state

Loading...
Searching...
No Matches
Macros | Enumerations | Functions
Keymap Creation

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

## Enumerations
enum | xkb_keymap_compile_flags { XKB_KEYMAP_COMPILE_NO_FLAGS = 0 }
enum | xkb_keymap_format { XKB_KEYMAP_FORMAT_TEXT_V1 = 1 , XKB_KEYMAP_FORMAT_TEXT_V2 = 2 }
enum | xkb_keymap_serialize_flags { XKB_KEYMAP_SERIALIZE_NO_FLAGS = 0 , XKB_KEYMAP_SERIALIZE_PRETTY = (1 << 0) , XKB_KEYMAP_SERIALIZE_KEEP_UNUSED = (1 << 1) }

## Functions
XKB_EXPORT struct xkb_keymap * | xkb_keymap::xkb_keymap_new_from_rmlvo (const struct xkb_rmlvo_builder *rmlvo, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
XKB_EXPORT struct xkb_keymap * | xkb_keymap::xkb_keymap_new_from_names (struct xkb_context *context, const struct xkb_rule_names *names, enum xkb_keymap_compile_flags flags)
XKB_EXPORT struct xkb_keymap * | xkb_keymap::xkb_keymap_new_from_names2 (struct xkb_context *context, const struct xkb_rule_names *names, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
XKB_EXPORT struct xkb_keymap * | xkb_keymap::xkb_keymap_new_from_file (struct xkb_context *context, FILE *file, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
XKB_EXPORT struct xkb_keymap * | xkb_keymap::xkb_keymap_new_from_string (struct xkb_context *context, const char *string, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
XKB_EXPORT struct xkb_keymap * | 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)
XKB_EXPORT struct xkb_keymap * | xkb_keymap::xkb_keymap_ref (struct xkb_keymap *keymap)
XKB_EXPORT void | xkb_keymap::xkb_keymap_unref (struct xkb_keymap *keymap)
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

Creating and destroying 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_compile_flags

enum xkb_keymap_compile_flags

Flags for keymap compilation.

Enumerator
XKB_KEYMAP_COMPILE_NO_FLAGS | Do not apply any flags.

## ◆ xkb_keymap_format

enum xkb_keymap_format

The possible keymap formats.

See The XKB keymap text format, V1 and V2 for the complete description of the formats and Keymap support for detailed differences between the formats.

Remarks
  A keymap can be parsed in one format and serialized in another, thanks to automatic fallback mechanisms.

Keymap format to use depending on the target protocol
Protocol | libxkbcommon keymap format
--- | ---
Name | Keymap format | Parsing | Serialization
X11 | XKB | XKB_KEYMAP_FORMAT_TEXT_V1 | Always use XKB_KEYMAP_FORMAT_TEXT_V1, since the other formats are incompatible.
Wayland | `xkb_v1` | Wayland compositors The format depends on the keyboard layout database (usually xkeyboard-config). Note that since v2 is a superset of v1, compositors are encouraged to use XKB_KEYMAP_FORMAT_TEXT_V2 whenever possible. Client apps Clients should use XKB_KEYMAP_FORMAT_TEXT_V1 to parse the keymap sent by a Wayland compositor, at least until XKB_KEYMAP_FORMAT_TEXT_V2 stabilizes. | At the time of writing (July 2025), the Wayland `xkb_v1` keymap format is only defined as “libxkbcommon compatible”. In theory it enables flexibility, but the set of supported features varies depending on the libxkbcommon version and libxkbcommon keymap format used. Unfortunately there is currently no Wayland API for keymap format negotiation. Therefore the recommended serialization format is XKB_KEYMAP_FORMAT_TEXT_V1, in order to ensure maximum compatibility for interchange. Serializing using XKB_KEYMAP_FORMAT_TEXT_V2 should be considered experimental, as some clients may fail to parse the resulting string.

Enumerator
XKB_KEYMAP_FORMAT_TEXT_V1 | The classic XKB text format, as generated by xkbcomp -xkb. Important This format should always be used when serializing a keymap for X11. For the Wayland `xkb_v1` format, it is advised to use this format as well for serializing, in order to ensure maximum compatibility for interchange.
XKB_KEYMAP_FORMAT_TEXT_V2 | Xkbcommon extensions of the classic XKB text format, incompatible with X11. Important Do not use when serializing a keymap for X11 (incompatible). Considered experimental when serializing for Wayland: at the time of writing (July 2025), there is only one XKB keymap format `xkb_v1` in Wayland and no Wayland API for keymap format negotiation, so the clients may not be able to parse the keymap if it uses v2-specific features. Therefore a compositor may parse keymaps using XKB_KEYMAP_FORMAT_TEXT_V2 but it should serialize them using XKB_KEYMAP_FORMAT_TEXT_V1 and rely on the automatic fallback mechanisms. Since 1.11.0

## ◆ 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.
XKB_KEYMAP_SERIALIZE_PRETTY | Enable pretty-printing.
XKB_KEYMAP_SERIALIZE_KEEP_UNUSED | Do not drop unused bits (key types, compatibility entries).

## Function Documentation

## ◆ xkb_keymap_new_from_rmlvo()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_rmlvo | ( | const struct xkb_rmlvo_builder * | rmlvo,
|  | enum xkb_keymap_format | format,
|  | enum xkb_keymap_compile_flags | flags )

Create a keymap from a RMLVO builder.

The primary keymap entry point: creates a new XKB keymap from a set of RMLVO (Rules + Model + Layouts + Variants + Options) names.

Parameters

  rmlvo | The RMLVO builder to use. See xkb_rmlvo_builder.
  format | The text format of the keymap file to compile.
  flags | Optional flags for the keymap, or 0.

Returns
  A keymap compiled according to the RMLVO names, or NULL if the compilation failed.

Since
  1.11.0

See also
  xkb_keymap_new_from_names2()
  xkb_rmlvo_builder

## ◆ xkb_keymap_new_from_names()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_names | ( | struct xkb_context * | context,
|  | const struct xkb_rule_names * | names,
|  | enum xkb_keymap_compile_flags | flags )

Create a keymap from RMLVO names.

Same as xkb_keymap_new_from_names2(), but with the keymap format fixed to: XKB_KEYMAP_FORMAT_TEXT_V2.

Deprecated
  Use xkb_keymap_new_from_names2() instead.

Since
  1.11.0: Deprecated
  1.11.0: Use internally XKB_KEYMAP_FORMAT_TEXT_V2 instead of XKB_KEYMAP_FORMAT_TEXT_V1

See also
  xkb_keymap_new_from_names2()
  xkb_rule_names
  xkb_keymap_new_from_rmlvo()

## ◆ xkb_keymap_new_from_names2()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_names2 | ( | struct xkb_context * | context,
|  | const struct xkb_rule_names * | names,
|  | enum xkb_keymap_format | format,
|  | enum xkb_keymap_compile_flags | flags )

Create a keymap from RMLVO names.

The primary keymap entry point: creates a new XKB keymap from a set of RMLVO (Rules + Model + Layouts + Variants + Options) names.

Parameters

  Library Context | The context in which to create the keymap.
  names | The RMLVO names to use. See xkb_rule_names.
  format | The text format of the keymap file to compile.
  flags | Optional flags for the keymap, or 0.

Returns
  A keymap compiled according to the RMLVO names, or NULL if the compilation failed.

See also
  xkb_rule_names
  xkb_keymap_new_from_rmlvo()

Since
  1.11.0

## ◆ xkb_keymap_new_from_file()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_file | ( | struct xkb_context * | context,
|  | FILE * | file,
|  | enum xkb_keymap_format | format,
|  | enum xkb_keymap_compile_flags | flags )

Create a keymap from a keymap file.

Parameters

  Library Context | The context in which to create the keymap.
  file | The keymap file to compile.
  format | The text format of the keymap file to compile.
  flags | Optional flags for the keymap, or 0.

Returns
  A keymap compiled from the given XKB keymap file, or NULL if the compilation failed.

The file must contain a complete keymap. For example, in the XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one top level xkb_keymap section, which in turn contains other required sections.

## ◆ xkb_keymap_new_from_string()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_string | ( | struct xkb_context * | context,
|  | const char * | string,
|  | enum xkb_keymap_format | format,
|  | enum xkb_keymap_compile_flags | flags )

Create a keymap from a keymap string.

This is just like xkb_keymap_new_from_file(), but instead of a file, gets the keymap as one enormous string.

See also
  xkb_keymap_new_from_file()

## ◆ xkb_keymap_new_from_buffer()

XKB_EXPORT 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 )

Create a keymap from a memory buffer.

This is just like xkb_keymap_new_from_string(), but takes a length argument so the input string does not have to be zero-terminated.

See also
  xkb_keymap_new_from_string()

Since
  0.3.0

## ◆ xkb_keymap_ref()

XKB_EXPORT struct xkb_keymap * xkb_keymap_ref | ( | struct xkb_keymap * | keymap | ) |

Take a new reference on a keymap.

Returns
  The passed in keymap.

## ◆ xkb_keymap_unref()

XKB_EXPORT void xkb_keymap_unref | ( | struct xkb_keymap * | keymap | ) |

Release a reference on a keymap, and possibly free it.

Parameters

  Keymap Creation | The keymap. If it is NULL, this function does nothing.

## ◆ 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_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

  Keymap Creation | The keymap to get as a string.
  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.
  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_get_as_string()
  xkb_keymap_new_from_string()