BossBey File Manager

Editing: inputlib.html

<?xml version="1.0" encoding="UTF-8"?>
<!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/html; charset=UTF-8" /><title>X Input Device Extension Library</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><style xmlns="" type="text/css">/*
 * Copyright (c) 2011 Gaetan Nadon
 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

/*
 * Shared stylesheet for X.Org documentation translated to HTML format
 * http://www.sagehill.net/docbookxsl/UsingCSS.html
 * http://www.w3schools.com/css/default.asp
 * https://addons.mozilla.org/en-US/firefox/addon/web-developer/developers
 * https://addons.mozilla.org/en-US/firefox/addon/font-finder/
 */

/*
 * The sans-serif fonts are considered more legible on a computer screen
 * http://dry.sailingissues.com/linux-equivalents-verdana-arial.html
 *
 */
body {
  font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
  /* In support of using "em" font size unit, the w3c recommended method */
  font-size: 100%;
}

/*
 * Selection: all elements requiring mono spaced fonts.
 *
 * The family names attempt to match the proportionally spaced font
 * family names such that the same font name is used for both.
 * We'd like to use Bitstream, for example, in both proportionally and
 * mono spaced font text.
 */
.command,
.errorcode,
.errorname,
.errortype,
.filename,
.funcsynopsis,
.function,
.parameter,
.programlisting,
.property,
.screen,
.structname,
.symbol,
.synopsis,
.type
{
  font-family:  "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
}

/*
 * Books have a title page, a preface, some chapters and appendices,
 * a glossary, an index and a bibliography, in that order.
 *
 * An Article has no preface and no chapters. It has sections, appendices,
 * a glossary, an index and a bibliography.
 */

/*
 * Selection: book main title and subtitle
 */
div.book>div.titlepage h1.title,
div.book>div.titlepage h2.subtitle {
  text-align: center;
}

/*
 * Selection: article main title and subtitle
 */
div.article>div.titlepage h2.title,
div.article>div.titlepage h3.subtitle,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title {
  text-align: center;
}

/*
 * Selection: various types of authors and collaborators, individuals or corporate
 *
 * These authors are not always contained inside an authorgroup.
 * They can be contained inside a lot of different parent types where they might
 * not be centered.
 * Reducing the margin at the bottom makes a visual separation between authors
 * We specify here the ones on the title page, others may be added based on merit.
 */
div.titlepage .authorgroup,
div.titlepage .author,
div.titlepage .collab,
div.titlepage .corpauthor,
div.titlepage .corpcredit,
div.titlepage .editor,
div.titlepage .othercredit {
  text-align: center;
  margin-bottom: 0.25em;
}

/*
 * Selection: the affiliation of various types of authors and collaborators,
 * individuals or corporate.
 */
div.titlepage .affiliation {
  text-align: center;
}

/*
 * Selection: product release information (X Version 11, Release 7)
 *
 * The releaseinfo element can be contained inside a lot of different parent
 * types where it might not be centered.
 * We specify here the one on the title page, others may be added based on merit.
 */
div.titlepage p.releaseinfo {
  font-weight: bold;
  text-align: center;
}

/*
 * Selection: publishing date
 */
div.titlepage .pubdate {
  text-align: center;
}

/*
 * The legal notices are displayed in smaller sized fonts
 * Justification is only supported in IE and therefore not requested.
 *
 */
.legalnotice {
  font-size: small;
  font-style: italic;
}

/*
 * For documentation having multiple licenses, the copyright and legalnotice
 * elements sequence cannot instantiated multiple times.
 * The copyright notice and license text are therefore coded inside a legalnotice
 * element. The role attribute on the paragraph is used to allow styling of the
 * copyright notice text which should not be italicized.
 */
p.multiLicensing {
  font-style: normal;
  font-size: medium;
}

/*
 * Selection: book or article main ToC title
 * A paragraph is generated for the title rather than a level 2 heading.
 * We do not want to select chapters sub table of contents, only the main one
 */
div.book>div.toc>p,
div.article>div.toc>p {
  font-size: 1.5em;
  text-align: center;
}

/*
 * Selection: major sections of a book or an article
 *
 * Unlike books, articles do not have a titlepage element for appendix.
 * Using the selector "div.titlepage h2.title" would be too general.
 */
div.book>div.preface>div.titlepage h2.title,
div.book>div.chapter>div.titlepage h2.title,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title,
div.book>div.appendix>div.titlepage h2.title,
div.article>div.appendix h2.title,
div.glossary>div.titlepage h2.title,
div.index>div.titlepage h2.title,
div.bibliography>div.titlepage h2.title {
   /* Add a border top over the major parts, just like printed books */
   /* The Gray color is already used for the ruler over the main ToC. */
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: Gray;
  /* Put some space between the border and the title */
  padding-top: 0.2em;
  text-align: center;
}

/*
 * A Screen is a verbatim environment for displaying text that the user might
 * see on a computer terminal. It is often used to display the results of a command.
 *
 * http://www.css3.info/preview/rounded-border/
 */
.screen {
  background: #e0ffff;
  border-width: 1px;
  border-style: solid;
  border-color: #B0C4DE;
  border-radius: 1.0em;
  /* Browser's vendor properties prior to CSS 3 */
  -moz-border-radius: 1.0em;
  -webkit-border-radius: 1.0em;
  -khtml-border-radius: 1.0em;
  margin-left: 1.0em;
  margin-right: 1.0em;
  padding: 0.5em;
}

/*
 * Emphasis program listings with a light shade of gray similar to what
 * DocBook XSL guide does: http://www.sagehill.net/docbookxsl/ProgramListings.html
 * Found many C API docs on the web using like shades of gray.
 */
.programlisting {
  background: #F4F4F4;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  padding: 0.5em;
}

/*
 * Emphasis functions synopsis using a darker shade of gray.
 * Add a border such that it stands out more.
 * Set the padding so the text does not touch the border.
 */
.funcsynopsis, .synopsis {
  background: #e6e6fa;
  border-width: 1px;
  border-style: solid;
  border-color: Gray;
  clear: both;
  margin: 0.5em;
  padding: 0.25em;
}

/*
 * Selection: paragraphs inside synopsis
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in synopsis
 */
.funcsynopsis p,
.synopsis p {
  margin: 0;
  padding: 0;
}

/*
 * Selection: variable lists, informal tables and tables
 *
 * Note the parameter name "variablelist.as.table" in xorg-xhtml.xsl
 * A table with rows and columns is constructed inside div.variablelist
 *
 * Set the left margin so it is indented to the right
 * Display informal tables with single line borders
 */
table {
  margin-left: 0.5em;
  border-collapse: collapse;
}

/*
 * Selection: paragraphs inside tables
 *
 * Removes the default browser margin, let the container set the padding.
 * Paragraphs are not always used in tables
 */
td p {
  margin: 0;
  padding: 0;
}

/*
 * Add some space between the left and right column.
 * The vertical alignment helps the reader associate a term
 * with a multi-line definition.
 */
td, th {
  padding-left: 1.0em;
  padding-right: 1.0em;
  vertical-align: top;
}

.warning {
  border: 1px solid red;
  background: #FFFF66;
  padding-left: 0.5em;
}
</style></head><body><div class="book"><div class="titlepage"><div><div><h1 class="title"><a id="inputlib"></a>X Input Device Extension Library</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Mark</span> <span class="surname">Patrick</span></h3><div class="affiliation"><span class="orgname">Ardent Computer<br /></span></div></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">George</span> <span class="surname">Sachs</span></h3><div class="affiliation"><span class="orgname">Hewlett-Packard<br /></span></div></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.7</p></div><div><p class="releaseinfo">Version 1.0</p></div><div><p class="copyright">Copyright © 1989, 1990, 1991 Hewlett-Packard Company, Ardent Computer</p></div><div><div class="legalnotice"><a id="Legal_Notice"></a><p>
Permission to use, copy, modify, and distribute this documentation for any purpose and without
fee is hereby granted, provided that the above copyright notice and this permission notice appear
in all copies. Ardent and Hewlett-Packard make no representations about the suitability for any
purpose of the information in this document. It is provided "as is" without express or implied
warranty.
</p></div></div><div><div class="legalnotice"><a id="Multi_Licensing"></a><p class="multiLicensing">
Copyright © 1989, 1990, 1991, 1992 X Consortium
</p><p>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the ‘‘Software’’), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
</p><p>
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
</p><p>
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN 
NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
THE SOFTWARE.
</p><p>
Except as contained in this notice, the name of the X Consortium shall not 
be used in advertising or otherwise to promote the sale, use or other dealings 
in this Software without prior written authorization from the X Consortium.
</p><p>X Window System is a trademark of The Open Group.</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="#Input_Extension">1. Input Extension</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Overview">Overview</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Design_Approach">Design Approach</a></span></dt><dt><span class="sect2"><a href="#Core_Input_Devices">Core Input Devices</a></span></dt><dt><span class="sect2"><a href="#Extension_Input_Devices">Extension Input Devices</a></span></dt><dt><span class="sect2"><a href="#Using_Extension_Input_Devices">Using Extension Input Devices</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Library_Extension_Requests">Library Extension Requests</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Window_Manager_Functions">Window Manager Functions</a></span></dt><dt><span class="sect2"><a href="#Events">Events</a></span></dt><dt><span class="sect2"><a href="#Event_Handling_Functions">Event Handling Functions</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#Input_Extension_Protocol_Encoding">A. Input Extension Protocol Encoding</a></span></dt></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Input_Extension"></a>Chapter 1. Input Extension</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Overview">Overview</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Design_Approach">Design Approach</a></span></dt><dt><span class="sect2"><a href="#Core_Input_Devices">Core Input Devices</a></span></dt><dt><span class="sect2"><a href="#Extension_Input_Devices">Extension Input Devices</a></span></dt><dt><span class="sect2"><a href="#Using_Extension_Input_Devices">Using Extension Input Devices</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Library_Extension_Requests">Library Extension Requests</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Window_Manager_Functions">Window Manager Functions</a></span></dt><dt><span class="sect2"><a href="#Events">Events</a></span></dt><dt><span class="sect2"><a href="#Event_Handling_Functions">Event Handling Functions</a></span></dt></dl></dd></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Overview"></a>Overview</h2></div></div></div><p>

This document describes an extension to
the X11 server.  The purpose of this extension is to support the use
of additional input devices beyond the pointer and keyboard devices
defined by the core X protocol.  This first section gives an overview
of the input extension.  The following sections correspond to 
chapters 9, 10, and 11, ``Window and Session Manager Functions'',
``Events'', and ``Event Handling Functions'' of the
``Xlib - C Language Interface'' manual
and describe how to use the input device extension.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Design_Approach"></a>Design Approach</h3></div></div></div><p>

The design approach of the extension is to define functions
and events analogous to the core functions and events.
This allows extension input devices and events to be individually
distinguishable from each other and from the core input devices and events.
These functions and events make use of a device identifier and support the
reporting of <span class="emphasis"><em>n</em></span>-dimensional motion data as well as other data that
is not currently reportable via the core input events.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Core_Input_Devices"></a>Core Input Devices</h3></div></div></div><p>

The X server core protocol supports two input devices:  a pointer and a
keyboard.  The pointer device has two major functions. 
First, it may be used to generate motion information
that client programs can detect. Second, it may also be used to indicate the
current location and focus of the X keyboard.  To accomplish this, the server 
echoes a cursor at the current position of the X pointer.  Unless the X
keyboard has been explicitly focused, this cursor also shows the current
location and focus of the X keyboard.
</p><p>

The X keyboard is used to generate input that client programs can detect.
</p><p>

The X keyboard and X pointer are referred to in this document as 
the <span class="emphasis"><em>core devices</em></span>, and the input
events they generate 
<code class="function">( KeyPress ,</code>
<code class="function">KeyRelease ,</code>
<code class="function">ButtonPress ,</code>
<code class="function">ButtonRelease ,</code>
and
<code class="function">MotionNotify )</code>
are known as the <span class="emphasis"><em>core input events</em></span>.  All other
input devices are referred to as <span class="emphasis"><em>extension input devices</em></span>, and the 
input events they generate are referred to as <span class="emphasis"><em>extension input events</em></span>.

This input extension does not change the behavior or functionality of the
core input devices, core events, or core protocol requests, with the
exception of the core grab requests.  These requests may affect the
synchronization of events from extension devices.  See the explanation
in the section titled ``Event Synchronization and Core Grabs.''

</p><p>

Selection of the physical devices to be initially used by the server as the 
core devices is left implementation dependent.  Functions are defined that
allow client programs to change which physical devices are used as the
core devices.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Extension_Input_Devices"></a>Extension Input Devices</h3></div></div></div><p>

The input extension controls access to input devices other than the X keyboard
and X pointer.  It allows client programs to select input from these devices 
independently
from each other and independently from the core devices.  Input events from
these devices are of extension types 
<code class="function">( DeviceKeyPress ,</code>
<code class="function">DeviceKeyRelease ,</code>
<code class="function">DeviceButtonPress ,</code>
<code class="function">DeviceButtonRelease ,</code>
<code class="function">DeviceMotionNotify ,</code>
and so on) and contain
a device identifier so that events of the same type coming from different
input devices can be distinguished.
</p><p>

Extension input events are not limited in size by the size of the server
32-byte wire events.  Extension input events
may be constructed by the server sending as many
wire-sized events as necessary to return the information required for
that event.
The library event reformatting routines
are responsible for combining these into one or more client XEvents.
</p><p>

Any input device that generates key, button, or motion data may be used as
an extension input device.
Extension input devices may have zero or more keys, zero or more buttons,
and may report zero or more axes of motion.  Motion may be reported 
as relative movements from a previous position or as an absolute
position.  All valuators reporting motion information for a given
extension input device must report the same kind of motion information
(absolute or relative).
</p><p>

This extension is designed to accommodate new types of input devices that
may be added in the future.  The protocol requests that refer to
specific characteristics of input devices organize that information
by <span class="emphasis"><em>input device classes</em></span>.  Server implementors may add new
classes of input devices without changing the protocol requests.
</p><p>

All extension input
devices are treated like the core X keyboard in determining their location
and focus.  The server does not track the location of these devices on an
individual basis and, therefore,
does not echo a cursor to indicate their current location.
Instead, their location is determined by the location of the core X pointer.
Like the core X keyboard, some may be explicitly focused. If they are
not explicitly focused,  their focus
is determined by the location of the core X pointer.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Input_Device_Classes"></a>Input Device Classes</h4></div></div></div><p>

Some of the input extension requests divide input devices into classes
based on their functionality.  This is intended to allow new classes of input
devices to be defined at a later time without changing the semantics of 
these functions.  The following input device classes are currently
defined:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">KEY</span></p></td><td><p>
The device reports key events.
      </p></td></tr><tr><td><p><span class="term">BUTTON</span></p></td><td><p>
The device reports button events.
      </p></td></tr><tr><td><p><span class="term">VALUATOR</span></p></td><td><p>
The device reports valuator data in motion events.
      </p></td></tr><tr><td><p><span class="term">PROXIMITY</span></p></td><td><p>
The device reports proximity events.
      </p></td></tr><tr><td><p><span class="term">FOCUS</span></p></td><td><p>
The device can be focused.
      </p></td></tr><tr><td><p><span class="term">FEEDBACK</span></p></td><td><p>
The device supports feedbacks.
    </p></td></tr></tbody></table></div><p>
</p><p>

Additional classes may be added in the future.
Functions that support multiple input classes, such as the 
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
function that lists all available input devices,
organize the data they return by input class.  Client programs that
use these functions should not access data unless it matches a 
class defined at the time those clients were compiled.  In this way,
new classes can be added without forcing existing clients that use
these functions to be recompiled.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Using_Extension_Input_Devices"></a>Using Extension Input Devices</h3></div></div></div><p>

A client that wishes to access an input device does so through the library
functions defined in the following sections.  A typical sequence of requests
that a client would make is as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
- lists all of the available input devices.  From the 
information returned by this request, determine whether the desired input
device is attached to the server.  For a description of the 
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
request, see the section entitled ``Listing Available Devices.''
    </p></li><li class="listitem"><p>
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
- requests that the server open the device for access by this client.
This request returns an 
<code class="function">XDevice</code>
structure that is used
by most other input extension requests to identify the specified device.
For a description of the 
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
request, see the section entitled ``Enabling and Disabling Extension Devices.''
    </p></li><li class="listitem"><p>
Determine the event types and event classes needed to select the desired
input extension events, and identify them when they are received.
This is done via macros whose name corresponds to the desired event, for
example,
<code class="function">DeviceKeyPress .</code>
For a description of these macros,
see the section entitled ``Selecting Extension Device Events.''
    </p></li><li class="listitem"><p>
<a class="xref" href="#XSelectExtensionEvent"><code class="function"> XSelectExtensionEvent</code></a>
- selects the desired events from the server.
For a description of the 
<code class="function">XSelextExtensionEvent</code>
request, see the section entitled ``Selecting Extension Device Events.''
    </p></li><li class="listitem"><p>
<span class="olink"><code class="function">XNextEvent</code></span>
- receives the next available event.  This is the core
<span class="olink"><code class="function">XNextEvent</code></span>
function provided by the standard X library.
    </p></li></ul></div><p>

Other requests are defined to grab and focus extension devices, to
change their key, button, or modifier mappings, to control the
propagation of input extension events, to get motion history from an
extension device, and to send input extension events to another client.
These functions are described in the following sections.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Library_Extension_Requests"></a>Library Extension Requests</h2></div></div></div><p>

Extension input devices are accessed by client programs through the 
use of new protocol requests.
The following requests are provided as extensions to Xlib.  Constants
and structures referenced by these functions may be found in the 
files <code class="function">&lt;X11/extensions/XI.h&gt;</code> and <code class="function">&lt;X11/extensions/XInput.h&gt;</code>,
which are attached to this document as 
Appendix A.
</p><p>

The library will return <code class="function">NoSuchExtension</code> if an extension request
is made to a server that does not support the input extension.
</p><p>

Input extension requests cannot be used to access the X keyboard and
X pointer devices.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Window_Manager_Functions"></a>Window Manager Functions</h3></div></div></div><p>

This section discusses the following X Input Extension Window Manager topics:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Changing the core devices
    </p></li><li class="listitem"><p>
Event synchronization and core grabs
    </p></li><li class="listitem"><p>
Extension active grabs
    </p></li><li class="listitem"><p>
Passively grabbing a key
    </p></li><li class="listitem"><p>
Passively grabbing a button
    </p></li><li class="listitem"><p>
Thawing a device
    </p></li><li class="listitem"><p>
Controlling device focus
    </p></li><li class="listitem"><p>
Controlling device feedback
    </p></li><li class="listitem"><p>
Ringing a bell on an input device
    </p></li><li class="listitem"><p>
Controlling device encoding
    </p></li><li class="listitem"><p>
Controlling button mapping
    </p></li><li class="listitem"><p>
Obtaining the state of a device
    </p></li></ul></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Changing_the_Core_Devices"></a>Changing the Core Devices</h4></div></div></div><p>

These functions are provided to change which physical device is used
as the X pointer or X keyboard.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Using these functions may change the characteristics of the core devices.
The new pointer device may have a different number of buttons from the 
old one, or the new keyboard device may have a different number of
keys or report a different range of keycodes.  Client programs may be
running that depend on those characteristics.  For example, a client
program could allocate an array based on the number of buttons on the
pointer device and then use the button numbers received in button events
as indices into that array.  Changing the core devices could cause
such client programs to behave improperly or to terminate abnormally
if they ignore the 
<code class="function">ChangeDeviceNotify</code>
event generated by these requests.
</p></div><p>

These functions change the X keyboard or X pointer device and generate an
<code class="function">XChangeDeviceNotify</code>
event and a
<code class="function">MappingNotify</code>
event.  
The specified device becomes the
new X keyboard or X pointer device.  The location of the core device
does not change as a result of this request.
</p><p>

These requests fail and return 
<code class="function">AlreadyGrabbed</code>
if either the specified
device or the core device it would replace are grabbed by some other client.
They fail and return 
<code class="function">GrabFrozen</code>
if either device is frozen by the active grab of another client.
</p><p>

These requests fail with a
<code class="function">BadDevice</code>
error if the specified device is invalid, has not previously been opened via
<code class="function">XOpenDevice ,</code>
or is
not supported as a core device by the server implementation.
</p><p>

Once the device has successfully replaced one of the core devices, it
is treated as a core device until it is in turn replaced by another
<code class="function">ChangeDevice</code>
request or until the server terminates.  The termination
of the client that changed the device will not cause it to change back.
Attempts to use the
<a class="xref" href="#XCloseDevice"><code class="function"> XCloseDevice</code></a>
request to close the new core device will fail with a
<code class="function">BadDevice</code>
error.

</p><p>

To change which physical device is used as the X keyboard, use the 
<a class="xref" href="#XChangeKeyboardDevice"><code class="function"> XChangeKeyboardDevice</code></a>
function.
The specified device must support input class 
<code class="function">Keys</code>
(as reported in the
<code class="function">ListInputDevices</code>
request) or the request will fail with a 
<code class="function">BadMatch</code>
error.
</p><p>

</p><div class="funcsynopsis"><a id="XChangeKeyboardDevice"></a><p><code class="funcdef">int <strong class="fsfunc"> XChangeKeyboardDevice</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var><code>)</code>;</p></div><p>

If no error occurs, 
<a class="xref" href="#XChangeKeyboardDevice"><code class="function"> XChangeKeyboardDevice</code></a>
returns 
<code class="function">Success .</code>
A 
<code class="function">ChangeDeviceNotify</code>
event with the request field set to 
<code class="function">NewKeyboard</code>
is sent to all clients selecting that event.
A 
<code class="function">MappingNotify</code>
event with the request field set to
<code class="function">MappingKeyboard</code>
is sent to all clients.
The requested device becomes the X keyboard, and the old keyboard becomes 
available as an extension input device.
The focus state of the new keyboard is the same as
the focus state of the old X keyboard.
</p><p>

<a class="xref" href="#XChangeKeyboardDevice"><code class="function"> XChangeKeyboardDevice</code></a>
can generate
<code class="function">AlreadyGrabbed ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
and 
<code class="function">GrabFrozen</code>
errors.

</p><p>

To change which physical device is used as the X pointer,
use the
<a class="xref" href="#XChangePointerDevice"><code class="function"> XChangePointerDevice</code></a>
function.
The specified device must support input class 
<code class="function">Valuators</code>
(as reported in the
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
request) and report at least two axes of motion,
or the request will fail with a 
<code class="function">BadMatch</code>
error.
If the specified device reports more than two axes, the two specified in
the xaxis and yaxis arguments will be used.  Data from other
valuators on the device will be ignored.
</p><p>

If the specified device reports absolute positional information, and the 
server implementation does not allow such a device to be used as the 
X pointer, the request will fail with a 
<code class="function">BadDevice</code>
error.

</p><div class="funcsynopsis"><a id="XChangePointerDevice"></a><p><code class="funcdef">int <strong class="fsfunc"> XChangePointerDevice</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> xaxis</var>, int<var class="pdparam"> yaxis</var><code>)</code>;</p></div><p>

If no error occurs, 
<a class="xref" href="#XChangePointerDevice"><code class="function"> XChangePointerDevice</code></a>
returns 
<code class="function">Success .</code>
A 
<code class="function">ChangeDeviceNotify</code>
event with the request field set to 
<code class="function">NewPointer</code>
is sent to all clients selecting that event.
A
<code class="function">MappingNotify</code>
event with the request field set to
<code class="function">MappingPointer</code>
is sent to all clients.
The requested device becomes the X pointer, and the old pointer becomes 
available as an extension input device.
</p><p>

<a class="xref" href="#XChangePointerDevice"><code class="function"> XChangePointerDevice</code></a>
can generate
<code class="function">AlreadyGrabbed ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
and 
<code class="function">GrabFrozen</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Event_Synchronization_and_Core_Grabs"></a>Event Synchronization and Core Grabs</h4></div></div></div><p>

Implementation of the input extension requires an extension of the
meaning of event synchronization for the core grab requests.  This is
necessary in order to allow window managers to freeze all input devices
with a single request.
</p><p>

The core grab requests require a pointer_mode and keyboard_mode
argument.  The meaning of these modes is changed by the input extension.
For the
<span class="olink"><code class="function">XGrabPointer</code></span>
and 
<span class="olink"><code class="function">XGrabButton</code></span>
requests, pointer_mode controls synchronization of the pointer device, 
and keyboard_mode controls the synchronization of all other input devices.  
For the 
<span class="olink"><code class="function">XGrabKeyboard</code></span>
and
<span class="olink"><code class="function">XGrabKey</code></span>
requests, pointer_mode controls the synchronization
of all input devices, except the X keyboard, while keyboard_mode controls
the synchronization of the keyboard.  When using one of the core grab
requests, the synchronization of extension devices
is controlled by the mode specified for the device not being grabbed.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Extension_Active_Grabs"></a>Extension Active Grabs</h4></div></div></div><p>

Active grabs of
extension devices are supported via the 
<a class="xref" href="#XGrabDevice"><code class="function"> XGrabDevice</code></a>
function in the same way that core devices are grabbed using the core 
<span class="olink"><code class="function">XGrabKeyboard</code></span>
function, except that an extension input device
is passed as a function parameter.  
The 
<a class="xref" href="#XUngrabDevice"><code class="function"> XUngrabDevice</code></a>
function allows a previous active grab for an extension device to be released.
</p><p>

