path: root/specs/Xi/protocol.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!-- lifted from troff+ms by doclifter 
     Hand-corrected by Peter Hutterer -->
<article id='protocolms'>
    <sect1 id="input_extension"><title>Input Extension</title>
        <para>
            <literallayout>
                <emphasis>
                    X11 Input Extension Protocol Specification
                    Version 1.0
                    X Consortium Standard
                    X Version 11, Release 6.8
                    Mark Patrick, Ardent Computer
                    George Sachs, Hewlett-Packard

                    Version 2.0
                    Peter Hutterer, University of South Australia
                </emphasis>
            </literallayout>
        </para>
        <para>Copyright &copy; 1989, 1990, 1991 by Hewlett-Packard Company and Ardent
            Computer</para>
        <para>Permission to use, copy, modify, and distribute this documentation for
            any purpose and without fee is hereby granted, provided that the above
            copyright notice and this permission notice appear in all copies.
            Ardent and Hewlett-Packard make no representations about the suitability 
            for any purpose of the information in this document. It is
            provided &quot;as is&quot; without express or implied warranty.
            Copyright &copy; 1989, 1990, 1991, 1992 X Consortium</para>
        <para>Permission is hereby granted, free of charge, to any person obtaining a copy
            of this software and associated documentation files (the &ldquo;Software&rdquo;), 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:</para>
        <para>The above copyright notice and this permission notice shall be included in
            all copies or substantial portions of the Software.</para>
        <para>THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
            IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
            FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
            X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
            AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
            CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
        <para>Except as contained in this notice, the name of the X Consortium shall not be
            used in advertising or otherwise to promote the sale, use or other dealings
            in this Software without prior written authorization from the X Consortium.
            <emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.</para>

        <para>Copyright &copy; 2008 by Peter Hutterer</para>
        <para>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:</para>
        <para>The above copyright notice and this permission notice (including the next
        paragraph) shall be included in all copies or substantial portions of the
        Software.</para>
        <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
        THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.</para>
        <beginpage/>
        <sect2>
            <title>Input Extension Overview</title>
            <para>This document defines an extension to the X11 protocol to support 
                input devices other than the core X keyboard and pointer. 
                An accompanying document defines a corresponding extension to Xlib 
                (similar extensions for languages other than C are anticipated).
                This first section gives an overview of the input extension. The 
                next section defines the new protocol requests defined by the extension.
                We conclude with a description of the new input events generated by
                the additional input devices.
            </para>
        </sect2>
        <sect2>
            <title>Input Extension Versions</title>
            <para>
                This document includes the specifications for X Input
                Extension Version 1.x and X Input Version 2.x (XI2). The
                differences for each version are spelled out in the respective
                descriptions for requests and events.
            </para>
            <para>
                There are three notable versions of XI. Most of this document
                describes the behaviour of the Input Extension 1.0, 1.1, 1.2,
                and 1.2. XI 1.4 introduced virtual devices that act as core
                devices (see <xref linkend='core_input_devices'/>) and input
                device hotplugging. XI 2.0 introduces the ability to create
                multiple virtual core devices. Unless stated otherwise, the
                content of this document applies to all versions of the Input
                Extension.
            </para>
        </sect2>
        <sect2 id='design_approach'>
            <title>Design Approach</title>
            <para>The design approach of the extension is to define requests
                and events analogous to the core requests and events. This allows
                extension input devices to be individually distinguishable from each other 
                and from the core input devices. These requests and events make use
                of a device identifier and support the reporting of n-dimensional motion 
                data as well as other data that is not reportable via the core 
                input events.
            </para>
        </sect2>
        <sect2 id='core_input_devices'>
            <title>Core Input Devices</title>
            <para>The X server core protocol supports two input devices:  a pointer and a
                keyboard. The pointer device has two major functions. 
                First, it may be used to generate motion information
                that client programs can detect. Second, it may also be used to indicate the
                current location and focus of the X keyboard. To accomplish this, the server 
                echoes a cursor at the current position of the X pointer. Unless the X
                keyboard has been explicitly focused, this cursor also shows the current
                location and focus of the X keyboard. The X keyboard is used
                to generate input that client programs can detect.</para>
            <para>
                In servers supporting XI 1.4 and above, the core pointer and
                the core keyboard are virtual devices that do not represent a
                physical device connected to the host computer. In XI 2.0 and
                above, multiple core pointers and core keyboards may exist,
                but for each core pointer there must be one core keyboard. No
                odd number of core devices is possible.
            </para>
            <para>The X keyboard and X pointer are referred to in this
                document as the <emphasis remap='I'>core devices</emphasis>,
                and the input events they generate
                (<emphasis>KeyPress</emphasis>,
                <emphasis>KeyRelease</emphasis>, 
                <emphasis>ButtonPress</emphasis>, 
                <emphasis>ButtonRelease</emphasis>, and
                <emphasis>MotionNotify</emphasis>) are known as the
                <emphasis remap='I'>core input events</emphasis>. All other
                input devices are referred to as <emphasis remap='I'>extension
                input devices</emphasis> and the input events they generate
                are referred to as <emphasis remap='I'>extension input events</emphasis>.
            </para> 
            <para>In servers supporting only XI 1.x, this input extension
                does not change the behavior or functionality of the
                core input devices, core events, or core protocol requests, with the
                exception of the core grab requests. These requests may affect the
                synchronization of events from extension devices. See the explanation
                in the section titled &quot;Event Synchronization and Core
                Grabs&quot;.
            </para>
            <para>Selection of the physical devices to be initially used by the server as the 
                core devices is left implementation-dependent. Requests are defined that
                allow client programs to change which physical devices are used as the
                core devices.</para>
            <para>
                In servers supporting XI 2.0 and above, core devices are also
                exteension devices and generate both core and input extension
                events.  For a detailed description of the handling of input
                devices in XI 2.0 and above, see <xref linkend='xi2_device_handling'/>.</para>
        </sect2>
        <sect2 id='extension_input_devices'>
            <title>Extension Input Devices</title>
            <para>The input extension v1.x controls access to input devices other than the X keyboard
                and X pointer. It allows client programs to select input from these devices 
                independently from each other and independently from the core
                devices. XI 2.0 and above also enable access to the X keyboard
                and the X pointer.
            </para>  
            <para>A client that wishes to access a specific device must first determine
                whether that device is connected to the X server. This is done through the
                <emphasis>ListInputDevices</emphasis> request, which will return a list of all devices that
                can be opened by the X server. A client can then open one or more of these
                devices using the <emphasis>OpenDevice</emphasis> request, specify what events they are
                interested in receiving, and receive and process input events from extension
                devices in the same way as events from the X keyboard and X pointer.
                Input events from these devices are of extension types (
                <emphasis>DeviceKeyPress</emphasis>, 
                <emphasis>DeviceKeyRelease</emphasis>, 
                <emphasis>DeviceButtonPress</emphasis>, 
                <emphasis>DeviceButtonRelease</emphasis>, 
                <emphasis>DeviceMotionNotify</emphasis>, etc.) and
                contain a device identifier so that events of the same type
                coming from different input devices can be
                distinguished.</para>
            <para>Any kind of input device may be used as an extension input device.
                Extension input devices may have 0 or more keys, 0 or more buttons,
                and may report 0 or more axes of motion. Motion may be reported 
                as relative movements from a previous position or as an absolute
                position. All valuators reporting motion information for a given
                extension input device must report the same kind of motion information
                (absolute or relative).</para>
            <para>This extension is designed to accommodate new types of input devices that
                may be added in the future. The protocol requests that refer to
                specific characteristics of input devices organize that information
                by <emphasis>input classes</emphasis>. Server implementors may add new
                classes of input devices without changing the protocol requests.
                Input classes are unique numbers registered with the X Consortium.
                Each extension input device may support multiple input classes.</para>
            <para>
                In XI 1.x, all extension input devices are treated like the core X keyboard in 
                determining their location and focus. The server does not track the 
                location of these devices on an individual basis, and therefore
                does not echo a cursor to indicate their current location.
                Instead, their location is determined by the location of the core X pointer.
                Like the core X keyboard, some may be explicitly focused. If they are
                not explicitly focused,  their focus is determined by the location of the 
                core X pointer.
            </para>
            <para>
                In XI 2.x, the location and focus of an extension input device
                is determined by its attachment. See <xref linkend="xi2_device_handling"/>.
            </para>
            <para>Most Input events reported by the server to a client are of fixed size (32 bytes).
                In order to represent the change in state of an input device the extension
                may need to generate a sequence of input events. A client side library
                (such as Xlib) will typically take these raw input events and format
                them into a form more convenient to the client.</para> 
            <sect3 id='event_classes'>
                <title>Event Classes</title>
                <para>In the core protocol a client registers interest in receiving certain
                    input events directed to a window by modifying that window's event-mask.
                    Most of the bits in the event mask are already used to specify interest
                    in core X events. The input extension specifies a different mechanism by which
                    a client can express interest in events generated by this extension.</para>
                <para>When a client opens a extension input device via the
                    <emphasis>OpenDevice</emphasis> request, an
                    <emphasis>XDevice</emphasis> structure is
                    returned. Macros are provided that extract 32-bit numbers
                    called <emphasis>event classes</emphasis> from
                    that structure, that a client can use to register interest
                    in extension events via the 
                    <emphasis>SelectExtensionEvent</emphasis>
                    request. The event class combines the desired event type
                    and device id, and may be thought of as the equivalent of
                    core event masks.</para>
            </sect3>
            <sect3 id='input_classes'>
                <title>Input Classes</title>
                <para>Some of the input extension requests divide input devices into classes
                    based on their functionality. This is intended to allow new classes of input
                    devices to be defined at a later time without changing the semantics of 
                    these requests. The following input device classes are currently
                    defined:</para>
                <variablelist remap='IP'>
                    <varlistentry>
                        <term><emphasis>KEY</emphasis></term>
                        <listitem>
                            <para>The device reports key events.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><emphasis>BUTTON</emphasis></term>
                        <listitem>
                            <para>The device reports button events.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><emphasis>VALUATOR</emphasis></term>
                        <listitem>
                            <para>The device reports valuator data in motion events.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><emphasis>PROXIMITY</emphasis></term>
                        <listitem>
                            <para>The device reports proximity events.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><emphasis>FOCUS</emphasis></term>
                        <listitem>
                            <para>The device can be focused and reports focus events.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><emphasis>FEEDBACK</emphasis></term>
                        <listitem>
                            <para>The device supports feedbacks.</para>
                        </listitem>
                    </varlistentry>
                    <varlistentry>
                        <term><emphasis>OTHER</emphasis></term>
                        <listitem>
                            <para>The <emphasis>ChangeDeviceNotify</emphasis>,
                                <emphasis>DeviceMappingNotify</emphasis>, and
                                <emphasis>DeviceStateNotify</emphasis> macros may be
                                invoked passing the <emphasis>XDevice</emphasis>
                                structure returned for this device.</para>
                        </listitem>
                    </varlistentry>
                </variablelist>

                <para>Each extension input device may support multiple input classes.
                    Additional classes may be added in the future.
                    Requests that support multiple input classes, such as the 
                    <emphasis>ListInputDevices</emphasis> function that lists all available input devices,
                    organize the data they return by input class. Client programs that
                    use these requests should not access data unless it matches a 
                    class defined at the time those clients were compiled. In this way,
                    new classes can be added without forcing existing clients that use
                    these requests to be recompiled.</para>
            </sect3>
        </sect2>
        <sect2 id='xi2_device_handling'>
            <title>XI 2.0 device handling</title>
            <para>XI Version 2.0 introduces a device hierarchy split up into
                so-called &quot;Master Devices&quot; (MD) and &quot;Slave
                Devices&quot; (SD). This distinction is key to both the device
                handling and the event handling in the server.</para>
            <para>An MD is always a virtual device and does not represent a
                physical device connected to the host computer. MDs come in
                two forms: as master pointers or as master keyboards. 
                A master pointer is reflected by a visible cursor on the
                screen. A master keyboard is reflected by a keyboard focus.
            </para>
            <para>
                Each master pointer is &quot;paired&quot; with the respective
                master keyboard and vice versa, and this pairing is maintained
                for the lifetime of both input devices.  Clients can utilise
                this pairing behaviour to implement combinatory input
                paradigms such as SHIFT + Click. For a description on how to
                obtain this pairing, see <xref linkend="listing_available_devices"/>.
            </para>
            <para>
                MDs may send core events and XI events. However, as an MD does
                not represent a physical device, they rely on SDs for event
                generation.
            </para>
            <para>
                An SD is a physical device configured in the server. SDs are
                not represented by a cursor or keyboard focus. An SD may be
                &quot;attached&quot; to a master pointer or master keyboard.
                In this case, each event generated by the SD is
                <emphasis>also</emphasis> routed through the MD. Such an event
                is modified inside the server and appears to the client as if
                generated by the MD. See <xref linkend="xi2_event_processing"/>
                for more details.
            </para>
            <para>SDs can only send XI events.</para>
            <para>
                <example width='3in'>
                    <title>Example device setup</title>
                    <para>A server may have two master devices (one master pointer
                    and one master keyboard). It thus displays one cursor and
                    provides one keyboard focus.</para>
                <para>One mouse and one keyboard are connected to the server.
                    The server thus controls two slave devices. The mouse is
                    attached to the master pointer and the keyboard to the
                    master keyboard.</para>
                <para>When the mouse moves, the matching slave device
                    generates an XI event. This event is processed until
                    delivered. After that, the same event is modified to
                    appear as being generated by the master pointer. This
                    modified event is then processed until delivered. To a
                    client, the latter event appears to be coming from the
                    master pointer.</para>
                </example>
            </para>
            <sect3 id='xi2_attachment'>
                <title>Attachment of slave devices</title>
                <para>
                    SDs can be attached to any master of the same type (e.g. a
                    physical pointer device can be attached to any master
                    pointer). In this case, the SD controls the MDs cursor and
                    a movement of the SD will change the cursor position of
                    this MD. Likewise, an attached keyboard device shares the
                    keyboard focus of the respective master keyboard.
                </para>
                <para>
                    SDs can be &quot;floating&quot;, in which case they are
                    not attached to an MD. Such a floating devices does not
                    route events through any MD and does not have a visible
                    cursor. The focus of such a floating device must be
                    explicitly controlled by the client program.
                </para>
            </sect3>
            <sect3 id='xi2_event_processing'>
                <title>Event processing for attached slave devices</title>
                <para>
                    If an SD generates an event, this event is processed as
                    normal and delivered to any client that previously
                    registered for the respective event type. Such events are
                    always input extension events and the SD can be identified
                    by the device identifier in event.
                </para>
                <para>
                    After the SD's event has been processed, the event's
                    device identifier is modified and set to the SD's master
                    device. The event is then processed again, this time
                    appearing as if generated by the master device.
                    During event processing, a core event is generated from
                    the input extension event. If the core event is delivered
                    to a client, the input extension event is not processed
                    further and the server continues with the next input
                    event. Only if the core event is not delivered may the
                    input extension event be delivered to a client.
                </para>
                <para>
                    Before the MD's event is processed, the MD switches state 
                    to represent the capabilities of the SD. As previously
                    described in <xref linkend="input_classes"/>, each SD
                    describes its capabilities through a number of input
                    classes. When the MD switches state, it duplicates the
                    input classes of the SD and thus appears to have the same
                    capabilities as the SD. Clients are notified of this
                    switch.
                </para>
                <para>
                    <example width='3in'>
                        <title>Event routing with two pointer devices.</title>
                        <para>
                            A server has a traditional USB mouse and a
                            graphics tablet attached. The USB mouse provides 3
                            buttons and relative x/y axes. The graphics tablet
                            provides 8 buttons and 3 absolute axes in a
                            device-specific coordinate system.
                            Both devices are attached to the same master
                            pointer.
                        </para>
                        <para>
                            When the mouse generates an event, this input
                            extension event is delivered as normal. The event
                            is then modified to appear as being generated by
                            the master pointer. The master pointer modifies
                            its input classes to appear as a device that
                            provides 3 buttons and two relative axes. The
                            input extension event is then processed.
                            A core event may be delivered instead of the input
                            extension event.
                        </para>
                        <para>
                            When the graphics tablet generates an event, this
                            input extension event is deliveredd as normal. The
                            event is ethen modified to appear as being
                            generated by the master pointer. The master
                            pointer modifies its input classes to appear as a
                            devices that provides 8 buttons and thre absolute
                            axes in a device-specific coordinate system. The
                            input extension event is then processed, and a
                            core event may be delivered instead of the input
                            extension event.
                        </para>
                    </example>
                </para>
            </sect3>
        </sect2>
    </sect1>
    <sect1 id='requests'>
        <title>Requests</title>
        <para>Extension input devices are accessed by client programs through the 
            use of new protocol requests. This section summarizes the new requests
            defined by this extension. The syntax and type definitions used below 
            follow the notation used for the X11 core protocol.</para>  
        <sect2 id='getting_the_extension_version'>
            <title>Getting the Extension Version</title>
            <para>The <emphasis>GetExtensionVersion</emphasis> request
                returns version information about the input extension.
                <literallayout>
                    GetExtensionVersion
                            name: STRING
                            client-major-version: CARD8
                            client-minor-version: CARD8
                    =&gt;
                            present: BOOL
                            protocol-major-version: CARD16
                            protocol-minor-version: CARD16
                </literallayout>
                The protocol version numbers returned indicate the version of the
                input extension supported by the target X server. The version
                numbers can be compared to constants defined in the header file
                <filename>XI.h</filename>. Each version is a superset of the
                previous versions.</para>
            <para>
                For clients supporting XI 1.x only, the name must be the
                name of the Input Extension as defined in the header
                file <filename>XI.h</filename>. client-major-version and
                client-minor-version are undefined.
                For clients supporting XI 2.0 and above, the name must be of
                zero length and client-major-version and client-minor version
                must reflect the Input Extension version as supported by the
                client.
                The server changes the behaviour of some requests depending on
                the version supported by the client. A client that does not
                specify support for XI 2.x cannot use the extended
                functionality of this version.
            </para>
            <para>
                client-major-version and client-minor-version are CARD8 to
                ensure binary compatibility with pre-XI 2.0 implementations.
            </para>
        </sect2>
        <sect2 id='listing_available_devices'><title>Listing Available Devices</title>
            <para>A client that wishes to access a specific device must first
                determine whether that device is connected to the X server. This
                is done through the
                <emphasis>ListInputDevices</emphasis> request, which will
                return a list of all devices that can be opened by the X server.
                For clients that have not announced XI 2.x support through the
                <emphasis>GetExtensionVersion</emphasis> request,
                <emphasis>ListInputDevices</emphasis> only returns the first
                master pointer, the first master keyboard, and all floating
                slave devices.
            <literallayout>
                ListInputDevices
                =&gt;
                input-devices: ListOfDeviceInfo
            </literallayout>
            where
            <literallayout>
                DEVICEINFO:
                        [type: ATOM
                         id: CARD8
                         num_classes: CARD8
                         use: {IsXKeyboard, IsXPointer, IsXExtensionPointer,
                               IsXExtensionKeyboard, IsExtensionDevice}
                         attached: CARD8
                         info: LISTofINPUTINFO
                         name: STRING8]
                         
                INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO}

                KEYINFO:
                        [class: CARD8
                         length: CARD8
                         min-keycode: KEYCODE
                         max-keycode: KEYCODE
                         num-keys: CARD16]

                BUTTONINFO:
                        [class: CARD8
                         length: CARD8
                         num-buttons: CARD16]

                VALUATORINFO:
                        [class: CARD8
                         length: CARD8
                         num_axes: CARD8
                         mode: SETofDEVICEMODE
                         motion_buffer_size: CARD32
                         axes: LISTofAXISINFO]
                        
                AXISINFO:
                        [resolution: CARD32
                         min-val: CARD32
                         max-val: CARD32]

                DEVICEMODE: {Absolute, Relative}
            </literallayout>
            </para>
            <para>Errors: None</para>
            <para>
                This request returns a list of all devices that can be opened by the X 
                server,  including the core X keyboard and X pointer. Some
                implementations may open all input devices as part of X
                initialization, while others may not open
                an input device until requested to do so by a client program.</para>
            <para>The information returned for each device is as follows:</para>
            <variablelist>
                <varlistentry><term>type</term>
                    <listitem>
                        <para>The <emphasis>type</emphasis> field is of type <emphasis>Atom</emphasis> and indicates the nature of the 
                            device. Clients may determine device types by invoking the <emphasis>XInternAtom</emphasis>
                            request passing one of the names defined in the header file <filename>XI.h</filename>. The
                            following names have been defined to date:</para>
                        <literallayout remap='DS'>
                            <emphasis>MOUSE</emphasis>	
                            <emphasis>TABLET</emphasis>
                            <emphasis>KEYBOARD</emphasis>	
                            <emphasis>TOUCHSCREEN</emphasis>
                            <emphasis>TOUCHPAD</emphasis>	
                            <emphasis>BUTTONBOX</emphasis>	
                            <emphasis>BARCODE</emphasis>
                            <emphasis>KNOB_BOX</emphasis>
                            <emphasis>TRACKBALL</emphasis>	
                            <emphasis>QUADRATURE</emphasis>
                            <emphasis>SPACEBALL</emphasis>
                            <emphasis>DATAGLOVE</emphasis>
                            <emphasis>EYETRACKER</emphasis>
                            <emphasis>CURSORKEYS</emphasis>
                            <emphasis>FOOTMOUSE</emphasis>
                            <emphasis>ID_MODULE</emphasis>
                            <emphasis>ONE_KNOB</emphasis>
                            <emphasis>NINE_KNOB</emphasis>
                        </literallayout>
                    </listitem>
                </varlistentry>
                <varlistentry><term>id</term>
                    <listitem>
                        <para>The <emphasis>id</emphasis> is a small cardinal value in the range 0-128 that uniquely 
                            identifies the device. It is assigned to the device when it is initialized by 
                            the server. Some implementations may not open an input device until requested
                            by a client program, and may close the device when the last client accessing
                            it requests that it be closed.
                            If a device is opened by a client program via <emphasis>XOpenDevice</emphasis>,
                            then closed via <emphasis>XCloseDevice</emphasis>, then opened again, it is not guaranteed
                            to have the same id after the second open request.</para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>num_classes</term>
                    <listitem>
                        <para>The <emphasis>num_classes</emphasis> field is a small cardinal value in the range 0-255
                            that specifies the number of input classes supported by the device for
                            which information is returned by <emphasis>ListInputDevices</emphasis>. Some input classes,
                            such as class <emphasis>Focus</emphasis> and class <emphasis>Proximity</emphasis> do not have any information
                            to be returned by <emphasis>ListInputDevices</emphasis>.</para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>use</term>
                    <listitem>
                        <para>The <emphasis>use</emphasis> field specifies how the device is currently being used. If the
                            value is <emphasis>IsXKeyboard</emphasis>, the device is currently being used as the 
                            X keyboard. If the value is <emphasis>IsXPointer</emphasis>, the device is currently
                            being used as the X pointer. If the value is <emphasis>IsXExtensionDevice</emphasis>,
                            the device is available for use as an extension device.</para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>attached</term>
                    <listitem>
                        <para>
                            If the use field is <constant>IsXExtensionPointer</constant>,
                            <emphasis>IsXExtensionKeyboard</emphasis>, or
                            <emphasis>IsXExtensionDevice</emphasis>, the
                            <emphasis>attached</emphasis> field specifies the device ID of the
                            master devices this device is attached to. If the
                            device is floating, the value is <emphasis>Floating</emphasis>.
                            If the use field is <emphasis>IsXPointer</emphasis>,
                            the attached field specifies the paired master keyboard that
                            provides modifier key states for input events. If the use
                            field is <emphasis>IsXKeyboard</emphasis>,
                            the attached field specifies the paired master
                            pointer that provides the pointer coordinates and
                            button states for input events.
                        </para>
                        <para>
                            For server implementations supporting XI 1.x only,
                            the attached field is unspecified.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>name</term>
                    <listitem>
                        <para>The <emphasis>name</emphasis> field contains a pointer to a null-terminated string that
                            corresponds to one of the defined device types.</para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>InputInfo</term>
                    <listitem>
                        <para><emphasis>InputInfo</emphasis> is one of: <emphasis>KeyInfo</emphasis>, <emphasis>ButtonInfo</emphasis> or 
                            <emphasis>ValuatorInfo</emphasis>. The first two fields are common to all three:

                            <variablelist>
                                <varlistentry><term>class</term>
                                    <listitem>
                                        <para>The <emphasis>class</emphasis> field is a cardinal value in the range 0-255. It uniquely
                                            identifies the class of input for which information is returned.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>length</term>
                                    <listitem>
                                        <para>The <emphasis>length</emphasis> field is a cardinal value 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>
                                    </listitem>
                                </varlistentry>
                            </variablelist>
                        </para>

                        <para>The remaining information returned for input class <emphasis>KEYCLASS</emphasis> is as follows:
                            <variablelist>
                                <varlistentry><term>min_keycode</term>
                                    <listitem>
                                        <para><emphasis>min_keycode</emphasis> is of type KEYCODE. It specifies the minimum keycode that
                                            the device will report. The minimum keycode will not be smaller than 8.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>max_keycode</term>
                                    <listitem>
                                        <para><emphasis>max_keycode</emphasis> is of type KEYCODE. It specifies the maximum keycode that
                                            the device will report. The maximum keycode will not be larger than 255.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>num_keys</term>
                                    <listitem>
                                        <para><emphasis>num_keys</emphasis> is a cardinal value that specifies the number of keys that the
                                            device has.</para>
                                    </listitem>
                                </varlistentry>
                            </variablelist>
                        </para>

                        <para>The remaining information returned for input class <emphasis>BUTTONCLASS</emphasis> is as 
                            follows:
                            <variablelist>
                                <varlistentry><term>num_buttons</term>
                                    <listitem>
                                        <para><emphasis>num_buttons</emphasis> is a cardinal value that specifies the number of buttons 
                                            that the device has.</para>
                                    </listitem>
                                </varlistentry>
                            </variablelist>
                        </para>

                        <para>The remaining information returned for input class <emphasis>VALUATORCLASS</emphasis> is as 
                            follows:
                            <variablelist>
                                <varlistentry><term>mode</term>
                                    <listitem>
                                        <para><emphasis>mode</emphasis> is a constant that has one of the following values: 
                                            <emphasis>Absolute</emphasis> or <emphasis>Relative</emphasis>. Some devices
                                            allow the mode to be changed dynamically via the <emphasis>SetDeviceMode</emphasis> request.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>motion_buffer_size</term>
                                    <listitem>
                                        <para><emphasis>motion_buffer_size</emphasis> is a cardinal number that specifies the number of 
                                            elements that can be contained in the motion history buffer for the device.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>axes</term>
                                    <listitem>
                                        <para>The <emphasis>axes</emphasis> field contains a pointer to an AXISINFO struture.</para>
                                    </listitem>
                                </varlistentry>
                            </variablelist>
                        </para>

                        <para>The information returned for each axis reported by the device is:
                            <variablelist>
                                <varlistentry><term>resolution</term>
                                    <listitem><para>The <emphasis>resolution</emphasis> is a cardinal value in counts/meter.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>min_val</term>
                                    <listitem><para>The <emphasis>min_val</emphasis> field is a cardinal value in that contains the minimum
                                            value the device reports for this axis. For devices whose mode is 
                                            <emphasis>Relative</emphasis>, the min_val field will contain 0.</para>
                                    </listitem>
                                </varlistentry>
                                <varlistentry><term>max_val</term>
                                    <listitem><para>The <emphasis>max_val</emphasis> field is a cardinal value in that contains the maximum
                                            value the device reports for this axis. For devices whose mode is 
                                            <emphasis>Relative</emphasis>, the max_val field will contain 0.</para>
                                    </listitem>
                                </varlistentry>
                            </variablelist>
                        </para>
                    </listitem>
            </varlistentry>
        </variablelist>
        </sect2>
        <sect2 id='enabling_devices'><title>Enabling Devices</title>
            <para>Client programs that wish to access an extension device must request that
                the server open that device. This is done via the <emphasis>OpenDevice</emphasis>
                request. 
            <literallayout>
                OpenDevice
                        id: CARD8
                =&gt;
                DEVICE: 
                        [device_id: XID
                         num_classes: INT32
                         classes: LISTofINPUTCLASSINFO]

                INPUTCLASSINFO:
                         [input_class: CARD8
                         event_type_base: CARD8]
            </literallayout>
            </para>
            <para>Errors: Device</para>
            <para>This request returns the event classes to be used by the client to indicate 
                which events the client program wishes to receive. Each input class
                may report several event classes. For example, input class <emphasis>Keys</emphasis> reports
                <emphasis>DeviceKeyPress</emphasis> and <emphasis>DeviceKeyRelease</emphasis> event classes. Input classes 
                are unique numbers registered with the X Consortium. Input class 
                <emphasis>Other</emphasis> exists
                to report event classes that are not specific to any one input class,
                such as <emphasis>DeviceMappingNotify</emphasis>, <emphasis>ChangeDeviceNotify</emphasis>, and 
                <emphasis>DeviceStateNotify</emphasis>.</para>
            <para>The information returned for each device is as follows:</para>
            <variablelist>
                <varlistentry><term>device_id</term>
                    <listitem>
                        <para>The <emphasis>device_id</emphasis> is a number that uniquely identifies the device.</para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>num_classes</term>
                    <listitem>
                        <para>The <emphasis>num_classes</emphasis> field contains the number of input classes supported
                            by this device.</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>For each class of input supported by the device,
                the <emphasis>InputClassInfo</emphasis> structure contains the following information:</para>
            <variablelist>
                <varlistentry><term>input_class</term>
                    <listitem>
                        <para>The <emphasis>input_class</emphasis> is a small cardinal number that identifies the class
                            of input.</para>
                    </listitem>
                </varlistentry>
                <varlistentry><term>event_type_base</term>
                    <listitem>
                        <para>The <emphasis>event_type_base</emphasis> is a small cardinal number that specifies the 
                            event type of one of the events reported by this input class. This information
                            is not directly used by client programs. Instead, the <emphasis>Device</emphasis> is used
                            by macros that return extension event types and event classes. This is 
                            described in the section of this document entitled "Selecting Extension
                            Device Events".</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>The information in the <emphasis>InputClassInfo</emphasis>
                reflects the state of this device at the time the request was
                processed. If the device is a master device, it may change
                classes in the future (see <xref linkend="xi2_event_processing"/>.</para>
            <para>Before it exits, the client program should explicitly
                request that the server close the device. This is done via
                the <emphasis>CloseDevice</emphasis> request.</para>
            <para>A client may open the same extension device more than once. Requests
                after the first successful one return an additional <emphasis>XDevice</emphasis> structure
                with the same information as the first, but otherwise have no effect.
                A single <emphasis>CloseDevice</emphasis> request will terminate that client's access to
                the device.</para>
            <para>If the client announces support of XI 2.x, any device returned
                through by <emphasis>ListInputDevices</emphasis> can be
                opened. Otherwise, only floating SDs may be opened by this
                client.
            </para>
            <para>Closing a device releases any active or passive grabs the requesting client
                has established. If the device is frozen only by an active grab of the
                requesting client, the queued events are released when the client terminates.</para>
            <para>If a client program terminates without closing a device, the server will
                automatically close that device on behalf of the client. This does not
                affect any other clients that may be accessing that
                device.
                <literallayout>
                    CloseDevice: 
                            device: DEVICE
                </literallayout>
                Errors: Device
            </para>
        </sect2>
        <sect2 id='changing_the_mode_of_a_device'><title>Changing The Mode Of A Device</title>
            <para>Some devices are capable of reporting either relative or absolute motion
                data. To change the mode of a device from relative to absolute, use the
                <emphasis>SetDeviceMode</emphasis> request. The valid values are <emphasis>Absolute</emphasis> or 
                <emphasis>Relative</emphasis>.</para>
            <para>This request will fail and return <emphasis>DeviceBusy</emphasis> if another client already
                has the device open with a different mode.  It will fail and return 
                <emphasis>AlreadyGrabbed</emphasis> if another client has the device grabbed.
                The request will fail with
                a <emphasis>BadMatch</emphasis> error if the requested mode is not supported by the device.
                <literallayout>
                    SetDeviceMode
                            device:DEVICE
                            mode: {Absolute, Relative}
                    =&gt;
                            status: {Success, DeviceBusy, AlreadyGrabbed}
                </literallayout>
            Errors: Device, Match, Mode</para>
        </sect2>
        <sect2 id='initializing_valuators_on_an_input_device'><title>Initializing Valuators on an Input Device</title>
            <para>Some devices that report absolute positional data can be initialized to a 
                starting value. Devices that are capable of reporting relative motion or
                absolute positional data may require that their valuators be initialized 
                to a starting value after the mode of the device is changed to <emphasis>Absolute</emphasis>.
                To initialize the valuators on such a device, use the <emphasis>SetDeviceValuators</emphasis>
                request.
                <literallayout>
                SetDeviceValuators
                        device: DEVICE
                        first_valuator: CARD8
                        num_valuators: CARD8
                        valuators: LISTOFINT32
                =&gt;
                        status: {Success, AlreadyGrabbed}
                </literallayout>
            Errors: Length, Device, Match, Value</para>
            <para>This request initializes the specified valuators on the specified extension
                input device. Valuators are numbered beginning with zero. Only the valuators
                in the range specified by first_valuator and num_valuators are set. If the
                number of valuators supported by the device is less than the expression
                first_valuator + num_valuators, a <emphasis>Value</emphasis> error will result.</para>
            <para>If the request succeeds, <emphasis>Success</emphasis> is returned. If the specifed device is 
                grabbed by some other client, the request will fail and a status of
                <emphasis>AlreadyGrabbed</emphasis> will be returned.</para>
        </sect2>
        <sect2 id='getting_input_device_controls'><title>Getting Input Device Controls</title>
            <para>
                <literallayout>
                GetDeviceControl
                        device: DEVICE
                        control: XID
                =&gt;
                controlState: {DeviceState}
                </literallayout>
            where
            <literallayout>
                DeviceState: DeviceResolutionState
            </literallayout>
            Errors: Length, Device, Match, Value</para>
            <para>This request returns the current state of the specified device control.
                The device control must be supported by the target server and device or an 
                error will result.</para>  
            <para>If the request is successful, a pointer to a generic DeviceState 
                structure will be returned. The information returned varies according to 
                the specified control and is mapped by a structure appropriate for that
                control.</para>
            <para>GetDeviceControl will fail with a BadValue error if the server does not support
                the specified control. It will fail with a BadMatch error if the device
                does not support the specified control.</para>
            <para>Supported device controls and the information returned for them include:
                <literallayout>
                DEVICE_RESOLUTION:
                    [control: CARD16
                    length: CARD16
                    num_valuators: CARD8
                    resolutions: LISTofCARD32
                    min_resolutions: LISTofCARD32
                    max_resolutions: LISTofCARD32]
                </literallayout>
                This device control returns a list of valuators and the range of valid 
                resolutions allowed for each. Valuators are numbered beginning with 0.
                Resolutions for all valuators on the device are returned. 
                For each valuator i on the device, resolutions[i] returns the current setting
                of the resolution, min_resolutions[i] returns the minimum valid setting,
                and max_resolutions[i] returns the maximum valid setting.</para>
            <para>When this control is specified, XGetDeviceControl will fail with a BadMatch
                error if the specified device has no valuators.
                <literallayout>
                ChangeDeviceControl:
                        device: DEVICE
                        XID: controlId
                        control: DeviceControl
                </literallayout>
            where
                <literallayout>
                DeviceControl: DeviceResolutionControl
                =&gt;
                        status: {Success, DeviceBusy, AlreadyGrabbed}
            </literallayout>
            Errors: Length, Device, Match, Value</para>
            <para>ChangeDeviceControl changes the specifed device control according to the values
                specified in the DeviceControl structure. The device control must be supported
                by the target server and device or an error will result.</para>
            <para>The information passed with this request varies according to the specified 
                control and is mapped by a structure appropriate for that control.</para>
            <para>ChangeDeviceControl will fail with a BadValue error if the server does not 
                support the specified control. It will fail with a BadMatch error if the 
                server supports the specified control, but the requested device does not.
                The request will fail and return a status of DeviceBusy if another client 
                already has the device open with a device control state that conflicts with
                the one specified in the request. It will fail with a status of 
                AlreadyGrabbed if some other client has grabbed the specified device. If 
                the request succeeds, Success is returned. If it fails, the device control 
                is left unchanged.</para>
            <para>Supported device controls and the information specified for them include:
            <literallayout>
                DEVICE_RESOLUTION:
                        [control: CARD16
                         length: CARD16
                         first_valuator: CARD8
                         num_valuators: CARD8
                         resolutions: LISTofCARD32]
            </literallayout>
                This device control changes the resolution of the specified valuators
                on the specified extension input device. Valuators are numbered beginning
                with zero. Only the valuators in the range specified by first_valuator
                and num_valuators are set. A value of -1 in the resolutions list indicates 
                that the resolution for this valuator is not to be changed. num_valuators 
                specifies the number of valuators in the resolutions list.</para>
            <para>When this control is specified, XChangeDeviceControl will fail with a BadMatch
                error if the specified device has no valuators. If a resolution is specified
                that is not within the range of valid values (as returned by XGetDeviceControl)
                the request will fail with a BadValue error. If the number of valuators
                supported by the device is less than the expression first_valuator + 
                num_valuators, a BadValue error will result.</para>
            <para>If the request fails for any reason, none of the valuator resolutions will be 
                changed.</para>
        </sect2>
        <sect2 id='selecting_extension_device_events'><title>Selecting Extension Device Events</title>
            <para>Extension input events are selected using the <emphasis>SelectExtensionEvent</emphasis>
                request.
                <literallayout>
                SelectExtensionEvent
                        interest: LISTofEVENTCLASS
                        window: WINDOW
                </literallayout>
                Errors: Window, Class, Access</para>
            <para>This request specifies to the server the events within the specified window
                which are of interest to the client. As with the core <emphasis>XSelectInput</emphasis>
                function, multiple clients can select input on the same window.</para>
            <para><emphasis>XSelectExtensionEvent</emphasis> requires a list of <emphasis remap='I'>event classes</emphasis>.
                An event class is a 32-bit number that combines an event type and
                device id, and is used to indicate which event a client wishes to 
                receive and from which device it wishes to receive it. Macros
                are provided to obtain event classes from the data returned by
                the <emphasis>XOpenDevice</emphasis> request. The names of these macros correspond
                to the desired events, i.e. the <emphasis>DeviceKeyPress</emphasis> is used to 
                obtain the event class for <emphasis>DeviceKeyPress</emphasis> events. The syntax
                of the macro invocation is:
                <synopsis>
                    DeviceKeyPress (device, event_type, event_class);
                        device: DEVICE
                        event_type: INT
                        event_class: INT
                </synopsis>
            </para>
            <para>The value returned in <emphasis>event_type</emphasis> is the value that will be contained in
                the event type field of the <emphasis>XDeviceKeyPressEvent</emphasis> when it is received by 
                the client. The value returned in <emphasis>event_class</emphasis> is the value that should
                be passed in making an <emphasis>XSelectExtensionEvent</emphasis> request to receive
                <emphasis>DeviceKeyPress</emphasis> events.</para>
            <para>For <emphasis>DeviceButtonPress</emphasis> events, the client may specify whether
                or not an implicit passive grab should be done when the button is
                pressed. If the client wants to guarantee that it will receive
                a <emphasis>DeviceButtonRelease</emphasis> event for each <emphasis>DeviceButtonPress</emphasis>
                event it receives, it should specify the <emphasis>DeviceButtonPressGrab</emphasis>
                event class as well as the <emphasis>DeviceButtonPress</emphasis> event class.
                This restricts the client in that only one client at a time
                may request <emphasis>DeviceButtonPress</emphasis> events from the same device and
                window if any client specifies this class.</para>
            <para>If any client has specified the <emphasis>DeviceButtonPressGrab</emphasis> class, any requests
                by any other client that specify the same device and window and specify
                <emphasis>DeviceButtonPress</emphasis> or <emphasis>DeviceButtonPressGrab</emphasis> will
                cause an <emphasis>Access</emphasis> error to be generated.</para>
            <para>If only the <emphasis>DeviceButtonPress</emphasis> class is specified, no implicit
                passive grab will be done when a button is pressed on the device.
                Multiple clients may use this class to specify the same device and
                window combination.</para>
            <para>A client may also specify the <emphasis>DeviceOwnerGrabButton</emphasis> class. If it has
                specified both the <emphasis>DeviceButtonPressGrab</emphasis> and the  
                <emphasis>DeviceOwnerGrabButton</emphasis> classes, implicit passive grabs will activate
                with owner_events set to <emphasis>True</emphasis>. If only the 
                <emphasis>DeviceButtonPressGrab</emphasis> class is specified, implicit passive grabs will
                activate with owner_events set to <emphasis>False</emphasis>.</para>
            <para>The client may select <emphasis>DeviceMotion</emphasis> events only when a 
                button is down. It does this by specifying the event classes 
                <emphasis>Button1Motion</emphasis> through <emphasis>Button5Motion</emphasis>, or <emphasis>ButtonMotion</emphasis>. 
                An input device will only support
                as many button motion classes as it has buttons.</para>
        </sect2>
        <sect2 id='determining_selected_events'><title>Determining Selected Events</title>
            <para>To determine which extension events are currently selected from a given
                window, use <emphasis>GetSelectedExtensionEvents</emphasis>.
                <literallayout>
                GetSelectedExtensionEvents 
                        window: WINDOW
                =&gt;
                        this-client: LISTofEVENTCLASS
                        all-clients: LISTofEVENTCLASS
                </literallayout>
            Errors: Window</para>
            <para>This request returns two lists specifying the events selected on the specified
                window. One list gives the extension events selected by this client from
                the specified window. The other list gives the extension events selected by
                all clients from the specified window. This information is equivalent
                to that returned by your-event-mask and all-event-masks in a
                <emphasis>GetWindowAttributes</emphasis> request.</para> 
        </sect2>
        <sect2 id='controlling_event_propagation'><title>Controlling Event Propagation</title>
            <para>Extension events propagate up the window hierarchy in the same manner
                as core events. If a window is not interested in an extension event, 
                it usually propagates to the closest ancestor that is interested,
                unless the dont_propagate list prohibits it.
                Grabs of extension devices may alter the set of windows that receive a 
                particular extension event.</para>
            <para>Client programs may control extension event propagation through the use
                of the following two requests.</para>  
            <para><emphasis>XChangeDeviceDontPropagateList</emphasis> adds an event to or deletes an event from 
                the do_not_propagate list of extension events for the specified window. This
                list is maintained for the life of the window, and is not altered if the 
                client terminates.

                <literallayout>
                ChangeDeviceDontPropagateList
                        window: WINDOW
                        eventclass: LISTofEVENTCLASS
                        mode: {AddToList, DeleteFromList}
                </literallayout>
                Errors: Window, Class, Mode</para>
            <para>This function modifies the list specifying the events that are not propagated
                to the ancestors of the specified window. You may use the modes <emphasis>AddToList</emphasis>
                or <emphasis>DeleteFromList</emphasis>.
                <literallayout>
                GetDeviceDontPropagateList
                        window: WINDOW
                        Errors: Window
                =&gt;
                        dont-propagate-list: LISTofEVENTCLASS
                </literallayout>
            This function returns a list specifying the events that are not propagated
                to the ancestors of the specified window.</para>
        </sect2>
        <sect2 id='sending_extension_events'><title>Sending Extension Events</title>
            <para>One client program may send an event to another via the 
                <emphasis>XSendExtensionEvent</emphasis> function.</para>
            <para>The event in the <emphasis>XEvent</emphasis> structure must be one of the events defined
                by the input extension, so that the X server can correctly byte swap the
                contents as necessary. The contents of the event are otherwise unaltered
                and unchecked by the X server except to force send_event to <emphasis>True</emphasis>
                in the forwarded event and to set the sequence number in the event correctly.</para>
            <para>XSendExtensionEvent returns zero if the conversion-to-wire protocol
                failed, otherwise it returns nonzero.
                <literallayout>
                SendExtensionEvent
                        device: DEVICE
                        destination: WINDOW
                        propagate: BOOL
                        eventclass: LISTofEVENTCLASS
                        event: XEVENT
                </literallayout>
            Errors: Device, Value, Class, Window</para>
        </sect2>
        <sect2 id='getting_motion_history'><title>Getting Motion History</title>
            <para>
                <literallayout>
                GetDeviceMotionEvents 
                        device: DEVICE
                        start, stop: TIMESTAMP or CurrentTime
                =&gt;
                        nevents_return: CARD32
                        mode_return: {Absolute, Relative}
                        axis_count_return: CARD8
                        events: LISTofDEVICETIMECOORD
            </literallayout>
            where
            <literallayout>
                DEVICETIMECOORD:
                        [data: LISTofINT32
                         time: TIMESTAMP]
            </literallayout>
            Errors: Device, Match</para>
            <para>This request returns all positions in the device's motion history buffer
                that fall between the specified start and stop times inclusive. If the
                start time is in the future, or is later than the stop time, no positions
                are returned.</para>
            <para>The data field of the DEVICETIMECOORD structure is a sequence of 
                data items. Each item is of type INT32, and there is one data item
                per axis of motion reported by the device. 
                The number of axes reported
                by the device is returned in the axis_count variable.</para>
            <para>The value of the data items depends on the mode of the device, which
                is returned in the mode variable.
                If the mode is Absolute, the data items are the raw values 
                generated by the device. These may be scaled by the client program 
                using the maximum values that the device can generate for each axis 
                of motion that it reports. The maximum and minimum values for each 
                axis are reported by the <emphasis>ListInputDevices</emphasis> request.</para>
            <para>If the mode is Relative, the data items are the relative values
                generated by the device. The client program must choose an initial
                position for the device and maintain a current position by 
                accumulating these relative values.</para>
        </sect2>
        <sect2 id='changing_the_core_devices'><title>Changing The Core Devices</title>
            <para>These requests are provided to change which physical device is used
                as the X pointer or X keyboard.
                These requests are deprecated in servers supporting XI 1.4 and
                above, and will always return a a <emphasis>BadDevice</emphasis>
                error.
            </para>
            <para>Using these requests may change the characteristics of the core devices.
                The new pointer device may have a different number of buttons than the 
                old one did, or the new keyboard device may have a different number of
                keys or report a different range of keycodes. Client programs may be
                running that depend on those characteristics. For example, a client
                program could allocate an array based on the number of buttons on the
                pointer device, and then use the button numbers received in button events
                as indicies into that array. Changing the core devices could cause
                such client programs to behave improperly or abnormally terminate.</para>
            <para>These requests change the X keyboard or X pointer device and generate
                an <emphasis>ChangeDeviceNotify</emphasis> event and a <emphasis>MappingNotify</emphasis> event. 
                The <emphasis>ChangeDeviceNotify</emphasis> event is sent only to those clients that have 
                expressed an interest in receiving that event via the 
                <emphasis>XSelectExtensionEvent</emphasis> request.
                The specified device becomes the
                new X keyboard or X pointer device. The location of the core device
                does not change as a result of this request.</para>
            <para>These requests fail and return <emphasis>AlreadyGrabbed</emphasis> if either the specified
                device or the core device it would replace are grabbed by some other
                client. They fail and return <emphasis>GrabFrozen</emphasis> if either device is frozen
                by the active grab of another client.</para>
            <para>These requests fail with a <emphasis>BadDevice</emphasis> error if the specified device is
                invalid, or has not previously been opened via <emphasis>OpenDevice</emphasis>.
                To change the X keyboard device, use the <emphasis>ChangeKeyboardDevice</emphasis> request.
                The specified device must support input class Keys (as reported in the
                ListInputDevices request) or the request will fail with a <emphasis>BadMatch</emphasis> error.
                Once the device has successfully replaced one of the core devices, it
                is treated as a core device until it is in turn replaced by another
                ChangeDevice request, or until the server terminates. The termination
                of the client that changed  the device will not cause it to change back.
                Attempts to use the CloseDevice request to close the new core device will
                fail with a BadDevice error.</para>
            <para>The focus state of the new keyboard is the same as the focus state of the old 
                X keyboard. If the new keyboard was not initialized with a <emphasis>FocusRec</emphasis>,
                one is added by the <emphasis>ChangeKeyboardDevice</emphasis> request. The X keyboard is 
                assumed to have a <emphasis>KbdFeedbackClassRec</emphasis>. If the device was initialized
                without a <emphasis>KbdFeedbackClassRec</emphasis>, one will be added by this request.
                The <emphasis>KbdFeedbackClassRec</emphasis> will specify a null routine as the control 
                procedure and the bell procedure.
                <literallayout>
                ChangeKeyboardDevice 
                        device: DEVICE
                        Errors: Device, Match
                =&gt;
                        status: Success, AlreadyGrabbed, Frozen
                </literallayout>
            </para>
            <para>To change the X pointer device, use the <emphasis>ChangePointerDevice</emphasis> request.
                The specified device must support input class Valuators (as reported in the
                ListInputDevices request) or the request will fail with a BadMatch error.
                The valuators to be used as the x- and y-axes of the pointer device must
                be specified. Data from other valuators on the device will be ignored.</para>
            <para>The X pointer device does not contain a <emphasis>FocusRec</emphasis>. If the new
                pointer was initialized with a <emphasis>FocusRec</emphasis>, it is freed by the 
                <emphasis>ChangePointerDevice</emphasis> request. The X pointer is assumed to have a
                <emphasis>ButtonClassRec</emphasis> and a <emphasis>PtrFeedbackClassRec</emphasis>. If the device
                was initialized without a <emphasis>ButtonClassRec</emphasis> or a <emphasis>PtrFeedbackClassRec</emphasis>,
                one will be added by this request. The <emphasis>ButtonClassRec</emphasis> added will
                have no buttons, and the <emphasis>PtrFeedbackClassRec</emphasis> will specify a null
                routine as the control procedure.</para>
            <para>If the specified device reports absolute positional information, and the 
                server implementation does not allow such a device to be used as the 
                X pointer, the request will fail with a <emphasis>BadDevice</emphasis> error.</para>
            <para>Once the device has successfully replaced one of the core devices, it
                is treated as a core device until it is in turn replaced by another
                ChangeDevice request, or until the server terminates. The termination
                of the client that changed  the device will not cause it to change back.
                Attempts to use the CloseDevice request to close the new core device will
                fail with a BadDevice error.
                <literallayout>
                ChangePointerDevice 
                        device: DEVICE
                        xaxis: CARD8
                        yaxis: CARD8
                =&gt;
                        status: Success, AlreadyGrabbed, Frozen
                </literallayout>
                Errors: Device, Match</para>
        </sect2>
        <sect2 id='event_synchronization_and_core_grabs'><title>Event Synchronization And Core Grabs</title>
            <para>Implementation of the input extension requires an extension of the
                meaning of event synchronization for the core grab requests. This is
                necessary in order to allow window managers to freeze all input devices
                with a single request.</para>
            <para>The core grab requests require a <emphasis>pointer_mode</emphasis> and <emphasis>keyboard_mode</emphasis>
                argument. The meaning of these modes is changed by the input extension.
                For the <emphasis>XGrabPointer</emphasis> and <emphasis>XGrabButton</emphasis> requests, <emphasis>pointer_mode</emphasis>
                controls synchronization of the pointer device, and <emphasis>keyboard_mode</emphasis>
                controls the synchronization of all other input devices. 
                For the <emphasis>XGrabKeyboard</emphasis>
                and <emphasis>XGrabKey</emphasis> requests, <emphasis>pointer_mode</emphasis> controls the synchronization
                of all input devices except the X keyboard, while <emphasis>keyboard_mode</emphasis> controls
                the synchronization of the keyboard. When using one of the core grab
                requests, the synchronization of extension devices
                is controlled by the mode specified for the device not being grabbed.</para>
        </sect2>
        <sect2 id='extension_active_grabs'><title>Extension Active Grabs</title>
            <para>Active grabs of extension devices are supported via the <emphasis>GrabDevice</emphasis>
                request in the same way that core devices are grabbed using the core 
                GrabKeyboard request, except that a <emphasis remap='I'>Device</emphasis> is passed as
                a function parameter. A list of events that the client wishes to 
                receive is also passed. The <emphasis>UngrabDevice</emphasis> request allows a
                previous active grab for an extension device to be released.</para>
            <para>To grab an extension device, use the <emphasis>GrabDevice</emphasis> request.
                The device must have previously been opened using the <emphasis>OpenDevice</emphasis> 
                request.
                <literallayout>
                GrabDevice 
                        device: DEVICE
                        grab-window: WINDOW
                        owner-events: BOOL
                        event-list: LISTofEVENTCLASS
                        this-device-mode: {Synchronous, Asynchronous}
                        other-device-mode: {Synchronous, Asynchronous}
                        time:TIMESTAMP or CurrentTime
                =&gt;
                        status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable
                </literallayout>
            Errors:  Device, Window, Value</para>
            <para>This request actively grabs control of the specified input device. Further 
                input events from this device are reported only to the grabbing client. 
                This request overrides any previous active grab by this client for this
                device.</para>
            <para>The event-list parameter is a pointer to a list of event classes. These
                are used to indicate which events the client wishes to receive while the 
                device is grabbed. Only event classes obtained from the grabbed device
                are valid.</para>
            <para>If owner-events is <emphasis>False</emphasis>, input events generated from this 
                device are reported with respect to grab-window, and are only reported if
                selected by being included in the event-list.
                If owner-events is 
                <emphasis>True</emphasis>, then if a generated event would normally be reported to this 
                client, it is reported normally, otherwise the event is reported with 
                respect to the grab-window, and is only reported if selected by being
                included in the event-list. For either value of owner-events, unreported
                events are discarded.</para>
            <para>If this-device-mode is <emphasis>Asynchronous</emphasis>, device event processing continues 
                normally. If the device is currently frozen by this client, then processing 
                of device events is resumed. If this-device-mode is <emphasis>Synchronous</emphasis>, 
                the state of the grabbed device (as seen by means of the protocol) appears 
                to freeze,
                and no further device events are generated by the server until the grabbing 
                client issues a releasing <emphasis>AllowDeviceEvents</emphasis> request or until the device 
                grab is released. Actual device input events are not lost while the device 
                is frozen; they are simply queued for later processing.</para>
            <para>If other-device-mode is <emphasis>Asynchronous</emphasis>, event processing is 
                unaffected by activation of the grab. If other-device-mode is 
                <emphasis>Synchronous</emphasis>, the state of all input devices except the grabbed one
                (as seen by means of the protocol) appears to 
                freeze, and no further events are generated by the server until 
                the grabbing client issues a releasing <emphasis>AllowDeviceEvents</emphasis> request or 
                until the device grab is released. Actual events are not lost
                while the devices are frozen; they are simply queued for later
                processing.</para>
            <para>This request generates <emphasis>DeviceFocusIn</emphasis> and <emphasis>DeviceFocusOut</emphasis> events.</para>  
            <para>This request fails and returns:</para>
            <variablelist remap='IP'>
                <varlistentry>
                    <term><constant>AlreadyGrabbed</constant></term>
                    <listitem><para>If the device is actively grabbed by some
                            other client.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><constant>NotViewable</constant></term>
                    <listitem>
                        <para> If grab-window is not viewable.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><constant>InvalidTime</constant></term>
                    <listitem>
                        <para>
                            If the specified time is earlier
                            than the last-grab-time for the specified device
                            or later than the current X server time. Otherwise,
                            the last-grab-time for the specified device is set
                            to the specified time and 
                            <emphasis>CurrentTime</emphasis>
                            is replaced by the current X server time.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><constant>Frozen</constant></term>
                    <listitem>
                        <para>If the device is frozen by an active grab of another client.</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>If a grabbed device is closed by a client while an active grab by that 
                client is in
                effect, that active grab will be released. Any passive grabs established by
                that client will be released. If the device is frozen only by an active grab
                of the requesting client, it is thawed.</para>
            <para>To release a grab of an extension device, use <emphasis>UngrabDevice</emphasis>.
                <literallayout>
                UngrabDevice 
                        device: DEVICE
                        time: TIMESTAMP or CurrentTime
                </literallayout>
            Errors: Device</para>

            <para>This request releases the device if this client has it actively grabbed
                (from either <emphasis>GrabDevice</emphasis> or <emphasis>GrabDeviceKey</emphasis>) and releases
                any queued events. If any devices were frozen by the grab,
                <emphasis>UngrabDevice</emphasis> thaws them.
                The request has no effect if the specified time is earlier 
                than the last-device-grab time or is later than the current server time.</para>  
            <para>This request generates <emphasis>DeviceFocusIn</emphasis> and <emphasis>DeviceFocusOut</emphasis> events.</para>  
            <para>An <emphasis>UngrabDevice</emphasis> is performed automatically if the event window for an
                active device grab becomes not viewable.</para>
        </sect2>
        <sect2 id='passively_grabbing_a_key'><title>Passively Grabbing A Key</title>
            <para>Passive grabs of buttons and keys on extension devices are supported
                via the <emphasis>GrabDeviceButton</emphasis> and <emphasis>GrabDeviceKey</emphasis> requests.
                These passive grabs are released via the <emphasis>UngrabDeviceKey</emphasis> and
                <emphasis>UngrabDeviceButton</emphasis> requests.</para>
            <para>To passively grab a single key on an extension device, use <emphasis>GrabDeviceKey</emphasis>.
                That device must have previously been opened using the <emphasis>OpenDevice</emphasis> 
                request.
                <literallayout>
                GrabDeviceKey
                        device: DEVICE
                        keycode: KEYCODE or AnyKey
                        modifiers: SETofKEYMASK or AnyModifier
                        modifier-device: DEVICE or NULL
                        grab-window: WINDOW
                        owner-events: BOOL
                        event-list: LISTofEVENTCLASS
                        this-device-mode: {Synchronous, Asynchronous}
                        other-device-mode: {Synchronous, Asynchronous}
                </literallayout>
            </para>
            <para>Errors:  Device, Match, Access, Window, Value</para>
            <para>This request is analogous to the core <emphasis>GrabKey</emphasis> request. It establishes a 
                passive grab on a device. Consequently, in the future:
                <itemizedlist>
                    <listitem>
                        <para>IF the device is not grabbed and the specified key, which itself can be a 
                            modifier key, is logically pressed when the specified modifier keys 
                            logically are down on the specified modifier device (and no other 
                            keys are down),</para>
                    </listitem>
                    <listitem>
                        <para>AND no other modifier keys logically are down,</para>
                    </listitem>
                    <listitem>
                        <para>AND EITHER the grab window is an ancestor of (or is) the focus window
                            OR the grab window is a descendent of the focus window and contains the pointer,</para>
                    </listitem>
                    <listitem>
                        <para>AND a passive grab on the same device and key combination does not exist on any
                            ancestor of the grab window,</para>
                    </listitem>
                    <listitem>
                        <para>THEN the device is actively grabbed, as for <emphasis>GrabDevice</emphasis>,
                            the last-device-grab time is set to the time at which the key was pressed
                            (as transmitted in the <emphasis>DeviceKeyPress</emphasis> event), and the 
                            <emphasis>DeviceKeyPress</emphasis> event is reported.</para>
                    </listitem>
            </itemizedlist>
            </para>
            <para>The interpretation of the remaining arguments is as for <emphasis>GrabDevice</emphasis>.
                The active grab is terminated automatically when logical state of the
                device has the specified key released (independent of the logical state of the 
                modifier keys).</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>A modifier of <emphasis>AnyModifier</emphasis> is equivalent to issuing the request for all
                possible modifier combinations (including the combination of no modifiers). 
                It is not required that all modifiers specified have currently assigned 
                keycodes.
                A key of <emphasis>AnyKey</emphasis> is equivalent to issuing
                the request for all possible keycodes. Otherwise, the key must be in
                the range specified by min-keycode and max-keycode in the <emphasis>ListInputDevices</emphasis>
                request. If it is not within that range, <emphasis>GrabDeviceKey</emphasis> generates a
                <emphasis>Value</emphasis> error.</para>
            <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is
                <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para>
            <para>An <emphasis>Access</emphasis> error is generated if some other client has issued a 
                <emphasis>GrabDeviceKey</emphasis> with the same device and key combination on the 
                same window. When using <emphasis>AnyModifier</emphasis> or <emphasis>AnyKey</emphasis>,
                the request fails completely and the X server generates a <emphasis>Access</emphasis>
                error and no grabs are established if there is a conflicting grab for any 
                combination.</para>
            <para>This request cannot be used to grab a key on the X keyboard device. 
                The core <emphasis>GrabKey</emphasis> request should be used for that purpose.</para>
            <para>To release a passive grab of a single key on an extension device, 
                use <emphasis>UngrabDeviceKey</emphasis>.
                <literallayout>
                UngrabDeviceKey
                        device: DEVICE
                        keycode: KEYCODE or AnyKey
                        modifiers: SETofKEYMASK or AnyModifier
                        modifier-device: DEVICE or NULL
                        grab-window: WINDOW
                </literallayout>
            Errors:  Device, Match, Window, Value, Alloc</para>
            <para>This request is analogous to the core <emphasis>UngrabKey</emphasis> request. It releases 
                the key combination on the specified window if it was grabbed by this 
                client. A modifier of <emphasis>AnyModifier</emphasis> is equivalent to issuing the 
                request for all possible modifier combinations (including the combination 
                of no modifiers). A key of <emphasis>AnyKey</emphasis> is equivalent to issuing the 
                request for all possible keycodes. This request has no effect on an 
                active grab.</para>
            <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is
                <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para>
        </sect2>
        <sect2 id='passively_grabbing_a_button'><title>Passively Grabbing A Button</title>
            <para>To establish a passive grab for a single button on an extension device,
                use <emphasis>GrabDeviceButton</emphasis>.
                <literallayout>
                GrabDeviceButton
                        device: DEVICE
                        button: BUTTON or AnyButton
                        modifiers: SETofKEYMASK or AnyModifier
                        modifier-device: DEVICE or NULL
                        grab-window: WINDOW
                        owner-events: BOOL
                        event-list: LISTofEVENTCLASS
                        this-device-mode: {Synchronous, Asynchronous}
                        other-device-mode: {Synchronous, Asynchronous}
                    </literallayout>
                Errors:  Device, Match, Window, Access, Value</para>
            <para>This request is analogous to the core <emphasis>GrabButton</emphasis> request. It 
                establishes an explicit passive grab for a button on an extension input 
                device. Since the server does not track extension devices, no cursor is 
                specified with this request. For the same reason, there is no 
                confine-to parameter. The device must have previously been opened using the
                <emphasis>OpenDevice</emphasis> request.</para>
            <para>The <emphasis>GrabDeviceButton</emphasis> request establishes a passive grab on a device.
                Consequently, in the future,</para> 
            <variablelist remap='IP'>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>IF the device is not grabbed and the specified button is logically pressed
                            when the specified modifier keys logically are down 
                            (and no other buttons or modifier keys are down),</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>AND the grab window contains the device,</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>AND a passive grab on the same device and button/ key combination does not 
                            exist on any ancestor of the grab window,</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>THEN the device is actively grabbed, as for <emphasis>GrabDevice</emphasis>,
                            the last-grab time is set to the time at which the button was pressed
                            (as transmitted in the <emphasis>DeviceButtonPress</emphasis> event), and the 
                            <emphasis>DeviceButtonPress</emphasis> event is reported.</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>The interpretation of the remaining arguments is as for 
                <emphasis>GrabDevice</emphasis>.
                The active grab is terminated automatically when logical state of the
                device has all buttons released (independent of the logical state of 
                the modifier keys).</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>A modifier of <emphasis>AnyModifier</emphasis> is equivalent to issuing the request for all
                possible modifier combinations (including the combination of no modifiers). 
                It is not required that all modifiers specified have currently assigned 
                keycodes. A button of <emphasis>AnyButton</emphasis> is equivalent to issuing the request 
                for all possible buttons. It is not required that the 
                specified button be assigned to a physical button.</para>
            <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is
                <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para>
            <para>An <emphasis>Access</emphasis> error is generated if some other client has issued a 
                <emphasis>GrabDeviceButton</emphasis> with the same device and button combination on the 
                same window. When using <emphasis>AnyModifier</emphasis> or <emphasis>AnyButton</emphasis>, the request 
                fails completely and the X server generates a <emphasis>Access</emphasis>
                error and no grabs are established if there is a conflicting grab for any 
                combination. The request has no effect on an active grab.</para>
            <para>This request cannot be used to grab a button on the X pointer
                device. The core <emphasis>GrabButton</emphasis> request should be used for that
                purpose.</para>
            <para>To release a passive grab of a button on an extension device, use 
                <emphasis>UngrabDeviceButton</emphasis>.
                <literallayout>
                UngrabDeviceButton
                        device: DEVICE
                        button: BUTTON or AnyButton
                        modifiers: SETofKEYMASK or AnyModifier
                        modifier-device: DEVICE or NULL
                        grab-window: WINDOW
                    </literallayout>
                Errors:  Device, Match, Window, Value, Alloc</para>
                <para>This request is analogous to the core UngrabButton request. It releases 
                    the passive button/key combination on the specified window if it was grabbed
                    by the client. A modifiers of <emphasis>AnyModifier</emphasis> is equivalent to issuing the
                    request for all possible modifier combinations (including the combination
                    of no modifiers). A button of <emphasis>AnyButton</emphasis> is equivalent to issuing the
                    request for all possible buttons. This request has no effect on an
                    active grab. The device must have previously been opened using the
                    <emphasis>OpenDevice</emphasis> request otherwise a <emphasis>Device</emphasis> error will be 
                    generated.</para>
                <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is
                    <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para>
                <para>This request cannot be used to ungrab a button on the X pointer
                    device. The core <emphasis>UngrabButton</emphasis> request should be used for that 
                    purpose.</para>
            </sect2>
            <sect2 id='thawing_a_device'><title>Thawing A Device</title>
                <para>To allow further events to be processed when a device has been frozen,
                    use <emphasis>AllowDeviceEvents</emphasis>.
                <literallayout>
                AllowDeviceEvents 
                        device: DEVICE
                        event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices, 
                        ReplayThisdevice, AsyncAll, or SyncAll}
                        time:TIMESTAMP or CurrentTime
                </literallayout>
                Errors:  Device, Value</para>
                <para>The <emphasis>AllowDeviceEvents</emphasis> request releases some queued events if the client
                    has caused a device to freeze. The request has no effect if the 
                    specified time is earlier than the last-grab time of the most recent 
                    active grab for the client, 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>
                <variablelist remap='IP'>
                    <varlistentry>
                        <term>&bull;</term>
                        <listitem>
                            <para>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, AsyncThisDevice thaws for all.
                            AsyncThisDevice has no effect if the specified device is not frozen by the 
                            client, but the device need not be grabbed by the client.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If the specified device is frozen and actively grabbed by the client,
                            event processing for that device continues normally until the next 
                            button or key 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.
                            SyncThisDevice has no effect if the specified device is not frozen by the client
                            or is not grabbed by the client.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>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 Grab),
                            the grab is released and that event is completely reprocessed.
                            This time, however, the request ignores any passive grabs at or above 
                            (towards the root) the grab-window of the grab just released.
                            The request has no effect if the specified device is not grabbed by the client
                            or if it is not frozen as the result of an event.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If the remaining devices are frozen by the client,
                            event processing for them continues as usual.
                            If the other devices are frozen multiple times  by the client on behalf of 
                            multiple separate grabs,
                            AsyncOtherDevices &ldquo;thaws&rdquo; for all.
                            AsyncOtherDevices has no effect if the devices are not frozen by the client,
                            but those devices need not be grabbed by the client.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>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 (button event for the grabbed device, key
                            or motion event for the device), at which time the devices again appear to
                            freeze. However, if the reported event causes the grab to be released,
                            then the devices do not freeze (but if any device is still
                            grabbed, then a subsequent event for it will still cause all devices
                            to freeze). 
                            SyncAll 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, 
                            SyncAll "thaws" for both (but a subsequent freeze for SyncAll
                            will only freeze each device once).</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>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, AsyncAll "thaws" for all.
                            AsyncAll has no effect unless all
                            devices are frozen by the client.</para>
                        <para>AsyncThisDevice, SyncThisDevice, and ReplayThisDevice 
                            have no effect on the processing of events from the remaining devices.
                            AsyncOtherDevices has no effect on the processing of events from the 
                            specified device.
                            When the event_mode is SyncAll or AsyncAll, 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>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect2>
        <sect2 id='controlling_device_focus'><title>Controlling Device Focus</title>
            <para>The current focus window for an extension input device can be 
                determined using the <emphasis>GetDeviceFocus</emphasis> request.
                Extension devices are focused using the <emphasis>SetDeviceFocus</emphasis>
                request in the same way that the keyboard is focused using
                the <emphasis>SetInputFocus</emphasis> request, except that a device is specified as
                part of the request. One additional focus state, <emphasis>FollowKeyboard</emphasis>,
                is provided for extension devices.</para>
            <para>To get the current focus state, revert state, and focus time of an extension device,
                use <emphasis>GetDeviceFocus</emphasis>.
                <literallayout>
                GetDeviceFocus
                        device: DEVICE
                =&gt;
                        focus: WINDOW, PointerRoot, FollowKeyboard, or None
                        revert-to: Parent, PointerRoot, FollowKeyboard, or None
                        focus-time: TIMESTAMP
                </literallayout>
            Errors:  Device, Match</para>
            <para>This request returns the current focus state, revert-to state, 
                and last-focus-time of an extension device.</para>
            <para>To set the focus of an extension device, use <emphasis>SetDeviceFocus</emphasis>.
                <literallayout>
                SetDeviceFocus 
                        device: DEVICE
                        focus: WINDOW, PointerRoot, FollowKeyboard, or None
                        revert-to: Parent, PointerRoot, FollowKeyboard, or None
                        focus-time: TIMESTAMP
                </literallayout>
            Errors:  Device, Window, Value, Match</para>
            <para>This request changes the focus for an extension input device and the 
                last-focus-change-time. The request has no effect if the specified 
                time is earlier than the last-focus-change-time or is later than the
                current X server time. Otherwise, the last-focus-change-time is set to the
                specified time, with CurrentTime replaced by the current server time.</para>
            <para>The action taken by the server when this request is requested depends
                on the value of the focus argument:</para>
            <variablelist remap='IP'>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If the focus argument is <emphasis>None</emphasis>, all input events from this device
                            will be discarded until a new focus window is set. In this case, the
                            revert-to argument is ignored.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If a window ID is assigned to the focus argument, it becomes the focus
                            window of the device. If an input event from the device would normally
                            be reported to this window or to one of its inferiors, the event is 
                            reported normally. Otherwise, the event is reported relative to the focus 
                            window.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If you assign <emphasis>PointerRoot</emphasis> to the focus argument, the focus window is 
                            dynamically taken to be the root window of whatever screen the pointer is
                            on at each input event. In this case, the revert-to argument is ignored.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If you assign <emphasis>FollowKeyboard</emphasis> to the focus argument, the focus window is 
                            dynamically taken to be the same as the focus of the X keyboard at each
                            input event.</para>
                        <para>The specified focus window must be viewable at the time of the request 
                            (else a <emphasis>Match</emphasis> error). If the focus window later becomes not viewable, 
                            the X server evaluates the revert-to argument
                            to determine the new focus window.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If you assign <emphasis>RevertToParent</emphasis>
                            to the revert-to argument, the focus reverts to the parent
                            (or the closest viewable ancestor), and the new revert-to value is taken to
                            be <emphasis>RevertToNone</emphasis>.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>&bull;</term>
                    <listitem>
                        <para>If you assign <emphasis>RevertToPointerRoot</emphasis>,
                            <emphasis>RevertToFollowKeyboard</emphasis>, or
                            <emphasis>RevertToNone</emphasis> to the revert-to
                            argument, the focus reverts to that value.</para>
                    </listitem>
                </varlistentry>
            </variablelist>
            <para>When the focus reverts,
                the X server generates <emphasis>DeviceFocusIn</emphasis>
                and <emphasis>DeviceFocusOut</emphasis>
                events, but the last-focus-change time is not affected.</para>
            <para>This request causes the X server to generate <emphasis>DeviceFocusIn</emphasis> and 
                <emphasis>DeviceFocusOut</emphasis> events.</para>
        </sect2>
        <sect2 id='controlling_device_feedback'><title>Controlling Device Feedback</title>
            <para>To get the settings of feedbacks on an extension device, use
                <emphasis>GetFeedbackControl</emphasis>.  This request provides functionality equivalent to
                the core <emphasis>GetKeyboardControl</emphasis> and <emphasis>GetPointerControl</emphasis> functions. It
                also provides a way to control displays associated with an input device that
                are capable of displaying an integer or string.
                <literallayout>
                GetFeedbackControl 
                        device: DEVICE
                =&gt;
                        num_feedbacks_return: CARD16
                        return_value: LISTofFEEDBACKSTATE
                </literallayout>
                where
                <literallayout>
                    FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState, 
                                    IntegerFeedbackState, StringFeedbackState, 
                                    BellFeedbackState, LedFeedbackState}
                </literallayout>
            </para>
            <para>Feedbacks are reported by class. Those
                feedbacks that are reported for the core keyboard device are in class
                <emphasis>KbdFeedback</emphasis>, and are returned in the 
                <emphasis>KbdFeedbackState</emphasis> structure. The members of that structure are as follows:
                <literallayout>
                CLASS Kbd:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         key_click_percent: CARD8
                         bell_percent: CARD8
                         bell_pitch: CARD16
                         bell_duration: CARD16
                         led_value: BITMASK
                         global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff}
                         auto_repeats: LISTofCARD8]
                </literallayout>
            </para>
            <para>Those feedbacks that are equivalent to those reported for the core pointer
                are in feedback class <emphasis>PtrFeedback</emphasis> and are reported in the 
                <emphasis>PtrFeedbackState</emphasis> structure. The members of that structure are:
                <literallayout>
                CLASS Ptr:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         accelNumerator: CARD16
                         accelDenominator: CARD16
                         threshold: CARD16]
                </literallayout>
            </para>
            <para>Some input devices provide a means of displaying an integer. Those devices
                  will support feedback class <emphasis>IntegerFeedback</emphasis>, which is reported in the 
                  <emphasis>IntegerFeedbackState</emphasis> structure. The members of that structure are:
                  <literallayout>
                  CLASS Integer:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         resolution: CARD32
                         min-val: INT32
                         max-val: INT32]
                  </literallayout>
              </para>
              <para>Some input devices provide a means of displaying a string. Those devices
                  will support feedback class <emphasis>StringFeedback</emphasis>, which is reported in the 
                  <emphasis>StringFeedbackState</emphasis> structure. The members of that structure are:
                  <literallayout>
                  CLASS String:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         max_symbols: CARD16
                         num_keysyms_supported: CARD16
                         keysyms_supported: LISTofKEYSYM]
                </literallayout>
            </para>
            <para>Some input devices contain a bell. Those devices
                will support feedback class <emphasis>BellFeedback</emphasis>, which is reported in the 
                <emphasis>BellFeedbackState</emphasis> structure. The members of that structure are:
                  <literallayout>
                  CLASS String:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         percent: CARD8
                         pitch: CARD16
                         duration: CARD16]
                 </literallayout>
             </para>
            <para>The percent sets the base volume for the bell between 0 (off) and 100
                (loud) inclusive, if possible. Setting to -1 restores the default.
                Other negative values generate a <emphasis>Value</emphasis> error.</para>
            <para>The pitch sets the pitch (specified in Hz) of the bell, if possible.
                Setting to -1 restores the default. Other negative values generate a 
                <emphasis>Value</emphasis> error.</para>
            <para>The duration sets the duration (specified in milliseconds) of the
                bell, if possible. Setting to -1 restores the default.
                Other negative values generate a <emphasis>Value</emphasis> error.</para>
            <para>A bell generator connected with the console but not directly on the
                device is treated as if it were part of the device.
                Some input devices contain LEDs. Those devices
                will support feedback class <emphasis>Led</emphasis>, which is reported in the 
                <emphasis>LedFeedbackState</emphasis> structure. The members of that structure are:
                  <literallayout>
                  CLASS String:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         led_mask: BITMASK
                         led_value: BITMASK]
                  </literallayout>
            </para>
            <para>Each bit in led_mask indicates that the corresponding led is supported by
                the feedback. At most 32 LEDs per feedback are supported. 
                No standard interpretation of LEDs is defined.</para>
            <para>This function will fail with a <emphasis>BadMatch</emphasis> error if the device specified 
                in the request does not support feedbacks.</para>
            <para>Errors:  Device, Match</para>
            <para>To change the settings of a feedback on an extension device, use
                <emphasis>ChangeFeedbackControl</emphasis>.
                <literallayout>
                ChangeFeedbackControl 
                        device: DEVICE
                        feedbackid: CARD8
                        value-mask: BITMASK
                        value: FEEDBACKCONTROL

                        FEEDBACKCONTROL: {KBDFEEDBACKCONTROL, 
                                          PTRFEEDBACKCONTROL, 
                                          INTEGERFEEDBACKCONTROL,
                                          STRINGFEEDBACKCONTROL, 
                                          BELLFEEDBACKCONTROL, 
                                          LEDFEEDBACKCONTROL}
                </literallayout>
            Errors:  Device, Match, Value</para>
            <para>Feedback controls are grouped by class. Those feedbacks that are 
                equivalent to those supported by the core keyboard are controlled
                by feedback class <emphasis>KbdFeedbackClass</emphasis> using the <emphasis>KbdFeedbackControl</emphasis>
                structure. The members of that structure are:
                <literallayout>
                KBDFEEDBACKCTL    
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         key_click_percent: INT8
                         bell_percent: INT8
                         bell_pitch: INT16
                         bell_duration: INT16
                         led_mask: INT32
                         led_value: INT32
                         key: KEYCODE
                         auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff, 
                                            AutoRepeatModeDefault}]
                </literallayout>
            </para>
            <para>The key_click_percent sets the volume for key clicks between 0 (off) and
                100 (loud) inclusive, if possible. Setting to -1 restores the default.
                Other negative values generate a <emphasis>Value</emphasis> error.</para>
            <para>If both auto_repeat_mode and key are specified, then the auto_repeat_mode 
                of that key is changed, if possible. If only auto_repeat_mode is specified,
                then the global auto-repeat mode for the entire keyboard is changed,
                if possible, without affecting the per-key settings. It is a <emphasis>Match</emphasis>
                error if a key is specified without an auto_repeat_mode.</para>
            <para>The order in which controls are verified and altered is server-dependent.
                If an error is generated, a subset of the controls may have been altered.</para>
            <para>Those feedback controls equivalent to those of the core pointer are 
                controlled by feedback class <emphasis>PtrFeedbackClass</emphasis> using the 
                <emphasis>PtrFeedbackControl</emphasis>
                structure. The members of that structure are as follows:
                <literallayout>
                PTRFEEDBACKCTL:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         accelNumerator: INT16
                         accelDenominator: INT16
                         threshold: INT16]
                </literallayout>
            </para>
            <para>The acceleration, expressed as a fraction, is a multiplier 
                for movement. For example, specifying 3/1 means the device moves three 
                times as fast as normal. The fraction may be rounded arbitrarily by the 
                X server. Acceleration only takes effect if the device moves more than 
                threshold pixels at once and only applies to the amount beyond the value 
                in the threshold argument. Setting a value to -1 restores the default.
                The values of the do-accel and do-threshold arguments must be nonzero for
                the device values to be set. Otherwise, the parameters will be unchanged.
                Negative values generate a <emphasis>Value</emphasis> error, as does a zero value
                for the accel-denominator argument.</para>
            <para>Some devices are capable of displaying an integer. This is done using
                feedback class <emphasis>IntegerFeedbackClass</emphasis> using the <emphasis>IntegerFeedbackControl</emphasis>
                structure. The members of that structure are as follows:
                <literallayout>
                INTEGERCTL:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         int_to_display: INT32]
                </literallayout>
            </para>
            <para>Some devices are capable of displaying an string. This is done using
                feedback class <emphasis>StringFeedbackClass</emphasis> using the <emphasis>StringFeedbackCtl</emphasis>
                structure. The members of that structure are as follows:
                <literallayout>
                STRINGCTL:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         syms_to_display: LISTofKEYSYMS]
                </literallayout>
            </para>
            <para>Some devices contain a bell. This is done using
                feedback class <emphasis>BellFeedbackClass</emphasis> using the <emphasis>BellFeedbackControl</emphasis>
                structure. The members of that structure are as follows:
                <literallayout>
                BELLCTL:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         percent: INT8
                         pitch: INT16
                         duration: INT16]
                </literallayout>
            </para>
            <para>Some devices contain leds. These can be turned on and off using
                the <emphasis>LedFeedbackControl</emphasis>
                structure. The members of that structure are as follows:
                <literallayout>
                LEDCTL:
                        [class: CARD8
                         length: CARD16
                         feedback id: CARD8
                         led_mask: BITMASK
                         led_value: BITMASK]
                </literallayout>
            Errors:  Device, Match, Value</para>
        </sect2>
        <sect2 id='ringing_a_bell_on_an_input_device'><title>Ringing a Bell on an Input Device</title>
            <para>To ring a bell on an extension input device, use <emphasis>DeviceBell</emphasis>.
                <literallayout>
                DeviceBell:
                        device: DEVICE
                        feedbackclass: CARD8
                        feedbackid: CARD8
                        percent: INT8
                </literallayout>
            Errors: Device, Value</para>
            <para>This request is analogous to the core <emphasis>Bell</emphasis> request. It rings the 
                specified bell on the specified input device feedback, using the specified
                volume.
                The specified volume is relative to the base volume for the feedback.
                If the value for the percent argument is not in the range -100 to 100
                inclusive, a <emphasis>Value</emphasis> error results.
                The volume at which the bell rings when the percent argument is nonnegative is:</para>
            <literallayout remap='DS'>
                base - [(base * percent) / 100] + percent
            </literallayout>
            <para>The volume at which the bell rings
                when the percent argument is negative is:</para>
            <literallayout remap='DS'>
                base + [(base * percent) / 100]
            </literallayout>
            <para>To change the base volume of the bell, use <emphasis>ChangeFeedbackControl</emphasis> request.</para>
        </sect2>
        <sect2 id='controlling_device_encoding'><title>Controlling Device Encoding</title>
            <para>To get the keyboard mapping of an extension device that has keys, use 
                <emphasis>GetDeviceKeyMapping</emphasis>.
                <literallayout>
                GetDeviceKeyMapping
                        device: DEVICE
                        first-keycode: KEYCODE
                        count: CARD8
                =&gt;
                        keysyms-per-keycode: CARD8
                        keysyms: LISTofKEYSYM
                </literallayout>
            Errors: Device, Match, Value</para>
            <para>This request returns the symbols for the specified number of keycodes for the 
                specified extension device, starting with the specified keycode.
                The first-keycode must be greater than or equal to
                min-keycode as returned in the connection setup (else a <emphasis>Value</emphasis> error),
                and</para>
            <literallayout remap='DS'>
                first-keycode + count - 1
            </literallayout>
            <para>must be less than or equal to max-keycode as returned in the connection setup
                (else a <emphasis>Value</emphasis> error).
                The number of elements in the keysyms list is</para>
            <literallayout remap='DS'>
                count * keysyms-per-keycode
            </literallayout>
            <para>and KEYSYM number N (counting from zero) for keycode K has an index
                (counting from zero) of</para>
            <literallayout remap='DS'>
                (K - first-keycode) * keysyms-per-keycode + N
            </literallayout>
            <para>in keysyms.
                The keysyms-per-keycode value is chosen arbitrarily by the server
                to be large enough to report all requested symbols.
                A special KEYSYM value of
                <emphasis>NoSymbol</emphasis>
                is used to fill in unused elements for individual keycodes.</para>
            <para>If the specified device has not first been opened by this client via
                <emphasis>OpenDevice</emphasis>, or if that device does not support input class Keys,
                this request will fail with a <emphasis>Device</emphasis> error.</para>
            <para>To change the keyboard mapping of an extension device that has keys, use 
                <emphasis>ChangeDeviceKeyMapping</emphasis>.
                <literallayout>
                ChangeDeviceKeyMapping
                        device: DEVICE
                        first-keycode: KEYCODE
                        keysyms-per-keycode: CARD8
                        keysyms: LISTofKEYSYM
                        num_codes: CARD8
                </literallayout>
            Errors:  Device, Match, Value, Alloc</para>
            <para>This request is analogous to the core <emphasis>ChangeKeyMapping</emphasis> request. 
                It defines the symbols for the specified number of keycodes for the 
                specified extension device.
                If the specified device has not first been opened by this client via
                <emphasis>OpenDevice</emphasis>, or if that device does not support input class Keys,
                this request will fail with a <emphasis>Device</emphasis> error.</para>
            <para>The number of elements in the keysyms list must be a multiple of
                keysyms_per_keycode. Otherwise, <emphasis>ChangeDeviceKeyMapping</emphasis> generates
                a <emphasis>Length</emphasis> error. The specified first_keycode must be greater
                than or equal to the min_keycode value returned by the <emphasis>ListInputDevices</emphasis>
                request, or this request will fail with a <emphasis>Value</emphasis> error. In addition,
                if the following expression is not less than the max_keycode value returned by
                the <emphasis>ListInputDevices</emphasis> request, the request will fail with a <emphasis>Value</emphasis>
                error:</para>
            <literallayout remap='DS'>
                first_keycode + (num_codes / keysyms_per_keycode) - 1
            </literallayout> <!-- remap='DE' -->
            <para>To obtain the keycodes that are used as modifiers on an 
                extension device that has keys, use <emphasis>GetDeviceModifierMapping</emphasis>.
                <literallayout>
                GetDeviceModifierMapping
                        device: DEVICE
                =&gt;
                        keycodes-per-modifier: CARD8
                        keycodes: LISTofKEYCODE
                </literallayout>
            Errors:  Device, Match</para>
            <para>This request is analogous to the core <emphasis>GetModifierMapping</emphasis> request. 
                This request returns the keycodes of the keys being used as modifiers.
                The number of keycodes in the list is 8*keycodes-per-modifier.
                The keycodes are divided into eight sets, with each set containing 
                keycodes-per-modifier elements. The sets are assigned in order to the 
                modifiers <emphasis>Shift</emphasis>,
                <emphasis>Lock</emphasis>, <emphasis>Control</emphasis>,
                <emphasis>Mod1</emphasis>, <emphasis>Mod2</emphasis>,
                <emphasis>Mod3</emphasis>, <emphasis>Mod4</emphasis>, and
                <emphasis>Mod5</emphasis>. The keycodes-per-modifier value is 
                chosen arbitrarily by the server; zeroes are used to fill in unused elements 
                within each set. If only zero values are given in a set, the use of the 
                corresponding modifier has been disabled. The order of keycodes within 
                each set is chosen arbitrarily by the server.</para>
            <para>To set which keycodes that are to be used as modifiers for an extension
                device, use <emphasis>SetDeviceModifierMapping</emphasis>.
                <literallayout>
                SetDeviceModifierMapping
                        device: DEVICE
                        keycodes-per-modifier: CARD8
                        keycodes: LISTofKEYCODE
                =&gt;
                        status: {Success, Busy, Failed}
                </literallayout>
            Errors:  Device, Match, Value, Alloc</para>
            <para>This request is analogous to the core <emphasis>SetModifierMapping</emphasis> request. 
                This request specifies the keycodes (if any) of the keys to be used as
                modifiers. The number of keycodes in the list must be 
                8*keycodes-per-modifier (else a <emphasis>Length</emphasis> error). The keycodes are 
                divided into eight sets, with the sets, with each set containing 
                keycodes-per-modifier elements. The sets are assigned in order to the 
                modifiers <emphasis>Shift</emphasis>,
                <emphasis>Lock</emphasis>, <emphasis>Control</emphasis>,
                <emphasis>Mod1</emphasis>, <emphasis>Mod2</emphasis>,
                <emphasis>Mod3</emphasis>, <emphasis>Mod4</emphasis>, and
                <emphasis>Mod5</emphasis>. Only non-zero keycode values are 
                used within each set; zero values are ignored. All of the non-zero 
                keycodes must be in the range specified by min-keycode and max-keycode 
                in the <emphasis>ListInputDevices</emphasis> request (else a <emphasis>Value</emphasis> error). The order of 
                keycodes within a set does not matter. If no non-zero values are specified 
                in a set, the use of the corresponding modifier is disabled, and the 
                modifier bit will always be zero. Otherwise, the modifier bit will be 
                one whenever at least one of the keys in the corresponding set is in the down
                position.</para>
            <para>A server can impose restrictions on how modifiers can be changed (for example,
                if certain keys do not generate up transitions in hardware or if multiple keys 
                per modifier are not supported). The status reply is <emphasis>Failed</emphasis>
                if some such restriction is violated, and none of the modifiers are changed.</para>
            <para>If the new non-zero keycodes specified for a modifier differ from those
                currently defined, and any (current or new) keys for that modifier are
                logically in the down state, then the status reply is <emphasis>Busy</emphasis>,
                and none of the modifiers are changed.</para>
            <para>This request generates a <emphasis remap='P->B'>DeviceMappingNotify</emphasis> event on a
                <emphasis>Success</emphasis> status. The <emphasis remap='P->B'>DeviceMappingNotify</emphasis> event will be sent only
                to those clients that have expressed an interest in receiving that event
                via the <emphasis>XSelectExtensionEvent</emphasis> request.</para>
            <para>A X server can impose restrictions on how modifiers can be changed, 
                for example, if certain keys do not generate up transitions in hardware 
                or if multiple modifier keys are not supported. If some such restriction 
                is violated, the status reply is
                <emphasis>MappingFailed</emphasis> , and none of the modifiers are changed.
                If the new keycodes specified for a modifier differ from those
                currently defined and any (current or new) keys for that modifier are
                in the logically down state, the status reply is <emphasis>MappingBusy</emphasis>, 
                and none of the modifiers are changed.</para>  
        </sect2>
        <sect2 id='controlling_button_mapping'><title>Controlling Button Mapping</title>
            <para>These requests are analogous to the core <emphasis>GetPointerMapping</emphasis>
                and <emphasis>ChangePointerMapping</emphasis> requests. They allow a client to
                determine the current mapping of buttons on an extension device,
                and to change that mapping.</para>
            <para>To get the current button mapping for an extension device, use
                <emphasis>GetDeviceButtonMapping</emphasis>.
                <literallayout>
                GetDeviceButtonMapping 
                        device: DEVICE
                        nmap: CARD8
                =&gt;
                        map_return: LISTofCARD8
                </literallayout>
            Errors:  Device, Match</para>
            <para>The <emphasis>GetDeviceButtonMapping</emphasis> function returns the current mapping of
                the buttons on the specified device. Elements of the list are indexed
                starting from one. The length of the list indicates the number of 
                physical buttons. The nominal mapping is the identity mapping map[i]=i.</para>
            <para><emphasis>nmap</emphasis> indicates the number of elements in the <emphasis>map_return</emphasis> 
                array. Only the first nmap entries will be copied by the library
                into the map_return array.</para>
            <para>To set the button mapping for an extension device, use
                <emphasis>SetDeviceButtonMapping</emphasis>.
                <literallayout>
                SetDeviceButtonMapping 
                        device: DEVICE
                        map: LISTofCARD8
                        nmap: CARD8
                =&gt;
                        status: CARD8
                </literallayout>
            Errors:  Device, Match, Value</para>
            <para>The <emphasis>SetDeviceButtonMapping</emphasis> function sets the mapping of the specified
                device and causes the X server to generate a <emphasis>DeviceMappingNotify</emphasis>
                event on a status of <emphasis>MappingSuccess</emphasis>. Elements of the list are
                indexed starting from one. The length of the list,
                specified in <emphasis>nmap</emphasis>,
                must be the same as
                <emphasis>GetDeviceButtonMapping</emphasis> would return. Otherwise,
                <emphasis>SetDeviceButtonMapping</emphasis> generates a <emphasis>Value</emphasis> error. A zero element
                disables a buttons, and elements are not restricted in value by the 
                number of physical buttons. However, no two elements can have the
                same nonzero value. Otherwise, this function generates a
                <emphasis>Value</emphasis> error. If any of the buttons to be altered are in the 
                down state, the status reply is <emphasis>MappingBusy</emphasis> and the mapping is
                not changed.</para> 
        </sect2>
        <sect2 id='obtaining_the_state_of_a_device'><title>Obtaining The State Of A Device</title>
            <para>To obtain vectors that describe the state of the keys, buttons and valuators
                of an extension device, use <emphasis>QueryDeviceState</emphasis>.
                <literallayout>
                QueryDeviceState 
                        device: DEVICE
                =&gt;
                        device-id: CARD8
                        data: LISTofINPUTCLASS
                </literallayout>
                where
                <literallayout>
                INPUTCLASS: {VALUATOR, BUTTON, KEY}

                CLASS VALUATOR:
                            [class: CARD8
                             num_valuators: CARD8
                             mode: CARD8
                             #x01 device mode (0 = Relative, 1 = Absolute)
                             #x02 proximity state (0 = InProximity, 1 = OutOfProximity)
                             valuators: LISTofINT32]

                CLASS BUTTON:
                            [class: CARD8
                             num_buttons: CARD8
                             buttons: LISTofCARD8]

                CLASS KEY:
                            [class: CARD8
                             num_keys: CARD8
                             keys: LISTofCARD8]
                </literallayout>
            Errors:  Device</para>
            <para>The <emphasis>QueryDeviceState</emphasis> request returns the current logical state of the 
                buttons, keys, and valuators on the specified input device.
                The <emphasis remap='I'>buttons</emphasis> and <emphasis remap='I'>keys</emphasis> arrays, byte N (from 0) contains the
                bits for key or button 8N to 8N+7 with the least significant bit in the
                byte representing key or button 8N.</para>
            <para>If the device has valuators, a bit in the mode field indicates whether the
                device is reporting Absolute or Relative data. If it is reporting Absolute
                data, the valuators array will contain the current value of the valuators.
                If it is reporting Relative data, the valuators array will contain undefined
                data.</para>
            <para>If the device reports proximity information, a bit in the mode field indicates
                whether the device is InProximity or OutOfProximity.</para>
        </sect2>
        <sect2 id='querying_a_devices_pointer'>
            <title>Querying A Device's Pointer</title>
            <para>
                Introduced with XI 2.0.
            <literallayout>
            QueryDevicePointer
                     window: WINDOW
                     deviceid: CARD8
            =&gt;
                     root: WINDOW
                     child: WINDOW
                        #x00 None
                     root-x: INT16
                     root-y: INT16
                     win-x: INT16
                     win-y: INT16
                     mask: CARD16
                     sameScreen: BYTE
            </literallayout>
            Errors: Device, Window
        </para>
        <para>
            The root window the specified device's pointer is logically on and
            the device's pointer coordinates relative to the root's origin are
            returned. If same-screen is <emphasis>False</emphasis>, then the
            device's pointer is not on the same screen as the argument window,
            child is <emphasis>None</emphasis>, and win-x and win-y are zero.
            If same-screen is <emphasis>True</emphasis>, then win-x and win-y
            are the device's pointer coordinates relative to the argument
            window's origin, and child is the child containing the device's
            pointer, if any. The current logical state of the modifier keys
            and the buttons are also returned. Note that the logical state of
            a device (as seen by means of the protocol) may lag the physical
            state if device event processing is frozen. If the device is a
            master device, the state of the modifier keys of the keyboard
            paired with this master are returned. If the device is an attached
            slave device, the state of the modifier keys of the keyboard
            paired with the device's master pointer are returned. If the
            device is a floating slave device, the logical state of the
            modifier keys is always zero.  
        </para> 
        <para>The above description is a modified version of the
            <emphasis>QueryPointer</emphasis> request description of the core
            protocol.
        </para>
    </sect2>
    <sect2 id='warping_a_devices_pointer'>
        <title>Warping A Device's Pointer</title>
        <para>
            Introduced with XI 2.0.
            <literallayout>
            WarpDevicePointer
                src-window: WINDOW
                dst-window: WINDOW
                src-x: INT16
                src-y: INT16
                src-width: INT16
                src-height: INT16
                dst-x: INT16
                dst-y: INT16
                deviceid: CARD8
            </literallayout>
            Errors: Device, Window, Value
        </para>
        <para>
            If dst-window is <emphasis>None</emphasis>, this request moves the
            specified device's pointer by offsets [dst-x, dst-y] relative to
            the current position of the device's pointer. If dst-window is a
            window, this request moves the device's pointer to [dst-x, dst-y]
            relative to dst-window's origin. However, if src-window is not
            <emphasis>None</emphasis>, the move only takes place if src-window
            contains the device's pointer and the device's pointer is
            contained in the specified rectangle of src-window.

            The src-x and src-y coordinates are relative to the src-window's
            origin. If src-height is zero, it is replaced with the current
            height of src-window minus src-y. If src-width is zero, it is
            replaced with the current width of src-window minus src-x.

            This request cannot be used to move the device's pointer outside
            the confine-to window of an active pointer grab or device grab. An
            attempt will only move the device's pointer as far as the closest
            edge of the confine-to window.

            This request will generate an event just as if the user had
            instantaneously moved the device's pointer.

            The above description is a modified version of the
            <emphasis>WarpPointer</emphasis> request description of the core
            protocol.  
        </para>
    </sect2>
    <sect2 id='changing_a_devices_cursor'>
        <title>Changing A Device's Cursor</title>
        <para>
            Introduced with XI 2.0.
            <literallayout>
            ChangeDeviceCursor:
                    win: WINDOW
                    cursor: CURSOR
                        #x00: None 
                    deviceid: CARD8
            </literallayout>
            Errors: Device, Window, Cursor
        </para>
        <para>
            If the device's pointer is in the window, the cursor specified
            will be used. If a cursor has been set previously for this device
            on this window, this request overwrites the previous setting. If
            the cursor is <emphasis>None</emphasis>}, the device-specific
            cursor shape is removed. The cursor shape selection is as follows:
            <itemizedlist>
                <listitem><para>Display the device's cursor if a device cursor
                        has been specified by an earlier
                    <emphasis>ChangeDeviceCursor</emphasis> request.</para>
                </listitem>
                <listitem><para>Display the window's cursor if a cursor has
                        been specified by an earlier
                        <emphasis>ChangeWindowAttributes</emphasis>
                        request.</para>
                </listitem>
                <listitem><para>Repeat on parent window until a cursor shape
                        has been found.</para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
    <sect2 id='changing_the_device_hierarchy'>
        <title>Changing The Device Hierarchy</title>
        <para>
            Introduced with XI 2.0.
            <literallayout>
            ChangeDeviceHierarchy
                    num-changes: CARD8
                    changes: ListOfHierarchyChange
            </literallayout>
            where
            <literallayout>
            HIERARCHYCHANGE: {CreateMasterInfo, RemoveMasterInfo, 
                              ChangeAttachementInfo}

            CreateMasterInfo:
                    [class: CARD16
                     length: CARD16
                     namelen: CARD16
                     sendCore: BOOL
                     enable: BOOL
                     name: STRING]

            RemoveMasterInfo:
                    [class: CARD16
                     length: CARD16
                     deviceid: CARD8
                     returnMode: CARD8
                        #x01: AttachToMaster
                        #x02: Floating
                     returnPointer: CARD8
                     returnKeyboard: CARD8]
                     
            ChangeAttachmentInfo:
                    [class: CARD16
                     length: CARD16
                     deviceid: CARD8
                     changeMode: CARD8
                        #x01: AttachToMaster
                        #x02: Floating
                     newMaster: CARD8]
            </literallayout>
            Errors: Device, Value
        </para>
        <para>
            The device hierarchy is modified as specified in changes. Changes
            is a list of one or more of <emphasis>CreateMasterInfo</emphasis>,
            <emphasis>RemoveMasterInfo</emphasis>, and
            <emphasis>ChangeAttachmentInfo</emphasis>.
        </para>
        <para>
            <emphasis>CreateMasterInfo</emphasis> creates a pair of master
            devices with the given name. The master pointer's name is
            automatically appended with &quot;&lt;space&gt;pointer&quot;, the
            master keyboard's name is automatically appended with
            &quot;&lt;space&gt;keyboard&quot;. If sendCore is
            <emphasis>True</emphasis>, the new master device sends core
            events. If enable is <emphasis>True</emphasis> the new master
            device is enabled after creation. Otherwise, the device is
            disabled and cannot send events until enabled.  </para>
        <para>
            <emphasis>RemoveMasterInfo</emphasis> removes a pair of master
            devices. The deviceid specifies the master device to remove and
            the device paired with this master device will be removed
            automatically. If returnMode is
            <emphasis>AttachToMaster</emphasis>, pointer devices attached to
            the master pointer will be attached to the device specified in
            returnPointer and keyboard devices attached to the master keyboard
            will be attached to the device specified in returnKeyboard. If
            returnMode is <emphasis>Floating</emphasis>,
            any device attached to the master pointer or master keyboard will
            be set floating and values specified in returnPointer and
            returnKeyboard are ignored.
        </para>
        <para>
            <emphasis>ChangeAttachmentInfo</emphasis> changes the attachment
            of the specified slave device. If changeMode is
            <emphasis>AttachToMaster</emphasis>, the device is reattached to
            the master device specified in newMaster. If changeMode is
            <emphasis>Floating</emphasis>, the device is set to floating and
            the value specified in newMaster is ignored.  </para>
        <para> The changes are processed in order and take effect immediately.
            If an error occurs, processing stops and the error is sent to the
            client. Changes already processed are not reversed if an error
            occurs and the client is required to issue a
            <emphasis>ListInputDevices</emphasis> request to obtain the new
            device hierarchy.  
        </para>
        <para> 
            A <emphasis>ChangeDeviceHierarchy</emphasis> request causes a
            <emphasis>DeviceHierarchyChanged</emphasis> event to be sent to
            all clients. The event is sent if at least one hierarchy change
            was successful and is sent even if a subsequent change generates
            an error.  
        </para>
    </sect2>
    <sect2 id='changing_a_windows_access_permissions'>
        <title>Changing A Window's Access Permissions</title>
        <para>
            Introduced with XI 2.0.
            <literallayout>
            ChangeWindowAccess
                window: WINDOW
                npermit:CARD8
                ndeny: CARD8
                defaultRule: CARD8
                    #x00: WindowAccessNoRule
                    #x01: WindowAccessKeepRule
                    #x02: WindowAccessDenyAll
                    #x03: WindowAccessAllowAll
                clear: CARD8
                    #x00: WindowAccessClearNone
                    #x01: WindowAccessClearPerm
                    #x02: WindowAccessClearDeny
                    #x03: WindowAccessClearRule
                    #x04: WindowAccessClearAll
                perm: LISTofCARD8
                deny: LISTofCARD8
            </literallayout>
            Errors: Window, Device, Value
        </para>
        <para>
            The access control list of the window is modified. If npermit is
            non-zero, the first p bytes after the request specify the device
            IDs of the devices permitted to access this window. If ndeny is
            non-zero, the first d bytes after the list of permitted devices
            specify the device IDs of the devices denied access to this
            window.  </para>
        <para>
            If defaultRule is <emphasis>WindowAccessNoRule</emphasis>, the
            window does not have a default rule and devices are allowed to
            access the window unless a parent window denies access. If
            defaultRule is <emphasis>WindowAccessKeepRule</emphasis>, the
            window's default rule remains unchanged from the current setting.
            If defaultRule is <emphasis>WindowAccessDenyAll</emphasis>, all
            devices are denied access to the window. If defaultRule is
            <emphasis>WindowAccessAllowAll</emphasis>, all devices are
            permitted access to the window even if a parent window restricts
            access.  </para>
        <para>
            If clear is not <emphasis>WindowAccessClearNone</emphasis>, a
            binary mask specifies the acces permissions to remove. If
            <emphasis>WindowAccessClearPerm</emphasis> is set, the list of
            permitted devices is freed. If
            <emphasis>WindowAccessClearDeny</emphasis> is set, the list of
            denied devices is freed. If
            <emphasis>WindowAccessClearRule</emphasis> is set, the default
            rule is set to <emphasis>WindowAccessNoRule</emphasis>. If clear
            is <emphasis>WindowAccessClearAll</emphasis>, all of the window's
            access settings are reset.  </para>
        <para>
            The X server tests each event for access control in the following
            order: 
            <itemizedlist> 
                <listitem><para> If the given device is in the perm list of
                        the current window, send the event.</para></listitem>
                <listitem><para> If the defaultRule of the current window is
                        <emphasis>WindowAccessDenyAll</emphasis>, discard the
                        event.</para></listitem>
                <listitem><para> If the given device is in the deny list of
                        the current window, discard the
                        event.</para></listitem> <listitem><para> If the
                        defaultRule of the current window is
                        <emphasis>WindowAccessAllowAll</emphasis>, send the
                        event.</para></listitem>
                <listitem><para> If window has a parent window, repeat on
                        parent window. Otherwise, send the
                        event.</para></listitem> </itemizedlist>
            This process is repeated until a rule of a window explicitly
            states that the event may be sent or that the event must be
            discarded.
        </para>
    </sect2>
    <sect2 id="querying_a_windows_access_permissions">
        <title>Querying A Window's Access Permissions</title>
        <para>
            Introduced with XI 2.0.
            <literallayout>
            QueryWindowAccess
                    window: WINDOW
            =&gt;
                    defaultRule: CARD8
                        #x00: WindowAccessNoRule
                        #x01: WindowAccessDenyAll
                        #x02: WindowAccessAllowAll
                    npermit: CARD8
                    ndeny: CARD8
                    perm: LISTofCARD8
                    deny: LISTofCARD8
            </literallayout>
            Errors: Window
        </para>
        <para>
            The device access control settings of the specified window are
            returned. If npermit is non-zero, the first p bytes after the
            request specify the device IDs of the  devices explicitly
            permitted access to the window. If ndeny is non-zero, the first d
            bytes after the list of permitted devices specify the device IDs
            of the devices denied access to the window.  
        </para>
        <para>
            The defaultRule can be <emphasis>WindowAccessNoRule</emphasis>,
            <emphasis>WindowAccessDenyAll</emphasis> or
            <emphasis>WindowAccessAllowAll</emphasis>.  
        </para>
    </sect2>
    <sect2 id="setting_the_client_pointer">
        <title>Setting The ClientPointer</title>
        <para>
        Introduced with XI 2.0
            <literallayout>
            SetClientPointer
                    window: WINDOW
                    deviceid: CARD8
            </literallayout>
            Errors: Window, Device
        </para>
        <para>
            The ClientPointer of the client specified by window is set to the
            device specified by deviceid. Window may be a client ID instead of
            a window ID.
        </para>
    </sect2>
    <sect2 id="querying_the_client_pointer">
        <title>Querying The ClientPointer</title>
        <para>
            Introduced with XI 2.0l.
            <literallayout>
            GetClientPointer
                     window: WINDOW
            </literallayout>
            Errors: Window
        </para>
        <para>
            The ClientPointer setting for the client specified by window is
            returned. If set is <emphasis>True</emphasis>, deviceid specifies
            the device set as ClientPointer. Otherwise, the client does not
            have a ClientPointer set and deviceid is undefined. Window may be
            client ID instead of a window ID.
        </para>
    </sect2>
    <sect2 id="registering_for_generic_events">
        <title>Registering For XI-specific GenericEvents</title>
        <para>
            Introduced with XI 2.0
            <literallayout>
            XiSelectEvent
                    window: WINDOW
                    mask: CARD32
                    deviceid: CARD8
                        #0x1f: AllDevices
            </literallayout>
            Errors: Window, Device, Value
        </para>
        <para>
            Register for the GenericEvents specified in mask on window for the
            device specified with deviceid. This request will overwrite a
            previous setting for the same device on the same window. If
            deviceid is <emphasis>AllDevices</emphasis>, the event mask
            applies to all devices. A device mask for
            <emphasis>AllDevices</emphasis> is stored separately from the
            device masks and has precedence over a device mask.  
        </para>
    </sect2>
    <sect2 id="issuing_an_extended_device_grab">
        <title>Issuing An Extended Device Grab</title>
        <para>
            Introduced with XI 2.0
            <literallayout>
            ExtendedGrabDevice
                     grab-window: Window
                     time: TIMESTAMP
                         #0x00: CurrentTime
                     deviceid: CARD8
                     device-mode: CARD8
                         #0x00: GrabModeSync
                         #0x01: GrabModeAsync
                     owner-events: BOOL
                     confine-to: WINDOW
                     cursor: CURSOR
                     event-count: CARD16
                     generic-event-count: CARD16
                     event-list: LISTofEVENTCLASS
                     generic-event-list: LISTofGENERICEVENTCLASS
            =&gt;
                     status: CARD8
            </literallayout>
            where
            <literallayout>
            GENERICEVENTCLASS:
                     extension: CARD8
                     evmask: CARD32
            </literallayout>
            Errors: Window, Device, Value
        </para>
        <para>
            This request actively grabs control of the specified input device.
            Further input events from this device are reported only to the
            grabbing client. This request overrides any previous active grab
            by this client for this device.
        </para>
        <para>
            The event-list parameter is a pointer to a list of event classes.
            These are used to indicate which events the client wishes to
            receive while the device is grabbed. Only event classes obtained
            from the grabbed device are valid.
        </para>
        <para>
            The generic-event-list parameter is a pointer to a list of generic
            event classes. These are used to indicate which generic events the
            client wishes to receive while the device is grabbed.
        </para>
        <para>
            If owner-events is <emphasis>False</emphasis>, input events
            generated from this device are reported with respect to
            grab-window, and are only reported if selected by being included
            in the event-list or generic-event-list. If owner-events is
            <emphasis>True</emphasis>, then if a generated event would
            normally be reported to this client, it is reported normally,
            otherwise the event is reported with respect to the grab-window,
            and is only reported if selected by being included in the
            event-list of the generic-event-list. For either value of
            owner-events, unreported events are discarded.
        </para>
        <para>
            If device-mode is <emphasis>GrabModeAsync</emphasis>, device event
            processing continues normally. If the device is currently frozen
            by this client, then processing of device events is resumed. If
            device-mode is <emphasis>GrabModeSync</emphasis>, the state of the
            grabbed device (as seen by means of the protocol) appears to
            freeze, and no further device events are generated by the server
            until the grabbing client issues a releasing
            <emphasis>AllowDeviceEvents</emphasis> request or until the device
            grab is released. Actual device input events are not lost while
            the device is frozen; they are simply queued for later processing.
        </para>
        <para>
            If a cursor is specified and the device is a master pointer, then
            it is displayed regardless of what window the device's pointer is
            in. If no cursor is specified, then when the pointer is in
            grab-window or one of its subwindows, the normal cursor for that
            window is displayed. Otherwise, the cursor for grab-window is
            displayed.
        </para>
        <para>
            If a confine-to window is specified and the device is a master
            pointer, then the pointer will be restricted to stay contained in
            that window. The confine-to window need have no relationship to
            the grab-window. If the pointer is not initially in the confine-to
            window, then it is warped automatically to the closest edge (and
            enter/leave events are generated normally) just before the grab
            activates. If the confine-to window is subsequently reconfigured,
            the pointer is warped automatically, as necessary, to keep it
            contained in the window. 
        </para>
        <para>
            This request generates <emphasis>DeviceFocusIn</emphasis> and
            <emphasis>DeviceFocusOut</emphasis> events for keyboard devices
            and <emphasis>DeviceEnterNotify</emphasis> and
            <emphasis>DeviceLeaveNotify</emphasis> for pointer devices.
        </para>
        <para>
            This request fails and returns: 
            <itemizedlist>
                <listitem>
                    <para> <emphasis>AlreadyGrabbed,</emphasis> if the device
                        is actively grabbed by some other
                        client.</para></listitem>
                <listitem><para> <emphasis>NotViewable,</emphasis> if
                        grab-window is not viewable. </para></listitem>
                <listitem><para> <emphasis>InvalidTime,</emphasis> if the
                        specified time is earlier than the last-grab-time for
                        the specified device or later than the current X
                        server time. Otherwise, the last-grab-time for the
                        specified device is set to the specified time and
                        <emphasis>CurrentTime</emphasis> is replaced by the
                        current X server time. </para></listitem>
                <listitem><para> <emphasis>Frozen,</emphasis> if the device is
                        frozen by an active grab of another
                        client.</para></listitem>
            </itemizedlist>
        </para>
        <para>
            The above description is a modified version of the
            <emphasis>GrabDevice</emphasis> request  description, and the
            <emphasis>GrabPointer</emphasis> request description from the core
            protocol.
        </para>
    </sect2>
