Libxkbcommon

https://xkbcommon.org/doc/current/
Admin
Libxkbcommon is a keyboard keymap compiler and support library that processes keymaps defined by the...
Tokens:122,709
Snippets:1,356
Trust Score:8.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### XKB :all Qualifier Example

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Demonstrates the usage of the ':all' qualifier in KccgstValue to apply a value to all layouts, with examples of its effect on different merge modes.

```xkb
Examples of :all qualified use KccgstValue| Layouts count| Final KccgstValue  
---|---|---  
x:all| 1| x:1  
2| x:1+x:2  
+x:all| 1| +x:1  
3| +x:1+x:2+x:3  
|x:all| 1| |x:1  
4| |x:1|x:2|x:3|x:4  
x|y:all| 1| x|y:1  
3| x|y:1|y:2|y:3  
```

--------------------------------

### Basic Rule Example

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Adds symbols to the result when the left-hand side matches the user's input. Example: mapping 'ctrl:nocaps' to '+ctrl(nocaps)'.

```xkbcommon
ctrl:nocaps = +ctrl(nocaps)
```

```xkbcommon
compose:menu = +compose(menu)
```

--------------------------------

### Example of xkbcli how-to-type command

Source: https://xkbcommon.org/doc/current/release-notes.html

Demonstrates how to use the 'xkbcli how-to-type' command to find ways to produce a specific keysym (e.g., '?') in a given keymap configuration.

```bash
$ xkbcli how-to-type --layout us,de 63 | column -ts $'	'
keysym: question (0x3f)
KEYCODE  KEY NAME  LAYOUT#  LAYOUT NAME   LEVEL#  MODIFIERS
20       AE11      2        German        2       [ Shift ]
20       AE11      2        German        2       [ Shift Lock ]
61       AB10      1        English (US)  2       [ Shift ]

```

--------------------------------

### rxkb_option_get_brief()

Source: https://xkbcommon.org/doc/current/group__registry.html

Gets a short, one-word description for an rxkb_option.

```APIDOC
## rxkb_option_get_brief()

### Description
Return a short (one-word) description of this option.

### Parameters
#### Path Parameters
- **_o_** (struct rxkb_option *) - Required - The option structure to query.

### Returns
- **const char *:** - A short description of the option. This function may return NULL.
```

--------------------------------

### Define Layout-Specific Options

Source: https://xkbcommon.org/doc/current/rule-file-format.html

This example demonstrates defining layout-specific options using the `[any]` range and `:%i` specifier. Options without a layout index are not layout-specific.

```xkbcommon
! layout[first] = symbols
* = pc
! layout[any] = symbols
* = %l[%i]%(v[%i])
// Not layout-specific
! option = symbols
opt1 = +opt1
// Layout-specific: note the range `[any]` and the `:%i` specifier
! layout[any] option = symbols
* opt2 = +opt2:%i
```

--------------------------------

### Actions and Keysyms Level List Examples

Source: https://xkbcommon.org/doc/current/release-notes.html

Demonstrates the support for empty and single-element lists for actions and keysyms, showcasing new syntax for defining key behaviors.

```text
key <A> { [{}, {a}, {a, A}] };
```

--------------------------------

### Compose File Sequences

Source: https://xkbcommon.org/doc/current/group__compose.html

Examples of sequences defined in the libX11 Compose file format, illustrating dead-key and multi-key compositions.

```compose
<dead_acute> <a >         : "á"   aacute # LATIN SMALL LETTER A WITH ACUTE
<Multi_key> <A> <T>      : "@"   at     # COMMERCIAL AT
```

--------------------------------

### Unicode case mapping example for title-cased keysym

Source: https://xkbcommon.org/doc/current/release-notes.html

Shows how xkb_keysym_to_lower and xkb_keysym_to_upper handle title-cased keysyms, using U01F2 as an example. This provides consistent behavior with Unicode 16.0 case mappings.

```c
/* Example of title-cased keysym: U01F2 “ǲ”:
 * xkb_keysym_to_lower(U01F2) == U01F3 “ǳ”
 * xkb_keysym_to_upper(U01F2) == U01F1 “Ǳ”
 */
```

--------------------------------

### Define Symbols with Layout Options

Source: https://xkbcommon.org/doc/current/rule-file-format.html

This example shows how to define symbols with layout-specific options. The order of options in the RMLVO configuration does not influence the resulting symbols.