Passive grabs of buttons and keys on extension devices are supported
via the 
<a class="xref" href="#XGrabDeviceButton"><code class="function"> XGrabDeviceButton</code></a>
and 
<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
functions.
These passive grabs are released via the
<a class="xref" href="#XUngrabDeviceKey"><code class="function"> XUngrabDeviceKey</code></a>
and
<a class="xref" href="#XUngrabDeviceButton"><code class="function"> XUngrabDeviceButton</code></a>
functions.

</p><p>

To grab an extension device, use the
<a class="xref" href="#XGrabDevice"><code class="function"> XGrabDevice</code></a>
function.
The device must have previously been opened using the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function.

</p><div class="funcsynopsis"><a id="XGrabDevice"></a><p><code class="funcdef">int <strong class="fsfunc"> XGrabDevice</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, int<var class="pdparam"> event_count</var>, XEventClass<var class="pdparam"> *event_list</var>, int<var class="pdparam"> this_device_mode</var>, int<var class="pdparam"> other_device_mode</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGrabDevice"><code class="function"> XGrabDevice</code></a>
actively grabs an extension input device and generates 
<code class="function">DeviceFocusIn</code>
and 
<code class="function">DeviceFocusOut</code>
events.
Further input events from this device are reported only to the grabbing client.
This function overrides any previous active grab by this client for this device.
</p><p>

The event_list parameter is a pointer to a list of event classes.  This list
indicates which events the client wishes to receive while the grab is active.
If owner_events is 
<code class="function">False ,</code>
input events from this device are reported with respect to 
grab_window and are reported only if specified in event_list.
If owner_events is
<code class="function">True ,</code>
then if a generated event would normally be reported to this client,
it is reported normally.
Otherwise, the event is reported with respect to the grab_window and is only
reported if specified in event_list.
</p><p>

The this_device_mode argument controls the further processing 
of events from this device, and the other_device_mode argument controls
the further processing of input events from all other devices.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the this_device_mode argument is 
<code class="function">GrabModeAsync ,</code>
device event processing continues
normally; if the device is currently frozen by this client, then
processing of device events is resumed.
If the this_device_mode  argument is
<code class="function">GrabModeSync ,</code>
the state of the grabbed device
(as seen by client applications) appears to freeze,
and no further device events are generated by the server until the
grabbing client issues a releasing 
<a class="xref" href="#XAllowDeviceEvents"><code class="function"> XAllowDeviceEvents</code></a>
call or until the device grab is released.
Actual device input events are not lost while the device is frozen; they are
simply queued for later processing.
    </p></li><li class="listitem"><p>
If the other_device_mode is 
<code class="function">GrabModeAsync ,</code>
event processing from other input devices is unaffected
by activation of the grab.  
If other_device_mode is 
<code class="function">GrabModeSync ,</code>
the state of all devices except the grabbed device
(as seen by client applications) appears to freeze, and no further
events are generated by the server until the grabbing client issues a
releasing 
<span class="olink"><code class="function">XAllowEvents</code></span>
or 
<a class="xref" href="#XAllowDeviceEvents"><code class="function"> XAllowDeviceEvents</code></a>
call or until the device grab is released.
Actual events are not lost
while the other devices are frozen; they are simply queued for later
processing.
    </p></li></ul></div><p>

<a class="xref" href="#XGrabDevice"><code class="function"> XGrabDevice</code></a>
fails on the following conditions:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the device is actively grabbed by some other client, it returns
<code class="function">AlreadyGrabbed .</code>
    </p></li><li class="listitem"><p>
If grab_window is not viewable, it returns
<code class="function">GrabNotViewable .</code>
    </p></li><li class="listitem"><p>
If the specified time is earlier
than the last-grab-time for the specified device
or later than the current X server time, it returns
<code class="function">GrabInvalidTime .</code>
Otherwise,
the last-grab-time for the specified device is set
to the specified time and 
<code class="function">CurrentTime</code>
is replaced by the current X server time.
    </p></li><li class="listitem"><p>
If the device is frozen by an active grab of another client, it returns
<code class="function">GrabFrozen .</code>
    </p></li></ul></div><p>

If a grabbed device is closed by a client while an active grab by that 
client is in effect, that active grab will be released. 
Any passive grabs established by that client will be released.
If the device is frozen only by an active grab
of the requesting client, it is thawed.
</p><p>

<a class="xref" href="#XGrabDevice"><code class="function"> XGrabDevice</code></a>
can generate
<code class="function">BadClass ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadValue ,</code>
and
<code class="function">BadWindow</code>
errors.

</p><p>

To release a grab of an extension device, use the
<a class="xref" href="#XUngrabDevice"><code class="function"> XUngrabDevice</code></a>
function.
</p><p>

</p><div class="funcsynopsis"><a id="XUngrabDevice"></a><p><code class="funcdef">int <strong class="fsfunc"> XUngrabDevice</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><p>

<a class="xref" href="#XUngrabDevice"><code class="function"> XUngrabDevice</code></a>
allows a client to release an extension input device and any
queued events if this client has it grabbed from either
<a class="xref" href="#XGrabDevice"><code class="function"> XGrabDevice</code></a>
or
<code class="function">XGrabDeviceKey .</code>
If any other devices are frozen by the grab,
<a class="xref" href="#XUngrabDevice"><code class="function"> XUngrabDevice</code></a>
thaws them. 
This function does not release the device and any
queued events if the specified time is earlier than the last-device-grab
time or is later than the current X server time.  It also generates 
<code class="function">DeviceFocusIn</code>
and 
<code class="function">DeviceFocusOut</code>
events.  The X server automatically performs an
<a class="xref" href="#XUngrabDevice"><code class="function"> XUngrabDevice</code></a>
if the event window for an active device grab becomes not viewable
or if the client terminates without releasing the grab.
</p><p>

<a class="xref" href="#XUngrabDevice"><code class="function"> XUngrabDevice</code></a>
can generate
<code class="function">BadDevice</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Passively_Grabbing_a_Key"></a>Passively Grabbing a Key</h4></div></div></div><p>

To passively grab a single key on an extension device, use
<code class="function">XGrabDeviceKey .</code>
That device must have previously been opened using the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function, or the request will fail with a
<code class="function">BadDevice</code>
error.  
If the specified device does not support input class
<code class="function">Keys ,</code>
the request will fail with a
<code class="function">BadMatch</code>
error.

</p><div class="funcsynopsis"><a id="XGrabDeviceKey"></a><p><code class="funcdef">int <strong class="fsfunc"> XGrabDeviceKey</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> keycode</var>, unsignedint<var class="pdparam"> modifiers</var>, XDevice<var class="pdparam"> *modifier_device</var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, int<var class="pdparam"> event_count</var>, XEventClass<var class="pdparam"> *event_list</var>, int<var class="pdparam"> this_device_mode</var>, int<var class="pdparam"> other_device_mode</var><code>)</code>;</p></div><p>

</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>device</em></span>
    </span></p></td><td><p>
Specifies the desired device.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>keycode</em></span>
    </span></p></td><td><p>
Specifies the keycode of the key that is to be grabbed.  You can pass
either the keycode or 
<code class="function">AnyKey .</code>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifiers</em></span>
    </span></p></td><td><p>
Specifies the set of keymasks.  This mask is the bitwise inclusive OR
of these keymask bits:  
<code class="function">ShiftMask ,</code>
<code class="function">LockMask ,</code>
<code class="function">ControlMask ,</code>
<code class="function">Mod1Mask ,</code>
<code class="function">Mod2Mask ,</code>
<code class="function">Mod3Mask ,</code>
<code class="function">Mod4Mask ,</code>
and
<code class="function">Mod5Mask .</code>
      </p></td></tr><tr><td><p><span class="term">
      
    </span></p></td><td><p>
You can also pass 
<code class="function">AnyModifier ,</code>
which is equivalent to issuing the grab key request 
for all possible modifier combinations (including the combination
of no modifiers).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifier_device</em></span>
    </span></p></td><td><p>
Specifies the device whose modifiers are to be used.  If NULL is 
specified, the core X keyboard is used as the modifier_device.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the ID of a window associated with the device specified above.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner_events</em></span>
    </span></p></td><td><p>
Specifies a boolean value of either
<code class="function">True</code>
or
<code class="function">False .</code>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_count</em></span>
    </span></p></td><td><p>
Specifies the number of elements in the event_list array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_list</em></span>
    </span></p></td><td><p>
Specifies a pointer to a list of event classes that indicate which events
the client wishes to receive.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>this_device_mode</em></span>
    </span></p></td><td><p>
Controls further processing of events from this device.
You can pass one of these constants:
<code class="function">GrabModeSync</code>
or
<code class="function">GrabModeAsync .</code>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>other_device_mode</em></span>
    </span></p></td><td><p>
Controls further processing of events from all other devices.
You can pass one of these constants: 
<code class="function">GrabModeSync</code>
or
<code class="function">GrabModeAsync .</code>
    </p></td></tr></tbody></table></div><p>
</p><p>

<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
is analogous to the core 
<span class="olink"><code class="function">XGrabKey</code></span>
function.  It creates an
explicit passive grab for a key on an extension device.
The 
<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
function establishes a passive grab on a device.
Consequently, in the future, 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
IF the device is not grabbed and the specified key, 
which itself can be a modifier key, is logically pressed
when the specified modifier keys logically are down on the specified
modifier device (and no other keys are down),
    </p></li><li class="listitem"><p>
AND no other modifier keys logically are down,
    </p></li><li class="listitem"><p>
AND EITHER the grab window is an ancestor of (or is) the focus window
or the grab window is a descendent of the focus window and contains the pointer,
    </p></li><li class="listitem"><p>
AND a passive grab on the same device and key combination does not exist on any
ancestor of the grab window,
    </p></li><li class="listitem"><p>
THEN the device is actively grabbed, as for
<code class="function">XGrabDevice ,</code>
the last-device-grab time is set to the time at which the key was pressed
(as transmitted in the 
<code class="function">DeviceKeyPress</code>
event), and the 
<code class="function">DeviceKeyPress</code>
event is reported.
    </p></li></ul></div><p>

The interpretation of the remaining arguments is as for
<code class="function">XGrabDevice .</code>
The active grab is terminated automatically when the logical state of the
device has the specified key released
(independent of the logical state of the modifier keys).
</p><p>

Note that the logical state of a device (as seen by means of the X protocol)
may lag the physical state if device event processing is frozen.
</p><p>

A modifier of 
<code class="function">AnyModifier</code>
is equivalent to issuing the request for all
possible modifier combinations (including the combination of no modifiers).  
It is not required that all modifiers specified have
currently assigned keycodes.
A key of 
<code class="function">AnyKey</code>
is equivalent to issuing
the request for all possible keycodes.  Otherwise, the key must be in
the range specified by min_keycode and max_keycode in the 
information returned by the
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
function.
If it is not within that range, 
<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
generates a
<code class="function">BadValue</code>
error.
</p><p>

<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
generates a
<code class="function">BadAccess</code>
error if some other client has issued a 
<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
with the same device and key combination on the same window.
When using
<code class="function">AnyModifier</code>
or
<code class="function">AnyKey ,</code>
the request fails completely and the X server generates a
<code class="function">BadAccess</code>
error, and no grabs are established if there is a conflicting grab
for any combination.
</p><p>

<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
returns
<code class="function">Success</code>
upon successful completion of the request.
</p><p>

<a class="xref" href="#XGrabDeviceKey"><code class="function"> XGrabDeviceKey</code></a>
can generate
<code class="function">BadAccess ,</code>
<code class="function">BadClass ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
<code class="function">BadValue ,</code>
and
<code class="function">BadWindow</code>
errors.

</p><p>

To release a passive grab of a single key on an extension device, use
<code class="function">XUngrabDeviceKey .</code>

</p><div class="funcsynopsis"><a id="XUngrabDeviceKey"></a><p><code class="funcdef">int <strong class="fsfunc"> XUngrabDeviceKey</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> keycode</var>, unsignedint<var class="pdparam"> modifiers</var>, XDevice<var class="pdparam"> *modifier_device</var>, Window<var class="pdparam"> ungrab_window</var><code>)</code>;</p></div><p>

<a class="xref" href="#XUngrabDeviceKey"><code class="function"> XUngrabDeviceKey</code></a>
is analogous to the core
<span class="olink"><code class="function">XUngrabKey</code></span>
function.  It releases an explicit passive grab for a key 
on an extension input device.
</p><p>

<a class="xref" href="#XUngrabDeviceKey"><code class="function"> XUngrabDeviceKey</code></a>
can generate
<code class="function">BadAlloc ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
<code class="function">BadValue ,</code>
and 
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Passively_Grabbing_a_Button"></a>Passively Grabbing a Button</h4></div></div></div><p>

To establish a passive grab for a single button on an extension device, use
<code class="function">XGrabDeviceButton .</code>
The specified device must have previously been opened using the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function, or the request will fail with a 
<code class="function">BadDevice</code>
error.  If the specified device does not support input class
<code class="function">Buttons ,</code>
the request will fail with a 
<code class="function">BadMatch</code>
error.

</p><div class="funcsynopsis"><a id="XGrabDeviceButton"></a><p><code class="funcdef">int <strong class="fsfunc"> XGrabDeviceButton</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, unsignedint<var class="pdparam"> button</var>, unsignedint<var class="pdparam"> modifiers</var>, XDevice*modifier_device<var class="pdparam"> </var>, Window<var class="pdparam"> grab_window</var>, Bool<var class="pdparam"> owner_events</var>, int<var class="pdparam"> event_count</var>, XEventClass<var class="pdparam"> *event_list</var>, int<var class="pdparam"> this_device_mode</var>, int<var class="pdparam"> other_device_mode</var><code>)</code>;</p></div><p>

</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      <span class="emphasis"><em>display</em></span>
    </span></p></td><td><p>
Specifies the connection to the X server.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>device</em></span>
    </span></p></td><td><p>
Specifies the desired device.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>button</em></span>
    </span></p></td><td><p>
Specifies the code of the button that is to be grabbed.  You can pass
either the button or
<code class="function">AnyButton .</code>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifiers</em></span>
    </span></p></td><td><p>
Specifies the set of keymasks.  This mask is the bitwise inclusive OR
of these keymask bits:
<code class="function">ShiftMask ,</code>
<code class="function">LockMask ,</code>
<code class="function">ControlMask , </code>
<code class="function">Mod1Mask ,</code>
<code class="function">Mod2Mask ,</code>
<code class="function">Mod3Mask ,</code>
<code class="function">Mod4Mask ,</code>
and
<code class="function">Mod5Mask .</code>
      </p></td></tr><tr><td><p><span class="term">
      
    </span></p></td><td><p>
You can also pass 
<code class="function">AnyModifier ,</code>
which is equivalent to issuing the grab request 
for all possible modifier combinations (including the combination
of no modifiers).
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>modifier_device</em></span>
    </span></p></td><td><p>
Specifies the device whose modifiers are to be used.  If NULL is 
specified, the core X keyboard is used as the modifier_device.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>grab_window</em></span>
    </span></p></td><td><p>
Specifies the ID of a window associated with the device specified above.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>owner_events</em></span>
    </span></p></td><td><p>
Specifies a boolean value of either
<code class="function">True</code>
or
<code class="function">False .</code>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_count</em></span>
    </span></p></td><td><p>
Specifies the number of elements in the event_list array.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>event_list</em></span>
    </span></p></td><td><p>
Specifies a list of event classes that indicates which device events are to be 
reported to the client.
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>this_device_mode</em></span>
    </span></p></td><td><p>
Controls further processing of events from this device.  You can pass one
of these constants:
<code class="function">GrabModeSync</code>
or
<code class="function">GrabModeAsync .</code>
      </p></td></tr><tr><td><p><span class="term">
      <span class="emphasis"><em>other_device_mode</em></span>
    </span></p></td><td><p>
Controls further processing of events from all other devices.  You can pass one
of these constants:
<code class="function">GrabModeSync</code>
or
<code class="function">GrabModeAsync .</code>
    </p></td></tr></tbody></table></div><p>
</p><p>

<a class="xref" href="#XGrabDeviceButton"><code class="function"> XGrabDeviceButton</code></a>
is analogous to the core
<span class="olink"><code class="function">XGrabButton</code></span>
function.  
It creates an explicit passive grab for a button on an extension input device.
Because the server does not track extension devices,
no cursor is specified with this request.
For the same reason, there is no confine_to parameter.
The device must have previously been opened using the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function.
</p><p>

The
<a class="xref" href="#XGrabDeviceButton"><code class="function"> XGrabDeviceButton</code></a>
function establishes a passive grab on a device.
Consequently, in the future, 
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
IF the device is not grabbed and the specified button is logically pressed
when the specified modifier keys logically are down 
(and no other buttons or modifier keys are down),
    </p></li><li class="listitem"><p>
AND EITHER the grab window is an ancestor of (or is) the focus window
OR the grab window is a descendent of the focus window and contains the pointer,
    </p></li><li class="listitem"><p>
AND a passive grab on the same device and button/key combination does not 
exist on any ancestor of the grab window,
    </p></li><li class="listitem"><p>
THEN the device is actively grabbed, as for
<code class="function">XGrabDevice ,</code>
the last-grab time is set to the time at which the button was pressed
(as transmitted in the
<code class="function">DeviceButtonPress</code>
event), and the 
<code class="function">DeviceButtonPress</code>
event is reported.
    </p></li></ul></div><p>

The interpretation of the remaining arguments is as for 
<code class="function">XGrabDevice .</code>
The active grab is terminated automatically when logical state of the
device has all buttons released (independent of the logical state of 
the modifier keys).
</p><p>

Note that the logical state of a device (as seen by means of the X protocol)
may lag the physical state if device event processing is frozen.
</p><p>

<a class="xref" href="#XGrabDeviceButton"><code class="function"> XGrabDeviceButton</code></a>
generates a
<code class="function">BadAccess</code>
error if some other client has issued a 
<a class="xref" href="#XGrabDeviceButton"><code class="function"> XGrabDeviceButton</code></a>
with the same device and button combination on the same window.  
When using
<code class="function">AnyModifier</code>
or
<code class="function">AnyButton ,</code>
the request fails completely and the X server generates a
<code class="function">BadAccess</code>
error and no grabs are
established if there is a conflicting grab for any combination.
</p><p>

<a class="xref" href="#XGrabDeviceButton"><code class="function"> XGrabDeviceButton</code></a>
can generate
<code class="function">BadAccess , </code>
<code class="function">BadClass ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
<code class="function">BadValue ,</code>
and
<code class="function">BadWindow</code>
errors.

</p><p>

To release a passive grab of a button on an extension device, use 
<code class="function">XUngrabDeviceButton .</code>

</p><div class="funcsynopsis"><a id="XUngrabDeviceButton"></a><p><code class="funcdef">int <strong class="fsfunc"> XUngrabDeviceButton</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, unsignedint<var class="pdparam"> button</var>, unsignedint<var class="pdparam"> modifiers</var>, XDevice<var class="pdparam"> *modifier_device</var>, Window<var class="pdparam"> ungrab_window</var><code>)</code>;</p></div><p>

<a class="xref" href="#XUngrabDeviceButton"><code class="function"> XUngrabDeviceButton</code></a>
is analogous to the core
<span class="olink"><code class="function">XUngrabButton</code></span>
function.  It releases an explicit passive grab for a button
on an extension device.
That device must have previously been opened using the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function, or a
<code class="function">BadDevice</code>
error will result.
</p><p>

A modifier of
<code class="function">AnyModifier</code>
is equivalent to issuing the request for all
possible modifier combinations (including the combination of no
modifiers).  
</p><p>

<a class="xref" href="#XUngrabDeviceButton"><code class="function"> XUngrabDeviceButton</code></a>
can generate
<code class="function">BadAlloc , </code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
<code class="function">BadValue ,</code>
and
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Thawing_a_Device"></a>Thawing a Device</h4></div></div></div><p>

To allow further events to be processed when a device has been frozen, use
<code class="function">XAllowDeviceEvents .</code>

</p><div class="funcsynopsis"><a id="XAllowDeviceEvents"></a><p><code class="funcdef">int <strong class="fsfunc"> XAllowDeviceEvents</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> event_mode</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><p>

<a class="xref" href="#XAllowDeviceEvents"><code class="function"> XAllowDeviceEvents</code></a>
releases some queued events if the client has caused a device to freeze.
It has no effect if the specified time is earlier than the last-grab 
time of the most recent active grab for the client and device, 
or if the specified time is later than the current X server time.
The following describes the processing that occurs depending on what constant
you pass to the event_mode argument:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="function">AsyncThisDevice</code>
    </p></li><li class="listitem"><p>
If the specified device is frozen by the client, event processing for that 
continues as usual.  If the device is frozen multiple times by the client on 
behalf of multiple separate grabs, 
<code class="function">AsyncThisDevice</code>
thaws for all.
<code class="function">AsyncThisDevice</code>
has no effect if the specified device is not frozen by the 
client, but the device need not be grabbed by the client.
    </p></li><li class="listitem"><p>
<code class="function">SyncThisDevice</code>
    </p></li><li class="listitem"><p>
If the specified device is frozen and actively grabbed by the client,
event processing for that device continues normally until the next 
key or button event is reported to the client.
At this time, 
the specified device again appears to freeze.
However, if the reported event causes the grab to be released,
the specified device does not freeze.
<code class="function">SyncThisDevice</code>
has no effect if the specified device is not frozen by the client
or is not grabbed by the client.
    </p></li><li class="listitem"><p>
<code class="function">ReplayThisDevice</code>
    </p></li><li class="listitem"><p>
If the specified device is actively grabbed by the client
and is frozen as the result of an event having been sent to the client
(either from the activation of a 
<code class="function">GrabDeviceButton</code>
or from a previous
<code class="function">AllowDeviceEvents</code>
with mode 
<code class="function">SyncThisDevice , </code>
but not from a
<code class="function">Grab ),</code>
the grab is released and that event is completely reprocessed.
This time, however, the request ignores any passive grabs at or above 
(toward the root) the grab-window of the grab just released.
The request has no effect if the specified device is not grabbed by the client
or if it is not frozen as the result of an event.
    </p></li><li class="listitem"><p>
<code class="function">AsyncOtherDevices</code>
    </p></li><li class="listitem"><p>
If the remaining devices are frozen by the client,
event processing for them continues as usual.
If the other devices are frozen multiple times  by the client on behalf of 
multiple separate grabs,
<code class="function">AsyncOtherDevices</code>
``thaws'' for all.
<code class="function">AsyncOtherDevices</code>
has no effect if the devices are not frozen by the client,
but those devices need not be grabbed by the client.
    </p></li><li class="listitem"><p>
<code class="function">SyncAll</code>
    </p></li><li class="listitem"><p>
If all devices are frozen by the client,
event processing (for all devices) continues normally until the next
button or key event is reported
to the client for a grabbed device,
at which time the devices again appear to
freeze.  However, if the reported event causes the grab to be released,
then the devices do not freeze (but if any device is still
grabbed, then a subsequent event for it will still cause all devices
to freeze).  
<code class="function">SyncAll</code>
has no effect unless all devices are frozen by the client.
If any device is frozen twice
by the client on behalf of two separate grabs, 
<code class="function">SyncAll</code>
"thaws" for both (but a subsequent freeze for 
<code class="function">SyncAll</code>
will freeze each device only once).
    </p></li><li class="listitem"><p>
<code class="function">AsyncAll</code>
    </p></li><li class="listitem"><p>
If all devices are frozen by the
client, event processing (for all devices) continues normally.
If any device is frozen multiple times by the client on behalf of multiple
separate grabs, 
<code class="function">AsyncAll</code>
``thaws ''for all.
If any device is frozen twice by the client on behalf of two separate grabs,
<code class="function">AsyncAll</code>
``thaws'' for both.
<code class="function">AsyncAll</code>
has no effect unless all devices are frozen by the client.
    </p></li></ul></div><p>

<code class="function">AsyncThisDevice ,</code>
<code class="function">SyncThisDevice ,</code>
and
<code class="function">ReplayThisDevice </code>
have no effect on the processing of events from the remaining devices.
<code class="function">AsyncOtherDevices</code>
has no effect on the processing of events from the specified device.
When the event_mode is
<code class="function">SyncAll</code>
or
<code class="function">AsyncAll ,</code>
the device parameter is ignored.
</p><p>

It is possible for several grabs of different devices (by the same 
or different clients) to be active simultaneously.
If a device is frozen on behalf of any grab,
no event processing is performed for the device.
It is possible for a single device to be frozen because of several grabs.
In this case,
the freeze must be released on behalf of each grab before events can 
again be processed.
</p><p>

<a class="xref" href="#XAllowDeviceEvents"><code class="function"> XAllowDeviceEvents</code></a>
can generate
<code class="function">BadDevice</code>
and 
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Controlling_Device_Focus"></a>Controlling Device Focus</h4></div></div></div><p>

