Quick Guide

Table of Contents

• Introduction
• Code for clients
• Code for a Wayland server

Introduction

This document contains a quick walk-through of the often-used parts of the library. We will employ a few use-cases to lead the examples:

1. An evdev client. evdev is the Linux kernel’s input subsystem; it only reports to the client which keys are pressed and released.
2. An X11 client, using the XCB library to communicate with the X server and the xcb-xkb library for using the XKB protocol.
3. A Wayland client, using the standard protocol.
4. A Wayland server, using the standard protocol.

The snippets are not complete, and some support code is omitted. You can find complete and more complex examples in the [source directory]:

1. tools/interactive-evdev.c contains an interactive evdev client.
2. tools/interactive-x11.c contains an interactive X11 client.
3. tools/interactive-wayland.c contains an interactive Wayland client.

Also, the library contains many more functions for examining and using the library context, the keymap and the keyboard state. See the hyper-linked reference documentation or go through the header files in xkbcommon/ for more details.

Code for clients

Before we can do anything interesting, we need a library context:

#include <xkbcommon/xkbcommon.h>
struct xkb_context *ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
if (!ctx) {
    /* Handle error */
    // ...
    exit(EXIT_FAILURE);
}

The xkb_context contains the keymap include paths, the log level and functions, and other general customizable administrativia.

Next we need to create a keymap, xkb_keymap. This is an immutable object which contains all of the information about the keys, layouts, etc. There are different ways to do this.

If we are an evdev client, we have nothing to go by, so we need to ask the user for his/her keymap preferences (for example, an Icelandic keyboard with a Dvorak layout). The configuration format is commonly called RMLVO (Rules+Model+Layout+Variant+Options), the same format used by the X server. With it, we can fill a struct called xkb_rule_names; passing NULL chooses the system’s default.

/* Example RMLVO for Canadian Dvorak. */
const struct xkb_rule_names names = {
    .rules = NULL,
    .model = "pc105",
    .layout = "ca",
    .variant = "fr-dvorak",
    .options = "terminate:ctrl_alt_bksp"
};
 
struct xkb_keymap *keymap = xkb_keymap_new_from_names2(
    ctx, &names, XKB_KEYMAP_FORMAT_TEXT_V1, XKB_KEYMAP_COMPILE_NO_FLAGS
);
if (!keymap) {
    /* Handle error */
    // ...
    exit(EXIT_FAILURE);
}

If we are a Wayland client, the compositor gives us a string complete with a keymap. In this case, we can create the keymap object like this:

/*
 * From the wl_keyboard::keymap event:
 * - format,
 * - keymap_buffer,
 * - keymap_buffer_size
 */
*keymap = xkb_keymap_new_from_buffer(ctx,
                                    keymap_buffer,
                                    keymap_buffer_size,
                                    format,
                                    XKB_KEYMAP_COMPILE_NO_FLAGS);
if (!*keymap) {
    /* Handle error */
    // ...
    exit(EXIT_FAILURE);
}

If we are an X11 client, we are better off getting the keymap from the X server directly. For this we need to choose the XInput device; here we will use the core keyboard device:

#include <xkbcommon/xkbcommon-x11.h>
 
int ret = EXIT_SUCCESS;
xcb_connection_t *conn = xcb_connect(display, NULL);
if (!conn || xcb_connection_has_error(conn)) {
    /* Handle connection error */
    // ...
    ret = EXIT_FAILURE;
    goto connection_error;
}
 
ret = xkb_x11_setup_xkb_extension(conn,
                                  XKB_X11_MIN_MAJOR_XKB_VERSION,
                                  XKB_X11_MIN_MINOR_XKB_VERSION,
                                  XKB_X11_SETUP_XKB_EXTENSION_NO_FLAGS,
                                  NULL, NULL, NULL, NULL);
if (!ret) {
    goto connection_error;
}
 
int32_t device_id = xkb_x11_get_core_keyboard_device_id(conn);
if (device_id == -1) {
    /* Handle device error */
    // ...
    ret = EXIT_FAILURE;
    goto device_error;
}
 
struct xkb_keymap *keymap = xkb_x11_keymap_new_from_device(
    ctx, conn, device_id, XKB_KEYMAP_COMPILE_NO_FLAGS
);
if (!keymap) {
    /* Handle keymap error */
    // ...
    ret = EXIT_FAILURE;
    goto keymap_error;
}

Now that we have the keymap, we are ready to handle the keyboard devices. For each device, we create an xkb_state, which remembers things like which keyboard modifiers and LEDs are active:

Wayland

enum xkb_error_code error;
struct xkb_state *state;
 
state = xkb_state_new_with_mode(keymap, XKB_STATE_MODE_CLIENT, &error);
if (!state) {
    /* Handle error */
    assert(error != XKB_SUCCESS);
    switch (error) {
    // ...
    default:
        exit(EXIT_FAILURE);
    }
}

X11/XCB

struct xkb_state *state = xkb_x11_state_new_from_device(keymap, conn, device_id);
if (!state)  {
    /* Handle error */
    // ...
    ret = EXIT_FAILURE;
    goto state_error;
}

evdev