```xkbcommon
! $azerty = be fr
! layout = symbols
* = pc+%l%(v)
! layout[1] = symbols
* = pc+%l[1]%(v[1])
! layout[2] = symbols
* = +%l[2]%(v[2])
// Repeat the previous rules set with indices 3 and 4
! layout option = symbols
$azerty caps:digits_row = +capslock(digits_row)
* misc:typo = +typo(base)
* lv3:ralt_alt = +level3(ralt_alt)
! layout[1] option = symbols
$azerty caps:digits_row = +capslock(digits_row):1
* misc:typo = +typo(base):1
* lv3:ralt_alt = +level3(ralt_alt):1
// Repeat the previous rules set for indices 2 to 4
```

--------------------------------

### rxkb_layout_first()

Source: https://xkbcommon.org/doc/current/group__registry.html

Returns the first layout for a given context, used to start iterating over layouts. The refcount of the returned layout is not increased.

```APIDOC
## rxkb_layout_first()

### Description
Return the first layout for this context. Use this to start iterating over the layouts, followed by calls to rxkb_layout_next(). Layouts are not sorted. The refcount of the returned layout is not increased. Use rxkb_layout_ref() if you need to keep this struct outside the immediate scope.

### Returns
The first layout in the layout list.
```

--------------------------------

### Define Custom Symbols File

Source: https://xkbcommon.org/doc/current/custom-configuration.html

Create a symbols file that defines a custom keyboard layout. This example uses the US Qwerty layout as a base and swaps the number keys.

```xkb
default partial alphanumeric_keys
xkb_symbols "basic" {
include "us(basic)" // Use the US Qwerty layout as a base
name[Group1]= "Test (Swapped numbers)";
// Map keys <XXXX> to key symbols, ordered by their shift level
key <AE01> { [ exclam, 1] };
key <AE02> { [ at, 2] };
key <AE03> { [ numbersign, 3] };
key <AE04> { [ dollar, 4] };
key <AE05> { [ percent, 5] };
key <AE06> { [ asciicircum, 6] };
key <AE07> { [ ampersand, 7] };
key <AE08> { [ asterisk, 8] };
key <AE09> { [ parenleft, 9] };
key <AE10> { [ parenright, 0] };
};
```

--------------------------------

### Support for Empty Compound Statements

Source: https://xkbcommon.org/doc/current/release-notes.html

Shows examples of newly supported empty compound statements in xkb_types, xkb_compat, and indicator configurations. These are initialized with default values.

```text
xkb_types: type "xxx" {};
xkb_compat: interpret x {}; and indicator "xxx" {};.
```

--------------------------------

### Process xkbcli list output with yq

Source: https://xkbcommon.org/doc/current/release-notes.html

This command demonstrates how to process the YAML output from `xkbcli list` using `yq` to extract layout information. Ensure `yq` is installed and the output is in YAML format.

```bash
xkbcli list | yq -r ".layouts[].layout"
```

--------------------------------

### Interactive X11 Keyboard Event Simulation

Source: https://xkbcommon.org/doc/current/faq.html

This command starts an interactive session to simulate keyboard events on X11, replacing xev -event keyboard for X11 sessions.

```bash
xkbcli interactive-x11
```

--------------------------------

### Get Keys Triggering Modifiers

Source: https://xkbcommon.org/doc/current/faq.html

This snippet provides a minimal example to find the keys that trigger a specific modifier. It iterates through keycodes and checks their state.

```c
#include <xkbcommon/xkbcommon.h>

static ssize_t
xkb_keymap_mod_get_codes(struct xkb_keymap *keymap, xkb_mod_index_t mod,
xkb_keycode_t *codes_out, size_t codes_size)
{
if (mod >= xkb_keymap_num_mods(keymap))
return -1;

ssize_t idx = 0;
for (xkb_keycode_t k = xkb_keymap_min_keycode(keymap);
k <= xkb_keymap_max_keycode(keymap) && idx >= 0; k++) {
/*
* We only test the first level of the first group.
*
* Since there is currently no way to reset the state, use a new one to
* avoid side effects (latches, etc.)
*/
struct xkb_state * const state = xkb_state_new(keymap);
assert(state);

static const enum xkb_key_direction directions[] = {
XKB_KEY_DOWN,
XKB_KEY_UP
};

for (size_t d = 0; d < ARRAY_SIZE(directions); d++) {
if (xkb_state_update_key(state, k, directions[d]) &&
xkb_state_mod_index_is_active(state, mod,
XKB_STATE_MODS_EFFECTIVE)) {
if ((size_t) idx < codes_size) {
assert(idx < (ssize_t) (SIZE_MAX / 2));
codes_out[idx++] = k;
} else {
idx = -2;
}
break;
}
}

xkb_state_unref(state);
}

return idx;
}
```

