libxkbcommon
1.11.0
Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
|
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 } |
Creating and destroying keymaps.
#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.
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.
Protocol
libxkbcommon keymap format
Name
Keymap format
Parsing
Serialization </thead> <tbody>
X11
XKB
Always use XKB_KEYMAP_FORMAT_TEXT_V1
, since the other formats are incompatible.
Wayland
XKB_KEYMAP_FORMAT_TEXT_V2
whenever possible. 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. </tbody>
Enumerator | |
---|---|
XKB_KEYMAP_FORMAT_TEXT_V1 | The classic XKB text format, as generated by @important This format should always be used when serializing a keymap for X11. @important For the Wayland |
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). @important Considered experimental when serializing for Wayland: at the time of writing (July 2025), there is only one XKB keymap format
|
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.
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. |
NULL
if the compilation failed.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
.
xkb_keymap_new_from_names2()
instead. XKB_KEYMAP_FORMAT_TEXT_V2
instead of XKB_KEYMAP_FORMAT_TEXT_V1
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.
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. |
NULL
if the compilation failed.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.
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. |
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_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.
xkb_keymap_new_from_file()
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.
xkb_keymap_new_from_string()
XKB_EXPORT struct xkb_keymap * xkb_keymap_ref | ( | struct xkb_keymap * | keymap | ) |
Take a new reference on a keymap.
XKB_EXPORT void xkb_keymap_unref | ( | struct xkb_keymap * | keymap | ) |
Release a reference on a keymap, and possibly free it.
keymap | The keymap. If it is NULL , this function does nothing. |
XKB_EXPORT char * xkb_keymap_get_as_string | ( | struct xkb_keymap * | keymap, |
enum xkb_keymap_format | format | ||
) |
Get the compiled keymap as a string.
keymap | 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. |
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.