5 This document contains a quick walk-through of the often-used parts of
6 the library. We will employ a few use-cases to lead the examples:
8 1. An evdev client. "evdev" is the Linux kernel's input subsystem; it
9 only reports to the client which keys are pressed and released.
11 2. An X11 client, using the XCB library to communicate with the X
12 server and the xcb-xkb library for using the XKB protocol.
14 3. A Wayland client, using the standard protocol.
16 The snippets are not complete, and some support code is omitted. You
17 can find complete and more complex examples in the source directory:
19 1. test/interactive-evdev.c contains an interactive evdev client.
21 2. test/interactive-x11.c contains an interactive X11 client.
23 Also, the library contains many more functions for examining and using
24 the library context, the keymap and the keyboard state. See the
25 hyper-linked reference documentation or go through the header files in
26 xkbcommon/ for more details.
30 Before we can do anything interesting, we need a library context:
33 #include <xkbcommon/xkbcommon.h>
35 struct xkb_context *ctx;
37 ctx = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
41 The `xkb_context` contains the keymap include paths, the log level and
42 functions, and other general customizable administrativia.
44 Next we need to create a keymap, `xkb_keymap`. This is an immutable object
45 which contains all of the information about the keys, layouts, etc. There
46 are different ways to do this.
48 If we are an evdev client, we have nothing to go by, so we need to ask
49 the user for his/her keymap preferences (for example, an Icelandic
50 keyboard with a Dvorak layout). The configuration format is commonly
51 called RMLVO (Rules+Model+Layout+Variant+Options), the same format used
52 by the X server. With it, we can fill a struct called `xkb_rule_names`;
53 passing `NULL` chooses the system's default.
56 struct xkb_keymap *keymap;
57 /* Example RMLVO for Icelandic Dvorak. */
58 struct xkb_rule_names names = {
63 .options = "terminate:ctrl_alt_bksp"
66 keymap = xkb_keymap_new_from_names(ctx, &names,
67 XKB_KEYMAP_COMPILE_NO_FLAGS);
71 If we are a Wayland client, the compositor gives us a string complete
72 with a keymap. In this case, we can create the keymap object like this:
75 /* From the wl_keyboard::keymap event. */
76 const char *keymap_string = <...>;
77 struct xkb_keymap *keymap;
79 keymap = xkb_keymap_new_from_string(ctx, keymap_string,
80 XKB_KEYMAP_FORMAT_TEXT_V1,
81 XKB_KEYMAP_COMPILE_NO_FLAGS);
85 If we are an X11 client, we are better off getting the keymap from the
86 X server directly. For this we need to choose the XInput device; here
87 we will use the core keyboard device:
90 #include <xkbcommon/xkbcommon-x11.h>
92 xcb_connection_t *conn = <...>;
95 device_id = xkb_x11_get_core_keyboard_device_id(conn);
96 if (device_id == -1) <error>
98 keymap = xkb_x11_keymap_new_from_device(ctx, conn, device_id,
99 XKB_KEYMAP_COMPILE_NO_FLAGS);
103 Now that we have the keymap, we are ready to handle the keyboard devices.
104 For each device, we create an `xkb_state`, which remembers things like which
105 keyboard modifiers and LEDs are active:
108 struct xkb_state *state;
110 state = xkb_state_new(keymap);
114 For X11/XCB clients, this is better:
117 state = xkb_x11_state_new_from_device(keymap, conn, device_id);
121 When we have an `xkb_state` for a device, we can start handling key events
122 from it. Given a keycode for a key, we can get its keysym:
125 <key event structure> event;
126 xkb_keycode_t keycode;
129 keycode = event->keycode;
130 keysym = xkb_state_key_get_one_sym(state, keycode);
133 We can see which keysym we got, and get its name:
136 char keysym_name[64];
138 if (keysym == XKB_KEY_Space)
141 xkb_keysym_get_name(keysym, keysym_name, sizeof(keysym_name));
144 libxkbcommon also supports an extension to the classic XKB, whereby a
145 single event can result in multiple keysyms. Here's how to use it:
148 const xkb_keysym_t *keysyms;
151 num_keysyms = xkb_state_key_get_syms(state, keycode, &keysyms);
154 We can also get a UTF-8 string representation for this key:
160 // First find the needed size; return value is the same as snprintf(3).
161 size = xkb_state_key_get_utf8(state, keycode, NULL, 0) + 1;
162 if (size <= 1) <nothing to do>
163 buffer = <allocate size bytes>
165 xkb_state_key_get_utf8(state, keycode, buffer, size);
168 Of course, we also need to keep the `xkb_state` up-to-date with the
169 keyboard device, if we want to get the correct keysyms in the future.
171 If we are an evdev client, we must let the library know whether a key
172 is pressed or released at any given time:
175 enum xkb_state_component changed;
178 changed = xkb_state_update_key(state, keycode, XKB_KEY_DOWN);
179 else if (<key release>)
180 changed = xkb_state_update_key(state, keycode, XKB_KEY_UP);
183 The `changed` return value tells us exactly which parts of the state
186 If it is a key-repeat event, we can ask the keymap what to do with it:
189 if (<key repeat> && !xkb_keymap_key_repeats(keymap, keycode))
193 On the other hand, if we are an X or Wayland client, the server already
194 does the hard work for us. It notifies us when the device's state
195 changes, and we can simply use what it tells us (the necessary
196 information usually comes in a form of some "state changed" event):
199 changed = xkb_state_update_mask(state,
200 event->depressed_mods,
203 event->depressed_layout,
204 event->latched_layout,
205 event->locked_layout);
208 Now that we have an always-up-to-date `xkb_state`, we can examine it.
209 For example, we can check whether the Control modifier is active, or
210 whether the Num Lock LED is active:
213 if (xkb_state_mod_name_is_active(state, XKB_MOD_NAME_CTRL,
214 XKB_STATE_MODS_EFFECTIVE) > 0)
215 <The Control modifier is active>
217 if (xkb_state_led_name_is_active(state, XKB_LED_NAME_NUM) > 0)
218 <The Num Lock LED is active>
221 And that's it! Eventually, we should free the objects we've created:
224 xkb_state_unref(state);
225 xkb_keymap_unref(keymap);
226 xkb_context_unref(ctx);