--------------------------------

### Create New RMLVO Builder

Source: https://xkbcommon.org/doc/current/group__rules-api.html

Creates a new RMLVO builder for XKB rules. Use this to start defining a keymap configuration. Defaults are used if rules or model are NULL or empty strings, with environment variables taking precedence.

```c
XKB_EXPORT struct xkb_rmlvo_builder *
xkb_rmlvo_builder_new(
    struct xkb_context *context,
    const char *rules,
    const char *model,
    enum xkb_rmlvo_builder_flags flags
);
```

--------------------------------

### xkb_x11_setup_xkb_extension

Source: https://xkbcommon.org/doc/current/group__x11.html

Sets up the XKB extension with the X server. It negotiates the XKB version and retrieves base event and error codes.

```APIDOC
## xkb_x11_setup_xkb_extension

### Description
Sets up the XKB extension with the X server. It negotiates the XKB version and retrieves base event and error codes.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **connection** (xcb_connection_t *) - Required - The XCB connection to the X server.
- **major_xkb_version** (uint16_t) - Required - The major version of XKB requested.
- **minor_xkb_version** (uint16_t) - Required - The minor version of XKB requested.
- **flags** (enum xkb_x11_setup_xkb_extension_flags) - Required - Flags to control the setup behavior.
- **major_xkb_version_out** (uint16_t *) - Output - Pointer to store the negotiated major XKB version.
- **minor_xkb_version_out** (uint16_t *) - Output - Pointer to store the negotiated minor XKB version.
- **base_event_out** (uint8_t *) - Output - Pointer to store the base event code for XKB.
- **base_error_out** (uint8_t *) - Output - Pointer to store the base error code for XKB.

### Returns
- **int** - Returns 0 on success, a negative value on failure.
```

--------------------------------

### Group Definition

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Defines a group of related values that can be referenced by a group name. Groups start with '$'. Example: defining '$azerty' for 'be' and 'fr' layouts.

```xkbcommon
! $azerty = be fr
```

--------------------------------

### XKB Include Directive and %-Expansion

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Illustrates how to include other rule files and explains the %-expansion rules for environment variables and system paths.

```xkb
%% 
    A literal %.

%H 
    The value of the $HOME environment variable.

%E 
    The extra lookup path for system-wide XKB data (usually /etc/xkb/rules).  

%S 
    The system-installed rules directory (usually /usr/share/X11/xkb/rules).  Note: This feature is supported by libxkbcommon but not by the legacy X11 tools.
```

--------------------------------

### Build libxkbcommon with Meson

Source: https://xkbcommon.org/doc/current/index.html

Standard commands to set up, compile, and test the libxkbcommon library using Meson.

```bash
meson setup build
meson compile -C build
meson test -C build
```

--------------------------------

### xkb_x11_setup_xkb_extension

Source: https://xkbcommon.org/doc/current/group__x11.html

Sets up the XKB X11 extension for an X client. This function must be called before any other function in the xkbcommon-x11 library to ensure proper XKB extension usage with the X server. It is idempotent and can be called multiple times.

```APIDOC
## Function Documentation
## ◆ xkb_x11_setup_xkb_extension()

### Description
Setup the XKB X11 extension for this X client. The xkbcommon-x11 library uses various XKB requests. Before doing so, an X client must notify the server that it will be using the extension. This function (or an XCB equivalent) must be called before any other function in this library is used.

Some X servers may not support or disable the XKB extension. If you want to support such servers, you need to use a different fallback. You may call this function several times; it is idempotent.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters (Function Arguments)
- **connection** (xcb_connection_t *) - An XCB connection to the X server.
- **major_xkb_version** (uint16_t) - The XKB extension version to request. To operate correctly, you must have (`major_xkb_version`, `minor_xkb_version`) >= (XKB_X11_MIN_MAJOR_XKB_VERSION, XKB_X11_MIN_MINOR_XKB_VERSION), though this is not enforced.
- **minor_xkb_version** (uint16_t) - See `minor_xkb_version`.
- **flags** (enum xkb_x11_setup_xkb_extension_flags) - Optional flags, or 0.
- **major_xkb_version_out** (uint16_t *) - [out] Backfilled with the compatible XKB extension version numbers picked by the server. Can be NULL.
- **minor_xkb_version_out** (uint16_t *) - [out] Backfilled with the compatible XKB extension version numbers picked by the server. Can be NULL.
- **base_event_out** (uint8_t *) - [out] Backfilled with the XKB base (also known as first) event code, needed to distinguish XKB events. Can be NULL.
- **base_error_out** (uint8_t *) - [out] Backfilled with the XKB base (also known as first) error code, needed to distinguish XKB errors. Can be NULL.

### Returns
- 1 on success, or 0 on failure.
```

