path: root/man/XI.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
            "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >
<!--

    Copyright &copyright; by Hewlett-Packard Company, Ardent Computer,

    Permission to use, copy, modify, distribute, and sell 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 &quot;as is&quot; without express or implied warranty.


    Copyright © 2008 Peter Hutterer
    Copyright © 2009 Red Hat, Inc.

    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 &quot;AS IS&quot;, 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.

    Author: Peter Hutterer
    -->
<reference>
<title>X Input Extension Library</title>

<refentry id="XAllowDeviceEvents.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XAllowDeviceEvents</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
	<refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XAllowDeviceEvents</refname>
        <refpurpose>release queued events</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XAllowDeviceEvents</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>int <parameter>event_mode</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device from which events are
                            to be allowed.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_mode</parameter></term>
                    <listitem><para>Specifies the event mode.You can pass
                            <constant>AsyncThisDevice</constant>,
                            <constant>SyncThisDevice</constant>,
                            <constant>ReplayThisDevice</constant>,
                            <constant>AsyncOtherDevices</constant>,
                            <constant>SyncAll</constant>,or
                            <constant>AsyncAll</constant>.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>time</parameter></term>
                    <listitem><para>Specifies the time.You can pass either a
                            timestamp or <constant>CurrentTime</constant>.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XAllowDeviceEvents</constant> function 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.
        </para>
        <para>
            The following describes the processing that occurs depending on what
            constant you pass to the event_mode argument.
        </para>
        <para>
            <constant>AsyncThisDevice</constant> If the specified device is
            frozen by the client, event processing for that device continues
            as usual. If the device is frozen multiple times by the client on
            behalf of multiple separate grabs,
            <constant>AsyncThisDevice</constant> thaws for
            all.<constant>AsyncThisDevice</constant> has no effect if the
            specified device is not frozen by the client, but the device need
            not be grabbed by the client.  
        </para>
        <para>
            <constant>SyncThisDevice</constant> 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.
            <constant>SyncThisDevice</constant> has no effect if the specified
            device is not frozen by the client or is not grabbed by the
            client.
        </para>
        <para>
            <constant>ReplayThisDevice</constant> 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 GrabDeviceButton or from a previous AllowDeviceEvents with
            mode SyncThisDevice, but not from a GrabDevice), 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) that 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.
        </para>
        <para>
            <constant>AsyncOtherDevices</constant> 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 grabs,
            <constant>AsyncOtherDevices</constant> &quot;thaws&quot; for all.
            <constant>AsyncOtherDevices</constant> has no effect if the
            devices are not frozen by the client.  
        </para>
        <para>
            <constant>SyncAll</constant> 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 all devices again appear to freeze.
            However, if the reported event causes the grab to be released,
            then the devices do not freeze. If any device is still grabbed,
            then a subsequent event for it will still cause all devices to
            freeze.  <constant>SyncAll</constant> 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,
            <constant>SyncAll</constant> thaws for both. A subsequent freeze
            for <constant>SyncAll</constant> will only freeze each device
            once.
        </para>
        <para>
            <constant>AsyncAll</constant> 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, <constant>AsyncAll</constant> thaws for
            all.  <constant>AsyncAll</constant> has no effect unless all
            devices are frozen by the client.  
        </para>
        <para>
            <constant>AsyncThisDevice</constant>,
            <constant>SyncThisDevice</constant>, and
            <constant>ReplayThisDevice</constant> have no effect on the
            processing of events from the remaining
            devices.<constant>AsyncOtherDevices</constant> has no effect on
            the processing of events from the specified device. When the
            event_mode is <constant>SyncAll</constant> or
            <constant>AsyncAll</constant>, the device parameter is ignored.
        </para>
        <para>
            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.  
        </para>
        <para> 
            <constant>XAllowDeviceEvents</constant> can generate a
            <constant>BadDevice</constant> or <constant>BadValue</constant>
            error.
        </para>
    </refsect1>

  <refsect1><title>Diagnostics</title><para>
      <variablelist>
        <varlistentry>
          <term><errorname>BadDevice</errorname></term>
          <listitem>
              <para>
                  An invalid device was specified. The specified device does
                  not exist or has not been opened by this client
                  via <constant>XOpenInputDevice</constant>. This error may
                  also occur if the specified device is the X keyboard or X
                  pointer device.  
              </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><errorname>BadValue</errorname></term>
          <listitem>
              <para>An invalid mode was specified on the request.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
  </refsect1>

  <refsect1><title>See also</title>
    <para>XGrabDevice(3)</para>
  </refsect1>
</refentry>

<refentry id="XChangeDeviceDontPropagateList.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XChangeDeviceDontPropagateList</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XChangeDeviceDontPropagateList</refname>
	<refname>XGetDeviceDontPropagateList</refname>
        <refpurpose>query or change the dont-propagate-list for extension devices</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XChangeDeviceDontPropagateList</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>Window*<parameter>window</parameter></paramdef>
                <paramdef>int *<parameter>count</parameter></paramdef>
                <paramdef>XEventClass *<parameter>event_list</parameter></paramdef>
                <paramdef>int<parameter>mode</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>XEventClass* <function>XGetDeviceDontPropagateList</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>Window *<parameter>window</parameter></paramdef>
                <paramdef>int *<parameter>count</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>window</parameter></term>
                    <listitem><para>Specifies the window whose
                            dont-propagate-list is to be queried or modified.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_list</parameter></term>
                    <listitem><para>Specifies a pointer to a list of event
                            classes.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>mode</parameter></term>
                    <listitem><para>Specifies the mode.You can pass
                            <constant>AddToList</constant>, or
                            <constant>DeleteFromList</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>count</parameter></term>
                    <listitem><para>Specifies the number of event classes in
                            the list.  
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XChangeDeviceDontPropagateList</constant> request
            modifies the list of events that should not be propagated to
            ancestors of the event window. This request allows extension
            events to be added to or deleted from that list. By default, all
            events are propagated to ancestor windows. Once modified, the list
            remains modified for the life of the window. Events are not
            removed from the list because the client that added them has
            terminated.  
        </para>
        <para>
            Suppression of event propagation is not allowed for all input
            extension events. If a specified event class is one that cannot be
            suppressed, a <constant>BadClass</constant> error will result.
            Events that can be suppressed include
            <constant>DeviceKeyPress</constant>,
            <constant>DeviceKeyRelease</constant>,
            <constant>DeviceButtonPress</constant>,
            <constant>DeviceButtonRelease</constant>,
            <constant>DeviceMotionNotify</constant>,
            <constant>ProximityIn</constant>, and
            <constant>ProximityOut</constant>.  
        </para>
        <para>
            <constant>XChangeDeviceDontPropagateList</constant> can generate a
            <constant>BadDevice</constant>, <constant>BadClass</constant>, or
            <constant>BadValue</constant> error.  
        </para>
        <para>
            The <constant>XGetDeviceDontPropagateList</constant> request
            queries the list of events that should not be propagated to
            ancestors of the event window.  
        </para>
        <para>
            <constant>XGetDeviceDontPropagateList</constant> can generate a
            <constant>BadClass</constant>  or <constant>BadWindow</constant>
            error.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if some other client has caused the
                            specified device to become the X keyboard or X
                            pointer device via the
                            <constant>XChangeKeyboardDevice</constant> or
                            <constant>XChangePointerDevice</constant>
                            requests.  
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted. Any argument defined as a set of
                            alternatives can generate this error.  
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>An invalid window id was specified.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadClass</errorname></term>
                    <listitem><para>An invalid event class was specified.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XChangeKeyboardDevice.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XChangeKeyboardDevice</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XChangeKeyboardDevice</refname>
        <refpurpose>change which device is used as the X keyboard</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XChangeKeyboardDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice*<parameter>device</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device to be used as the X
                            keyboard.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XChangeKeyboardDevice</constant> request causes the
            server to use the specified device as the X keyboard. The device
            must have been previously opened by the requesting client via
            <constant>XOpenDevice</constant> or a
            <constant>BadDevice</constant> error will result. The device must
            support input class <constant>Keys</constant>, or a
            <constant>BadMatch</constant> error will result. If the server
            implementation does not support using the requested device as the
            X keyboard, a <constant>BadDevice</constant> error will result.
        </para>
        <para>
            If the specified device is grabbed by another client,
            <constant>AlreadyGrabbed</constant> is returned. If the specified
            device is frozen by a grab on another device,
            <constant>GrabFrozen</constant> is returned. If the request is
            successful, <constant>Success</constant> is returned.
        </para>
        <para>
            If the request succeeds, a <constant>ChangeDeviceNotify</constant>
            event is sent to all clients that have selected that event. A
            <constant>MappingNotify</constant> event with request =
            <constant>MappingKeyboard</constant> is sent to all clients. The
            specified device becomes the X keyboard and the old X keyboard
            becomes accessible through the input extension protocol requests.
        </para>
        <para>
            <constant>XChangeKeyboardDevice</constant> can generate a
            <constant>BadDevice</constant> or a <constant>BadMatch</constant>
            error.  
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist, has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>, or is
                            already one of the core X device (pointer or
                            keyboard). This error may also occur if the server
                            implementation does not support using the
                            specified device as the X keyboard.  </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XChangeKeyboardDevice</constant> request
                            was made specifying a device that has no keys.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
    <refsect1><title>See also</title>
        <para>XChangePointerDevice</para>
    </refsect1>
</refentry>

<refentry id="XChangePointerDevice.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XChangePointerDevice</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XChangePointerDevice</refname>
        <refpurpose>change which device is the X pointer</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XChangePointerDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>int <parameter>xaxis</parameter></paramdef>
                <paramdef>int <parameter>yaxis</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device to be used as the X
                            pointer.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>xaxis</parameter></term>
                    <listitem><para>Specifies the axis of the device to be
                            used as the X pointer x-axis.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>yaxis</parameter></term>
                    <listitem><para>Specifies the axis of the device to be
                            used as the X pointer y-axis.  
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XChangePointerDevice</constant> request causes the
            server to use the specified device as the X pointer. The device
            must have been opened by the client via
            <constant>XOpenDevice</constant> or a
            <constant>BadDevice</constant> error will result. The device must
            support input class <constant>Valuators</constant> or a
            <constant>BadMatch</constant> error will result. If the
            implementation does not support use of the specified device as the
            X pointer, a <constant>BadDevice</constant> error will result.
        </para>
        <para>
            If the specified device is grabbed by another client,
            <constant>AlreadyGrabbed</constant> is returned. If the specified
            device is frozen by a grab on another device,
            <constant>GrabFrozen</constant> is returned. If the request is
            successful, <constant>Success</constant> is returned.  
        </para>
        <para>
            If the request succeeds, a <constant>ChangeDeviceNotify</constant>
            event is sent to all clients that have selected that event. A
            <constant>MappingNotify</constant> event with request =
            <constant>MappingPointer</constant> is sent to all clients. The
            specified device becomes the X pointer, and the old X pointer
            becomes accessible through the input extension protocol requests.
        </para>
        <para>
            <constant>XChangePointerDevice</constant> can generate a
            <constant>BadDevice</constant> or a <constant>BadMatch</constant>
            error.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist, has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>, or is
                            already one of the core X input devices (pointer
                            or keyboard). This error may also occur if the
                            server implementation does not support using the
                            specified device as the X pointer.  
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XChangePointerDevice</constant> request
                            was made specifying a device that has less than
                            two valuators, or specifying a valuator index
                            beyond the range supported by the device.  
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XChangeKeyboardDevice</para>
    </refsect1>
</refentry>

<refentry id="XDeviceBell.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XDeviceBell</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XDeviceBell</refname>
        <refpurpose>ring a bell on a device supported through the input extension</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XDeviceBell</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>XID *<parameter>feedbackclass</parameter></paramdef>
                <paramdef>XID *<parameter>feedbackid</parameter></paramdef>
                <paramdef>int *<parameter>percent</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device with which the bell
                            is associated.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>feedbackclass</parameter></term>
                    <listitem><para>Specifies the class of the feedback with
                            which the bell is associated.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>feedbackid</parameter></term>
                    <listitem><para>Specifies the id of the feedback with
                            which the bell is associated.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>percent</parameter></term>
                    <listitem><para>Specifies the volume in the range -100 to
                            100 at which the bell should be rung.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XDeviceBell</constant> request causes the server to
            ring a bell on the specified feedback of the specified device, if
            possible. The specified volume is relative to the base volume for
            the bell. If an invalid device is specified, a
            <constant>BadDevice</constant> error will be returned. The
            feedbackclass and feedbackid parameters contain values returned by
            an <constant>XGetFeedbackControl</constant> request and uniquely
            identify the bell to ring. If a feedbackclass is specified that
            does not support a bell, or if a nonexistent feedbackid is
            specified, or a percent value is specified that is not in the
            range -100 to 100, a <constant>BadValue</constant> error will be
            returned.
        </para>
        <para>
            The volume at which the bell is rung when the percent argument is
            nonnegative is: base - [(base * percent) / 100] + percent 
        </para>
        <para>
            The volume at which the bell rings when the percent argument is
            negative is: base + [(base * percent) / 100] 
        </para>
        <para>
            To change the base volume of the bell, use
            <constant>XChangeFeedbackControl</constant>.
        </para>
        <para>
            <constant>XDeviceBell</constant> can generate a
            <constant>BadDevice</constant> or a <constant>BadValue</constant>
            error.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist, or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>.  
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>An invalid feedbackclass, feedbackid, or
                            percent value was specified.  
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XChangeFeedbackControl(3), XBell(3)</para>
    </refsect1>
</refentry>

<refentry id="XGetDeviceControl.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGetDeviceControl</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGetDeviceControl</refname>
	<refname>XChangeDeviceControl</refname>
        <refpurpose>query and change input device controls</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>XDeviceControl *<function>XGetDeviceControl</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice*<parameter>device</parameter></paramdef>
                <paramdef>int *<parameter>controlType</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XChangeDeviceControl</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice*<parameter>device</parameter></paramdef>
                <paramdef>int <parameter>controlType</parameter></paramdef>
                <paramdef>XDeviceControl *<parameter>control</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose control is to
                            be interrogated or modified.  
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>controlType</parameter></term>
                    <listitem><para>Specifies the type of control to be
                            interrogated or changed.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>control</parameter></term>
                    <listitem><para>Specifies the address of an
                            <constant>XDeviceControl</constant> structure that
                            contains the new values for the Device.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            These requests are provided to manipulate those input devices that
            support device control. A <constant>BadMatch</constant> error will
            be generated if the requested device does not support any device
            controls.
        </para>
        <para>
            Valid device control types that can be used with these requests
            include the following: 
        </para>
        <para>
            DEVICE_RESOLUTION Queries or changes the resolution of valuators
            on input devices.
        </para>
        <para>
            The <constant>XGetDeviceControl</constant> request returns a
            pointer to an <constant>XDeviceControl</constant> structure.
        </para>
        <para>
            <constant>XGetDeviceControl</constant> can generate a
            <constant>BadDevice</constant> or <constant>BadMatch</constant>
            error.
        </para>
        <para>
            The <constant>XChangeDeviceControl</constant> request modifies the
            values of one control on the specified device. The control is
            identified by the id field of the
            <constant>XDeviceControl</constant> structure that is passed with
            the request.
        </para>
        <para>
            <constant>XChangeDeviceControl</constant> can generate a
            <constant>BadDevice</constant>, <constant>BadMatch</constant>, or
            <constant>BadValue</constant>  error..SH STRUCTURES Each control
            is described by a structure specific to that control. These
            structures are defined in the file <constant>XInput.h</constant>.
        </para>
        <para>
            <constant>XDeviceControl</constant> is a generic structure that
            contains two fields that are at the beginning of each class of
            control: 
        </para>
        <para>
            <synopsis>
                typedef struct {
                    XID <structfield>class</structfield>;
                    int <structfield>length</structfield>;
                } <structname>XDeviceControl</structname>;
            </synopsis>
        </para>
        <para>
            The <constant>XDeviceResolutionState</constant> structure defines
            the information that is returned for device resolution for devices
            with valuators.
        </para>
        <para>
            <synopsis>
                typedef struct {
                    XID <structfield>control</structfield>;
                    int <structfield>length</structfield>;
                    int <structfield>num_valuators</structfield>;
                    int* <structfield>resolutions</structfield>;
                    int* <structfield>min_resolutions</structfield>;
                    int* <structfield>max_resolutions</structfield>;
                } <structname>XDeviceResolutionState</structname>;
            </synopsis>
        </para>
        <para>
            The <constant>XDeviceResolutionControl</constant> structure
            defines the attributes that can be controlled for keyboard
            Devices.
        </para>
        <para>
            <synopsis>
                typedef struct {
                    XID <structfield>control</structfield>;
                    int <structfield>length</structfield>;
                    int <structfield>first_valuator</structfield>;
                    int <structfield>num_valuators</structfield>;
                    int* <structfield>resolutions</structfield>;
                } <structname>XDeviceResolutionControl</structname>;
            </synopsis>
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if some other client has caused the
                            specified device to become the X keyboard or X
                            pointer device via the
                            <constant>XChangeKeyboardDevice</constant> or
                            <constant>XChangePointerDevice</constant>
                            requests.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetDeviceControl</constant> request was
                            made specifying a device that has no controls or
                            an <constant>XChangeDeviceControl</constant>
                            request was made with an
                            <constant>XDeviceControl</constant> structure that
                            contains an invalid Device type. It may also occur
                            if an invalid combination of mask bits is
                            specified ( <constant>DvKey</constant> but no
                            <constant>DvAutoRepeatMode</constant> for keyboard
                            Devices), or if an invalid KeySym is specified for
                            a string Device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the
                            <constant>XChangeDeviceControl</constant> request.
                            Unless a specific range is specified for an
                            argument, the full range defined by the argument's
                            type is accepted. Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para></para>
    </refsect1>
</refentry>