The current focus window for an extension input device can be 
determined using the
<a class="xref" href="#XGetDeviceFocus"><code class="function"> XGetDeviceFocus</code></a>
function.
Extension devices are focused using the
<a class="xref" href="#XSetDeviceFocus"><code class="function"> XSetDeviceFocus</code></a>
function in the same way that the keyboard is focused using the core
<span class="olink"><code class="function">XSetInputFocus</code></span>
function, except that a device ID is passed as
a function parameter.  One additional focus state,
<code class="function">FollowKeyboard ,</code>
is provided for extension devices.
</p><p>

To get the current focus state, revert state,
and focus time of an extension device, use
<code class="function">XGetDeviceFocus .</code>

</p><div class="funcsynopsis"><a id="XGetDeviceFocus"></a><p><code class="funcdef">int <strong class="fsfunc"> XGetDeviceFocus</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, Window<var class="pdparam"> *focus_return</var>, int<var class="pdparam"> *revert_to_return</var>, Time<var class="pdparam"> *focus_time_return</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceFocus"><code class="function"> XGetDeviceFocus</code></a>
returns the focus state, the revert-to state,
and the last-focus-time for an extension input device.
</p><p>

<a class="xref" href="#XGetDeviceFocus"><code class="function"> XGetDeviceFocus</code></a>
can generate
<code class="function">BadDevice</code>
and
<code class="function">BadMatch</code>
errors.

</p><p>

To set the focus of an extension device, use
<code class="function">XSetDeviceFocus .</code>

</p><div class="funcsynopsis"><a id="XSetDeviceFocus"></a><p><code class="funcdef">int <strong class="fsfunc"> XSetDeviceFocus</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, Window<var class="pdparam"> focus</var>, int<var class="pdparam"> revert_to</var>, Time<var class="pdparam"> time</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSetDeviceFocus"><code class="function"> XSetDeviceFocus</code></a>
changes the focus for an extension input device and the 
last-focus-change-time.  It has no effect if the specified 
time is earlier than the last-focus-change-time or is later than the
current X server time.  Otherwise, the last-focus-change-time is set to the
specified time.
This function causes the X server to generate
<code class="function">DeviceFocusIn</code>
and 
<code class="function">DeviceFocusOut</code>
events.
</p><p>

The action taken by the server when this function is requested depends
on the value of the focus argument:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the focus argument is
<code class="function">None ,</code>
all input events from this device will be discarded until a new focus window
is set.  In this case, the revert_to argument is ignored.
    </p></li><li class="listitem"><p>
If the focus argument is a window ID, it becomes the focus
window of the device.  If an input event from the device would normally
be reported to this window or to one of its inferiors, the event is 
reported normally.  Otherwise, the event is reported relative to the focus 
window.
    </p></li><li class="listitem"><p>
If the focus argument is
<code class="function">PointerRoot ,</code>
the focus window is dynamically taken to be the root window 
of whatever screen the pointer is on at each input event.
In this case, the revert_to argument is ignored.
    </p></li><li class="listitem"><p>
If the focus argument is
<code class="function">FollowKeyboard ,   </code>
the focus window is dynamically taken to be the same as the focus
of the X keyboard at each input event.
    </p></li></ul></div><p>

The specified focus window must be viewable at the time
<a class="xref" href="#XSetDeviceFocus"><code class="function"> XSetDeviceFocus</code></a>
is called.  Otherwise, it generates a
<code class="function">BadMatch</code>
error.
If the focus window later becomes not viewable,
the X server evaluates the revert_to argument
to determine the new focus window.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the revert_to argument is
<code class="function">RevertToParent ,</code>
the focus reverts to the parent (or the closest viewable ancestor),
and the new revert_to value is taken to be
<code class="function">RevertToNone .  </code>
    </p></li><li class="listitem"><p>
If the revert_to argument is
<code class="function">RevertToPointerRoot ,</code>
<code class="function">RevertToFollowKeyboard ,</code>
or
<code class="function">RevertToNone ,</code>
the focus reverts to that value.
    </p></li></ul></div><p>

When the focus reverts,
the X server generates
<code class="function">DeviceFocusIn</code>
and
<code class="function">DeviceFocusOut</code>
events, but the last-focus-change time is not affected.
</p><p>

<a class="xref" href="#XSetDeviceFocus"><code class="function"> XSetDeviceFocus</code></a>
can generate
<code class="function">BadDevice ,</code>
<code class="function">BadMatch , </code>
<code class="function">BadValue ,</code>
and
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Controlling_Device_Feedback"></a>Controlling Device Feedback</h4></div></div></div><p>

To determine the current feedback settings of an extension input device, use
<code class="function">XGetFeedbackControl .</code>

</p><div class="funcsynopsis"><a id="XGetFeedbackControl"></a><p><code class="funcdef">XFeedbackState * <strong class="fsfunc"> XGetFeedbackControl</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> *num_feedbacks_return</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetFeedbackControl"><code class="function"> XGetFeedbackControl</code></a>
returns a list of
<code class="function">FeedbackState</code>
structures that describe the feedbacks supported by the specified device.
There is an
<code class="function">XFeedbackState</code>
structure for each class of feedback.  These are of 
variable length, but the first three members are common to all.
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
} XFeedbackState;
</pre><p>
</p><p>

The common members are as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The class member identifies the class of feedback.
It may be compared to constants defined in the file
<code class="function">&lt; X11/extensions/XI.h &gt;.</code>
Currently defined feedback constants include:
<code class="function">KbdFeedbackClass , </code>
<code class="function">PtrFeedbackClass ,</code>
<code class="function">StringFeedbackClass ,</code>
<code class="function">IntegerFeedbackClass , </code>
<code class="function">LedFeedbackClass ,</code>
and
<code class="function">BellFeedbackClass .</code>
    </p></li><li class="listitem"><p>
The length member specifies the length of the
<code class="function">FeedbackState</code>
structure and can be used by clients to traverse the list.
    </p></li><li class="listitem"><p>
The id member uniquely identifies a feedback for a given device and class.
This allows a device to support more than one feedback of the same class.
Other feedbacks of other classes or devices may have the same ID.

</p></li></ul></div><p>

Those feedbacks equivalent to those
supported by the core keyboard are reported in class
<code class="function">KbdFeedback</code>
using the
<code class="function">XKbdFeedbackState</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int click;
     int percent;
     int pitch;
     int duration;
     int led_mask;
     int global_auto_repeat;
     char auto_repeats[32];
} XKbdFeedbackState;
</pre><p>
</p><p>

The additional members of the
<code class="function">XKbdFeedbackState</code>
structure report the current state of the feedback:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The click member specifies the key-click volume and has a value in the range
0 (off) to 100 (loud).
    </p></li><li class="listitem"><p>
The percent member specifies the bell volume and has a value in the range
0 (off) to 100 (loud).
    </p></li><li class="listitem"><p>
The pitch member specifies the bell pitch in Hz. The range of the value is 
implementation-dependent.
    </p></li><li class="listitem"><p>
The duration member specifies the duration in milliseconds of the bell.
    </p></li><li class="listitem"><p>
The led_mask member is a bit mask that describes the current state of up to 
32 LEDs.  A value of 1 in a bit indicates that the corresponding LED is on.
    </p></li><li class="listitem"><p>
The global_auto_repeat member has a value of
<code class="function">AutoRepeatModeOn</code>
or
<code class="function">AutoRepeatModeOff .</code>
    </p></li><li class="listitem"><p>
The auto_repeats member is a bit vector.  Each bit set to 1 indicates
that auto-repeat is enabled for the corresponding key.  The vector is
represented as 32 bytes.  Byte N (from 0) contains the bits for keys
8N to 8N + 7, with the least significant bit in the byte representing
key 8N.

</p></li></ul></div><p>

Those feedbacks equivalent to those
supported by the core pointer are reported in class
<code class="function">PtrFeedback</code>
using the
<code class="function">XPtrFeedbackState</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int accelNum;
     int accelDenom;
     int threshold;
} XPtrFeedbackState;
</pre><p>
</p><p>

The additional members of the
<code class="function">XPtrFeedbackState</code>
structure report the current state of the feedback:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The accelNum member returns the numerator for the acceleration multiplier.
    </p></li><li class="listitem"><p>
The accelDenom member returns the denominator for the acceleration multiplier.
    </p></li><li class="listitem"><p>
The accelDenom member returns the threshold for the acceleration.

</p></li></ul></div><p>

Integer feedbacks are those capable of displaying integer numbers
and reported via the
<code class="function">XIntegerFeedbackState</code>
structure.
The minimum and maximum values that they can display are reported.
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int resolution;
     int minVal;
     int maxVal;
} XIntegerFeedbackState;
</pre><p>
</p><p>

The additional members of the
<code class="function">XIntegerFeedbackState</code>
structure report the capabilities of the feedback:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The resolution member specifies the number of digits that the feedback
can display.
    </p></li><li class="listitem"><p>
The minVal member specifies the minimum value that the feedback can display.
    </p></li><li class="listitem"><p>
The maxVal specifies the maximum value that the feedback can display.

</p></li></ul></div><p>

String feedbacks are those that can display character information
and are reported via the
<code class="function">XStringFeedbackState</code>
structure.
Clients set these feedbacks by passing a list of 
<code class="function">KeySyms</code>
to be displayed.
The 
<a class="xref" href="#XGetFeedbackControl"><code class="function"> XGetFeedbackControl</code></a>
function returns the
set of key symbols that the feedback can display, as well as the 
maximum number of symbols that can be displayed.
The
<code class="function">XStringFeedbackState</code>
structure is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int max_symbols;
     int  num_syms_supported;
     KeySym *syms_supported;
} XStringFeedbackState;
</pre><p>
</p><p>

The additional members of the
<code class="function">XStringFeedbackState</code>
structure report the capabilities of the feedback:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The max_symbols member specifies the maximum number of symbols
that can be displayed.
    </p></li><li class="listitem"><p>
The syms_supported member is a pointer to the list of supported symbols.
    </p></li><li class="listitem"><p>
The num_syms_supported member specifies the length of the list of supported symbols.

</p></li></ul></div><p>

Bell feedbacks are those that can generate a sound
and are reported via the
<code class="function">XBellFeedbackState</code>
structure.
Some implementations may support a bell as part of a
<code class="function">KbdFeedback</code>
feedback.  Class
<code class="function">BellFeedback</code>
is provided for implementations that do not choose to do
so and for devices that support multiple feedbacks that can produce sound.
The meaning of the members is the same as that of the corresponding fields in
the 
<code class="function">XKbdFeedbackState</code>
structure.
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int percent;
     int pitch;
     int duration;
} XBellFeedbackState;
</pre><p>
</p><p>

Led feedbacks are those that can generate a light and are reported via the
<code class="function">XLedFeedbackState</code>
structure.
Up to 32 lights per feedback are supported.  
Each bit in led_mask
corresponds to one supported light, and the corresponding bit in led_values
indicates whether that light is currently on (1) or off (0).
Some implementations may support leds as part of a
<code class="function">KbdFeedback</code>
feedback.
Class 
<code class="function">LedFeedback</code>
is provided for implementations that do not choose to do
so and for devices that support multiple led feedbacks.
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     Mask led_values;
     Mask led_mask;
} XLedFeedbackState;
</pre><p>
</p><p>

<a class="xref" href="#XGetFeedbackControl"><code class="function"> XGetFeedbackControl</code></a>
can generate
<code class="function">BadDevice</code>
and
<code class="function">BadMatch</code>
errors.

</p><p>

To free the information returned by the
<a class="xref" href="#XGetFeedbackControl"><code class="function"> XGetFeedbackControl</code></a>
function, use 
<code class="function">XFreeFeedbackList .</code>

</p><div class="funcsynopsis"><a id="XFreeFeedbackList"></a><p><code class="funcdef">void <strong class="fsfunc"> XFreeFeedbackList</strong>(</code>XFeedbackState<var class="pdparam"> *list</var><code>)</code>;</p></div><p>

<a class="xref" href="#XFreeFeedbackList"><code class="function"> XFreeFeedbackList</code></a>
frees the list of feedback control information.

</p><p>

To change the settings of a feedback on an extension device, use
<code class="function">XChangeFeedbackControl .</code>
This function modifies the current control values of the specified feedback
using information passed in the appropriate
<code class="function">XFeedbackControl</code>
structure for the feedback.
Which values are modified depends on the valuemask passed.

</p><div class="funcsynopsis"><a id="XChangeFeedbackControl"></a><p><code class="funcdef">int <strong class="fsfunc"> XChangeFeedbackControl</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, unsignedlong<var class="pdparam"> valuemask</var>, XFeedbackControl<var class="pdparam"> *value</var><code>)</code>;</p></div><p>

<a class="xref" href="#XChangeFeedbackControl"><code class="function"> XChangeFeedbackControl</code></a>
controls the device characteristics described by the
<code class="function">XFeedbackControl</code>
structure. 
There is an
<code class="function">XFeedbackControl</code>
structure for each class of feedback.  
These are of variable length, but the first 
three members are common to all and are as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
} XFeedbackControl;
</pre><p>
</p><p>

Feedback class 
<code class="function">KbdFeedback</code>
controls feedbacks equivalent to those provided by the core keyboard using the
<code class="function">KbdFeedbackControl</code>
structure, which is defined as follows:.
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int click;
     int percent;
     int pitch;
     int duration;
     int led_mask;
     int led_value;
     int key;
     int auto_repeat_mode;
} XKbdFeedbackControl;
</pre><p>
</p><p>

This class controls the device characteristics described by the
<code class="function">XKbdFeedbackControl</code>
structure.  These include the key_click_percent,
global_auto_repeat, and individual key auto-repeat.  Valid modes
are
<code class="function">AutoRepeatModeOn ,</code>
<code class="function">AutoRepeatModeOff ,</code>
and
<code class="function">AutoRepeatModeDefault .</code>
</p><p>

Valid masks are as follows:

</p><pre class="literallayout">

#define   DvKeyClickPercent           (1&gt;&lt;&lt;0)
#define   DvPercent                   (1&gt;&lt;&lt;0)
#define   DvPitch                     (1&gt;&lt;&lt;0)
#define   DvDuration                  (1&gt;&lt;&lt;0)
#define   DvLed                       (1&gt;&lt;&lt;0)
#define   DvLedMode                   (1&gt;&lt;&lt;0)
#define   DvKey                       (1&gt;&lt;&lt;0)
#define   DvAutoRepeatMode            (1&gt;&lt;&lt;0)
</pre><p>

Feedback class
<code class="function">PtrFeedback</code>
controls feedbacks equivalent to those provided by the core pointer using the
<code class="function">PtrFeedbackControl</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int accelNum;
     int accelDenom;
     int threshold;
} XPtrFeedbackControl;
</pre><p>
</p><p>

Which values are modified depends on the valuemask passed.
</p><p>

Valid masks are as follows:

</p><pre class="literallayout">
#define    DvAccelnum        (1L&lt;&lt;0)
#define    DvAccelDenom      (1L&lt;&lt;1)
#define    DvThreshold       (1L&lt;&lt;2)
</pre><p>

The acceleration, expressed as a fraction, is a multiplier for movement. 
For example,
specifying 3/1 means that the device moves three times as fast as normal.
The fraction may be rounded arbitrarily by the X server.  
Acceleration takes effect only if the device moves more than threshold pixels at
once and applies only to the amount beyond the value in the threshold argument.
Setting a value to -1 restores the default.
The values of the accelNumerator and threshold fields must be nonzero for
the pointer values to be set.
Otherwise, the parameters will be unchanged.
Negative values generate a
<code class="function">BadValue</code>
error, as does a zero value
for the accelDenominator field.
</p><p>

This request fails with a
<code class="function">BadMatch</code>
error if the specified device is not currently reporting relative motion.
If a device that is capable of reporting both relative and absolute motion
has its mode changed from
<code class="function">Relative</code>
to
<code class="function">Absolute</code>
by an
<a class="xref" href="#XSetDeviceMode"><code class="function"> XSetDeviceMode</code></a>
request, valuator control values
will be ignored by the server while the device is in that mode.
</p><p>

Feedback class
<code class="function">IntegerFeedback</code>
controls integer feedbacks displayed on input devices and are
reported via the
<code class="function">IntegerFeedbackControl</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int int_to_display;
} XIntegerFeedbackControl;
</pre><p>
</p><p>

Valid masks are as follows:

</p><pre class="literallayout">

#define   DvInteger           (1L&lt;&lt;0)
</pre><p>

Feedback class
<code class="function">StringFeedback</code>
controls string feedbacks displayed on input devices
and reported via the
<code class="function">StringFeedbackControl</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int num_keysyms;
     KeySym *syms_to_display;
} XStringFeedbackControl;
</pre><p>
</p><p>

Valid masks are as follows:

</p><pre class="literallayout">

#define   DvString           (1L&lt;&lt;0)
</pre><p>

Feedback class
<code class="function">BellFeedback</code>
controls a bell on an input device and is reported via the
<code class="function">BellFeedbackControl</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int percent;
     int pitch;
     int duration;
} XBellFeedbackControl;
</pre><p>
</p><p>

Valid masks are as follows:

</p><pre class="literallayout">

#define   DvPercent                   (1L&lt;&lt;1)
#define   DvPitch                     (1L&lt;&lt;2)
#define   DvDuration                  (1L&lt;&lt;3)
</pre><p>

Feedback class
<code class="function">LedFeedback</code>
controls lights on an input device and are reported via the
<code class="function">LedFeedbackControl</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID class;
     int length;
     XID id;
     int led_mask;
     int led_values;
} XLedFeedbackControl;
</pre><p>
</p><p>

Valid masks are as follows:

</p><pre class="literallayout">

#define   DvLed                       (1L&lt;&lt;4)
#define   DvLedMode                   (1L&lt;&lt;5)
</pre><p>

<a class="xref" href="#XChangeFeedbackControl"><code class="function"> XChangeFeedbackControl</code></a>
can generate
<code class="function">BadDevice ,</code>
<code class="function">BadFeedBack ,</code>
<code class="function">BadMatch ,</code>
and
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Ringing_a_Bell_on_an_Input_Device"></a>Ringing a Bell on an Input Device</h4></div></div></div><p>

To ring a bell on an extension input device, use
<code class="function">XDeviceBell .</code>

</p><div class="funcsynopsis"><a id="XDeviceBell"></a><p><code class="funcdef">int <strong class="fsfunc"> XDeviceBell</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, XIDfeedbackclass,<var class="pdparam"> feedbackid</var>, int<var class="pdparam"> percent</var><code>)</code>;</p></div><p>

<a class="xref" href="#XDeviceBell"><code class="function"> XDeviceBell</code></a>
is analogous to the core 
<span class="olink"><code class="function">XBell</code></span>
function.  It rings the specified bell on the specified input device feedback,
using the specified volume.
The specified volume is relative to the base volume for the feedback.
If the value for the percent argument is not in the range -100 to 100
inclusive, a
<code class="function">BadValue</code>
error results.
The volume at which the bell rings when the percent argument is nonnegative is:
</p><p>

</p><pre class="literallayout">
       base - [(base * percent) / 100] + percent
</pre><p>
</p><p>

The volume at which the bell rings
when the percent argument is negative is:
</p><p>

</p><pre class="literallayout">
       base + [(base * percent) / 100]
</pre><p>
</p><p>

To change the base volume of the bell, use
<code class="function">XChangeFeedbackControl .</code>
</p><p>

<a class="xref" href="#XDeviceBell"><code class="function"> XDeviceBell</code></a>
can generate
<code class="function">BadDevice</code>
and
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Controlling_Device_Encoding"></a>Controlling Device Encoding</h4></div></div></div><p>

To get the key mapping of an extension device that supports input class 
<code class="function">Keys ,</code>
use 
<code class="function">XGetDeviceKeyMapping .</code>

</p><div class="funcsynopsis"><a id="XGetDeviceKeyMapping"></a><p><code class="funcdef">KeySym * <strong class="fsfunc"> XGetDeviceKeyMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, KeyCode<var class="pdparam"> first_keycode_wanted</var>, int<var class="pdparam"> keycode_count</var>, int<var class="pdparam"> *keysyms_per_keycode_return</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceKeyMapping"><code class="function"> XGetDeviceKeyMapping</code></a>
is analogous to the core
<span class="olink"><code class="function">XGetKeyboardMapping</code></span>
function.  
It returns the symbols for the specified number of keycodes for the 
specified extension device.
</p><p>

<a class="xref" href="#XGetDeviceKeyMapping"><code class="function"> XGetDeviceKeyMapping</code></a>
returns the symbols for the 
specified number of keycodes for the 
specified extension device, starting with the specified keycode.
The first_keycode_wanted must be greater than or equal to
min-keycode as returned 
by the
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
request (else a 
<code class="function">BadValue</code>
error results). The following value:
</p><pre class="literallayout">
first_keycode_wanted + keycode_count - 1
</pre><p>
</p><p>

must be less than or equal to max-keycode as returned 
by the 
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
request (else a 
<code class="function">BadValue</code>
error results).
</p><p>

The number of elements in the keysyms list is as follows:
</p><pre class="literallayout">
keycode_count * keysyms_per_keycode_return
</pre><p>
And KEYSYM number N (counting from zero) for keycode K has an index
(counting from zero), in keysyms, of the following:
</p><pre class="literallayout">
(K - first_keycode_wanted) * keysyms_per_keycode_return + N
</pre><p>
</p><p>

The keysyms_per_keycode_return value is chosen arbitrarily by the server
to be large enough to report all requested symbols.
A special KEYSYM value of
<code class="function">NoSymbol</code>
is used to fill in unused elements for individual keycodes.
</p><p>

To free the data returned by this function, use
<span class="olink"><code class="function">XFree</code></span>.
</p><p>

If the specified device has not first been opened by this client via
<code class="function">XOpenDevice ,</code>
this request will fail with a
<code class="function">BadDevice</code>
error.
If that device does not support input class
<code class="function">Keys ,</code>
this request will fail with a 
<code class="function">BadMatch</code>
error.
</p><p>

<a class="xref" href="#XGetDeviceKeyMapping"><code class="function"> XGetDeviceKeyMapping</code></a>
can generate
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
and
<code class="function">BadValue</code>
errors.

</p><p>

To change the keyboard mapping of an extension device that supports input class 
<code class="function">Keys ,</code>
use 
<code class="function">XChangeDeviceKeyMapping .</code>

</p><div class="funcsynopsis"><a id="XChangeDeviceKeyMapping"></a><p><code class="funcdef">int <strong class="fsfunc"> XChangeDeviceKeyMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> first_keycode</var>, int<var class="pdparam"> keysyms_per_keycode</var>, KeySym<var class="pdparam"> *keysyms</var>, int<var class="pdparam"> num_codes</var><code>)</code>;</p></div><p>

<a class="xref" href="#XChangeDeviceKeyMapping"><code class="function"> XChangeDeviceKeyMapping</code></a>
is analogous to the core
<span class="olink"><code class="function">XChangeKeyboardMapping</code></span>
function.  
It defines the symbols for the specified number of keycodes for the 
specified extension keyboard device.
</p><p>

If the specified device has not first been opened by this client via
<code class="function">XOpenDevice ,</code>
this request will fail with a
<code class="function">BadDevice</code>
error.
If the specified device does not support input class
<code class="function">Keys ,</code>
this request will fail with a
<code class="function">BadMatch</code>
error.
</p><p>

The number of elements in the keysyms list must be a multiple of
keysyms_per_keycode.  Otherwise,
<a class="xref" href="#XChangeDeviceKeyMapping"><code class="function"> XChangeDeviceKeyMapping</code></a>
generates a
<code class="function">BadLength</code>
error.
The specified first_keycode must be greater than or equal to
the min_keycode value returned by the
<code class="function">ListInputDevices</code>
request, or this request will fail with a
<code class="function">BadValue</code>
error.  In addition, if the following expression is not less than
the max_keycode value returned by the
<code class="function">ListInputDevices</code>
request, the request will fail with a
<code class="function">BadValue</code>
error:
</p><pre class="literallayout">
       first_keycode + (num_codes / keysyms_per_keycode) - 1
</pre><p>
</p><p>

<a class="xref" href="#XChangeDeviceKeyMapping"><code class="function"> XChangeDeviceKeyMapping</code></a>
can generate
<code class="function">BadAlloc ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
and
<code class="function">BadValue</code>
errors.

</p><p>

To obtain the keycodes that are used as modifiers on an 
extension device that supports input class
<code class="function">Keys ,</code>
use
<code class="function">XGetDeviceModifierMapping .</code>

</p><div class="funcsynopsis"><a id="XGetDeviceModifierMapping"></a><p><code class="funcdef">XModifierKeymap * <strong class="fsfunc"> XGetDeviceModifierMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceModifierMapping"><code class="function"> XGetDeviceModifierMapping</code></a>
is analogous to the core
<span class="olink"><code class="function">XGetModifierMapping</code></span>
function.  
The
<a class="xref" href="#XGetDeviceModifierMapping"><code class="function"> XGetDeviceModifierMapping</code></a>
function returns a newly created
<code class="function">XModifierKeymap</code>
structure that contains the keys being used as
modifiers for the specified device.
The structure should be freed after use with
<code class="function">XFreeModifierMapping .</code>
If only zero values appear in the set for any modifier,
that modifier is disabled.
</p><p>

<a class="xref" href="#XGetDeviceModifierMapping"><code class="function"> XGetDeviceModifierMapping</code></a>
can generate
<code class="function">BadDevice</code>
and
<code class="function">BadMatch</code>
errors.

