<!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.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libxkbcommon: X11 support</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 id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libxkbcommon
 <span id="projectnumber">0.8.2</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#define-members">Macros</a> |
<a href="#enum-members">Enumerations</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">X11 support</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga719a51dea993976d5c2bcb2ba426a725"><td class="memItemLeft" align="right" valign="top"><a id="ga719a51dea993976d5c2bcb2ba426a725"></a>
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#ga719a51dea993976d5c2bcb2ba426a725">XKB_X11_MIN_MAJOR_XKB_VERSION</a>   1</td></tr>
<tr class="separator:ga719a51dea993976d5c2bcb2ba426a725"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gad053d1ecebb59150ffa81ae3029a839b"><td class="memItemLeft" align="right" valign="top"><a id="gad053d1ecebb59150ffa81ae3029a839b"></a>
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#gad053d1ecebb59150ffa81ae3029a839b">XKB_X11_MIN_MINOR_XKB_VERSION</a>   0</td></tr>
<tr class="separator:gad053d1ecebb59150ffa81ae3029a839b"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:ga4034b296086a8012f427b408dabe0d06"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#ga4034b296086a8012f427b408dabe0d06">xkb_x11_setup_xkb_extension_flags</a> { <a class="el" href="group__x11.html#gga4034b296086a8012f427b408dabe0d06ab5db780e817e951b21470ce58410c500">XKB_X11_SETUP_XKB_EXTENSION_NO_FLAGS</a> = 0
}</td></tr>
<tr class="separator:ga4034b296086a8012f427b408dabe0d06"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga0183a3fdd7d36ef75da3e0f5249f2e6f"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#ga0183a3fdd7d36ef75da3e0f5249f2e6f">xkb_x11_setup_xkb_extension</a> (xcb_connection_t *connection, uint16_t major_xkb_version, uint16_t minor_xkb_version, enum <a class="el" href="group__x11.html#ga4034b296086a8012f427b408dabe0d06">xkb_x11_setup_xkb_extension_flags</a> flags, uint16_t *major_xkb_version_out, uint16_t *minor_xkb_version_out, uint8_t *base_event_out, uint8_t *base_error_out)</td></tr>
<tr class="separator:ga0183a3fdd7d36ef75da3e0f5249f2e6f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga8b01ff183ac596884b008e1c65f1afea"><td class="memItemLeft" align="right" valign="top">int32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#ga8b01ff183ac596884b008e1c65f1afea">xkb_x11_get_core_keyboard_device_id</a> (xcb_connection_t *connection)</td></tr>
<tr class="separator:ga8b01ff183ac596884b008e1c65f1afea"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga9ccc80dcb7488167c8466cb833286559"><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structxkb__keymap.html">xkb_keymap</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#ga9ccc80dcb7488167c8466cb833286559">xkb_keymap::xkb_x11_keymap_new_from_device</a> (struct <a class="el" href="structxkb__context.html">xkb_context</a> *context, xcb_connection_t *connection, int32_t device_id, enum <a class="el" href="group__keymap.html#gad418fa5861e00b37c362075a380299b2">xkb_keymap_compile_flags</a> flags)</td></tr>
<tr class="separator:ga9ccc80dcb7488167c8466cb833286559"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaf710c637c60d9a47a9cce37b89d2afe2"><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structxkb__state.html">xkb_state</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__x11.html#gaf710c637c60d9a47a9cce37b89d2afe2">xkb_state::xkb_x11_state_new_from_device</a> (struct <a class="el" href="structxkb__keymap.html">xkb_keymap</a> *keymap, xcb_connection_t *connection, int32_t device_id)</td></tr>
<tr class="separator:gaf710c637c60d9a47a9cce37b89d2afe2"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Additional X11 support for xkbcommon. </p>
<dl class="section since"><dt>Since</dt><dd>0.4.0 </dd></dl>
<h3><a id="x11-overview"></a>Overview</h3><div class="textblock"><p></p>
<p>The xkbcommon-x11 module provides a means for creating an <a class="el" href="structxkb__keymap.html" title="Opaque compiled keymap object. ">xkb_keymap</a> corresponding to the currently active keymap on the X server. To do so, it queries the XKB X11 extension using the xcb-xkb library. It can be used as a replacement for Xlib's keyboard handling.</p>
<p>Following is an example workflow using xkbcommon-x11. A complete example may be found in the test/interactive-x11.c file in the xkbcommon source repository. On startup:</p>
<ol type="1">
<li>Connect to the X server using xcb_connect().</li>
<li>Setup the XKB X11 extension. You can do this either by using the xcb_xkb_use_extension() request directly, or by using the <a class="el" href="group__x11.html#ga0183a3fdd7d36ef75da3e0f5249f2e6f" title="Setup the XKB X11 extension for this X client. ">xkb_x11_setup_xkb_extension()</a> helper function.</li>
</ol>
<p>The XKB extension supports using separate keymaps and states for different keyboard devices. The devices are identified by an integer device ID and are managed by another X11 extension, XInput. The original X11 protocol only had one keyboard device, called the "core
keyboard", which is still supported as a "virtual device".</p>
<ol type="1">
<li>We will use the core keyboard as an example. To get its device ID, use either the xcb_xkb_get_device_info() request directly, or the <a class="el" href="group__x11.html#ga8b01ff183ac596884b008e1c65f1afea" title="Get the keyboard device ID of the core X11 keyboard. ">xkb_x11_get_core_keyboard_device_id()</a> helper function.</li>
<li>Create an initial <a class="el" href="structxkb__keymap.html" title="Opaque compiled keymap object. ">xkb_keymap</a> for this device, using the <a class="el" href="group__x11.html#ga9ccc80dcb7488167c8466cb833286559" title="Create a keymap from an X11 keyboard device. ">xkb_x11_keymap_new_from_device()</a> function.</li>
<li>Create an initial <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a> for this device, using the <a class="el" href="group__x11.html#gaf710c637c60d9a47a9cce37b89d2afe2" title="Create a new keyboard state object from an X11 keyboard device. ">xkb_x11_state_new_from_device()</a> function.</li>
</ol>
<dl class="section note"><dt>Note</dt><dd>At this point, you may consider setting various XKB controls and XKB per-client flags. For example, enabling detectable autorepeat: <br />
<a href="https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Detectable_Autorepeat">https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Detectable_Autorepeat</a></dd></dl>
<p>Next, you need to react to state changes (e.g. a modifier was pressed, the layout was changed) and to keymap changes (e.g. a tool like xkbcomp, setxkbmap or xmodmap was used):</p>
<ol type="1">
<li>Select to listen to at least the following XKB events: NewKeyboardNotify, MapNotify, StateNotify; using the xcb_xkb_select_events_aux() request.</li>
<li>When NewKeyboardNotify or MapNotify are received, recreate the <a class="el" href="structxkb__keymap.html" title="Opaque compiled keymap object. ">xkb_keymap</a> and <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a> as described above.</li>
<li>When StateNotify is received, update the <a class="el" href="structxkb__state.html" title="Opaque keyboard state object. ">xkb_state</a> accordingly using the <a class="el" href="group__state.html#ga566677517a286527e05efc5680adbe6b" title="Update a keyboard state from a set of explicit masks. ">xkb_state_update_mask()</a> function.</li>
</ol>
<dl class="section note"><dt>Note</dt><dd>It is also possible to use the KeyPress/KeyRelease <code>state</code> field to find the effective modifier and layout state, instead of using XkbStateNotify: <br />
<a href="https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Computing_A_State_Field_from_an_XKB_State">https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Computing_A_State_Field_from_an_XKB_State</a> <br />
However, XkbStateNotify is more accurate.</dd>
<dd>
There is no need to call <a class="el" href="group__state.html#gac554aa20743a621692c1a744a05e06ce" title="Update the keyboard state to reflect a given key being pressed or released. ">xkb_state_update_key()</a>; the state is already synchronized.</dd></dl>
<p>Finally, when a key event is received, you can use ordinary xkbcommon functions, like <a class="el" href="group__state.html#gae56031a8c1d48e7802da32f5f39f5738" title="Get the single keysym obtained from pressing a particular key in a given keyboard state...">xkb_state_key_get_one_sym()</a> and <a class="el" href="group__state.html#ga0774b424063b45c88ec0354c77f9a247" title="Get the Unicode/UTF-8 string obtained from pressing a particular key in a given keyboard state...">xkb_state_key_get_utf8()</a>, as you normally would.</p>
<p></p>
</div><h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="ga4034b296086a8012f427b408dabe0d06"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4034b296086a8012f427b408dabe0d06">◆ </a></span>xkb_x11_setup_xkb_extension_flags</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="group__x11.html#ga4034b296086a8012f427b408dabe0d06">xkb_x11_setup_xkb_extension_flags</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Flags for the <a class="el" href="group__x11.html#ga0183a3fdd7d36ef75da3e0f5249f2e6f" title="Setup the XKB X11 extension for this X client. ">xkb_x11_setup_xkb_extension()</a> function. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga4034b296086a8012f427b408dabe0d06ab5db780e817e951b21470ce58410c500"></a>XKB_X11_SETUP_XKB_EXTENSION_NO_FLAGS </td><td class="fielddoc"><p>Do not apply any flags. </p>
</td></tr>
</table>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga0183a3fdd7d36ef75da3e0f5249f2e6f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga0183a3fdd7d36ef75da3e0f5249f2e6f">◆ </a></span>xkb_x11_setup_xkb_extension()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int xkb_x11_setup_xkb_extension </td>
<td>(</td>
<td class="paramtype">xcb_connection_t * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t </td>
<td class="paramname"><em>major_xkb_version</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t </td>
<td class="paramname"><em>minor_xkb_version</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">enum <a class="el" href="group__x11.html#ga4034b296086a8012f427b408dabe0d06">xkb_x11_setup_xkb_extension_flags</a> </td>
<td class="paramname"><em>flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t * </td>
<td class="paramname"><em>major_xkb_version_out</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t * </td>
<td class="paramname"><em>minor_xkb_version_out</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t * </td>
<td class="paramname"><em>base_event_out</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t * </td>
<td class="paramname"><em>base_error_out</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Setup the XKB X11 extension for this X client. </p>
<p>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.</p>
<p>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.</p>
<p>You may call this function several times; it is idempotent.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir"></td><td class="paramname">connection</td><td>An XCB connection to the X server. </td></tr>
<tr><td class="paramdir"></td><td class="paramname">major_xkb_version</td><td>See <code>minor_xkb_version</code>. </td></tr>
<tr><td class="paramdir"></td><td class="paramname">minor_xkb_version</td><td>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. </td></tr>
<tr><td class="paramdir"></td><td class="paramname">flags</td><td>Optional flags, or 0. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">major_xkb_version_out</td><td>See <code>minor_xkb_version_out</code>. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">minor_xkb_version_out</td><td>Backfilled with the compatible XKB extension version numbers picked by the server. Can be NULL. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">base_event_out</td><td>Backfilled with the XKB base (also known as first) event code, needed to distinguish XKB events. Can be NULL. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">base_error_out</td><td>Backfilled with the XKB base (also known as first) error code, needed to distinguish XKB errors. Can be NULL.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>1 on success, or 0 on failure. </dd></dl>
</div>
</div>
<a id="ga8b01ff183ac596884b008e1c65f1afea"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga8b01ff183ac596884b008e1c65f1afea">◆ </a></span>xkb_x11_get_core_keyboard_device_id()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t xkb_x11_get_core_keyboard_device_id </td>
<td>(</td>
<td class="paramtype">xcb_connection_t * </td>
<td class="paramname"><em>connection</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the keyboard device ID of the core X11 keyboard. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>An XCB connection to the X server.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A device ID which may be used with other xkb_x11_* functions, or -1 on failure. </dd></dl>
</div>
</div>
<a id="ga9ccc80dcb7488167c8466cb833286559"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga9ccc80dcb7488167c8466cb833286559">◆ </a></span>xkb_x11_keymap_new_from_device()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">struct <a class="el" href="structxkb__keymap.html">xkb_keymap</a> * xkb_x11_keymap_new_from_device </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structxkb__context.html">xkb_context</a> * </td>
<td class="paramname"><em>context</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">xcb_connection_t * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"><em>device_id</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">enum <a class="el" href="group__keymap.html#gad418fa5861e00b37c362075a380299b2">xkb_keymap_compile_flags</a> </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Create a keymap from an X11 keyboard device. </p>
<p>This function queries the X server with various requests, fetches the details of the active keymap on a keyboard device, and creates an <a class="el" href="structxkb__keymap.html" title="Opaque compiled keymap object. ">xkb_keymap</a> from these details.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>The context in which to create the keymap. </td></tr>
<tr><td class="paramname">connection</td><td>An XCB connection to the X server. </td></tr>
<tr><td class="paramname">device_id</td><td>An XInput device ID (in the range 0-127) with input class KEY. Passing values outside of this range is an error (the XKB protocol predates the XInput2 protocol, which first allowed IDs > 127). </td></tr>
<tr><td class="paramname">flags</td><td>Optional flags for the keymap, or 0.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A keymap retrieved from the X server, or NULL on failure. </dd></dl>
</div>
</div>
<a id="gaf710c637c60d9a47a9cce37b89d2afe2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf710c637c60d9a47a9cce37b89d2afe2">◆ </a></span>xkb_x11_state_new_from_device()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">struct <a class="el" href="structxkb__state.html">xkb_state</a> * xkb_x11_state_new_from_device </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structxkb__keymap.html">xkb_keymap</a> * </td>
<td class="paramname"><em>keymap</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">xcb_connection_t * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"><em>device_id</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Create a new keyboard state object from an X11 keyboard device. </p>
<p>This function is the same as <a class="el" href="group__state.html#ga281f0dc1cab624ab11e7c4d318d9d4ac" title="Create a new keyboard state object. ">xkb_state_new()</a>, only pre-initialized with the state of the device at the time this function is called.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">keymap</td><td>The keymap for which to create the state. </td></tr>
<tr><td class="paramname">connection</td><td>An XCB connection to the X server. </td></tr>
<tr><td class="paramname">device_id</td><td>An XInput 1 device ID (in the range 0-255) with input class KEY. Passing values outside of this range is an error.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A new keyboard state object, or NULL on failure. </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
38dab587768953aca88376a81d96f344
>
files
>
36