<refentry id="XGetDeviceKeyMapping.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGetDeviceKeyMapping</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGetDeviceKeyMapping</refname>
	<refname>XChangeDeviceKeyMapping</refname>
        <refpurpose>query or change device key mappings</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>KeySym *<function>XGetDeviceKeyMapping</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>KeyCode <parameter>first_keycode</parameter></paramdef>
                <paramdef>int <parameter>keycode_count</parameter></paramdef>
                <paramdef>int *<parameter>keysyms_per_keycode_return</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose key mapping is
                            to be queried or modified.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>first_keycode</parameter></term>
                    <listitem><para>Specifies the first KeyCode to be
                            returned.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>keycode_count</parameter></term>
                    <listitem><para>Specifies the number of KeyCodes to be
                            returned or modified.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>keysyms_per_keycode</parameter></term>
                    <listitem><para>Specifies the number of KeySyms per
                            KeyCode.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>keysyms_per_keycode_return</parameter></term>
                    <listitem><para>Specifies the address of a variable into
                            which the number of KeySyms per KeyCodewill be
                            returned.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>keysyms</parameter></term>
                    <listitem><para>Specifies the address of an array of
                            KeySyms.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            For the specified device, the
            <constant>XGetDeviceKeyMapping</constant> request returns the
            symbols for the specified number of KeyCodes starting with
            first_keycode. The value specified in first_keycode must be
            greater than or equal to min_keycode as returned by
            <constant>XListInputDevices</constant>, or a
            <constant>BadValue</constant> error results. In addition, the
            following expression must be less than or equal to max_keycode as
            returned by <constant>XListInputDevices</constant>: 
        </para> 
        <para>
            first_keycode + keycode_count - 1
        </para>
        <para>
            If this is not the case, a <constant>BadValue</constant> error
            results. The number of elements in the KeySyms list is: </para>
        <para>
            keycode_count * keysyms_per_keycode_return
        </para>
        <para>
            KeySym number N, counting from zero, for KeyCode K has the
            following index in the list, counting from zero: 
            (K - first_code) * keysyms_per_code_return + N 
        </para>
        <para>
            The X server arbitrarily chooses the keysyms_per_keycode_return
            value to be large enough to report all requested symbols. A
            special KeySym value of <constant>NoSymbol</constant> is used to
            fill in unused elements for individual KeyCodes. To free the
            storage returned by <constant>XGetDeviceKeyMapping</constant>, use
            <constant>XFree</constant>.
        </para>
        <para>
            If the specified device does not support input class keys, a
            <constant>BadMatch</constant> error will result.
        </para>
        <para>
            <constant>XGetDeviceKeyMapping</constant> can generate a
            <constant>BadDevice</constant>, <constant>BadMatch</constant>, or
            <constant>BadValue</constant> error.
        </para>
        <para>
            For the specified device, the
            <constant>XChangeDeviceKeyMapping</constant> request defines the
            symbols for the specified number of KeyCodes starting with
            first_keycode. The symbols for KeyCodes outside this range remain
            unchanged. The number of elements in keysyms must be: 
        </para>
        <para>
            num_codes * keysyms_per_keycode 
        </para>
        <para>
            The specified first_keycode must be greater than or equal to
            min_keycode returned by <constant>XListInputDevices</constant>, or
            a <constant>BadValue</constant> error results. In addition, the
            following expression must be less than or equal to max_keycode as
            returned by <constant>XListInputDevices</constant>, or a
            <constant>BadValue</constant> error results: 
        </para>
        <para>
            first_keycode + num_codes - 1</para>
        <para>
            KeySym number N, counting from zero, for KeyCode K has the
            following index in keysyms, counting from zero: 
        </para>
        <para>
            (K - first_keycode) * keysyms_per_keycode + N
        </para>
        <para>
            The specified keysyms_per_keycode can be chosen arbitrarily by the
            client to be large enough to hold all desired symbols. A special
            KeySym value of <constant>NoSymbol</constant> should be used to
            fill in unused elements for individual KeyCodes. It is legal for
            <constant>NoSymbol</constant> to appear in nontrailing positions
            of the effective list for a
            KeyCode.<constant>XChangeDeviceKeyMapping</constant> generates a
            <constant>DeviceMappingNotify</constant> event that is sent to all
            clients that have selected that type of event.
        </para>
        <para>
            There is no requirement that the X server interpret this mapping.
            It is merely stored for reading and writing by clients.
        </para>
        <para>
            If the specified device does not support input class keys, a
            <constant>BadMatch</constant> error results.
        </para>
        <para>
            <constant>XChangeDeviceKeyMapping</constant> can generate a
            <constant>BadDevice</constant>, <constant>BadMatch</constant>,
            <constant>BadAlloc</constant>, or <constant>BadValue</constant>
            error.
        </para>
        <para>
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetDeviceKeyMapping</constant> or
                            <constant>XChangeDeviceKeyMapping</constant>
                            request was made specifying a device that has no
                            keys.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted. Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadAlloc</errorname></term>
                    <listitem><para>The server failed to allocate the
                            requested resource or server memory.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XSetDeviceButtonMapping(3), XSetDeviceModifierMapping(3)</para>
    </refsect1>
</refentry>

<refentry id="XGetDeviceModifierMapping.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGetDeviceModifierMapping</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGetDeviceModifierMapping</refname>
	<refname>XSetDeviceModifierMapping</refname>
        <refpurpose>query or change device modifier mappings</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XSetDeviceModifierMapping</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>XModifierKeymap *<parameter>modmap</parameter></paramdef>
        </funcprototype>
        <funcprototype>
          <funcdef>XModifierKeymap *<function>XGetDeviceModifierMapping</function></funcdef>
          <paramdef>Display *<parameter>display</parameter></paramdef>
          <paramdef>XDevice *<parameter>device</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose modifier
                            mapping is to be queried or modified.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modmap</parameter></term>
                    <listitem><para>Specifies a pointer to the
                            <constant>XModifierKeymap</constant> structure.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XSetDeviceModifierMapping</constant> request
            specifies the KeyCodes of the keys (if any) that are to be used as
            modifiers for the specified device. If it succeeds, the X server
            generates a <constant>DeviceMappingNotify</constant> event, and
            <constant>XSetDeviceModifierMapping</constant> returns
            <constant>MappingSuccess</constant>. X permits at most eight
            modifier keys. If more than eight are specified in the
            <constant>XModifierKeymap</constant> structure, a
            <constant>BadLength</constant> error results.
        </para>
        <para>
            The modifiermap member of the <constant>XModifierKeymap</constant>
            structure contains eight sets of max_keypermod KeyCodes, one for
            each modifier in the order <constant>Shift</constant>,
            <constant>Lock</constant>, <constant>Control</constant>,
            <constant>Mod1</constant>, <constant>Mod2</constant>,
            <constant>Mod3</constant>, <constant>Mod4</constant>, and
            <constant>Mod5</constant>. 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 as returned by <constant>XListInputDevices</constant>,
            or a <constant>BadValue</constant> error results. No KeyCode may
            appear twice in the entire map, or a <constant>BadValue</constant>
            error results.
        </para>
        <para>
            An X server can impose restrictions on how modifiers can be
            changed, for example, if certain keys do not generate up
            transitions in hardware, if auto-repeat cannot be disabled on
            certain keys, or if multiple modifier keys are not supported. If
            some such restriction is violated, the status reply is
            <constant>MappingFailed</constant>, 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,
            <constant>XSetDeviceModifierMapping</constant> returns
            <constant>MappingBusy</constant>, and none of the modifiers is
            changed.
        </para>
        <para>
            <constant>XSetDeviceModifierMapping</constant> can generate
            <constant>BadLength</constant>, <constant>BadDevice</constant>,
            <constant>BadMatch</constant>, <constant>BadAlloc</constant>, and
            <constant>BadValue</constant> errors.
        </para>
        <para>
            The <constant>XGetDeviceModifierMapping</constant> request returns
            a pointer to a newly created <constant>XModifierKeymap</constant>
            structure that contains the keys being used as modifiers. The
            structure should be freed after use by calling
            <constant>XFreeModifierMapping </constant>. If only zero values
            appear in the set for any modifier, that modifier is disabled.
        </para>
        <para>
            <constant>XGetDeviceModifierMapping</constant> can generate
            <constant>BadDevice</constant> and <constant>BadMatch</constant>
            errors.
        </para>
    </refsect1>
    <refsect1><title>Structures</title>
        <para>
            The <constant>XModifierKeymap</constant> structure contains:
        </para>
        <para>
            <synopsis>
                typedef struct {
                int <structfield>max_keypermod</structfield>;
                KeyCode *<structfield>modifiermap</structfield>;
                } <structname>XModifierKeymap</structname>;
            </synopsis>
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadLength</errorname></term>
                    <listitem><para>More than eight keys were specified in the
                            <constant>XModifierKeymap</constant> structure.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadAlloc</errorname></term>
                    <listitem><para>The server failed to allocate the
                            requested resource or server memory.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetDeviceModifierMapping</constant> or
                            <constant>XChangeDeviceModifierMapping</constant>
                            request was made specifying a device that has no
                            keys.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted. Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XSetDeviceKeyMapping(3), XSetDeviceButtonMapping(3)</para>
    </refsect1>
</refentry>

<refentry id="XGetDeviceMotionEvents.man">
    <refentryinfo>
      <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
      <refentrytitle>XGetDeviceMotionEvents</refentrytitle>
      <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGetDeviceMotionEvents</refname>
	<refname>XDeviceTimeCoord</refname>
       <refpurpose>get device motion history</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
      <title>Syntax</title>
      <funcsynopsis>
        <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
        <funcprototype>
          <funcdef>XDeviceTimeCoord *<function>XGetDeviceMotionEvents</function></funcdef>
          <paramdef>Display *<parameter>display</parameter></paramdef>
          <paramdef>XDevice *<parameter>device</parameter></paramdef>
          <paramdef>Time <parameter>start</parameter></paramdef>
          <paramdef>Time <parameter>stop</parameter></paramdef>
          <paramdef>int *<parameter>nevents_return</parameter></paramdef>
          <paramdef>int *<parameter>mode_return</parameter></paramdef>
          <paramdef>int *<parameter>axis_count_return</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
          <variablelist>
            <varlistentry><term><parameter>display</parameter></term>
              <listitem><para>Specifies the connection to the X server.
              </para></listitem>
            </varlistentry>
            <varlistentry><term><parameter>device</parameter></term>
              <listitem><para>Specifies the device whose motion history is to
                      be queried.
              </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><parameter>start</parameter></term>
                <term><parameter>stop</parameter></term>
                <listitem><para>Specify the time interval in which the events
                        are returned from the motionhistory buffer.You can
                        pass a timestamp or <constant>CurrentTime</constant>.
                </para></listitem>
            </varlistentry>
            <varlistentry><term><parameter>nevents_return</parameter></term>
              <listitem><para>Returns the number of events from the motion
                      history buffer.
              </para></listitem>
            </varlistentry>
            <varlistentry><term><parameter>mode_return</parameter></term>
              <listitem><para>Returns the mode of the device
                      (<constant>Absolute</constant> or
                      <constant>Relative</constant>).
              </para></listitem>
            </varlistentry>
            <varlistentry><term><parameter>axis_count_return</parameter></term>
              <listitem><para>Returns the count of axes being reported.
              </para></listitem>
            </varlistentry>
          </variablelist>
        </para>
      </refsect1>

      <refsect1><title>Description</title>
          <para>
              The server may retain the recent history of the device motion
              and do so to a finer granularity than is reported by
              <constant>DeviceMotionNotify</constant> events. The
              <constant>XGetDeviceMotionEvents</constant> request makes this
              history available.
          </para>
        <para>
            The <constant>XGetDeviceMotionEvents</constant> request returns
            all events in the motion history buffer that fall between the
            specified start and stop times, inclusive. If the start time is
            later than the stop time or if the start time is in the future, no
            events are returned. If the stop time is in the future, it is
            equivalent to specifying <constant>CurrentTime</constant>.
        </para>
        <para>
            The <constant>mode</constant> indicates whether the device is
            reporting absolute positional data (mode = 
            <constant>Absolute</constant> ) or relative motion data (mode =
             <constant>Relative</constant> ). Some devices allow their mode to
            be changed via the <constant>XSetDeviceMode</constant> request.
            These constants are defined in the file XI.h. The
            <constant>axis_count</constant> returns the number of axes or
            valuators being reported by the device.
        </para>
        <para>
            <constant>XGetDeviceMotionEvents</constant> can generate a
            <constant>BadDevice</constant>, or <constant>BadMatch</constant>
            error.
        </para>
    </refsect1>
    <refsect1><title>Structures</title>
        <para>
            The <constant>XDeviceTimeCoord</constant> structure contains: 
        </para>
        <para>
            <synopsis>
                typedef struct {
                    Time <structfield>time</structfield>;
                    int *<structfield>data</structfield>;
                } <structname>XDeviceTimeCoord</structname>;
            </synopsis>
        </para>
        <para>
            The time member is set to the time, in milliseconds. The data
            member is a pointer to an array of integers. These integers are
            set to the values of each valuator or axis reported by the device.
            There is one element in the array per axis of motion reported by
            the device. The value of the array elements depends on the mode of
            the device. If the mode is <constant>Absolute</constant>, the
            values are the raw values generated by the device. These may be
            scaled by client programs using the maximum values that the device
            can generate. The maximum value for each axis of the device is
            reported in the max_val field of the
            <constant>XAxisInfo</constant> returned by the
            <constant>XListInputDevices</constant> request. If the mode is
            <constant>Relative</constant>, the data values are the relative
            values generated by the device.
        </para>
        <para>
            You should use <constant>XFreeDeviceMotionEvents</constant> to
            free the data returned by this request.
        </para>
        <para>
            Errors returned by this request: <constant>BadDevice</constant>,
            <constant>BadMatch</constant>.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetDeviceMotionEvents</constant>
                            request is made specifying a device that has no
                            valuators and reports no axes of motion.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XGetExtensionVersion.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGetExtensionVersion</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XQueryInputVersion</refname>
	<refname>XGetExtensionVersion</refname>
        <refpurpose>query the version of the input extension.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>XExtensionVersion *<function>XQueryInputVersion</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>major</parameter></paramdef>
                <paramdef>int <parameter>minor</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>XExtensionVersion *<function>XGetExtensionVersion</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>char *<parameter>name</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>name</parameter></term>
                    <listitem><para>Specifies the extension to be queried.
                            The input extension name is definedin the header
                            file  <constant>XI.h</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>major</parameter></term>
                    <listitem><para>Specifies the major version as supported
                            by the client.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>minor</parameter></term>
                    <listitem><para>Specifies the minor version as supported
                            by the client.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XQueryInputVersion</constant>  request queries the
            version of the input extension and returns an
            <constant>XExtensionVersion</constant>  structure. This structure
            contains a major_version and minor_version number which can be
            compared with constants defined in  <constant>XI.h</constant>. The
            client must specify the highest version numbers it can supports.
        </para>
        <para>
            The <constant>XGetExtensionVersion</constant>  request is
            deprecated and should not be used. Clients issuing a
            <constant>XgetExtensionVersion</constant>  request will not be
            able to use MPX features. The
            <constant>XGetExtensionVersion</constant>  request queries the
            version of the input extension, and returns an
            <constant>XExtensionVersion</constant>  structure.  This structure
            contains a major_version and minor_version number which can be
            compared with constants defined in  <constant>XI.h</constant>.
            Support for additional protocol requests added to the input
            extension after its initial release is indicated by a version
            number corresponding to the added requests.  Each version contains
            all the protocol requests contained by previous versions.
        </para>
        <para>
            You should use  <constant>XFree</constant>  to free the
            <constant>XExtensionVersion</constant>  structure.
        </para>
    </refsect1>
    <refsect1><title>Structures</title>
        <para>
            This request returns an XExtensionVersion structure.
        </para>
        <para>
            <synopsis>
                typedef struct {
                int <structfield>present</structfield>;
                short <structfield>major_version</structfield>;
                short <structfield>minor_version; </structfield>
                } <structname>XExtensionVersion</structname>;
            </synopsis>
        </para>

    </refsect1>
</refentry>

<refentry id="XGetFeedbackControl.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGetFeedbackControl</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGetFeedbackControl</refname>
	<refname>XChangeFeedbackControl</refname>
        <refpurpose>query and change input device feedbacks</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>XFeedbackState *<function>XGetFeedbackControl</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>int *<parameter>num_feedbacks</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XChangeFeedbackControl</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice* <parameter>device</parameter></paramdef>
                <paramdef>Mask <parameter>mask</parameter></paramdef>
                <paramdef>XFeedbackControl *<parameter>control</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