</p><p>

To set which keycodes are to be used as modifiers for an extension device, use
<code class="function">XSetDeviceModifierMapping .</code>

</p><div class="funcsynopsis"><a id="XSetDeviceModifierMapping"></a><p><code class="funcdef">int <strong class="fsfunc"> XSetDeviceModifierMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, XModifierKeymap<var class="pdparam"> *modmap</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSetDeviceModifierMapping"><code class="function"> XSetDeviceModifierMapping</code></a>
is analogous to the core
<span class="olink"><code class="function">XSetModifierMapping</code></span>
function.  
The 
<a class="xref" href="#XSetDeviceModifierMapping"><code class="function"> XSetDeviceModifierMapping</code></a>
function specifies the keycodes of the keys, if any, 
that are to be used as modifiers.  A zero value means
that no key should be used.  No two arguments can have the same nonzero
keycode value.  Otherwise,
<a class="xref" href="#XSetDeviceModifierMapping"><code class="function"> XSetDeviceModifierMapping</code></a>
generates a
<code class="function">BadValue</code>
error.
There are eight modifiers, and the modifiermap member of the 
<code class="function">XModifierKeymap</code>
structure contains eight sets of max_keypermod 
keycodes, one for each modifier in the order 
<code class="function">Shift ,</code>
<code class="function">Lock ,</code>
<code class="function">Control ,</code>
<code class="function">Mod1 ,</code>
<code class="function">Mod2 ,</code>
<code class="function">Mod3 ,</code>
<code class="function">Mod4 ,</code>
and
<code class="function">Mod5 .</code>
Only nonzero keycodes have meaning in each set, and zero keycodes
are ignored.
In addition, all of the nonzero keycodes must be in the range specified by 
min_keycode and max_keycode reported by the
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
function.
Otherwise,
<span class="olink"><code class="function">XSetModifierMapping</code></span>
generates a
<code class="function">BadValue</code>
error.
No keycode may appear twice in the entire map. 
Otherwise, it generates a
<code class="function">BadValue</code>
error.
</p><p>

A X server can impose restrictions on how modifiers can be changed, 
for example,
if certain keys do not generate up transitions in hardware or if multiple
modifier keys are not supported.  
If some such restriction is violated, 
the status reply is
<code class="function">MappingFailed ,</code>
and none of the modifiers are changed.
If the new keycodes specified for a modifier differ from those
currently defined and any (current or new) keys for that modifier are
in the logically down state, 
the status reply is
<code class="function">MappingBusy , </code>
and none of the modifiers are changed.
<span class="olink"><code class="function">XSetModifierMapping</code></span>
generates a
<code class="function">DeviceMappingNotify</code>
event on a
<code class="function">MappingSuccess</code>
status.
</p><p>

<a class="xref" href="#XSetDeviceModifierMapping"><code class="function"> XSetDeviceModifierMapping</code></a>
can generate
<code class="function">BadAlloc ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
and
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Controlling_Button_Mapping"></a>Controlling Button Mapping</h4></div></div></div><p>

To set the mapping of the buttons on an extension device, use
<code class="function">XSetDeviceButtonMapping .</code>

</p><div class="funcsynopsis"><a id="XSetDeviceButtonMapping"></a><p><code class="funcdef">int <strong class="fsfunc"> XSetDeviceButtonMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, unsignedchar<var class="pdparam"> map[]</var>, int<var class="pdparam"> nmap</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSetDeviceButtonMapping"><code class="function"> XSetDeviceButtonMapping</code></a>
sets the mapping of the buttons on an extension device.
If it succeeds, the X server generates a
<code class="function">DeviceMappingNotify</code>
event, and
<a class="xref" href="#XSetDeviceButtonMapping"><code class="function"> XSetDeviceButtonMapping</code></a>
returns
<code class="function">MappingSuccess .</code>
Elements of the list are indexed starting from one.
The length of the list must be the same as
<a class="xref" href="#XGetDeviceButtonMapping"><code class="function"> XGetDeviceButtonMapping</code></a>
would return, or a 
<code class="function">BadValue</code>
error results.
The index is a button number, and the element of the list
defines the effective number.
A zero element disables a button, and elements are not restricted in
value by the number of physical buttons.
However, no two elements can have the same nonzero value, or a
<code class="function">BadValue</code>
error results.
If any of the buttons to be altered are logically in the down state,
<a class="xref" href="#XSetDeviceButtonMapping"><code class="function"> XSetDeviceButtonMapping</code></a>
returns
<code class="function">MappingBusy ,</code>
and the mapping is not changed.
</p><p>

<a class="xref" href="#XSetDeviceButtonMapping"><code class="function"> XSetDeviceButtonMapping</code></a>
can generate
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
and
<code class="function">BadValue</code>
errors.

</p><p>

To get the button mapping, use
<code class="function">XGetDeviceButtonMapping .</code>

</p><div class="funcsynopsis"><a id="XGetDeviceButtonMapping"></a><p><code class="funcdef">int <strong class="fsfunc"> XGetDeviceButtonMapping</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, unsignedchar<var class="pdparam"> map_return[]</var>, int<var class="pdparam"> nmap</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceButtonMapping"><code class="function"> XGetDeviceButtonMapping</code></a>
returns the current mapping of the specified extension device.
Elements of the list are indexed starting from one.
<a class="xref" href="#XGetDeviceButtonMapping"><code class="function"> XGetDeviceButtonMapping</code></a>
returns the number of physical buttons actually on the pointer.
The nominal mapping for the buttons is the identity mapping: map[i]=i.
The nmap argument specifies the length of the array where the button
mapping is returned, and only the first nmap elements are returned 
in map_return.
</p><p>

<a class="xref" href="#XGetDeviceButtonMapping"><code class="function"> XGetDeviceButtonMapping</code></a>
can generate
<code class="function">BadDevice</code>
and
<code class="function">BadMatch</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Obtaining_the_State_of_a_Device"></a>Obtaining the State of a Device</h4></div></div></div><p>

To obtain information that describes the state of the keys, buttons, and 
valuators of an extension device, use
<code class="function">XQueryDeviceState .</code>

</p><div class="funcsynopsis"><a id="XQueryDeviceState"></a><p><code class="funcdef">XDeviceState * <strong class="fsfunc"> XQueryDeviceState</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var><code>)</code>;</p></div><p>

<a class="xref" href="#XQueryDeviceState"><code class="function"> XQueryDeviceState</code></a>
returns a pointer to an
<code class="function">XDeviceState</code>
structure, which points to a list of
structures that describe the state of the keys, buttons, and valuators 
on the device:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID device_id;
     int num_classes;
     XInputClass *data;
} XDeviceState;
</pre><p>
</p><p>

The structures are of variable length, but the first 
two members are common to all and are as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     unsigned char class;
     unsigned char length;
} XInputClass;
</pre><p>
</p><p>

The class member contains a class identifier.  This identifier can be
compared with constants defined in the file 
<code class="function">&lt; X11/extensions/XI.h &gt;.</code>
Currently defined constants are:
<code class="function">KeyClass ,</code>
<code class="function">ButtonClass ,</code>
and
<code class="function">ValuatorClass .</code>
</p><p>

The length member contains the length of the structure and can be used
by clients to traverse the list.
</p><p>

The 
<code class="function">XValuatorState</code>
structure describes the current state of the valuators
on the device.
The num_valuators member contains the number of valuators
on the device.
The mode member is a mask whose bits report the data mode
and other state information for the device.
The following bits are currently defined:
</p><pre class="literallayout">

DeviceMode     1 &lt;&lt; 0     Relative = 0, Absolute = 1
     ProximityState     1 &lt;&lt; 1     InProximity = 0, OutOfProximity = 1
</pre><p>
The valuators member contains a pointer to an array of integers that
describe the current value of the valuators.
If the mode is 
<code class="function">Relative ,</code>
these values are undefined.
</p><p>

</p><pre class="literallayout">

typedef struct {
     unsigned char class;
     unsigned char length;
     unsigned char num_valuators;
     unsigned char mode;
     int *valuators;
} XValuatorState;
</pre><p>
</p><p>

The
<code class="function">XKeyState</code>
structure describes the current state of the keys
on the device.  Byte N (from 0) contains the
bits for key 8N to 8N + 7 with the least significant bit in the
byte representing key 8N.
</p><p>

</p><pre class="literallayout">

typedef struct {
     unsigned char class;
     unsigned char length;
     short num_keys;
     char keys[32];
} XKeyState;
</pre><p>
</p><p>

The
<code class="function">XButtonState</code>
structure describes the current state of the buttons
on the device.  Byte N (from 0) contains the bits for button 8N to 8N + 7
with the least significant bit in the
byte representing button 8N.
</p><p>

</p><pre class="literallayout">

typedef struct {
     unsigned char class;
     unsigned char length;
     short num_buttons;
     char buttons[32];
} XButtonState;
</pre><p>
</p><p>

<a class="xref" href="#XQueryDeviceState"><code class="function"> XQueryDeviceState</code></a>
can generate
<code class="function">BadDevice</code>
errors.

</p><p>

To free the data returned by this function, use
<code class="function">XFreeDeviceState .</code>

</p><div class="funcsynopsis"><a id="XFreeDeviceState"></a><p><code class="funcdef">void <strong class="fsfunc"> XFreeDeviceState</strong>(</code>XDeviceState<var class="pdparam"> *state</var><code>)</code>;</p></div><p>

<a class="xref" href="#XFreeDeviceState"><code class="function"> XFreeDeviceState</code></a>
frees the device state data.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Events"></a>Events</h3></div></div></div><p>

The input extension creates input events analogous to the core input events.
These extension input events are generated by manipulating one of the
extension input devices.
The remainder of this section discusses the following X Input Extension
event topics:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Event types
    </p></li><li class="listitem"><p>
Event classes
    </p></li><li class="listitem"><p>
Event structures
    </p></li></ul></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Event_Types"></a>Event Types</h4></div></div></div><p>

Event types are integer numbers that a client can use to determine what
kind of event it has received.  The client compares the type field of 
the event structure with known event types to make this determination.
</p><p>

The core input event types are constants and are defined in the header file
<code class="function">&lt; X11/X.h &gt;.</code>
Extension event types are not constants.  Instead, they
are dynamically allocated by the extension's request to the X server
when the extension is initialized.  Because of this, extension event
types must be obtained by the client from the server.
</p><p>

The client program determines the event type for an extension event by using
the information returned by the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
request.
This type can then be used for comparison with the type field
of events received by the client.
</p><p>

Extension events propagate up the window hierarchy in the same manner
as core events.  If a window is not interested in an extension event, 
it usually propagates to the closest ancestor that is interested,
unless the dont_propagate list prohibits it.
Grabs of extension devices may alter the set of windows that receive a particular
extension event.
</p><p>

The following table lists the event category and its associated event
type or types.
</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col align="center" class="c1" /><col align="center" class="c2" /></colgroup><thead><tr><th align="center">Event Category</th><th align="center">Event Type</th></tr></thead><tbody><tr><td align="center">Device key</td><td align="center"><code class="function">DeviceKeyPress</code></td></tr><tr><td align="center"> </td><td align="center"><code class="function">DeviceKeyRelease</code></td></tr><tr><td align="center">Device motion</td><td align="center"><code class="function">DeviceButtonPress</code></td></tr><tr><td align="center"> </td><td align="center"><code class="function">DeviceButtonRelease</code></td></tr><tr><td align="center"> </td><td align="center"><code class="function">DeviceMotionNotify</code></td></tr><tr><td align="center">Device input focus</td><td align="center"><code class="function">DeviceFocusIn</code></td></tr><tr><td align="center"> </td><td align="center"><code class="function">DeviceFocusOut</code></td></tr><tr><td align="center">Device state notification</td><td align="center"><code class="function">DeviceStateNotify</code></td></tr><tr><td align="center">Device proximity</td><td align="center"><code class="function">ProximityIn</code></td></tr><tr><td align="center"> </td><td align="center"><code class="function">ProximityOut</code></td></tr><tr><td align="center">Device mapping</td><td align="center"><code class="function">DeviceMappingNotify</code></td></tr><tr><td align="center">Device change</td><td align="center"><code class="function">ChangeDeviceNotify</code></td></tr></tbody></table></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Event_Classes"></a>Event Classes</h4></div></div></div><p>

Event classes are integer numbers that are used in the same way as the
core event masks.  They are used by a client program to indicate to the
server which events that client program wishes to receive.
</p><p>

The core input event masks are constants and are defined in the header file
<code class="function">&lt; X11/X.h &gt;.</code>
Extension event classes are not constants.  Instead, they are dynamically
allocated by the extension's request to the X server
when the extension is initialized.  Because of this, extension event
classes must be obtained by the client from the server.
</p><p>

The event class for an extension event and device is obtained from
information returned by the 
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function. 
This class can then be used in an
<a class="xref" href="#XSelectExtensionEvent"><code class="function"> XSelectExtensionEvent</code></a>
request to ask that events of that type from that device be sent to
the client program.
</p><p>

For
<code class="function">DeviceButtonPress</code>
events, the client may specify whether
or not an implicit passive grab should be done when the button is
pressed.  If the client wants to guarantee that it will receive a
<code class="function">DeviceButtonRelease</code>
event for each
<code class="function">DeviceButtonPress</code>
event it receives, it should specify the
<code class="function">DeviceButtonPressGrab</code>
class in addition to the
<code class="function">DeviceButtonPress</code>
class.
This restricts the client in that only one client at a time
may request
<code class="function">DeviceButtonPress</code>
events from the same device and
window if any client specifies this class.
</p><p>

If any client has specified the
<code class="function">DeviceButtonPressGrab</code>
class, any requests by any other client that specify the same device
and window and specify either
<code class="function">DeviceButtonPress</code>
or
<code class="function">DeviceButtonPressGrab</code>
will cause an
<code class="function">Access</code>
error to be generated.
</p><p>

If only the
<code class="function">DeviceButtonPress</code>
class is specified, no implicit passive grab will be done when a button
is pressed on the device.
Multiple clients may use this class to specify the same device and
window combination.
</p><p>

The client may also select
<code class="function">DeviceMotion</code>
events only when a button is down.
It does this by specifying the event classes 
<code class="function">DeviceButton1Motion</code>
through
<code class="function">DeviceButton5Motion .  </code>
An input device will support only
as many button motion classes as it has buttons.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Event_Structures"></a>Event Structures</h4></div></div></div><p>

Each extension event type has a corresponding structure declared in
<code class="function">&lt; X11/extensions/XInput.h &gt;.</code>
All event structures have the following common members:
</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term">
      type
    </span></p></td><td><p>
Set to the event type number that uniquely identifies it.  For example,
when the X server reports a
<code class="function">DeviceKeyPress</code>
event to a client application, it sends an
<code class="function">XDeviceKeyPressEvent</code>
structure.
      </p></td></tr><tr><td><p><span class="term">
      serial
    </span></p></td><td><p>
Set from the serial number reported in the protocol but expanded from the
16-bit least significant bits to a full 32-bit value.
      </p></td></tr><tr><td><p><span class="term">
      send_event
    </span></p></td><td><p>
Set to 
<code class="function">True</code>
if the event came from an
<span class="olink"><code class="function">XSendEvent</code></span>
request.
      </p></td></tr><tr><td><p><span class="term">
      display
    </span></p></td><td><p>
Set to a pointer to a structure that defines the display 
on which the event was read.
    </p></td></tr></tbody></table></div><p>
</p><p>

Extension event structures report the current position of the X pointer.
In addition, if the device reports motion data and is reporting absolute data,
the current value of any valuators the device contains is also reported.
</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Device_Key_Events"></a>Device Key Events</h5></div></div></div><p>

Key events from extension devices contain all the information that is
contained in a key event from the X keyboard.  In addition, they contain
a device ID and report the current value of any valuators on the device,
if that device is reporting absolute data.
If data for more than six valuators is being reported, more than one
key event will be sent.
The axes_count member contains the number of axes that are being
reported.  The server sends as many of these events as are
needed to report the device data.  Each event contains the total number
of axes reported in the axes_count member and the first axis reported
in the current event in the first_axis member.
If the device supports input class
<code class="function">Valuators , </code>
but is not reporting absolute mode data,
the axes_count member  contains zero (0).
</p><p>

The location reported in 
the x, y and x_root, y_root members is the location of the core X pointer.
</p><p>

The
<code class="function">XDeviceKeyEvent</code>
structure is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;                      /* of event */
     unsigned long serial;          /* # of last request processed */
     Bool send_event;               /* true if from SendEvent request */
     Display *display;              /* Display the event was read from */
     Window window;                 /* "event" window reported relative to */
     XID deviceid;
     Window root;                   /* root window event occurred on */
     Window subwindow;              /* child window */
     Time time;                     /* milliseconds */
     int x, y;                      /* x, y coordinates in event window */
     int x_root;                    /* coordinates relative to root */
     int y_root;                    /* coordinates relative to root */
     unsigned int state;            /* key or button mask */
     unsigned int keycode;          /* detail */
     Bool same_screen;              /* same screen flag */
     unsigned int device_state;     /* device key or button mask */
     unsigned char axes_count;
     unsigned char first_axis;
     int axis_data[6];
} XDeviceKeyEvent;

typedef XDeviceKeyEvent XDeviceKeyPressedEvent;
typedef XDeviceKeyEvent XDeviceKeyReleasedEvent;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Device_Button_Events"></a>Device Button Events</h5></div></div></div><p>

Button events from extension devices contain all the information that is
contained in a button event from the X pointer.  In addition, they contain
a device ID and report the current value of any valuators on the device
if that device is reporting absolute data.
If data for more than six valuators is being reported, more than one
button event may be sent.
The axes_count member contains the number of axes that are being
reported.  The server sends as many of these events as are
needed to report the device data.  Each event contains the total number
of axes reported in the axes_count member and the first axis reported
in the current event in the first_axis member.
If the device supports input class
<code class="function">Valuators , </code>
but is not reporting absolute mode data,
the axes_count member contains zero (0).
</p><p>

The location reported in 
the x, y and x_root, y_root members is the location of the core X pointer.
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;                      /* of event */
     unsigned long serial;          /* # of last request processed by server */
     Bool send_event;               /* true if from a SendEvent request */
     Display *display;              /* Display the event was read from */
     Window window;                 /* "event" window reported relative to */
     XID deviceid;
     Window root;                   /* root window that the event occurred on */
     Window subwindow;              /* child window */
     Time time;                     /* milliseconds */
     int x, y;                      /* x, y coordinates in event window */
     int x_root;                    /* coordinates relative to root */
     int y_root;                    /* coordinates relative to root */
     unsigned int state;            /* key or button mask */
     unsigned int button;           /* detail */
     Bool same_screen;              /* same screen flag */
     unsigned int device_state;     /* device key or button mask */
     unsigned char axes_count;
     unsigned char first_axis;
     int axis_data[6];
} XDeviceButtonEvent;

typedef XDeviceButtonEvent XDeviceButtonPressedEvent;
typedef XDeviceButtonEvent XDeviceButtonReleasedEvent;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Device_Motion_Events"></a>Device Motion Events</h5></div></div></div><p>

Motion events from extension devices contain all the information that is
contained in a motion event from the X pointer.  In addition, they contain
a device ID and report the current value of any valuators on the device.
</p><p>

The location reported in 
the x, y and x_root, y_root members is the location of the core X pointer, 
and so is 2-dimensional.
</p><p>

Extension motion devices may report motion data for a variable number of 
axes.  
The axes_count member contains the number of axes that are being
reported.  The server sends as many of these events as are
needed to report the device data.  Each event contains the total number
of axes reported in the axes_count member and the first axis reported
in the current event in the first_axis member.
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;                          /* of event */
     unsigned long serial;              /* # of last request processed by server */
     Bool send_event;                   /* true if from a SendEvent request */
     Display *display;                  /* Display the event was read from */
     Window window;                     /* "event" window reported relative to */
     XID deviceid;
     Window root;                       /* root window that the event occurred on */
     Window subwindow;                  /* child window */
     Time time;                         /* milliseconds */
     int x, y;                          /* x, y coordinates in event window */
     int x_root;                        /* coordinates relative to root */
     int y_root;                        /* coordinates relative to root */
     unsigned int state;                /* key or button mask */
     char is_hint;                      /* detail */
     Bool same_screen;                  /* same screen flag */
     unsigned int device_state;         /* device key or button mask */
     unsigned char axes_count;
     unsigned char first_axis;
     int axis_data[6];
} XDeviceMotionEvent;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Device_Focus_Events"></a>Device Focus Events</h5></div></div></div><p>

These events are equivalent to the core focus events.
They contain the same information, with the addition
of a device ID to identify which device has had a focus change,
and a timestamp.
</p><p>

<code class="function">DeviceFocusIn</code>
and
<code class="function">DeviceFocusOut</code>
events are generated for
focus changes of extension devices in the same manner as core focus
events are generated.
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;                      /* of event */
     unsigned long serial;          /* # of last request processed by server */
     Bool send_event;               /* true if this came from a SendEvent request */
     Display *display;              /* Display the event was read from */
     Window window;                 /* "event" window it is reported relative to */
     XID deviceid;
     int mode;                      /* NotifyNormal, NotifyGrab, NotifyUngrab */
     int detail;
                                    /*
                                     * NotifyAncestor, NotifyVirtual, NotifyInferior, 
                                     * NotifyNonLinear,NotifyNonLinearVirtual, NotifyPointer,
                                     * NotifyPointerRoot, NotifyDetailNone 
                                     */
     Time time;
} XDeviceFocusChangeEvent;

typedef XDeviceFocusChangeEvent XDeviceFocusInEvent;
typedef XDeviceFocusChangeEvent XDeviceFocusOutEvent;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Device_StateNotify_Event"></a>Device StateNotify Event</h5></div></div></div><p>

This event is analogous to the core keymap event but
reports the current state of the device for each
input class that it supports.
It is generated after every
<code class="function">DeviceFocusIn</code>
event and
<code class="function">EnterNotify</code>
event and is delivered to clients who have selected
<code class="function">XDeviceStateNotify</code>
events.
</p><p>

If the device supports input class
<code class="function">Valuators ,</code>
the mode member in the
<code class="function">XValuatorStatus</code>
structure is a bitmask that reports the device mode,
proximity state, and other state information.
The following bits are currently defined:
</p><pre class="literallayout">

0x01     Relative = 0, Absolute = 1
     0x02     InProximity = 0, OutOfProximity = 1
</pre><p>
</p><p>

If the device supports more valuators than can be reported in a single
<code class="function">XEvent ,</code>
multiple
<code class="function">XDeviceStateNotify</code>
events will be generated.
</p><p>

</p><pre class="literallayout">

typedef struct {
     unsigned char class;
     unsigned char length;
} XInputClass;

typedef struct {
     unsigned char class;
     unsigned char length;
     unsigned char num_valuators;
     unsigned char mode;
     int valuators[6];
} XValuatorStatus;

typedef struct {
     unsigned char class;
     unsigned char length;
     short num_keys;
     char keys[32];
} XKeyStatus;

typedef struct {
     unsigned char class;
     unsigned char length;
     short num_buttons;
     char buttons[32];
} XButtonStatus;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Device_Mapping_Event"></a>Device Mapping Event</h5></div></div></div><p>

This event is equivalent to the core
<code class="function">MappingNotify</code>
event.
It notifies client programs when the mapping of keys,
modifiers, or buttons on an extension device has changed.
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;
     unsigned long serial;     
     Bool send_event;
     Display *display;
     Window window;
     XID deviceid;
     Time time;
     int request;
     int first_keycode;
     int count;
} XDeviceMappingEvent;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="ChangeDeviceNotify_Event"></a>ChangeDeviceNotify Event</h5></div></div></div><p>

This event has no equivalent in the core protocol.  It notifies client
programs when one of the core devices has been changed.
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;
     unsigned long serial;
     Bool send_event;
     Display *display;
     Window window;
     XID deviceid;
     Time time;
     int request;
} XChangeDeviceNotifyEvent;
</pre><p>

</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="Proximity_Events"></a>Proximity Events</h5></div></div></div><p>

These events have no equivalent in the core protocol.  Some input
devices such as graphics tablets or touchscreens may send these
events to indicate that a stylus has moved into or out of contact
with a positional sensing surface.
</p><p>

The event contains the current value of any valuators on the device
if that device is reporting absolute data.
If data for more than six valuators is being reported, more than one
proximity event may be sent.
The axes_count member contains the number of axes that are being
reported.  The server sends as many of these events as are
needed to report the device data.  Each event contains the total number
of axes reported in the axes_count member and the first axis reported
in the current event in the first_axis member.
If the device supports input class
<code class="function">Valuators , </code>
but is not reporting absolute mode data,
the axes_count member contains zero (0).
</p><p>

</p><pre class="literallayout">

typedef struct {
     int type;                 /* ProximityIn or ProximityOut */        
     unsigned long serial;     /* # of last request processed by server */
     Bool send_event;          /* true if this came from a SendEvent request */
     Display *display;         /* Display the event was read from */
     Window window;      
     XID deviceid;
     Window root;            
     Window subwindow;      
     Time time;            
     int x, y;            
     int x_root, y_root;  
     unsigned int state;           
     Bool same_screen;     
     unsigned int device_state;   /* device key or button mask */
     unsigned char axes_count;
     unsigned char first_axis;
     int axis_data[6];
} XProximityNotifyEvent;