--------------------------------

### Example C++ Classes for Doxygen Graph Generation

Source: https://xkbcommon.org/doc/current/graph_legend.html

These C++ class definitions are used to demonstrate how Doxygen generates inheritance and usage graphs. They include examples of documented, undocumented, truncated, and templated classes.

```c++
/*! Invisible class because of truncation */
class Invisible { };
/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };
/* Class not documented with doxygen comments */
class Undocumented { };
/*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };
/*! A template class */
template<class T> class Templ { };
/*! Class that is inherited using protected inheritance */
class ProtectedBase { };
/*! Class that is inherited using private inheritance */
class PrivateBase { };
/*! Class that is used by the Inherited class */
class Used { };
/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
protected ProtectedBase,
private PrivateBase,
public Undocumented,
public Templ<int>
{
private:
Used *m_usedClass;
};
```

--------------------------------

### xkb_keymap_num_levels_for_key

Source: https://xkbcommon.org/doc/current/functions_func.html

Gets the number of levels for a specific key.

```APIDOC
## xkb_keymap_num_levels_for_key

### Description
Returns the number of different levels (e.g., base, Shift, AltGr) available for a specific keycode.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_keymap**: (type not specified) - A pointer to the keymap.
- **keycode**: (integer) - The keycode of the key.
- **num_levels**: (integer) - The number of levels for this key.

#### Response Example
(Not specified in source)
```

--------------------------------

### Create an xkb_context

Source: https://xkbcommon.org/doc/current/md_doc_2quick-guide.html

Initializes a new xkb_context, which is the top-level library context. This context holds keymap include paths, log levels, and other administrative settings. Use XKB_CONTEXT_NO_FLAGS when no specific flags are required.

```c
#include <xkbcommon/xkbcommon.h>

struct xkb_context *ctx;
ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
if (!ctx) <error>
```

--------------------------------

### xkb_keymap_num_leds

Source: https://xkbcommon.org/doc/current/functions_func.html

Gets the number of LEDs defined in the keymap.

```APIDOC
## xkb_keymap_num_leds

### Description
Returns the total number of LEDs defined in this keymap.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_keymap**: (type not specified) - A pointer to the keymap.
- **num_leds**: (integer) - The number of LEDs.

#### Response Example
(Not specified in source)
```

--------------------------------

### Interactively Test Custom Layout

Source: https://xkbcommon.org/doc/current/custom-configuration.html

Use `xkbcli compile-keymap` piped to `xkbcli interactive` to preview how keys behave interactively. The window needs to stay focused and logs keys in the terminal. Use `Esc` to quit.

```bash
xkbcli compile-keymap --include /tmp/xkb \
--include-defaults \
--layout test \
| xkbcli interactive
```

--------------------------------

### xkb_keymap_mod_get_mask

Source: https://xkbcommon.org/doc/current/functions_func.html

Gets the modifier mask for a modifier name.

```APIDOC
## xkb_keymap_mod_get_mask

### Description
Retrieves the bitmask representing a modifier given its name.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_keymap**: (type not specified) - A pointer to the keymap.
- **mod_name**: (string) - The name of the modifier.
- **mask_out**: (integer) - Output for the modifier mask.

#### Response Example
(Not specified in source)
```

--------------------------------

### Create a New xkb Registry Context

Source: https://xkbcommon.org/doc/current/group__registry.html

Creates a new xkb registry context. Use RXKB_CONTEXT_NO_DEFAULT_INCLUDES to prevent loading default system paths.

```c
struct rxkb_context * rxkb_context_new(enum rxkb_context_flags flags);
```

--------------------------------

### xkb_keymap_key_get_name

Source: https://xkbcommon.org/doc/current/functions_func.html

Gets the name of a key given its keycode.

```APIDOC
## xkb_keymap_key_get_name

### Description
Retrieves the symbolic name of a key given its keycode.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_keymap**: (type not specified) - A pointer to the keymap.
- **keycode**: (integer) - The keycode of the key.
- **name_out**: (string) - Output buffer for the key name.

#### Response Example
(Not specified in source)
```

--------------------------------

### xkb_keymap_key_get_mods_for_level

Source: https://xkbcommon.org/doc/current/functions_func.html

Gets the modifier mapping for a specific key and level.

