/usr/share/doc/libxkbcommon-dev/md_doc_quick-guide.html is in libxkbcommon-dev 0.5.0-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.9.1"/>
<title>libxkbcommon: Quick Guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-extra.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libxkbcommon
 <span id="projectnumber">0.5.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Quick Guide </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Introduction</h2>
<p>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:</p>
<ol type="1">
<li>An evdev client. "evdev" is the Linux kernel's input subsystem; it only reports to the client which keys are pressed and released.</li>
<li>An X11 client, using the XCB library to communicate with the X server and the xcb-xkb library for using the XKB protocol.</li>
<li>A Wayland client, using the standard protocol.</li>
</ol>
<p>The snippets are not complete, and some support code is omitted. You can find complete and more complex examples in the source directory:</p>
<ol type="1">
<li>test/interactive-evdev.c contains an interactive evdev client.</li>
<li>test/interactive-x11.c contains an interactive X11 client.</li>
</ol>
<p>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.</p>
<h2>Code</h2>
<p>Before we can do anything interesting, we need a library context. So let's create one:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="xkbcommon_8h.html">xkbcommon/xkbcommon.h</a>></span></div>
<div class="line"></div>
<div class="line"><span class="keyword">struct </span><a class="code" href="structxkb__context.html">xkb_context</a> ctx;</div>
<div class="line"></div>
<div class="line">ctx = <a class="code" href="group__context.html#gacecddbdb020205f335719fe445dc9fdc">xkb_context_new</a>(<a class="code" href="group__context.html#ggaea2acb5b9e06239e20a7c34f5b223092a52382673b85690e1990796b1c9c20538">XKB_CONTEXT_NO_FLAGS</a>);</div>
<div class="line"><span class="keywordflow">if</span> (!ctx) <error></div>
</div><!-- fragment --><p>The <a class="el" href="structxkb__context.html" title="Opaque top level library context object. ">xkb_context</a> contains the keymap include paths, the log level and functions, and other general customizable administrativia.</p>
<p>Next we need to create a keymap, <a class="el" href="structxkb__keymap.html" title="Opaque compiled keymap object. ">xkb_keymap</a>. This is an immutable object which contains all of the information about the keys, layouts, etc. There are different ways to do this.</p>
<p>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 <a class="el" href="structxkb__rule__names.html" title="Names to compile a keymap with, also known as RMLVO. ">xkb_rule_names</a>; passing NULL chooses the system's default.</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code" href="structxkb__keymap.html">xkb_keymap</a> *keymap;</div>
<div class="line"><span class="comment">/* Example RMLVO for Icelandic Dvorak. */</span></div>
<div class="line"><span class="keyword">struct </span><a class="code" href="structxkb__rule__names.html">xkb_rule_names</a> names = {</div>
<div class="line"> .<a class="code" href="structxkb__rule__names.html#a0968f4602001f2306febd32c34bd2280">rules</a> = NULL,</div>
<div class="line"> .model = <span class="stringliteral">"pc105"</span>,</div>
<div class="line"> .layout = <span class="stringliteral">"is"</span>,</div>
<div class="line"> .variant = <span class="stringliteral">"dvorak"</span>,</div>
<div class="line"> .options = <span class="stringliteral">"terminate:ctrl_alt_bksp"</span></div>
<div class="line">};</div>
<div class="line"></div>
<div class="line">keymap = <a class="code" href="group__keymap.html#ga502717aa7148fd17d4970896f1e9e06f">xkb_keymap_new_from_names</a>(ctx, &names,</div>
<div class="line"> <a class="code" href="group__keymap.html#ggad418fa5861e00b37c362075a380299b2ae274bf0a09997d395e712156b0dbf7fa">XKB_KEYMAP_COMPILE_NO_FLAGS</a>);</div>
<div class="line"><span class="keywordflow">if</span> (!keymap) <error></div>
</div><!-- fragment --><p>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:</p>
<div class="fragment"><div class="line"><span class="comment">/* From the wl_keyboard::keymap event. */</span></div>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *keymap_string = <...>;</div>
<div class="line"></div>
<div class="line">keymap = <a class="code" href="group__keymap.html#ga9d98e2e1348bd756bd3229d0b9432886">xkb_keymap_new_from_string</a>(ctx, keymap_string,</div>
<div class="line"> <a class="code" href="group__keymap.html#ggab0f75d6cc5773e5dd404e2c3f61366a3ad63ee709a87611a89b42c3e1275347ed">XKB_KEYMAP_FORMAT_TEXT_V1</a>,</div>
<div class="line"> <a class="code" href="group__keymap.html#ggad418fa5861e00b37c362075a380299b2ae274bf0a09997d395e712156b0dbf7fa">XKB_KEYMAP_COMPILE_NO_FLAGS</a>);</div>
<div class="line"><span class="keywordflow">if</span> (!keymap) <error></div>
</div><!-- fragment --><p>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:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="xkbcommon-x11_8h.html">xkbcommon/xkbcommon-x11.h</a>></span></div>
<div class="line"></div>
<div class="line">xcb_connection_t *conn = <...>;</div>
<div class="line">int32_t device_id;</div>
<div class="line"></div>
<div class="line">device_id = <a class="code" href="group__x11.html#ga8b01ff183ac596884b008e1c65f1afea">xkb_x11_get_core_keyboard_device_id</a>(conn);</div>
<div class="line"><span class="keywordflow">if</span> (device_id == -1) <error></div>
<div class="line"></div>
<div class="line">keymap = <a class="code" href="group__x11.html#ga9ccc80dcb7488167c8466cb833286559">xkb_x11_keymap_new_from_device</a>(ctx, conn, device_id,</div>
<div class="line"> <a class="code" href="group__keymap.html#ggad418fa5861e00b37c362075a380299b2ae274bf0a09997d395e712156b0dbf7fa">XKB_KEYMAP_COMPILE_NO_FLAGS</a>);</div>
<div class="line"><span class="keywordflow">if</span> (!keymap) <error></div>
</div><!-- fragment --><p>Now that we have the keymap, we are ready to handle the keyboard devices. For each device, we create an <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a>, which remembers things like which keyboard modifiers and LEDs are active:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code" href="structxkb__state.html">xkb_state</a> *state;</div>
<div class="line"></div>
<div class="line">state = <a class="code" href="group__state.html#ga281f0dc1cab624ab11e7c4d318d9d4ac">xkb_state_new</a>(keymap);</div>
<div class="line"><span class="keywordflow">if</span> (!state) <error></div>
</div><!-- fragment --><p>For X11/XCB clients, this is better:</p>
<div class="fragment"><div class="line">state = <a class="code" href="group__x11.html#gaf710c637c60d9a47a9cce37b89d2afe2">xkb_x11_state_new_from_device</a>(keymap, conn, device_id);</div>
<div class="line"><span class="keywordflow">if</span> (!state) <error></div>
</div><!-- fragment --><p>When we have an <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a> for a device, we can start handling key events from it. Given a keycode for a key, we can get its keysym:</p>
<div class="fragment"><div class="line"><key <span class="keyword">event</span> structure> event;</div>
<div class="line"><a class="code" href="xkbcommon_8h.html#ac29aee92124c08d1953910ab28ee1997">xkb_keycode_t</a> keycode;</div>
<div class="line"><a class="code" href="xkbcommon_8h.html#a79e604a22703391bdfe212cfc10ea007">xkb_keysym_t</a> keysym;</div>
<div class="line"></div>
<div class="line">keycode = <span class="keyword">event</span>->keycode;</div>
<div class="line">keysym = <a class="code" href="group__state.html#gae56031a8c1d48e7802da32f5f39f5738">xkb_state_key_get_one_sym</a>(state, keycode);</div>
</div><!-- fragment --><p>We can see which keysym we got, and get its name:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> keysym_name[64];</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">if</span> (keysym == XKB_KEY_Space)</div>
<div class="line"> <got a space></div>
<div class="line"></div>
<div class="line"><a class="code" href="group__keysyms.html#ga63456bb7e56a2e7a3e02de86b19900ef">xkb_keysym_get_name</a>(keysym, keysym_name, <span class="keyword">sizeof</span>(keysym_name));</div>
</div><!-- fragment --><p>libxkbcommon also supports an extension to the classic XKB, whereby a single event can result in multiple keysyms. Here's how to use it:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <a class="code" href="xkbcommon_8h.html#a79e604a22703391bdfe212cfc10ea007">xkb_keysym_t</a> *keysyms;</div>
<div class="line"><span class="keywordtype">int</span> num_keysyms;</div>
<div class="line"></div>
<div class="line">num_keysyms = <a class="code" href="group__state.html#ga47311e7268935dd2fe3e6ef057a82cb0">xkb_state_key_get_syms</a>(state, keycode, &keysyms);</div>
</div><!-- fragment --><p>We can also get a UTF-8 string representation for this key:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> *buffer;</div>
<div class="line"><span class="keywordtype">int</span> size;</div>
<div class="line"></div>
<div class="line"><span class="comment">// First find the needed size; return value is the same as snprintf(3).</span></div>
<div class="line">size = <a class="code" href="group__state.html#ga0774b424063b45c88ec0354c77f9a247">xkb_state_key_get_utf8</a>(state, keycode, NULL, 0) + 1;</div>
<div class="line"><span class="keywordflow">if</span> (size <= 1) <nothing to <span class="keywordflow">do</span>></div>
<div class="line">buffer = <allocate size bytes></div>
<div class="line"></div>
<div class="line"><a class="code" href="group__state.html#ga0774b424063b45c88ec0354c77f9a247">xkb_state_key_get_utf8</a>(state, keycode, buffer, size);</div>
</div><!-- fragment --><p>Of course, we also need to keep the <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a> up-to-date with the keyboard device, if we want to get the correct keysyms in the future.</p>
<p>If we are an evdev client, we must let the library know whether a key is pressed or released at any given time:</p>
<div class="fragment"><div class="line"><span class="keyword">enum</span> <a class="code" href="group__state.html#ga04e8eac0666cc64dee6f0d5a7a773a03">xkb_state_component</a> changed;</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">if</span> (<key press>)</div>
<div class="line"> changed = <a class="code" href="group__state.html#gac554aa20743a621692c1a744a05e06ce">xkb_state_update_key</a>(state, keycode, <a class="code" href="group__state.html#gga631f03db07f30774659ab3f787b152e7a10b02b45f1fceae1b43bc69162f84678">XKB_KEY_DOWN</a>);</div>
<div class="line"><span class="keywordflow">else</span> <span class="keywordflow">if</span> (<key release>)</div>
<div class="line"> changed = <a class="code" href="group__state.html#gac554aa20743a621692c1a744a05e06ce">xkb_state_update_key</a>(state, keycode, <a class="code" href="group__state.html#gga631f03db07f30774659ab3f787b152e7aa685cb474cd090014d1049f74c3e3ec5">XKB_KEY_UP</a>);</div>
</div><!-- fragment --><p>The <code>changed</code> return value tells us exactly which parts of the state have changed.</p>
<p>If is is a key-repeat event, we can ask the keymap what to do with it:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<key repeat> && !<a class="code" href="group__components.html#ga9d7f998efeca98b3afc7c257bbac90a8">xkb_keymap_key_repeats</a>(keymap, keycode))</div>
<div class="line"> <discard <span class="keyword">event</span>></div>
</div><!-- fragment --><p>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):</p>
<div class="fragment"><div class="line">changed = <a class="code" href="group__state.html#ga566677517a286527e05efc5680adbe6b">xkb_state_update_mask</a>(state,</div>
<div class="line"> event->depressed_mods,</div>
<div class="line"> event->latched_mods,</div>
<div class="line"> event->locked_mods,</div>
<div class="line"> event->depressed_layout,</div>
<div class="line"> event->latched_layout,</div>
<div class="line"> event->locked_layout);</div>
</div><!-- fragment --><p>Now that we have an always-up-to-date <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a>, we can examine it. For example, we can check whether the Control modifier is active, or whether the Num Lock LED is active:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__state.html#gaaa5d800b0ae71ef78e412dc841d2e011">xkb_state_mod_name_is_active</a>(state, XKB_MOD_NAME_CTRL,</div>
<div class="line"> <a class="code" href="group__state.html#gga04e8eac0666cc64dee6f0d5a7a773a03a2357b9f2490e89ab2d549695ea49de4f">XKB_STATE_MODS_EFFECTIVE</a>) > 0)</div>
<div class="line"> <The Control modifier is active></div>
<div class="line"></div>
<div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__state.html#gaebde139a6b3f964f137bfeadc4793166">xkb_state_led_name_is_active</a>(state, XKB_LED_NAME_NUM) > 0)</div>
<div class="line"> <The Num Lock LED is active></div>
</div><!-- fragment --><p>And that's it! When we're finished, we should free the objects we've created:</p>
<div class="fragment"><div class="line"><a class="code" href="group__state.html#gacf5a9ee65857c4bdb7fbb5fbaa2dc115">xkb_state_unref</a>(state);</div>
<div class="line"><a class="code" href="group__keymap.html#gafb6b3d3fce63eb6dde6c1de0850fcf41">xkb_keymap_unref</a>(keymap);</div>
<div class="line"><a class="code" href="group__context.html#ga2c02737136dbc738b3c0db0a3a85e23a">xkb_context_unref</a>(ctx);</div>
</div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Mon Jul 20 2015 08:16:22 for libxkbcommon by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.9.1
</small></address>
</body>
</html>
|