typedef XProximityNotifyEvent XProximityInEvent;
typedef XProximityNotifyEvent XProximityOutEvent;
</pre><p>

</p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Event_Handling_Functions"></a>Event Handling Functions</h3></div></div></div><p>

This section discusses the X Input Extension
event handling functions that allow you to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Determine the extension version
    </p></li><li class="listitem"><p>
List the available devices
    </p></li><li class="listitem"><p>
Enable and disable extension devices
    </p></li><li class="listitem"><p>
Change the mode of a device
    </p></li><li class="listitem"><p>
Initialize valuators on an input device
    </p></li><li class="listitem"><p>
Get input device controls
    </p></li><li class="listitem"><p>
Change input device controls
    </p></li><li class="listitem"><p>
Select extension device events
    </p></li><li class="listitem"><p>
Determine selected device events
    </p></li><li class="listitem"><p>
Control event propagation
    </p></li><li class="listitem"><p>
Send an event
    </p></li><li class="listitem"><p>
Get motion history
    </p></li></ul></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Determining_the_Extension_Version"></a>Determining the Extension Version</h4></div></div></div><p>

</p><div class="funcsynopsis"><a id="XGetExtensionVersion"></a><p><code class="funcdef">XExtensionVersion * <strong class="fsfunc"> XGetExtensionVersion</strong>(</code>Display<var class="pdparam"> *display</var>, char<var class="pdparam"> *name</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetExtensionVersion"><code class="function"> XGetExtensionVersion</code></a>
allows a client to determine whether a server supports
the desired version of the input extension.
</p><p>

The 
<code class="function">XExtensionVersion</code>
structure returns information about the version of the extension
supported by the server and is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     Bool present;   
     short major_version;
     short minor_version;
} XExtensionVersion;
</pre><p>
</p><p>

The major and minor versions can be compared with constants defined in
the header file 
<code class="function">&lt; X11/extensions/XI.h &gt;.</code>
Each version is a superset of the previous versions.
</p><p>

You should use 
<span class="olink"><code class="function">XFree</code></span>.
to free the data returned by this function.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Listing_Available_Devices"></a>Listing Available Devices</h4></div></div></div><p>

A client program that wishes to access a specific device
must first determine whether that device is connected to the X server.  This
is done through the
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
function, which will return a list of all devices that can be opened
by the X server.  The client program can use one
of the names defined in the
<code class="function">&lt; X11/extensions/XI.h &gt;</code>
header file in an
<span class="olink"><code class="function">XInternAtom</code></span>
request to determine the device type of the desired device.  This type 
can then be compared with the device types returned by the 
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
request.
</p><p>

</p><div class="funcsynopsis"><a id="XListInputDevices"></a><p><code class="funcdef">XDeviceInfo * <strong class="fsfunc"> XListInputDevices</strong>(</code>Display<var class="pdparam"> *display</var>, int<var class="pdparam"> *ndevices</var><code>)</code>;</p></div><p>

<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
allows a client to determine which devices 
are available for X input and information about those devices.
An array of
<code class="function">XDeviceInfo</code>
structures is returned, with one element in the array for each device.
The number of devices is returned in the ndevices argument.
</p><p>

The X pointer device and X keyboard device are reported, as well as
all available extension input devices.  The use member of the 
<code class="function">XDeviceInfo</code>
structure specifies the current use of the device.
If the value of this member is 
<code class="function">IsXPointer ,</code>
the device is the X pointer device.  If the value is
<code class="function">IsXKeyboard ,</code>
the device is the X keyboard device.  If the value is
<code class="function">IsXExtensionDevice ,</code>
the device is available for use as an extension input device.
</p><p>

Each
<code class="function">XDeviceInfo</code>
entry contains a pointer to a list of structures 
that describe the characteristics of each class
of input supported by that device.  The num_classes member
contains the number of entries in that list.
</p><p>

If the device supports input class
<code class="function">Valuators ,</code>
one of the structures pointed to by the
<code class="function">XDeviceInfo</code>
structure will be an
<code class="function">XValuatorInfo</code>
structure.  The axes member of that structure
contains the address of an array of
<code class="function">XAxisInfo</code>
structures.
There is one element in this array for each axis of motion
reported by the device.  The number of elements in this 
array is contained in the num_axes element of the 
<code class="function">XValuatorInfo</code>
structure.
The size of the motion buffer for the device is
reported in the motion_buffer member of the
<code class="function">XValuatorInfo</code>
structure.
</p><p>

The
<code class="function">XDeviceInfo</code>
structure is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct _XDeviceInfo {
     XID id;        
     Atom type;
     char *name;
     int num_classes;
     int use;
     XAnyClassPtr inputclassinfo;
} XDeviceInfo;
</pre><p>
</p><p>

The structures pointed to by the
<code class="function">XDeviceInfo</code>
structure are defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct _XKeyInfo {
     XID class;
     int length;
     unsigned short min_keycode;
     unsigned short max_keycode;
     unsigned short num_keys;
} XKeyInfo;

typedef struct _XButtonInfo {
     XID class;
     int length;
     short num_buttons;
} XButtonInfo;

typedef struct _XValuatorInfo {
     XID class;
     int length;
     unsigned char num_axes;
     unsigned char mode;
     unsigned long motion_buffer;
     XAxisInfoPtr axes;
} XValuatorInfo;
</pre><p>
</p><p>

The
<code class="function">XAxisInfo</code>
structure pointed to by the
<code class="function">XValuatorInfo</code>
structure is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct _XAxisInfo {
     int resolution;
     int min_value;
     int max_value;
} XAxisInfo;
</pre><p>
</p><p>

The following atom names are defined in the 
<code class="function">&lt; X11/extensions/XI.h &gt;</code>
header file.
</p><pre class="literallayout">

MOUSE     QUADRATURE
TABLET     SPACEBALL
KEYBOARD     DATAGLOVE
TOUCHSCREEN     EYETRACKER
TOUCHPAD     CURSORKEYS
BUTTONBOX     FOOTMOUSE
BARCODE     ID_MODULE
KNOB_BOX     ONE_KNOB
TRACKBALL     NINE_KNOB\s+1
</pre><p>
</p><p>

These names can be used in an
<span class="olink"><code class="function">XInternAtom</code></span>
request to return an atom that can be used for comparison
with the type member of the 
<code class="function">XDeviceInfo</code>
structure.
</p><p>

<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
returns NULL if there are no input devices to list.

</p><p>

To free the data returned by 
<code class="function">XListInputDevices ,</code>
use
<code class="function">XFreeDeviceList .</code>

</p><p>

</p><div class="funcsynopsis"><a id="XFreeDeviceList"></a><p><code class="funcdef">void <strong class="fsfunc"> XFreeDeviceList</strong>(</code>XDeviceInfo<var class="pdparam"> *list</var><code>)</code>;</p></div><p>

<a class="xref" href="#XFreeDeviceList"><code class="function"> XFreeDeviceList</code></a>
frees the list of input device information.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Enabling_and_Disabling_Extension_Devices"></a>Enabling and Disabling Extension Devices</h4></div></div></div><p>

Each client program that wishes to access an extension device must request
that the server open that device by calling the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
function.

</p><div class="funcsynopsis"><a id="XOpenDevice"></a><p><code class="funcdef">XDevice * <strong class="fsfunc"> XOpenDevice</strong>(</code>Display<var class="pdparam"> *display</var>, XID<var class="pdparam"> device_id</var><code>)</code>;</p></div><p>

<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
opens the device for the requesting client and, on success, returns an
<code class="function">XDevice</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID device_id;
     int num_classes;
     XInputClassInfo *classes;
} XDevice;
</pre><p>
</p><p>

The
<code class="function">XDevice</code>
structure contains a pointer to an array of
<code class="function">XInputClassInfo</code>
structures.  Each element in that array
contains information about events of a particular input class supported
by the input device.
</p><p>

The
<code class="function">XInputClassInfo</code>
structure is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     unsigned char input_class;
     unsigned char event_type_base;
} XInputClassInfo;
</pre><p>
</p><p>

A client program can determine the event
type and event class for a given event by using macros defined by the 
input extension.  The name of the macro corresponds to the desired event,
and the macro is passed the structure that describes the device from which
input is desired, for example:
</p><p>

</p><pre class="literallayout">

DeviceKeyPress(XDevice *device, event_type, event_class)
</pre><p>
</p><p>

The macro will fill in the values of the event class to be used in an
<a class="xref" href="#XSelectExtensionEvent"><code class="function"> XSelectExtensionEvent</code></a>
request to select the event and the event type to be used in comparing
with the event types of events received via
<span class="olink"><code class="function">XNextEvent</code></span>.
</p><p>

<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
can generate
<code class="function">BadDevice</code>
errors.

</p><p>

Before terminating, the client program should request that the server close
the device by calling the
<a class="xref" href="#XCloseDevice"><code class="function"> XCloseDevice</code></a>
function.

</p><div class="funcsynopsis"><a id="XCloseDevice"></a><p><code class="funcdef">int <strong class="fsfunc"> XCloseDevice</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var><code>)</code>;</p></div><p>

<a class="xref" href="#XCloseDevice"><code class="function"> XCloseDevice</code></a>
closes the device for the requesting client and frees the associated
<code class="function">XDevice</code>
structure.
</p><p>

A client may open the same extension device more than once.  Requests
after the first successful one return an additional
<code class="function">XDevice</code>
structure
with the same information as the first, but otherwise have no effect.
A single
<a class="xref" href="#XCloseDevice"><code class="function"> XCloseDevice</code></a>
request will terminate that client's access to the device.
</p><p>

Closing a device releases any active or passive grabs the requesting client
has established.  If the device is frozen only by an active grab of the
requesting client, any queued events are released.
</p><p>

If a client program terminates without closing a device, the server will
automatically close that device on behalf of the client.  This does not
affect any other clients that may be accessing that device.
</p><p>

<a class="xref" href="#XCloseDevice"><code class="function"> XCloseDevice</code></a>
can generate
<code class="function">BadDevice</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Changing_the_Mode_of_a_Device"></a>Changing the Mode of a Device</h4></div></div></div><p>

Some devices are capable of reporting either relative or absolute motion
data. 
To change the mode of a device from relative to absolute, use
<code class="function">XSetDeviceMode .</code>

</p><div class="funcsynopsis"><a id="XSetDeviceMode"></a><p><code class="funcdef">int <strong class="fsfunc"> XSetDeviceMode</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSetDeviceMode"><code class="function"> XSetDeviceMode</code></a>
allows a client to request the server to change the mode of a 
device that is capable of reporting either absolute positional data or relative
motion data.  If the device is invalid or if the client has not previously 
requested that the server open the device via an
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
request, this request will fail with a
<code class="function">BadDevice</code>
error.
If the device does not support input class
<code class="function">Valuators</code>
or if it is not capable of reporting the specified mode,
the request will fail with a 
<code class="function">BadMatch</code>
error.
</p><p>

This request will fail and return
<code class="function">DeviceBusy</code>
if another client has already opened the device and requested a different mode.
</p><p>

<a class="xref" href="#XSetDeviceMode"><code class="function"> XSetDeviceMode</code></a>
can generate
<code class="function">BadDevice ,</code>
<code class="function">BadMatch ,</code>
<code class="function">BadMode ,</code>
and
<code class="function">DeviceBusy</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Initializing_Valuators_on_an_Input_Device"></a>Initializing Valuators on an Input Device</h4></div></div></div><p>

Some devices that report absolute positional data can be initialized to a 
starting value.  Devices that are capable of reporting relative motion or
absolute positional data may require that their valuators be initialized 
to a starting value after the mode of the device is changed to
<code class="function">Absolute .</code>

</p><p>

To initialize the valuators on such a device, use 
<code class="function">XSetDeviceValuators .</code>

</p><div class="funcsynopsis"><a id="XSetDeviceValuators"></a><p><code class="funcdef">Status <strong class="fsfunc"> XSetDeviceValuators</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int*valuators,first_valuator,<var class="pdparam"> num_valuators</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSetDeviceValuators"><code class="function"> XSetDeviceValuators</code></a>
initializes the specified valuators on the specified extension
input device.  Valuators are numbered beginning with zero.  Only the valuators
in the range specified by first_valuator and num_valuators are set.  
A
<code class="function">BadValue</code>
error results if the number of valuators supported by the device 
is less than the following expression:
</p><pre class="literallayout">

first_valuator + num_valuators
</pre><p>
</p><p>

If the request succeeds,
<code class="function">Success</code>
is returned.  If the specified device is grabbed by some other client,
the request will fail and a status of
<code class="function">AlreadyGrabbed</code>
will be returned.
</p><p>

<a class="xref" href="#XSetDeviceValuators"><code class="function"> XSetDeviceValuators</code></a>
can generate
<code class="function">BadDevice ,</code>
<code class="function">BadLength ,</code>
<code class="function">BadMatch ,</code>
and 
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Getting_Input_Device_Controls"></a>Getting Input Device Controls</h4></div></div></div><p>

Some input devices support various configuration controls
that can be queried or changed by clients.  The set of supported
controls will vary from one input device to another.  Requests
to manipulate these controls will fail if either the target
X server or the target input device does not support the 
requested device control.
</p><p>

Each device control has a unique identifier.  Information
passed with each device control varies in length and is mapped
by data structures unique to that device control.

</p><p>

To query a device control, use
<code class="function">XGetDeviceControl .</code>

</p><div class="funcsynopsis"><a id="XGetDeviceControl"></a><p><code class="funcdef">XDeviceControl * <strong class="fsfunc"> XGetDeviceControl</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> control</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceControl"><code class="function"> XGetDeviceControl</code></a>
returns the current state of the specified device control.
If the target X server does not support that device control, a
<code class="function">BadValue</code>
error is returned.
If the specified device does not support that device control, a
<code class="function">BadMatch</code>
error
is returned.
</p><p>

If the request is successful, a pointer to a generic 
<code class="function">XDeviceState</code>
structure is returned.  The information returned varies according
to the specified control and is mapped by a structure appropriate
for that control.
The first two members are common to all device controls
and are defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID control;
     int length;
} XDeviceState;
\fP
</pre><p>
</p><p>

The control may be compared to constants defined in the file
<code class="function">&lt; X11/extensions/XI.h &gt;.</code>
Currently defined device controls include DEVICE_RESOLUTION.
</p><p>

The information returned for the DEVICE_RESOLUTION control is
defined in the 
<code class="function">XDeviceResolutionState</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID control;
     int length;
     int num_valuators;
     int *resolutions;
     int *min_resolutions;
     int *max_resolutions;
} XDeviceResolutionState;
</pre><p>
</p><p>

This device control returns a list of valuators and the range of 
valid resolutions allowed for each.  Valuators are numbered 
beginning with zero (0).  Resolutions for all valuators on the device are 
returned.  For each valuator i on the device, resolutions[i] returns 
the current setting of the resolution, min_resolutions[i] returns 
the minimum valid setting, and max_resolutions[i] returns the 
maximum valid setting.
</p><p>

When this control is specified,
<a class="xref" href="#XGetDeviceControl"><code class="function"> XGetDeviceControl</code></a>
fails with a
<code class="function">BadMatch</code>
error if the specified device has no valuators.
</p><p>

<a class="xref" href="#XGetDeviceControl"><code class="function"> XGetDeviceControl</code></a>
can generate
<code class="function">BadMatch</code>
and
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Changing_Input_Device_Controls"></a>Changing Input Device Controls</h4></div></div></div><p>

Some input devices support various configuration controls
that can be changed by clients.  Typically, this would be
done to initialize the device to a known state or configuration.
The set of supported controls will vary from one input device 
to another.  Requests to manipulate these controls will fail if 
either the target X server or the target input device does not 
support the requested device control.  Setting the device control 
will also fail if the target input device is grabbed by another 
client or is open by another client and has been set to a conflicting
state.
</p><p>

Each device control has a unique identifier.  Information
passed with each device control varies in length and is mapped
by data structures unique to that device control.

</p><p>

To change a device control, use
<code class="function">XChangeDeviceControl .</code>

</p><div class="funcsynopsis"><a id="XChangeDeviceControl"></a><p><code class="funcdef">Status <strong class="fsfunc"> XChangeDeviceControl</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, int<var class="pdparam"> control</var>, XDeviceControl<var class="pdparam"> *value</var><code>)</code>;</p></div><p>

<a class="xref" href="#XChangeDeviceControl"><code class="function"> XChangeDeviceControl</code></a>
changes the current state of the specified device control.
If the target X server does not support that device control, a
<code class="function">BadValue</code>
error is returned.
If the specified device does not support that device control, a
<code class="function">BadMatch</code>
error is returned.
If another client has the target device grabbed, a status of
<code class="function">AlreadyGrabbed</code>
is returned.
If another client has the device open and has set it to a 
conflicting state, a status of
<code class="function">DeviceBusy</code>
is returned.
If the request fails for any reason, the device control will not
be changed.
</p><p>

If the request is successful, the device control will be changed
and a status of
<code class="function">Success</code>
is returned.
The information passed varies according to the specified control
and is mapped by a structure appropriate for that control.
The first two members are common to all device controls:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID control;
     int length;
} XDeviceControl;
</pre><p>
</p><p>

The control may be set using constants defined in the 
<code class="function">&lt; X11/extensions/XI.h &gt;</code>
header file.
Currently defined device controls include DEVICE_RESOLUTION.
</p><p>

The information that can be changed by the DEVICE_RESOLUTION 
control is defined in the 
<code class="function">XDeviceResolutionControl</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     XID control;
     int length;
     int first_valuator;
     int num_valuators;
     int *resolutions;
} XDeviceResolutionControl;
</pre><p>
</p><p>

This device control changes the resolution of the specified 
valuators on the specified extension input device.  Valuators 
are numbered beginning with zero.  Only the valuators in the range 
specified by first_valuator and num_valuators are set.  A value 
of -1 in the resolutions list indicates that the resolution for 
this valuator is not to be changed.  The num_valuators member
specifies the number of valuators in the resolutions list.
</p><p>

When this control is specified,
<a class="xref" href="#XChangeDeviceControl"><code class="function"> XChangeDeviceControl</code></a>
fails with a
<code class="function">BadMatch</code>
error if the specified device has no valuators.
If a resolution is specified that is not within the range of valid values 
(as returned by
<code class="function">XGetDeviceControl ),</code>
<a class="xref" href="#XChangeDeviceControl"><code class="function"> XChangeDeviceControl</code></a>
fails with a
<code class="function">BadValue</code>
error.
A
<code class="function">BadValue</code>
error results if the number of valuators supported by the device 
is less than the following expression:
</p><p>

</p><pre class="literallayout">

first_valuator + num_valuators, 
</pre><p>
</p><p>

<a class="xref" href="#XChangeDeviceControl"><code class="function"> XChangeDeviceControl</code></a>
can generate
<code class="function">BadMatch</code>
and
<code class="function">BadValue</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Selecting_Extension_Device_Events"></a>Selecting Extension Device Events</h4></div></div></div><p>

To select device input events, use
<code class="function">XSelectExtensionEvent .</code>
The parameters passed are a pointer to 
a list of classes that define the desired event types and devices, a count
of the number of elements in the list, and the ID of the window from which 
events are desired.

</p><div class="funcsynopsis"><a id="XSelectExtensionEvent"></a><p><code class="funcdef">int <strong class="fsfunc"> XSelectExtensionEvent</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> window</var>, XEventClass<var class="pdparam"> *event_list</var>, int<var class="pdparam"> event_count</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSelectExtensionEvent"><code class="function"> XSelectExtensionEvent</code></a>
requests the server to send events that match the events and
devices described by the event list and that come from the requested 
window.  
The elements of the
<code class="function">XEventClass</code>
array are the event_class values
obtained by invoking a macro with the pointer to an
<code class="function">XDevice</code>
structure returned by the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
request.
For example, the
<code class="function">DeviceKeyPress</code>
macro would return the
<code class="function">XEventClass</code>
for
<code class="function">DeviceKeyPress</code>
events from the specified device if it were invoked in the following form:
</p><pre class="literallayout">

DeviceKeyPress (XDevice *device, event_type, event_class)
</pre><p>
</p><p>

Macros are defined for the following event classes: 
</p><pre class="literallayout">
<code class="function">DeviceKeyPress</code>
<code class="function">DeviceKeyRelease</code>
<code class="function">DeviceButtonPress</code>
<code class="function">DeviceButtonRelease</code>
<code class="function">DeviceMotionNotify</code>
<code class="function">DeviceFocusIn</code>
<code class="function">DeviceFocusOut</code>
<code class="function">ProximityIn</code>
<code class="function">ProximityOut</code>
<code class="function">DeviceStateNotify</code>
<code class="function">DeviceMappingNotify</code>
<code class="function">ChangeDeviceNotify</code>
<code class="function">DevicePointerMotionHint</code>
<code class="function">DeviceButton1Motion </code>
<code class="function">DeviceButton2Motion</code>
<code class="function">DeviceButton3Motion, </code>
<code class="function">DeviceButton4Motion</code>
<code class="function">DeviceButton5Motion</code>
<code class="function">DeviceButtonMotion,</code>
<code class="function">DeviceOwnerGrabButton</code>
<code class="function">DeviceButtonPressGrab</code>
</pre><p>
</p><p>

To get the next available event from within a client program, use the core
<span class="olink"><code class="function">XNextEvent</code></span>
function.  This returns the next event whether it
came from a core device or an extension device.
</p><p>

Succeeding
<a class="xref" href="#XSelectExtensionEvent"><code class="function"> XSelectExtensionEvent</code></a>
requests using event classes
for the same device as was specified on a previous request will replace
the previous set of selected events from that device with the new set.
</p><p>

<a class="xref" href="#XSelectExtensionEvent"><code class="function"> XSelectExtensionEvent</code></a>
can generate
<code class="function">BadAccess , </code>
<code class="function">BadClass ,</code>
<code class="function">BadLength ,</code>
and
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Determining_Selected_Device_Events"></a>Determining Selected Device Events</h4></div></div></div><p>

To determine which extension events are currently selected from a given
window, use
<code class="function">XGetSelectedExtensionEvents .</code>

</p><div class="funcsynopsis"><a id="XGetSelectedExtensionEvents"></a><p><code class="funcdef">int <strong class="fsfunc"> XGetSelectedExtensionEvents</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> window</var>, int<var class="pdparam"> *this_client_count</var>, XEventClass<var class="pdparam"> **this_client</var>, int<var class="pdparam"> *all_clients_count</var>, XEventClass<var class="pdparam"> **all_clients</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetSelectedExtensionEvents"><code class="function"> XGetSelectedExtensionEvents</code></a>
returns pointers to two event class arrays.  
One lists the extension events selected by this client from
the specified window.  The other lists the extension events selected by
all clients from the specified window.  This information is analogous
to that returned in your_event_mask and all_event_masks of the
<code class="function">XWindowAttributes</code>
structure when an 
<span class="olink"><code class="function">XGetWindowAttributes</code></span>
request is made.
To free the two arrays returned by this function, use
<span class="olink"><code class="function">XFree</code></span>.
</p><p>

<a class="xref" href="#XGetSelectedExtensionEvents"><code class="function"> XGetSelectedExtensionEvents</code></a>
can generate
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Controlling_Event_Propagation"></a>Controlling Event Propagation</h4></div></div></div><p>

Client programs may control event propagation through the use
of the following two functions:
<a class="xref" href="#XChangeDeviceDontPropagateList"><code class="function"> XChangeDeviceDontPropagateList</code></a>
and
<code class="function">XGetDeviceDontPropagateList .  </code>
</p><p>

</p><div class="funcsynopsis"><a id="XChangeDeviceDontPropagateList"></a><p><code class="funcdef">int <strong class="fsfunc"> XChangeDeviceDontPropagateList</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> window</var>, int<var class="pdparam"> event_count</var>, XEventClass<var class="pdparam"> *events</var>, int<var class="pdparam"> mode</var><code>)</code>;</p></div><p>

<a class="xref" href="#XChangeDeviceDontPropagateList"><code class="function"> XChangeDeviceDontPropagateList</code></a>
adds an event to or deletes an event from the do_not_propagate list 
of extension events for the specified window.
There is one list per window, and the list remains for the life of the window.
The list is not altered if a client that changed the list terminates.
</p><p>

Suppression of event propagation is not allowed for all events.  If a
specified
<code class="function">XEventClass</code>
is invalid because suppression of that event is not allowed, a
<code class="function">BadClass</code>
error results.
</p><p>

<a class="xref" href="#XChangeDeviceDontPropagateList"><code class="function"> XChangeDeviceDontPropagateList</code></a>
can generate
<code class="function">BadClass ,</code>
<code class="function">BadMode ,</code>
and
<code class="function">BadWindow</code>
errors.

</p><p>