```APIDOC
## xkb_keymap_key_get_mods_for_level

### Description
Retrieves the modifier mapping for a specific key and a given level (e.g., Shift, AltGr).

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_keymap**: (type not specified) - A pointer to the keymap.
- **keycode**: (integer) - The keycode of the key.
- **level**: (integer) - The level for which to get the modifier mapping.
- **mods_out**: (type not specified) - Output for the modifier mask.

#### Response Example
(Not specified in source)
```

--------------------------------

### rxkb_iso639_code_next()

Source: https://xkbcommon.org/doc/current/globals.html

Gets the next ISO 639 code in the list.

```APIDOC
## rxkb_iso639_code_next()

### Description
Gets the next ISO 639 code in the list.

### Function Signature
`rxkb_iso639_code *rxkb_iso639_code_next(rxkb_iso639_code *code);`

### Parameters
*   **code** (*rxkb_iso639_code* *) - A pointer to the current ISO 639 code.

### Returns
A pointer to the next ISO 639 code, or NULL if there are no more.

### File
xkbregistry.h
```

--------------------------------

### xkb_context_new

Source: https://xkbcommon.org/doc/current/functions_func.html

Creates a new XKB context.

```APIDOC
## xkb_context_new

### Description
Creates a new XKB context, which is the main object for managing XKB resources and state.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_context**: (type not specified) - A pointer to the newly created XKB context.

#### Response Example
(Not specified in source)
```

--------------------------------

### Create Directory for Testing

Source: https://xkbcommon.org/doc/current/custom-configuration.html

Create a temporary directory to store custom XKB symbols files for testing purposes. This directory is later used with the --include option.

```bash
mkdir -p "/tmp/xkb/symbols"
```

--------------------------------

### rxkb_iso3166_code_next()

Source: https://xkbcommon.org/doc/current/globals.html

Gets the next ISO 3166 code in the list.

```APIDOC
## rxkb_iso3166_code_next()

### Description
Gets the next ISO 3166 code in the list.

### Function Signature
`rxkb_iso3166_code *rxkb_iso3166_code_next(rxkb_iso3166_code *code);`

### Parameters
*   **code** (*rxkb_iso3166_code* *) - A pointer to the current ISO 3166 code.

### Returns
A pointer to the next ISO 3166 code, or NULL if there are no more.

### File
xkbregistry.h
```

--------------------------------

### xkb_compose_state_get_status

Source: https://xkbcommon.org/doc/current/functions_func.html

Gets the current status of the compose state machine.

```APIDOC
## xkb_compose_state_get_status

### Description
Gets the current status of the compose state machine, indicating whether it is waiting for more input, has produced a result, or encountered an error.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_compose_state**: (type not specified) - Description of the compose state.
- **status**: (type not specified) - The current status of the compose state machine.

#### Response Example
(Not specified in source)
```

--------------------------------

### Create a new xkb_context

Source: https://xkbcommon.org/doc/current/group__context.html

Creates a new xkb_context with optional flags. Returns NULL on failure. Use XKB_CONTEXT_NO_FLAGS for default behavior.

```c
struct xkb_context * xkb_context_new (enum xkb_context_flags flags)
```

--------------------------------

### Get Logging Verbosity

Source: https://xkbcommon.org/doc/current/group__logging.html

Retrieves the current logging verbosity setting for a context.

```c
int xkb_context_get_log_verbosity(struct xkb_context *context);
```

--------------------------------

### rxkb_context_new

Source: https://xkbcommon.org/doc/current/group__registry.html

Creates a new xkb registry context with a specified set of flags. The context is initialized with a reference count of 1 and must be released using rxkb_context_unref(). File parsing is not performed upon creation; use rxkb_context_parse() for that.

```APIDOC
## rxkb_context_new()

### Description
Create a new xkb registry context.

The context has an initial refcount of 1. Use rxkb_context_unref() to release memory associated with this context.
Creating a context does not parse the files yet, use rxkb_context_parse().

### Parameters
- **flags** (enum rxkb_context_flags) - Flags affecting context behavior.

### Returns
A new xkb registry context or NULL on failure.
```

--------------------------------

### rxkb_option_first

Source: https://xkbcommon.org/doc/current/group__registry.html

Retrieves the first option within an option group to start iteration.

```APIDOC
## rxkb_option_first()

### Description
Returns the first option for this option group. Use this to start iterating over the options, followed by calls to rxkb_option_next(). Options are not sorted. The refcount of the returned option is not increased. Use rxkb_option_ref() if you need to keep this struct outside the immediate scope.

### Signature
RXKB_EXPORT struct rxkb_option * rxkb_option_first(struct rxkb_option_group * _group_)

### Returns
The first option in the option list.
```