</para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose feedbacks are
                            to be queried or modified.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>num_feedbacks</parameter></term>
                    <listitem><para>Specifies an address into which the number
                            of feedbacks supported by thedevice is to be
                            returned.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>mask</parameter></term>
                    <listitem><para>Specifies a mask specific to each type of
                            feedback that describes howthe feedback is to be
                            modified.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>control</parameter></term>
                    <listitem><para>Specifies the address of an
                            <constant>XFeedbackControl</constant> structure
                            that containsthe new values for the feedback.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            These requests are provided to manipulate those input devices that
            support feedbacks.  A  <constant>BadMatch</constant>  error will
            be generated if the requested device does not support feedbacks.
            Whether or not a given device supports feedbacks can be determined
            by examining the information returned by the
            <constant>XOpenDevice</constant>  request.  For those devices that
            support feedbacks,  <constant>XOpenDevice</constant>  will return
            an  <constant>XInputClassInfo</constant>  structure with the
            input_class field equal to the constant
            <constant>FeedbackClass</constant>  (defined in the file
            <constant>XI.h</constant>).
        </para>
        <para>
            The  <constant>XGetFeedbackControl</constant>  request returns a
            pointer to a list of  <constant>XFeedbackState</constant>
            structures.  Each item in this list describes one of the feedbacks
            supported by the device.  The items are variable length, so each
            contains its length to allow traversal to the next item in the
            list.
        </para>
        <para>
            The feedback classes that are currently defined are:
            <constant>KbdFeedbackClass</constant>,
            <constant>PtrFeedbackClass</constant>,
            <constant>StringFeedbackClass</constant>,
            <constant>IntegerFeedbackClass</constant>,
            <constant>LedFeedbackClass</constant>, and
            <constant>BellFeedbackClass</constant>. These constants are
            defined in the file  <constant>XI.h</constant>.  An input device
            may support zero or more classes of feedback, and may support
            multiple feedbacks of the same class.  Each feedback contains a
            class identifier and an id that is unique within that class for
            that input device.  The id is used to identify the feedback when
            making an  <constant>XChangeFeedbackControl</constant>  request.
        </para>
        <para>
            <constant>XGetFeedbackControl</constant>  can generate a
            <constant>BadDevice</constant>  or  <constant>BadMatch</constant>
            error.
        </para>
        <para>
            The  <constant>XChangeFeedbackControl</constant>  request modifies
            the values of one feedback on the specified device.  The feedback
            is identified by the id field of the
            <constant>XFeedbackControl</constant>  structure that is passed
            with the request.  The fields of the feedback that are to be
            modified are identified by the bits of the mask that is passed
            with the request.
        </para>
        <para>
            <constant>XChangeFeedbackControl</constant>  can generate a
            <constant>BadDevice</constant>,  <constant>BadMatch</constant>, or
            <constant>BadValue</constant>   error.
        </para>
    </refsect1>
    <refsect1><title>Structures</title>
        <para>
            Each class of feedback is described by a structure specific to
            that class. These structures are defined in the file
            <constant>XInput.h</constant>.
            <constant>XFeedbackState</constant>  and
            <constant>XFeedbackControl</constant>  are generic structures that
            contain three fields that are at the beginning of each class of
            feedback: </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                } <structname>XFeedbackState</structname>,
                <structname>XFeedbackControl;</structname>
            </synopsis>
        </para>
        <para>
            The <constant>XKbdFeedbackState</constant> structure defines the
            attributes that are returned for feedbacks equivalent to those on
            the X keyboard.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>click</structfield>;
                int <structfield>percent</structfield>;
                int <structfield>pitch</structfield>;
                int <structfield>duration</structfield>;
                int <structfield>led_mask</structfield>;
                int <structfield>global_auto_repeat</structfield>;
                char <structfield>auto_repeats[32]</structfield>;
                } <structname>XKbdFeedbackState</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XPtrFeedbackState</constant>  structure defines the
            attributes that are returned for feedbacks equivalent to those on
            the the X pointer.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>accelNum</structfield>;
                int <structfield>accelDenom</structfield>;
                int <structfield>threshold</structfield>;
                } <structname>XPtrFeedbackState</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XIntegerFeedbackState</constant>  structure defines
            attributes that are returned for integer feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>resolution</structfield>;
                int <structfield>minVal</structfield>;
                int <structfield>maxVal</structfield>;
                } <structname>XIntegerFeedbackState</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XStringFeedbackState</constant>  structure defines
            the attributes that are returned for string feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>max_symbols</structfield>;
                int <structfield>num_syms_supported</structfield>;
                KeySym *<structfield>syms_supported</structfield>;
                } <structname>XStringFeedbackState</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XBellFeedbackState</constant>  structure defines
            the attributes that are returned for bell feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>percent</structfield>;
                int <structfield>pitch</structfield>;
                int <structfield>duration</structfield>;
                } <structname>XBellFeedbackState</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XLedFeedbackState</constant>  structure defines the
            attributes that are returned for LED feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct { XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>led_values</structfield>;
                } <structname>XLedFeedbackState</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XPrtFeedbackControl</constant>  structure defines
            the attributes that can be controlled for pointer feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>accelNum</structfield>;
                int <structfield>accelDenom</structfield>;
                int <structfield>threshold</structfield>;
                } <structname>XPtrFeedbackControl</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XKbdFeedbackControl</constant>  structure defines
            the attributes that can be controlled for keyboard feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>click</structfield>;
                int <structfield>percent</structfield>;
                int <structfield>pitch</structfield>;
                int <structfield>duration</structfield>;
                int <structfield>led_mask</structfield>;
                int <structfield>led_value</structfield>;
                int <structfield>key</structfield>;
                int <structfield>auto_repeat_mode</structfield>;
                } <structname>XKbdFeedbackControl</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XStringFeedbackControl</constant>  structure
            defines the attributes that can be controlled for string
            feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>num_keysyms</structfield>;
                KeySym  *<structfield>syms_to_display</structfield>;
                } <structname>XStringFeedbackControl</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XIntegerFeedbackControl</constant>  structure
            defines the attributes that can be controlled for integer
            feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                XID <structfield>id</structfield>;
                int <structfield>int_to_display</structfield>;
                } <structname>XIntegerFeedbackControl</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XBellFeedbackControl</constant>  structure defines
            the attributes that can be controlled for bell feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID     <structfield>class</structfield>;
                int     <structfield>length</structfield>;
                XID     <structfield>id</structfield>;
                int     <structfield>percent</structfield>;
                int     <structfield>pitch</structfield>;
                int     <structfield>duration</structfield>;
                } <structname>XBellFeedbackControl</structname>;
            </synopsis>
        </para>
        <para>
            The  <constant>XLedFeedbackControl</constant>  structure defines
            the attributes that can be controlled for LED feedbacks.
        </para>
        <para>
            <synopsis>
                typedef struct {
                XID     <structfield>class</structfield>;
                int     <structfield>length</structfield>;
                XID     <structfield>id</structfield>;
                int     <structfield>led_mask</structfield>;
                int     <structfield>led_values</structfield>;
                } <structname>XLedFeedbackControl</structname>;
            </synopsis>
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified.  The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>.  This error
                            may also occur if some other client has caused the
                            specified device to become the X keyboard or X
                            pointer device via the
                            <constant>XChangeKeyboardDevice</constant>  or
                            <constant>XChangePointerDevice</constant>
                            requests.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetFeedbackControl</constant>  request
                            was made specifying a device that has no
                            feedbacks, or an
                            <constant>XChangeFeedbackControl</constant>
                            request was made with an
                            <constant>XFeedbackControl</constant>  structure
                            that contains an invalid feedback type.  It may
                            also occur if an invalid combination of mask bits
                            is specified ( <constant>DvKey</constant>  but no
                            <constant>DvAutoRepeatMode</constant>  for
                            keyboard feedbacks), or if an invalid KeySym is
                            specified for a string feedback.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the
                            <constant>XChangeFeedbackControl</constant>
                            request. Unless a specific range is specified for
                            an argument, the full range defined by the
                            argument's type is accepted.  Any argument defined
                            as a set of alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>


<refentry id="XGrabDeviceButton.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGrabDeviceButton</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGrabDeviceButton</refname>
	<refname>XUngrabDeviceButton</refname>
        <refpurpose>grab/ungrab extension input device buttons</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XGrabDeviceButton</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>unsigned int <parameter>button</parameter></paramdef>
                <paramdef>unsigned int <parameter>modifiers</parameter></paramdef>
                <paramdef>XDevice*<parameter>modifier_device</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>Bool<parameter>owner_events</parameter></paramdef>
                <paramdef>unsigned int <parameter>event_count</parameter></paramdef>
                <paramdef>XEventClass*<parameter>event_list</parameter></paramdef>
                <paramdef>int <parameter>this_device_mode</parameter></paramdef>
                <paramdef>int<parameter>other_devices_mode</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XUngrabDeviceButton</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>unsigned int <parameter>button</parameter></paramdef>
                <paramdef>unsigned int <parameter>modifiers</parameter></paramdef>
                <paramdef>XDevice*<parameter>modifier_device</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