</p><div class="funcsynopsis"><a id="XGetDeviceDontPropagateList"></a><p><code class="funcdef">XEventClass * <strong class="fsfunc"> XGetDeviceDontPropagateList</strong>(</code>Display<var class="pdparam"> *display</var>, Window<var class="pdparam"> window</var>, int<var class="pdparam"> *event_count</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceDontPropagateList"><code class="function"> XGetDeviceDontPropagateList</code></a>
allows a client to determine the do_not_propagate list of extension events
for the specified window.
It returns an array of
<code class="function">XEventClass ,</code>
each
<code class="function">XEventClass</code>
representing a device/event type pair.
To free the data returned by this function, use
<span class="olink"><code class="function">XFree</code></span>.
</p><p>

<a class="xref" href="#XGetDeviceDontPropagateList"><code class="function"> XGetDeviceDontPropagateList</code></a>
can generate
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Sending_an_Event"></a>Sending an Event</h4></div></div></div><p>

To send an extension event to another client, use
<code class="function">XSendExtensionEvent .</code>

</p><div class="funcsynopsis"><a id="XSendExtensionEvent"></a><p><code class="funcdef">int <strong class="fsfunc"> XSendExtensionEvent</strong>(</code>Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, Window<var class="pdparam"> window</var>, Bool<var class="pdparam"> propagate</var>, int<var class="pdparam"> event_count</var>, XEventClass<var class="pdparam"> *event_list</var>, XEvent<var class="pdparam"> *event</var><code>)</code>;</p></div><p>

<a class="xref" href="#XSendExtensionEvent"><code class="function"> XSendExtensionEvent</code></a>
identifies the destination window, determines which clients should receive
the specified event, and ignores any active grabs.
It requires a list of
<code class="function">XEventClass</code>
to be specified.
These are obtained by opening an input device with the
<a class="xref" href="#XOpenDevice"><code class="function"> XOpenDevice</code></a>
request.
</p><p>

<a class="xref" href="#XSendExtensionEvent"><code class="function"> XSendExtensionEvent</code></a>
uses the window argument to identify the destination window as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If you pass
<code class="function">PointerWindow ,</code>
the destination window is the window that contains the pointer.
    </p></li><li class="listitem"><p>
If you pass
<code class="function">InputFocus</code>
and if the focus window contains the pointer,
the destination window is the window that contains the pointer.
If the focus window does not contain the pointer,
the destination window is the focus window.
    </p></li></ul></div><p>

To determine which clients should receive the specified events, 
<a class="xref" href="#XSendExtensionEvent"><code class="function"> XSendExtensionEvent</code></a>
uses the propagate argument as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If propagate is
<code class="function">False ,</code>
the event is sent to every client selecting
from the destination window
any of the events specified in the event_list array.
    </p></li><li class="listitem"><p>
If propagate is
<code class="function">True </code>
and no clients have selected from the destination window
any of the events specified in the event_list array, the destination is 
replaced with the closest ancestor of destination for which some client
has selected one of the specified events and for which no intervening
window has that event in its do_not_propagate mask.
If no such window exists,
or if the window is an ancestor of the focus window, and 
<code class="function">InputFocus</code>
was originally specified as the destination,
the event is not sent to any clients.  Otherwise, the event is reported to every
client selecting on the final destination any of the events specified
in event_list.
    </p></li></ul></div><p>

The event in the
<code class="function">XEvent</code>
structure must be one of the events defined
by the input extension, so that the X server can correctly byte swap the
contents as necessary.  The contents of the event are otherwise unaltered
and unchecked by the X server except to force send_event to
<code class="function">True</code>
in the forwarded event and to set the sequence number in the event correctly.
</p><p>

<a class="xref" href="#XSendExtensionEvent"><code class="function"> XSendExtensionEvent</code></a>
returns zero if the conversion-to-wire protocol failed;
otherwise, it returns nonzero.
</p><p>

<a class="xref" href="#XSendExtensionEvent"><code class="function"> XSendExtensionEvent</code></a>
can generate
<code class="function">BadClass ,</code>
<code class="function">BadDevice ,</code>
<code class="function">BadValue ,</code>
and
<code class="function">BadWindow</code>
errors.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="Getting_Motion_History"></a>Getting Motion History</h4></div></div></div><p>

</p><div class="funcsynopsis"><a id="XGetDeviceMotionEvents"></a><p><code class="funcdef">XDeviceTimeCoord * <strong class="fsfunc"> XGetDeviceMotionEvents</strong>(</code><var class="pdparam"> axis_count_return)</var>, Display<var class="pdparam"> *display</var>, XDevice<var class="pdparam"> *device</var>, Timestart,<var class="pdparam"> stop</var>, int<var class="pdparam"> *nevents_return</var>, int<var class="pdparam"> *mode_return</var>, int<var class="pdparam"> *axis_count_return</var><code>)</code>;</p></div><p>

<a class="xref" href="#XGetDeviceMotionEvents"><code class="function"> XGetDeviceMotionEvents</code></a>
returns all positions in the device's motion history buffer
that fall between the specified start and stop times inclusive.
If the start time is in the future or is later than the stop time,
no positions are returned.
</p><p>

The return type for this function is an
<code class="function">XDeviceTimeCoord</code>
structure, which is defined as follows:
</p><p>

</p><pre class="literallayout">

typedef struct {
     Time time;
     unsigned int *data;
} XDeviceTimeCoord;
</pre><p>
</p><p>

The data member is a pointer to an array of data items.
Each item is of type int, and there is one data item
per axis of motion reported by the device.
The number of axes reported by the device is returned in the axis_count variable.
</p><p>

The value of the data items depends on the mode of the device. 
The mode is returned in the mode variable.  If the 
mode is
<code class="function">Absolute ,</code>
the data items are the raw values generated by the device.
These may be scaled by the client program using the
maximum values that the device can generate for each axis of motion
that it reports.  The maximum value for each axis is reported in
the max_val member of the
<code class="function">XAxisInfo</code>
structure, which is part of the information returned by the
<a class="xref" href="#XListInputDevices"><code class="function"> XListInputDevices</code></a>
request.
</p><p>

If the mode is
<code class="function">Relative ,</code>
the data items are the relative values generated by the device.
The client program must choose an initial
position for the device and maintain a current position by 
accumulating these relative values.
</p><p>

Consecutive calls to
<a class="xref" href="#XGetDeviceMotionEvents"><code class="function"> XGetDeviceMotionEvents</code></a>
can return data of different modes, that is, if
some client program has changed the mode of the device via an
<a class="xref" href="#XSetDeviceMode"><code class="function"> XSetDeviceMode</code></a>
request.
</p><p>

<a class="xref" href="#XGetDeviceMotionEvents"><code class="function"> XGetDeviceMotionEvents</code></a>
can generate
<code class="function">BadDevice</code>
and
<code class="function">BadMatch</code>
errors.

</p><p>

To free the data returned by
<code class="function">XGetDeviceMotionEvents ,</code>
use
<code class="function">XFreeDeviceMotionEvents .</code>
</p><p>

</p><div class="funcsynopsis"><a id="XFreeDeviceMotionEvents"></a><p><code class="funcdef">void <strong class="fsfunc"> XFreeDeviceMotionEvents</strong>(</code>XDeviceTimeCoord<var class="pdparam"> *events</var><code>)</code>;</p></div><p>

<a class="xref" href="#XFreeDeviceMotionEvents"><code class="function"> XFreeDeviceMotionEvents</code></a>
frees the specified array of motion information.

<code class="function">Appendix A</code>

</p><p>

The following information is contained in the <code class="function">&lt;X11/extensions/XInput.h&gt;</code>
and <code class="function">&lt;X11/extensions/XI.h&gt;</code> header files:
</p><pre class="literallayout">

/* Definitions used by the library and client */

#ifndef _XINPUT_H_
#define _XINPUT_H_

#ifndef _XLIB_H_
#include &lt;X11/Xlib.h&gt;
#endif

#ifndef _XI_H_
#include "XI.h"
#endif

#define _deviceKeyPress          0
#define _deviceKeyRelease     1

#define _deviceButtonPress     0
#define _deviceButtonRelease     1

#define _deviceMotionNotify     0

#define _deviceFocusIn          0
#define _deviceFocusOut          1

#define _proximityIn          0
#define _proximityOut          1

#define _deviceStateNotify     0
#define _deviceMappingNotify     1
#define _changeDeviceNotify     2

#define FindTypeAndClass(d, type, class, classid, offset) \
    { int i; XInputClassInfo *ip; \
    type = 0; class = 0; \
    for (i=0, ip= ((XDevice *) d)-&gt;classes; \
      i&lt; ((XDevice *) d)-&gt;num_classes; \
      i++, ip++) \
     if (ip-&gt;input_class == classid) \
         {type =  ip-&gt;event_type_base + offset; \
          class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | type;}}

#define DeviceKeyPress(d, type, class) \
    FindTypeAndClass(d, type, class, KeyClass, _deviceKeyPress)

#define DeviceKeyRelease(d, type, class) \
    FindTypeAndClass(d, type, class, KeyClass, _deviceKeyRelease)

#define DeviceButtonPress(d, type, class) \
    FindTypeAndClass(d, type, class, ButtonClass, _deviceButtonPress)

#define DeviceButtonRelease(d, type, class) \
    FindTypeAndClass(d, type, class, ButtonClass, _deviceButtonRelease)

#define DeviceMotionNotify(d, type, class) \
    FindTypeAndClass(d, type, class, ValuatorClass, _deviceMotionNotify)

#define DeviceFocusIn(d, type, class) \
    FindTypeAndClass(d, type, class, FocusClass, _deviceFocusIn)

#define DeviceFocusOut(d, type, class) \
    FindTypeAndClass(d, type, class, FocusClass, _deviceFocusOut)

#define ProximityIn(d, type, class) \
    FindTypeAndClass(d, type, class, ProximityClass, _proximityIn)

#define ProximityOut(d, type, class) \
    FindTypeAndClass(d, type, class, ProximityClass, _proximityOut)

#define DeviceStateNotify(d, type, class) \
    FindTypeAndClass(d, type, class, OtherClass, _deviceStateNotify)

#define DeviceMappingNotify(d, type, class) \
    FindTypeAndClass(d, type, class, OtherClass, _deviceMappingNotify)

#define ChangeDeviceNotify(d, type, class) \
    FindTypeAndClass(d, type, class, OtherClass, _changeDeviceNotify)

#define DevicePointerMotionHint(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _devicePointerMotionHint;}

#define DeviceButton1Motion(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButton1Motion;}

#define DeviceButton2Motion(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButton2Motion;}

#define DeviceButton3Motion(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButton3Motion;}

#define DeviceButton4Motion(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButton4Motion;}

#define DeviceButton5Motion(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButton5Motion;}

#define DeviceButtonMotion(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButtonMotion;}

#define DeviceOwnerGrabButton(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceOwnerGrabButton;}

#define DeviceButtonPressGrab(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _deviceButtonGrab;}

#define NoExtensionEvent(d, type, class) \
    { class =  ((XDevice *) d)-&gt;device_id &lt;&lt; 8 | _noExtensionEvent;}

#define BadDevice(dpy, error) _xibaddevice(dpy, &amp;error)

#define BadClass(dpy, error) _xibadclass(dpy, &amp;error)

#define BadEvent(dpy, error) _xibadevent(dpy, &amp;error)

#define BadMode(dpy, error) _xibadmode(dpy, &amp;error)

#define DeviceBusy(dpy, error) _xidevicebusy(dpy, &amp;error)

/***************************************************************
 *
 * DeviceKey events.  These events are sent by input devices that
 * support input class Keys.
 * The location of the X pointer is reported in the coordinate
 * fields of the x,y and x_root,y_root fields.
 *
 */

typedef struct 
    {
    int            type;         /* of event */
    unsigned long  serial;       /* # of last request processed */
    Bool           send_event;   /* true if from SendEvent request */
    Display        *display;     /* Display the event was read from */
    Window         window;       /* "event" window reported relative to */
    XID            deviceid;
    Window         root;         /* root window event occurred on */
    Window         subwindow;    /* child window */
    Time           time;         /* milliseconds */
    int            x, y;         /* x, y coordinates in event window */
    int            x_root;       /* coordinates relative to root */
    int            y_root;       /* coordinates relative to root */
    unsigned int   state;        /* key or button mask */
    unsigned int   keycode;      /* detail */
    Bool           same_screen;  /* same screen flag */
    unsigned int   device_state; /* device key or button mask */
    unsigned char  axes_count;
    unsigned char  first_axis;
    int            axis_data[6];
    } XDeviceKeyEvent;

typedef XDeviceKeyEvent XDeviceKeyPressedEvent;
typedef XDeviceKeyEvent XDeviceKeyReleasedEvent;

/*******************************************************************
 *
 * DeviceButton events.  These events are sent by extension devices
 * that support input class Buttons.
 *
 */

typedef struct {
    int           type;         /* of event */
    unsigned long serial;       /* # of last request processed by server */
    Bool          send_event;   /* true if from a SendEvent request */
    Display       *display;     /* Display the event was read from */
    Window        window;       /* "event" window reported relative to */
    XID           deviceid;
    Window        root;         /* root window that the event occurred on */
    Window        subwindow;    /* child window */
    Time          time;         /* milliseconds */
    int           x, y;         /* x, y coordinates in event window */
    int           x_root;       /* coordinates relative to root */
    int           y_root;       /* coordinates relative to root */
    unsigned int  state;        /* key or button mask */
    unsigned int  button;       /* detail */
    Bool          same_screen;  /* same screen flag */
    unsigned int  device_state; /* device key or button mask */
    unsigned char axes_count;
    unsigned char first_axis;
    int           axis_data[6];
    } XDeviceButtonEvent;

typedef XDeviceButtonEvent XDeviceButtonPressedEvent;
typedef XDeviceButtonEvent XDeviceButtonReleasedEvent;

/*******************************************************************
 *
 * DeviceMotionNotify event.  These events are sent by extension devices
 * that support input class Valuators.
 *
 */

typedef struct 
    {
    int           type;        /* of event */
    unsigned long serial;      /* # of last request processed by server */
    Bool          send_event;  /* true if from a SendEvent request */
    Display       *display;    /* Display the event was read from */
    Window        window;      /* "event" window reported relative to */
    XID           deviceid;
    Window        root;        /* root window that the event occurred on */
    Window        subwindow;   /* child window */
    Time          time;        /* milliseconds */
    int           x, y;        /* x, y coordinates in event window */
    int           x_root;      /* coordinates relative to root */
    int           y_root;      /* coordinates relative to root */
    unsigned int  state;       /* key or button mask */
    char          is_hint;     /* detail */
    Bool          same_screen; /* same screen flag */
    unsigned int  device_state; /* device key or button mask */
    unsigned char axes_count;
    unsigned char first_axis;
    int           axis_data[6];
    } XDeviceMotionEvent;

/*******************************************************************
 *
 * DeviceFocusChange events.  These events are sent when the focus
 * of an extension device that can be focused is changed.
 *
 */

typedef XDeviceFocusChangeEvent XDeviceFocusInEvent;
typedef XDeviceFocusChangeEvent XDeviceFocusOutEvent;

/*******************************************************************
 *
 * ProximityNotify events.  These events are sent by those absolute
 * positioning devices that are capable of generating proximity information.
 *
 */

typedef struct 
    {
    int             type;      /* ProximityIn or ProximityOut */        
    unsigned long   serial;    /* # of last request processed by server */
    Bool            send_event; /* true if this came from a SendEvent request */
    Display         *display;  /* Display the event was read from */
    Window          window;      
    XID                 deviceid;
    Window          root;            
    Window          subwindow;      
    Time            time;            
    int             x, y;            
    int             x_root, y_root;  
    unsigned int    state;           
    Bool            same_screen;     
    unsigned int    device_state; /* device key or button mask */
    unsigned char   axes_count;
    unsigned char   first_axis;
    int             axis_data[6];
    } XProximityNotifyEvent;
typedef XProximityNotifyEvent XProximityInEvent;
typedef XProximityNotifyEvent XProximityOutEvent;

/*******************************************************************
 *
 * DeviceStateNotify events are generated on EnterWindow and FocusIn 
 * for those clients who have selected DeviceState.
 *
 */

typedef struct
    {
    unsigned char     class;
    unsigned char     length;
    } XInputClass;

typedef struct {
    unsigned char     class;
    unsigned char     length;
    unsigned char     num_valuators;
    unsigned char     mode;
    int                  valuators[6];
} XValuatorStatus;

typedef struct {
    unsigned char     class;
    unsigned char     length;
    short          num_keys;
    char             keys[32];
} XKeyStatus;

typedef struct {
    unsigned char     class;
    unsigned char     length;
    short          num_buttons;
    char             buttons[32];
} XButtonStatus;

/*******************************************************************
 *
 * DeviceMappingNotify event.  This event is sent when the key mapping,
 * modifier mapping, or button mapping of an extension device is changed.
 *
 */

typedef struct {
    int           type;
    unsigned long serial;       /* # of last request processed by server */
    Bool          send_event;   /* true if this came from a SendEvent request */
    Display       *display;     /* Display the event was read from */
    Window        window;       /* unused */
    XID           deviceid;
    Time          time;
    int           request;      /* one of MappingModifier, MappingKeyboard,
                                    MappingPointer */
    int           first_keycode;/* first keycode */
    int           count;        /* defines range of change w. first_keycode*/
} XDeviceMappingEvent;

/*******************************************************************
 *
 * ChangeDeviceNotify event.  This event is sent when an 
 * XChangeKeyboard or XChangePointer request is made.
 *
 */

typedef struct {
    int           type;
    unsigned long serial;       /* # of last request processed by server */
    Bool          send_event;   /* true if this came from a SendEvent request */
    Display       *display;     /* Display the event was read from */
    Window        window;       /* unused */
    XID           deviceid;
    Time          time;
    int           request;      /* NewPointer or NewKeyboard */
} XChangeDeviceNotifyEvent;

/*******************************************************************
 *
 * Control structures for input devices that support input class
 * Feedback.  These are used by the XGetFeedbackControl and 
 * XChangeFeedbackControl functions.
 *
 */

typedef struct {
     XID            class;
     int            length;
     XID            id;
} XFeedbackState;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     click;
    int     percent;
    int     pitch;
    int     duration;
    int     led_mask;
    int     global_auto_repeat;
    char    auto_repeats[32];
} XKbdFeedbackState;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     accelNum;
    int     accelDenom;
    int     threshold;
} XPtrFeedbackState;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     resolution;
    int     minVal;
    int     maxVal;
} XIntegerFeedbackState;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     max_symbols;
    int     num_syms_supported;
    KeySym  *syms_supported;
} XStringFeedbackState;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     percent;
    int     pitch;
    int     duration;
} XBellFeedbackState;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     led_values;
    int     led_mask;
} XLedFeedbackState;

typedef struct {
     XID            class;
     int            length;
     XID         id;
} XFeedbackControl;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     accelNum;
    int     accelDenom;
    int     threshold;
} XPtrFeedbackControl;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     click;
    int     percent;
    int     pitch;
    int     duration;
    int     led_mask;
    int     led_value;
    int     key;
    int     auto_repeat_mode;
} XKbdFeedbackControl;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     num_keysyms;
    KeySym  *syms_to_display;
} XStringFeedbackControl;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     int_to_display;
} XIntegerFeedbackControl;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     percent;
    int     pitch;
    int     duration;
} XBellFeedbackControl;

typedef struct {
    XID     class;
    int     length;
    XID     id;
    int     led_mask;
    int     led_values;
} XLedFeedbackControl;

/*******************************************************************
 *
 * Device control structures.
 *
 */

typedef struct {
     XID            control;
     int            length;
} XDeviceControl;

typedef struct {
     XID            control;
     int            length;
     int            first_valuator;
     int            num_valuators;
     int            *resolutions;
} XDeviceResolutionControl;

typedef struct {
     XID            control;
     int            length;
     int            num_valuators;
     int            *resolutions;
     int            *min_resolutions;
     int            *max_resolutions;
} XDeviceResolutionState;

/*******************************************************************
 *
 * An array of XDeviceList structures is returned by the 
 * XListInputDevices function.  Each entry contains information
 * about one input device.  Among that information is an array of 
 * pointers to structures that describe the characteristics of 
 * the input device.
 *
 */

typedef struct _XAnyClassinfo *XAnyClassPtr;

typedef struct _XAnyClassinfo {
    XID      class;
    int      length;
    } XAnyClassInfo;

typedef struct _XDeviceInfo *XDeviceInfoPtr;

typedef struct _XDeviceInfo
    {
    XID                 id;        
    Atom                type;
    char                *name;
    int                 num_classes;
    int                 use;
    XAnyClassPtr      inputclassinfo;
    } XDeviceInfo;

typedef struct _XKeyInfo *XKeyInfoPtr;

typedef struct _XKeyInfo
    {
    XID               class;
    int               length;
    unsigned short      min_keycode;
    unsigned short      max_keycode;
    unsigned short      num_keys;
    } XKeyInfo;

typedef struct _XButtonInfo *XButtonInfoPtr;

typedef struct _XButtonInfo {
    XID          class;
    int          length;
    short      num_buttons;
    } XButtonInfo;

typedef struct _XAxisInfo *XAxisInfoPtr;

typedef struct _XAxisInfo {
    int      resolution;
    int      min_value;
    int      max_value;
    } XAxisInfo;

typedef struct _XValuatorInfo *XValuatorInfoPtr;

typedef struct     _XValuatorInfo
    {
    XID               class;
    int               length;
    unsigned char       num_axes;
    unsigned char       mode;
    unsigned long       motion_buffer;
    XAxisInfoPtr        axes;
    } XValuatorInfo;

/*******************************************************************
 *
 * An XDevice structure is returned by the XOpenDevice function.  
 * It contains an array of pointers to XInputClassInfo structures.
 * Each contains information about a class of input supported by the
 * device, including a pointer to an array of data for each type of event
 * the device reports.
 *
 */

typedef struct {
        unsigned char   input_class;
        unsigned char   event_type_base;
} XInputClassInfo;

typedef struct {
        XID                    device_id;
        int                    num_classes;
        XInputClassInfo        *classes;
} XDevice;

/*******************************************************************
 *
 * The following structure is used to return information for the 
 * XGetSelectedExtensionEvents function.
 *
 */

typedef struct {
        XEventClass     event_type;
        XID             device;
} XEventList;

/*******************************************************************
 *
 * The following structure is used to return motion history data from 
 * an input device that supports the input class Valuators.
 * This information is returned by the XGetDeviceMotionEvents function.
 *
 */

typedef struct {
        Time   time;
        int    *data;
} XDeviceTimeCoord;

/*******************************************************************
 *
 * Device state structure.
 * This is returned by the XQueryDeviceState request.
 *
 */

typedef struct {
        XID          device_id;
        int          num_classes;
        XInputClass     *data;
} XDeviceState;

/*******************************************************************
 *
 * Note that the mode field is a bitfield that reports the Proximity
 * status of the device as well as the mode.  The mode field should
 * be OR'd with the mask DeviceMode and compared with the values
 * Absolute and Relative to determine the mode, and should be OR'd
 * with the mask ProximityState and compared with the values InProximity
 * and OutOfProximity to determine the proximity state.
 *
 */

typedef struct {
    unsigned char     class;
    unsigned char     length;
    unsigned char     num_valuators;
    unsigned char     mode;
    int                  *valuators;
} XValuatorState;

typedef struct {
    unsigned char     class;
    unsigned char     length;
    short          num_keys;
    char             keys[32];
} XKeyState;

typedef struct {
    unsigned char     class;
    unsigned char     length;
    short          num_buttons;
    char             buttons[32];
} XButtonState;

/*******************************************************************
 *
 * Function definitions.
 *
 */

_XFUNCPROTOBEGIN

extern int     XChangeKeyboardDevice(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */
#endif
);

extern int     XChangePointerDevice(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int               /* xaxis */,
    int               /* yaxis */
#endif
);

extern int     XGrabDevice(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    Window          /* grab_window */,
    Bool          /* ownerEvents */,
    int               /* event count */,
    XEventClass*     /* event_list */,
    int               /* this_device_mode */,
    int               /* other_devices_mode */,
    Time          /* time */
#endif
);

extern int     XUngrabDevice(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    Time           /* time */
#endif
);

extern int     XGrabDeviceKey(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned int     /* key */,
    unsigned int     /* modifiers */,
    XDevice*          /* modifier_device */,
    Window          /* grab_window */,
    Bool          /* owner_events */,
    unsigned int     /* event_count */,
    XEventClass*     /* event_list */,
    int               /* this_device_mode */,
    int               /* other_devices_mode */
#endif
);

extern int     XUngrabDeviceKey(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned int     /* key */,
    unsigned int     /* modifiers */,
    XDevice*          /* modifier_dev */,
    Window          /* grab_window */
#endif
);

extern int     XGrabDeviceButton(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned int     /* button */,
    unsigned int     /* modifiers */,
    XDevice*          /* modifier_device */,
    Window          /* grab_window */,
    Bool          /* owner_events */,
    unsigned int     /* event_count */,
    XEventClass*     /* event_list */,
    int               /* this_device_mode */,
    int               /* other_devices_mode */
#endif
);

extern int     XUngrabDeviceButton(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned int     /* button */,
    unsigned int     /* modifiers */,
    XDevice*          /* modifier_dev */,
    Window          /* grab_window */
#endif
);

extern int     XAllowDeviceEvents(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int               /* event_mode */,
    Time          /* time */
#endif
);