--------------------------------

### Get Logging Level

Source: https://xkbcommon.org/doc/current/group__logging.html

Retrieves the currently configured logging level for a given context.

```c
enum xkb_log_level xkb_context_get_log_level(struct xkb_context *context);
```

--------------------------------

### Compile and Test Keymap with xkbcomp for X11

Source: https://xkbcommon.org/doc/current/debugging.html

This command pipes the output of 'xkbcli compile-keymap' to 'xkbcomp' for testing custom configurations in an X11 environment. It's a workaround for X11's lack of support for alternative configuration paths.

```bash
xkbcli compile-keymap --include ~/xkb-test --include-defaults --layout my-layout \
| xkbcomp - $DISPLAY
```

--------------------------------

### rxkb_model_first

Source: https://xkbcommon.org/doc/current/group__registry.html

Retrieves the first model for a given context, used to start iterating over available models.

```APIDOC
## rxkb_model_first()

### Description
Returns the first model for this context. Use this to start iterating over the models, followed by calls to rxkb_model_next(). Models are not sorted. The refcount of the returned model is not increased. Use rxkb_model_ref() if you need to keep this struct outside the immediate scope.

### Returns
The first model in the model list.
```

--------------------------------

### xkb_keymap_new_from_file

Source: https://xkbcommon.org/doc/current/group__keymap.html

Creates a new XKB keymap from a file.

```APIDOC
## xkb_keymap_new_from_file

### Description
Creates a new XKB keymap from a file.

### Function Signature
`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)`

### Parameters
* `context` (struct xkb_context *) - Pointer to the XKB context.
* `file` (FILE *) - Pointer to the file stream containing the keymap definition.
* `format` (enum xkb_keymap_format) - The desired format for the keymap.
* `flags` (enum xkb_keymap_compile_flags) - Flags to control keymap compilation.

### Returns
Returns a pointer to the newly created `struct xkb_keymap` on success, or NULL on failure.
```

--------------------------------

### XKB Rule %-Expansion for Values

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Shows how to use %-expansion within KccgstValue to refer to model, layout, and variant values, including indexed access.

```xkb
`%m`, `%l`, `%v` 
    The model, layout or variant, if _only one_ was given (e.g. `%l` for “us,il” is invalid).  

`%l[1]`, `%l[2]`, …, `%v[1]`, `%v[2]`, … 
    Layout or variant for the specified layout Index, if _more than one_ was given, e.g.: `%l[1]` is invalid for “us” but expands to “us” for “us,de”.  

`%+m, %+l, %+l[1], %+l[2], …, %+v, %+v[1], %+v[2], …` 
    As above, but prefixed with ‘+’. Similarly, ‘|’, ‘^’, ‘-’, ‘_’ may be used instead of ‘+’. See the merge mode documentation for the special meaning of ‘+’, ‘|’ and ‘^’.  

`%(m), %(l), %(l[1]), %(l[2]), …, %(v), %(v[1]), %(v[2]), …` 
    As above, but prefixed by ‘(’ and suffixed by ‘)’.  

`:%i, %l[%i], %(l[%i]), etc.` 
    
In case the mapping uses an extended layout index, %i corresponds to the index of the matched layout.
```

--------------------------------

### Interpret Modifier Predicate

Source: https://xkbcommon.org/doc/current/release-notes.html

Example of an interpret modifier predicate. Previously, extraneous arguments were ignored; now, they are rejected.

```xkb
interpret ISO_Level3_Shift+AnyOf(all,extraneous) { ... };
```

--------------------------------

### Extended Layout Indices in XKB

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Demonstrates the usage of extended layout indices like 'single', 'first', 'later', and 'any' for more flexible layout matching.

```xkb
single 
    Matches a single layout; layout[single] is the same as without explicit index: layout.  

first 
    Matches the first layout/variant, no matter how many layouts are in the RMLVO configuration. Acts as both layout and layout[1].  

later 
    Matches all but the first layout. This is an index _range_. Acts as layout[2] .. layout[4].  

any 
    Matches layout at any position. This is an index _range_. Acts as layout, layout[1] .. layout[4].
```

--------------------------------

### Get Keysym Name

Source: https://xkbcommon.org/doc/current/md_doc_2quick-guide.html

Retrieves the name of a given keysym. Ensure the buffer is large enough to hold the name.

```c
char keysym_name[64];
if (keysym == XKB_KEY_Space)
<got a space>
xkb_keysym_get_name(keysym, keysym_name, sizeof(keysym_name));
```