</para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device that is to be
                            grabbed or released</para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>button</parameter></term>
                    <listitem><para>Specifies the device button that is to
                            be grabbed or released or <constant>AnyButton</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modifiers</parameter></term>
                    <listitem><para>Specifies the set of keymasks or
                            <constant>AnyModifier</constant>.The mask is
                            the bitwise inclusive OR of the valid keymask
                            bits. Valid bits are:
                            <constant>Shiftmask</constant>,
                            <constant>LockMask</constant>,
                            <constant>ControlMask</constant>,
                            <constant>Mod1Mask</constant>,
                            <constant>Mod2Mask,Mod3Mask</constant>,
                            <constant>Mod4Mask</constant>,
                            <constant>Mod5Mask</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modifier_device</parameter></term>
                    <listitem><para>specifies the device whose modifiers are
                            to be used.  If the modifier_devicespecified is
                            NULL, the X keyboard will be used as the
                            modifier_device.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>grab_window</parameter></term>
                    <listitem><para>Specifies the grab window.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>owner_events</parameter></term>
                    <listitem><para>Specifies a Boolean value that indicates
                            whether the deviceevents are to be reported as
                            usual or reported with respect to the grab
                            windowif selected by the event list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_count</parameter></term>
                    <listitem><para>Specifies the number of event classes in
                            the event list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_list</parameter></term>
                    <listitem><para>Specifies which events are reported to the
                            client.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>this_device_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from this device.You can pass
                            <constant>GrabModeSync</constant> or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>other_devices_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from all other devices.You can pass
                            <constant>GrabModeSync</constant> or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The  <constant>XGrabDeviceButton</constant>  request establishes a
            passive grab. In the future, the device is actively grabbed (as
            for  <constant>XGrabDevice</constant>, the last-grab time is set
            to the time at which the button was pressed (as transmitted in the
            <constant>DeviceButtonPress</constant>  event), and the
            <constant>DeviceButtonPress</constant>  event is reported if all
            of the following conditions are true:

            <itemizedlist>
                <listitem>
                    <para>
                        The device is not grabbed, and the specified button is
                        logically pressed when the specified modifier keys are
                        logically down on the specified modifier device and no
                        other buttons or modifier keys are logically down.
                    </para>
                </listitem>
                <listitem>
                    <para>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 device.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        A passive grab on the same button/modifier combination
                        does not exist on any ancestor of grab_window.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            The interpretation of the remaining arguments is as for
            <constant>XGrabDevice</constant>. The active grab is terminated
            automatically when the logical state of the device has all buttons
            released (independent of the logical state of the modifier keys).
        </para>
        <para>
            Note that the logical state of a device (as seen by client
            applications) may lag the physical state if device event
            processing is frozen.
        </para>
        <para>
            This request overrides all previous grabs by the same client on
            the same button/modifier combinations on the same window. A
            modifiers of  <constant>AnyModifier</constant>  is equivalent to
            issuing the grab 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
            button of  <constant>AnyButton</constant>  is equivalent to
            issuing the request for all possible buttons. Otherwise, it is not
            required that the specified button currently be assigned to a
            physical button.
        </para>
        <para>
            A modifier_device of NULL indicates that the X keyboard is to be
            used as the modifier_device.
        </para>
        <para>
            If some other client has already issued a
            <constant>XGrabDeviceButton</constant>  with the same
            button/modifier combination on the same window, a
            <constant>BadAccess</constant>  error results. When using
            <constant>AnyModifier</constant>  or
            <constant>AnyButton</constant> , the request fails completely, and
            a  <constant>BadAccess</constant>  error results (no grabs are
            established) if there is a conflicting grab for any combination.
            <constant>XGrabDeviceButton</constant>  has no effect on an active
            grab.
        </para>
        <para>
            <constant>XGrabDeviceButton</constant>  can generate
            <constant>BadClass</constant>,  <constant>BadDevice</constant>,
            <constant>BadMatch</constant>,  <constant>BadValue</constant>, and
            <constant>BadWindow</constant>  errors..P The
            <constant>XUngrabDeviceButton</constant>  request releases the
            passive grab for a button/modifier combination on the specified
            window if it was grabbed by this client. A modifier of
            <constant>AnyModifier</constant>  is equivalent to issuing the
            ungrab request for all possible modifier combinations, including
            the combination of no modifiers. A button of
            <constant>AnyButton</constant>  is equivalent to issuing the
            request for all possible buttons.
            <constant>XUngrabDeviceButton</constant>  has no effect on an
            active grab.
        </para>
        <para>
            A modifier_device of NULL indicates that the X keyboard should be
            used as the modifier_device.
        </para>
        <para>
            <constant>XUngrabDeviceButton</constant>  can generate
            <constant>BadDevice</constant>,  <constant>BadMatch</constant>,
            <constant>BadValue</constant>  and  <constant>BadWindow</constant>
            errors.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified.  The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>.  This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGrabDeviceButton</constant>  request
                            was made specifying a device that has no buttons,
                            or specifying a modifier device that has no keys.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted.  Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XAllowDeviceEvents(3), XGrabDevice(3), XGrabDeviceKey(3)</para>
    </refsect1>
</refentry>

<refentry id="XGrabDeviceKey.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGrabDeviceKey</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGrabDeviceKey</refname>
	<refname>XUngrabDeviceKey</refname>
        <refpurpose>grab/ungrab extension input device Keys</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XGrabDeviceKey</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>unsigned int <parameter>Key</parameter></paramdef>
                <paramdef>unsigned int <parameter>modifiers</parameter></paramdef>
                <paramdef>XDevice *<parameter>modifier_device</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>Bool <parameter>owner_events</parameter></paramdef>
                <paramdef>unsigned int <parameter>event_count</parameter></paramdef>
                <paramdef>XEventClass <parameter>event_list</parameter></paramdef>
                <paramdef>int <parameter>this_device_mode</parameter></paramdef>
                <paramdef>int <parameter>other_devices_mode</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XUngrabDeviceKey</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>unsigned int <parameter>Key</parameter></paramdef>
                <paramdef>unsigned int <parameter>modifiers</parameter></paramdef>
                <paramdef>XDevice *<parameter>modifier_device</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device that is to be
                            grabbed or released.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>Key</parameter></term>
                    <listitem><para>Specifies the device Key that is to be
                            grabbed released or <constant>AnyKey</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modifiers</parameter></term>
                    <listitem><para>Specifies the set of keymasks or
                            <constant>AnyModifier</constant>.The mask is the
                            bitwise inclusive OR of the valid keymask
                            bits.Valid bits are: ShiftMask, LockMask,
                            ControlMask, Mod1Mask, Mod2Mask,Mod3Mask,
                            Mod4Mask, Mod5Mask.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modifier_device</parameter></term>
                    <listitem><para>Specifies the device whose modifiers are
                            to be used. If a modifier_device ofNULL is
                            specified, the X keyboard will be used as the
                            modifier_device.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>grab_window</parameter></term>
                    <listitem><para>Specifies the grab window.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>owner_events</parameter></term>
                    <listitem><para>Specifies a Boolean value that indicates
                            whether the deviceevents are to be reported as
                            usual or reported with respect to the grab
                            windowif selected by the event list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_count</parameter></term>
                    <listitem><para>Specifies the number of event classes in
                            the event list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_list</parameter></term>
                    <listitem><para>Specifies which device events are reported
                            to the client.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>this_device_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from this device.You can pass
                            <constant>GrabModeSync</constant> or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>other_devices_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from other devices.You can pass
                            <constant>GrabModeSync</constant>or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <constant>XGrabDeviceKey</constant> request establishes a
            passive grab. In the future, the device is actively grabbed (as
            for <constant>XGrabDevice</constant>, the last-device-grab time is
            set to the time at which the Key was pressed (as transmitted in
            the <constant>DeviceKeyPress</constant> event), and the
            <constant>DeviceKeyPress</constant> event is reported if all of
            the following conditions are true:

            <itemizedlist>
                <listitem>
                    <para>The device is not grabbed, and the specified key is
                        logically pressed when the specified modifier keys are
                        logically down, and no other keys or modifier keys are
                        logically down.
                    </para>
                </listitem>
                <listitem>
                    <para>The grab_window is an ancestor (or is) the focus
                        window OR the grab window is a descendant of the focus
                        window and contains the device.
                    </para>
                </listitem>
                <listitem>
                    <para>The confine_to window (if any) is
                        viewable.
                    </para>
                </listitem>
                <listitem>
                    <para>A passive grab on the same key/modifier combination
                        does not exist on any ancestor of grab_window.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            The interpretation of the remaining arguments is as for
            <constant>XGrabDevice</constant>. The active grab is terminated
            automatically when the logical state of the device has the
            specified key released.
        </para>
        <para>
            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.
        </para>
        <para>
            If the key is not <constant>AnyKey</constant>, it must be in the
            range specified by min_keycode and max_keycode as returned by the
            <constant>XListInputDevices</constant> request. Otherwise, a
            <constant>BadValue</constant> error results.
        </para>
        <para>
            This request overrides all previous grabs by the same client on
            the same Key/modifier combinations on the same window. A modifier
            of <constant>AnyModifier</constant> is equivalent to issuing the
            grab 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
            <constant>AnyKey</constant> is equivalent to issuing the request
            for all possible keys. Otherwise, it is not required that the
            specified key currently be assigned to a physical Key.
        </para>
        <para>
            If a modifier_device of NULL is specified, the X keyboard will be
            used as the modifier_device.
        </para>
        <para>
            If some other client has already issued a
            <constant>XGrabDeviceKey</constant> with the same Key/modifier
            combination on the same window, a <constant>BadAccess</constant>
            error results. When using <constant>AnyModifier</constant> or
            <constant>AnyKey</constant>, the request fails completely, and a
            <constant>BadAccess</constant> error results (no grabs are
            established) if there is a conflicting grab for any
            combination.<constant>XGrabDeviceKey</constant> has no effect on
            an active grab.
        </para>
        <para>
            <constant>XGrabDeviceKey</constant> can generate
            <constant>BadAccess</constant>, <constant>BadClass</constant>,
            <constant>BadDevice</constant>, <constant>BadMatch</constant>,
            <constant>BadValue</constant>, and <constant>BadWindow</constant>
            errors. It returns <constant>Success</constant> on successful
            completion of the request.
        </para>
        <para>
            The <constant>XUngrabDeviceKey</constant> request releases the
            passive grab for a key/modifier combination on the specified
            window if it was grabbed by this client. A modifier of
            <constant>AnyModifier</constant> is equivalent to issuing the
            ungrab request for all possible modifier combinations, including
            the combination of no modifiers. A Key of
            <constant>AnyKey</constant> is equivalent to issuing the request
            for all possible Keys.<constant>XUngrabDeviceKey</constant> has no
            effect on an active grab.
        </para>
        <para>
            If a modifier_device of NULL is specified, the X keyboard will be
            used as the modifier_device.
        </para>
        <para>
            <constant>XUngrabDeviceKey</constant> can generate
            <constant>BadDevice</constant>, <constant>BadMatch</constant>,
            <constant>BadValue</constant> and <constant>BadWindow</constant>
            errors.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGrabDeviceKey</constant> request was
                            made specifying a device that has no keys, or a
                            modifier device that has no keys.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted. Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XAllowDeviceEvents(3), XGrabDevice(3), XGrabDeviceButton(3)</para>
    </refsect1>
</refentry>

<refentry id="XGrabDevice.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGrabDevice</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XGrabDevice</refname>
	<refname>XUngrabDevice</refname>
        <refpurpose>grab/release the specified extension device</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef> int <function>XGrabDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>Bool <parameter>owner_events</parameter></paramdef>
                <paramdef>int <parameter>event_count</parameter></paramdef>
                <paramdef>XEventClass *<parameter>event_list</parameter></paramdef>
                <paramdef>int <parameter>this_device_mode</parameter></paramdef>
                <paramdef>int <parameter>other_devices_mode</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XUngrabDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device to be grabbed or
                            released.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>grab_window</parameter></term>
                    <listitem><para>Specifies the id of a window to be
                            associated with the device.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>owner_events</parameter></term>
                    <listitem><para>Specifies a Boolean value that indicates
                            whether theevents from the deviceare to be
                            reported as usual or reported with respect to the
                            grab windowif selected by the event list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_count</parameter></term>
                    <listitem><para>Specifies the number of elements in the
                            event_list array.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_list</parameter></term>
                    <listitem><para>Specifies a pointer to a list of event
                            classes that indicates which eventsthe client
                            wishes to receive. These event classes must have
                            beenobtained specifying the device being grabbed.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>this_device_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from this device.You can pass
                            <constant>GrabModeSync</constant>or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>other_devices_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from other devices.You can pass
                            <constant>GrabModeSync</constant>or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>time</parameter></term>
                    <listitem><para>Specifies the time.You can pass either a
                            timestamp or <constant>CurrentTime</constant>.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The <constant>XGrabDevice</constant> request actively grabs
            control of the device and generates
            <constant>DeviceFocusIn</constant> and
            <constant>DeviceFocusOut</constant> events. Further device events
            are reported only to the grabbing
            client.<constant>XGrabDevice</constant> overrides any active
            device grab by this client. event_list 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
            <constant>False</constant>, all generated device events are
            reported with respect to grab_window if selected. If owner_events
            is <constant>True</constant> and if a generated device 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 the event_list.
        </para>
        <para>
            If the this_device_mode argument is
            <constant>GrabModeAsync</constant>, device event processing
            continues as usual. If the device is currently frozen by this
            client, then processing of device events is resumed. If the
            this_device_mode argument is <constant>GrabModeSync</constant>,
            the state of the device (as seen by client applications) appears
            to freeze, and the X server generates no further device events
            until the grabbing client issues a releasing
            <constant>XAllowDeviceEvents</constant> call or until the device
            grab is released. Actual device changes are not lost while the
            device is frozen; they are simply queued in the server for later
            processing.
        </para>
        <para>
            If other_devices_mode is <constant>GrabModeAsync</constant>,
            processing of events from other devices is unaffected by
            activation of the grab. If other_devices_mode is
            <constant>GrabModeSync</constant>, the state of all devices except
            the grabbed device (as seen by client applications) appears to
            freeze, and the X server generates no further events from those
            devices until the grabbing client issues a releasing
            <constant>XAllowDeviceEvents</constant> call or until the device
            grab is released. Actual events are not lost while the devices are
            frozen; they are simply queued in the server for later processing.
        </para>
        <para>
            If the device is actively grabbed by some other client,
            <constant>XGrabDevice</constant> fails and returns
            <constant>AlreadyGrabbed</constant>. If grab_window is not
            viewable, it fails and returns
            <constant>GrabNotViewable</constant>. If the device is frozen by
            an active grab of another client, it fails and returns
            <constant>GrabFrozen</constant>. If the specified time is earlier
            than the last-device-grab time or later than the current X server
            time, it fails and returns <constant>GrabInvalidTime</constant>.
            Otherwise, the last-device-grab time is set to the specified time
            <constant>( CurrentTime</constant> is replaced by the current X
            server time).
        </para>
        <para>
            If a grabbed device is closed by a client while an active grab by
            that client is in effect, the active grab is released. If the
            device is frozen only by an active grab of the requesting client,
            it is thawed.
        </para>
        <para>
            <constant>XGrabDevice</constant> can generate
            <constant>BadClass</constant>, <constant>BadDevice</constant>,
            <constant>BadValue</constant>, and <constant>BadWindow</constant>
            errors.
        </para>
        <para>
            The <constant>XUngrabDevice</constant> request releases the device
            and any queued events if this client has it actively grabbed from
            either <constant>XGrabDevice</constant> or
            <constant>XGrabDeviceKey</constant>. If other devices are frozen
            by the grab, <constant>XUngrabDevice</constant> thaws
            them.<constant>XUngrabDevice</constant> 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 <constant>DeviceFocusIn</constant> and
            <constant>DeviceFocusOut</constant> events. The X server
            automatically performs an <constant>UngrabDevice</constant>
            request if the event window for an active device grab becomes not
            viewable.
        </para>
        <para>
            <constant>XUngrabDevice</constant> can generate a
            <constant>BadDevice</constant> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted. Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XAllowDeviceEvents(3),XGrabDeviceButton(3),XGrabDeviceKey(3)</para>
    </refsect1>
</refentry>

<refentry id="XListInputDevices.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XListInputDevices</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
	<refname>XListInputDevices</refname>
	<refname>XFreeDeviceList</refname>
        <refpurpose>list available input devices</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>XDeviceInfo *<function>XListInputDevices</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int *<parameter>ndevices_return</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XFreeDeviceList</function></funcdef>
                <paramdef>XDeviceInfo *<parameter>list</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>ndevices_return</parameter></term>
                    <listitem><para>Specifies a pointer to a variable where
                            the number of available devices canbe returned.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>list</parameter></term>
                    <listitem><para>Specifies the list of devices to free. The
                            <constant>XFreeDeviceList</constant> functionfrees
                            the list of available extension input devices.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The <constant>XListInputDevices</constant> request lists the
            available input devices. This list includes the core keyboard
            and any physical input device
            currently accessible through the X server, and any input devices
            that are not currently accessible through the X server but could
            be accessed if requested.
        </para>
        <para>
            A master pointer is a virtual pointer device that does not
            represent a physical device. It is visually represented through a
            cursor. A master keyboard is a virtual keyboard device that does
            not represent a physical device. It is virtually representd
            through a keyboard focus. A master pointer and a master keyboard
            are always paired (i.e. if shift is pressed on the master
            keyboard, a pointer click would be a shift-click). Multiple master
            pointer/keyboard pairs can exist.
        </para>
        <para>
            X servers supporting the X Input Extension version 2,
            <constant>XListInputDevices</constant> only returns the first
            master pointer, the first master keyboard and all slave
            devices. Additional master devices are not listed.
        </para>
        <para>
            Physical devices (so-called slave devices) are attached to either
            a master pointer or a master keyboard, depending on their
            capabilities. If a slave device generates an event, the event is
            also generated by the respective master device. Multiple slave
            devices can be attached to a single master device.
        </para>
        <para>
            Some server implementations may make all physical input devices
            available at the time the server is initialized. Others may wait
            until requested by a client to access an input device. In the
            latter case, it is possible that an input device will be listed as
            available at one time but not at another.
        </para>
        <para>
            For each input device available to the server, the
            XListInputDevices request returns an XDeviceInfo structure. That
            structure contains a pointer to a list of structures, each of
            which contains information about one class of input supported by
            the device. The XDeviceInfo structure is defined as follows:

            <synopsis>
                typedef struct _XDeviceInfo {
                XID     <structfield>id</structfield>;
                Atom    <structfield>type</structfield>;
                char    *<structfield>name</structfield>;
                int	    <structfield>num_classes</structfield>;
                int	    <structfield>use</structfield>;
                XAnyClassPtr <structfield>inputclassinfo</structfield>;
                } <structname>XDeviceInfo</structname>;
            </synopsis>
        </para>

        <para>
            The id is a number in the range 0-128 that uniquely identifies the
            device. It is assigned to the device when it is initialized by the
            server.
        </para>
        <para>
            The type field is of type Atom and indicates the nature of the
            device.
        </para>
        <para>
            The name field contains a pointer to a null-terminated string that
            corresponds to one of the defined device types. The name will
            correspond to one of the following strings (defined in the header
            file <constant>XI.h</constant>:
        </para>
        <para>
            <constant>XI_MOUSE</constant> 
            <constant>XI_TABLET</constant>
            <constant>XI_KEYBOARD</constant>
            <constant>XI_TOUCHSCREEN</constant>
            <constant>XI_TOUCHPAD</constant> 
            <constant>XI_BUTTONBOX</constant>
            <constant>XI_BARCODE</constant> 
            <constant>XI_TRACKBALL</constant>
            <constant>XI_QUADRATURE</constant>
            <constant>XI_ID_MODULE</constant> 
            <constant>XI_ONE_KNOB</constant>
            <constant>XI_NINE_KNOB</constant> 
            <constant>XI_KNOB_BOX</constant>
            <constant>XI_SPACEBALL</constant>
            <constant>XI_DATAGLOVE</constant>
            <constant>XI_EYETRACKER</constant>
            <constant>XI_CURSORKEYS</constant>
            <constant>XI_FOOTMOUSE</constant>
            <constant>XI_JOYSTICK</constant>
        </para>
        <para>
            These names may be directly compared with the name field of the
            XDeviceInfo structure, or used in an XInternAtom request to return
            an atom that can be compared with the type field of the
            XDeviceInfo structure.
        </para>
        <para>
            The num_classes field is a number in the range 0-255 that
            specifies the number of input classes supported by the device for
            which information is returned by ListInputDevices. Some input
            classes, such as class Focus and class Proximity do not have any
            information to be returned by ListInputDevices.
        </para>
        <para>
            All devices provide an AttachClass. This class specifies the
            master device a given slave device is attached to. For master
            devices, the class specifies the respective paired master device.
        </para>
        <para>
            The use field specifies how the device is currently being used. If
            the value is <constant>IsXKeyboard</constant>, the device is a
            master keyboard. If the value is <constant>IsXPointer</constant>,
            the device is a master pointer. If the value is
            <constant>IsXExtensionPointer</constant>, the device is a slave
            pointer. If the value is
            <constant>IsXExtensionKeyboard</constant>, the device is a slave
            keyboard. If the value is <constant>IsXExtensionDevice</constant>,
            the device is available for use as an extension device.
        </para>
        <para>
            The inputclassinfo field contains a pointer to the first
            input-class specific data. The first two fields are common to all
            classes.
        </para>
        <para>
            The class field is a number in the range 0-255. It uniquely
            identifies the class of input for which information is returned.
            Currently defined classes are KeyClass, ButtonClass, and
            ValuatorClass.
        </para>
        <para>
            The length field is a number in the range 0- 255. It specifies the
            number of bytes of data that are contained in this input class.
            The length includes the class and length fields.
        </para>
        <para>
            The XKeyInfo structure describes the characteristics of the keys
            on the device. It is defined as follows: 
        </para>
        <para>
            <synopsis>
                typedef struct _XKeyInfo {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                unsigned short <structfield>min_keycode</structfield>;
                unsigned short <structfield>max_keycode</structfield>;
                unsigned short <structfield>num_keys</structfield>;
                } <structname>XKeyInfo</structname>;

            </synopsis>
        </para>
        <para>
            min_keycode is of type KEYCODE. It specifies the minimum keycode
            that the device will report. The minimum keycode will not be
            smaller than 8.
        </para>
        <para>
            max_keycode is of type KEYCODE. It specifies the maximum keycode
            that the device will report. The maximum keycode will not be
            larger than 255.
        </para>
        <para>
            num_keys specifies the number of keys that the device has.
        </para>
        <para>
            The XButtonInfo structure defines the characteristics of the
            buttons on the device. It is defined as follows: 
        </para>
        <para>
            <synopsis>
                typedef struct _XButtonInfo {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                short <structfield>num_buttons</structfield>;
                } <structname>XButtonInfo</structname>;
            </synopsis>
        </para>
        <para>
            num_buttons specifies the number of buttons that the device has.
        </para>
        <para>
            The XValuatorInfo structure defines the characteristics of the
            valuators on the device. It is defined as follows: 
        </para>
        <para>
            <synopsis>
                typedef struct	_XValuatorInfo {
                XID <structfield>class</structfield>;
                int <structfield>length</structfield>;
                unsigned char <structfield>num_axes</structfield>;
                unsigned char <structfield>mode</structfield>;
                unsigned long <structfield>motion_buffer</structfield>;
                XAxisInfoPtr <structfield>axes</structfield>;
                } <structname>XValuatorInfo</structname>;
            </synopsis>
        </para>
        <para>
            num_axes contains the number of axes the device supports.
        </para>
        <para>
            mode is a constant that has one of the following values: Absolute
            or Relative. Some devices allow the mode to be changed dynamically
            via the SetDeviceMode request.
        </para>
        <para>
            motion_buffer_size is a cardinal number that specifies the number
            of elements that can be contained in the motion history buffer for
            the device.
        </para>
        <para>
            The axes field contains a pointer to an XAxisInfo structure.
        </para>
        <para>
            The XAxisInfo structure is defined as follows: 
        </para>
        <para>
            <synopsis>
                typedef struct _XAxisInfo {
                int <structfield>resolution</structfield>;
                int <structfield>min_value</structfield>;
                int <structfield>max_value</structfield>;
                } <structname>XAxisInfo</structname>;
            </synopsis>
        </para>
        <para>
            The resolution contains a number in counts/meter.
        </para>
        <para>
            The min_val field contains a number that specifies the minimum
            value the device reports for this axis. For devices whose mode is
            Relative, the min_val field will contain 0.
        </para>
        <para>
            The max_val field contains a number that specifies the maximum
            value the device reports for this axis. For devices whose mode is
            Relative, the max_val field will contain 0.
        </para>
        <para>
            The XAttachInfo structure is defined as follows: 

            <synopsis>
                typedef struct _XAttachInfo {
                int	<structfield>attached</structfield>;
                } <structname>XAttachInfo</structname>;
            </synopsis>
        </para>
        <para>
            If the device is a slave device, attached specifies the device ID
            of the master device this device is attached to. If the device is
            not attached to a master device, attached is
            <constant>Floating</constant>. If the device is a master device,
            attached specifies the device ID of the master device this device
            is paired with.
        </para>
        <para>
            To free the <constant>XDeviceInfo</constant> array created by
            <constant>XListInputDevices</constant>, use
            <constant>XFreeDeviceList</constant>.
        </para>
    </refsect1>
</refentry>

<refentry id="XOpenDevice.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XOpenDevice</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XOpenDevice</refname>
	<refname>XCloseDevice</refname>
        <refpurpose>open or close an extension input device</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>XDevice *<function>XOpenDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XID <parameter>device_id</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef><function>XCloseDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device_id</parameter></term>
                    <listitem><para>Specifies the id of the device to be
                            opened</para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device to be
                            closed</para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The <constant>XOpenDevice</constant> request makes an input
            device accessible to a client through input extension protocol
            requests. If successful, it returns a pointer to an
            <constant>XDevice</constant> structure.
        </para>
        <para>
            The <constant>XCloseDevice</constant> request makes an input
            device inaccessible to a client through input extension protocol
            requests. Before terminating, and client that has opened input
            devices through the input extension should close them via
            <constant>CloseDevice</constant>.
        </para>
        <para>
            When a client makes an <constant>XCloseDevice</constant> request,
            any active grabs that the client has on the device are released.
            Any event selections that the client has are deleted, as well as
            any passive grabs. If the requesting client is the last client
            accessing the device, the server may disable all access by X to
            the device.
        </para>
        <para>
            <constant>XOpenDevice</constant> and
            <constant>XCloseDevice</constant> can generate a
            <constant>BadDevice</constant> error.
        </para>
    </refsect1>
    <refsect1><title>Structures</title>
        <para>
            The <constant>XDevice</constant> structure returned by
            <constant>XOpenDevice</constant> contains:

            <synopsis>
                typedef struct {
                XID <structfield>device_id</structfield>;
                int <structfield>num_classes</structfield>;
                XInputClassInfo *<structfield>classes</structfield>;
                } <structname>XDevice</structname>;
            </synopsis>
        </para>
        <para>
            The classes field is a pointer to an array of XInputClassInfo
            structures. Each element of this array contains an event type base
            for a class of input supported by the specified device. The
            num_classes field indicates the number of elements in the classes
            array.
        </para>
        <para>
            The <constant>XInputClassInfo</constant> structure contains: 
        </para>
        <para>
            <synopsis>
                typedef struct {
                    unsigned char <structfield>input_class</structfield>;
                    unsigned char <structfield>event_type_base</structfield>;
                } <structname>XInputClassInfo</structname>;
            </synopsis>
        </para>
        <para>
            The input_class field identifies one class of input supported by
            the device. Defined types include <constant>KeyClass</constant>,
            <constant>ButtonClass</constant>,
            <constant>ValuatorClass</constant>,
            <constant>ProximityClass</constant>,
            <constant>FeedbackClass</constant>,
            <constant>FocusClass</constant>, and
            <constant>OtherClass</constant>. The event_type_base identifies
            the event type of the first event in that class.
        </para>
        <para>
            The information contained in the
            <constant>XInputClassInfo</constant> structure is used by macros
            to obtain the event classes that clients use in making
            <constant>XSelectExtensionEvent</constant> requests. Currently
            defined macros include <constant>DeviceKeyPress</constant>,
            <constant>DeviceKeyRelease</constant>,
            <constant>DeviceButtonPress</constant>,
            <constant>DeviceButtonRelese</constant>,
            <constant>DeviceMotionNotify</constant>,
            <constant>DeviceFocusIn</constant>,
            <constant>DeviceFocusOut</constant>,
            <constant>ProximityIn</constant>,
            <constant>ProximityOut</constant>,
            <constant>DeviceStateNotify</constant>,
            <constant>DeviceMappingNotify</constant>,
            <constant>ChangeDeviceNotify</constant>,
            <constant>DevicePointerMotionHint</constant>,
            <constant>DeviceButton1Motion</constant>,
            <constant>DeviceButton2Motion</constant>,
            <constant>DeviceButton3Motion</constant>,
            <constant>DeviceButton4Motion</constant>,
            <constant>DeviceButton5Motion</constant>,
            <constant>DeviceButtonMotion</constant>,
            <constant>DeviceOwnerGrabButton</constant>,
            <constant>DeviceButtonPressGrab</constant>, and
            <constant>NoExtensionEvent</constant>.
        </para>
        <para>
            To obtain the proper event class for a particular device, one of
            the above macros is invoked using the <constant>XDevice</constant>
            structure for that device. For example, 
            <synopsis>
                DeviceKeyPress (*device, type, eventclass);
            </synopsis>
        </para>
        <para>
            returns the <constant>DeviceKeyPress</constant> event type and the
            eventclass for <constant>DeviceKeyPress</constant> events from the
            specified device.
        </para>
        <para>
            This <constant>eventclass</constant> can then be used in an
            <constant>XSelectExtensionEvent</constant> request to ask the
            server to send <constant>DeviceKeyPress</constant> events from
            this device. When a selected event is received via
            <constant>XNextEvent</constant>, the <constant>type</constant> can
            be used for comparison with the type in the event.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist, or is the X
                            keyboard or X pointer. This error may also occur
                            if some other client has caused the specified
                            device to become the X keyboard or X pointer
                            device via the
                            <constant>XChangeKeyboardDevice</constant> or
                            <constant>XChangePointerDevice</constant>
                            requests.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XQueryDeviceState.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XQueryDeviceState</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XQueryDeviceState</refname>
        <refpurpose>query the state of an extension input device.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XQueryDeviceState</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose state is to be
                            queried.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The <constant>XQueryDeviceState</constant> request queries the
            state of an input device. The current state of keys and buttons
            (up or down), and valuators (current value) on the device is
            reported by this request. Each key or button is represented by a
            bit in the <constant>XDeviceState</constant> structure that is
            returned. Valuators on the device report 0 if they are reporting
            relative information, and the current value if they are reporting
            absolute information.
        </para>
        <para>
            <constant>XQueryDeviceState</constant> can generate a
            <constant>BadDevice</constant> error.
        </para>
    </refsect1>
    <refsect1><title>Structures</title>
        <para>
            The <constant>XDeviceState</constant> structure contains: </para>
        <para>
            <synopsis>
                typedef struct {
                    XID <structfield>device_id</structfield>;
                    int <structfield>num_classes</structfield>;
                    XInputClass *<structfield>data</structfield>;
                } <structname>XDeviceState</structname>;
            </synopsis>
        </para>
        <para>
            The <constant>XValuatorState</constant> structure contains: </para>
        <para>
            <synopsis>
                typedef struct {
                    unsigned char <structfield>class</structfield>;
                    unsigned char <structfield>length</structfield>;
                    unsigned char <structfield>num_valuators</structfield>;
                    unsigned char <structfield>mode</structfield>;
                    int *<structfield>valuators</structfield>;
                } <structname>XValuatorState</structname>;
            </synopsis>
        </para>
        <para>
            The <constant>XKeyState</constant> structure contains: </para>
        <para>
            <synopsis>
                typedef struct {
                    unsigned char <structfield>class</structfield>;
                    unsigned char <structfield>length</structfield>;
                    short     <structfield>num_keys</structfield>;
                    char <structfield>keys</structfield>[32];
                } <structname>XKeyState</structname>;
            </synopsis>
        </para>
        <para>
            The <constant>XButtonState</constant> structure contains: </para>
        <para>
            <synopsis>
                typedef struct {
                    unsigned char <structfield>class</structfield>;
                    unsigned char <structfield>length</structfield>;
                    short     <structfield>num_buttons</structfield>;
                    char <structfield>buttons</structfield>[32];
                } <structname>XButtonState</structname>;
            </synopsis>
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if some other client has caused the
                            specified device to become the X keyboard or X
                            pointer device via the
                            <constant>XChangeKeyboardDevice</constant> or
                            <constant>XChangePointerDevice</constant>
                            requests.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>


<refentry id="XSelectExtensionEvent.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XSelectExtensionEvent</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XSelectExtensionEvent</refname>
	<refname>XGetSelectedExtensionEvents</refname>
        <refpurpose>select extension events, get the list of currently
            selected extension events</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef><function>XSelectExtensionEvent</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>Window <parameter>w</parameter></paramdef>
                <paramdef>XEventClass *<parameter>event_list</parameter></paramdef>
                <paramdef>int <parameter>event_count</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef><function>XGetSelectedExtensionEvents</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>Window <parameter>w</parameter></paramdef>
                <paramdef>int <parameter>this_client_event_count_return</parameter></paramdef>
                <paramdef>XEventClass *<parameter>this_client_event_list_return</parameter></paramdef>
                <paramdef>int <parameter>all_clients_event_count_return</parameter></paramdef>
                <paramdef>XEventClass *<parameter>all_clients_event_list_return</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>w</parameter></term>
                    <listitem><para>Specifies the window whose events you
                            are interested in.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_list</parameter></term>
                    <listitem><para>Specifies the list of event classes
                            that describe the events you are interested
                            in.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>event_count</parameter></term>
                    <listitem><para>Specifies the count of event classes
                            in the event list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>this_client_event_count_return</parameter></term>
                    <listitem><para>Returns the count of event classes
                            selected by this client.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>this_client_event_list_return</parameter></term>
                    <listitem><para>Returns a pointer to the list of event
                            classes
                            selected by this client.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>all_clients_event_count_return</parameter></term>
                    <listitem><para>Returns the count of event classes
                            selected by all clients.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>all_clients_event_list_return</parameter></term>
                    <listitem><para>Returns a pointer to the list of event
                            classes selected by all clients.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
    <refsect1><title>Description</title>
        <para>
            The <constant>XSelectExtensionEvent</constant> request causes
            the X server to report the events associated with the
            specified list of event classes.  Initially, X will not report
            any of these events.  Events are reported relative to a
            window.  If a window is not interested in a device event, it
            usually propagates to the closest ancestor that is interested,
            unless the do_not_propagate mask prohibits it.  </para><para>

            Multiple clients can select for the same events on the same window
            with the following restrictions:
            <itemizedlist>
                <listitem>
                    <para>
                        Multiple clients can select events on the same
                        window because their event masks are disjoint.
                        When the X server generates an event, it reports
                        it to all interested clients.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Only one client at a time can select a
                        <constant>DeviceButtonPress</constant> event with
                        automatic passive grabbing enabled, which is
                        associated with the event class
                        <constant>DeviceButtonPressGrab</constant>.  To
                        receive <constant>DeviceButtonPress</constant>
                        events without automatic passive grabbing, use
                        event class <constant>DeviceButtonPress</constant>
                        but do not specify event class
                        <constant>DeviceButtonPressGrab</constant>.
                    </para>
                </listitem>
            </itemizedlist>
            The server reports the event to all interested clients.
            </para><para>

            Information contained in the <constant>XDevice</constant>
            structure returned by <constant>XOpenDevice</constant> is used by
            macros to obtain the event classes that clients use in making
            <constant>XSelectExtensionEvent</constant> requests.  Currently
            defined macros include <constant>DeviceKeyPress</constant>,
            <constant>DeviceKeyRelease</constant>,
            <constant>DeviceButtonPress</constant>,
            <constant>DeviceButtonRelese</constant>,
            <constant>DeviceMotionNotify</constant>,
            <constant>DeviceFocusIn</constant>,
            <constant>DeviceFocusOut</constant>,
            <constant>ProximityIn</constant>,
            <constant>ProximityOut</constant>,
            <constant>DeviceStateNotify</constant>,
            <constant>DeviceMappiingNotify</constant>,
            <constant>ChangeDeviceNotify</constant>,
            <constant>DevicePointerMotionHint</constant>,
            <constant>DeviceButton1Motion</constant>,
            <constant>DeviceButton2Motion</constant>,
            <constant>DeviceButton3Motion</constant>,
            <constant>DeviceButton4Motion</constant>,
            <constant>DeviceButton5Motion</constant>,
            <constant>DeviceButtonMotion</constant>,
            <constant>DeviceOwnerGrabButton</constant>,
            <constant>DeviceButtonPressGrab</constant>, and
            <constant>NoExtensionEvent</constant>.  </para><para>

            To obtain the proper event class for a particular device, one of the above
            macros is invoked using the <constant>XDevice</constant> structure
            for that device. For example,
            <synopsis>
                DeviceKeyPress (*device, type, eventclass);
            </synopsis>
            returns the <constant>DeviceKeyPress</constant> event type and the
            eventclass for selecting <constant>DeviceKeyPress</constant>
            events from this device.
        </para>
        <para>
            <constant>XSelectExtensionEvent</constant> can generate a
            <constant>BadWindow</constant> or <constant>BadClass</constant>
            error.  The <constant>XGetSelectedExtensionEvents</constant>
            request reports the extension events selected by this client and
            all clients for the specified window.  This request returns
            pointers to two <constant>XEventClass</constant> arrays.  One
            lists the input extension events selected by this client from the
            specified window.  The other lists the event classes selected by
            all clients from the specified window.  You should use
            <constant>XFree</constant> to free these
            two arrays.
        </para>
        <para>
            <constant>XGetSelectedExtensionEvents</constant>
            can generate a <constant>BadWindow</constant> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadClass</errorname></term><listitem>
                        <para>
                            A value for an <constant>XEventClass</constant> is
                            invalid.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

</refentry>


<refentry id="XSendExtensionEvent.man">
        <refentryinfo>
            <productname>__vendorversion__</productname>
        </refentryinfo>

        <refmeta>
            <refentrytitle>XSendExtensionEvent</refentrytitle>
            <manvolnum>__libmansuffix__</manvolnum>
        <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
        <refnamediv>
             <refname>XSendExtensionEvent</refname>
             <refpurpose>send input extension events to a client</refpurpose>
        </refnamediv>
        <refsynopsisdiv>
            <title>Syntax</title>
            <funcsynopsis>
                <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
                <funcprototype>
                    <funcdef>Status <function>XSendExtensionEvent</function></funcdef>
                    <paramdef>Display *<parameter>display</parameter></paramdef>
                    <paramdef>XDevice *<parameter>device</parameter></paramdef>
                    <paramdef>Window <parameter>destination</parameter></paramdef>
                    <paramdef>Bool <parameter>propagate</parameter></paramdef>
                    <paramdef>int <parameter>event_count</parameter></paramdef>
                    <paramdef>XEventClass *<parameter>event_list</parameter></paramdef>
                    <paramdef>XEvent *<parameter>event_send</parameter></paramdef>
                </funcprototype>
            </funcsynopsis>
        </refsynopsisdiv>
        <refsect1><title>Arguments</title>

            <para>
                <variablelist>
                    <varlistentry><term><parameter>display</parameter></term>
                        <listitem><para>Specifies the connection to the X
                                server.
                        </para></listitem>
                    </varlistentry>
                    <varlistentry><term><parameter>device</parameter></term>
                        <listitem><para>Specifies the device from which the
                                events are to be sent.
                        </para></listitem>
                    </varlistentry>
                    <varlistentry><term><parameter>destination</parameter></term>
                        <listitem><para>Specifies the window the event is to
                                be sent to.  You can pass window id,
                                <constant>PointerWindow</constant>,or
                                <constant>InputFocus</constant>.
                        </para></listitem>
                    </varlistentry>
                    <varlistentry><term><parameter>propagate</parameter></term>
                        <listitem><para>Specifies a Boolean value that is
                                either True or False.
                        </para></listitem>
                    </varlistentry>
                    <varlistentry><term><parameter>event_count</parameter></term>
                        <listitem><para>Specifies the count of XEventClasses
                                in event_list.
                        </para></listitem>
                    </varlistentry>
                    <varlistentry><term><parameter>event_list</parameter></term>
                        <listitem><para>Specifies the list of event selections
                                to be used.
                        </para></listitem>
                    </varlistentry>
                    <varlistentry><term><parameter>event_send</parameter></term>
                        <listitem><para>Specifies a pointer to the event that
                                is to be sent.
                        </para></listitem>
                    </varlistentry>
                </variablelist>
            </para>
        </refsect1>
        <refsect1><title>Description</title>
            <para>
                The <constant>XSendExtensionEvent</constant> request
                identifies the destination
            window, determines which clients should receive the specified
            events, and ignores any active grabs.  This request requires you
            to pass an event class list.  For a discussion of the valid event
            class names, see
            <constant>XOpenDevice(__libmansuffix__)</constant>
            This request uses the w argument to identify the destination
            window as follows:
            <itemizedlist>
                <listitem>
                    <para>
                        If w is <constant>PointerWindow</constant>,the
                        destination window is the window that contains the
                        pointer.
                    </para>
                </listitem>
                <listitem>
                    <para>If w is <constant>InputFocus</constant>and if the
                        focus window contains the pointer,the destination
                        window is the window that contains the pointer;
                        otherwise, the destination window is the focus window.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            To determine which clients should receive the specified events,
            <constant>XSendExtensionEvent</constant>uses the propagate
            argument as follows:
            <itemizedlist>
                <listitem>
                    <para> If event_list is the empty set,the event is sent to
                        the client that created the destination window. If
                        that client no longer exists,no event is sent.
                    </para>
                </listitem>
                <listitem>
                    <para>If propagate is <constant>False</constant>,the event
                        is sent to every client selecting on destination any
                        of the eventtypes specified by the event_list array.
                    </para>
                </listitem>
                <listitem>
                    <para>If propagate is <constant>True</constant>and no
                        clients have selected on destination any ofthe events
                        specified by the event_list array,the destination is
                        replaced with theclosest ancestor of destination for
                        which some client has selected atype specified by the
                        event-list array and for which no interveningwindow
                        has that type in itsdo-not-propagate-mask. If no such
                        window exists or if the window isan ancestor of the
                        focus window and <constant>InputFocus</constant>was
                        originally specifiedas the destination, the event is
                        not sent to any clients. Otherwise, the event is
                        reported to every client selecting on the
                        finaldestination any of the events specified in the
                        event_list array.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            The event in the <constant>XEvent</constant>structure must be one
            of the events defined by the input extension (or a
            <constant>BadValue</constant>error results) so that the X server
            can correctly byte-swapthe contents as necessary. The contents of
            the event areotherwise unaltered and unchecked by the X server
            except to force send_event to <constant>True</constant>in the
            forwarded event and to set the serial number in the event
            correctly.
        </para>
        <para>
            <constant>XSendExtensionEvent</constant>returns zero if the
            conversion to wire protocol format failedand returns nonzero
            otherwise.<constant>XSendExtensionEvent</constant>can generate
            <constant>BadClass</constant>, <constant>BadDevice</constant>,
            <constant>BadValue</constant>, and <constant>BadWindow</constant>
            errors.
        </para>
    </refsect1>
    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem>
                        <para>
                            Some numeric value falls outside the range of
                            values accepted by the request.  Unless a specific
                            range is specified for an argument, the full range
                            defined by the argument's type is accepted.  Any
                            argument defined as a set of alternatives can
                            generate this error.
                        </para>
                        </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
</para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XSetDeviceButtonMapping.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XSetDeviceButtonMapping</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XSetDeviceButtonMapping</refname>
	<refname>XGetDeviceButtonMapping</refname>
        <refpurpose>query or change device button mappings</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XSetDeviceButtonMapping</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>unsigned char <parameter>map</parameter>[]</paramdef>
                <paramdef>int <parameter>nmap</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XGetDeviceButtonMapping</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>unsigned char <parameter>map_return</parameter>[]</paramdef>
                <paramdef>int <parameter>nmap</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose button mapping
                            is to be queried or changed.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>map</parameter></term>
                    <listitem><para>Specifies the mapping list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>map_return</parameter></term>
                    <listitem><para>Returns the mapping list.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>nmap</parameter></term>
                    <listitem><para>Specifies the number of items in the
                            mapping list.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The <constant>XSetDeviceButtonMapping</constant> request sets
            the mapping of the specified device. If it succeeds, the X server
            generates a <constant>DeviceMappingNotify</constant> event, and
            <constant>XSetDeviceButtonMapping</constant> returns
            <constant>MappingSuccess</constant>. Element map[i] defines the
            logical button number for the physical button i+1. The length of
            the list must be the same as
            <constant>XGetDeviceButtonMapping</constant> would return, or a
            <constant>BadValue</constant> error results. 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 <constant>BadValue</constant> error
            results. If any of the buttons to be altered are logically in the
            down state, <constant>XSetDeviceButtonMapping</constant> returns
            <constant>MappingBusy</constant>, and the mapping is not changed.
        </para>
        <para>
            <constant>XSetDeviceButtonMapping</constant> can generate
            <constant>BadDevice</constant>, <constant>BadMatch</constant>, and
            <constant>BadValue</constant> errors.
        </para>
        <para>
            The <constant>XGetDeviceButtonMapping</constant> request returns
            the current mapping of the specified device. Buttons are numbered
            starting from one.<constant>XGetDeviceButtonMapping</constant>
            returns the number of physical buttons actually on the device. The
            nominal mapping for a device is map[i]=i+1. The nmap argument
            specifies the length of the array where the device mapping is
            returned, and only the first nmap elements are returned in
            map_return.
        </para>
        <para>
            <constant>XGetDeviceButtonMapping</constant> can generate
            <constant>BadDevice</constant> or <constant>BadMatch</constant>
            errors.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>. This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetDeviceButtonMapping</constant> or
                            <constant>XSetDeviceButtonMapping</constant>
                            request was made specifying a device that has no
                            buttons.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted. Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XChangeDeviceKeyboardControl(3), XChangeDeviceKeyMapping(3),
            XChangeDeviceModifierMapping(3)</para>
    </refsect1>
</refentry>


<refentry id="XSetDeviceFocus.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XSetDeviceFocus</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XSetDeviceFocus</refname>
	<refname>XGetDeviceFocus</refname>
        <refpurpose>control extension input device focus</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef><function>XSetDeviceFocus</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Window <parameter>focus</parameter></paramdef>
                <paramdef>int  <parameter>revert_to</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef><function>XGetDeviceFocus</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Window *<parameter>focus_return</parameter></paramdef>
                <paramdef>int *<parameter>revert_to_return</parameter></paramdef>
                <paramdef>int * <parameter>time_return</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose focus is to be
                            queried or changed.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>focus</parameter></term>
                    <listitem><para>Specifies the window,
                            <constant>PointerRoot</constant>,
                            <constant>FollowKeyboard</constant>,or
                            <constant>None</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>focus_return</parameter></term>
                    <listitem><para>Returns the focus window,
                            <constant>PointerRoot</constant>,
                            <constant>FollowKeyboard</constant>,or
                            <constant>None</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>revert_to</parameter></term>
                    <listitem><para>Specifies where the input focus reverts to
                            if the window becomes notviewable.You can pass
                            <constant>RevertToParent</constant>,
                            <constant>RevertToPointerRoot</constant>,
                            <constant>RevertToFollowKeyboard</constant>,or
                            <constant>RevertToNone</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>revert_to_return</parameter></term>
                    <listitem><para>Returns the current focus state
                            <constant>RevertToParent</constant>,
                            <constant>RevertToPointerRoot</constant>,
                            <constant>RevertToFollowKeyboard</constant>,or
                            <constant>RevertToNone</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>time_return</parameter></term>
                    <listitem><para>Returns the last_focus_time for the
                            device.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>time</parameter></term>
                    <listitem><para>Specifies the time.You can pass either a
                            timestamp or <constant>CurrentTime</constant>.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The  <constant>XSetDeviceFocus</constant>  request changes the
            focus of the specified device and its last-focus-change time. It
            has no effect if the specified time is earlier than the current
            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
            <constant>CurrentTime</constant>  is replaced by the current X
            server time).  <constant>XSetDeviceFocus</constant>  causes the X
            server to generate  <constant>DeviceFocusIn</constant>  and
            <constant>DeviceFocusOut</constant>  events.
        </para>
        <para>
            Depending on the focus argument, the following occurs:

            <itemizedlist>
                <listitem><para> If focus is  <constant>None</constant> , all
                        device events are discarded until a new focus window
                        is set, and the revert_to argument is ignored.
                </para></listitem>
                <listitem><para>If focus is a window, it becomes the device's
                        focus window. If a generated device event would
                        normally be reported to this window or one of its
                        inferiors, the event is reported as usual. Otherwise,
                        the event is reported relative to the focus window.
                </para></listitem>
                <listitem><para>
                        If focus is  <constant>PointerRoot</constant>, the
                        focus window is dynamically taken to be the root
                        window of whatever screen the pointer is on at each
                        event from the specified device. In this case, the
                        revert_to argument is ignored.
                </para></listitem>
                <listitem><para>
                        If focus is  <constant>FollowKeyboard</constant>, the
                        focus window is dynamically taken to be the window to
                        which the X keyboard focus is set at each input event.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            The specified focus window must be viewable at the time
            <constant>XSetDeviceFocus</constant>  is called, or a
            <constant>BadMatch</constant>  error results. If the focus window
            later becomes not viewable, the X server evaluates the revert_to
            argument to determine the new focus window as follows:

            <itemizedlist>
                <listitem><para>If revert_to is
                        <constant>RevertToParent</constant>, the focus reverts
                        to the parent (or the closest viewable ancestor), and
                        the new revert_to value is taken to be
                        <constant>RevertToNone</constant>.
                </para></listitem>
                <listitem><para>
                        If revert_to is
                        <constant>RevertToPointerRoot</constant>,
                        <constant>RevertToFollowKeyboard</constant>, or
                        <constant>RevertToNone</constant>, the focus reverts
                        to  <constant>PointerRoot</constant>,
                        <constant>FollowKeyboard</constant>, or
                        <constant>None</constant>, respectively.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            When the focus reverts, the X server generates
            <constant>DeviceFocusIn</constant>  and
            <constant>DeviceFocusOut</constant>  events, but the
            last-focus-change time is not affected.
        </para>
        <para> Input extension devices are not required to support the ability
            to be focused. Attempting to set the focus of a device that does
            not support this request will result in a
            <constant>BadMatch</constant>  error.  Whether or not given device
            can support this request can be determined by the
            information returned by  <constant>XOpenDevice</constant>. For
            those devices that support focus,
            <constant>XOpenDevice</constant>  will return an
            <constant>XInputClassInfo</constant>  structure with the
            input_class field equal to the constant
            <constant>FocusClass</constant>  (defined in the file
            <constant>XI.h</constant>).
        </para>
        <para>
            <constant>XSetDeviceFocus</constant>  can generate
            <constant>BadDevice</constant>, <constant>BadMatch</constant>,
            <constant>BadValue</constant>, and
            <constant>BadWindow</constant> errors.
        </para>
        <para>
            The  <constant>XGetDeviceFocus</constant>  request returns the
            focus window and the current focus state.
        </para>
        <para>
            Not all input extension devices can be focused.  Attempting to
            query the focus state of a device that can't be focused results in
            a  <constant>BadMatch</constant>  error.  A device that can be
            focused returns information for input Class Focus when an
            <constant>XOpenDevice</constant>  request is made.
        </para>
        <para>
            <constant>XGetDeviceFocus</constant>  can generate
            <constant>BadDevice</constant>, and  <constant>BadMatch</constant>
            errors.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified.  The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>.  This error
                            may also occur if the specified device is the X
                            keyboard or X pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted.  Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XGetDeviceFocus</constant>  or
                            <constant>XSetDeviceFocus</constant>  request was
                            made specifying a device that the server
                            implementation does not allow to be focused.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>


<refentry id="XSetDeviceMode.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XSetDeviceMode</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XSetDeviceMode</refname>
        <refpurpose>change the mode of a device</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef><function>XSetDeviceMode</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>int  <parameter>mode</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose mode is to be
                            changed.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>mode</parameter></term>
                    <listitem><para>Specifies the mode.You can pass
                            <constant>Absolute</constant>,or
                            <constant>Relative</constant>.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The  <constant>XSetDeviceMode</constant>  request changes the
            mode of an input device that is capable of reporting either
            absolute positional information or relative motion information.
            Not all input devices are capable of reporting motion data, and
            not all are capable of changing modes from
            <constant>Absolute</constant>  to  <constant>Relative</constant>.
        </para>
        <para>
            <constant>XSetDeviceMode</constant>  can generate a
            <constant>BadDevice</constant>  or  <constant>BadMode</constant>
            error.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified.  The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>.  This error
                            may also occur if some other client has caused the
                            specified device to become the X keyboard or X
                            pointer device via the
                            <constant>XChangeKeyboardDevice</constant>  or
                            <constant>XChangePointerDevice</constant>
                            requests.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XSetDeviceMode</constant>  request is
                            made specifying a device that has no valuators and
                            reports no axes of motion.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMode</errorname></term>
                    <listitem><para>An invalid mode was specified.  This error
                            will also be returned if the specified device is
                            not capable of supporting the
                            <constant>XSetDeviceMode</constant>  request.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>


<refentry id="XSetDeviceValuators.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XSetDeviceValuators</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XSetDeviceValuators</refname>
        <refpurpose>initialize the valuators on an extension input device</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef><function>XSetDeviceValuators</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>int *<parameter>valuators</parameter></paramdef>
                <paramdef>int <parameter>first_valuator</parameter></paramdef>
                <paramdef>int <parameter>num_valuators</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device whose valuators are
                            to be initialized.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>valuators</parameter></term>
                    <listitem><para>Specifies a pointer to an array of integer
                            values to be used to initialize thedevice
                            valuators.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>first_valuator</parameter></term>
                    <listitem><para>Specifies the first valuator to be set.
                            Valuators are numbered beginning withzero.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>num_valuators</parameter></term>
                    <listitem><para>Specifies the number of valuators to be
                            set.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>The  <constant>XSetDeviceValuators</constant>  request sets the
            current values of the valuators of an input device. The valuators
            in the range first_valuator to (first_valuator + num_valuators)
            are set to the specified values.  Valuators are numbered beginning
            with 0. Not all input devices support initialization of valuator
            values.  If this request is made to a device that does not support
            valuators initialization, a  <constant>BadMatch</constant>  error
            will occur.
        </para>
        <para>
            If the request succeeds, a status of Success is returned.  If
            another client has the device grabbed, a status of AlreadyGrabbed
            is returned.
        </para>
        <para>
            <constant>XSetDeviceValuators</constant>  can generate a
            <constant>BadLength</constant>,  <constant>BadDevice</constant> ,
            <constant>BadMatch</constant>, or  <constant>BadValue</constant>
            error.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified.  The
                            specified device does not exist or has not been
                            opened by this client via
                            <constant>XOpenInputDevice</constant>.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if an
                            <constant>XSetDeviceValuators</constant>  request
                            is made specifying a device that has no valuators
                            and reports no axes of motion, or if such a
                            request is made specifying a device that does not
                            support valuator initialization.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>An invalid first_valuator or num_valuators
                            values was specified.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

</refentry>

<!-- XI 1.5 -->
<refentry id="XListDeviceProperty.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>July 9, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XListDeviceProperties</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
    </refmeta>
    <refnamediv>
        <refname>XListDeviceProperties</refname>
        <refpurpose>List a device's properties.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Atom* <function>XListDeviceProperties</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>int *<parameter>nprops_return</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>device</parameter></term>
                    <listitem><para>The device to grab.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>nprops_return</parameter></term>
		    <listitem><para>Specifies the number of Atoms returned.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>num_values</parameter></term>
		    <listitem><para>Specifies the number of elements in the
                            values list.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>property</parameter></term>
		    <listitem><para>Specifies the property to modify or query.</para></listitem>
		</varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <function>XListDeviceProperties</function> function returns a
            list of the properties associated with the input device specified
            in <parameter>device</parameter>.
            Each device may have an arbitrary number of properties attached,
            some of which were created by the driver and/or server, others
            created by clients at runtime.
        </para>
        <para>The client is expected to free the list of properties using
            <function>XFree</function>.</para>
        <para>
            <function>XListDeviceProperties</function> can generate a
            <errorname>BadDevice</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadAtom</errorname></term>
                    <listitem><para>A value does not describe a valid named
                            identifier.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            device does not exist.
</para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>
            <function>XChangeDeviceProperty</function>,
            <function>XGetDeviceProperty</function>,
            <function>XDeleteDeviceProperty</function>.
        </para>
    </refsect1>
</refentry>

<refentry id="XGetDeviceProperties.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>July 9, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XGetDeviceProperty</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
    </refmeta>
    <refnamediv>
        <refname>XGetDeviceProperty</refname>
        <refname>XChangeDeviceProperty</refname>
        <refname>XDeleteDeviceProperty</refname>
        <refpurpose>Get, change or delete a device's property.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XGetDeviceProperty</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Atom <parameter>property</parameter></paramdef>
                <paramdef>long <parameter>offset</parameter></paramdef>
                <paramdef>long <parameter>length</parameter></paramdef>
                <paramdef>Bool <parameter>delete</parameter></paramdef>
                <paramdef>Bool <parameter>pending</parameter></paramdef>
                <paramdef>Atom <parameter>req_type</parameter></paramdef>
                <paramdef>Atom *<parameter>actual_type_return</parameter></paramdef>
                <paramdef>int *<parameter>actual_format_return</parameter></paramdef>
                <paramdef>unsigned long *<parameter>nitems_return</parameter></paramdef>
                <paramdef>unsigned long *<parameter>bytes_after_return</parameter></paramdef>
                <paramdef>unsigned char **<parameter>prop_return</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>void <function>XChangeDeviceProperty</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Atom <parameter>property</parameter></paramdef>
                <paramdef>Atom <parameter>type</parameter></paramdef>
                <paramdef>int <parameter>format</parameter></paramdef>
                <paramdef>int <parameter>mode</parameter></paramdef>
                <paramdef>const char *<parameter>data</parameter></paramdef>
                <paramdef>int <parameter>nelements</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>void <function>XDeleteDeviceProperty</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XDevice *<parameter>device</parameter></paramdef>
                <paramdef>Atom <parameter>property</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>actual_type_return</parameter></term>
		    <listitem><para>Returns an atom identifier that defines
                            the actual type of the property.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>actual_format_return</parameter></term>
                    <listitem><para>Returns the actual format of the property.
                    </para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>bytes_after_return</parameter></term>
                    <listitem><para>Returns the number of bytes remaining to
                            be read in the property if a partial read was
                            performed.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>data</parameter></term>
                    <listitem><para>Specifies the property data.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>delete</parameter></term>
                    <listitem><para>Specifies a Boolean value that determines
                            wether the property is deleted.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>device</parameter></term>
                    <listitem><para>The device to grab.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>format</parameter></term>
                    <listitem><para>Specifies whether the data should be
                            viewed as a list of 8-bit, 16-bit, or 32-bit
                            quantities. Possible values are 8, 16, and 32.
                            This information allows the X server to correctly
                            perform byte-swap operations as necessary. If the
                            format is 16-bit or 32-bit, you must explicitly
                            cast the data pointer to an (unsigned char*) in
                            the call to
                            <function>XChangeDeviceProperty</function>.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>length</parameter></term>
		    <listitem><para>Specifies the length in 32-bit multiplies
                            of the data to be retrieved.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>mode</parameter></term>
		    <listitem><para>Specifies the mode of operation. You can
                            pass <constant>PropModeReplace</constant>,
                            <constant>PropModePrepend</constant>, or
                            <constant>PropModeAppend</constant>.
                     </para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>nelements</parameter></term>
		    <listitem><para>Specifies the number of elements in data.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>nitems_return</parameter></term>
		    <listitem><para>Returns the actual number of 8-bit,
                            16-bit, or 32-bit items stored in the prop_return
                            array.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>num_values</parameter></term>
		    <listitem><para>Specifies the number of elements in the
                            values list.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>offset</parameter></term>
		    <listitem><para>Specifies the offset in the specified
                            property (in 32-bit quantities) where the data is
                            to be retrieved.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>pending</parameter></term>
		    <listitem><para>Specifies whether to retrieve the pending
                            state of the property or the current state.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>property</parameter></term>
		    <listitem><para>Specifies the property to modify or query.</para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>prop_return</parameter></term>
                    <listitem><para>Returns the data in the specified format.
                            If the returned format is 8, the returned data is
                            represented as a char array. If the returned
                            format is 16, the returned data is represented as
                            an array of short int type and should be cast to
                            that type to obtain the elements. If the returned
                            format is 32, the property data will be stored as
                            an array of longs (which in a 64-bit application
                            will be 64-bit values that are padded in the upper
                            4 bytes).
                    </para></listitem>
		</varlistentry>
                <varlistentry>
                    <term><parameter>req_type</parameter></term>
		    <listitem><para>Specifies the atom identifier associated
                            with the property type or
                            <constant>AnyPropertyType</constant>.</para></listitem>
		</varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            The <function>XGetDeviceProperty</function> function returns 
            the actual type of the property; the actual format of the property;
            the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes
            remaining to be read in the property; and a pointer to the data actually
            returned.
            For a detailed description of this function, see the man page
            to <function>XGetWindowProperty</function>.
        </para>
	<para>
            The <function>XChangeDeviceProperty</function> function alters the
            property for the specified device and causes the server to
            generate a <function>XPropertyNotifyEvent</function> event on that
            device.
            For a detailed description of this function, see the man page to
            <function>XChangeProperty</function>.
	</para>
        <para>
            The <function>XDeleteDeviceProperty</function> function
            deletes the specified device property. Note that a client cannot
            delete a property created by a driver or the server. Attempting to
            do so will result in a <errorname>BadAtom</errorname> error.
        </para>
        <para>
            <function>XGetDeviceProperty</function> can generate a
            <errorname>BadAtom</errorname>,
            <errorname>BadDevice</errorname> error.
        </para>
        <para>
            <function>XChangeDeviceProperty</function> can generate a
            <errorname>BadDevice</errorname>, a
            <errorname>BadMatch</errorname>, a
            <errorname>BadAtom</errorname>, and a
            <errorname>BadValue</errorname> error.
        </para>
        <para>
            <function>XDeleteDeviceProperty</function> can generate a
            <errorname>BadDevice</errorname>, and a
            <errorname>BadAtom</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadAtom</errorname></term>
                    <listitem><para>A value does not describe a valid named
                            identifier or the client attempted to remove
                            a driver-allocated property.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            device does not exist.
</para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>
            <function>XListDeviceProperties</function>,
            <function>XQueryDeviceProperty</function>,
            <function>XConfigureDeviceProperty</function>.
        </para>
    </refsect1>
</refentry>
<!--- XI2 -->
<refentry id="XISetClientPointer.man">
  <refentryinfo>
    <productname>__vendorversion__</productname>
    <pubdate>February 14, 2008</pubdate>
    <authorgroup>
      <author>
        <firstname>Peter</firstname><surname>Hutterer</surname>
        <contrib>Specification and implementation.</contrib>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>XISetClientPointer, XIGetClientPointer</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
    </refmeta>
    <refnamediv>
        <refname>XISetClientPointer</refname>
	<refname>XIGetClientPointer</refname>
	<refpurpose>set or get the ClientPointer device.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
	<title>Syntax</title>
	<funcsynopsis>
	    <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
	    <funcprototype>
		<funcdef><function>XISetClientPointer</function></funcdef>
		<paramdef>Display *<parameter>display</parameter></paramdef>
		<paramdef>Window <parameter>win</parameter></paramdef>
		<paramdef>int <parameter>deviceid</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>Bool <function>XIGetClientPointer</function></funcdef>
		<paramdef>Display *<parameter>display</parameter></paramdef>
		<paramdef>Window <parameter>win</parameter></paramdef>
		<paramdef>int *<parameter>device</parameter></paramdef>
	    </funcprototype>
	</funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
	<para>
	    <variablelist>
		<varlistentry>
		    <term><parameter>display</parameter></term>
		    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
		</varlistentry>
		<varlistentry>
		    <term><parameter>win</parameter></term>
		    <listitem><para>Specifies a window belonging to the
			    client. May be <constant>None</constant>.
                    </para></listitem>
		</varlistentry>
		<varlistentry>
		    <term><parameter>deviceid</parameter></term>
		    <listitem><para>Specifies the ClientPointer device.
                    </para></listitem>
		</varlistentry>
	    </variablelist>
	</para>
    </refsect1>

    <refsect1><title>Description</title>
	<para>
	    The ClientPointer is the device that is percieved to be the core
	    pointer for non-XI protocol requests and replies.  Each  time  a
	    protocol message needs device-dependent data and the  device  is
	    not explicitly  given,  the ClientPointer device is used to obtain
            the data. For example, a <function>XQueryPointer</function>
            request will return the coordinates of the ClientPointer.
        </para>
        <para>
            <function>XISetClientPointer</function> request sets the
            ClientPointer device for the client that owns the given window. If
            <parameter>win</parameter> is <constant>None</constant>, the
            requesting client's ClientPointer is set to the device specified
            with <constant>deviceid</constant>. Only master pointer devices can be
            set as ClientPointer.
        </para>
        <para>
            <function>XISetClientPointer</function>  and can generate a
            <errorname>BadDevice</errorname> and a
            <errorname>BadWindow</errorname> error.
        </para>
        <para>
            The <function>XIGetClientPointer</function> request returns the
            ClientPointer's device ID for the client that owns the given
            window. If <parameter>win</parameter> is
            <constant>None</constant>, the requesting client's ClientPointer
            is returned.
        </para>
        <para>
            <parameter>win</parameter> may be a client ID instead
            of a window.
        </para>
        <para>
            <function>XIGetClientPointer</function> can generate a
            <errorname>BadWindow</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term><listitem>
                        <para>
                            An invalid device was specified. The device does
                            not exist or is not a master pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XIQueryPointer.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIQueryPointer</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XIQueryPointer</refname>
        <refpurpose> get device pointer coordinates.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Bool <function>XIQueryPointer</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Window <parameter>win</parameter></paramdef>
                <paramdef>Window *<parameter>root_return</parameter></paramdef>
                <paramdef>Window *<parameter>child_return</parameter></paramdef>
                <paramdef>int *<parameter>root_x_return</parameter></paramdef>
                <paramdef>int *<parameter>root_y_return</parameter></paramdef>
                <paramdef>int *<parameter>win_x_return</parameter></paramdef>
                <paramdef>int *<parameter>win_y_return</parameter></paramdef>
                <paramdef>XIModifierState *<parameter>modifiers_return</parameter></paramdef>
                <paramdef>XIGroupState *<parameter>group_return</parameter></paramdef>
                <paramdef>XIButtonState *<parameter>buttons_return</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>buttons_return</parameter></term>
                    <listitem>
                        <para>
                            Returns the current button state.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>child_return</parameter></term>
                    <listitem>
                        <para>
                            Returns the child window that the pointer is
                            located in, if any.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>deviceid</parameter></term>
                    <listitem><para>Specifies the device to query.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>group_return</parameter></term>
                    <listitem>
                        <para>
                            Returns the current group state.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>modifiers_return</parameter></term>
                    <listitem>
                        <para>
                            Returns the current state of the modifier keys.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>root_return</parameter></term>
                    <listitem>
                        <para>
                          Returns the root window that the pointer is in.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>root_x_return</parameter></term>
                    <term><parameter>root_y_return</parameter></term>
                    <listitem>
                        <para>
                          Return the pointer coordinates relative to the root
                          window's origin.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>win</parameter></term>
                    <listitem>
                        <para>
                          Specifies the window.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>win_x_return</parameter></term>
                    <term><parameter>win_y_return</parameter></term>
                    <listitem><para>
                            Return the pointer coordinates relative to the
                            specified window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
        The <function>XIQueryPointer</function> function returns the root
        window the device's pointer is logically on and the pointer
        coordinates relative to the root window's origin.  If
        <function>XIQueryPointer</function> returns
        <constant>False</constant>, the pointer is not on the same screen as
        the specified window, and
        <function>XIQueryPointer</function> returns
        <constant>None</constant> to <parameter>child_return</parameter> and
        zero to <parameter>win_x_return</parameter> and
        <parameter>win_y_return</parameter>.  If
        <function>XIQueryPointer</function> returns
        <constant>True</constant>, the pointer coordinates returned to
        <parameter>win_x_return</parameter> and
        <parameter>win_y_return</parameter> are relative to the origin of the
        specified window.  In this case,
        <function>XIQueryPointer</function> returns the child that
        contains the pointer, if any, or else <constant>None</constant> to
        <parameter>child_return</parameter>.
        </para>
        <para>
            <function>XIQueryPointer</function> returns the current
            logical state of the buttons
            <parameter>buttons_return</parameter>. The keyboard paired with
            the master pointer is selected to obtain the data for
            <parameter>modifiers_return</parameter> and
            <parameter>group_return</parameter>. 
        </para>
        <para>
            <function>XIQueryPointer</function> is identical to
            <function>XQueryPointer</function> but specifies the device
            explicitly.
        </para>
        <para>
            <function>XIQueryPointer</function> can generate a
            <errorname>BadDevice</errorname> and a
            <errorname>BadWindow</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem>
                        <para>
                            An invalid device was specified. The device does
                            not exist or is not a pointer device.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
</para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
    <refsect1><title>See also</title>
        <para>
            <function>XQueryPointer</function>
        </para>
    </refsect1>

</refentry>

<refentry id="XIDefineCursor.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIDefineCursor, XIUndefineCursor</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XIDefineCursor</refname>
	<refname>XIUndefineCursor</refname>
        <refpurpose>define device cursors.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XDefineCursor</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Window <parameter>win</parameter></paramdef>
                <paramdef>Cursor <parameter>cursor</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XUndefineCursor</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Window <parameter>win</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>cursor</parameter> </term><listitem>
                        <para>
                            Specifies the cursor that is to be displayed or
                            <constant>None</constant>.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>deviceid</parameter></term>
                    <listitem><para>Specifies the device whose cursor is to
                            change.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>win</parameter></term>
                    <listitem><para>Specifies the window.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            If a cursor is set, it will be used when the device's pointer is in the
            window. If the cursor is <constant>None</constant>, it is equivalent to
            <function>XUndefineDefineCursor</function>.
        </para>
        <para>
            <function>XIDefineCursor</function> can generate
            <errorname>BadCursor</errorname> and
            <errorname>BadWindow</errorname>.
        </para>
        <para>
            The <function>XIUndefineCursor</function> function undoes the
            effect of a previous <function>XIDefineCursor</function> for
            this window. When the pointer is in the window, the window's
            default cursor will now be used. If no default cursor is defined,
            the parent's cursor for this device will be used (if defined) or
            the parent's default cursor will be used.
        </para>
        <para>
            <function>XIDefineCursor</function> and
            <function>XIUndefineCursor</function> are identical to
            <function>XDefineCursor</function> and
            <function>XUndefineCursor</function> but specify the device
            explicitly.
        </para>
        <para>
            <function>XUndefineDevicePointer</function> can generate a
            <errorname>BadDevice</errorname> and a
            <errorname>BadWindow</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            device does not exist or is not a pointer
                            device.
                    </para></listitem>

                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
    <refsect1> <title>See also</title>
        <para>
            <function>XDefineCursor</function>,
            <function>XUndefineCursor</function>
        </para>
    </refsect1>
</refentry>

<refentry id="XIWarpPointer.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIWarpPointer</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XIWarpPointer</refname>
        <refpurpose>move a device's pointer.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Bool <function>XIWarpPointer</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Window <parameter>src_w</parameter></paramdef>
                <paramdef>Window <parameter>dest_w</parameter></paramdef>
                <paramdef>int <parameter>src_x</parameter></paramdef>
                <paramdef>int <parameter>src_y</parameter></paramdef>
                <paramdef>int <parameter>src_width</parameter></paramdef>
                <paramdef>int <parameter>src_height</parameter></paramdef>
                <paramdef>int <parameter>dest_x</parameter></paramdef>
                <paramdef>int <parameter>dest_y</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>dest_w</parameter></term>
                    <listitem>
                        <para>
                            Specifies the destination window or
                            <constant>None</constant>.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>dest_x</parameter></term>
                    <term><parameter>dest_y</parameter></term>
                    <listitem>
                        <para>
                            Specify the x and y coordinates within the
                            destination window.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>deviceid</parameter></term>
                    <listitem><para>Specifies the master pointer device or
                            floating slave device to move.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>src_x</parameter></term>
                    <term><parameter>src_y</parameter></term>
                    <term><parameter>src_width</parameter></term>
                    <term><parameter>src_height</parameter></term>
                    <listitem>
                        <para>
                          Specify a rectangle in the source window.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>src_w</parameter></term>
                    <listitem>
                        <para>
                            Specifies the source window or
                            <constant>None</constant>.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
             If <parameter>dest_w</parameter> is <constant>None</constant>,
             <function>XIWarpPointer</function> moves the pointer by the
             offsets (<parameter>dest_x</parameter>,
             <parameter>dest_y</parameter>) relative to the current position
             of the pointer.  If
             <parameter>dest_w</parameter> is a window,
             <function>XIWarpPointer</function> moves the pointer to the
             offsets
             (<parameter>dest_x</parameter>, <parameter>dest_y</parameter>)
             relative to the origin of <parameter>dest_w</parameter>.
             However, if <parameter>src_w</parameter> is a window, the move
             only takes place if the window <parameter>src_w</parameter>
             contains the pointer and if the specified rectangle of
             <parameter>src_w</parameter> contains the pointer.
        </para>
        <para>
            The <parameter>src_x</parameter> and <parameter>src_y</parameter>
            coordinates are relative to the origin of
            <parameter>src_w</parameter>.  If
            <parameter>src_height</parameter> is zero, it is replaced with the
            current height of <parameter>src_w</parameter> minus
            <parameter>src_y</parameter>.  If <parameter>src_w</parameter>idth
            is zero, it is replaced with the current width of
            <parameter>src_w</parameter> minus <parameter>src_x</parameter>.
        </para>
        <para>
            There is seldom any reason for calling this function.  The pointer
            should normally be left to the user.  If you do use this function,
            however, it generates events just as if the user had
            instantaneously moved the pointer from one position to another.
            Note that you cannot use <function>XIWarpPointer</function>
            to move the pointer outside the confine_to window of an active
            pointer grab.  An attempt to do so will only move the pointer as
            far as the closest edge of the confine_to window.
        </para>
        <para>
            <function>XIWarpPointer</function> is identical to
            <function>XWarpPointer</function> but specifies the device
            explicitly.
        </para>
        <para>
            <function>XIWarpPointer</function> can generate a
            <errorname>BadDevice</errorname> and a
            <errorname>BadWindow</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            device does not exist or is not a pointer
                            device.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
    <refsect1><title>See also</title>
        <para><function>XWarpPointer</function></para>
    </refsect1>
</refentry>

<refentry id="XIChangeHierarchy.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIChangeHierarchy</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XIChangeHierarchy</refname>
        <refpurpose>change the device hierarchy.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XIChangeHierarchy</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>XIAnyHierarchyChangeInfo *<parameter>changes</parameter></paramdef>
                <paramdef>int <parameter>num_changes</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>num_changes</parameter></term>
                    <listitem>
                        <para>
                            Specifies the number of elements in changes.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>changes</parameter></term>
                    <listitem>
                        <para>
                            Specifies the changes to be made.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            <function>XIChangeHierarchy</function> modifies the device
            hierarchy by creating or removing master devices or changing the
            attachment of slave devices. If <parameter>num_changes</parameter>
            is non-zero, <parameter>changes</parameter> is an array of
            <type>XIAnyHierarchyChangeInfo</type> structures.
        </para>
        <para>
            <function>XIChangeHierarchy</function> processes
            <parameter>changes</parameter> in order, effective immediately. If
            an error occurs, processing is aborted and the error is reported
            to the client. Changes already made remain effective.
        </para>
        <para>
            The list of <parameter>changes</parameter> is any combination of
            <structname>XIAnyHierarchyChangeInfo</structname>. The
            <structfield>type</structfield> of a hierarchy change can be
            <constant>XICreateMaster</constant>,
            <constant>XIRemoveMaster</constant>,
            <constant>XIAttachSlave</constant> or
            <constant>XIDetachSlave</constant>.
        </para>
        <para>
            <synopsis>
                typedef union {
                    int <structfield>type</structfield>;
                    <structfield>XICreateMasterInfo</structfield> create;
                    <structfield>XIRemoveMasterInfo</structfield> remove;
                    <structfield>XIAttachSlave</structfield> attach;
                    <structfield>XIDetachSlave</structfield> detach;
                } <structname>XIAnyHierarchyChangeInfo</structname>;
            </synopsis>
        </para>
        <para>
            <synopsis>
                typedef struct {
                    int <structfield>type</structfield>; /* <constant>XICreateMaster</constant> */
                    char* <structfield>name</structfield>;
                    Bool <structfield>sendCore</structfield>;
                    Bool <structfield>enable</structfield>;
                } <structname>XICreateMasterInfo</structname>;
            </synopsis>
        </para>
        <para>
            <synopsis>
                typedef struct {
                    int <structfield>type</structfield>; /* <constant>XIRemoveMaster</constant> */
                    int <structfield>device</structfield>;
                    int <structfield>returnMode</structfield>;
                    XDevice* <structfield>returnPointer</structfield>;
                    XDevice* <structfield>returnKeyboard</structfield>;
                } <structname>XIRemoveMasterInfo</structname>;
            </synopsis>
        </para>
        <para>
            <synopsis>
                typedef struct {
                    int <structfield>type</structfield>; /* <constant>XIAttachSlave</constant> */
                    int <structfield>device</structfield>;
                    int <structfield>newMaster</structfield>;
                } <structname>XIAttachSlaveInfo</structname>;
            </synopsis>
        </para>
        <para>
            <synopsis>
                typedef struct {
                    int <structfield>type</structfield>; /* <constant>XIDetachSlave</constant> */
                    int <structfield>device</structfield>;
                } <structname>XIDetachSlaveInfo</structname>;
            </synopsis>
        </para>
        <para>
            <structname>XICreateMasterInfo</structname> creates a new master
            pointer and a new master keyboard labelled
            &quot;<structfield>name</structfield> pointer&quot; and
            &quot;<structfield>name</structfield> keyboard&quot; respectively.
            If <structfield>sendCore</structfield> is
            <constant>True</constant>, the devices will send core events. If
            <structfield>enable</structfield> is <constant>True</constant>,
            the device is enabled immediately.
        </para>
        <para>
            <structname>XICreateMasterInfo</structname> can generate a
            <errorname>BadValue</errorname> error.
        </para>
        <para>
            <structname>XIRemoveMasterInfo</structname> removes
            <structfield>device</structfield> and its paired master device. If
            <structfield>returnMode</structfield> is
            <constant>XIAttachToMaster</constant>, all pointers attached to
            <structfield>device</structfield> or its paired master device are
            attached to <structfield>returnPointer</structfield>. Likewise,
            all keyboards are attached to
            <structfield>returnKeyboard</structfield>. If
            <structfield>returnMode</structfield> is
            <constant>XIFloating</constant>, all attached devices are set to
            floating.
        </para>
        <para>
            <structname>XIRemoveMasterInfo</structname> can generate a
            <errorname>BadValue</errorname> and a
            <errorname>BadDevice</errorname> error.
        </para>
        <para>
            <structname>XIAttachSlaveInfo</structname> attaches 
            <structfield>device</structfield> to
            <structfield>newMaster</structfield>. If the device is currently
            attached to a master device, it is detached from the master
            device and attached to the new master device.
        </para>
        <para>
            <function>XIAttachSlaveInfo</function> can generate a
            <errorname>BadDevice</errorname> error.
        </para>
        <para>
            <structname>XIDettachSlaveInfo</structname> deattaches 
            <structfield>device</structfield> from the current master device
            and sets it floating. If the device is already floating, no
            changes are made.
        </para>
        <para>
            <function>XIDetachSlaveInfo</function> can generate a
            <errorname>BadDevice</errorname> error.
        </para>
        <para>
            <function>XIChangeHierarchy</function> generates an
            <constant>XIHierarchyEvent</constant> if any modifications were
            successful.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem>
                        <para>
                            An invalid device was specified. The device does
                            not exist or is not a appropriate for the type of
                            change.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem>
                        <para>
                            Some numeric value falls out of the allowed range.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XISelectEvents.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XISelectEvents</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XISelectEvents</refname>
        <refpurpose>select for XI2 events on the window.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XISelectEvents</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>Window <parameter>win</parameter></paramdef>
                <paramdef>XIEventMask *<parameter>masks</parameter></paramdef>
                <paramdef>int <parameter>num_masks</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>masks</parameter></term>
                    <listitem><para>Device event mask.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>num_masks</parameter></term>
                    <listitem><para>Number of masks in
                            <parameter>masks</parameter>.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>win</parameter></term>
                    <listitem>
                        <para>
                            Specifies the window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            XI2 events must be selected using
            <function>XISelectEvents</function>.
        </para>
        <para>
            <function>XISelectEvents</function> sets the event mask for this
            client on <parameter>win</parameter>. Further events are only
            reported to this client if the event type matches the selected
            event mask.
            The <parameter>masks</parameter> overrides the previously
            selected event mask for the given device.
        </para>
        <para>
            If <parameter>deviceid</parameter> is a valid device, the event mask
            is selected only for this device. If
            <parameter>deviceid</parameter> is
            <constant>XIAllDevices</constant> or
            <constant>XIAllMasterDevices</constant>, the event mask is
            selected for all devices or all master devices, respectively.
            The effective event mask is the bit-wise OR of the
            <constant>XIAllDevices</constant>,
            <constant>XIAllMasterDevices</constant> and the respective
            device's event mask.
        </para>
        <para>
        <synopsis>
            typedef struct {
                int <structfield>deviceid</structfield>;
                int <structfield>mask_len</structfield>;
                unsigned char* <structfield>mask</structfield>;
            } <structname>XIEventMask</structname>;
        </synopsis>
        The <structfield>mask_len</structfield> specifies the length of mask
        in bytes. <structfield>mask</structfield> is a binary mask in the
        form of (1 &lt;&lt; event type). <structfield>deviceid</structfield>
        must be either a device or <constant>XIAllDevices</constant> or
        <constant>XIAllMasterDevices</constant>. A client may submit several
        masks with the same <structfield>deviceid</structfield> in one
        request but only the last mask will be effective.
        </para>
        <para>
            <function>XISelectEvents</function> can generate a
            <errorname>BadValue</errorname>, a
            <errorname>BadDevice</errorname>, and a
            <errorname>BadWindow</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>A value is outside of the permitted range.
</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not
                            name a defined window.
</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid device was specified. The
                            device does not exist.
</para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XIQueryVersion.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIQueryVersion</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
    <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
</refmeta>
    <refnamediv>
        <refname>XIQueryVersion</refname>
        <refpurpose>announce and query the support XI2 version.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XIQueryVersion</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int *<parameter>major_version_inout</parameter></paramdef>
                <paramdef>int *<parameter>minor_version_inout</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>major_version_inout</parameter></term>
                    <listitem><para>Specifies the client's supported XI2 version, and
                            returns the server's supported version.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>minor_version_inout</parameter></term>
                    <listitem><para>Specifies the client's supported XI2 version, and
                            returns the server's supported version.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            <function>XIQueryVersion</function> announces the client's
            supported XI2 version to the server and returns server's
            supported version. The server may treat a client differently
            depending on the version support announced. The
            <parameter>major_version_inout</parameter> must be 2 or greater,
            otherwise a <errorname>BadValue</errorname> error occurs.
        </para>
        <para>
            <function>XIQueryVersion</function> can generate a
            <errorname>BadValue</errorname> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>A value is outside of the permitted range.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>

<refentry id="XISetFocus.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XISetFocus, XIGetFocus</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
        <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
    </refmeta>
    <refnamediv>
        <refname>XISetFocus</refname>
        <refname>XIGetFocus</refname>
        <refpurpose>set or get the device's focus.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XISetFocus</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Window <parameter>focus</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>Status <function>XIGetFocus</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>Window *<parameter>focus_return</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>deviceid</parameter></term>
                    <listitem><para>Specifies the device whose focus is to be
                            queried or changed.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>focus</parameter></term>
                    <listitem><para>The new focus window.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>focus_return</parameter></term>
                    <listitem><para>Returns the current focus window.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>time</parameter></term>
                    <listitem><para>A valid timestamp or CurrentTime.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            <function>XISetFocus</function> changes the focus of the
            specified device ans its last-focus-change time. It
            has no effect if the specified time is earlier than the current
            last-focus-change time or is later than the current X server time.
            Otherwise, the last-focus-change time is set to the specified
            <parameter>time</parameter>.
            <constant>CurrentTime</constant> is replaced by the current X
            server time).  <constant>XISetFocus</constant>  causes the X
            server to generate core, XI and XI2 focus events.
        </para>
        <para>
            If the <parameter>focus</parameter> window is
            <constant>None</constant> all keyboard events by this device are
            discarded until a new focus window is set. Otherwise, if
            <parameter>focus</parameter> is a window, it becomes the device's
            focus window. If a generated device event would normally be
            reported to this window or one of its inferiors, the event is
            reported as usual. Otherwise, the event is reported relative to
            the focus window.
        </para>
        <para>
            The specified focus window must be viewable at the time
            <constant>XISetFocus</constant>  is called, or a
            <constant>BadMatch</constant> error results. If the focus window
            later becomes not viewable, the focus reverts to the parent (or
            the closest viewable ancestor. When the focus reverts, the X
            server generates core, XI and XI2 focus events but the
            last-focus-change time is not affected.
        </para>
        <para>
            Attempting to set the focus on a master pointer device or an
            attached slave device will result in a
            <constant>BadDevice</constant> error.
        </para>
        <para>
            <constant>XISetFocus</constant>  can generate
            <constant>BadDevice</constant>, <constant>BadMatch</constant>,
            <constant>BadValue</constant>, and
            <constant>BadWindow</constant> errors.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>A value is outside of the permitted range.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem>
                        <para>
                            An invalid device was specified. The device does
                            not exist or is not a appropriate for the type of
                            change.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem>
                        <para>
                            The window is not viewable.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>
<refentry id="XIGrabDevice.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
        <pubdate>February 14, 2008</pubdate>
        <authorgroup>
            <author>
                <firstname>Peter</firstname><surname>Hutterer</surname>
                <contrib>Specification and implementation.</contrib>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIGrabDevice, XIUngrabDevice</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
        <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
    </refmeta>
    <refnamediv>
        <refname>XIGrabDevice</refname>
        <refname>XIUngrabDevice</refname>
        <refpurpose>grab or ungrab the device.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput2.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>Status <function>XIGrabDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
                <paramdef>Cursor <parameter>cursor</parameter></paramdef>
                <paramdef>int <parameter>grab_mode</parameter></paramdef>
                <paramdef>int <parameter>paired_device_mode</parameter></paramdef>
                <paramdef>Bool <parameter>owner_events</parameter></paramdef>
                <paramdef>XIEventMask *<parameter>mask</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>Status <function>XIUngrabDevice</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>Time <parameter>time</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Arguments</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><parameter>cursor</parameter></term>
                    <listitem><para>Specifies the cursor image to display
                            for the duration of the grab.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>deviceid</parameter></term>
                    <listitem><para>Specifies the device that should be
                            grabbed or ungrabbed.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>grab_mode</parameter></term>
                    <term><parameter>paired_device_mode</parameter></term>
                    <listitem><para>The grab mode for this device and (if
                            applicable) the paired device.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>grab_window</parameter></term>
                    <listitem><para>The grab window.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>mask</parameter></term>
                    <listitem><para>Event mask.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>owner_events</parameter></term>
                    <listitem><para>True if events are to be reported
                            normally.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter>time</parameter></term>
                    <listitem><para>A valid timestamp or CurrentTime.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            <function>XIGrabDevice</function> actively grabs control of the
            device. Further device events are reported only to the grabbing
            client. <constant>XIGrabDevice</constant> overrides any active
            device grab by this client. if <parameter>deviceid</parameter>
            is an attached slave device, the device is set floating until
            the client calls <function>XIUngrabDevice</function>.
        </para>
        <para>
            If <parameter>owner_events</parameter> is
            <constant>False</constant>, all generated device events are
            reported with respect to grab_window if selected. If
            <parameter>owner_events</parameter> is <constant>True</constant>
            and if a generated device 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 the event <parameter>mask</parameter>.
        </para>
        <para>
            If the <parameter>grab_mode</parameter> argument is
            <constant>GrabModeAsync</constant>, device event processing
            continues as usual. If the device is currently frozen by this
            client, then processing of device events is resumed. If the
            <parameter>grab_mode</parameter> argument is
            <constant>GrabModeSync</constant>, the state of the device (as
            seen by client applications) appears
            to freeze, and the X server generates no further device events
            until the grabbing client issues a releasing
            <constant>XIAllowEvents</constant> call or until the device
            grab is released. Actual device changes are not lost while the
            device is frozen; they are simply queued in the server for later
            processing.
        </para>
        <para>
            If <parameter>paired_device_mode</parameter> is
            <constant>GrabModeAsync</constant>, processing of events from
            the paired master device is unaffected by
            activation of the grab. If
            <parameter>paired_device_mode</parameter> is
            <constant>GrabModeSync</constant>, the state of the paired
            master device (as seen by client applications) appears to
            freeze, and the X server generates no further events from this
            device until the grabbing client issues a releasing
            <constant>XIAllowEvents</constant> call or until the device
            grab is released. Actual events are not lost while the devices are
            frozen; they are simply queued in the server for later processing.
            If the device is a slave device
            <parameter>paired_device_mode</parameter> is ignored.
        </para>
        <para>
            If the device is actively grabbed by some other client,
            <constant>XIGrabDevice</constant> fails and returns
            <constant>AlreadyGrabbed</constant>. If
            <parameter>grab_window</parameter> is not
            viewable, it fails and returns
            <constant>GrabNotViewable</constant>. If the device is frozen by
            an active grab of another client, it fails and returns
            <constant>GrabFrozen</constant>. If the specified time is earlier
            than the last-device-grab time or later than the current X server
            time, it fails and returns <constant>GrabInvalidTime</constant>.
            Otherwise, the last-device-grab time is set to the specified
            time. <constant>CurrentTime</constant> is replaced by the
            current X server time.
        </para>
        <para>
            If cursor is not <constant>None</constant> this cursor is
            displayed until the client calls
            <function>XIUngrabDevice</function>.
        </para>
        <para>
            <constant>XIGrabDevice</constant> can generate
            <constant>BadDevice</constant>, <constant>BadValue</constant>,
            and <constant>BadWindow</constant> errors.
        </para>
        <para>
            The <constant>XIUngrabDevice</constant> request releases the
            device and any queued events if this client has it actively
            grabbed from either <function>XIGrabDevice</function> or
            <function>XIGrabKey</function> or
            <function>XIGrabButton</function>. If other devices are frozen
            by the grab, <function>XUngrabDevice</function> thaws
            them. <function>XUngrabDevice</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. The X server automatically performs an
            <constant>XIUngrabDevice</constant> request if the event window
            for an active device grab becomes not
            viewable.
        </para>
        <para>
            <constant>XIUngrabDevice</constant> can generate a
            <constant>BadDevice</constant> error.
        </para>
    </refsect1>

    <refsect1><title>Diagnosis</title>
        <para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>A value is outside of the permitted range.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem>
                        <para>
                            An invalid device was specified. The device does
                            not exist or is not a appropriate for the type of
                            change.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem>
                        <para>
                            The window is not viewable.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>
</refentry>
<refentry id="XIGrabButton.man">
    <refentryinfo>
        <productname>__vendorversion__</productname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>XIGrabButton, XIGrabKeysym</refentrytitle>
        <manvolnum>__libmansuffix__</manvolnum>
        <refmiscinfo class='source'>__xorgversion__</refmiscinfo>
        <refmiscinfo class='manual'>XINPUT FUNCTIONS</refmiscinfo>
    </refmeta>
    <refnamediv>
	<refname>XIGrabButton</refname>
	<refname>XIUngrabButton</refname>
	<refname>XIGrabKeysym</refname>
	<refname>XIUngrabKeysym</refname>
        <refpurpose>grab/ungrab buttons or keys</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <funcsynopsis>
            <funcsynopsisinfo>#include &lt;X11/extensions/XInput.h&gt;</funcsynopsisinfo>
            <funcprototype>
                <funcdef>int <function>XIGrabButton</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>int <parameter>button</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>Cursor <parameter>cursor</parameter></paramdef>
                <paramdef>int <parameter>grab_mode</parameter></paramdef>
                <paramdef>int <parameter>paired_device_mode</parameter></paramdef>
                <paramdef>Bool<parameter>owner_events</parameter></paramdef>
                <paramdef>XIEventMask *<parameter>mask</parameter></paramdef>
                <paramdef>int <parameter>num_modifiers</parameter></paramdef>
                <paramdef>XIGrabModifiers *<parameter>modifiers_inout</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XIUngrabButton</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>int <parameter>button</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>int <parameter>num_modifiers</parameter></paramdef>
                <paramdef>XIGrabModifiers *<parameter>modifiers</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XIGrabKeysym</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>int <parameter>keysym</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>Cursor <parameter>cursor</parameter></paramdef>
                <paramdef>int <parameter>grab_mode</parameter></paramdef>
                <paramdef>int <parameter>paired_device_mode</parameter></paramdef>
                <paramdef>Bool<parameter>owner_events</parameter></paramdef>
                <paramdef>XIEventMask *<parameter>mask</parameter></paramdef>
                <paramdef>int <parameter>num_modifiers</parameter></paramdef>
                <paramdef>XIGrabModifiers *<parameter>modifiers_inout</parameter></paramdef>
            </funcprototype>
            <funcprototype>
                <funcdef>int <function>XIUngrabKeysym</function></funcdef>
                <paramdef>Display *<parameter>display</parameter></paramdef>
                <paramdef>int <parameter>deviceid</parameter></paramdef>
                <paramdef>int <parameter>keysym</parameter></paramdef>
                <paramdef>Window <parameter>grab_window</parameter></paramdef>
                <paramdef>int <parameter>num_modifiers</parameter></paramdef>
                <paramdef>XIGrabModifiers *<parameter>modifiers</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1><title>Arguments</title>

        <para>
            <variablelist>
                <varlistentry><term><parameter>display</parameter></term>
                    <listitem><para>Specifies the connection to the X server.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>device</parameter></term>
                    <listitem><para>Specifies the device that is to be
                            grabbed or released</para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>button</parameter></term>
                    <listitem><para>Specifies the device button that is to
                            be grabbed or released or <constant>XIAnyButton</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>keysym</parameter></term>
                    <listitem><para>Specifies the keysym that is to
                            be grabbed or released or <constant>XIAnyKeysym</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>num_modifiers</parameter></term>
                    <listitem><para>Number of elements in
                            <parameter>modifiers</parameter> or
                            <parameter>modifiers_return</parameter>
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modifiers</parameter></term>
                    <listitem><para>Specifies the set of latched and base
                            modifiers or <constant>XIAnyModifier</constant>
                            to ungrab. The data type is for consistency with
                            the respective grab request and the status code
                            of the XIGrabModifiers struct is ignored.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>modifiers_inout</parameter></term>
                    <listitem><para>Specifies the set of latched and base
                            modifiers or <constant>XIAnyModifier</constant>
                            to grab. Returns the modifiers that could not be
                            grabbed and their status code.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>grab_window</parameter></term>
                    <listitem><para>Specifies the grab window.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>owner_events</parameter></term>
                    <listitem><para>Specifies a Boolean value that indicates
                            whether the are to be reported as
                            usual or reported with respect to the grab
                            window.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>mask</parameter></term>
                    <listitem><para>Specifies the event mask.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>grab_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from this device. You can pass
                            <constant>GrabModeSync</constant> or
                            <constant>GrabModeAsync</constant>.
                    </para></listitem>
                </varlistentry>
                <varlistentry><term><parameter>paired_device_mode</parameter></term>
                    <listitem><para>Specifies further processing of events
                            from the paired master device. You can pass
                            <constant>GrabModeSync</constant> or
                            <constant>GrabModeAsync</constant>.
                            If <parameter>deviceid</parameter> specifies a
                            floating slave device, this parameter is
                            ignored.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>Description</title>
        <para>
            <function>XIGrabButton</function> and
            <function>XIGrabKeysym</function> establishes a
            passive grab. The modifier device for a button grab is the
            paired master device if <parameter>deviceid</parameter>
            specifies a master pointer. Otherwise, the modifier device is
            the device specified with <parameter>deviceid</parameter>.
            In the future, the device is actively grabbed (as
            for <constant>XIGrabDevice</constant>, the last-grab time is set
            to the time at which the button or keysym was pressed and the
            <constant>X_XIButtonPress</constant> or
            <constant>X_XIKeyPress</constant> event is reported if all
            of the following conditions are true:

            <itemizedlist>
                <listitem>
                    <para>
                        The device is not grabbed, and the specified button
                        or keysym is logically pressed when the specified
                        modifier keys are logically down on the modifier
                        device and no other buttons or modifier keys are
                        logically down.
                    </para>
                </listitem>
                <listitem>
                    <para>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 device.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        A passive grab on the same button/modifier combination
                        does not exist on any ancestor of grab_window.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            The interpretation of the remaining arguments is as for
            <constant>XIGrabDevice</constant>. The active grab is terminated
            automatically when the logical state of the device has all
            buttons or keys released (independent of the logical state of
            the modifier keys).
        </para>
        <para>
            Note that the logical state of a device (as seen by client
            applications) may lag the physical state if device event
            processing is frozen.
        </para>
        <para>
            This request overrides all previous grabs by the same client on
            the same button/modifier or keysym/modifier combinations on the
            same window. A modifiers of <constant>XIAnyModifier</constant>
            is equivalent to issuing the grab 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 button of
            <constant>XIAnyButton</constant>  is equivalent to
            issuing the request for all possible buttons. Otherwise, it is not
            required that the specified button currently be assigned to a
            physical button.
        </para>
        <para>
            If some other client has already issued a
            <function>XIGrabButton</function>  or
            <function>XIGrabKeysym</function> with the same
            button/modifier or keysym/modifier combination on the same
            window, a <constant>BadAccess</constant>  error results. When
            using <constant>XIAnyModifier</constant>  or
            <constant>XIAnyButton</constant> , the request fails completely, and
            a  <constant>XIBadAccess</constant>  error results (no grabs are
            established) if there is a conflicting grab for any combination.
            <function>XIGrabButton</function> and
            <function>XIGrabKeysym</function> have no effect on an active
            grab.
        </para>
        <para>
            <function>XIGrabButton</function> and
            <function>XIGrabKeysym</function> can generate
            <constant>BadClass</constant>, <constant>BadDevice</constant>,
            <constant>BadMatch</constant>, <constant>BadValue</constant>, and
            <constant>BadWindow</constant> errors. 
        </para>
        <para>
            <function>XIUngrabButton</function> and
            <function>XIUngrabKeysym</function> releases the
            passive grab for a button/modifier or keysym/modifier
            combination on the specified window if it was grabbed by this
            client. A modifier of <constant>XIAnyModifier</constant>  is
            equivalent to issuing the ungrab request for all possible
            modifier combinations, including the combination of no
            modifiers. A button of <constant>XIAnyButton</constant> is
            equivalent to issuing the request for all possible buttons.
            <function>XIUngrabButton</function> and
            <function>XIUngrabKeysym</function> have no effect on an
            active grab.
        </para>
        <para>
            <function>XIUngrabButton</function>  and
            <function>XIUngrabKeysym</function> can generate
            <constant>BadDevice</constant>,  <constant>BadMatch</constant>,
            <constant>BadValue</constant>  and  <constant>BadWindow</constant>
            errors.
        </para>
    </refsect1>

    <refsect1><title>Diagnostics</title><para>
            <variablelist>
                <varlistentry>
                    <term><errorname>BadDevice</errorname></term>
                    <listitem><para>An invalid deviceid was specified.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadMatch</errorname></term>
                    <listitem><para>This error may occur if 
                            <function>XIGrabButton</function> 
                            specified a device that has no
                            buttons, or <function>XIGrabKeysym</function>
                            specified a device that has no keys.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadValue</errorname></term>
                    <listitem><para>Some numeric value falls outside the range
                            of values accepted by the request. Unless a
                            specific range is specified for an argument, the
                            full range defined by the argument's type is
                            accepted.  Any argument defined as a set of
                            alternatives can generate this error.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><errorname>BadWindow</errorname></term>
                    <listitem><para>A value for a Window argument does not name a defined Window.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1><title>See also</title>
        <para>XIAllowEvents(3), XIGrabDevice(3)</para>
    </refsect1>
</refentry>
</reference>