struct xkb_state *state = xkb_state_new(keymap);
if (!state) {
    /* Handle error */
    // ...
    exit(EXIT_FAILURE);
}

When we have an xkb_state for a device, we can start handling key events from it. Given a keycode for a key, we can get its keysym:

/* Key event was delivered in `*event` */
xkb_keycode_t keycode = event->keycode;
xkb_keysym_t keysym;
keysym = xkb_state_key_get_one_sym(state, keycode);

We can see which keysym we got, and get its name:

switch(keysym) {
    case XKB_KEY_space:
        /* Got a space */
        // ...
        break;
    // ...
    default:
        /* Default handle */
        // ...
        assert(!"unhandled keysym");
}
 
char keysym_name[64];
xkb_keysym_get_name(keysym, keysym_name, sizeof(keysym_name));

xkbcommon also supports an extension to the classic XKB, whereby a single event can result in multiple keysyms. Here’s how to use it:

const xkb_keysym_t *keysyms;
const int num_keysyms = xkb_state_key_get_syms(state, keycode, &keysyms);
for (int k = 0; k < num_keysyms; k++) {
    /* Handle keysym */
    // ...
    handle_keysym(keysyms[k]);
}

We can also get a UTF-8 string representation for this key:

/* First find the needed size; return value is the same as snprintf(3). */
int size = xkb_state_key_get_utf8(state, keycode, NULL, 0) + 1;
if (size <= 1) {
    /* Handle keysym with no UTF-8 representation */
    assert(!"no UTF-8 representation");
} else {
    char *utf8 = malloc((size_t)size);
    if (!utf8) {
        /* Handle error */
        // ...
        exit(EXIT_FAILURE);
    }
    xkb_state_key_get_utf8(state, keycode, utf8, size);
    assert(*utf8 != '\0');
    // ...
    free(utf8);
}

Of course, we also need to keep the xkb_state up-to-date with the keyboard device, if we want to get the correct keysyms in the future.

If we are an evdev client, we must let the library know whether a key is pressed or released at any given time:

enum xkb_state_component changed;
enum {
    KEY_STATE_RELEASE = 0,
    KEY_STATE_PRESS = 1,
    KEY_STATE_REPEAT = 2,
};
switch (direction) {
    case KEY_STATE_RELEASE:
        changed = xkb_state_update_key(state, keycode, XKB_KEY_UP);
        break;
    case KEY_STATE_PRESS:
        changed = xkb_state_update_key(state, keycode, XKB_KEY_DOWN);
        break;
    case KEY_STATE_REPEAT:
        changed = xkb_state_update_key(state, keycode, XKB_KEY_REPEATED);
        break;
    default:
        /* Handle error */
        // ...
        exit(EXIT_FAILURE);
}

The changed return value tells us exactly which parts of the state have changed.

If it is a key-repeat event, we can ask the keymap what to do with it:

if (direction == KEY_STATE_REPEAT &&
    !xkb_keymap_key_repeats(keymap, keycode)) {
    /* Discard event */
    // ...
}

On the other hand, if we are an X or Wayland client, the server already does the hard work for us. It notifies us when the device’s state changes, and we can simply use what it tells us (the necessary information usually comes in a form of some “state changed” event):

enum xkb_state_component changed = xkb_state_update_mask(
    state,
    event->depressed_mods,
    event->latched_mods,
    event->locked_mods,
    event->depressed_layout,
    event->latched_layout,
    event->locked_layout
);

Now that we have an always-up-to-date xkb_state, we can examine it. For example, we can check whether the Control modifier is active, or whether the Num Lock LED is active:

if (changed & XKB_STATE_MODS_EFFECTIVE) {
    if (xkb_state_mod_name_is_active(state, XKB_MOD_NAME_CTRL,
                                    XKB_STATE_MODS_EFFECTIVE) > 0) {
        /* Handle active Control modifier */
        // ...
    }
}
if (changed & XKB_STATE_LEDS) {
    if (xkb_state_led_name_is_active(state, XKB_LED_NAME_NUM) > 0) {
        /* Handle active Num Lock LED */
        // ...
    }
}

And that’s it! Eventually, we should free the objects we’ve created:

xkb_state_unref(state);
xkb_keymap_unref(keymap);
xkb_context_unref(ctx);

Code for a Wayland server

The code is very similar to the evdev client presented hereinabove. The main difference is the use of the xkb_machine API instead of the xkb_state API.

#include <xkbcommon/xkbcommon.h>
 
enum {
    EVDEV_OFFSET = 8,
};
 
struct my_keyboard {
    struct xkb_context *ctx;
    struct xkb_keymap *keymap;
    struct xkb_machine *machine;
    struct xkb_events *events;
};
 