extern int     XGetDeviceFocus(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    Window*          /* focus */,
    int*          /* revert_to */,
    Time*          /* time */
#endif
);

extern int     XSetDeviceFocus(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    Window          /* focus */,
    int               /* revert_to */,
    Time          /* time */
#endif
);

extern XFeedbackState     *XGetFeedbackControl(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int*          /* num_feedbacks */
#endif
);

extern int     XFreeFeedbackList(
#if NeedFunctionPrototypes
    XFeedbackState*     /* list */
#endif
);

extern int     XChangeFeedbackControl(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned long     /* mask */,
    XFeedbackControl*     /* f */
#endif
);

extern int     XDeviceBell(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    XID               /* feedbackclass */,
    XID               /* feedbackid */,
    int               /* percent */
#endif
);

extern KeySym     *XGetDeviceKeyMapping(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
#if NeedWidePrototypes
    unsigned int     /* first */,
#else
    KeyCode          /* first */,
#endif
    int               /* keycount */,
    int*          /* syms_per_code */
#endif
);

extern int     XChangeDeviceKeyMapping(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int               /* first */,
    int               /* syms_per_code */,
    KeySym*          /* keysyms */,
    int               /* count */
#endif
);

extern XModifierKeymap     *XGetDeviceModifierMapping(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */
#endif
);

extern int     XSetDeviceModifierMapping(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    XModifierKeymap*     /* modmap */
#endif
);

extern int     XSetDeviceButtonMapping(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned char*     /* map[] */,
    int               /* nmap */
#endif
);

extern int     XGetDeviceButtonMapping(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    unsigned char*     /* map[] */,
    unsigned int     /* nmap */
#endif
);

extern XDeviceState     *XQueryDeviceState(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */
#endif
);

extern int     XFreeDeviceState(
#if NeedFunctionPrototypes
    XDeviceState*     /* list */
#endif
);

extern XExtensionVersion *XGetExtensionVersion(
#if NeedFunctionPrototypes
    Display*          /* display */,
    _Xconst char*     /* name */
#endif
);

extern XDeviceInfo     *XListInputDevices(
#if NeedFunctionPrototypes
    Display*          /* display */,
    int*          /* ndevices */
#endif
);

extern int     XFreeDeviceList(
#if NeedFunctionPrototypes
    XDeviceInfo*     /* list */
#endif
);

extern XDevice     *XOpenDevice(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XID               /* id */
#endif
);

extern int     XCloseDevice(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */
#endif
);

extern int     XSetDeviceMode(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int               /* mode */
#endif
);

extern int     XSetDeviceValuators(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int*          /* valuators */,
    int               /* first_valuator */,
    int               /* num_valuators */
#endif
);

extern XDeviceControl     *XGetDeviceControl(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int               /* control */
#endif
);

extern int     XChangeDeviceControl(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    int               /* control */,
    XDeviceControl*     /* d */
#endif
);

extern int     XSelectExtensionEvent(
#if NeedFunctionPrototypes
    Display*          /* display */,
    Window          /* w */,
    XEventClass*     /* event_list */,
    int               /* count */
#endif
);

extern int     XGetSelectedExtensionEvents(
#if NeedFunctionPrototypes
    Display*          /* display */,
    Window          /* w */,
    int*          /* this_client_count */,
    XEventClass**     /* this_client_list */,
    int*          /* all_clients_count */,
    XEventClass**     /* all_clients_list */
#endif
);

extern int     XChangeDeviceDontPropagateList(
#if NeedFunctionPrototypes
    Display*          /* display */,
    Window          /* window */,
    int               /* count */,
    XEventClass*     /* events */,
    int               /* mode */
#endif
);

extern XEventClass     *XGetDeviceDontPropagateList(
#if NeedFunctionPrototypes
    Display*          /* display */,
    Window          /* window */,
    int*          /* count */
#endif
);

extern Status     XSendExtensionEvent(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    Window          /* dest */,
    Bool          /* prop */,
    int               /* count */,
    XEventClass*     /* list */,
    XEvent*          /* event */
#endif
);

extern XDeviceTimeCoord     *XGetDeviceMotionEvents(
#if NeedFunctionPrototypes
    Display*          /* display */,
    XDevice*          /* device */,
    Time          /* start */,
    Time          /* stop */,
    int*          /* nEvents */,
    int*          /* mode */,
    int*          /* axis_count */
#endif
);

extern int     XFreeDeviceMotionEvents(
#if NeedFunctionPrototypes
    XDeviceTimeCoord*     /* events */
#endif
);

extern int     XFreeDeviceControl(
#if NeedFunctionPrototypes
    XDeviceControl*     /* control */
#endif
);

_XFUNCPROTOEND

#endif /* _XINPUT_H_ */

/* Definitions used by the server, library and client */

#ifndef _XI_H_

#define _XI_H_

#define sz_xGetExtensionVersionReq          8
#define sz_xGetExtensionVersionReply          32
#define sz_xListInputDevicesReq               4
#define sz_xListInputDevicesReply          32
#define sz_xOpenDeviceReq               8
#define sz_xOpenDeviceReply               32
#define sz_xCloseDeviceReq               8
#define sz_xSetDeviceModeReq               8
#define sz_xSetDeviceModeReply               32
#define sz_xSelectExtensionEventReq          12
#define sz_xGetSelectedExtensionEventsReq     8
#define sz_xGetSelectedExtensionEventsReply     32
#define sz_xChangeDeviceDontPropagateListReq     12
#define sz_xGetDeviceDontPropagateListReq     8
#define sz_xGetDeviceDontPropagateListReply     32
#define sz_xGetDeviceMotionEventsReq          16
#define sz_xGetDeviceMotionEventsReply          32
#define sz_xChangeKeyboardDeviceReq          8
#define sz_xChangeKeyboardDeviceReply          32
#define sz_xChangePointerDeviceReq          8
#define sz_xChangePointerDeviceReply          32
#define sz_xGrabDeviceReq               20
#define sz_xGrabDeviceReply               32
#define sz_xUngrabDeviceReq               12
#define sz_xGrabDeviceKeyReq               20
#define sz_xGrabDeviceKeyReply               32
#define sz_xUngrabDeviceKeyReq               16
#define sz_xGrabDeviceButtonReq               20
#define sz_xGrabDeviceButtonReply          32
#define sz_xUngrabDeviceButtonReq          16
#define sz_xAllowDeviceEventsReq          12
#define sz_xGetDeviceFocusReq               8
#define sz_xGetDeviceFocusReply               32
#define sz_xSetDeviceFocusReq               16
#define sz_xGetFeedbackControlReq          8
#define sz_xGetFeedbackControlReply          32
#define sz_xChangeFeedbackControlReq          12
#define sz_xGetDeviceKeyMappingReq          8
#define sz_xGetDeviceKeyMappingReply          32
#define sz_xChangeDeviceKeyMappingReq          8
#define sz_xGetDeviceModifierMappingReq          8
#define sz_xSetDeviceModifierMappingReq          8
#define sz_xSetDeviceModifierMappingReply     32
#define sz_xGetDeviceButtonMappingReq          8
#define sz_xGetDeviceButtonMappingReply          32
#define sz_xSetDeviceButtonMappingReq          8
#define sz_xSetDeviceButtonMappingReply          32
#define sz_xQueryDeviceStateReq               8
#define sz_xQueryDeviceStateReply          32
#define sz_xSendExtensionEventReq          16
#define sz_xDeviceBellReq               8
#define sz_xSetDeviceValuatorsReq          8
#define sz_xSetDeviceValuatorsReply          32
#define sz_xGetDeviceControlReq               8
#define sz_xGetDeviceControlReply          32
#define sz_xChangeDeviceControlReq          8
#define sz_xChangeDeviceControlReply          32

#define INAME                "XInputExtension"

#define XI_KEYBOARD     "KEYBOARD"
#define XI_MOUSE     "MOUSE"
#define XI_TABLET     "TABLET"
#define XI_TOUCHSCREEN     "TOUCHSCREEN"
#define XI_TOUCHPAD     "TOUCHPAD"
#define XI_BARCODE     "BARCODE"
#define XI_BUTTONBOX     "BUTTONBOX"
#define XI_KNOB_BOX     "KNOB_BOX"
#define XI_ONE_KNOB     "ONE_KNOB"
#define XI_NINE_KNOB     "NINE_KNOB"
#define XI_TRACKBALL     "TRACKBALL"
#define XI_QUADRATURE     "QUADRATURE"
#define XI_ID_MODULE     "ID_MODULE"
#define XI_SPACEBALL     "SPACEBALL"
#define XI_DATAGLOVE     "DATAGLOVE"
#define XI_EYETRACKER     "EYETRACKER"
#define XI_CURSORKEYS     "CURSORKEYS"
#define XI_FOOTMOUSE     "FOOTMOUSE"

#define Dont_Check               0
#define XInput_Initial_Release          1
#define XInput_Add_XDeviceBell          2
#define XInput_Add_XSetDeviceValuators     3
#define XInput_Add_XChangeDeviceControl     4

#define XI_Absent          0
#define XI_Present          1

#define XI_Initial_Release_Major          1
#define XI_Initial_Release_Minor          0

#define XI_Add_XDeviceBell_Major          1
#define XI_Add_XDeviceBell_Minor          1

#define XI_Add_XSetDeviceValuators_Major     1
#define XI_Add_XSetDeviceValuators_Minor     2

#define XI_Add_XChangeDeviceControl_Major     1
#define XI_Add_XChangeDeviceControl_Minor     3

#define DEVICE_RESOLUTION     1

#define NoSuchExtension          1

#define COUNT               0
#define CREATE               1

#define NewPointer          0
#define NewKeyboard          1

#define XPOINTER          0
#define XKEYBOARD          1

#define UseXKeyboard          0xFF

#define IsXPointer          0
#define IsXKeyboard          1
#define IsXExtensionDevice     2

#define AsyncThisDevice          0
#define SyncThisDevice          1
#define ReplayThisDevice     2
#define AsyncOtherDevices     3
#define AsyncAll          4
#define SyncAll               5

#define FollowKeyboard           3
#define RevertToFollowKeyboard      3

#define DvAccelNum              (1L &lt;&lt; 0)
#define DvAccelDenom            (1L &lt;&lt; 1)
#define DvThreshold             (1L &lt;&lt; 2)

#define DvKeyClickPercent     (1L&lt;&lt;0)
#define DvPercent          (1L&lt;&lt;1)
#define DvPitch               (1L&lt;&lt;2)
#define DvDuration          (1L&lt;&lt;3)
#define DvLed               (1L&lt;&lt;4)
#define DvLedMode          (1L&lt;&lt;5)
#define DvKey               (1L&lt;&lt;6)
#define DvAutoRepeatMode     (1L&lt;&lt;7)

#define DvString                (1L &lt;&lt; 0)

#define DvInteger               (1L &lt;&lt; 0)

#define DeviceMode              (1L &lt;&lt; 0)
#define Relative                0
#define Absolute                1

#define ProximityState          (1L &lt;&lt; 1)
#define InProximity             (0L &lt;&lt; 1)
#define OutOfProximity          (1L &lt;&lt; 1)

#define AddToList               0
#define DeleteFromList          1

#define KeyClass            0
#define ButtonClass            1
#define ValuatorClass            2
#define FeedbackClass            3
#define ProximityClass       4
#define FocusClass            5
#define OtherClass            6

#define KbdFeedbackClass       0
#define PtrFeedbackClass       1
#define StringFeedbackClass       2
#define IntegerFeedbackClass       3
#define LedFeedbackClass       4
#define BellFeedbackClass       5

#define _devicePointerMotionHint 0
#define _deviceButton1Motion      1
#define _deviceButton2Motion      2
#define _deviceButton3Motion      3
#define _deviceButton4Motion      4
#define _deviceButton5Motion      5
#define _deviceButtonMotion      6
#define _deviceButtonGrab      7
#define _deviceOwnerGrabButton      8
#define _noExtensionEvent      9

#define XI_BadDevice     0
#define XI_BadEvent     1
#define XI_BadMode     2
#define XI_DeviceBusy     3
#define XI_BadClass     4

typedef     unsigned long     XEventClass;

/*******************************************************************
 *
 * Extension version structure.
 *
 */

typedef struct {
        int        present;
        short     major_version;
        short     minor_version;
} XExtensionVersion;

#endif /* _XI_H_ */

</pre><p>

</p></div></div></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="Input_Extension_Protocol_Encoding"></a>Appendix A. Input Extension Protocol Encoding</h1></div></div></div><p>
<code class="function">Syntactic Conventions</code>
</p><p>

All numbers are in decimal, 
unless prefixed with #x, in which case they are in hexadecimal (base 16).
</p><p>

The general syntax used to describe requests, replies, errors, events, and
compound types is:
</p><p>

</p><pre class="literallayout">
<code class="function">NameofThing</code>
  encode-form
  ...
  encode-form
</pre><p>
Each encode-form describes a single component.
</p><p>

For components described in the protocol as:
</p><p>

</p><pre class="literallayout">
name: TYPE
</pre><p>
the encode-form is:
</p><p>

</p><pre class="literallayout">

N	TYPE	name
</pre><p>
N is the number of bytes occupied in the data stream, 
and TYPE is the interpretation of those bytes.
For example,
</p><p>

</p><pre class="literallayout">

depth: CARD8
</pre><p>
becomes:
</p><p>

</p><pre class="literallayout">

1	CARD8	depth
</pre><p>
For components with a static numeric value the encode-form is:
</p><p>

</p><pre class="literallayout">

N	value	name
</pre><p>
The value is always interpreted as an N-byte unsigned integer.
For example, 
the first two bytes of a Window error are always zero (indicating an
error in general) and three (indicating the Window error in particular):
</p><p>

</p><pre class="literallayout">

1	0	Error
1	3	code
</pre><p>
For components described in the protocol as:
</p><p>

</p><pre class="literallayout">
name: <code class="function">{Name1, ..., NameI}</code>
</pre><p>
</p><p>

the encode-form is:
</p><p>

</p><pre class="literallayout">

N		name
	value1 Name1
	...
	valueI NameI
</pre><p>
The value is always interpreted as an N-byte unsigned integer.
Note that the size of N is sometimes larger than that strictly required 
to encode the values.
For example:
</p><p>

</p><pre class="literallayout">
class: <code class="function">{InputOutput, InputOnly, CopyFromParent}</code>
</pre><p>
</p><p>

becomes:
</p><p>

</p><pre class="literallayout">

2			class
	0	CopyFromParent
	1	InputOutput
	2	InputOnly
</pre><p>
For components described in the protocol as:
</p><p>

</p><pre class="literallayout">
NAME: TYPE or <code class="function">Alternative1 ... or AlternativeI</code>
</pre><p>
</p><p>

the encode-form is:
</p><p>

</p><pre class="literallayout">

N	TYPE			NAME
	value1	Alternative1
	...
	valueI	AlternativeI
</pre><p>
The alternative values are guaranteed not to conflict with the encoding
of TYPE.  
For example:
</p><p>

</p><pre class="literallayout">
destination: WINDOW or <code class="function">PointerWindow</code> or <code class="function">InputFocus</code>
</pre><p>
</p><p>

becomes:
</p><p>

</p><pre class="literallayout">

4	WINDOW		destination
	0	PointerWindow
	1	InputFocus
</pre><p>
For components described in the protocol as:
</p><p>

</p><pre class="literallayout">

value-mask: BITMASK
</pre><p>
the encode-form is:
</p><p>

</p><pre class="literallayout">

N	BITMASK			value-mask
	mask1	mask-name1
	...
	maskI	mask-nameI
</pre><p>
The individual bits in the mask are specified and named, 
and N is 2 or 4.
The most-significant bit in a BITMASK is reserved for use in defining
chained (multiword) bitmasks, as extensions augment existing core requests.
The precise interpretation of this bit is not yet defined here, 
although a probable mechanism is that a 1-bit indicates that another N bytes 
of bitmask follows, with bits within the overall mask still interpreted 
from least-significant to most-significant with an N-byte unit, with N-byte units 
interpreted in stream order, and with the overall mask being byte-swapped 
in individual N-byte units.
</p><p>

For LISTofVALUE encodings, the request is followed by a section of the form:
</p><p>

</p><pre class="literallayout">

VALUEs
 encode-form
 ...
 encode-form
</pre><p>
listing an encode-form for each VALUE.
The NAME in each encode-form keys to the corresponding BITMASK bit.
The encoding of a VALUE always occupies four bytes, 
but the number of bytes specified in the encoding-form indicates how
many of the least-significant bytes are actually used; 
the remaining bytes are unused and their values do not matter.
</p><p>

In various cases, the number of bytes occupied by a component will be specified
by a lowercase single-letter variable name instead of a specific numeric
value, and often some other component will have its value specified as a
simple numeric expression involving these variables.
Components specified with such expressions are always interpreted 
as unsigned integers.
The scope of such variables is always just the enclosing request, reply, 
error, event, or compound type structure.
For example:
</p><p>

</p><pre class="literallayout">

2	3+n			request length
4n	LISTofPOINT		points
</pre><p>
For unused bytes (the values of the bytes are undefined and do not matter),
the encode-form is:
</p><p>

</p><pre class="literallayout">

N			unused
</pre><p>
If the number of unused bytes is variable, the encode-form typically is:
</p><p>

</p><pre class="literallayout">

p			unused, p=pad(E)
</pre><p>
where E is some expression,
and pad(E) is the number of bytes needed to round E up to a multiple of four.
</p><p>

</p><pre class="literallayout">

pad(E) = (4 - (E mod 4)) mod 4
</pre><p>

<code class="function">Common Types</code>

</p><p>

LISTofFOO
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
In this document the LISTof notation strictly means some number of repetitions
of the FOO encoding; 
the actual length of the list is encoded elsewhere.
    </p></li></ul></div><p>

SETofFOO
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A set is always represented by a bitmask, with a 1-bit indicating presence in
the set.
    </p></li></ul></div><p>

BITMASK: CARD32
</p><p>

WINDOW: CARD32
</p><p>

BYTE: 8-bit value
</p><p>

INT8: 8-bit signed integer
</p><p>

INT16: 16-bit signed integer
</p><p>

INT32: 32-bit signed integer
</p><p>

CARD8: 8-bit unsigned integer
</p><p>

CARD16: 16-bit unsigned integer
</p><p>

CARD32: 32-bit unsigned integer
</p><p>

TIMESTAMP: CARD32
</p><p>

EVENTCLASS: CARD32
</p><p>

</p><pre class="literallayout">

INPUTCLASS
	0	KeyClass
	1	ButtonClass
	2	ValuatorClass
	3	FeedbackClass
	4	ProximityClass
	5	FocusClass
	6	OtherClass
</pre><p>
</p><p>

</p><pre class="literallayout">

INPUTCLASS
	0	KbdFeedbackClass
	1	PtrFeedbackClass
	2	StringFeedbackClass
	3	IntegerFeedbackClass
	4	LedFeedbackClass
	5	BellFeedbackClass
</pre><p>
</p><p>

</p><pre class="literallayout">

INPUTINFO
	0	KEYINFO
	1	BUTTONINFO
	2	VALUATORINFO
</pre><p>
</p><p>

</p><pre class="literallayout">

DEVICEMODE
	0	Relative
	1	Absolute
</pre><p>
</p><p>

</p><pre class="literallayout">

PROXIMITYSTATE
	0	InProximity
	1	OutOfProximity
</pre><p>
</p><p>

</p><pre class="literallayout">

BOOL
	0	False
	1	True
</pre><p>
</p><p>

KEYSYM: CARD32
</p><p>

KEYCODE: CARD8
</p><p>

BUTTON: CARD8
</p><p>

</p><pre class="literallayout">

SETofKEYBUTMASK
	#x0001	Shift
	#x0002	Lock
	#x0004	Control
	#x0008	Mod1
	#x0010	Mod2
	#x0020	Mod3
	#x0040	Mod4
	#x0080	Mod5
	#x0100	Button1
	#x0200	Button2
	#x0400	Button3
	#x0800	Button4
	#x1000	Button5
	#xe000	unused but must be zero
</pre><p>
</p><p>

</p><pre class="literallayout">

SETofKEYMASK
	encodings are the same as for SETofKEYBUTMASK, except with
	#xff00		unused but must be zero
</pre><p>
</p><p>

STRING8: LISTofCARD8
</p><p>

</p><pre class="literallayout">

STR
	1	n		length of name in bytes
	n	STRING8		name
</pre><p>

<code class="function">Errors</code>

</p><p>

</p><pre class="literallayout">

Request
	1	0		Error
	1	1		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Value
	1	0		Error
	1	2		code
	2	CARD16		sequence number
	4	&lt;32-bits&gt;		bad value
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Window
	1	0		Error
	1	3		code
	2	CARD16		sequence number
	4	CARD32		bad resource id
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Match
	1	0		Error
	1	8		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Access
	1	0		Error
	1	10		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Alloc
	1	0		Error
	1	11		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Name
	1	0		Error
	1	15		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Device
	1	0		Error
	1	CARD8		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Event
	1	0		Error
	1	CARD8		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Mode
	1	0		Error
	1	CARD8		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

Class
	1	0		Error
	1	CARD8		code
	2	CARD16		sequence number
	4			unused
	2	CARD16		minor opcode
	1	CARD8		major opcode
	21			unused
</pre><p>

Keyboards

</p><p>

KEYCODE values are always greater than 7 (and less than 256).
</p><p>

KEYSYM values with the bit #x10000000 set are reserved as vendor-specific.
</p><p>

The names and encodings of the standard KEYSYM values are contained in

appendix F.
</p><p>

Pointers

</p><p>

BUTTON values are numbered starting with one.
</p><p>

Requests

</p><p>

</p><pre class="literallayout">

GetExtensionVersion
	1	CARD8		input extension opcode
	1	1		GetExtensionVersion opcode
	2	2+(n+p)/4		request length
	2	n		length of name
	2			unused
	n	STRING8		name
	p			unused, p=pad(n)
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	1		GetExtensionVersion opcode
	2	CARD16		sequence number
	4	0		reply length
	2	CARD16		major version
	2	CARD16		minor version
	1	BOOL		present
	19			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

ListInputDevices
	1	CARD8		input extension opcode
	1	2		ListInputDevices opcode
	2	1		request length
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	2			ListInputDevices opcode
	2	CARD16			sequence number
	4	(n+p)/4			reply length
	1	CARD8			number of input devices
	23				unused
	n	LISTofDEVICEINFO	info for each input device
	p				unused, p=pad(n)
</pre><p>
</p><p>

</p><pre class="literallayout">

DEVICEINFO
	4	CARD32		device type
	1	CARD8		device id
	1	CARD8		number of input classes this device reports
	1	CARD8		device use
			0	IsXPointer
			1	IsXKeyboard
			2	IsXExtensionDevice
	1			unused
	n	LISTofINPUTINFO 		input info for each input class
	m	STR			name
	p				unused, p=pad(m)
</pre><p>
</p><p>

</p><pre class="literallayout">

INPUTINFO	KEYINFO or BUTTONINFO or VALUATORINFO
</pre><p>
</p><p>

</p><pre class="literallayout">

KEYINFO
	1	0		class id
	1	8		length
	1	KEYCODE		minimum keycode
	1	KEYCODE		maximum keycode
	2	CARD16		number of keys
	2			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

BUTTONINFO
	1	1		class id
	1	4		length
	2	CARD16		number of buttons
</pre><p>
</p><p>

</p><pre class="literallayout">

VALUATORINFO
	1	2		class id
	1	8+12n		length
	1	n		number of axes
	1	SETofDEVICEMODE			mode
	4	CARD32		size of motion buffer
	12n	LISTofAXISINFO		valuator limits
</pre><p>
</p><p>

</p><pre class="literallayout">

AXISINFO
	4	CARD32		resolution
	4	CARD32		minimum value
	4	CARD32		maximum value
</pre><p>
</p><p>

</p><pre class="literallayout">

OpenDevice
	1	CARD8		input extension opcode
	1	3		OpenDevice opcode
	2	2		request length
	1	CARD8		device id
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	3			OpenDevice opcode
	2	CARD16			sequence number
	4	(n+p)/4			reply length
	1	CARD8			number of input classes
	23				unused
	n	LISTofINPUTCLASSINFO	input class information
	p				unused, p=pad(n)
</pre><p>
</p><p>

</p><pre class="literallayout">

INPUTCLASSINFO
	1	CARD8		input class id
		0	KEY
		1	BUTTON
		2	VALUATOR
		3	FEEDBACK
		4	PROXIMITY
		5	FOCUS
		6	OTHER
	1	CARD8		event type base code for this class
</pre><p>
</p><p>

</p><pre class="literallayout">

CloseDevice
	1	CARD8		input extension opcode
	1	4		CloseDevice opcode
	2	2		request length
	1	CARD8		device id
	3			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

SetDeviceMode
	1	CARD8		input extension opcode
	1	5		SetDeviceMode opcode
	2	2		request length
	1	CARD8		device id
	1	CARD8		mode
	2			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	5			SetDeviceMode opcode
	2	CARD16			sequence number
	4	0			reply length
	1	CARD8			status
		0		Success
			1	AlreadyGrabbed
		3 + first_error	DeviceBusy
	23				unused
</pre><p>
</p><p>

</p><pre class="literallayout">