</sect1>
<sect1 id='events'><title>Events</title>
    <para>The input extension creates input events analogous to the core input events.
        These extension input events are generated by manipulating one of the
        extension input devices.</para>  
    <sect2 id='button_key_and_motion_events'><title>Button, Key, and Motion Events</title>
            <para>
            <literallayout>
            DeviceKeyPress
            DeviceKeyRelease
            DeviceButtonPress,
            DeviceButtonRelease 
            DeviceMotionNotify
                    device: CARD8
                    root, event: WINDOW
                    child: Window or None
                    same-screen: BOOL
                    root-x, root-y, event-x, event-y: INT16
                    detail: &lt;see below&gt;
                    state: SETofKEYBUTMASK
                    time: TIMESTAMP
            </literallayout>
            </para>
            <para>These events are generated when a key, button, or valuator logically changes state.
                The generation of these logical changes may lag the physical changes,
                if device event processing is frozen. Note that <emphasis>DeviceKeyPress</emphasis>
                and <emphasis>DeviceKeyRelease</emphasis> are generated for all keys, even those mapped to modifier bits.
                The &ldquo;source&rdquo; of the event is the window the pointer is in.
                The window with respect to which the event is normally reported is found
                by looking up the hierarchy (starting with the source window)
                for the first window on which any client has selected interest in the event.
                The actual window used for reporting can be modified by active grabs and
                by the focus window.The window the event is reported with respect to is called 
                the &ldquo;event&rdquo; window.</para>  
            <para>The root is the root window of the &ldquo;source&rdquo; window, and root-x and root-y 
                are the pointer coordinates relative to root's origin at the time of the event.
                Event is the &ldquo;event&rdquo; window. If the event window is on the same screen as 
                root, then event-x and event-y are the pointer coordinates relative to the
                event window's origin. Otherwise, event-x and event-y are zero. If the 
                source window is an inferior of the event window, then child is set to 
                the child of the event window that is an ancestor of (or is) the source window.
                Otherwise, it is set to None.
            </para>
            <para>
                XI 1.x:
                The state component gives the logical state of the buttons
                on the X pointer and modifier keys on the core X keyboard
                just before the event.
            </para>
            <para>
                XI 2.x:
                The state component gives the logical state of the buttons
                or keys on the device specified in the event field.  If the
                device is a master device, the state component also contains
                the modifier keys on the paired master device. If the device
                is a slave device, the state component also contains the
                modifier keys or buttons of the master device paired with this
                device's master device.  If the device is not attached to a
                master device, the state component only contains the logical
                state of the buttons or keys of this device, with all other
                bits set to zero.
            </para>
            <para>
                The detail component type varies with the event type:
            <informaltable pgwide='0' frame='all'>
                <tgroup cols='2' align='center' colsep='1' rowsep='1'>
                    <colspec colname='c1' colwidth='2in'/>
                    <colspec colname='c2'/>
                    <tbody>
                        <row>
                            <entry align='left'>Event</entry>
                            <entry align='left'>Component</entry>
                        </row>
                        <row>
                            <entry align='left'>DeviceKeyPress</entry>
                            <entry align='left'>KEYCODE</entry>
                        </row>
                        <row>
                            <entry align='left'>DeviceKeyRelease</entry>
                            <entry align='left'>KEYCODE</entry>
                        </row>
                        <row>
                            <entry align='left'>DeviceButtonPress</entry>
                            <entry align='left'>BUTTON</entry>
                        </row>
                        <row>
                            <entry align='left'>DeviceButtonRelease</entry>
                            <entry align='left'>BUTTON</entry>
                        </row>
                        <row>
                            <entry align='left'>DeviceMotionNotify</entry>
                            <entry align='left'>{ Normal , Hint }</entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
            </para>
            <para>The granularity of motion events is not guaranteed, but a client selecting 
                for motion events is guaranteed to get at least one event when a valuator
                changes. If <emphasis>DeviceMotionHint</emphasis> is selected, the server is free to send 
                only one <emphasis>DeviceMotionNotify</emphasis> event (with detail <emphasis>Hint</emphasis>) to the
                client for the event window, until either a key or button changes state,
                the pointer leaves the event window, or the client issues a
                <emphasis>QueryDeviceState</emphasis> or <emphasis>GetDeviceMotionEvents</emphasis> request.</para>
        </sect2>
        <sect2 id='devicevaluator_event'><title>DeviceValuator Event</title>
            <para>
                <literallayout>
                DeviceValuator
                        device: CARD8
                        device_state: SETofKEYBUTMASK
                        num_valuators: CARD8
                        first_valuator: CARD8
                        valuators: LISTofINT32
                </literallayout>
            </para>
            <para>DeviceValuator events are generated to contain valuator information for which
                there is insufficient space in DeviceKey, DeviceButton, DeviceMotion, and
                Proximity wire events. For events of these types, a second event of type
                DeviceValuator follows immediately. The library combines these events into
                a single event that a client can receive via XNextEvent. DeviceValuator
                events are not selected for by clients, they only exist to contain information
                that will not fit into some event selected by clients.</para>
            <para>The device_state component gives the state of the 
                buttons and modifiers on the device generating the event.</para>  
            <para>Extension motion devices may report motion data for a variable number of 
                axes. The valuators array contains the values of all axes reported by the
                device. If more than 6 axes are reported, more than one DeviceValuator event 
                will be sent by the server, and more than one DeviceKey, DeviceButton,
                DeviceMotion, or Proximity event will be reported by the library. 
                Clients should examine the corresponding fields of the event reported by
                the library to determine the total number of axes reported, and the first axis
                reported in the current event. Axes are numbered beginning with zero.</para>
            <para>For Button, Key and Motion events on a device reporting absolute motion data
                the current value of the device's valuators is reported. For devices that
                report relative data, Button and Key events may be followed by a DeviceValuator
                event that contains 0s in the num_valuators field.  In this case, only the
                device_state component will have meaning.</para>
        </sect2>
        <sect2 id='device_focus_events'><title>Device Focus Events</title>
            <para>
                <literallayout>
                DeviceFocusIn
                DeviceFocusOut
                        device: CARD8
                        time: TIMESTAMP
                        event: WINDOW
                        mode: { Normal, WhileGrabbed, Grab, Ungrab}
                        detail: { Ancestor, Virtual, Inferior, Nonlinear, 
                                  NonlinearVirtual, Pointer, PointerRoot, None}
                </literallayout>
            </para>
            <para>These events are generated when the input focus changes and are reported to 
                clients selecting <emphasis>DeviceFocusChange</emphasis> for the specified device and window.
                Events generated by <emphasis>SetDeviceFocus</emphasis> when the device is not grabbed
                have mode <emphasis>Normal</emphasis>. Events generated by <emphasis>SetDeviceFocus</emphasis> when the 
                device is grabbed have mode <emphasis>WhileGrabbed</emphasis>. Events generated when a 
                device grab actives have mode <emphasis>Grab</emphasis>, and events generated when a device
                grab deactivates have mode <emphasis>Ungrab</emphasis>.</para>  
            <para>All <emphasis>DeviceFocusOut</emphasis> events caused by a window unmap are generated after 
                any <emphasis>UnmapNotify</emphasis> event, but the ordering of <emphasis>DeviceFocusOut</emphasis> with
                respect to generated <emphasis>EnterNotify</emphasis>, <emphasis>LeaveNotify</emphasis>, 
                <emphasis>VisibilityNotify</emphasis> and <emphasis>Expose</emphasis> events is not constrained.</para>
            <para><emphasis>DeviceFocusIn</emphasis> and <emphasis>DeviceFocusOut</emphasis> events are generated for
                focus changes of extension devices in the same manner as focus events for 
                the core devices are generated.</para>
        </sect2>
        <sect2 id='device_state_notify_event'><title>Device State Notify Event</title>
            <para>
                <literallayout>
                DeviceStateNotify
                time: TIMESTAMP
                device: CARD8
                num_keys: CARD8
                num_buttons: CARD8
                num_valuators: CARD8
                classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass}
                    SetOfDeviceMode:
                        #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity
                        #x40 Device Mode (0 = Relative, 1 = Absolute)
                    SetOfInputClass: #x04 reporting valuators
                        #x02 reporting buttons
                        #x01 reporting keys
                buttons: LISTofCARD8
                keys: LISTofCARD8
                valuators: LISTofCARD32
                </literallayout>
            </para>
            <para>This event reports the state of the device just as in the 
                <emphasis>QueryDeviceState</emphasis> request. This event is reported to clients selecting 
                <emphasis>DeviceStateNotify</emphasis> for the device and window and is generated immediately 
                after every <emphasis>EnterNotify</emphasis> and <emphasis>DeviceFocusIn</emphasis>. If the device has
                no more than 32 buttons, no more than 32 keys, and no more than 3 valuators,
                This event can report the state of the device. If the device has more
                than 32 buttons, the event will be immediately followed by a 
                DeviceButtonStateNotify event. If the device has more than 32 keys, the
                event will be followed by a DeviceKeyStateNotify event. If the device has more
                than 3 valuators, the event will be followed by one or more DeviceValuator
                events.</para>
        </sect2>
        <sect2 id='device_keystate_and_buttonstate_notify_e'><title>Device KeyState and ButtonState Notify Events</title>
            <para>
                <literallayout>
                DeviceKeyStateNotify
                        device: CARD8
                        keys: LISTofCARD8

                DeviceButtonStateNotify
                        device: CARD8
                        buttons: LISTofCARD8
                </literallayout>
            </para>
            <para>These events contain information about the state of keys and buttons on a 
                device that will not fit into the DeviceStateNotify wire event. These events
                are not selected by clients, rather they may immediately follow a
                DeviceStateNotify wire event and be combined with it into a single 
                DeviceStateNotify client event that a client may receive via XNextEvent.</para>
        </sect2>
        <sect2 id='devicemappingnotify_event'><title>DeviceMappingNotify Event</title>
            <para>
                <literallayout>
                DeviceMappingNotify
                        time: TIMESTAMP
                        device: CARD8
                        request: CARD8
                        first_keycode: CARD8
                        count: CARD8
                </literallayout>
            </para>
            <para>This event reports a change in the mapping of keys, modifiers, or buttons on
                an extension device. This event is reported to clients selecting 
                <emphasis>DeviceMappingNotify</emphasis> for the device and window and is generated
                after every client <emphasis>SetDeviceButtonMapping</emphasis>, <emphasis>ChangeDeviceKeyMapping</emphasis>,
                or  <emphasis>ChangeDeviceModifierMapping</emphasis> request.</para>
        </sect2>
        <sect2 id='changedevicenotify_event'><title>ChangeDeviceNotify Event</title>
            <para>
                <literallayout>
                ChangeDeviceNotify
                        device: CARD8
                        time: TIMESTAMP
                        request: CARD8
                </literallayout>
            </para>
            <para>This event reports a change in the physical device being used as the core
                X keyboard or X pointer device.
                <emphasis>ChangeDeviceNotify</emphasis> events are reported to clients selecting 
                <emphasis>ChangeDeviceNotify</emphasis> for the device and window and is generated
                after every client <emphasis>ChangeKeyboardDevice</emphasis>
                or  <emphasis>ChangePointerDevice</emphasis> request.</para>
        </sect2>
        <sect2 id='proximity_events'><title>Proximity Events</title>
            <para>
                <literallayout>
                ProximityIn
                ProximityOut
                        device: CARD8
                        root, event: WINDOW
                        child: Window or None
                        same-screen: BOOL
                        root-x, root-y, event-x, event-y: INT16
                        state: SETofKEYBUTMASK
                        time: TIMESTAMP
                        device-state: SETofKEYBUTMASK
                        axis-count: CARD8
                        first-axis: CARD8
                        axis-data: LISTofINT32
                </literallayout>
            </para>
            <para>These events are generated by some devices (such as graphics tablets or 
                touchscreens) to indicate that a stylus has moved into or out of contact
                with a positional sensing surface.</para>
            <para>The &ldquo;source&rdquo; of the event is the window the pointer is in.
                The window with respect to which the event is normally reported is found
                by looking up the hierarchy (starting with the source window)
                for the first window on which any client has selected interest in the event.
                The actual window used for reporting can be modified by active grabs and
                by the focus window.The window the event is reported with respect to is called
                the &ldquo;event&rdquo; window.</para>
            <para>The root is the root window of the &ldquo;source&rdquo; window, and root-x and root-y
                are the pointer coordinates relative to root's origin at the time of the event.
                Event is the &ldquo;event&rdquo; window. If the event window is on the same screen as
                root, then event-x and event-y are the pointer coordinates relative to the
                event window's origin. Otherwise, event-x and event-y are zero. If the
                source window is an inferior of the event window, then child is set to
                the child of the event window that is an ancestor of (or is) the source window.
                Otherwise, it is set to None. The state component gives the logical state of
                the buttons on the core X pointer and modifier keys on the core X keyboard
                just before the event. The device-state component gives the state of the
                buttons and modifiers on the device generating the event.</para>
        </sect2>
        <sect2 id='device_presence_events'>
            <title>DevicePresenceEvents</title>
            <para>
                Introduced with XI 1.4.
                <literallayout>
                DevicePresence
                        time: TIMESTAMP
                        devchange: BYTE
                            #x00: DeviceAdded
                            #x01: DeviceRemoved
                            #x02: DeviceEnabled
                            #x03: DeviceDisabled
                            #x04: DeviceUnrecoverable
                        deviceid: BYTE
                        control: CARD16
                </literallayout>
            </para>
            <para>
                <emphasis>DevicePresence</emphasis> events are sent when the
                server adds or removes, or enables or disables an input
                device. The client is expected to query the server for the
                list of input devices using the
                <emphasis>ListInputDevices</emphasis> request to obtain the
                updated list of input devices.
            </para>
            <para>
                The <emphasis>devchange</emphasis> field specifies the type of
                operation. In case of <emphasis>DeviceAdded</emphasis>, a new
                device has been added to the server, but this device does not
                yet send events. If devchange is set to
                <emphasis>DeviceEnabled</emphasis>, the device is enabled and
                will generate events.
                If the field is <emphasis>DeviceDisabled</emphasis> or
                <emphasis>DeviceRemoved</emphasis>, the given device is
                disabled and stops sending events or was removed from the
                server, respectively.
                If the field is <emphasis>DeviceUnrecoverable</emphasis>, an
                IO-error has occured on the device and the device is forcibly
                disabled and removed by the server.
            </para>
        </sect2>
        <sect2 id='device_crossing_events'>
            <title>DeviceCrossingEvents</title>
            <para>
                Introduced with XI 2.0.
                <literallayout>
                DeviceEnterEvent
                DeviceLeaveEvent
                        detail: BYTE
                            #0x00: Ancestor
                            #0x01: Virtual
                            #0x02: Inferior
                            #0x03: Nonlinear
                            #0x04: NonlinearVirtual
                        time: TIMESTAMP
                        root: WINDOW
                        event: WINDOW
                        child: WINDOW
                            #0x00: None
                        root-x: INT16
                        root-y: INT16
                        event-x: INT16
                        event-y: INT16
                        state: SETofKEYBUTMASK
                        mode: BYTE
                            #x00: Normal
                            #x01: Grab
                            #x10: SameScreen
                            #x20: Focus
                        deviceid: CARD8
                </literallayout>
            </para>
            <para>
                If pointer motion or a window hierarchy change causes the
                device's pointer to be in a different window than before,
                <emphasis>DeviceEnterNotify</emphasis> and
                <emphasis>DeviceLeaveNotify</emphasis> events are generated
                instead of a <emphasis>DeviceMotionNotify</emphasis> event.
                The deviceid specifies the device that generated the
                <emphasis>DeviceEnterNotify</emphasis> or
                <emphasis>DeviceLeaveNotify</emphasis> event.  </para>
            <para>
                Only clients selecting DeviceEnter on a window receive
                <emphasis>DeviceEnterNotify</emphasis> ev\-ents, and only
                clients selecting DeviceLeave receive
                <emphasis>DeviceLeaveNotify</emphasis> events. The device's
                pointer position reported in the event is always the final
                position, not the initial position of the device's pointer.
                The root is the root window for this position, and root-x and
                root-y are the device's pointer coordinates relative to root's
                origin at the time of the event. Event is the event window. If
                the event window is on the same screen as root, then event-x
                and event-y are the device's pointer coordinates relative to
                the event window's origin and mode has the
                <emphasis>SameScreen</emphasis> bit set. Otherwise, event-x
                and event-y are zero and the <emphasis>SameScreen</emphasis>
                bit is unset. In a <emphasis>DeviceLeaveNotify</emphasis>
                event, if a child of the event window contains the initial
                position of the device's pointer, then the child component is
                set to that child. Otherwise, it is <emphasis>None</emphasis>.
                For a <emphasis>DeviceEnterNotify</emphasis> event, if a child
                of the event window contains the final pointer position, then
                the child component is set to that child. Otherwise, it is
                <emphasis>None</emphasis>. If the event window is the focus
                window or an inferior of the focus window, then mode has the
                <emphasis>Focus</emphasis> bit set. Otherwise, the
                <emphasis>Focus</emphasis> bit is unset. 
            </para>
            <para>
                Normal pointer motion events have mode
                <emphasis>Normal</emphasis>. Pseudo-motion events when a grab
                activates have mode <emphasis>Grab</emphasis>, and
                pseudo-motion events when a grab deactivates have mode
                <emphasis>Ungrab</emphasis>. Only the lower four bits must be
                considered when determining the grab mode.  </para>
            <para>
                All <emphasis>DeviceEnterNotify</emphasis> and
                <emphasis>DeviceLeaveNotify</emphasis> events caused by a
                window hierarchy change are generated after any hierarchy
                event caused by that change (that is
                <emphasis>UnmapNotify</emphasis>,
                <emphasis>MapNotify</emphasis>,
                <emphasis>ConfigureNotify</emphasis>,
                <emphasis>GravityNotify</emphasis>,
                <emphasis>CirculateNotify</emphasis>), but the ordering of
                <emphasis>DeviceEnterNotify</emphasis> and
                <emphasis>DeviceLeaveNotify</emphasis> events with respect to
                <emphasis>DeviceFocusOut</emphasis> events is not constrained. 
            </para>
            <para>
                The above description is a modified version of the
                <emphasis>EnterNotify</emphasis> and
                <emphasis>LeaveNotify</emphasis> event description from
                the core protocol. For  a detailed description about the
                generation of <emphasis>EnterNotify</emphasis> and
                <emphasis>LeaveNotify</emphasis> events see
                the core protocol specification.
            </para>
        </sect2>
        <sect2 id='device_hierarchy_changed_event'>
            <title>Device Hierarchy Changed Event</title>
            <para>
                Introduced with XI 2.0.
                <literallayout>
                DeviceHierarchyChangedEvent
                    time: TIMESTAMP
                </literallayout>
                The DeviceHierarchyChangedEvent is a GenericEvent.
            </para>
            <para>
                If a client modifies the device hierarchy through the
                <emphasis>ChangeDeviceHierarchy</emphasis> request, a
                <emphasis>DeviceHierarchyChangedEvent</emphasis> is sent to
                all clients. The event does not include information about the
                device hierarchy and a client is expected to issue a
                <emphasis>ListInputDevices</emphasis> request to obtain the
                new device hierarchy.
            </para>
        </sect2>

        <sect2 id='device_classes_changed_event'>
            <title>DeviceClassesChangedEvent</title>
            <para>
                Introduced with XI 2.0.
                <literallayout>
                DeviceClassesChangedEvent
                        deviceid: CARD8
                        new-slave: CARD8
                        time: TIMESTAMP
                        num-classes: CARD8
                        classes: LISTofINPUTINFO
                </literallayout>
                The DeviceClassesChangedEvent is a GenericEvent.
            </para>
            <para>
                A <emphasis>DeviceClassesChangedEvent</emphasis> is sent to
                all clients when an event from a slave device causes a master
                device to change its classes.
            </para>
            <para>
                The deviceid specifies the master device that has changed
                state and new-slave is set to the device ID of the slave
                device that now sends events through this master device. The
                event is followed by num-classes elements of
                <emphasis>KeyInfo</emphasis>,
                <emphasis>ValuatorInfo</emphasis>, and
                <emphasis>ButtonInfo</emphasis> that reflect the capabilities
                of the slave device.  For a description of
                <emphasis>INPUTINFO</emphasis>, see 
                <xref linkend="listing_available_devices"/>.
            </para>
        </sect2>
    </sect1>
</article>