static int
new_keyboard(struct my_keyboard *keyboard, const struct xkb_rule_names *names)
{
    assert(keyboard->ctx);
 
    /*
     * Initialize the keymap
     */
 
    struct xkb_keymap *keymap =
        xkb_keymap_new_from_names2(keyboard->ctx, names,
                                   XKB_KEYMAP_FORMAT_TEXT_V1,
                                   XKB_KEYMAP_COMPILE_NO_FLAGS);
    if (!keymap) {
        /* Handle error */
        // ...
        exit(EXIT_FAILURE);
    }
 
    /*
     * Initialize the state machine
     */
 
    enum xkb_error_code error;
    struct xkb_machine_builder_config config = { .size = sizeof(config) };
    struct xkb_machine_builder *machine_builder =
        xkb_machine_builder_new(keymap, &config, &error);
    if (!machine_builder) {
        assert(error != XKB_SUCCESS);
        switch (error) {
        // ...
        default:
            exit(EXIT_FAILURE);
        }
    }
    struct xkb_machine *machine = xkb_machine_new(machine_builder, &error);
    xkb_machine_builder_unref(machine_builder);
    if (!machine) {
        assert(error != XKB_SUCCESS);
        switch (error) {
        // ...
        default:
            exit(EXIT_FAILURE);
        }
    }
 
    struct xkb_events *events = xkb_events_new(keyboard->ctx, NULL, &error);
    if (!events) {
        assert(error != XKB_SUCCESS);
        switch (error) {
        // ...
        default:
            exit(EXIT_FAILURE);
        }
    }
 
    char *keymap_string =
        xkb_keymap_get_as_string(keymap, XKB_KEYMAP_FORMAT_TEXT_V1);
 
    if (!keymap_string) {
        /* Handle error */
        // ...
        exit(EXIT_FAILURE);
    }
 
    /* Send keymap to the clients */
    // ...
 
    free(keymap_string);
 
    /* Save the objects for further use */
    keyboard->keymap = keymap;
    keyboard->machine = machine;
    keyboard->events = events;
 
    return EXIT_SUCCESS;
}
 
static int
destroy_keyboard(struct my_keyboard *keyboard)
{
    xkb_events_unref(keyboard->events);
    xkb_machine_unref(keyboard->machine);
    xkb_keymap_unref(keyboard->keymap);
    xkb_context_unref(keyboard->ctx);
    return EXIT_SUCCESS;
}
 
static int
handle_key(struct my_keyboard *keyboard, uint32_t key, uint32_t state)
{
    /*
     * Update the server state with the key event
     */
 
    const xkb_keycode_t keycode = key + EVDEV_OFFSET;
    enum xkb_key_direction direction = WL_KEYBOARD_KEY_STATE_RELEASED
        ? XKB_KEY_UP
        : WL_KEYBOARD_KEY_STATE_REPEATED
            ? XKB_KEY_REPEATED
            : XKB_KEY_DOWN;
    enum xkb_error_code error =
        xkb_machine_process_key(keyboard->machine, keycode, direction,
                                keyboard->events);
    if (error != XKB_SUCCESS) {
        /* Handle error */
        // ...
        exit(EXIT_FAILURE);
    }
 
    /*
     * Process the generated XKB events
     */
 
    const struct xkb_event *event;
    while ((event = xkb_events_next(keyboard->events)) != NULL) {
        const enum xkb_event_type event_type =
            xkb_event_get_type(event);
        switch (event_type) {
            case XKB_EVENT_TYPE_INVALID:
                /* Report error */
                // ...
                exit(EXIT_FAILURE);
            case XKB_EVENT_TYPE_KEY: {
                xkb_keycode_t kc = XKB_KEYCODE_INVALID;
                error = xkb_event_get_keycode(event, &kc, &direction);
                if (error != XKB_SUCCESS) {
                    /* Handle error */
                    // ...
                    exit(EXIT_FAILURE);
                }
                /* Send key event to clients */
                // ...
                assert(kc != XKB_KEYCODE_INVALID);
                break;
            }
            case XKB_EVENT_TYPE_STATE_COMPONENTS: {
                struct xkb_event_components components = {
                    .size = sizeof(components)
                };
                error = xkb_event_get_components(event, &components);
                if (error != XKB_SUCCESS) {
                    /* Handle error */
                    // ...
                    exit(EXIT_FAILURE);
                }
                if (components.changed) {
                    /* Send component changes to clients */
                    // ...
                }
                break;
            }
            case XKB_EVENT_TYPE_POINTER_MOTION: {
                struct xkb_event_pointer_motion motion = {
                    .size = sizeof(motion)
                };
                error = xkb_event_get_pointer_motion(event, &motion);
                if (error != XKB_SUCCESS) {
                    /* Handle error */
                    // ...
                    exit(EXIT_FAILURE);
                }
                /* Move cursor */
                // ...
                break;
            }
            case XKB_EVENT_TYPE_POINTER_BUTTON: {
                struct xkb_event_pointer_button button = {
                    .size = sizeof(button)
                };
                error = xkb_event_get_pointer_button(event, &button);
                assert(error == XKB_SUCCESS);
                if (error != XKB_SUCCESS) {
                    /* Handle error */
                    // ...
                    exit(EXIT_FAILURE);
                }
                /* Operate button */
                // ...
                break;
            }
            default:
                /* Report unhandled event */
                // ...
                exit(EXIT_FAILURE);
        }
    }
    return EXIT_SUCCESS;
}

Synthetic updates are handled using xkb_machine::xkb_machine_process_synthetic().