--------------------------------

### rxkb_layout_get_brief()

Source: https://xkbcommon.org/doc/current/group__registry.html

Retrieves a short, one-word description of the XKB layout.

```APIDOC
## rxkb_layout_get_brief()

### Description
Return a short (one-word) description of this layout.

### Parameters
* `_l_` (struct rxkb_layout *) - The layout structure to query.

### Returns
* `const char *` - A brief description of the layout, or NULL if not available.
```

--------------------------------

### xkb_state_key_get_utf8

Source: https://xkbcommon.org/doc/current/functions.html

Gets the UTF-8 string representation of a symbol for a key at the current layout and level. Suitable for direct display.

```APIDOC
## xkb_state_key_get_utf8()

### Description
Gets the UTF-8 string representation of a symbol for a key at the current layout and level. Suitable for direct display.

### Method
Not Applicable (Function Call)

### Endpoint
Not Applicable (Function Call)

### Parameters
None explicitly documented in this snippet.

### Request Example
Not Applicable (Function Call)

### Response
Returns the UTF-8 string.

#### Success Response
- **return value** (`const char *`) - A pointer to the UTF-8 string representation.
```

--------------------------------

### xkb_context_include_path_append_default

Source: https://xkbcommon.org/doc/current/group__include-path.html

Appends the default include paths to the xkb_context. This ensures that standard keyboard description files can be found.

```APIDOC
## xkb_context_include_path_append_default

### Description
Appends the default include paths to the xkb_context. This ensures that standard keyboard description files can be found.

### Method
`int`

### Parameters
- **context** (`struct xkb_context *`) - The xkb_context to modify.
```

--------------------------------

### Compiling Keymap from File

Source: https://xkbcommon.org/doc/current/faq.html

This command compiles a keymap from a specified file, serving as a replacement for xkbcomp -xkb /path/to/keymap/file.

```bash
xkbcli compile-keymap --keymap /path/to/keymap/file
```

--------------------------------

### xkb_state_key_get_syms

Source: https://xkbcommon.org/doc/current/functions.html

Gets all symbols associated with a key for the current layout and level. This can return multiple symbols if the key has different outputs.

```APIDOC
## xkb_state_key_get_syms()

### Description
Gets all symbols associated with a key for the current layout and level. This can return multiple symbols if the key has different outputs.

### Method
Not Applicable (Function Call)

### Endpoint
Not Applicable (Function Call)

### Parameters
None explicitly documented in this snippet.

### Request Example
Not Applicable (Function Call)

### Response
Returns an array of symbols.

#### Success Response
- **return value** (`const xkb_keysym_t *`) - A pointer to an array of keysyms.
```

--------------------------------

### xkb_state_key_get_one_sym

Source: https://xkbcommon.org/doc/current/functions.html

Retrieves a single symbol associated with a key at the current layout and level. Useful for getting the primary character output.

```APIDOC
## xkb_state_key_get_one_sym()

### Description
Retrieves a single symbol associated with a key at the current layout and level. Useful for getting the primary character output.

### Method
Not Applicable (Function Call)

### Endpoint
Not Applicable (Function Call)

### Parameters
None explicitly documented in this snippet.

### Request Example
Not Applicable (Function Call)

### Response
Returns the symbol value.

#### Success Response
- **return value** (`xkb_keysym_t`) - The keysym value.
```

--------------------------------

### rxkb_context_parse()

Source: https://xkbcommon.org/doc/current/globals.html

Parses XKB configuration data into the rxkb_context.

```APIDOC
## rxkb_context_parse()

### Description
Parses XKB configuration data into the rxkb_context.

### Function Signature
`bool rxkb_context_parse(rxkb_context *context, const char *string);`

### Parameters
*   **context** (*rxkb_context* *) - A pointer to the rxkb_context.
*   **string** (*const char* *) - A string containing XKB configuration data.

### Returns
`true` on success, `false` on failure.

### File
xkbregistry.h
```

--------------------------------

### xkb_state_key_get_consumed_mods

Source: https://xkbcommon.org/doc/current/functions.html

Gets the modifier state consumed by a specific key press. This helps in understanding how modifiers affect key behavior.

```APIDOC
## xkb_state_key_get_consumed_mods()

### Description
Gets the modifier state consumed by a specific key press. This helps in understanding how modifiers affect key behavior.

### Method
Not Applicable (Function Call)

### Endpoint
Not Applicable (Function Call)

### Parameters
None explicitly documented in this snippet.

### Request Example
Not Applicable (Function Call)

### Response
Returns the consumed modifier mask.

#### Success Response
- **return value** (`xkb_mod_mask_t`) - The modifier mask representing consumed modifiers.
```