SelectExtensionEvent
	1	CARD8			input extension opcode
	1	6			SelectExtensionEvent opcode
	2	3+n				request length
	4	Window			event window
	2	CARD16			count
	2				unused
	4n	LISTofEVENTCLASS	desired events
</pre><p>
</p><p>

</p><pre class="literallayout">

GetSelectedExtensionEvents
	1	CARD8		input extension opcode
	1	7		GetSelectedExtensionEvents opcode
	2	2		request length
	4	Window		event window
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	7		GetSelecteExtensionEvents opcode
	2	CARD16		sequence number
	4	n + m  		reply length
	2	n     		this client count
	2	m     		all clients count
	20			unused
	4n	LISTofEVENTCLASS	this client list
	4m	LISTofEVENTCLASS	all clients list
</pre><p>
</p><p>

</p><pre class="literallayout">

ChangeDeviceDontPropagateList
	1	CARD8			input extension opcode
	1	8			ChangeDeviceDontPropagateList opcode
	2	3+n				request length
	4	Window			event window
	2	n			count of events
	1	mode
		0	AddToList
		1	DeleteFromList
	1				unused
	4n	LISTofEVENTCLASS	desired events
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceDontPropagateList
	1	CARD8		input extension opcode
	1	9		GetDeviceDontPropagateList opcode
	2	2		request length
	4	Window		event window
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	9			GetDeviceDontPropagateList opcode
	2	CARD16			sequence number
	4	n  			reply length
	2	n			count of events
	22				unused
	4n	LISTofEVENTCLASS	don't propagate list
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceMotionEvents
	1	CARD8		input extension opcode
	1	10		GetDeviceMotionEvents opcode
	2	4		request length
	4	TIMESTAMP		start
		0	CurrentTime
	4	TIMESTAMP		stop
		0	CurrentTime
	1	CARD8		device id
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1		1		Reply
	1		10	GetDeviceMotionEvents opcode
	2		CARD16	sequence number
	4		(m+1)n	reply length
	4		n		number of DEVICETIMECOORDs in events
	1		m		number of valuators per event
	1		CARD8		mode of the device
			0	Absolute
			1	Relative
	18				unused
	(4m+4)n	LISTofDEVICETIMECOORD	events
</pre><p>
</p><p>

</p><pre class="literallayout">

DEVICETIMECOORD
	4	TIMESTAMP		time
	4m	LISTofINT32		valuators
</pre><p>
</p><p>

</p><pre class="literallayout">

ChangeKeyboardDevice
	1	CARD8		input extension opcode
	1	11		ChangeKeyboardDevice opcode
	2	2		request length
	1	CARD8		device id
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	11		ChangeKeyboardDevice opcode
	2	CARD16		sequence number
	4	0		reply length
	1			status
		0	Success
		1	AlreadyGrabbed
		2	DeviceFrozen
	23			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

ChangePointerDevice
	1	CARD8		input extension opcode
	1	12		ChangePointerDevice opcode
	2	2		request length
	1	CARD8		x-axis
	1	CARD8		y-axis
	1	CARD8		device id
	1			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	12		ChangePointerDevice opcode
	2	CARD16		sequence number
	4	0		reply length
	1			status
		0	Success
		1	AlreadyGrabbed
		2	DeviceFrozen
	23			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

GrabDevice
	1	CARD8		input extension opcode
	1	13		GrabDevice opcode
	2	5+n			request length
	4	WINDOW		grab-window
	4	TIMESTAMP		time
		0	CurrentTime
	2	n		count of events
	1			this-device-mode
		0	Synchronous
		1	Asynchronous
	1			other-devices-mode
		0	Synchronous
		1	Asynchronous
	1	BOOL		owner-events
	1	CARD8		device id
	2			unused
	4n	LISTofEVENTCLASS	event list
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	13		GrabDevice opcode
	2	CARD16		sequence number
	4	0		reply length
	1			status
		0	Success
		1	AlreadyGrabbed
		2	InvalidTime
		3	NotViewable
		4	Frozen
	23			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

UngrabDevice
	1	CARD8		input extension opcode
	1	14		UngrabDevice opcode
	2	3		request length
	4	TIMESTAMP		time
		0	CurrentTime
	1	CARD8		device id
	3			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

GrabDeviceKey
	1	CARD8		input extension opcode
	1	15		GrabDeviceKey opcode
	2	5+n		request length
	4	WINDOW		grab-window
	2	n		count of events
	2	SETofKEYMASK		modifiers
		#x8000	AnyModifier
	1	CARD8		modifier device
		#x0FF	UseXKeyboard
	1	CARD8		grabbed device
	1	KEYCODE			key
		0	AnyKey
	1			this-device-mode
		0	Synchronous
		1	Asynchronous
	1			other-devices-mode
		0	Synchronous
		1	Asynchronous
	1	BOOL		owner-events
	2			unused
	4n	LISTofEVENTCLASS	event list
</pre><p>
</p><p>

</p><pre class="literallayout">

UngrabDeviceKey
	1	CARD8		input extension opcode
	1	16		UngrabDeviceKey opcode
	2	4		request length
	4	WINDOW		grab-window
	2	SETofKEYMASK		modifiers
		#x8000	AnyModifier
	1	CARD8		modifier device
		#x0FF	UseXKeyboard
	1	KEYCODE			key
		0	AnyKey
	1	CARD8		grabbed device
	3			unused

</pre><p>
</p><p>

</p><pre class="literallayout">

GrabDeviceButton
	1	CARD8		input extension opcode
	1	17		GrabDeviceButton opcode
	2	5+n		request length
	4	WINDOW		grab-window
	1	CARD8		grabbed device
	1	CARD8		modifier device
		#x0FF	UseXKeyboard
	2	n		count of desired events
	2	SETofKEYMASK		modifiers
	1			this-device-mode
		0	Synchronous
		1	Asynchronous
	1			other-device-mode
		0	Synchronous
		1	Asynchronous
	1	BUTTON		button
		0	AnyButton
	1	BOOL		owner-events
		#x8000	AnyModifier
	2			unused
	4n	LISTofEVENTCLASS	event list
</pre><p>
</p><p>

</p><pre class="literallayout">

UngrabDeviceButton
	1	CARD8		input extension opcode
	1	18		UngrabDeviceButton opcode
	2	4		request length
	4	WINDOW		grab-window
	2	SETofKEYMASK		modifiers
		#x8000	AnyModifier
	1	CARD8		modifier device
		#x0FF	UseXKeyboard
	1	BUTTON		button
		0	AnyButton
	1	CARD8		grabbed device
	3			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

AllowDeviceEvents
	1	CARD8		input extension opcode
	1	19		AllowDeviceEvents opcode
	2	3		request length
	4	TIMESTAMP		time
		0	CurrentTime
	1			mode
		0	AsyncThisDevice
		1	SyncThisDevice
		2	ReplayThisDevice
		3	AsyncOtherDevices
		4	AsyncAll
		5	SyncAll
	1	CARD8		device id
	2			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceFocus
	1	CARD8		input extension opcode
	1	20		GetDeviceFocus opcode
	2	2		request length
	1	CARD8		device
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	20		GetDeviceFocus opcode
	2	CARD16		sequence number
	4	0		reply length
	4	WINDOW		focus
		0	None
		1	PointerRoot
		3	FollowKeyboard
	4	TIMESTAMP	focus time
	1			revert-to
		0	None
		1	PointerRoot
		2	Parent
		3	FollowKeyboard
	15			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

SetDeviceFocus
	1	CARD8		input extension opcode
	1	21		SetDeviceFocus opcode
	2	4		request length
	4	WINDOW		focus
		0	None
		1	PointerRoot
		3	FollowKeyboard
	4	TIMESTAMP		time
		0	CurrentTime
	1			revert-to
		0	None
		1	PointerRoot
		2	Parent
		3	FollowKeyboard
	1	CARD8		device
	2			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

GetFeedbackControl
	1	CARD8		input extension opcode
	1	22		GetFeedbackControl opcode
	2	2		request length
	1	CARD8		device id
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	22		GetFeedbackControl opcode
	2	CARD16		sequence number
	4	m/4			reply length
	2	n		number of feedbacks supported
	22			unused
	m	LISTofFEEDBACKSTATE	feedbacks
</pre><p>
</p><p>

</p><pre class="literallayout">

FEEDBACKSTATE	KBDFEEDBACKSTATE, PTRFEEDBACKSTATE, INTEGERFEEDBACKSTATE, 
  STRINGFEEDBACKSTATE, BELLFEEDBACKSTATE, or LEDFEEDBACKSTATE
</pre><p>
</p><p>

</p><pre class="literallayout">

KBDFEEDBACKSTATE
	1	0		feedback class id
	1	CARD8		id of this feedback
	2	20		length
	2	CARD16		pitch
	2	CARD16		duration
	4	CARD32		led_mask
	4	CARD32		led_values
	1	    		global_auto_repeat
		0	Off
		1	On
	1	CARD8		click
	1	CARD8		percent
	1	    		unused
	32	LISTofCARD8	auto_repeats
</pre><p>
</p><p>

</p><pre class="literallayout">

PTRFEEDBACKSTATE
	1	0		feedback class id
	1	CARD8		id of this feedback
	2	12		length
	2			unused
	2	CARD16		acceleration-numerator
	2	CARD16		acceleration-denominator
	2	CARD16		threshold
</pre><p>
</p><p>

</p><pre class="literallayout">

INTEGERFEEDBACKSTATE
	1	0		feedback class id
	1	CARD8		id of this feedback
	2	16		length
	4	CARD32		resolution
	4	INT32		minimum value
	4	INT32		maximum value
</pre><p>
</p><p>

</p><pre class="literallayout">

STRINGFEEDBACKSTATE
	1	1		feedback class id
	1	CARD8		id of this feedback
	2	4n+8		length
	2	CARD16		max_symbols
	2	n      		number of keysyms supported
	4n	LISTofKEYSYM		key symbols supported
</pre><p>
</p><p>

</p><pre class="literallayout">

BELLFEEDBACKSTATE
	1	1		feedback class id
	1	CARD8		id of this feedback
	2	12		length
	1	CARD8		percent
	3			unused
	2	CARD16		pitch
	2	CARD16		duration
</pre><p>
</p><p>

</p><pre class="literallayout">

LEDFEEDBACKSTATE
	1	1		feedback class id
	1	CARD8		id of this feedback
	2	12		length
	4	CARD32		led_mask
	4	BITMASK		led_values
		#x0001	On
		#x0002	Off
</pre><p>
</p><p>

</p><pre class="literallayout">

ChangeFeedbackControl
	1	CARD8		input extension opcode
	1	23		ChangeFeedbackControl opcode
	2	3+n/4		request length
	4	BITMASK		value-mask (has n bits set to 1)
		#x0001	keyclick-percent
		#x0002	bell-percent
		#x0004	bell-pitch
		#x0008	bell-duration
		#x0010	led
		#x0020	led-mode
		#x0040	key
		#x0080	auto-repeat-mode
		#x0001	string
		#x0001	integer
		#x0001	acceleration-numerator
		#x0002	acceleration-denominator
		#x0004	acceleration-threshold
	1	CARD8		device id
	1	CARD8		feedback class id
	2			unused
	n	FEEDBACKCLASS
</pre><p>
</p><p>

</p><pre class="literallayout">

FEEDBACKCLASS	KBDFEEDBACKCTL, PTRFEEDBACKCTL, INTEGERFEEDBACKCTL, 
  STRINGFEEDBACKCTL, BELLFEEDBACKCTL, or LEDFEEDBACKCTL 
</pre><p>
</p><p>

</p><pre class="literallayout">

KBDFEEDBACKCTL
	1	0		feedback class id
	1	CARD8		id of this feedback
	2	20		length
	1	KEYCODE		key
	1			auto-repeat-mode
		0	Off
		1	On
		2	Default
	1	INT8		key-click-percent
	1	INT8		bell-percent
	2	INT16		bell-pitch
	2	INT16		bell-duration
	4	CARD32		led_mask
	4	CARD32		led_values
</pre><p>
</p><p>

</p><pre class="literallayout">

PTRFEEDBACKCTL
	1	1		feedback class id
	1	CARD8		id of this feedback
	2	12		length
	2			unused
	2	INT16		numerator
	2	INT16		denominator
	2	INT16		threshold
</pre><p>
</p><p>

</p><pre class="literallayout">

STRINGCTL
	1	2		feedback class id
	1	CARD8		id of this feedback
	2	4n+8		length
	2			unused
	2	n		number of keysyms to display
	4n	LISTofKEYSYM		list of key symbols to display
</pre><p>
</p><p>

</p><pre class="literallayout">

INTEGERCTL
	1	3		feedback class id
	1	CARD8		id of this feedback
	2	8		length
	4	INT32		integer to display
</pre><p>
</p><p>

</p><pre class="literallayout">

LEDCTL
	1	4		feedback class id
	1	CARD8		id of this feedback
	2	12		length
	4	CARD32		led_mask
	4	BITMASK		led_values
		#x0001	On
		#x0002	Off
</pre><p>
</p><p>

</p><pre class="literallayout">

BELLCTL
	1	5		feedback class id
	1	CARD8		id of this feedback
	2	8		length
	1	INT8		percent
	3			unused
	2	INT16		pitch
	2	INT16		duration
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceKeyMapping
	1	CARD8		input extension opcode
	1	24		GetDeviceKeyMapping opcode
	2	2		request length
	1	CARD8		device
	1	KEYCODE		first-keycode
	1	CARD8		count
	1			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	24		GetDeviceKeyMapping opcode
	2	CARD16		sequence number
	4	nm		reply length (m = count field from the request)
	1	n		keysyms-per-keycode
	23			unused
	4nm	LISTofKEYSYM		keysyms
</pre><p>
</p><p>

</p><pre class="literallayout">

ChangeDeviceKeyMapping
	1	CARD8		input extension opcode
	1	25		ChangeDeviceKeyMapping opcode
	2	2+nm		request length
	1	CARD8		device
	1	KEYCODE		first-keycode
	1	m		keysyms-per-keycode
	1	n		keycode-count
	4nm	LISTofKEYSYM		keysyms
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceModifierMapping
	1	CARD8		input extension opcode
	1	26		GetDeviceModifierMapping opcode
	2	2		request length
	1	CARD8		device
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	26		GetDeviceModifierMapping opcode
	2	CARD16		sequence number
	4	2n		reply length
	1	n		keycodes-per-modifier
	23			unused
	8n	LISTofKEYCODE		keycodes
</pre><p>
</p><p>

</p><pre class="literallayout">

SetDeviceModifierMapping
	1	CARD8		input extension opcode
	1	27		SetDeviceModifier opcode
	2	2+2n		request length
	1	CARD8		device
	1	n		keycodes-per-modifier
	2			unused
	8n	LISTofKEYCODE		keycodes
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	27		SetDeviceModifierMapping opcode
	2	CARD16		sequence number
	4	0		reply length
	1			status
		0	Success
		1	Busy
		2	Failed
	23			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceButtonMapping
	1	CARD8		input extension opcode
	1	28		GetDeviceButtonMapping opcode
	2	2		request length
	1	CARD8		device
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	28		GetDeviceButtonMapping opcode
	2	CARD16		sequence number
	4	(n+p)/4		reply length
	1	n		number of elements in map list
	23			unused
	n	LISTofCARD8			map
	p			unused, p=pad(n)
</pre><p>
</p><p>

</p><pre class="literallayout">

SetDeviceButtonMapping
	1	CARD8		input extension opcode
	1	29		SetDeviceButtonMapping opcode
	2	2+(n+p)/4		request length
	1	CARD8		device
	1	n		length of map
	2			unused
	n	LISTofCARD8			map
	p			unused, p=pad(n)
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1		Reply
	1	29		SetDeviceButtonMapping opcode
	2	CARD16		sequence number
	4	0		reply length
	1			status
		0	Success
		1	Busy
	23			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

QueryDeviceState
	1	CARD8		input extension opcode
	1	30		QueryDeviceState opcode
	2	2		request length
	1	CARD8		device
	3			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	30			QueryDeviceState opcode
	2	CARD16			sequence number
	4	m/4			reply length
	1	n     	 		number of input classes
	23				unused
	m	LISTofINPUTSTATE
</pre><p>
</p><pre class="literallayout">

INPUTSTATE	KEYSTATE or BUTTONSTATE or VALUATORSTATE
</pre><p>
</p><p>

</p><pre class="literallayout">

KEYSTATE
	1	CARD8		key input class id
	1	36		length
	1	CARD8		num_keys
	1			unused
	32	LISTofCARD8		status of keys
</pre><p>
</p><pre class="literallayout">

BUTTONSTATE
	1	CARD8		button input class id
	1	36		length
	1	CARD8		num_buttons
	1			unused
	32	LISTofCARD8			status of buttons
</pre><p>
</p><pre class="literallayout">

VALUATORSTATE
	1	CARD8		valuator input class id
	1	4n + 4		length
	1	n		number of valuators
	1			mode
		#x01	DeviceMode (0 = Relative, 1 = Absolute)
		#x02	ProximityState (0 = InProximity, 1 = OutOfProximity)
	4n	LISTofCARD32		status of valuators
</pre><p>
</p><p>

</p><pre class="literallayout">

SendExtensionEvent
	1	CARD8			input extension opcode
	1	31			SendExtensionEvent opcode
	2	4 + 8n + m		request length
	4	WINDOW			destination
	1	CARD8			device
	1	BOOL			propagate
	2	CARD16			eventclass count
	1	CARD8			num_events
	3				unused
	32n	LISTofEVENTS		events to send
	4m	LISTofEVENTCLASS	desired events
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceBell
	1	CARD8		input extension opcode
	1	32		DeviceBell opcode
	2	2		request length
	1	CARD8		device id
	1	CARD8		feedback id
	1	CARD8		feedback class
	1	INT8		percent
</pre><p>
</p><p>

</p><pre class="literallayout">

SetDeviceValuators
	1	CARD8		input extension opcode
	1	33		SetDeviceValuators opcode
	2	2 + n		request length
	1	CARD8		device id
	1	CARD8		first valuator
	1	n    		number of valuators
	1			unused
	4n	LISTofINT32	valuator values to set
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	33			SetDeviceValuators opcode
	2	CARD16			sequence number
	4	0			reply length
	1	CARD8			status
		0	Success
		1	AlreadyGrabbed
	23				unused
</pre><p>
</p><p>

</p><pre class="literallayout">

GetDeviceControl
	1	CARD8		input extension opcode
	1	34		GetDeviceControl opcode
	2	2		request length
	2	CARD16		device control type
	1	CARD8		device id
	1			unused
</pre><p>
</p><pre class="literallayout">

=&gt;
	1	1			Reply
	1	34			GetDeviceControl opcode
	2	CARD16			sequence number
	4	n/4			reply length
	1	CARD8			status
		0			Success
		1			AlreadyGrabbed
		3 + first_error		DeviceBusy
	23				unused
	n				DEVICESTATE
</pre><p>
</p><pre class="literallayout">

DEVICESTATE			DEVICERESOLUTIONSTATE
</pre><p>
</p><p>

</p><pre class="literallayout">

DEVICERESOLUTIONSTATE
 	2	0		control type
 	2	8 + 12n		length
 	4	n    		num_valuators
 	4n	LISTOfCARD32	resolution values
 	4n	LISTOfCARD32	resolution min_values
 	4n	LISTOfCARD32	resolution max_values
</pre><p>
</p><p>

</p><p>

</p><pre class="literallayout">

ChangeDeviceControl
 	1	CARD8		input extension opcode
 	1	35		ChangeDeviceControl opcode
 	2	2+n/4		request length
 	2	CARD16		control type
 	1	CARD8		device id
 	1			unused
 	n			DEVICECONTROL
</pre><p>
</p><pre class="literallayout">

DEVICECONTROL		DEVICERESOLUTIONCTL
</pre><p>
</p><p>

</p><pre class="literallayout">

DEVICERESOLUTIONCTL
 	2	1		control type
 	2	8 + 4n		length
 	1	CARD8		first_valuator
 	1	n    		num_valuators
 	2			unused
 	4n	LISTOfCARD32	resolution values
</pre><p>
</p><p>

</p><pre class="literallayout">

=&gt;
 	1	1			Reply
 	1	35			ChangeDeviceControl opcode
 	2	CARD16			sequence number
 	4	0			reply length
 	1	CARD8			status
 		0			Success
 		1			AlreadyGrabbed
 		3 + first_error		DeviceBusy
 	23				unused
</pre><p>

Events

</p><p>

DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelease,
ProximityIn, ProximityOut, and DeviceStateNotify  events may be followed by 
zero or more DeviceValuator events.  DeviceMotionNotify events will be 
followed by one or more DeviceValuator events.
</p><p>

</p><pre class="literallayout">

DeviceValuator
	1	CARD8		code
	1	CARD8		device id
	2	CARD16		sequence number
	2	SETofKEYBUTMASK		state
	1	n		number of valuators this device reports
	1	m		number of first valuator in this event
	24	LISTofINT32	valuators
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceKeyPress
	1	CARD8		code
	1	KEYCODE		detail
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
		0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK		state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceKeyRelease
	1	CARD8		code
	1	KEYCODE		detail
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
		0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK			state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceButtonPress
	1	CARD8		code
	1	BUTTON		detail
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
		0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK		state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceButtonRelease
	1	CARD8		code
	1	BUTTON		detail
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
		0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK		state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceMotionNotify
	1	CARD8		code
	1			detail
		0	Normal
		1	Hint
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
	 	0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK		state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><pre class="literallayout">

DeviceFocusIn
	1	CARD8		code
	1			detail
		0	Ancestor
		1	Virtual
		2	Inferior
		3	Nonlinear
		4	NonlinearVirtual
		5	Pointer
		6	PointerRoot
		7	None
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		event
	1			mode
		0	Normal
		1	Grab
		2	Ungrab
		3	WhileGrabbed
	1	CARD8		device id
	18			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceFocusOut
	1	CARD8		code
	1			detail
		0	Ancestor
		1	Virtual
		2	Inferior
		3	Nonlinear
		4	NonlinearVirtual
		5	Pointer
		6	PointerRoot
		7	None
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		event
	1			mode
		0	Normal
		1	Grab
		2	Ungrab
		3	WhileGrabbed
	1	CARD8		device id
	18			unused
</pre><p>
</p><p>

</p><pre class="literallayout">

ProximityIn
	1	CARD8		code
	1			unused
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
		0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK			state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><p>

</p><pre class="literallayout">

ProximityOut
	1	CARD8		code
	1			unused
	2	CARD16		sequence number
	4	TIMESTAMP		time
	4	WINDOW		root
	4	WINDOW		event
	4	WINDOW		child
		0	None
	2	INT16		root-x
	2	INT16		root-y
	2	INT16		event-x
	2	INT16		event-y
	2	SETofKEYBUTMASK			state
	1	BOOL		same-screen
	1	CARD8		device id
		#x80		MORE_EVENTS follow
</pre><p>
</p><p>

DeviceStateNotify events may be immediately followed by zero or one
DeviceKeyStateNotify and/ or zero or more DeviceValuator events.
</p><p>

</p><pre class="literallayout">

DeviceStateNotify
	1	CARD8		code
	1	CARD8		device id
		#x80		MORE_EVENTS follow
	2	CARD16		sequence number
	4	TIMESTAMP		time
	1	CARD8		num_keys
	1	CARD8		num_buttons
	1	CARD8		num_valuators
 	1	CARD8		valuator mode and input classes reported
 		#x01	reporting keys
 		#x02	reporting buttons
 		#x04	reporting valuators
 		#x40	device mode (0 = Relative, 1 = Absolute)
 		#x80	proximity state (0 = InProximity, 1 = OutOfProximity)
	4	LISTofCARD8		first 32 keys (if reported)
	4	LISTofCARD8		first 32 buttons (if reported)
	12	LISTofCARD32		first 3 valuators (if reported)
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceKeyStateNotify
	1	CARD8		code
	1	CARD8		device id
		#x80		MORE_EVENTS follow
	2	CARD16		sequence number
	28	LISTofCARD8		state of keys 33-255
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceButtonStateNotify
	1	CARD8		code
	1	CARD8		device id
		#x80		MORE_EVENTS follow
	2	CARD16		sequence number
	28	LISTofCARD8		state of buttons 33-255
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceValuator
	1	CARD8		code
	1	CARD8		device id
	2	CARD16		sequence number
	2	SETofKEYBUTMASK		state
	1	n		number of valuators this device reports
	1	n		number of first valuator in this event
	24	LISTofINT32	valuators
</pre><p>
</p><p>

</p><pre class="literallayout">

DeviceMappingNotify
	1	CARD8		code
	1	CARD8		device id
	2	CARD16		sequence number
	1			request
		0	MappingModifier
		1	MappingKeyboard
		2	MappingPointer
	1	KEYCODE		first-keycode
	1	CARD8		count
	1			unused
	4	TIMESTAMP		time
	20			unused
</pre><p>
</p><pre class="literallayout">

ChangeDeviceNotify
	1	CARD8		code
	1	CARD8		id of device specified on change request
	2	CARD16		sequence number
	4	TIMESTAMP		time
	1			request
		0	NewPointer
		1	NewKeyboard
	23			unused
</pre></div></div></body></html>

Cancel