--------------------------------

### xkb_context Functions

Source: https://xkbcommon.org/doc/current/functions.html

Functions for creating, configuring, and managing the xkb context, including include paths, logging, and user data.

```APIDOC
## xkb_context Functions

### Description
Functions for creating, configuring, and managing the xkb context, including include paths, logging, and user data.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response
- **xkb_context** (struct) - The xkb context.

### Response Example
(Not specified in source)
```

--------------------------------

### xkb_rmlvo_builder_new

Source: https://xkbcommon.org/doc/current/functions.html

Creates a new rmlvo builder. This is the starting point for constructing rule, modifier, layout, variant, and option configurations.

```APIDOC
## xkb_rmlvo_builder_new()

### Description
Creates a new rmlvo builder. This is the starting point for constructing rule, modifier, layout, variant, and option configurations.

### Method
Not Applicable (Function Call)

### Endpoint
Not Applicable (Function Call)

### Parameters
None explicitly documented in this snippet.

### Request Example
Not Applicable (Function Call)

### Response
Returns a new `xkb_rmlvo_builder` object.

#### Success Response
- **return value** (`xkb_rmlvo_builder`) - A newly created rmlvo builder object.
```

--------------------------------

### rxkb_context_new()

Source: https://xkbcommon.org/doc/current/globals.html

Creates a new rxkb_context.

```APIDOC
## rxkb_context_new()

### Description
Creates a new rxkb_context.

### Function Signature
`rxkb_context *rxkb_context_new(rxkb_context_flags flags);`

### Parameters
*   **flags** (*rxkb_context_flags*) - Flags to configure the new context.

### Returns
A pointer to the newly created rxkb_context, or NULL on failure.

### File
xkbregistry.h
```

--------------------------------

### Essential Headers for xkbcommon

Source: https://xkbcommon.org/doc/current/xkbcommon_8h.html

Includes necessary standard C headers and libxkbcommon specific headers for keyboard functionality.

```c
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdarg.h>
#include <xkbcommon/xkbcommon-names.h>
#include <xkbcommon/xkbcommon-keysyms.h>
#include <xkbcommon/xkbcommon-compat.h>
```

--------------------------------

### Rule with Specific Layout and Option

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Applies a rule only when both the layout and option match specific values. Example: 'be caps:digits_row'.

```xkbcommon
be caps:digits_row = +capslock(digits_row)
```

```xkbcommon
fr caps:digits_row = +capslock(digits_row)
```

--------------------------------

### Rule Set with Multiple LHS Components

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Allows matching on multiple MLVO components. Example: matching 'layout' and 'option' simultaneously.

```xkbcommon
! layout option = symbols
```

--------------------------------

### xkb_state_key_get_level

Source: https://xkbcommon.org/doc/current/functions.html

Gets the active level for a key. Levels typically correspond to Shift, AltGr, etc., modifying the key's output.

```APIDOC
## xkb_state_key_get_level()

### Description
Gets the active level for a key. Levels typically correspond to Shift, AltGr, etc., modifying the key's output.

### Method
Not Applicable (Function Call)

### Endpoint
Not Applicable (Function Call)

### Parameters
None explicitly documented in this snippet.

### Request Example
Not Applicable (Function Call)

### Response
Returns the index of the active level.

#### Success Response
- **return value** (`int`) - The index of the active level.
```

--------------------------------

### Rule Set Header

Source: https://xkbcommon.org/doc/current/rule-file-format.html

Defines a rule set mapping MLVO options to KcCGST symbols. Starts with '!' followed by 'option = symbols'.

```xkbcommon
! option = symbols
```

--------------------------------

### xkb_keymap_new_from_string

Source: https://xkbcommon.org/doc/current/group__keymap.html

Creates a new XKB keymap from a null-terminated string. It takes a context, the keymap string, a format, and compilation flags.

```APIDOC
## xkb_keymap_new_from_string()

### Description
Creates a keymap from a keymap string. This function is similar to `xkb_keymap_new_from_file()`, but reads the keymap from a string.

### Parameters
- **_context_** (struct xkb_context *) - The XKB context.
- **_string_** (const char *) - The null-terminated string containing the keymap definition.
- **_format_** (enum xkb_keymap_format) - The format of the keymap string.
- **_flags_** (enum xkb_keymap_compile_flags) - Flags to control the compilation process.

### Returns
- struct xkb_keymap * - A pointer to the newly created keymap, or NULL on failure.
```
Tokens:
Raw