# PaCkAgE DaTaStReAm inputproto 1 1264 # end of header 07070100062358000081a400000000000000000000000153c4dc4000000128000001000001001cffffffffffffffff0000001300000000inputproto/pkginfoPKG=inputproto NAME=inputproto 2.3.1 SPARC 32bit Solaris 10 VERSION=2.3.1 PSTAMP=15th July 2014 VENDOR=X.org EMAIL=http://cgit.freedesktop.org/xorg/proto/inputproto/ DESC=X.org InputProto protocol headers ARCH=sparc CATEGORY=utility CLASSES=none BASEDIR=/ ISTATES=S s 1 2.3.1 RSTATES=S s 1 2.3.1 07070100062357000081a400000000000000000000000153c4dc41000004f3000001000001001cffffffffffffffff0000001200000000inputproto/pkgmap: 1 1264 1 d none /usr/local/include 0755 root root 1 d none /usr/local/include/X11 0755 root root 1 d none /usr/local/include/X11/extensions 0755 root root 1 f none /usr/local/include/X11/extensions/XI.h 0644 root root 9823 7952 1405410366 1 f none /usr/local/include/X11/extensions/XI2.h 0644 root root 10542 63701 1405410366 1 f none /usr/local/include/X11/extensions/XI2proto.h 0644 root root 37518 28045 1405410367 1 f none /usr/local/include/X11/extensions/XIproto.h 0644 root root 42622 42914 1405410366 1 d none /usr/local/lib 0755 root root 1 d none /usr/local/lib/pkgconfig 0755 root root 1 f none /usr/local/lib/pkgconfig/inputproto.pc 0644 root root 190 17628 1405410367 1 d none /usr/local/share 0755 root root 1 d none /usr/local/share/doc 0755 root root 1 d none /usr/local/share/doc/inputproto 0755 root root 1 f none /usr/local/share/doc/inputproto/XI2proto.html 0644 root root 150512 49193 1405410366 1 f none /usr/local/share/doc/inputproto/XI2proto.txt 0644 root root 108918 23593 1405410366 1 f none /usr/local/share/doc/inputproto/XIproto.html 0644 root root 139585 37849 1405410366 1 f none /usr/local/share/doc/inputproto/XIproto.txt 0644 root root 104572 62785 1405410366 1 i checkinstall 791 2770 1405410368 1 i pkginfo 296 23720 1405410368 07070100000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000b00000000TRAILER!!!07070100062358000081a400000000000000000000000153c4dc4000000128000001000001001cffffffffffffffff0000000800000000pkginfoPKG=inputproto NAME=inputproto 2.3.1 SPARC 32bit Solaris 10 VERSION=2.3.1 PSTAMP=15th July 2014 VENDOR=X.org EMAIL=http://cgit.freedesktop.org/xorg/proto/inputproto/ DESC=X.org InputProto protocol headers ARCH=sparc CATEGORY=utility CLASSES=none BASEDIR=/ ISTATES=S s 1 2.3.1 RSTATES=S s 1 2.3.1 07070100062357000081a400000000000000000000000153c4dc41000004f3000001000001001cffffffffffffffff0000000700000000pkgmap: 1 1264 1 d none /usr/local/include 0755 root root 1 d none /usr/local/include/X11 0755 root root 1 d none /usr/local/include/X11/extensions 0755 root root 1 f none /usr/local/include/X11/extensions/XI.h 0644 root root 9823 7952 1405410366 1 f none /usr/local/include/X11/extensions/XI2.h 0644 root root 10542 63701 1405410366 1 f none /usr/local/include/X11/extensions/XI2proto.h 0644 root root 37518 28045 1405410367 1 f none /usr/local/include/X11/extensions/XIproto.h 0644 root root 42622 42914 1405410366 1 d none /usr/local/lib 0755 root root 1 d none /usr/local/lib/pkgconfig 0755 root root 1 f none /usr/local/lib/pkgconfig/inputproto.pc 0644 root root 190 17628 1405410367 1 d none /usr/local/share 0755 root root 1 d none /usr/local/share/doc 0755 root root 1 d none /usr/local/share/doc/inputproto 0755 root root 1 f none /usr/local/share/doc/inputproto/XI2proto.html 0644 root root 150512 49193 1405410366 1 f none /usr/local/share/doc/inputproto/XI2proto.txt 0644 root root 108918 23593 1405410366 1 f none /usr/local/share/doc/inputproto/XIproto.html 0644 root root 139585 37849 1405410366 1 f none /usr/local/share/doc/inputproto/XIproto.txt 0644 root root 104572 62785 1405410366 1 i checkinstall 791 2770 1405410368 1 i pkginfo 296 23720 1405410368 0707010006236d000041ed00000000000000000000000253c4dc4100000000000001000001001cffffffffffffffff0000000800000000install0707010006236e000081ed00000000000000000000000153c4dc4000000317000001000001001cffffffffffffffff0000001500000000install/checkinstall#!/bin/sh # expected_bits="32" expected_release="5.10" expected_platform="sparc" # release=`uname -r` platform=`uname -p` bits=`isainfo -b` # if [ ${platform} != ${expected_platform} ]; then echo "\n\n\n\tThis package must be installed on a ${expected_platform} architecture\n" echo "\tAborting installation.\n\n\n" exit 1 fi if [ ${release} != ${expected_release} ]; then echo "\n\n\n\tThis package must be installed on a ${expected_release} machine\n" echo "\tAborting installation.\n\n\n" exit 1 fi #if [ ${bits} != ${expected_bits} ]; then # echo "\n\n\n\tThis package must be installed on a ${expected_bits} bit machine\n" # echo "\tYour machine is running a ${bits} bit O.S. currently\n" # echo "\tAborting installation.\n\n\n" # exit 1 #fi exit 0 07070100062359000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000000500000000root0707010006235a000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000000900000000root/usr0707010006235b000041ed00000000000000000000000553c4dc4100000000000001000001001cffffffffffffffff0000000f00000000root/usr/local07070100062363000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000001300000000root/usr/local/lib07070100062364000041ed00000000000000000000000253c4dc4100000000000001000001001cffffffffffffffff0000001d00000000root/usr/local/lib/pkgconfig07070100062365000081a400000000000000000000000153c4dc3f000000be000001000001001cffffffffffffffff0000002b00000000root/usr/local/lib/pkgconfig/inputproto.pcprefix=/usr/local exec_prefix=${prefix} libdir=${exec_prefix}/lib includedir=${prefix}/include Name: InputProto Description: Input extension headers Version: 2.3.1 Cflags: -I${includedir} 07070100062366000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000001500000000root/usr/local/share07070100062367000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000001900000000root/usr/local/share/doc07070100062368000041ed00000000000000000000000253c4dc4100000000000001000001001cffffffffffffffff0000002400000000root/usr/local/share/doc/inputproto0707010006236b000081a400000000000000000000000153c4dc3e00022141000001000001001cffffffffffffffff0000003100000000root/usr/local/share/doc/inputproto/XIproto.html 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 1.5
Peter Hutterer
Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and
Ardent Computer
Permission to use, copy, modify, and distribute this
documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice and this
permission notice appear in all copies. Ardent and
Hewlett-Packard make no representations about the suitability
for any purpose of the information in this document. It is
provided "as is" without express or implied warranty. Copyright
© 1989, 1990, 1991, 1992 X Consortium
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the “Software”), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE 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.
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. X
Window System is a trademark of The Open Group.
Copyright © 2008 by Peter Hutterer
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
(including the next paragraph) shall be included in all copies
or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

1. Input Extension Overview

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.

This document only describes the behaviour of servers supporting up to the X Input Extension 1.5. For servers supporting the X Input Extensions 2.0, see XI2proto.txt. New clients are discouraged from using this protocol specification. Instead, the use of XI 2.x is recommended.

1.1 Design Approach

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.

1.2 Core Input Devices

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.

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 servers supporting XI 2.0 and above, there may be multiple core pointers and keyboards. Refer to XI2proto.txt for more information.

The X keyboard and X pointer are referred to in this document as the core devices, and the input events they generate (KeyPress, KeyRelease, ButtonPress, ButtonRelease, and MotionNotify) are known as the core input events. All other input devices are referred to as extension input devices and the input events they generate are referred to as extension input events.

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 "Event Synchronization and Core Grabs".

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.

1.3 Extension Input Devices

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.

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 ListInputDevices 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 OpenDevice 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 ( DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify, etc.) and contain a device identifier so that events of the same type coming from different input devices can be distinguished.

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).

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 input classes. 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.

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.

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.

1.4 Event Classes

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.

When a client opens a extension input device via the OpenDevice request, an XDevice structure is returned. Macros are provided that extract 32-bit numbers called event classes from that structure, that a client can use to register interest in extension events via the SelectExtensionEvent request. The event class combines the desired event type and device id, and may be thought of as the equivalent of core event masks.

1.5 Input Classes

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:

KEY
       The device reports key events.
BUTTON
       The device reports button events.
VALUATOR
       The device reports valuator data in motion events.
PROXIMITY
       The device reports proximity events.
FOCUS
       The device can be focused and reports focus events.
FEEDBACK
       The device supports feedbacks.
OTHER
       The ChangeDeviceNotify, DeviceMappingNotify, and
       DeviceStateNotify macros may be invoked passing the
       XDevice structure returned for this device.

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 ListInputDevices 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.

2. Requests

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.

2.1 Getting the Extension Version

The GetExtensionVersion request returns version information about the input extension.

GetExtensionVersion
        name: STRING
=>
        present: BOOL
        protocol-major-version: CARD16
        protocol-minor-version: CARD16

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 XI.h. Each version is a superset of the previous versions.

The name must be the name of the Input Extension as defined in the header file XI.h.

2.2 Listing Available Devices

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 ListInputDevices request, which will return a list of all devices that can be opened by the X server.

ListInputDevices
=>
input-devices: ListOfDeviceInfo

where

DEVICEINFO:
        [type: ATOM
         id: CARD8
         num_classes: CARD8
         use: {IsXKeyboard, IsXPointer, IsXExtensionPointer,
               IsXExtensionKeyboard, IsExtensionDevice}
         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}
Errors: None

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.

The information returned for each device is as follows:

type
       The type field is of type Atom and indicates the nature
       of the device. Clients may determine device types by
       invoking the XInternAtom request passing one of the
       names defined in the header file XI.h. The following
       names have been defined to date:
MOUSE
TABLET
KEYBOARD
TOUCHSCREEN
TOUCHPAD
BUTTONBOX
BARCODE
KNOB_BOX
TRACKBALL
QUADRATURE
SPACEBALL
DATAGLOVE
EYETRACKER
CURSORKEYS
FOOTMOUSE
ID_MODULE
ONE_KNOB
NINE_KNOB
JOYSTICK
id
       The id 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
       XOpenDevice, then closed via XCloseDevice, then opened
       again, it is not guaranteed to have the same id after
       the second open request.
num_classes
       The num_classes 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 ListInputDevices. Some input classes, such
       as class Focus and class Proximity do not have any
       information to be returned by ListInputDevices.
use
       The use field specifies how the device is currently
       being used. If the value is IsXKeyboard, the device is
       currently being used as the X keyboard. If the value is
       IsXPointer, the device is currently being used as the X
       pointer. If the value is IsXExtensionPointer, the device
       is available for use as an extension pointer. If the value
       is IsXExtensionKeyboard, the device is available for use as
       and extension keyboard.
       Older versions of XI report all extension devices as
       IsXExtensionDevice.
name
       The name field contains a pointer to a null-terminated
       string that corresponds to one of the defined device
       types.
InputInfo
       InputInfo is one of: KeyInfo, ButtonInfo or
       ValuatorInfo. The first two fields are common to all
       three:
class
        The class field is a cardinal value in the range
        0-255. It uniquely identifies the class of input
        for which information is returned.
length
        The length 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.

The remaining information returned for input class KEYCLASS is as follows:

min_keycode
        min_keycode is of type KEYCODE. It specifies the
        minimum keycode that the device will report. The
        minimum keycode will not be smaller than 8.
max_keycode
        max_keycode is of type KEYCODE. It specifies the
        maximum keycode that the device will report. The
        maximum keycode will not be larger than 255.
num_keys
        num_keys is a cardinal value that specifies the
        number of keys that the device has.

The remaining information returned for input class BUTTONCLASS is as follows:

num_buttons
        num_buttons is a cardinal value that specifies the
        number of buttons that the device has.

The remaining information returned for input class VALUATORCLASS is as follows:

mode
        mode is a constant that has one of the following
        values: Absolute or Relative. Some devices allow
        the mode to be changed dynamically via the
        SetDeviceMode request.
motion_buffer_size
        motion_buffer_size is a cardinal number that
        specifies the number of elements that can be
        contained in the motion history buffer for the
        device.
axes
        The axes field contains a pointer to an AXISINFO
        struture.

The information returned for each axis reported by the device is:

resolution
        The resolution is a cardinal value in
        counts/meter.
min_val
        The min_val field is a cardinal value in that
        contains the minimum value the device reports for
        this axis. For devices whose mode is Relative, the
        min_val field will contain 0.
max_val
        The max_val field is a cardinal value in that
        contains the maximum value the device reports for
        this axis. For devices whose mode is Relative, the
        max_val field will contain 0.

2.3 Enabling Devices

Client programs that wish to access an extension device must request that the server open that device. This is done via the OpenDevice request.

OpenDevice
        id: CARD8
=>
DEVICE:
        [device_id: XID
         num_classes: INT32
         classes: LISTofINPUTCLASSINFO]
INPUTCLASSINFO:
         [input_class: CARD8
         event_type_base: CARD8]
Errors: Device

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 Keys reports DeviceKeyPress and DeviceKeyRelease event classes. Input classes are unique numbers registered with the X Consortium. Input class Other exists to report event classes that are not specific to any one input class, such as DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify.

The information returned for each device is as follows:

device_id
       The device_id is a number that uniquely identifies the
       device.
num_classes
       The num_classes field contains the number of input
       classes supported by this device.
For each class of input supported by the device, the
InputClassInfo structure contains the following information:
input_class
       The input_class is a small cardinal number that
       identifies the class of input.
event_type_base
       The event_type_base 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 Device 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".

The information in the InputClassInfo reflects the state of this device at the time the request was processed.

Before it exits, the client program should explicitly request that the server close the device. This is done via the CloseDevice request.

A client may open the same extension device more than once. Requests after the first successful one return an additional XDevice structure with the same information as the first, but otherwise have no effect. A single CloseDevice request will terminate that client’s access to the device.

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.

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.

CloseDevice:
        device: DEVICE
Errors: Device

2.4 Changing The Mode Of A Device

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 SetDeviceMode request. The valid values are Absolute or Relative.

This request will fail and return DeviceBusy if another client already has the device open with a different mode. It will fail and return AlreadyGrabbed if another client has the device grabbed. The request will fail with a BadMatch error if the device has no valuators and reports no axes of motion. The request will fail with a BadMode error if the requested mode is not supported by the device.

SetDeviceMode
        device:DEVICE
        mode: {Absolute, Relative}
=>
        status: {Success, DeviceBusy, AlreadyGrabbed}
Errors: Device, Match, Mode

2.5 Initializing Valuators on an Input Device

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 Absolute. To initialize the valuators on such a device, use the SetDeviceValuators request.

SetDeviceValuators
        device: DEVICE
        first_valuator: CARD8
        num_valuators: CARD8
        valuators: LISTOFINT32
=>
        status: {Success, AlreadyGrabbed}
Errors: Length, Device, Match, Value

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 Value error will result.

If the request succeeds, Success is returned. If the specifed device is grabbed by some other client, the request will fail and a status of AlreadyGrabbed will be returned.

2.6 Getting Input Device Controls

GetDeviceControl
        device: DEVICE
        control: XID
=>
controlState: {DeviceState}

where

DeviceState: DeviceResolutionState
Errors: Length, Device, Match, Value

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.

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.

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.

Supported device controls and the information returned for them include:

DEVICE_RESOLUTION:
    [control: CARD16
    length: CARD16
    num_valuators: CARD8
    resolutions: LISTofCARD32
    min_resolutions: LISTofCARD32
    max_resolutions: LISTofCARD32]

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.

When this control is specified, XGetDeviceControl will fail with a BadMatch error if the specified device has no valuators.

ChangeDeviceControl:
        device: DEVICE
        XID: controlId
        control: DeviceControl

where

DeviceControl: DeviceResolutionControl
=>
        status: {Success, DeviceBusy, AlreadyGrabbed}
Errors: Length, Device, Match, Value

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.

The information passed with this request varies according to the specified control and is mapped by a structure appropriate for that control.

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.

Supported device controls and the information specified for them include:

DEVICE_RESOLUTION:
        [control: CARD16
         length: CARD16
         first_valuator: CARD8
         num_valuators: CARD8
         resolutions: LISTofCARD32]

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.

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.

If the request fails for any reason, none of the valuator resolutions will be changed.

ChangeDeviceControl causes the server to send a DevicePresence event to interested clients.

2.7 Selecting Extension Device Events

Extension input events are selected using the SelectExtensionEvent request.

SelectExtensionEvent
        interest: LISTofEVENTCLASS
        window: WINDOW
Errors: Window, Class, Access

This request specifies to the server the events within the specified window which are of interest to the client. As with the core XSelectInput function, multiple clients can select input on the same window.

XSelectExtensionEvent requires a list of event classes. 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 XOpenDevice request. The names of these macros correspond to the desired events, i.e. the DeviceKeyPress is used to obtain the event class for DeviceKeyPress events. The syntax of the macro invocation is:

DeviceKeyPress (device, event_type, event_class);
    device: DEVICE
    event_type: INT
    event_class: INT

The value returned in event_type is the value that will be contained in the event type field of the XDeviceKeyPressEvent when it is received by the client. The value returned in event_class is the value that should be passed in making an XSelectExtensionEvent request to receive DeviceKeyPress events.

For DeviceButtonPress 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 DeviceButtonRelease event for each DeviceButtonPress event it receives, it should specify the DeviceButtonPressGrab event class as well as the DeviceButtonPress event class. This restricts the client in that only one client at a time may request DeviceButtonPress events from the same device and window if any client specifies this class.

If any client has specified the DeviceButtonPressGrab class, any requests by any other client that specify the same device and window and specify DeviceButtonPress or DeviceButtonPressGrab will cause an Access error to be generated.

If only the DeviceButtonPress 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.

A client may also specify the DeviceOwnerGrabButton class. If it has specified both the DeviceButtonPressGrab and the DeviceOwnerGrabButton classes, implicit passive grabs will activate with owner_events set to True. If only the DeviceButtonPressGrab class is specified, implicit passive grabs will activate with owner_events set to False.

The client may select DeviceMotion events only when a button is down. It does this by specifying the event classes Button1Motion through Button5Motion, or ButtonMotion. An input device will only support as many button motion classes as it has buttons.

2.8 Determining Selected Events

To determine which extension events are currently selected from a given window, use GetSelectedExtensionEvents.

GetSelectedExtensionEvents
        window: WINDOW
=>
        this-client: LISTofEVENTCLASS
        all-clients: LISTofEVENTCLASS
Errors: Window

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 GetWindowAttributes request.

2.9 Controlling Event Propagation

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.

Client programs may control extension event propagation through the use of the following two requests.

XChangeDeviceDontPropagateList 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.

ChangeDeviceDontPropagateList
        window: WINDOW
        eventclass: LISTofEVENTCLASS
        mode: {AddToList, DeleteFromList}
Errors: Window, Class, Mode

This function modifies the list specifying the events that are not propagated to the ancestors of the specified window. You may use the modes AddToList or DeleteFromList.

GetDeviceDontPropagateList
        window: WINDOW
=>
        dont-propagate-list: LISTofEVENTCLASS
Errors: Window

This function returns a list specifying the events that are not propagated to the ancestors of the specified window.

2.10 Sending Extension Events

One client program may send an event to another via the XSendExtensionEvent function.

The event in the XEvent 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 True in the forwarded event and to set the sequence number in the event correctly.

XSendExtensionEvent returns zero if the conversion-to-wire protocol failed, otherwise it returns nonzero.

SendExtensionEvent
        device: DEVICE
        destination: WINDOW
        propagate: BOOL
        eventclass: LISTofEVENTCLASS
        event: XEVENT
Errors: Device, Value, Class, Window

2.11 Getting Motion History

GetDeviceMotionEvents
        device: DEVICE
        start, stop: TIMESTAMP or CurrentTime
=>
        nevents_return: CARD32
        mode_return: {Absolute, Relative}
        axis_count_return: CARD8
        events: LISTofDEVICETIMECOORD

where

DEVICETIMECOORD:
        [data: LISTofINT32
         time: TIMESTAMP]
Errors: Device, Match

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.

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.

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 ListInputDevices request.

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.

2.12 Changing The Core Devices

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 BadDevice error.

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.

These requests change the X keyboard or X pointer device and generate an ChangeDeviceNotify event and a MappingNotify event. The ChangeDeviceNotify event is sent only to those clients that have expressed an interest in receiving that event via the XSelectExtensionEvent 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.

These requests fail and return AlreadyGrabbed if either the specified device or the core device it would replace are grabbed by some other client. They fail and return GrabFrozen if either device is frozen by the active grab of another client.

These requests fail with a BadDevice error if the specified device is invalid, or has not previously been opened via OpenDevice. To change the X keyboard device, use the ChangeKeyboardDevice request. The specified device must support input class Keys (as reported in the ListInputDevices request) or the request will fail with a BadMatch 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.

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 FocusRec, one is added by the ChangeKeyboardDevice request. The X keyboard is assumed to have a KbdFeedbackClassRec. If the device was initialized without a KbdFeedbackClassRec, one will be added by this request. The KbdFeedbackClassRec will specify a null routine as the control procedure and the bell procedure.

ChangeKeyboardDevice
        device: DEVICE
=>
        status: Success, AlreadyGrabbed, Frozen
Errors: Device, Match

To change the X pointer device, use the ChangePointerDevice 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.

The X pointer device does not contain a FocusRec. If the new pointer was initialized with a FocusRec, it is freed by the ChangePointerDevice request. The X pointer is assumed to have a ButtonClassRec and a PtrFeedbackClassRec. If the device was initialized without a ButtonClassRec or a PtrFeedbackClassRec, one will be added by this request. The ButtonClassRec added will have no buttons, and the PtrFeedbackClassRec will specify a null routine as the control procedure.

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 BadDevice 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.

ChangePointerDevice
        device: DEVICE
        xaxis: CARD8
        yaxis: CARD8
=>
     status: Success, AlreadyGrabbed, Frozen
Errors: Device, Match

2.12 Event Synchronization And Core Grabs

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.

The core grab requests require a pointer_mode and keyboard_mode argument. The meaning of these modes is changed by the input extension. For the XGrabPointer and XGrabButton requests, pointer_mode controls synchronization of the pointer device, and keyboard_mode controls the synchronization of all other input devices. For the XGrabKeyboard and XGrabKey requests, pointer_mode controls the synchronization of all input devices except the X keyboard, while keyboard_mode controls the synchronization of the keyboard. When using one of the core grab requests, the synchronization of extension devices is controlled by the mode specified for the device not being grabbed.

2.13 Extension Active Grabs

Active grabs of extension devices are supported via the GrabDevice request in the same way that core devices are grabbed using the core GrabKeyboard request, except that a Device is passed as a function parameter. A list of events that the client wishes to receive is also passed. The UngrabDevice request allows a previous active grab for an extension device to be released.

To grab an extension device, use the GrabDevice request. The device must have previously been opened using the OpenDevice request.

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
=>
        status: Success, AlreadyGrabbed, Frozen,
                InvalidTime, NotViewable
Errors: Device, Window, Value

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.

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.

If owner-events is False, 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 True, 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.

If this-device-mode is Asynchronous, 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 Synchronous, 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 AllowDeviceEvents 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.

If other-device-mode is Asynchronous, event processing is unaffected by activation of the grab. If other-device-mode is Synchronous, 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 AllowDeviceEvents 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.

This request generates DeviceFocusIn and DeviceFocusOut events.

This request fails and returns:

AlreadyGrabbed
       If the device is actively grabbed by some other client.
NotViewable
       If grab-window is not viewable.
InvalidTime
       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
       CurrentTime is replaced by the current X server time.
Frozen
       If the device is frozen by an active grab of another
       client.

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.

To release a grab of an extension device, use UngrabDevice.

UngrabDevice
        device: DEVICE
        time: TIMESTAMP or CurrentTime
Errors: Device

This request releases the device if this client has it actively grabbed (from either GrabDevice or GrabDeviceKey) and releases any queued events. If any devices were frozen by the grab, UngrabDevice 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.

This request generates DeviceFocusIn and DeviceFocusOut events.

An UngrabDevice is performed automatically if the event window for an active device grab becomes not viewable.

2.14 Passively Grabbing A Key

Passive grabs of buttons and keys on extension devices are supported via the GrabDeviceButton and GrabDeviceKey requests. These passive grabs are released via the UngrabDeviceKey and UngrabDeviceButton requests.

To passively grab a single key on an extension device, use GrabDeviceKey. That device must have previously been opened using the OpenDevice request.

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}
Errors: Device, Match, Access, Window, Value

This request is analogous to the core GrabKey request. It establishes a passive grab on a device. Consequently, in the future:

  • 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),

  • AND no other modifier keys logically are down,

  • 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,

  • AND a passive grab on the same device and key combination does not exist on any ancestor of the grab window,

  • THEN the device is actively grabbed, as for GrabDevice, the last-device-grab time is set to the time at which the key was pressed (as transmitted in the DeviceKeyPress event), and the DeviceKeyPress event is reported.

The interpretation of the remaining arguments is as for GrabDevice. 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).

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.

A modifier of AnyModifier 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 AnyKey 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 ListInputDevices request. If it is not within that range, GrabDeviceKey generates a Value error.

NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device.

An Access error is generated if some other client has issued a GrabDeviceKey with the same device and key combination on the same window. When using AnyModifier or AnyKey, the request fails completely and the X server generates a Access error and no grabs are established if there is a conflicting grab for any combination.

This request cannot be used to grab a key on the X keyboard device. The core GrabKey request should be used for that purpose.

To release a passive grab of a single key on an extension device, use UngrabDeviceKey.

UngrabDeviceKey
        device: DEVICE
        keycode: KEYCODE or AnyKey
        modifiers: SETofKEYMASK or AnyModifier
        modifier-device: DEVICE or NULL
        grab-window: WINDOW
Errors: Device, Match, Window, Value, Alloc

This request is analogous to the core UngrabKey request. It releases the key combination on the specified window if it was grabbed by this client. A modifier of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A key of AnyKey is equivalent to issuing the request for all possible keycodes. This request has no effect on an active grab.

NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device.

2.15 Passively Grabbing A Button

To establish a passive grab for a single button on an extension device, use GrabDeviceButton.

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}
Errors: Device, Match, Window, Access, Value

This request is analogous to the core GrabButton 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 OpenDevice request.

The GrabDeviceButton request establishes a passive grab on a device. Consequently, in the future,

  • 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),

  • AND the grab window contains the device,

  • AND a passive grab on the same device and button/ key combination does not exist on any ancestor of the grab window,

  • THEN the device is actively grabbed, as for GrabDevice, the last-grab time is set to the time at which the button was pressed (as transmitted in the DeviceButtonPress event), and the DeviceButtonPress event is reported.

The interpretation of the remaining arguments is as for GrabDevice. 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).

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.

A modifier of AnyModifier 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 AnyButton is equivalent to issuing the request for all possible buttons. It is not required that the specified button be assigned to a physical button.

NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device.

An Access error is generated if some other client has issued a GrabDeviceButton with the same device and button combination on the same window. When using AnyModifier or AnyButton, the request fails completely and the X server generates a Access error and no grabs are established if there is a conflicting grab for any combination. The request has no effect on an active grab.

This request cannot be used to grab a button on the X pointer device. The core GrabButton request should be used for that purpose.

To release a passive grab of a button on an extension device, use UngrabDeviceButton.

UngrabDeviceButton
        device: DEVICE
        button: BUTTON or AnyButton
        modifiers: SETofKEYMASK or AnyModifier
        modifier-device: DEVICE or NULL
        grab-window: WINDOW
Errors: Device, Match, Window, Value, Alloc

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 AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A button of AnyButton 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 OpenDevice request otherwise a Device error will be generated.

NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device.

This request cannot be used to ungrab a button on the X pointer device. The core UngrabButton request should be used for that purpose.

2.16 Thawing A Device

To allow further events to be processed when a device has been frozen, use AllowDeviceEvents.

AllowDeviceEvents
        device: DEVICE
        event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices,
        ReplayThisdevice, AsyncAll, or SyncAll}
        time:TIMESTAMP or CurrentTime
Errors: Device, Value

The AllowDeviceEvents 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.

The following describes the processing that occurs depending on what constant you pass to the event-mode argument:

  • 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.

  • 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.

  • 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.

  • 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 “thaws” 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.

  • 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).

  • 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.

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.

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.

2.17 Controlling Device Focus

The current focus window for an extension input device can be determined using the GetDeviceFocus request. Extension devices are focused using the SetDeviceFocus request in the same way that the keyboard is focused using the SetInputFocus request, except that a device is specified as part of the request. One additional focus state, FollowKeyboard, is provided for extension devices.

To get the current focus state, revert state, and focus time of an extension device, use GetDeviceFocus.

GetDeviceFocus
        device: DEVICE
=>
        focus: WINDOW, PointerRoot, FollowKeyboard, or None
        revert-to: Parent, PointerRoot, FollowKeyboard, or None
        focus-time: TIMESTAMP
Errors: Device, Match

This request returns the current focus state, revert-to state, and last-focus-time of an extension device.

To set the focus of an extension device, use SetDeviceFocus.

SetDeviceFocus
        device: DEVICE
        focus: WINDOW, PointerRoot, FollowKeyboard, or None
        revert-to: Parent, PointerRoot, FollowKeyboard, or None
        focus-time: TIMESTAMP
Errors: Device, Window, Value, Match

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.

The action taken by the server when this request is requested depends on the value of the focus argument:

  • If the focus argument is None, 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.

  • 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.

  • If you assign PointerRoot 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.

  • If you assign FollowKeyboard 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. The specified focus window must be viewable at the time of the request (else a Match error). If the focus window later becomes not viewable, the X server evaluates the revert-to argument to determine the new focus window.

  • If you assign RevertToParent 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 RevertToNone.

  • If you assign RevertToPointerRoot, RevertToFollowKeyboard, or RevertToNone to the revert-to argument, the focus reverts to that value.

When the focus reverts, the X server generates DeviceFocusIn and DeviceFocusOut events, but the last-focus-change time is not affected.

This request causes the X server to generate DeviceFocusIn and DeviceFocusOut events.

2.18 Controlling Device Feedback

To get the settings of feedbacks on an extension device, use GetFeedbackControl. This request provides functionality equivalent to the core GetKeyboardControl and GetPointerControl functions. It also provides a way to control displays associated with an input device that are capable of displaying an integer or string.

GetFeedbackControl
        device: DEVICE
=>
        num_feedbacks_return: CARD16
        return_value: LISTofFEEDBACKSTATE

where

FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState,
                IntegerFeedbackState, StringFeedbackState,
                BellFeedbackState, LedFeedbackState}

Feedbacks are reported by class. Those feedbacks that are reported for the core keyboard device are in class KbdFeedback, and are returned in the KbdFeedbackState structure. The members of that structure are as follows:

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]

Those feedbacks that are equivalent to those reported for the core pointer are in feedback class PtrFeedback and are reported in the PtrFeedbackState structure. The members of that structure are:

CLASS Ptr:
        [class: CARD8
         length: CARD16
         feedback id: CARD8
         accelNumerator: CARD16
         accelDenominator: CARD16
         threshold: CARD16]

Some input devices provide a means of displaying an integer. Those devices will support feedback class IntegerFeedback, which is reported in the IntegerFeedbackState structure. The members of that structure are:

CLASS Integer:
      [class: CARD8
       length: CARD16
       feedback id: CARD8
       resolution: CARD32
       min-val: INT32
       max-val: INT32]

Some input devices provide a means of displaying a string. Those devices will support feedback class StringFeedback, which is reported in the StringFeedbackState structure. The members of that structure are:

CLASS String:
      [class: CARD8
       length: CARD16
       feedback id: CARD8
       max_symbols: CARD16
       num_keysyms_supported: CARD16
       keysyms_supported: LISTofKEYSYM]

Some input devices contain a bell. Those devices will support feedback class BellFeedback, which is reported in the BellFeedbackState structure. The members of that structure are:

CLASS Bell:
      [class: CARD8
       length: CARD16
       feedback id: CARD8
       percent: CARD8
       pitch: CARD16
       duration: CARD16]

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 Value error.

The pitch sets the pitch (specified in Hz) of the bell, if possible. Setting to -1 restores the default. Other negative values generate a Value error.

The duration sets the duration (specified in milliseconds) of the bell, if possible. Setting to -1 restores the default. Other negative values generate a Value error.

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 Led, which is reported in the LedFeedbackState structure. The members of that structure are:

CLASS Led:
      [class: CARD8
       length: CARD16
       feedback id: CARD8
       led_mask: BITMASK
       led_value: BITMASK]

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.

This function will fail with a BadMatch error if the device specified in the request does not support feedbacks.

Errors: Device, Match

To change the settings of a feedback on an extension device, use ChangeFeedbackControl.

ChangeFeedbackControl
        device: DEVICE
        feedbackid: CARD8
        value-mask: BITMASK
        value: FEEDBACKCONTROL
        FEEDBACKCONTROL: {KBDFEEDBACKCONTROL,
                          PTRFEEDBACKCONTROL,
                          INTEGERFEEDBACKCONTROL,
                          STRINGFEEDBACKCONTROL,
                          BELLFEEDBACKCONTROL,
                          LEDFEEDBACKCONTROL}
Errors: Device, Match, Value

Feedback controls are grouped by class. Those feedbacks that are equivalent to those supported by the core keyboard are controlled by feedback class KbdFeedbackClass using the KbdFeedbackControl structure. The members of that structure are:

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}]

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 Value error.

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 Match error if a key is specified without an auto_repeat_mode.

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.

Those feedback controls equivalent to those of the core pointer are controlled by feedback class PtrFeedbackClass using the PtrFeedbackControl structure. The members of that structure are as follows:

PTRFEEDBACKCTL:
        [class: CARD8
         length: CARD16
         feedback id: CARD8
         accelNumerator: INT16
         accelDenominator: INT16
         threshold: INT16]

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 Value error, as does a zero value for the accel-denominator argument.

Some devices are capable of displaying an integer. This is done using feedback class IntegerFeedbackClass using the IntegerFeedbackControl structure. The members of that structure are as follows:

INTEGERCTL:
        [class: CARD8
         length: CARD16
         feedback id: CARD8
         int_to_display: INT32]

Some devices are capable of displaying a string. This is done using feedback class StringFeedbackClass using the StringFeedbackCtl structure. The members of that structure are as follows:

STRINGCTL:
        [class: CARD8
         length: CARD16
         feedback id: CARD8
         syms_to_display: LISTofKEYSYMS]

Some devices contain a bell. This is done using feedback class BellFeedbackClass using the BellFeedbackControl structure. The members of that structure are as follows:

BELLCTL:
        [class: CARD8
         length: CARD16
         feedback id: CARD8
         percent: INT8
         pitch: INT16
         duration: INT16]

Some devices contain leds. These can be turned on and off using the LedFeedbackControl structure. The members of that structure are as follows:

LEDCTL:
        [class: CARD8
         length: CARD16
         feedback id: CARD8
         led_mask: BITMASK
         led_value: BITMASK]
Errors: Device, Match, Value

2.20 Ringing a Bell on an Input Device

To ring a bell on an extension input device, use DeviceBell.

DeviceBell:
        device: DEVICE
        feedbackclass: CARD8
        feedbackid: CARD8
        percent: INT8
Errors: Device, Value

This request is analogous to the core Bell 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 Value error results. The volume at which the bell rings when the percent argument is nonnegative is:

base - [(base * percent) / 100] + percent

The volume at which the bell rings when the percent argument is negative is:

base + [(base * percent) / 100]

To change the base volume of the bell, use ChangeFeedbackControl request.

Controlling Device Encoding

To get the keyboard mapping of an extension device that has keys, use GetDeviceKeyMapping.

GetDeviceKeyMapping
        device: DEVICE
        first-keycode: KEYCODE
        count: CARD8
=>
        keysyms-per-keycode: CARD8
        keysyms: LISTofKEYSYM
Errors: Device, Match, Value

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 Value error), and

first-keycode + count - 1

must be less than or equal to max-keycode as returned in the connection setup (else a Value error). The number of elements in the keysyms list is

count * keysyms-per-keycode

and KEYSYM number N (counting from zero) for keycode K has an index (counting from zero) of

(K - first-keycode) * keysyms-per-keycode + N

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 NoSymbol is used to fill in unused elements for individual keycodes.

If the specified device has not first been opened by this client via OpenDevice, or if that device does not support input class Keys, this request will fail with a Device error.

To change the keyboard mapping of an extension device that has keys, use ChangeDeviceKeyMapping.

ChangeDeviceKeyMapping
        device: DEVICE
        first-keycode: KEYCODE
        keysyms-per-keycode: CARD8
        keysyms: LISTofKEYSYM
        num_codes: CARD8
Errors: Device, Match, Value, Alloc

This request is analogous to the core ChangeKeyMapping 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 OpenDevice, or if that device does not support input class Keys, this request will fail with a Device error.

The number of elements in the keysyms list must be a multiple of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping generates a Length error. The specified first_keycode must be greater than or equal to the min_keycode value returned by the ListInputDevices request, or this request will fail with a Value error. In addition, if the following expression is not less than the max_keycode value returned by the ListInputDevices request, the request will fail with a Value error:

first_keycode + (num_codes / keysyms_per_keycode) - 1

To obtain the keycodes that are used as modifiers on an extension device that has keys, use GetDeviceModifierMapping.

GetDeviceModifierMapping
        device: DEVICE
=>
        keycodes-per-modifier: CARD8
        keycodes: LISTofKEYCODE
Errors: Device, Match

This request is analogous to the core GetModifierMapping 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 Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. 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.

To set which keycodes that are to be used as modifiers for an extension device, use SetDeviceModifierMapping.

SetDeviceModifierMapping
        device: DEVICE
        keycodes-per-modifier: CARD8
        keycodes: LISTofKEYCODE
=>
        status: {Success, Busy, Failed}
Errors: Device, Match, Value, Alloc

This request is analogous to the core SetModifierMapping 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 Length 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 Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. 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 ListInputDevices request (else a Value 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.

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). If some such restriction is violated, the status reply is MappingFailed, 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 MappingBusy, and none of the modifiers are changed.

This request generates a DeviceMappingNotify event on a Success status. The DeviceMappingNotify event will be sent only to those clients that have expressed an interest in receiving that event via the XSelectExtensionEvent request.

2.20 Controlling Button Mapping

These requests are analogous to the core GetPointerMapping and ChangePointerMapping requests. They allow a client to determine the current mapping of buttons on an extension device, and to change that mapping.

To get the current button mapping for an extension device, use GetDeviceButtonMapping.

GetDeviceButtonMapping
        device: DEVICE
        nmap: CARD8
=>
        map_return: LISTofCARD8
Errors: Device, Match

The GetDeviceButtonMapping 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.

nmap indicates the number of elements in the map_return array. Only the first nmap entries will be copied by the library into the map_return array.

To set the button mapping for an extension device, use SetDeviceButtonMapping.

SetDeviceButtonMapping
        device: DEVICE
        map: LISTofCARD8
        nmap: CARD8
=>
        status: CARD8
Errors: Device, Match, Value

The SetDeviceButtonMapping function sets the mapping of the specified device and causes the X server to generate a DeviceMappingNotify event on a status of MappingSuccess. Elements of the list are indexed starting from one. The length of the list, specified in nmap, must be the same as GetDeviceButtonMapping would return. Otherwise, SetDeviceButtonMapping generates a Value error. A zero element disables a button, and elements are not restricted in value by the number of physical buttons. If any of the buttons to be altered are in the down state, the status reply is MappingBusy and the mapping is not changed.

In servers supporting XI 1.x, no two elements can have the same nonzero value. Otherwise, this function generates a Value error.

2.21 Obtaining The State Of A Device

To obtain vectors that describe the state of the keys, buttons and valuators of an extension device, use QueryDeviceState.

QueryDeviceState
        device: DEVICE
=>
        device-id: CARD8
        data: LISTofINPUTCLASS

where

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]
Errors: Device

The QueryDeviceState request returns the current logical state of the buttons, keys, and valuators on the specified input device. The buttons and keys 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.

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.

If the device reports proximity information, a bit in the mode field indicates whether the device is InProximity or OutOfProximity.

2.22 Listing Device Properties

Introduced with XI 1.5

ListDeviceProperties
         deviceid: CARD8
=>
         nAtoms: CARD16
         Atoms: LISTofATOM
Errors: Device

Each device can store an arbitrary number of properties. These properties can be allocated by either the client or the driver. The client can change device properties and the server guarantees that the device driver is notified about a change of the device’s properties.

ListDeviceProperties returns all properties of a device. The client is expected to retrieve details about the properties it is interested in separately.

2.23 Getting a Device Property

Introduced with XI 1.5

GetDeviceProperty:
         property: ATOM
         type: ATOM
         longOffset: CARD32
         longLength: CARD32
         deviceid: CARD8
         delete: BOOL
=>
         propertyType: ATOM
         bytesAfter: CARD32
         nItems: CARD32
         format: CARD8
         deviceid: CARD8
         data: [LISTofCARD8]
Errors: Atom, Device, Value, Access

Retrieve the value for a property. If the property does not exist, propertyType is None and all other fields are undefined.

If type is not AnyPropertyType and does not match the property’s actual type, the propertyType, bytesAfter, and format are returned but not the actual data.

longOffset and longLength specify the offset and length respectively in 32-bit multiples of the data to retrieve.

If delete is True, the property is deleted after querying its data. If the property cannot be deleted, a BadAccess error is returned.

propertyType returns the atom identifier that defines the actual type of the property.

If bytesAfter is non-zero, it specifies the number of data 4-byte units after the retrieved chunk of data.

format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. This information allows the X server to correctly perform byte-swap operations as necessary.

nItem specifies the number of 8-bit, 16-bit, or 32-bit items returned after the request.

2.24 Changing a Device Property

Introduced with XI 1.5

ChangeDeviceProperty:
         property: ATOM
         type: ATOM
         deviceid: CARD8
         format: CARD8
         mode: CARD8
         nUnits: CARD32
Errors: Atom, Device, Value, Match, Access

Changes the value of a specified property.

The type specifies the atom identifier that defines the type of the property. If mode is not PropModeReplace, the type must match the current type of the property or a BadMatch error is returned.

format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. This information allows the X server to correctly perform byte-swap operations as necessary.

If mode is PropModeReplace, a preexising value for this property is replaced with the new value. If mode is PropModePrepend or PropModeAppend, the value is prepended or appended, respectively, to the current value of the property.

nUnits specifies the number of 8-bit, 16-bit, or 32-bit items supplied after the reply.

Changing a device property results in a DevicePropertyNotifyEvent being sent to all clients.

2.25 Deleting a Device Property

Introduced with XI 1.5

DeleteDeviceProperty:
         property: ATOM
         deviceid: CARD8
Errors: Atom, Device, Match, Access.

Deletes the specified property. If the property cannot be deleted by the client, a BadAccess error is returned.

3. Events

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.

3.1 Button, Key, and Motion Events

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: <see below>
        state: SETofKEYBUTMASK
        time: TIMESTAMP

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 DeviceKeyPress and DeviceKeyRelease are generated for all keys, even those mapped to modifier bits. The “source” 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 “event” window.

The root is the root window of the “source” 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 “event” 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 X pointer and modifier keys on the core X keyboard just before the event.

The detail component type varies with the event type: Event Component DeviceKeyPress KEYCODE DeviceKeyRelease KEYCODE DeviceButtonPress BUTTON DeviceButtonRelease BUTTON DeviceMotionNotify { Normal , Hint }

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 DeviceMotionHint is selected, the server is free to send only one DeviceMotionNotify event (with detail Hint) 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 QueryDeviceState or GetDeviceMotionEvents request.

3.2 DeviceValuator Event

DeviceValuator
        device: CARD8
        device_state: SETofKEYBUTMASK
        num_valuators: CARD8
        first_valuator: CARD8
        valuators: LISTofINT32

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.

The device_state component gives the state of the buttons and modifiers on the device generating the event.

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.

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.

3.3 Device Focus Events

DeviceFocusIn
DeviceFocusOut
        device: CARD8
        time: TIMESTAMP
        event: WINDOW
        mode: { Normal, WhileGrabbed, Grab, Ungrab}
        detail: { Ancestor, Virtual, Inferior, Nonlinear,
                  NonlinearVirtual, Pointer, PointerRoot, None}

These events are generated when the input focus changes and are reported to clients selecting DeviceFocusChange for the specified device and window. Events generated by SetDeviceFocus when the device is not grabbed have mode Normal. Events generated by SetDeviceFocus when the device is grabbed have mode WhileGrabbed. Events generated when a device grab activates have mode Grab, and events generated when a device grab deactivates have mode Ungrab.

All DeviceFocusOut events caused by a window unmap are generated after any UnmapNotify event, but the ordering of DeviceFocusOut with respect to generated EnterNotify, LeaveNotify, VisibilityNotify and Expose events is not constrained.

DeviceFocusIn and DeviceFocusOut events are generated for focus changes of extension devices in the same manner as focus events for the core devices are generated.

3.4 Device State Notify Event

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

This event reports the state of the device just as in the QueryDeviceState request. This event is reported to clients selecting DeviceStateNotify for the device and window and is generated immediately after every EnterNotify and DeviceFocusIn. 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.

3.5 Device KeyState and ButtonState Notify Events

DeviceKeyStateNotify
        device: CARD8
        keys: LISTofCARD8
DeviceButtonStateNotify
        device: CARD8
        buttons: LISTofCARD8

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.

3.6 DeviceMappingNotify Event

DeviceMappingNotify
        time: TIMESTAMP
        device: CARD8
        request: CARD8
        first_keycode: CARD8
        count: CARD8

This event reports a change in the mapping of keys, modifiers, or buttons on an extension device. This event is reported to clients selecting DeviceMappingNotify for the device and window and is generated after every client SetDeviceButtonMapping, ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request.

3.7 ChangeDeviceNotify Event

ChangeDeviceNotify
        device: CARD8
        time: TIMESTAMP
        request: CARD8

This event reports a change in the physical device being used as the core X keyboard or X pointer device. ChangeDeviceNotify events are reported to clients selecting ChangeDeviceNotify for the device and window and is generated after every client ChangeKeyboardDevice or ChangePointerDevice request.

3.7 Proximity Events

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

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.

The “source” 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 “event” window.

The root is the root window of the “source” 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 “event” 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.

3.8 DevicePresenceEvents

Introduced with XI 1.4.

DevicePresence
        time: TIMESTAMP
        devchange: BYTE
            #x00: DeviceAdded
            #x01: DeviceRemoved
            #x02: DeviceEnabled
            #x03: DeviceDisabled
            #x04: DeviceUnrecoverable
            #x05: DeviceControlChanged
        deviceid: BYTE
        control: CARD16

DevicePresence 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 ListInputDevices request to obtain the updated list of input devices. DevicePresence events are also sent when a control on the device has been changed.

The devchange field specifies the type of operation. In case of DeviceAdded, a new device has been added to the server, but this device does not yet send events. If devchange is set to DeviceEnabled, the device is enabled and will generate events. If the field is DeviceDisabled or DeviceRemoved, the given device is disabled and stops sending events or was removed from the server, respectively. If the field is DeviceUnrecoverable, an IO-error has occured on the device and the device is forcibly disabled and removed by the server. If devchange is DeviceControlChanged, control specifies the type of control that has been changed.

3.9 DevicePropertyNotifyEvent

Introduced with XI 1.5.

DevicePropertyNotifyEvent
        deviceid: CARD8
        state: CARD8
        time: TIMESTAMP
        atom: ATOM

A DevicePropertyNotifyEvent is sent to all clients when a property on the device is created, deleted, or changes value.

The deviceid specifies the device which’s property has been modified.

The atom specifies the named identifier of the property that has been altered.

If state is PropertyNewValue, the given property has a new value or has been newly created. If state is PropertyDeleted, the given property has been deleted.


0707010006236c000081a400000000000000000000000153c4dc3e0001987c000001000001001cffffffffffffffff0000003000000000root/usr/local/share/doc/inputproto/XIproto.txtX11 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 1.5 Peter Hutterer Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and Ardent Computer Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. Ardent and Hewlett-Packard make no representations about the suitability for any purpose of the information in this document. It is provided "as is" without express or implied warranty. Copyright © 1989, 1990, 1991, 1992 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 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. 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. X Window System is a trademark of The Open Group. Copyright © 2008 by Peter Hutterer Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 1. Input Extension Overview --------------------------- 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. This document only describes the behaviour of servers supporting up to the X Input Extension 1.5. For servers supporting the X Input Extensions 2.0, see XI2proto.txt. New clients are discouraged from using this protocol specification. Instead, the use of XI 2.x is recommended. 1.1 Design Approach ~~~~~~~~~~~~~~~~~~~ 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. 1.2 Core Input Devices ~~~~~~~~~~~~~~~~~~~~~~ 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. 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 servers supporting XI 2.0 and above, there may be multiple core pointers and keyboards. Refer to XI2proto.txt for more information. The X keyboard and X pointer are referred to in this document as the core devices, and the input events they generate (KeyPress, KeyRelease, ButtonPress, ButtonRelease, and MotionNotify) are known as the core input events. All other input devices are referred to as extension input devices and the input events they generate are referred to as extension input events. 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 "Event Synchronization and Core Grabs". 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. 1.3 Extension Input Devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. 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 ListInputDevices 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 OpenDevice 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 ( DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify, etc.) and contain a device identifier so that events of the same type coming from different input devices can be distinguished. 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). 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 input classes. 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. 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. 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. 1.4 Event Classes ----------------- 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. When a client opens a extension input device via the OpenDevice request, an XDevice structure is returned. Macros are provided that extract 32-bit numbers called event classes from that structure, that a client can use to register interest in extension events via the SelectExtensionEvent request. The event class combines the desired event type and device id, and may be thought of as the equivalent of core event masks. 1.5 Input Classes ~~~~~~~~~~~~~~~~~ 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: KEY The device reports key events. BUTTON The device reports button events. VALUATOR The device reports valuator data in motion events. PROXIMITY The device reports proximity events. FOCUS The device can be focused and reports focus events. FEEDBACK The device supports feedbacks. OTHER The ChangeDeviceNotify, DeviceMappingNotify, and DeviceStateNotify macros may be invoked passing the XDevice structure returned for this device. 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 ListInputDevices 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. 2. Requests ----------- 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. 2.1 Getting the Extension Version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The GetExtensionVersion request returns version information about the input extension. GetExtensionVersion name: STRING => present: BOOL protocol-major-version: CARD16 protocol-minor-version: CARD16 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 XI.h. Each version is a superset of the previous versions. The name must be the name of the Input Extension as defined in the header file XI.h. 2.2 Listing Available Devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 ListInputDevices request, which will return a list of all devices that can be opened by the X server. ListInputDevices => input-devices: ListOfDeviceInfo where DEVICEINFO: [type: ATOM id: CARD8 num_classes: CARD8 use: {IsXKeyboard, IsXPointer, IsXExtensionPointer, IsXExtensionKeyboard, IsExtensionDevice} 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} Errors: None 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. The information returned for each device is as follows: type The type field is of type Atom and indicates the nature of the device. Clients may determine device types by invoking the XInternAtom request passing one of the names defined in the header file XI.h. The following names have been defined to date: MOUSE TABLET KEYBOARD TOUCHSCREEN TOUCHPAD BUTTONBOX BARCODE KNOB_BOX TRACKBALL QUADRATURE SPACEBALL DATAGLOVE EYETRACKER CURSORKEYS FOOTMOUSE ID_MODULE ONE_KNOB NINE_KNOB JOYSTICK id The id 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 XOpenDevice, then closed via XCloseDevice, then opened again, it is not guaranteed to have the same id after the second open request. num_classes The num_classes 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 ListInputDevices. Some input classes, such as class Focus and class Proximity do not have any information to be returned by ListInputDevices. use The use field specifies how the device is currently being used. If the value is IsXKeyboard, the device is currently being used as the X keyboard. If the value is IsXPointer, the device is currently being used as the X pointer. If the value is IsXExtensionPointer, the device is available for use as an extension pointer. If the value is IsXExtensionKeyboard, the device is available for use as and extension keyboard. Older versions of XI report all extension devices as IsXExtensionDevice. name The name field contains a pointer to a null-terminated string that corresponds to one of the defined device types. InputInfo InputInfo is one of: KeyInfo, ButtonInfo or ValuatorInfo. The first two fields are common to all three: class The class field is a cardinal value in the range 0-255. It uniquely identifies the class of input for which information is returned. length The length 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. The remaining information returned for input class KEYCLASS is as follows: min_keycode min_keycode is of type KEYCODE. It specifies the minimum keycode that the device will report. The minimum keycode will not be smaller than 8. max_keycode max_keycode is of type KEYCODE. It specifies the maximum keycode that the device will report. The maximum keycode will not be larger than 255. num_keys num_keys is a cardinal value that specifies the number of keys that the device has. The remaining information returned for input class BUTTONCLASS is as follows: num_buttons num_buttons is a cardinal value that specifies the number of buttons that the device has. The remaining information returned for input class VALUATORCLASS is as follows: mode mode is a constant that has one of the following values: Absolute or Relative. Some devices allow the mode to be changed dynamically via the SetDeviceMode request. motion_buffer_size motion_buffer_size is a cardinal number that specifies the number of elements that can be contained in the motion history buffer for the device. axes The axes field contains a pointer to an AXISINFO struture. The information returned for each axis reported by the device is: resolution The resolution is a cardinal value in counts/meter. min_val The min_val field is a cardinal value in that contains the minimum value the device reports for this axis. For devices whose mode is Relative, the min_val field will contain 0. max_val The max_val field is a cardinal value in that contains the maximum value the device reports for this axis. For devices whose mode is Relative, the max_val field will contain 0. 2.3 Enabling Devices ~~~~~~~~~~~~~~~~~~~~ Client programs that wish to access an extension device must request that the server open that device. This is done via the OpenDevice request. OpenDevice id: CARD8 => DEVICE: [device_id: XID num_classes: INT32 classes: LISTofINPUTCLASSINFO] INPUTCLASSINFO: [input_class: CARD8 event_type_base: CARD8] Errors: Device 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 Keys reports DeviceKeyPress and DeviceKeyRelease event classes. Input classes are unique numbers registered with the X Consortium. Input class Other exists to report event classes that are not specific to any one input class, such as DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify. The information returned for each device is as follows: device_id The device_id is a number that uniquely identifies the device. num_classes The num_classes field contains the number of input classes supported by this device. For each class of input supported by the device, the InputClassInfo structure contains the following information: input_class The input_class is a small cardinal number that identifies the class of input. event_type_base The event_type_base 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 Device 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". The information in the InputClassInfo reflects the state of this device at the time the request was processed. Before it exits, the client program should explicitly request that the server close the device. This is done via the CloseDevice request. A client may open the same extension device more than once. Requests after the first successful one return an additional XDevice structure with the same information as the first, but otherwise have no effect. A single CloseDevice request will terminate that client's access to the device. 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. 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. CloseDevice: device: DEVICE Errors: Device 2.4 Changing The Mode Of A Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 SetDeviceMode request. The valid values are Absolute or Relative. This request will fail and return DeviceBusy if another client already has the device open with a different mode. It will fail and return AlreadyGrabbed if another client has the device grabbed. The request will fail with a BadMatch error if the device has no valuators and reports no axes of motion. The request will fail with a BadMode error if the requested mode is not supported by the device. SetDeviceMode device:DEVICE mode: {Absolute, Relative} => status: {Success, DeviceBusy, AlreadyGrabbed} Errors: Device, Match, Mode 2.5 Initializing Valuators on an Input Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 Absolute. To initialize the valuators on such a device, use the SetDeviceValuators request. SetDeviceValuators device: DEVICE first_valuator: CARD8 num_valuators: CARD8 valuators: LISTOFINT32 => status: {Success, AlreadyGrabbed} Errors: Length, Device, Match, Value 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 Value error will result. If the request succeeds, Success is returned. If the specifed device is grabbed by some other client, the request will fail and a status of AlreadyGrabbed will be returned. 2.6 Getting Input Device Controls ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GetDeviceControl device: DEVICE control: XID => controlState: {DeviceState} where DeviceState: DeviceResolutionState Errors: Length, Device, Match, Value 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. 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. 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. Supported device controls and the information returned for them include: DEVICE_RESOLUTION: [control: CARD16 length: CARD16 num_valuators: CARD8 resolutions: LISTofCARD32 min_resolutions: LISTofCARD32 max_resolutions: LISTofCARD32] 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. When this control is specified, XGetDeviceControl will fail with a BadMatch error if the specified device has no valuators. ChangeDeviceControl: device: DEVICE XID: controlId control: DeviceControl where DeviceControl: DeviceResolutionControl => status: {Success, DeviceBusy, AlreadyGrabbed} Errors: Length, Device, Match, Value 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. The information passed with this request varies according to the specified control and is mapped by a structure appropriate for that control. 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. Supported device controls and the information specified for them include: DEVICE_RESOLUTION: [control: CARD16 length: CARD16 first_valuator: CARD8 num_valuators: CARD8 resolutions: LISTofCARD32] 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. 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. If the request fails for any reason, none of the valuator resolutions will be changed. ChangeDeviceControl causes the server to send a DevicePresence event to interested clients. 2.7 Selecting Extension Device Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extension input events are selected using the SelectExtensionEvent request. SelectExtensionEvent interest: LISTofEVENTCLASS window: WINDOW Errors: Window, Class, Access This request specifies to the server the events within the specified window which are of interest to the client. As with the core XSelectInput function, multiple clients can select input on the same window. XSelectExtensionEvent requires a list of event classes. 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 XOpenDevice request. The names of these macros correspond to the desired events, i.e. the DeviceKeyPress is used to obtain the event class for DeviceKeyPress events. The syntax of the macro invocation is: DeviceKeyPress (device, event_type, event_class); device: DEVICE event_type: INT event_class: INT The value returned in event_type is the value that will be contained in the event type field of the XDeviceKeyPressEvent when it is received by the client. The value returned in event_class is the value that should be passed in making an XSelectExtensionEvent request to receive DeviceKeyPress events. For DeviceButtonPress 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 DeviceButtonRelease event for each DeviceButtonPress event it receives, it should specify the DeviceButtonPressGrab event class as well as the DeviceButtonPress event class. This restricts the client in that only one client at a time may request DeviceButtonPress events from the same device and window if any client specifies this class. If any client has specified the DeviceButtonPressGrab class, any requests by any other client that specify the same device and window and specify DeviceButtonPress or DeviceButtonPressGrab will cause an Access error to be generated. If only the DeviceButtonPress 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. A client may also specify the DeviceOwnerGrabButton class. If it has specified both the DeviceButtonPressGrab and the DeviceOwnerGrabButton classes, implicit passive grabs will activate with owner_events set to True. If only the DeviceButtonPressGrab class is specified, implicit passive grabs will activate with owner_events set to False. The client may select DeviceMotion events only when a button is down. It does this by specifying the event classes Button1Motion through Button5Motion, or ButtonMotion. An input device will only support as many button motion classes as it has buttons. 2.8 Determining Selected Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To determine which extension events are currently selected from a given window, use GetSelectedExtensionEvents. GetSelectedExtensionEvents window: WINDOW => this-client: LISTofEVENTCLASS all-clients: LISTofEVENTCLASS Errors: Window 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 GetWindowAttributes request. 2.9 Controlling Event Propagation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. Client programs may control extension event propagation through the use of the following two requests. XChangeDeviceDontPropagateList 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. ChangeDeviceDontPropagateList window: WINDOW eventclass: LISTofEVENTCLASS mode: {AddToList, DeleteFromList} Errors: Window, Class, Mode This function modifies the list specifying the events that are not propagated to the ancestors of the specified window. You may use the modes AddToList or DeleteFromList. GetDeviceDontPropagateList window: WINDOW => dont-propagate-list: LISTofEVENTCLASS Errors: Window This function returns a list specifying the events that are not propagated to the ancestors of the specified window. 2.10 Sending Extension Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ One client program may send an event to another via the XSendExtensionEvent function. The event in the XEvent 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 True in the forwarded event and to set the sequence number in the event correctly. XSendExtensionEvent returns zero if the conversion-to-wire protocol failed, otherwise it returns nonzero. SendExtensionEvent device: DEVICE destination: WINDOW propagate: BOOL eventclass: LISTofEVENTCLASS event: XEVENT Errors: Device, Value, Class, Window 2.11 Getting Motion History ~~~~~~~~~~~~~~~~~~~~~~~~~~~ GetDeviceMotionEvents device: DEVICE start, stop: TIMESTAMP or CurrentTime => nevents_return: CARD32 mode_return: {Absolute, Relative} axis_count_return: CARD8 events: LISTofDEVICETIMECOORD where DEVICETIMECOORD: [data: LISTofINT32 time: TIMESTAMP] Errors: Device, Match 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. 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. 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 ListInputDevices request. 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. 2.12 Changing The Core Devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 BadDevice error. 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. These requests change the X keyboard or X pointer device and generate an ChangeDeviceNotify event and a MappingNotify event. The ChangeDeviceNotify event is sent only to those clients that have expressed an interest in receiving that event via the XSelectExtensionEvent 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. These requests fail and return AlreadyGrabbed if either the specified device or the core device it would replace are grabbed by some other client. They fail and return GrabFrozen if either device is frozen by the active grab of another client. These requests fail with a BadDevice error if the specified device is invalid, or has not previously been opened via OpenDevice. To change the X keyboard device, use the ChangeKeyboardDevice request. The specified device must support input class Keys (as reported in the ListInputDevices request) or the request will fail with a BadMatch 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. 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 FocusRec, one is added by the ChangeKeyboardDevice request. The X keyboard is assumed to have a KbdFeedbackClassRec. If the device was initialized without a KbdFeedbackClassRec, one will be added by this request. The KbdFeedbackClassRec will specify a null routine as the control procedure and the bell procedure. ChangeKeyboardDevice device: DEVICE => status: Success, AlreadyGrabbed, Frozen Errors: Device, Match To change the X pointer device, use the ChangePointerDevice 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. The X pointer device does not contain a FocusRec. If the new pointer was initialized with a FocusRec, it is freed by the ChangePointerDevice request. The X pointer is assumed to have a ButtonClassRec and a PtrFeedbackClassRec. If the device was initialized without a ButtonClassRec or a PtrFeedbackClassRec, one will be added by this request. The ButtonClassRec added will have no buttons, and the PtrFeedbackClassRec will specify a null routine as the control procedure. 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 BadDevice 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. ChangePointerDevice device: DEVICE xaxis: CARD8 yaxis: CARD8 => status: Success, AlreadyGrabbed, Frozen Errors: Device, Match 2.12 Event Synchronization And Core Grabs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. The core grab requests require a pointer_mode and keyboard_mode argument. The meaning of these modes is changed by the input extension. For the XGrabPointer and XGrabButton requests, pointer_mode controls synchronization of the pointer device, and keyboard_mode controls the synchronization of all other input devices. For the XGrabKeyboard and XGrabKey requests, pointer_mode controls the synchronization of all input devices except the X keyboard, while keyboard_mode controls the synchronization of the keyboard. When using one of the core grab requests, the synchronization of extension devices is controlled by the mode specified for the device not being grabbed. 2.13 Extension Active Grabs ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Active grabs of extension devices are supported via the GrabDevice request in the same way that core devices are grabbed using the core GrabKeyboard request, except that a Device is passed as a function parameter. A list of events that the client wishes to receive is also passed. The UngrabDevice request allows a previous active grab for an extension device to be released. To grab an extension device, use the GrabDevice request. The device must have previously been opened using the OpenDevice request. 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 => status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable Errors: Device, Window, Value 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. 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. If owner-events is False, 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 True, 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. If this-device-mode is Asynchronous, 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 Synchronous, 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 AllowDeviceEvents 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. If other-device-mode is Asynchronous, event processing is unaffected by activation of the grab. If other-device-mode is Synchronous, 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 AllowDeviceEvents 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. This request generates DeviceFocusIn and DeviceFocusOut events. This request fails and returns: AlreadyGrabbed If the device is actively grabbed by some other client. NotViewable If grab-window is not viewable. InvalidTime 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 CurrentTime is replaced by the current X server time. Frozen If the device is frozen by an active grab of another client. 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. To release a grab of an extension device, use UngrabDevice. UngrabDevice device: DEVICE time: TIMESTAMP or CurrentTime Errors: Device This request releases the device if this client has it actively grabbed (from either GrabDevice or GrabDeviceKey) and releases any queued events. If any devices were frozen by the grab, UngrabDevice 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. This request generates DeviceFocusIn and DeviceFocusOut events. An UngrabDevice is performed automatically if the event window for an active device grab becomes not viewable. 2.14 Passively Grabbing A Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Passive grabs of buttons and keys on extension devices are supported via the GrabDeviceButton and GrabDeviceKey requests. These passive grabs are released via the UngrabDeviceKey and UngrabDeviceButton requests. To passively grab a single key on an extension device, use GrabDeviceKey. That device must have previously been opened using the OpenDevice request. 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} Errors: Device, Match, Access, Window, Value This request is analogous to the core GrabKey request. It establishes a passive grab on a device. Consequently, in the future: * 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), * AND no other modifier keys logically are down, * 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, * AND a passive grab on the same device and key combination does not exist on any ancestor of the grab window, * THEN the device is actively grabbed, as for GrabDevice, the last-device-grab time is set to the time at which the key was pressed (as transmitted in the DeviceKeyPress event), and the DeviceKeyPress event is reported. The interpretation of the remaining arguments is as for GrabDevice. 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). 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. A modifier of AnyModifier 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 AnyKey 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 ListInputDevices request. If it is not within that range, GrabDeviceKey generates a Value error. NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device. An Access error is generated if some other client has issued a GrabDeviceKey with the same device and key combination on the same window. When using AnyModifier or AnyKey, the request fails completely and the X server generates a Access error and no grabs are established if there is a conflicting grab for any combination. This request cannot be used to grab a key on the X keyboard device. The core GrabKey request should be used for that purpose. To release a passive grab of a single key on an extension device, use UngrabDeviceKey. UngrabDeviceKey device: DEVICE keycode: KEYCODE or AnyKey modifiers: SETofKEYMASK or AnyModifier modifier-device: DEVICE or NULL grab-window: WINDOW Errors: Device, Match, Window, Value, Alloc This request is analogous to the core UngrabKey request. It releases the key combination on the specified window if it was grabbed by this client. A modifier of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A key of AnyKey is equivalent to issuing the request for all possible keycodes. This request has no effect on an active grab. NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device. 2.15 Passively Grabbing A Button ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To establish a passive grab for a single button on an extension device, use GrabDeviceButton. 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} Errors: Device, Match, Window, Access, Value This request is analogous to the core GrabButton 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 OpenDevice request. The GrabDeviceButton request establishes a passive grab on a device. Consequently, in the future, * 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), * AND the grab window contains the device, * AND a passive grab on the same device and button/ key combination does not exist on any ancestor of the grab window, * THEN the device is actively grabbed, as for GrabDevice, the last-grab time is set to the time at which the button was pressed (as transmitted in the DeviceButtonPress event), and the DeviceButtonPress event is reported. The interpretation of the remaining arguments is as for GrabDevice. 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). 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. A modifier of AnyModifier 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 AnyButton is equivalent to issuing the request for all possible buttons. It is not required that the specified button be assigned to a physical button. NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device. An Access error is generated if some other client has issued a GrabDeviceButton with the same device and button combination on the same window. When using AnyModifier or AnyButton, the request fails completely and the X server generates a Access error and no grabs are established if there is a conflicting grab for any combination. The request has no effect on an active grab. This request cannot be used to grab a button on the X pointer device. The core GrabButton request should be used for that purpose. To release a passive grab of a button on an extension device, use UngrabDeviceButton. UngrabDeviceButton device: DEVICE button: BUTTON or AnyButton modifiers: SETofKEYMASK or AnyModifier modifier-device: DEVICE or NULL grab-window: WINDOW Errors: Device, Match, Window, Value, Alloc 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 AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A button of AnyButton 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 OpenDevice request otherwise a Device error will be generated. NULL may be passed for the modifier_device. If the modifier_device is NULL, the core X keyboard is used as the modifier_device. This request cannot be used to ungrab a button on the X pointer device. The core UngrabButton request should be used for that purpose. 2.16 Thawing A Device ~~~~~~~~~~~~~~~~~~~~~ To allow further events to be processed when a device has been frozen, use AllowDeviceEvents. AllowDeviceEvents device: DEVICE event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices, ReplayThisdevice, AsyncAll, or SyncAll} time:TIMESTAMP or CurrentTime Errors: Device, Value The AllowDeviceEvents 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. The following describes the processing that occurs depending on what constant you pass to the event-mode argument: * 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. * 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. * 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. * 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 “thaws” 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. * 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). * 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. 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. 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. 2.17 Controlling Device Focus ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The current focus window for an extension input device can be determined using the GetDeviceFocus request. Extension devices are focused using the SetDeviceFocus request in the same way that the keyboard is focused using the SetInputFocus request, except that a device is specified as part of the request. One additional focus state, FollowKeyboard, is provided for extension devices. To get the current focus state, revert state, and focus time of an extension device, use GetDeviceFocus. GetDeviceFocus device: DEVICE => focus: WINDOW, PointerRoot, FollowKeyboard, or None revert-to: Parent, PointerRoot, FollowKeyboard, or None focus-time: TIMESTAMP Errors: Device, Match This request returns the current focus state, revert-to state, and last-focus-time of an extension device. To set the focus of an extension device, use SetDeviceFocus. SetDeviceFocus device: DEVICE focus: WINDOW, PointerRoot, FollowKeyboard, or None revert-to: Parent, PointerRoot, FollowKeyboard, or None focus-time: TIMESTAMP Errors: Device, Window, Value, Match 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. The action taken by the server when this request is requested depends on the value of the focus argument: * If the focus argument is None, 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. * 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. * If you assign PointerRoot 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. * If you assign FollowKeyboard 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. The specified focus window must be viewable at the time of the request (else a Match error). If the focus window later becomes not viewable, the X server evaluates the revert-to argument to determine the new focus window. * If you assign RevertToParent 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 RevertToNone. * If you assign RevertToPointerRoot, RevertToFollowKeyboard, or RevertToNone to the revert-to argument, the focus reverts to that value. When the focus reverts, the X server generates DeviceFocusIn and DeviceFocusOut events, but the last-focus-change time is not affected. This request causes the X server to generate DeviceFocusIn and DeviceFocusOut events. 2.18 Controlling Device Feedback ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To get the settings of feedbacks on an extension device, use GetFeedbackControl. This request provides functionality equivalent to the core GetKeyboardControl and GetPointerControl functions. It also provides a way to control displays associated with an input device that are capable of displaying an integer or string. GetFeedbackControl device: DEVICE => num_feedbacks_return: CARD16 return_value: LISTofFEEDBACKSTATE where FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState, IntegerFeedbackState, StringFeedbackState, BellFeedbackState, LedFeedbackState} Feedbacks are reported by class. Those feedbacks that are reported for the core keyboard device are in class KbdFeedback, and are returned in the KbdFeedbackState structure. The members of that structure are as follows: 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] Those feedbacks that are equivalent to those reported for the core pointer are in feedback class PtrFeedback and are reported in the PtrFeedbackState structure. The members of that structure are: CLASS Ptr: [class: CARD8 length: CARD16 feedback id: CARD8 accelNumerator: CARD16 accelDenominator: CARD16 threshold: CARD16] Some input devices provide a means of displaying an integer. Those devices will support feedback class IntegerFeedback, which is reported in the IntegerFeedbackState structure. The members of that structure are: CLASS Integer: [class: CARD8 length: CARD16 feedback id: CARD8 resolution: CARD32 min-val: INT32 max-val: INT32] Some input devices provide a means of displaying a string. Those devices will support feedback class StringFeedback, which is reported in the StringFeedbackState structure. The members of that structure are: CLASS String: [class: CARD8 length: CARD16 feedback id: CARD8 max_symbols: CARD16 num_keysyms_supported: CARD16 keysyms_supported: LISTofKEYSYM] Some input devices contain a bell. Those devices will support feedback class BellFeedback, which is reported in the BellFeedbackState structure. The members of that structure are: CLASS Bell: [class: CARD8 length: CARD16 feedback id: CARD8 percent: CARD8 pitch: CARD16 duration: CARD16] 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 Value error. The pitch sets the pitch (specified in Hz) of the bell, if possible. Setting to -1 restores the default. Other negative values generate a Value error. The duration sets the duration (specified in milliseconds) of the bell, if possible. Setting to -1 restores the default. Other negative values generate a Value error. 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 Led, which is reported in the LedFeedbackState structure. The members of that structure are: CLASS Led: [class: CARD8 length: CARD16 feedback id: CARD8 led_mask: BITMASK led_value: BITMASK] 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. This function will fail with a BadMatch error if the device specified in the request does not support feedbacks. Errors: Device, Match To change the settings of a feedback on an extension device, use ChangeFeedbackControl. ChangeFeedbackControl device: DEVICE feedbackid: CARD8 value-mask: BITMASK value: FEEDBACKCONTROL FEEDBACKCONTROL: {KBDFEEDBACKCONTROL, PTRFEEDBACKCONTROL, INTEGERFEEDBACKCONTROL, STRINGFEEDBACKCONTROL, BELLFEEDBACKCONTROL, LEDFEEDBACKCONTROL} Errors: Device, Match, Value Feedback controls are grouped by class. Those feedbacks that are equivalent to those supported by the core keyboard are controlled by feedback class KbdFeedbackClass using the KbdFeedbackControl structure. The members of that structure are: 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}] 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 Value error. 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 Match error if a key is specified without an auto_repeat_mode. 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. Those feedback controls equivalent to those of the core pointer are controlled by feedback class PtrFeedbackClass using the PtrFeedbackControl structure. The members of that structure are as follows: PTRFEEDBACKCTL: [class: CARD8 length: CARD16 feedback id: CARD8 accelNumerator: INT16 accelDenominator: INT16 threshold: INT16] 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 Value error, as does a zero value for the accel-denominator argument. Some devices are capable of displaying an integer. This is done using feedback class IntegerFeedbackClass using the IntegerFeedbackControl structure. The members of that structure are as follows: INTEGERCTL: [class: CARD8 length: CARD16 feedback id: CARD8 int_to_display: INT32] Some devices are capable of displaying a string. This is done using feedback class StringFeedbackClass using the StringFeedbackCtl structure. The members of that structure are as follows: STRINGCTL: [class: CARD8 length: CARD16 feedback id: CARD8 syms_to_display: LISTofKEYSYMS] Some devices contain a bell. This is done using feedback class BellFeedbackClass using the BellFeedbackControl structure. The members of that structure are as follows: BELLCTL: [class: CARD8 length: CARD16 feedback id: CARD8 percent: INT8 pitch: INT16 duration: INT16] Some devices contain leds. These can be turned on and off using the LedFeedbackControl structure. The members of that structure are as follows: LEDCTL: [class: CARD8 length: CARD16 feedback id: CARD8 led_mask: BITMASK led_value: BITMASK] Errors: Device, Match, Value 2.20 Ringing a Bell on an Input Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To ring a bell on an extension input device, use DeviceBell. DeviceBell: device: DEVICE feedbackclass: CARD8 feedbackid: CARD8 percent: INT8 Errors: Device, Value This request is analogous to the core Bell 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 Value error results. The volume at which the bell rings when the percent argument is nonnegative is: base - [(base * percent) / 100] + percent The volume at which the bell rings when the percent argument is negative is: base + [(base * percent) / 100] To change the base volume of the bell, use ChangeFeedbackControl request. Controlling Device Encoding To get the keyboard mapping of an extension device that has keys, use GetDeviceKeyMapping. GetDeviceKeyMapping device: DEVICE first-keycode: KEYCODE count: CARD8 => keysyms-per-keycode: CARD8 keysyms: LISTofKEYSYM Errors: Device, Match, Value 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 Value error), and first-keycode + count - 1 must be less than or equal to max-keycode as returned in the connection setup (else a Value error). The number of elements in the keysyms list is count * keysyms-per-keycode and KEYSYM number N (counting from zero) for keycode K has an index (counting from zero) of (K - first-keycode) * keysyms-per-keycode + N 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 NoSymbol is used to fill in unused elements for individual keycodes. If the specified device has not first been opened by this client via OpenDevice, or if that device does not support input class Keys, this request will fail with a Device error. To change the keyboard mapping of an extension device that has keys, use ChangeDeviceKeyMapping. ChangeDeviceKeyMapping device: DEVICE first-keycode: KEYCODE keysyms-per-keycode: CARD8 keysyms: LISTofKEYSYM num_codes: CARD8 Errors: Device, Match, Value, Alloc This request is analogous to the core ChangeKeyMapping 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 OpenDevice, or if that device does not support input class Keys, this request will fail with a Device error. The number of elements in the keysyms list must be a multiple of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping generates a Length error. The specified first_keycode must be greater than or equal to the min_keycode value returned by the ListInputDevices request, or this request will fail with a Value error. In addition, if the following expression is not less than the max_keycode value returned by the ListInputDevices request, the request will fail with a Value error: first_keycode + (num_codes / keysyms_per_keycode) - 1 To obtain the keycodes that are used as modifiers on an extension device that has keys, use GetDeviceModifierMapping. GetDeviceModifierMapping device: DEVICE => keycodes-per-modifier: CARD8 keycodes: LISTofKEYCODE Errors: Device, Match This request is analogous to the core GetModifierMapping 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 Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. 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. To set which keycodes that are to be used as modifiers for an extension device, use SetDeviceModifierMapping. SetDeviceModifierMapping device: DEVICE keycodes-per-modifier: CARD8 keycodes: LISTofKEYCODE => status: {Success, Busy, Failed} Errors: Device, Match, Value, Alloc This request is analogous to the core SetModifierMapping 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 Length 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 Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. 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 ListInputDevices request (else a Value 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. 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). If some such restriction is violated, the status reply is MappingFailed, 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 MappingBusy, and none of the modifiers are changed. This request generates a DeviceMappingNotify event on a Success status. The DeviceMappingNotify event will be sent only to those clients that have expressed an interest in receiving that event via the XSelectExtensionEvent request. 2.20 Controlling Button Mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These requests are analogous to the core GetPointerMapping and ChangePointerMapping requests. They allow a client to determine the current mapping of buttons on an extension device, and to change that mapping. To get the current button mapping for an extension device, use GetDeviceButtonMapping. GetDeviceButtonMapping device: DEVICE nmap: CARD8 => map_return: LISTofCARD8 Errors: Device, Match The GetDeviceButtonMapping 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. nmap indicates the number of elements in the map_return array. Only the first nmap entries will be copied by the library into the map_return array. To set the button mapping for an extension device, use SetDeviceButtonMapping. SetDeviceButtonMapping device: DEVICE map: LISTofCARD8 nmap: CARD8 => status: CARD8 Errors: Device, Match, Value The SetDeviceButtonMapping function sets the mapping of the specified device and causes the X server to generate a DeviceMappingNotify event on a status of MappingSuccess. Elements of the list are indexed starting from one. The length of the list, specified in nmap, must be the same as GetDeviceButtonMapping would return. Otherwise, SetDeviceButtonMapping generates a Value error. A zero element disables a button, and elements are not restricted in value by the number of physical buttons. If any of the buttons to be altered are in the down state, the status reply is MappingBusy and the mapping is not changed. In servers supporting XI 1.x, no two elements can have the same nonzero value. Otherwise, this function generates a Value error. 2.21 Obtaining The State Of A Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To obtain vectors that describe the state of the keys, buttons and valuators of an extension device, use QueryDeviceState. QueryDeviceState device: DEVICE => device-id: CARD8 data: LISTofINPUTCLASS where 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] Errors: Device The QueryDeviceState request returns the current logical state of the buttons, keys, and valuators on the specified input device. The buttons and keys 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. 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. If the device reports proximity information, a bit in the mode field indicates whether the device is InProximity or OutOfProximity. 2.22 Listing Device Properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduced with XI 1.5 ListDeviceProperties deviceid: CARD8 => nAtoms: CARD16 Atoms: LISTofATOM Errors: Device Each device can store an arbitrary number of properties. These properties can be allocated by either the client or the driver. The client can change device properties and the server guarantees that the device driver is notified about a change of the device's properties. ListDeviceProperties returns all properties of a device. The client is expected to retrieve details about the properties it is interested in separately. 2.23 Getting a Device Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduced with XI 1.5 GetDeviceProperty: property: ATOM type: ATOM longOffset: CARD32 longLength: CARD32 deviceid: CARD8 delete: BOOL => propertyType: ATOM bytesAfter: CARD32 nItems: CARD32 format: CARD8 deviceid: CARD8 data: [LISTofCARD8] Errors: Atom, Device, Value, Access Retrieve the value for a property. If the property does not exist, propertyType is None and all other fields are undefined. If type is not AnyPropertyType and does not match the property's actual type, the propertyType, bytesAfter, and format are returned but not the actual data. longOffset and longLength specify the offset and length respectively in 32-bit multiples of the data to retrieve. If delete is True, the property is deleted after querying its data. If the property cannot be deleted, a BadAccess error is returned. propertyType returns the atom identifier that defines the actual type of the property. If bytesAfter is non-zero, it specifies the number of data 4-byte units after the retrieved chunk of data. format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. This information allows the X server to correctly perform byte-swap operations as necessary. nItem specifies the number of 8-bit, 16-bit, or 32-bit items returned after the request. 2.24 Changing a Device Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduced with XI 1.5 ChangeDeviceProperty: property: ATOM type: ATOM deviceid: CARD8 format: CARD8 mode: CARD8 nUnits: CARD32 Errors: Atom, Device, Value, Match, Access Changes the value of a specified property. The type specifies the atom identifier that defines the type of the property. If mode is not PropModeReplace, the type must match the current type of the property or a BadMatch error is returned. format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. This information allows the X server to correctly perform byte-swap operations as necessary. If mode is PropModeReplace, a preexising value for this property is replaced with the new value. If mode is PropModePrepend or PropModeAppend, the value is prepended or appended, respectively, to the current value of the property. nUnits specifies the number of 8-bit, 16-bit, or 32-bit items supplied after the reply. Changing a device property results in a DevicePropertyNotifyEvent being sent to all clients. 2.25 Deleting a Device Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduced with XI 1.5 DeleteDeviceProperty: property: ATOM deviceid: CARD8 Errors: Atom, Device, Match, Access. Deletes the specified property. If the property cannot be deleted by the client, a BadAccess error is returned. 3. Events --------- 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. 3.1 Button, Key, and Motion Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: state: SETofKEYBUTMASK time: TIMESTAMP 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 DeviceKeyPress and DeviceKeyRelease are generated for all keys, even those mapped to modifier bits. The “source” 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 “event” window. The root is the root window of the “source” 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 “event” 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 X pointer and modifier keys on the core X keyboard just before the event. The detail component type varies with the event type: Event Component DeviceKeyPress KEYCODE DeviceKeyRelease KEYCODE DeviceButtonPress BUTTON DeviceButtonRelease BUTTON DeviceMotionNotify { Normal , Hint } 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 DeviceMotionHint is selected, the server is free to send only one DeviceMotionNotify event (with detail Hint) 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 QueryDeviceState or GetDeviceMotionEvents request. 3.2 DeviceValuator Event ~~~~~~~~~~~~~~~~~~~~~~~~ DeviceValuator device: CARD8 device_state: SETofKEYBUTMASK num_valuators: CARD8 first_valuator: CARD8 valuators: LISTofINT32 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. The device_state component gives the state of the buttons and modifiers on the device generating the event. 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. 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. 3.3 Device Focus Events ~~~~~~~~~~~~~~~~~~~~~~~ DeviceFocusIn DeviceFocusOut device: CARD8 time: TIMESTAMP event: WINDOW mode: { Normal, WhileGrabbed, Grab, Ungrab} detail: { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual, Pointer, PointerRoot, None} These events are generated when the input focus changes and are reported to clients selecting DeviceFocusChange for the specified device and window. Events generated by SetDeviceFocus when the device is not grabbed have mode Normal. Events generated by SetDeviceFocus when the device is grabbed have mode WhileGrabbed. Events generated when a device grab activates have mode Grab, and events generated when a device grab deactivates have mode Ungrab. All DeviceFocusOut events caused by a window unmap are generated after any UnmapNotify event, but the ordering of DeviceFocusOut with respect to generated EnterNotify, LeaveNotify, VisibilityNotify and Expose events is not constrained. DeviceFocusIn and DeviceFocusOut events are generated for focus changes of extension devices in the same manner as focus events for the core devices are generated. 3.4 Device State Notify Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 This event reports the state of the device just as in the QueryDeviceState request. This event is reported to clients selecting DeviceStateNotify for the device and window and is generated immediately after every EnterNotify and DeviceFocusIn. 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. 3.5 Device KeyState and ButtonState Notify Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DeviceKeyStateNotify device: CARD8 keys: LISTofCARD8 DeviceButtonStateNotify device: CARD8 buttons: LISTofCARD8 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. 3.6 DeviceMappingNotify Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DeviceMappingNotify time: TIMESTAMP device: CARD8 request: CARD8 first_keycode: CARD8 count: CARD8 This event reports a change in the mapping of keys, modifiers, or buttons on an extension device. This event is reported to clients selecting DeviceMappingNotify for the device and window and is generated after every client SetDeviceButtonMapping, ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request. 3.7 ChangeDeviceNotify Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ChangeDeviceNotify device: CARD8 time: TIMESTAMP request: CARD8 This event reports a change in the physical device being used as the core X keyboard or X pointer device. ChangeDeviceNotify events are reported to clients selecting ChangeDeviceNotify for the device and window and is generated after every client ChangeKeyboardDevice or ChangePointerDevice request. 3.7 Proximity Events ~~~~~~~~~~~~~~~~~~~~ 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 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. The “source” 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 “event” window. The root is the root window of the “source” 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 “event” 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. 3.8 DevicePresenceEvents ~~~~~~~~~~~~~~~~~~~~~~~~ Introduced with XI 1.4. DevicePresence time: TIMESTAMP devchange: BYTE #x00: DeviceAdded #x01: DeviceRemoved #x02: DeviceEnabled #x03: DeviceDisabled #x04: DeviceUnrecoverable #x05: DeviceControlChanged deviceid: BYTE control: CARD16 DevicePresence 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 ListInputDevices request to obtain the updated list of input devices. DevicePresence events are also sent when a control on the device has been changed. The devchange field specifies the type of operation. In case of DeviceAdded, a new device has been added to the server, but this device does not yet send events. If devchange is set to DeviceEnabled, the device is enabled and will generate events. If the field is DeviceDisabled or DeviceRemoved, the given device is disabled and stops sending events or was removed from the server, respectively. If the field is DeviceUnrecoverable, an IO-error has occured on the device and the device is forcibly disabled and removed by the server. If devchange is DeviceControlChanged, control specifies the type of control that has been changed. 3.9 DevicePropertyNotifyEvent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Introduced with XI 1.5. DevicePropertyNotifyEvent deviceid: CARD8 state: CARD8 time: TIMESTAMP atom: ATOM A DevicePropertyNotifyEvent is sent to all clients when a property on the device is created, deleted, or changes value. The deviceid specifies the device which's property has been modified. The atom specifies the named identifier of the property that has been altered. If state is PropertyNewValue, the given property has a new value or has been newly created. If state is PropertyDeleted, the given property has been deleted. 0707010006236a000081a400000000000000000000000153c4dc3e0001a976000001000001001cffffffffffffffff0000003100000000root/usr/local/share/doc/inputproto/XI2proto.txtThe X Input Extension 2.x ========================= :toclevels: 3 :toc: :numbered: Authors: - Peter Hutterer (Red Hat) - Daniel Stone (Collabora Ltd.) - Chase Douglas (Canonical, Ltd.) [[history]] History ------- - v2.3, December 2012: Pointer barrier events added - v2.2, March 2012: Multitouch support added - v2.1, December 2011: new raw event behaviour, smooth scrolling support added - v2.0, October 2009: Initial release of XI2 protocol [[intro-xi20]] Introduction ------------ The X Input Extension version 2.0 (XI2) is the second major release of the X Input Extension. XI2 provides a number of enhancements over version 1.5, including: - use of XGE and GenericEvents. GenericEvents are of flexible length with a minimum length of 32 bytes. - explicit device hierarchy of master and slave devices. See Section <>. - use of multiple independent master devices (Multi-Pointer X or MPX). - the ability for devices to change capabilities at runtime. - raw device events XI2's intent is to replace both core input processing and prior versions of the X Input Extension. Historically, the majority of applications employed the core protocol requests and events to handle user input. The core protocol does not provide information about which device generated the event. The X Input Extension version up to 1.5 requires the differentiation between core and extended devices. Extended devices may not be core devices and thus cannot be used on applications employing the core protocol. XI2 addresses both of these issues by enabling devices to be both extended and core devices and providing device information in each event (with the exception of core events). Changes in version 2.1 ---------------------- - RawEvents are sent regardless of the grab state. - Addition of the ScrollClass for smooth scrolling Changes in version 2.2 ---------------------- - Multitouch support added Changes in version 2.3 ---------------------- - Pointer barrier events added // ❧❧❧❧❧❧❧❧❧❧❧ Notations used in this document ------------------------------- Notation for requests: ┌─── Name of request name of request field: type of request field name of request field: type of request field ▶ name of reply field: type of reply field └─── Notation for events: ┌─── Name of event name of field: type of field name of field: type of field └─── Complex fields are specified in the following notation: name of field: COMPLEXFIELDTYPE or, if multiple of these fields exist: name of field: LISTofCOMPLEXFIELDTYPE COMPLEXFIELDTYPE: { name of subfield: type of subfield, name of subfield: type of subfield } // ❧❧❧❧❧❧❧❧❧❧❧ Interoperability between version 1.x and 2.0 -------------------------------------------- There is little interaction between 1.x and 2.x versions of the X Input Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as possible. Several direct incompatibilities are observable: [[interop-xi1-limitations]] Limitations resulting from different variable ranges ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XI2 provides a larger range for some fields than XI1. As a result, XI1 clients may not receive data an XI2 client receives. These fields include: - devices with a deviceid of greater than 127 are invisible to XI1 clients. - key events and key grabs featuring larger than 255 can only be sent to XI2 clients. - no subpixel information is available to XI1 clients. If motion events are in a subpixel range only, the server may omit these events and an XI 1.x client will not receive events until the pixel boundary is crossed. [[interop-xi1-grabs]] Blocking of grabs ~~~~~~~~~~~~~~~~~ XI1 grabs are different to XI2 grab and a device may not be grabbed through an XI2 grab if an XI1 grab is currently active on this device or vice versa. Likewise, a keycode or button already grabbed by an XI 1.x or XI2 client may not be grabbed with the same modifier combination by an XI2 or XI 1.x client, respectively. [[interop-xi1-device-list]] Invisibility of Master Devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XI 1.x was not designed with support for multiple master devices. As a result, only the first master pointer and master keyboard are visible to XI 1.x clients; all other master devices are invisible and cannot be accessed from XI 1.x calls. Smooth scrolling ~~~~~~~~~~~~~~~~ Historically, X implemented scrolling events by using button press events: button 4 was one “click” of the scroll wheel upwards, button 5 was downwards, button 6 was one unit of scrolling left, and button 7 was one unit of scrolling right. This is insufficient for e.g. touchpads which are able to provide scrolling events through multi-finger drag gestures, or simply dragging your finger along a designated strip along the side of the touchpad. Newer X servers may provide scrolling information through valuators to provide clients with more precision than the legacy button events. This scrolling information is part of the valuator data in device events. Scrolling events do not have a specific event type. Valuators for axes sending scrolling information must have one ScrollClass for each scrolling axis. If scrolling valuators are present on a device, the server must provide two-way emulation between these valuators and the legacy button events for each delta unit of scrolling. One unit of scrolling in either direction is considered to be equivalent to one button event, e.g. for a unit size of 1.0, -2.0 on an valuator type Vertical sends two button press/release events for button 4. Likewise, a button press event for button 7 generates an event on the Horizontal valuator with a value of +1.0. The server may accumulate deltas of less than one unit of scrolling. Any server providing this behaviour marks emulated button or valuator events with the XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag for raw events, to hint at applications which event is a hardware event. If more than one scroll valuator of the same type is present on a device, the valuator marked with Preferred for the same scroll direction is used to convert legacy button events into scroll valuator events. If no valuator is marked Preferred or more than one valuator is marked with Preferred for this scroll direction, this should be considered a driver bug and the behaviour is implementation-dependent. [[hierarchy]] The Master/Slave device hierarchy --------------------------------- XI2 introduces a device hierarchy split up into so-called Master Devices (MD) and Slave Devices (SD). [[hierarchy-master]] Master devices ~~~~~~~~~~~~~~ An MD is a virtual device created and managed by the server. MDs may send core events and XI events. However, an MD does not represent a physical device and relies on SDs for event generation. MDs come in two forms: as master pointers or as master keyboards. A master pointer is represented by a visible cursor on the screen. A master keyboard is represented by a keyboard focus. Each master pointer is paired with the respective master keyboard and vice versa, and this pairing is constant for the lifetime of both input devices. Clients can use this pairing behaviour to implement input paradigms that require pointer and keyboard interation (e.g. SHIFT + Click). [[hierarchy-slave]] Slave devices ~~~~~~~~~~~~~ An SD is usually a physical device configured in the server. SDs are not represented by a cursor or keyboard focus and may be attached to a master pointer or master keyboard. SDs can only be attached to any master of the same type (e.g. a physical pointer device can be attached to any master pointer). If an event is generated by an SD - if the SD is attached to a master pointer, it changes the position and/or button state of the master pointer. - if the SD has a keyboard focus other than None, the key event is sent to the focus window. - if the SD is attached to a master keyboard, it sends events to this keyboard's focus window (if applicable) and/or changes the modifier state of this keyboard. - if the SD is not attached to an MD ("floating"), it does not change any master device. The SD has its own (invisible) sprite and its own focus. Both the sprite and the focus must be managed explicitly by the client program. Note: the keyboard focus of an attached slave device is independent to that of the master device. Two keyboard events are generated, once with deviceid and sourceid set to the slave device. This keyboard event is sent to the slave device's focus window. The second event has a deviceid of the master and a sourceid of the slave device. This second event is delivered to the master keyboard's focus window. [[hierarchy-dcce]] Event processing for attached slave devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Whenever an SD changes its logical state, - the event is delivered as an XI event to any interested clients. If the device is floating, event processing stops. Otherwise, if the device is attached, - the master device changes its classes to reflect the SD's capabilities. All interested clients are notified of this device change. - then, the event is delivered as an XI event from the MD to any interested clients. If the event has been delivered, event processing stops. Otherwise, - the event is delivered as a core event to any interested clients. Given that W is the event window, and P the parent window of W, event delivery to P is only attempted if neither the XI event, nor the core event has been delivered on W. Once an event has been delivered as either XI or core event, event processing stops. [[clientpointer]] The ClientPointer principle ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Many core protocol and some extension requests are ambiguous when multiple master devices are available (e.g. QueryPointer does not specify which pointer). The X server does not have the knowledge to chose the contextually correct master device. For each client, one master pointer is designated as this clients's "ClientPointer". Whenever a client sends an ambiguous request (e.g. QueryPointer), the ClientPointer or the keyboard paired with the ClientPointer is chosen to provide the data for this request. This ClientPointer may be explicitly assigned to a client with the SetClientPointer call. If no ClientPointer is set when a client issues an ambiguous request, the server choses one device as the ClientPointer. The method of chosing a ClientPointer from the available master pointers is implementation-specific. If the master pointer currently set as ClientPointer for one or more clients is removed, the server may either unset the ClientPointer setting or change the ClientPointer to a different master pointer. [[multitouch]] Touch device support -------------------- XI 2.2 introduces support for multi-touch devices. The traditional pointer/keyboard approach enforced by XI 2.0 with the master/slave device hierarchy is not always suitable for multi-touch devices that can provide a dynamic number of touchpoints per physical device; it is not known without client-specific interpretation whether the touchpoints must be considered separately or grouped together. The additions in XI 2.2 aim to: - support a dynamic number of simultaneous touch points, - support devices that are both multi-touch and traditional pointer devices, - allow touchpoints to be either grouped together or handled separately, - be backwards-compatible to pre-XI 2.2 clients through emulation of XI 2.x/XI 1.x and core pointer events. Touch events are only available to clients supporting version 2.2 or later of the X Input Extension. Clients must use the XIQueryVersion request to announce support for this version. Touch devices may generate emulated pointer events alongside XI 2.2 touch events to support older clients; see Section <>. Touch event processing differs from normal event processing in a few ways. The most notable differences are that touch events are processed partially out-of-band from pointer and keyboard events, and that touch events may be sent to multiple clients simultaneously. For more details see Section <>. [[multitouch-lifecycle]] Touch event sequences ~~~~~~~~~~~~~~~~~~~~~ Touch input follows a three-stage cycle: begin - update - update - ... - end i.e. “begin” the sequence by touching the device, “update” the current touch location or properties any number of times, and finally “end” the sequence by ceasing to touch the device. Within this document, the term "touch sequence" is used to describe the above sequence of events. In the protocol, the three stages are represented with the event types TouchBegin, TouchUpdate, and TouchEnd, respectively. A touch sequence always generates TouchBegin and TouchEnd events, and may also generate TouchUpdate events. Clients must select for all three of these events simultaneously. When a touch starts, clients are sent a TouchBegin event detailing the position of the touchpoint, as well as the initial properties of the touchpoint. Note that the logical state of the device (as seen through the input protocol) may lag the physical state if event processing is affected by grabs. Multiple touchpoints may be active on the same device at any time, potentially owned by and/or delivered to a different set of clients. Whenever the touch position or any other property of the touchpoint changes, a TouchUpdate event is sent to all clients listening to events for that touchpoint with the updated information. When the touch has physically ended, or a client will otherwise not receive any more events for a given touchpoint, a TouchEnd event will be sent to that client. Passive touch grabs are similar to standard input event grabs in that they take precedence over event selections and are searched from the root window to the child window (as opposed to selections, which start their search at the child window and continue up to the root window). When a touch grab activates, the client whose grab activates becomes the “owner” of this touch sequence, and must decide what to do with it, as per Section <>. See the <> request documentation for more information on passive grab activation. Only one client may select for touch events from a given device on a window. [[multitouch-ownership]] Ownership of touch sequences ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once a grabbing client becomes the owner of a touch, it must either “accept” or "reject" the touch sequence using the XIAllowEvents request. If a touch sequence is rejected, a TouchEnd event is sent to the rejecting client, and it will not receive any more events for this touch. The server then looks to the next window in the stack for another passive grab, and attempts to pass ownership on to the next candidate for a passive grab (i.e. the next window towards the final child window with a matching grab), or to the first applicable event selection if there are no more grabs. If a touch sequence is accepted by its owner, all other clients receive TouchEnd events, and the touch sequence is exclusively delivered to the owner from that point on. If the touch sequence physically ends while the owner of the touch sequence has not yet accepted or rejected ownership, the owner receives a TouchEnd event and all other clients receive a TouchUpdate event with the TouchPendingEnd flag set. The owner must still accept or reject the sequence nonetheless. If the owner rejects the touch sequence, the server will still attempt to exhaust all other passive grabs and/or event selections looking for a final owner. If the touch sequence has not physically ended yet and the owner of the touch sequence rejects, the owner receives a TouchEnd event and ownership is passed to the next client. Clients may opt for touch events to be delivered before they become the owner of the touch sequence. In this case, the logical state of the device (as seen by means of the protocol) always matches the physical state of the device. Clients must use caution if they opt for this feature; any action taken must be undone if the touch sequence ends without the client becoming the owner. To select for touch events regardless of ownership, a client must set the TouchOwnership event mask in addition to the TouchBegin, TouchUpdate and TouchEnd mask. When selected, a client will receive touch events as they occur on the device. If and when the client becomes the owner of a touch sequence, a TouchOwnership event is sent to the client. If the client is the initial owner of the sequence, the TouchBegin is immediately followed by the TouchOwnership event. Otherwise, TouchUpdate events may preceed a TouchOwnership event. A client is not guaranteed to become the owner of any given touch sequence. The server delivers touch events to all clients that have selected for TouchOwnership and to the current owner of the sequence in parallel. If a client has selected for TouchOwnership and is not the current owner of the sequence and the current owner accepts the sequence, the client receives a TouchEnd event and no further events from this sequence are sent to this client. If a client has selected for TouchOwnership and the physical touch ends before the current owner has accepted or rejected the sequence, the client receives a TouchUpdate event with the TouchPendingEnd flag set. No further TouchUpdate events will be sent for this sequence. If the current owner accepts the sequence, the client receives a TouchEnd event. Otherwise, if the current owner rejects the sequence, the client may become the owner of the touch sequence and receive a TouchOwnership event and a TouchEnd event. [[multitouch-device-modes]] Touch device modes ~~~~~~~~~~~~~~~~~~ Touch devices come in many different forms with varying capabilities. The following device modes are defined for this protocol: 'DirectTouch': These devices map their input region to a subset of the screen region. Touch events are delivered to window at the location of the touch. "direct" here refers to the user manipulating objects at their screen location. An example of a DirectTouch device is a touchscreen. 'DependentTouch': These devices do not have a direct correlation between a touch location and a position on the screen. Touch events are delivered according to the location of the device's cursor and often need to be interpreted relative to the current position of that cursor. Such interactions are usually the result of a gesture performed on the device, rather than direct manipulation. An example of a DependentTouch device is a trackpad. A device is identified as only one of the device modes above at any time, and the touch mode may change at any time. If a device's touch mode changes, an XIDeviceChangedEvent is generated. [[multitouch-processing]] Touch event delivery ~~~~~~~~~~~~~~~~~~~~ For direct touch devices, the window set for event propagation is the set of windows from the root window to the topmost window lying at the co-ordinates of the touch. For dependent devices, the window set for event propagation is the set of windows from the root window to the window that contains the device's pointer. A dependent device may only have one window set at a time, for all touches. Any future touch sequence will use the same window set. The window set is cleared when all touch sequences on the device end. A window set is calculated on TouchBegin and remains constant until the end of the sequence. Modifications to the window hierarchy, new grabs or changed event selection do not affect the window set. Pointer control of dependent devices ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On a dependent device, the device may differ between a pointer-controlling touch and a non-pointer-controlling touch. For example, on a touchpad the first touch is pointer-controlling (i.e. serves only to move the visible pointer). Multi-finger gestures on a touchpad cause all touches to be non-pointer-controlling. For pointer-controlling touches, no touch events are sent; the touch generates regular pointer events instead. Non-pointer-controlling touches send touch events. A touch may change from pointer-controlling to non-pointer-controlling, or vice versa. - If a touch changes from pointer-controlling to non-pointer-controlling, a new touch ID is assigned and a TouchBegin is sent for the last known position of the touch. Further events are sent as TouchUpdate events, or as TouchEnd event if the touch terminates. - If a touch changes from non-pointer-controlling to pointer-controlling, a TouchEnd is sent for that touch at the last known position of the touch. Further events are sent as pointer events. The conditions to switch from pointer-controlling to non-pointer-controlling touch is implementation-dependent. A device may support touches that are both pointer-controlling and a touch event. In the dependent touch example event sequence below, touches are marked when switching to pointer-controlling (pc) or to non-pointer-controlling (np). .Dependent touch example event sequence on a touchpad [width="50%", options="header"] |==================================================== | Finger 1 | Finger 2 | Event generated(touchid) | down | | Motion | move | | Motion | move | | Motion | (np) | down | TouchBegin(0), TouchBegin(1) | move | -- | TouchUpdate(0) | -- | move | TouchUpdate(1) | up | (pc) | TouchEnd(0), TouchEnd(1) | | move | Motion | down | (np) | TouchBegin(2), TouchBegin(3) | move | -- | TouchUpdate(2) | up | (pc) | TouchEnd(2), TouchEnd(3) | | up | Motion | down | | Motion | (np) | down | TouchBegin(4), TouchBegin(5) | (pc) | up | TouchEnd(4), TouchEnd(5) | move | | Motion | up | | Motion |==================================================== [[multitouch-emulation]] Pointer emulation from multitouch events ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Touch sequences from direct touch devices may emulate pointer events. Only one touch sequence from a device may emulate pointer events at a time; which touch sequence emulates pointer events is implementation-dependent. Pointer events are emulated as follows: - A TouchBegin event generates a pointer motion event to the location of the touch with the same axis values of the touch event, followed by a button press event for button 1. - A TouchUpdate event generates a pointer motion event to the location of the touch and/or to update axis values of the pointer device. The button state as seen from the protocol includes button 1 set. - A TouchEnd event generates a pointer motion event to the location of the touch and/or to update the axis values if either have changed, followed by a button release event for button 1. The button state as seen from the protocol includes button 1 set. If a touch sequence emulates pointer events and an emulated pointer event triggers the activation of a passive grab, the grabbing client becomes the owner of the touch sequence. The touch sequence is considered to have been accepted if - the grab mode is asynchronous, or - the grab mode is synchronous and the device is thawed as a result of AllowEvents with AsyncPointer or AsyncDevice Otherwise, if the button press is replayed by the client, the touch sequence is considered to be rejected. Touch event delivery precedes pointer event delivery. A touch event emulating pointer events is delivered: - as a touch event to the top-most window of the current window set if a client has a touch grab on this window, - otherwise, as a pointer event to the top-most window of the current window set if a client has a pointer grab on this window, - otherwise, to the next child window in the window set until a grab has been found. If no touch or pointer grab on any window is active and the last window in the window set has been reached, the event is delivered: - as a touch event to the window if a client has selected for touch events on this window - otherwise, as a pointer event to the window if a client has selected for pointer events. - otherwise, to the next parent window in the window set until a selection has been found. Emulated pointer events will have the PointerEmulated flag set. A touch event that emulates pointer events has the TouchEmulatingPointer flag set. [[barrier-events]] Pointer barrier events ^^^^^^^^^^^^^^^^^^^^^^ If a master pointer moves against a pointer barrier blocking movement in that pointer's direction, the movement of the pointer is clamped to the x or y coordinate of the barrier, whichever applies. For a description of pointer barriers and barrier creation and destruction see the XFixes protocol specification v 5.0 or later. http://cgit.freedesktop.org/xorg/proto/fixesproto/plain/fixesproto.txt A pointer hitting a blocking barrier creates a new barrier event sequence, identified by a unique event ID. A new event ID is assigned when the pointer first hits a barrier. Subsequent movements against or along the pointer barrier are assigned the same event ID. The event generated by the pointer leaving the barrier, or being released by a client request, is the last event with this event ID. Any future movements of this device blocked by this barrier will be assigned a new event ID. Pointer barrier events are delivered exclusively to the client that created the barrier, and to the window specified in the CreatePointerBarrier request (the "barrier window"). A pointer barrier blocks pointer movement regardless of whether its window is mapped and/or viewable. If the pointer barrier window is destroyed, the pointer barrier remains blocking but a client will not receive further events. If a device is actively grabbed by a client or a passive grab activated for this client, and the pointer moves against a pointer barrier created by this client and the grab-window is the barrier window, that client will receive pointer barrier events if: - owner-events is true or false and the grab's event mask includes pointer barrier events, or - owner-events is true and the client has selected for barrier events on the barrier window. If the grab-window is not the barrier window, the client will receive events if: - the client has selected for barrier events on the barrier window. If the barrier is not owned by this client, no barrier events are sent to this client. The client owning the barrier will receive events if: - the client has pointer barrier events selected on the window associated with the pointer barrier The BarrierDeviceIsGrabbed flag is set whenever a pointer barrier event is generated while the device is actively grabbed by any client or a passive grab has activated for this device prior to the event. [[glossary-notations]] Notations used in this document ------------------------------- Notation for requests: ┌─── Name of request name of request field: type of request field name of request field: type of request field ▶ name of reply field: type of reply field └─── Notation for events: ┌─── Name of event name of field: type of field name of field: type of field └─── Complex fields are specified in the following notation: name of field: COMPLEXFIELDTYPE or, if multiple of these fields exist: name of field: LISTofCOMPLEXFIELDTYPE COMPLEXFIELDTYPE: { name of subfield: type of subfield, name of subfield: type of subfield } [[glossary-datatypes]] Data types ---------- BUTTONMASK A binary mask defined as (1 << button number). A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK. DEVICE { DEVICEID, AllDevices, AllMasterDevices } A DEVICE specifies either a DEVICEID or AllDevices or AllMasterDevices. DEVICEID { CARD16 } A DEVICEID is a numerical ID for a device currently available in the server. The server may re-use a device ID after a device's removal. The device IDs 0 and 1 are reserved. AllDevices ........ 0 AllMasterDevices .. 1 DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer, SlaveKeyboard, FloatingSlave } A DEVICEUSE field specifies the current use of a device in the MD/SD device hierarchy. See Section "The Master/Slave device hierarchy" for more information. EVENTMASK An EVENTMASK is a binary mask defined as (1 << event type). A SETofEVENTMASK is a binary OR of zero or more EVENTMASK. FP1616 Fixed point decimal in 16.16 format as one INT16 and one CARD16. The INT16 contains the integral part, the CARD16 the decimal fraction shifted by 16. FP3232 Fixed point decimal in 32.32 format as one INT32 and one CARD32. The INT32 contains the integral part, the CARD32 the decimal fraction shifted by 32. MODIFIERMASK A MODIFIERMASK is a binary mask defined as (1 << modifier map index). A SETofMODIFIERMASK is a binary OR of zero or more MODIFIERMASK or GrabAnyModifier. VALUATORMASK A binary mask defined as (1 << valuator number). A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK. [[errors]] Errors ------ Errors are sent using core X error reports. Device A value for a DEVICE argument does not specify a valid DEVICE. [[requests]] Requests -------- The server does not guarantee that the length of a reply remains constant in future revisions of XI2. A client must always retrieve the exact length of the protocol reply from the connection, even if the reply is longer than defined for the XI2 version supported by the client. Additional bytes in a request may include data supported in later versions of XI2. Clients should ignore this data. Padding bytes in XI2 protocol requests are required to be 0. [[requests-xi20]] Requests introduced in version 2.0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[requests-queryversion]] XIQueryVersion ^^^^^^^^^^^^^^ ┌─── XIQueryVersion major_version: CARD16 minor_version: CARD16 ▶ major_version: CARD16 minor_version: CARD16 └─── The client sends the highest supported version to the server and the server sends the highest version it supports, but no higher than the requested version. Major versions changes can introduce incompatibilities in existing functionality, minor version changes introduce only backward compatible changes. It is the client's responsibility to ensure that the server supports a version which is compatible with its expectations. major_version Major XI2 version. minor_version Minor XI2 version. If major_version is less than 2, a BadValue error occurs. [[requests-querydevice]] XIQueryDevice ^^^^^^^^^^^^^ ┌─── XIQueryDevice DEVICE deviceid ▶ num_devices: CARD16 deviceinfo: LISTofDEVICEINFO └─── DEVICEINFO { deviceid: DEVICEID use: DEVICEUSE attachment: DEVICEID enabled: BOOL num_classes: CARD16 name_len: CARD16 name: LISTofCHAR8 classes: LISTofCLASS } CLASS { BUTTONCLASS, KEYCLASS, VALUATORCLASS, SCROLLCLASS, TOUCHCLASS } BUTTONCLASS { type: ButtonClass length: CARD16 sourceid: CARD16 num_buttons: CARD16 state: SETofBUTTONMASK labels: LISTofATOM } KEYCLASS { type: KeyClass length: CARD16 sourceid: CARD16 num_keys: CARD16 keys: LISTofCARD32 } VALUATORCLASS { type: ValuatorClass length: CARD16 sourceid: CARD16 number: CARD16 label: ATOM min: FP3232 max: FP3232 value: FP3232 resolution: CARD32 mode: CARD8 } SCROLLCLASS¹ { type: ScrollClass length: CARD16 sourceid: CARD16 number: CARD16 scroll_type: SCROLLTYPE flags: SETofSCROLLFLAGS increment: FP3232 } SCROLLTYPE { Vertical, Horizontal } SCROLLFLAGS { NoEmulation, Preferred } TOUCHCLASS² { type: TouchClass length: CARD16 sourceid: CARD16 mode: TOUCHMODE num_touches: CARD16 } TOUCHMODE { DirectTouch, DependentTouch } ¹ since XI 2.1 ² since XI 2.2 XIQueryDevice details information about the requested input devices. devices The device to list. If devices is AllDevices, all enabled and disabled devices are listed. If devices is AllMasterDevices, all enabled and disabled master devices are listed. If devices is a valid DEVICE, only this DEVICE is listed and num_devices is 1. num_devices The number of deviceinfos returned. Each deviceinfo is detailed as follows: deviceid The unique ID of the device. Device IDs may get re-used when a device is removed. use If the device is a master pointer, use is MasterPointer. If the device is a master keyboard, use is MasterKeyboard. If the device is a slave pointer, use is SlavePointer. If the device is a slave keyboard, use is SlaveKeyboard. If the device is a floating slave, use is FloatingSlave. attachment If the device is a master pointer or a master keyboard, attachment specifies the paired master keyboard, or the paired master pointer, respectively. If the device is a non-floating slave device attachment specifies the master device this device is attached to. If the device is a floating slave, attachment is undefined. enabled Zero if the device is disabled, non-zero otherwise. num_classes Number of classes provided. name_len Length of the name in bytes not including padding. classes Details the available classes provided by the device in an undefined order. name The device's name. padded to a multiple of 4 bytes. For all classes, type specifies the device class. Clients are required to ignore unknown device classes. The length field specifies the length of the class in 4 byte units. The following classes may occur only once: ButtonClass, KeyClass ButtonClass: type Always ButtonClass. length Length in 4 byte units. sourceid The device this class originates from. num_buttons Number of buttons provided by the device. labels List of Atoms specifying the label for each button. An Atom of None specifies an unlabeled button. Buttons are listed in the device-native order regardless of the current button mapping. state The current button mask for this device after button mapping is applied. Each bit representing a button is 1 if this button is logically down, or 0 otherwise. State is a multiple of 4-byte units and always contains at least num_buttons bits. KeyClass: type Always KeyClass. length Length in 4 byte units. sourceid The device this class originates from. num_keys Number of keycodes provided by the device. keys List of keycodes provided. ValuatorClass: type Always ValuatorClass. length Length in 4 byte units. sourceid The device this class originates from. number Valuator number of this axis. The valuator number is in device-native order and potential axis mappings are ignored. label Atom specifying the axis name. An Atom of None specifies an unlabeled axis. min Minimum value. max Minimum value. resolution Resolution in counts/meter. mode Relative or Absolute. value Last published axis value (if mode is absolute). An axis in Relative mode may specify min and max as a hint to the client. If no min and max information is available, both must be 0. ScrollClass: type Always ScrollClass. number Valuator number that is referred to. This valuator number must be listed in the ValuatorClassInfo. scroll_type: Vertical for a vertical scrolling axis, Horizontal for a horizontal scrolling axis. flags: A set of flags that apply to this scroll axis. NoEmulation: no legacy scroll button events are generated for events on this scrolling axis. Preferred: This axis is the preferred axis for emulating valuator events from legacy scroll button events. increment: The valuator delta equivalent to one positive unit of scrolling. A ScrollClass may only exist if the device has at least one ValuatorClass and each valuator number listed in any ScrollClass. Only one ScrollClass may exist per ValuatorClass. TouchClass: type Always TouchClass. length Length in 4 byte units. sourceid The device this class originates from. mode The device type of the touch device. This mode may change at runtime. num_touches The maximum number of simultaneous touchpoints the device may send. If num_touches is 0, the number of supported touches is unknown or unlimited. Devices with a TouchClass emit touch events with the same axes as pointer events. [[requests-selectevents]] XISelectEvents ^^^^^^^^^^^^^^ ┌─── XISelectEvents window: Window num_masks: CARD16 masks: LISTofEVENTMASK └─── EVENTMASK { deviceid: DEVICE, mask_len: CARD16, mask: SETofEVENTMASK window The window to select the events on. num_masks Number of items in masks. deviceid Numerical deviceid, or AllDevices, or AllMasterDevices. mask_len Length of mask in 4 byte units. mask Event mask. An event mask for an event type T is defined as (1 << T). XISelectEvents selects for XI2 events on window. If num_masks is 0, a BadValue error occurs. Each mask sets the (and overwrites a previous) event mask for the DEVICE specified through deviceid. The device AllDevices or AllMasterDevices is treated as a separate device by server. A client's event mask is the union of AllDevices, AllMasterDevices and the per-device event mask. The removal of device from the server unsets the event masks for the device. If an event mask is set for AllDevices or AllMasterDevices, the event mask is not cleared on device removal and affects all future devices. If mask_len is 0, the event mask for the given device is cleared. The mask for XIHierarchyEvents may only be selected for XIAllDevices. Setting it for any other device results in a BadValue error. A client selecting for any of XI_TouchBegin, XI_TouchUpdate, or XI_TouchEnd must select for all three events at the same time, else a BadValue error will be generated. A client selecting for XI_TouchOwnership must select for all three of the other touch events. If the selection for these touch events overlaps a current selection by another client (e.g. selecting for a specific device when another client has a selection for XIAllDevices), a BadAccess error occurs. [[requests-getselectedevents]] XIGetSelectedEvents ^^^^^^^^^^^^^^^^^^^ ┌─── XIGetSelectedEvents window: Window ▶ num_masks: CARD16 masks: LISTofEVENTMASK └─── window The window to select the events on. num_masks Number of items in masks. masks Selected event masks by this client. Masks are returned on a per-device basis, with masks for AllDevices and AllMasterDevices returned separately. A client can calculate the effective mask for a device with a bitwise OR of the AllDevices, the AllMasterDevices and the device-specific mask. If num_masks is 0, no events have been selected by this client on the given window. [[requests-querypointer]] XIQueryPointer ^^^^^^^^^^^^^^ ┌─── XIQueryPointer window: Window deviceid: DEVICEID ▶ root: Window child: Window root_x: FP1616 root_y: FP1616 win_x: FP1616 win_y: FP1616 same_screen: BOOL mods: MODIFIERINFO group: GROUPINFO buttons_len: CARD16 buttons: SETofBUTTONMASK └─── Query a master pointer device for its current position. root The root window the pointer is logically on. child The child window of window that contains the pointer or None. root_x root_y Pointer position relative to the root window's origin. win_x win_y Pointer position relative to window or 0 if same_screen is false. same_screen True if window is on the same screen as the pointer. mods XKB modifier state on the paired device. group XKB group state on the paired device. buttons_len The length of buttons in 4 byte units. buttons Button state. If the device is not a master pointer device or not a floating slave pointer, a BadDevice error results. [[requests-warppointer]] XIWarpPointer ^^^^^^^^^^^^^ ┌─── XIWarpPointer src_win: Window dst_win: Window src_x: FP1616 src_y: FP1616 src_width: INT16 src_height: INT16 dst_x: FP1616 dst_y: FP1616 deviceid: DEVICEID └─── WarpPointer moves the pointer of deviceid as if the user had moved the pointer. WarpPointer can only be called for MasterPointer and FloatingSlave devices. src_win If src_window is not None, the move only takes place if src_window contains the pointer and the pointer is contained in the specified rectangle of src_window. dst_win If dst_win is None, this request moves the pointer by offsets dst_x/dst_y relative to the current position of the pointer. If dst_window is a window, this request moves the pointer to dst_x/dst_y relative to dst_win's origin. src_x src_y src_width src_height Specifies the source window rectangle. dst_x dst_y The relative coordinates to move the pointer if dst_win is None, or the absolute coordinates if dst_win is a window. deviceid The device to warp. This request cannot be used to move the pointer outside the confine-to window of an active pointer grab. An attempt will only move the pointer as far as the closest edge of the confine-to window. This request will generate events just as if the user had instantaneously moved the pointer. [[requests-changecursor]] XIChangeCursor ^^^^^^^^^^^^^^ ┌─── XIChangeCursor win: Window cursor: Cursor deviceid: DEVICEID └─── Change a master pointer's cursor on the specified window. window The window. cursor The new cursor or None. deviceid The master pointer device. Whenever device enters a window W, the cursor shape is selected in the following order: - if the current window has a device cursor C(d) defined for device, display this cursor C(d). - otherwise, if the current window has a cursor C(w) defined in the core protocol's window attributes, display cursor C(w). - repeat on parent window until a cursor has been found. The device cursor for a given window is reset once the window is destroyed or the device is removed, whichever comes earlier. If deviceid does not specify a master pointer, a BadDevice error is returned. [[requests-changehierarchy]] XIChangeHierarchy ^^^^^^^^^^^^^^^^^ ┌─── XIChangeHierarchy num_changes: CARD8 changes: LISTofHIERARCHYCHANGES └─── HIERARCHYCHANGE { ADDMASTER, REMOVEMASTER, ATTACHSLAVE, DETACHSLAVE } HIERARCHYCHANGETYPE { AddMaster, RemoveMaster, AttachSlave, DetachSlave } CHANGEMODE { Float, Attach } ADDMASTER { type: HIERARCHYCHANGETYPE length: CARD16 name_len: CARD16 send_core: BOOL enable: BOOL name: LISTofCHAR8 } REMOVEMASTER { type: HIERARCHYCHANGETYPE length: CARD16 deviceid: DEVICEID return_mode: CHANGEMODE return_pointer: DEVICEID return_keyboard: DEVICEID } ATTACHSLAVE { type: HIERARCHYCHANGETYPE length: CARD16 deviceid: DEVICEID master: DEVICEID } DETACHSLAVE { type: HIERARCHYCHANGETYPE length: CARD16 deviceid: DEVICEID } XIChangeHierarchy allows a client to modify the <>. num_changes The number of changes to apply to the current hierarchy. changes The list of changes. The server processes the changes in the order received from the client and applies each requested change immediately. If an error occurs, processing stops at the current change and returns the number of successfully applied changes in the error. ADDMASTER creates a pair of master devices. type Always AddMaster. length Length in 4 byte units. name_len Length of name in bytes. send_core True if the device should send core events. enable True if the device is to be enabled immediately. name The name for the new master devices. The master pointer's name is automatically appended with " pointer", the master keyboard's name is automatically appended with " keyboard". REMOVEMASTER removes an existing master device. type Always RemoveMaster. length Length in 4 byte units. deviceid The device to remove. return_mode Return mode for attached slave devices. If return_mode is Float, all slave devices are set to floating. If return_mode is Attach, slave pointers are attached to return_pointer and slave keyboards are attached to return_keyboard. return_pointer return_keyboard The master pointer and master keyboard to attach slave devices to, if return_mode is Attach. If return_mode is Float, return_pointer and return_keyboard are undefined. Removing a master pointer removes the paired master keyboard and vice versa. ATTACHSLAVE attaches a slave device to a given master device. type Always ChangeAttachment. length Length in 4 byte units. deviceid Deviceid of the slave device. master The new master device to attach this slave device to. If any clients are selecting for touch events from the slave device, their selection will be canceled. DETACHSLAVE detaches a slave device from its current master device. type Always ChangeAttachment. length Length in 4 byte units. deviceid Deviceid of the slave device. [[requests-setclientpointer]] XISetClientPointer ^^^^^^^^^^^^^^^^^^ ┌─── XISetClientPointer win: Window deviceid: DEVICEID └─── Set the ClientPointer for the client owning win to the given device. win Window or client ID. deviceid The master pointer or master keyboard that acts as ClientPointer. Some protocol requests are ambiguous and the server has to choose a device to provide data for a request or a reply. By default, the server will choose a client's ClientPointer device to provide the data, unless the client currently has a grab on another device. See section <> for more details. If win is None, the ClientPointer for this client is set to the given device. Otherwise, if win is a valid window, the ClientPointer for the client owning this window is set to the given device. Otherwise, if win is not a valid window but a client with the client mask equal to win exists, this client's ClientPointer is set to the given device. If deviceid does not specify a master pointer or master keyboard, a BadDevice error is returned. If window does not specify a valid window or client ID and is not None, a BadWindow error is returned. [[requests-getclientpointer]] XIGetClientPointer ^^^^^^^^^^^^^^^^^^ ┌─── XIGetClientPointer win: Window ▶ set: BOOL deviceid: DEVICEID └─── Query the ClientPointer for the client owning win. win The window or client ID. set True if the client has a ClientPointer set. deviceid The master pointer that acts as a ClientPointer if set is True. No difference is made between a ClientPointer set explicitly through XISetClientPointer and a ClientPointer implicitly assigned by the server in response to an ambiguous request. [[requests-setfocus]] XISetFocus ^^^^^^^^^^ ┌─── XISetFocus focus: Window deviceid: DEVICEID time: Time └─── Set the focus for the given device to the given window. Future key events from this device are sent to this window. This request generates FocusIn and FocusOut events. focus A viewable window or None. deviceid The device to modify the focus window for. time Specifies the time to change the focus or CurrentTime. If focus is None, key events from this device are discarded until a new focus window is set. If focus is a viewable window, key events from this device are sent to this window. If the window becomes unviewable, the window's first viewable ancestor automatically becomes the focus window and FocusIn and FocusOut events are sent as if a client had changed the focus window. This is equivalent to RevertToParent in the core XSetInputFocus window. This request has no effect if the specified time is earlier than the current last-focus-change time or is later than the current X server time. Otherwise, the last-focus-change time is set to the specified time. [[requests-getfocus]] XIGetFocus ^^^^^^^^^^ ┌─── XIGetFocus deviceid: DEVICEID ▶ focus: Window └─── Return the current focus window for the given device. [[requests-grabdevice]] XIGrabDevice ^^^^^^^^^^^^ ┌─── XIGrabDevice deviceid: DEVICEID grab_window: Window owner_events: BOOL grab_mode: { Synchronous, Asynchronous } paired_device_mode: { Synchronous, Asynchronous } time: TIMESTAMP or CurrentTime cursor: Cursor mask_len: CARD16 masks: SETofEVENTMASK ▶ status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable └─── 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 overides any previous active grab by this client for this device. This request does not affect the processing of XI 2.2 touch events. deviceid The device to grab. grab_window Events are reported relative to the grab window. owner_events Specifies whether event will be reported normally or relative to the grab window. grab_mode Specifies if this device will be frozen as a result of the grab. paired_device_mode Specifies if the master device paired with this device will be frozen as a result of the grab. time A valid server time or CurrentTime. cursor The cursor to display for the duration of the grab or None. mask_len Length of mask in 4 byte units. mask Event mask. An event mask for an event type T is defined as (1 << T). status Success or the reason why the grab could not be established. The masks parameter specifies which events the client wishes to receive while the device is grabbed. If owner-events is False, 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 True, 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. If grab-mode is Asynchronous, device event processing continues normally. If the device is currently frozen by this client, then processing of device events is resumed. If grab-mode is Synchronous, 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 XIAllowEvents 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. If the device is a slave device, the paired-device-mode is ignored. Otherwise, if this device is a master device and paired-device-mode is Asynchronous, event processing is unaffected by activation of the grab. If this device is a master device and paired-device-mode is Synchronous, the state of the master device paired with this device (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 XIAllowEvents 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. If the cursor is not None and the device is a master pointer device, the cursor will be displayed until the device is ungrabbed. This request fails and returns: AlreadyGrabbed: If the device is actively grabbed by some other client. NotViewable: If grab-window is not viewable. InvalidTime: 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 CurrentTime is replaced by the current X server time. Frozen: If the device is frozen by an active grab of another client. To release a grab of a device, use XIUngrabDevice. [[requests-ungrabdevice]] XIUngrabDevice ^^^^^^^^^^^^^^ ┌─── XIUngrabDevice deviceid: DEVICEID time: TIMESTAMP or CurrentTime └─── This request releases the device if this client has it actively grabbed (from either XIGrabDevice or XIPassiveGrabDevice) and releases any queued events. If any devices were frozen by the grab, XIUngrabDevice thaws them. deviceid The device to grab. time A valid server time or CurrentTime. 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. This request generates FocusIn and FocusOut events. An XIUngrabDevice is performed automatically if the event window for an active device grab becomes not viewable. [[requests-allowevents]] XIAllowEvents ^^^^^^^^^^^^^ ┌─── XIAllowEvents deviceid: DEVICEID time: TIMESTAMP or CurrentTime event_mode: { AsyncDevice, SyncDevice, AsyncPairedDevice, SyncPairedDevice, ReplayDevice, AsyncPair, SyncPair, AcceptTouch¹, RejectTouch¹ } touchid¹: CARD32 grab_window¹: Window └─── ¹ since XI 2.2 The XIAllowEvents request releases some queued events if the client has caused a device to freeze. It also is used to handle touch grab and ownership processing. deviceid The device to grab. time A valid server time or CurrentTime. event_mode Specifies whether a device is to be thawed and events are to be replayed, or how to handle a grabbed touch sequence. touchid The ID of the touch sequence to accept or reject. The value is undefined for event modes other than AcceptTouch and RejectTouch. grab_window The window on which to accept or reject a touch sequence grab. The value is undefined for event modes other than AcceptTouch and RejectTouch. 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. The time parameter must be CurrentTime for requests with event modes of AcceptTouch and RejectTouch. When event-mode is AcceptTouch, a BadValue error occurs if the touch ID is invalid. A BadAccess error occurs if this client is not the current or potential owner of the specified touch ID. The following describes the processing that occurs depending on what constant you pass to the event-mode argument: AsyncDevice: 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, AsyncDevice thaws for all. AsyncDevice has no effect if the specified device is not frozen by the client, but the device need not be grabbed by the client. SyncDevice: If the specified device is frozen and actively grabbed by the client, event processing for that device continues normally until the next 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. SyncDevice has no effect if the specified device is not frozen by the client or is not grabbed by the client. ReplayDevice: 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 XIGrabButton or from a previous XIAllowEvents with mode SyncDevice, 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. AsyncPairedDevice If the paired master device is frozen by the client, event processing for it continues as usual. If the paired device is frozen multiple times by the client on behalf of multiple separate grabs, AsyncPairedDevice thaws for all. AsyncPairedDevice has no effect if the device is not frozen by the client, but those devices need not be grabbed by the client. AsyncPairedDevice has no effect if deviceid specifies a slave device. SyncPairedDevice If the paired master device is frozen by the client, event processing (for the paired master device) continues normally until the next button or key event is reported to the client for the grabbed device (button event for the grabbed device, key or motion event for the device), at which time the device again appears to freeze. However, if the reported event causes the grab to be released, then the device does not freeze. SyncPairedDevice has no effect if the specified device is not grabbed by the client or if it is no frozen as the result of an event. SyncPairedDevice has no effect if deviceid specifies a slave device. SyncPair If both the device and the paired master device are frozen by the client, event processing (for both devices) continues normally until the next XIButtonPress, XIButtonRelease, XIKeyPress, or XIKeyRelease event is reported to the client for a grabbed device (button event for a pointer, key event for a keyboard), 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 the other device is still grabbed, then a subsequent event for it will still cause both devices to freeze). SyncPair has no effect unless both the device and the paired master device are frozen by the client. If the device or paired master device is frozen twice by the client on behalf of two separate grabs, SyncPair thaws for both (but a subsequent freeze for SyncPair will only freeze each device once). SyncPair has no effect if deviceid specifies a slave device. AsyncPair If the device and the paired master device are frozen by the client, event processing for both devices continues normally. If a device is frozen twice by the client on behalf of two separate grabs, AsyncBoth thaws for both. AsyncPair has no effect unless both the device and the paired master device frozen by the client. AsyncPair has no effect if deviceid specifies a slave device. AcceptTouch The client is deemed to have taken control of the touch sequence once it owns the sequence. TouchEnd events will be sent to all clients listening to the touch sequence that have either grabbed the touch sequence on a child window of the grab_window or have received events for the touch sequence through event selection. These clients will no longer receive any TouchUpdate events. RejectTouch The client is no longer interested in the touch sequence, and will receive a TouchEnd event. If the client is the current owner of the sequence, ownership will be passed on to the next listener. [[requests-passivegrabdevice]] XIPassiveGrabDevice ^^^^^^^^^^^^^^^^^^^ ┌─── XIPassiveGrabDevice deviceid: DEVICE detail: CARD32 grab_type: GRABTYPE grab_window: Window cursor: Cursor owner_events: Bool grab_mode: { Synchronous, Asynchronous, Touch¹ } paired_device_mode: { Synchronous, Asynchronous } num_modifiers: INT16 mask_len: CARD16 masks: SETofEVENTMASK modifiers: LISTofSETofMODIFIERMASK ▶ num_modifiers_return: INT16 modifiers_return: LISTofGRABMODIFIERINFO └─── GRABTYPE { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter, GrabtypeFocusIn, GrabtypeTouchBegin¹ } GRABMODIFIERINFO { status: Access modifiers: SETofMODIFIERMASK } ¹ since XI 2.2 Establish an explicit passive grab for a button or keycode on the specified input device. cursor The cursor to display for the duration of the grab. If grab_type is not GrabtypeButton, this argument is ignored. deviceid The device to establish the passive grab on or AllDevices or AllMasterDevices. detail The button number, or key symbol to grab for. Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and GrabtypeTouchBegin. grab_type The type of grab to establish. grab_window Events are reported relative to the grab window. grab_mode If grab-mode is Asynchronous, device event processing continues normally. If the device is currently frozen by this client, then processing of device events is resumed. If grab-mode is Synchronous, 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 XIAllowEvents 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. If grab_type is GrabtypeTouchBegin, grab_mode must be set to Touch. mask_len Length of mask in 4 byte units. mask Event mask. An event mask for an event type T is defined as (1 << T). modifiers XKB modifier state to activate this passive grab. num_modifiers Number of elements in modifiers. owner_events Specifies whether event will be reported normally or relative to the grab window. num_modifiers_return Number of elements in modifiers_return modifiers_return XKB modifier state that could not be grabbed. If owner-events is False, 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 True, 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. If deviceid specifies a master pointer, the modifiers of the paired master keyboard are used. If deviceid specifies a slave pointer the modifiers of the master keyboard paired with the attached master pointers are used. If deviceid specifies a slave keyboard, the modifiers of the attached master keyboard are used. Note that activating a grab on a slave device detaches the device from its master. In this case, the modifiers after activation of the grab are from the slave device only and may be different to the modifier state when the grab was triggered. In the future, if grab_type is GrabtypeButton or GrabtypeKeyboard, the device is actively grabbed if: - the device is not grabbed, and - the specified modifier keys are down, and - the grab_type is GrabtypeButton and the button specified in detail is logically pressed or the grab_type is GrabtypeKeycode and the keycode specified in detail is logically pressed, and - the grab_window contains the pointer, and - a passive grab on the same button/keycode + modifier combination does not exist on an ancestor of grab_window. Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the device is actively grabbed if: - the device is not actively grabbed, and - the specified modifier keys are down, and - the grab_type is GrabtypeEnter and the device's pointer has moved into grab_window or a descendant of grab_window, or the grab_type is GrabtypeFocusIn and the device's focus has been set to the grab_window or a descendant of grab_window, and - a passive grab of the same grab_type + modifier combination does not does not exist on an ancestor of grab_window. Otherwise, if grab_type is GrabtypeTouchBegin, a touch grab begins if: - the device is not actively grabbed, and - the specified modifier keys are down - a touch begins in grab_window or a descendant of grab_window, and - a passive grab of the same grab_type + modifier combination does not does not exist on an ancestor of grab_window. Ownership of the touch sequence is granted to the grabbing client if: - a TouchBegin or pointer grab for an emulated touch sequence of a direct touch device with the same modifier set does not exist on an ancestor of grab_window, or all applicable grabs have released ownership. A modifier of GrabAnyModifier is equivalent to issuing the request for all possible modifier combinations (including no modifiers). A client may request a grab for GrabAnyModifier and explicit modifier combinations in the same request. A GrabtypeButton or GrabtypeKeyboard grab is released when all buttons or keycode are released, independent of the state of modifier keys. A GrabtypeEnter or GrabtypeFocusIn grab is released when the pointer or focus leaves the window and all of its descendants, independent of the state of modifier keys. A GrabtypeTouchBegin grab is released when the touch sequence ends or the client uses XIAllowEvents with mode RejectTouch. 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. This request overrides all previous passive grabs by the same client on the same button/key/enter/focus in + modifier combinations on the same window. If some other client already has issued a XIPassiveGrabDevice request with the same button or keycode and modifier combination, the failed modifier combinations is returned in modifiers_return. If some other client already has issued an XIPassiveGrabDevice request of grab_type XIGrabtypeEnter, XIGrabtypeFocusIn, or XIGrabtypeTouchBegin with the same grab_window and the same modifier combination, the failed modifier combinations are returned in modifiers_return. If num_modifiers_return is zero, all passive grabs have been successful. If a button grab or enter grab activates, EnterNotify and LeaveNotify events with mode Grab are generated as if the pointer were to suddenly warp from its current position some position in the grab_window. However, the pointer does not warp, and the pointer position is used as both the initial and final positions for the events. If a keycode grab or focus grab activates, FocusIn and FocusOut events with mode Grab are generated as if the focus were to change from the current window to the grab_window. If an enter or focus in grab activates, additional EnterNotify events with mode XIPassiveGrabNotify are generated as if the pointer or focus were to suddenly warp from its current position to some position in the grab window. These events are sent to the grabbing client only and only if the grab event mask has selected for it. If such a passive grab deactivates, addional LeaveNotify events with mode XIPassiveUngrabNotify are generated and sent to the grabbing client before the grab deactivates. For GrabtypeTouchBegin, grab_mode must be Touch or a BadValue error is generated. See section <> for additional notes on touch grabs, as they do not behave like traditional grabs: in particular, they do not freeze the device, and delivery of touch events continues even if the device is frozen due to a grab by another client. [[requests-passiveungrabdevice]] XIPassiveUngrabDevice ^^^^^^^^^^^^^^^^^^^^^ ┌─── XIPassiveUngrabDevice deviceid: DEVICEID detail: CARD32 grab_type: GRABTYPE grab_window: Window num_modifiers: INT16 modifiers: LISTofSETofMODIFIERMASK └─── Release an explicit passive grab on the specified input device. deviceid The device to establish the passive grab on. detail The button number or key symbol to ungrab. Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and GrabtypeTouchBegin. grab_type The type of grab to establish. grab_window Events are reported relative to the grab window. modifiers XKB modifier state to activate this passive grab. num_modifiers Number of elements in modifiers. This request has no effect if the client does not have a passive grab of the same type, same button or keycode (if applicable) and modifier combination on the grab_window. [[requests-listproperties]] XIListProperties ^^^^^^^^^^^^^^^^ ┌─── XIListProperties deviceid: DEVICEID ▶ num_properties: INT16 properties: LISTofATOM └─── List the properties associated with the given device. deviceid The device to list the properties for. num_properties Number of properties in the reply properties All properties on the device. [[requests-changeproperty]] XIChangeProperty ^^^^^^^^^^^^^^^^ ┌─── XIChangeProperty deviceid: DEVICEID property: ATOM type: ATOM format: { 8, 16, 32 } mode: { Append, Prepend, Replace } num_items: CARD32 data: LISTofINT8, or LISTofINT16, or LISTofINT32 └─── Change the given property on the given device. deviceid The device to change the property on. property The property to modify. type The property's type. mode One of Append, Prepend, or Replace num_items Number of items following this request. data Property data (nitems * format/8 bytes) The type is uninterpreted by the server. The format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities so that the server can correctly byte-swap as necessary. If the mode is Replace, the previous propert y value is discarded. If the mode is Prepend or Append, then the type and format must match the existing property value (or a Match error results). If the property is undefined, it is treated as defined with the correct type and format with zero-length data. For Prepend, the data is tacked on to the beginning of the existing data, and for Append, it is tacked on to the end of the existing data. The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the device is removed, or until server reset. A property cannot be deleted by setting nitems to zero. To delete a property, use XIDeleteProperty. This request generates an XIPropertyEvent. [[requests-deleteproperty]] XIDeleteProperty ^^^^^^^^^^^^^^^^ ┌─── XIDeleteProperty deviceid: DEVICEID property: ATOM └─── Deletes the given property on the given device. deviceid The device to delete the property on. property The property to delete. If the property is deleted, an XIPropertyEvent is generated on the device. If the property does not exist, this request does nothing. [[requests-getproperty]] XIGetProperty ^^^^^^^^^^^^^ ┌─── XIGetProperty deviceid: DEVICEID property: ATOM type: Atom or AnyPropertyType offset: CARD32 len: CARD32 delete: BOOL ▶ type: Atom bytes_after: CARD32 num_items: CARD32 format: { 8, 16, 32 } data: LISTofINT8, or LISTofINT16, or LISTofINT32 └─── Get the data for the given property on the given device. deviceid The device to retrieve the property data from. property The property to retrieve the data from.. type The property type to retrieve or AnyPropertyType offset The offset in 4-byte units. len Number of bytes to receive in 4-byte units. delete Delete the property after retrieving the data. bytes_after Number of unread bytes in the stored property num_items Number of items in data format 8, 16, or 32 data Property data (nitems * format/8 bytes) If the specified property does not exist for the specified device, then the return type is None, the format and bytes-after are zero, and the value is empty. The delete argument is ignored in this case. If the specified property exists but its type does not match the specified type, then the return type is the actual type of the property, the format is the actual format of the property (never zero), the bytes-after is the length of the property in bytes (even if the format is 16 or 32), and the value is empty. The delete argument is ignored in this case. If the specified property exists and either AnyPropertyType is specified or the specified type matches the actual type of the property, then the return type is the actual type of the property, the format is the actual format of the property (never zero), and the bytes-after and value are as follows, given: N = actual length of the stored property in bytes (even if the format is 16 or 32) I = 4 * long-offset T = N−I L = MINIMUM(T, 4 * long-length) A = N − (I + L) The returned value starts at byte index I in the property (indexing from 0), and its length in bytes is L. However, it is a Value error if offset is given such that L is negative. The value of bytes_after is A, giving the number of trailing unread bytes in the stored property. If delete is True and the bytes_after is zero, the property is also deleted from the device, and a XIPropertyNotify event is generated on the device. [[requests-xi23]] Requests introduced in version 2.3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[requests-barrierreleasepointer]] XIBarrierReleasePointer ^^^^^^^^^^^^^^^^^^^^^^^ ┌─── XIBarrierReleasePointer num_items: CARD32 ▶ data: LISTofBARRIERRELEASEINFO └─── BARRIERRELEASEINFO { deviceid: DEVICEID, barrier: Barrier, eventid: CARD32 } Release a pointer currently blocked by a barrier. In the future, movement of this pointer against the barrier will not be blocked. deviceid The device currently being blocked by a barrier barrier The barrier currently blocking the device eventid The unique event ID assigned to this barrier event sequence If the barrier given does not currently block this device, or the eventid is invalid, this request does nothing. Releasing a pointer barrier is only valid during one barrier event sequence, and only applies to the next movement of this device against this barrier. If the pointer moves away from the barrier following a XIBarrierReleasePointer request, the release request is discarded. In the future, if the pointer moves against the barrier again, a new eventid is assigned and the client must re-issue the XIBarrierReleasePointer request. If the device is not a master pointer device, a BadDevice error results. If the barrier does not name a valid barrier, a BadValue error results. [[events]] Events ------ An event specifies its length in 4-byte units after the initial 32 bytes. Future versions of the protocol may provide additional information in the same event, thus increasing the event size. Clients are required to always read the number of bytes specified by the event, not the size of the event they may have been compiled against. The following event types are available in XI2. Version 2.0: - HierarchyChanged - DeviceChanged - KeyPress - KeyRelease - ButtonPress - ButtonRelease - Motion - RawKeyPress - RawKeyRelease - RawButtonPress - RawButtonRelease - RawMotion - Enter - Leave - FocusIn - FocusOut - PropertyEvent Version 2.2: - TouchBegin - TouchUpdate - TouchOwnership - TouchEnd - RawTouchBegin - RawTouchUpdate - RawTouchEnd Version 2.3: - BarrierHit - BarrierLeave All events have a set of common fields specified as EVENTHEADER. EVENTHEADER { type: BYTE extension: BYTE sequenceNumber: CARD16 length: CARD32 evtype: CARD16 deviceid: DEVICEID time: Time } type Always GenericEvent. extension Always the X Input extension offset. sequenceNumber Sequence number of last request processed by the server. length Length in 4-byte units after the initial 32 bytes. evtype XI-specific event type. deviceid Numerical device id for a device. time Time in ms when the event occurred. [[events-xi20]] Events introduced in version 2.0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[events-hierarchyevent]] HierarchyEvent ^^^^^^^^^^^^^^ ┌─── HierarchyEvent EVENTHEADER flags: SETofHIERARCHYMASK num_info: CARD16 info: LISTofHIERARCHYINFO └─── HIERARCHYMASK { MasterAdded, MasterRemoved, SlaveAttached, SlaveDetached, SlaveAdded, SlaveRemoved, DeviceEnabled, DeviceDisabled } HIERARCHYINFO { deviceid: DEVICEID, attachment: DEVICEID, type: DEVICEUSE enabled: BOOL flags: SETofHIERARCHYMASK} flags Set of the changes that have occured, causing this event. num_info The number of device info structs following the request. info: The current hierarchy information. An XIHierarchyEvent is sent whenever the device hierarchy been changed. The flags specify all types of hierarchy modifiations that have occured. For all devices, info details the hierarchy information after the modification of the hierarchy has occured. For each device specified with deviceid: - if type is MasterPointer or MasterKeyboard, attachment decribes the pairing of this device. - if type is SlavePointer or SlaveKeyboard, attachment describes the master device this device is attached to. - if type is FloatingSlave device, attachment is undefined. enabled True if the device is enabled and can send events. A disabled master device will not forward events from an attached, enabled slave device. Note: Multiple devices may be affected in one hierarchy change, deviceid in an XIHierarchyEvent is always the first affected device. Clients should ignore deviceid and instead use the devices list. [[events-devicechangedevent]] DeviceChangedEvent ^^^^^^^^^^^^^^^^^^ ┌─── DeviceChangedEvent EVENTHEADER reason: CHANGEREASON source: DEVICEID num_classes: CARD16 classes: LISTofCLASS └─── CHANGEREASON { SlaveSwitch, DeviceChange } A DeviceChangeEvent is sent whenever a device changes it's capabilities. This can happen either by a new slave device sending events through a master device, or by a physical device changing capabilities at runtime. reason The reason for generating this event. If reason is SlaveSwitch, the slave device sending events through this device has changed and source specifies the new slave device. A SlaveSwitch reason can only occur on a master device. If reason is DeviceChange, the device itself has changed through other means (e.g. a physical device change) and source is the device itself. source The source of the new classes. num_classes Number of classes provided. classes Details the available classes provided by the device. The order the classes are provided in is undefined. For a detailed description of classes, see the XIQueryDevice request. [[events-deviceevent]] DeviceEvent ^^^^^^^^^^^ ┌─── DeviceEvent EVENTHEADER detail: CARD32 root: Window event: Window child: Window root_x: FP1616 root_y: FP1616 event_x: FP1616 event_y: FP1616 buttons_len: CARD16 valuators_len: CARD16 sourceid: DEVICEID mods: MODIFIERINFO group: GROUPINFO flags: DEVICEEEVENTFLAGS buttons: SETofBUTTONMASK valuators: SETofVALUATORMASK axisvalues: LISTofFP3232 └─── BUTTONBIT { (1 << Button1), (1 << Button2), ... , (1 << ButtonN) } VALUATORBIT { (1 << 1), ( 1 << 2), ... ( 1 << n) } MODIFIERINFO { base_mods: CARD32, latched_mods: CARD32, locked_mods: CARD32, effective_mods: CARD32} GROUPINFO { base_group: CARD8, latched_group: CARD8, locked_group: CARD8, effective_group: CARD8} DEVICEEVENTFLAGS (all events): none DEVICEEVENTFLAGS (key events only): { KeyRepeat } DEVICEEVENTFLAGS (pointer events only): { PointerEmulated } DEVICEEVENTFLAGS (touch events only): { TouchPendingEnd, TouchEmulatingPointer } An XIDeviceEvent is generated whenever the logical state of a device changes in response to a button press, a button release, a motion, a key press or a key release. The event type may be one of KeyPress, KeyRelease, ButtonPress, ButtonRelease, Motion. XI 2.2: The event type may also be TouchBegin, TouchUpdate, or TouchEnd. detail The button number, key code, touch ID, or 0. root event child The root window, event window or subwindow, respectively. See core protocol specification for more detail. root_x root_y The position of the pointer in screen coordinates (16.16 fixed point). event_x event_y The position of the pointer in screen coordinates relative to the event window (16.16 fixed point). buttons_len The length of buttons in 4 byte units. valuators_len The length of valuators in 4 byte units. sourceid The source device that originally generated the event. mods XKB modifier state before the event occured. group XKB group state before the event. buttons Button state before the event. valuators Bitmask of valuators provided in axisvalues. axisvalues Valuator data in device-native resolution. This is a non-sparse array, value N represents the axis corresponding to the Nth bit set in valuators. flags Miscellaneous information about this event; the union of the common flag set and either the key or pointer flag set, depending on the event type. KeyRepeat means that this event is for repeating purposes, and the physical state of the key has not changed. This is only valid for KeyPress events. PointerEmulated signals that the event has been emulated from another XI 2.x event for legacy client support, and that this event should be ignored if the client listens for these events. This flag is set on scroll ButtonPress and RawButtonPress events (buttons 4, 5, 6 and 7) if a smooth-scrolling event on the Rel Vert Scroll or Rel Horiz Scroll axes was also generated. It is also set on Motion, ButtonPress, and ButtonRelease events generated by direct touch devices. TouchPendingEnd (for touch events only) means that the touch has physically ended, however another client still holds a grab, so the touch should be considered alive until all grabbing clients have accepted or passed on ownership. The touch will not generate any further TouchUpdate events once an event with TouchPendingEnd has been received. TouchEmulatingPointer is set on touch events that emulate pointer events. Modifier state in mods is detailed as follows: base_mods XKB base modifier state. latched_mods XKB latched modifier state. locked_mods XKB locked modifier state. Group state in group is detailed as follows: base_group XKB base group state. latched_group XKB latched group state. locked_group XKB locked group state. In servers supporting XI 2.2, a TouchBegin event is generated whenever a new touch sequence initializes. A TouchEnd event is generated whenever a touch sequence ceases. A TouchUpdate event is generated whenever a valuator value changes, or a flag flag (e.g. pending end) has changed for that touch sequence; this may result in a TouchUpdate event being sent with zero valuators. The average finger size is significantly larger than one pixel. The selection of the hotspot of a touchpoint is implementation dependent and may not be the logical center of the touch. Touch tracking IDs are provided in the detail field of touch events. Its value is always provided in every touch event. Tracking IDs are represented as unsigned 32-bit values and increase strictly monotonically in value for each new touch, wrapping back to 0 upon reaching the numerical limit of IDs. The increment between two touch IDs is indeterminate. Clients may not assume that any future touches will have specific touch IDs. IDs are globally unique. The button state in touch events represents the state of the device's physical buttons only, even if that sequence is emulating pointer events. Touch events do not generate enter/leave events. [[events-rawevent]] RawEvent ^^^^^^^^ ┌─── RawEvent EVENTHEADER detail: CARD32 sourceid¹: DEVICEID flags: DEVICEEVENTFLAGS valuators_len: CARD16 valuators: SETofVALUATORMASK axisvalues: LISTofFP3232 axisvalues_raw: LISTofFP3232 └─── ¹ since XI 2.1 A RawEvent provides the information provided by the driver to the client. RawEvent provides both the raw data as supplied by the driver and transformed data as used in the server. Transformations include, but are not limited to, axis clipping and acceleration. Transformed valuator data may be equivalent to raw data. In this case, both raw and transformed valuator data is provided. RawEvents are sent exclusively to all root windows. Clients supporting XI 2.0 receive raw events when the device is not grabbed, or when the device is grabbed by the client but not when the device is grabbed by another client. Clients supporting XI 2.1 or later receive raw events at all times, even when the device is grabbed by another client. eventtype The type of event that occured on the device. detail The button number, keycode or touch ID¹. sourceid The source device that originally generated the event. The sourceid is undefined for clients not supporting XI 2.1. flags Flags as described in DeviceEvent. valuators_len The length of valuators in 4 byte units. valuators Bitmask of valuators provided in axisvalues and axisvalues_raw. axisvalues Valuator data in device-native resolution. This is a non-sparse array, value N represents the axis corresponding to the Nth bit set in valuators. axisvalues_raw Untransformed valuator data in device-native resolution. This is a non-sparse array, value N represents the axis corresponding to the Nth bit set in valuators. ¹ since XI 2.2 [[events-enterleave]] Enter or Leave or FocusIn or FocusOut ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ┌─── Enter or Leave or FocusIn or FocusOut EVENTHEADER root: Window event: Window child: Window sourceid: DEVICEID root_x: FP1616 root_y: FP1616 event_x FP1616 event_y: FP1616 mode: NOTIFYMODE detail: NOTIFYDETAIL same_screen: BOOL focus: BOOL mods: MODIFIERINFO group: GROUPINFO buttons_len: CARD16 buttons: SETofBUTTONMASK └─── NOTIFYMODE { Normal, Grab, Ungrab } NOTIFYDETAIL { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual, Pointer, PointerRoot, None } Enter or Leave events are sent whenever a device's pointer enters or leaves a window. FocusIn or FocusOut events are sent whenever a device's focus is set to or away from a window. The enter/leave and focus in/out model is described in the core protocol specification, Section 11. (EnterNotify, LeaveNotify events). For enter and leave events, the modifier and group state is the state of the paired master device if the device is a master device, or the state of the attached master keyboard if the device is an attached slave device, or zero if the device is a floating slave device. For focus in and out events, the button state is the state of the paired master device if the device is a master device, or the state of the attached master keyboard if the device is an attached slave device, or zero if the device is a floating slave device. root event child The root window, event window, and child window, respectively. See the core protocol specification for more detail. sourceid The device that caused the pointer to move. root_x root_y The pointer coordinates relative to the root window. event_x event_y The pointer coordinates relative to the event window. mode Normal pointer motion events have mode Normal. Pseudo-motion events when a grab activates have mode Grab, and pseudo-motion events when a grab deactivates have mode Ungrab. Pseudo-motion events caused by the activation or deactivation of a passive enter or focus in grab have mode XIPassiveGrabNotify or XIPassiveUngrabNotify. detail Specifies the relation of the event window to the window the pointer entered or left. See the core protocol spec for details. same_screen True if the event window is on the same screen as the pointer's root window. focus If the event window is the focus window or an inferior of the focus window, then focus is True. Otherwise, focus is False. This field is unspecified for focus in/out events. mods XKB modifier state before the event occured. group XKB group state before the event. buttons_len The length of buttons in 4 byte units. buttons Button state before the event. [[events-propertyevent]] XIPropertyEvent ^^^^^^^^^^^^^^^ ┌─── XIPropertyEvent EVENTHEADER property: ATOM what: { PropertyCreated, PropertyDeleted, PropertyModified } └─── XIPropertyEvents are sent whenever a device property is created, deleted or modified by a client. property The property that has been created, deleted, or modified what Specifies what has been changed. [[events-xi22]] Events introduced in version 2.2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[events-touchownershipevent]] TouchOwnershipEvent ^^^^^^^^^^^^^^^^^^^ ┌─── TouchOwnershipEvent EVENTHEADER touchid: CARD32 root: Window event: Window child: Window sourceid: DEVICEID flags: SETofTOUCHOWNERSHIPFLAGS └─── TOUCHOWNERSHIPFLAGS: (none currently defined) A TouchOwnershipEvent indicates that ownership has changed, and the client is now the owner of the touch sequence specified by touchid. touchid The identifier of the touch sequence. root event child The root window, event window, and child window, respectively. See the core protocol specification for more detail. sourceid The source device that originally generated the event. flags A bitmask of flags for this event. [[events-xi23]] Events introduced in version 2.3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [[events-barrierevent]] BarrierEvent ^^^^^^^^^^^^ ┌─── BarrierEvent EVENTHEADER eventid: CARD32 root: Window event: Window barrier: Barrier dtime: CARD32 flags: SETofBARRIERFLAGS sourceid: DEVICEID root_x: FP1616 root_y: FP1616 dx: FP3232 dy: FP3232 └─── BARRIERFLAGS { PointerReleased, DeviceIsGrabbed } A BarrierEvent indicates interaction between a barrier and a pointer device. If the event type is BarrierHit, pointer movement has been blocked by a barrier. If the event type is BarrierLeave, a pointer previously blocked by a barrier has moved away from that barrier, or has moved through the blocking barrier following an earlier XIBarrierReleasePointer request. eventid The unique event ID for this barrier event sequence. root event The root window or barrier window, respectively. The barrier window is always the drawable specified in in the CreatePointerBarrier request. barrier The barrier blocking pointer movement. dtime The relative time in milliseconds between the last event and this event. flags A set of flags that apply to this barrier event PointerReleased: The pointer has moved through the barrier following a XIBarrierReleasePointer request (BarrierLeave only). DeviceIsGrabbed: The pointer device that generated this event is currently grabbed. sourceid The source device that originally generated the event. root_x root_y The position of the pointer in screen coordinates (16.16 fixed point), after being constrained by barrier and/or screen extents. dx dy The relative movement of the pointer from its previous position to the new position if pointer movement were not constrained by this barrier. Root coordinates in barrier events represent the position of the cursor after confinement by barriers, screens and RandR output extents. Barrier event IDs are provided in the eventid field of barrier events. Its value is always provided in every barrier event. Event IDs are represented as unsigned 32-bit values and increase strictly monotonically in value for each new barrier event sequence, wrapping back to 0 upon reaching the numerical limit of IDs. The increment between two event IDs is indeterminate. Clients may not assume that any future barrier constraints will have specific event IDs. IDs are unique per device per barrier. If a pointer is actively grabbed after a barrier event sequence has initiated, future barrier events of this sequence continue to use the same eventid, but all barrier events have the DeviceIsGrabbed flag set. If the pointer is ungrabbed, future events of this sequence have the same eventid and the DeviceIsGrabbed flag is unset. The PointerReleased flag may only be set on a BarrierLeave event. A BarrierLeave(PointerReleased) event is generated when the pointer moves through the barrier following a XIBarrierReleasePointer request. The time between the XIBarrierReleasePointer and the BarrierLeave event thus depends on user input. A BarrierLeave(PointerReleased) event is also generated if the barrier is destroyed while pointer movement is constrained by the barrier, or the master pointer blocked by the barrier is removed. This event has a dx/dy of 0/0. :numbered!: [[xi22-usecases]] [appendix] XI 2.2 Use-cases ---------------- All use-cases that include the receiving and processing of touch events require the client to announce XI 2.2 support in the XIQueryVersion request. Client C wants to process touch events from a device D on window W. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * C calls XISelectEvent for XI_Touch{Begin|Update|End} from D on W. * C receives TouchBegin whenever a touch sequence starts within W's borders. * C receives TouchUpdate events whenever an axis valuator value changes for a touch sequence it received a TouchBegin event for. * C receives TouchEnd whenever a touch it received a TouchBegin event for ceases. While client I wants to pre-process touch events from device D on the parent window of W. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * C calls XISelectEvent for XI_Touch{Begin|Update|Ownership|End} from D on W. * I calls XIPassiveGrab for XI_Touch{Begin|Update|Ownership|End} from D on a parent window of W. * I receives TouchBegin whenever a touch begins within window W, as well as a TouchOwnership event indicating that it currently owns the touch sequence. C receives a TouchBegin event as well, but without TouchOwnership. * When an axis valuator changes in this touch sequence, both I and C receive a TouchUpdate event. I may process the event to determine if it is going to accept or reject the touch, whereas C may perform reversible processing. * If I decides it is going to claim the touch sequence for its exclusive processing, it calls XIAllowEvents with an event mode of XIAcceptTouch; at this point, C receives a TouchEnd event, and undoes any processing it has already performed due to the touch sequence. Further TouchUpdate events are delivered only to I. * Alternatively, if I decides it does not want to receive further events from this touch sequence, it calls XIAllowEvents with an event mode of XIRejectTouch; at this point, I receives a TouchEnd event confirming that it has rejected the touch. C receives a TouchOwnership event confirming that it is now the new owner of the touch, and further TouchUpdate events are delivered only to C. As C now owns the touch, it is free to perform irreversible processing of the sequence. * When the touch physically ceases, a TouchEnd event is sent to C. While client I wants to process pointer events on window W's parent, window Y. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * I calls XIPassiveGrab for XI_{ButtonPress,MotionNotify,ButtonRelease} to create a synchronous pointer grab from D on Y. * C calls XISelectEvent for XI_Touch{Begin|Update|Ownership|End} from D on W. * I receives a ButtonPress event whenever a touch begins within W, and is considered the owner of the event. C receives a TouchBegin event, but does not receive a TouchOwnership event. * When the touchpoint moves, C will receive a TouchUpdate event. Event delivery to I is subject to the synchronous delivery mechanism. The emulated motion notify event is queued in the server while the device is frozen. * I may assert ownership by calling XIAllowEvents on Y with any mode other than ReplayDevice, which will cause all further events to be sent only to I, with a TouchEnd event being sent to C. * Alternatively, I may reject the touch sequence by calling XIAllowEvents on Y with mode ReplayDevice, which will cause no further events from that touch to be sent to I, and a TouchOwnership event to be sent to C, with subsequent motion events being sent as TouchUpdate events. Driver DRV provides touch support from tracked device D: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * DRV initializes a TouchClass for the device. * DRV parses D's device protocol and selects one touch sequence to be emulated as pointer event. * DRV calls the respective input driver API with the touch sequence data. The touch sequence emulating a pointer has the respective flag set. DRV does not submit pointer data for any touchpoint. 07070100062369000081a400000000000000000000000153c4dc3e00024bf0000001000001001cffffffffffffffff0000003200000000root/usr/local/share/doc/inputproto/XI2proto.html The X Input Extension 2.x

Authors:

1. History

  • v2.3, December 2012: Pointer barrier events added

  • v2.2, March 2012: Multitouch support added

  • v2.1, December 2011: new raw event behaviour, smooth scrolling support added

  • v2.0, October 2009: Initial release of XI2 protocol

2. Introduction

The X Input Extension version 2.0 (XI2) is the second major release of the X Input Extension.

XI2 provides a number of enhancements over version 1.5, including:

  • use of XGE and GenericEvents. GenericEvents are of flexible length with a minimum length of 32 bytes.

  • explicit device hierarchy of master and slave devices. See Section The Master/Slave device hierarchy.

  • use of multiple independent master devices (Multi-Pointer X or MPX).

  • the ability for devices to change capabilities at runtime.

  • raw device events

XI2’s intent is to replace both core input processing and prior versions of the X Input Extension. Historically, the majority of applications employed the core protocol requests and events to handle user input. The core protocol does not provide information about which device generated the event. The X Input Extension version up to 1.5 requires the differentiation between core and extended devices. Extended devices may not be core devices and thus cannot be used on applications employing the core protocol. XI2 addresses both of these issues by enabling devices to be both extended and core devices and providing device information in each event (with the exception of core events).

3. Changes in version 2.1

  • RawEvents are sent regardless of the grab state.

  • Addition of the ScrollClass for smooth scrolling

4. Changes in version 2.2

  • Multitouch support added

5. Changes in version 2.3

  • Pointer barrier events added

6. Notations used in this document

Notation for requests:

┌───
    Name of request
        name of request field:       type of request field
        name of request field:       type of request field
        ▶
        name of reply field:         type of reply field
└───

Notation for events:

┌───
    Name of event
        name of field:               type of field
        name of field:               type of field
└───

Complex fields are specified in the following notation:

name of field:                  COMPLEXFIELDTYPE

or, if multiple of these fields exist:

name of field:                  LISTofCOMPLEXFIELDTYPE
COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
                     name of subfield:   type of subfield }

7. Interoperability between version 1.x and 2.0

There is little interaction between 1.x and 2.x versions of the X Input Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as possible. Several direct incompatibilities are observable:

7.1. Limitations resulting from different variable ranges

XI2 provides a larger range for some fields than XI1. As a result, XI1 clients may not receive data an XI2 client receives. These fields include:

  • devices with a deviceid of greater than 127 are invisible to XI1 clients.

  • key events and key grabs featuring larger than 255 can only be sent to XI2 clients.

  • no subpixel information is available to XI1 clients. If motion events are in a subpixel range only, the server may omit these events and an XI 1.x client will not receive events until the pixel boundary is crossed.

7.2. Blocking of grabs

XI1 grabs are different to XI2 grab and a device may not be grabbed through an XI2 grab if an XI1 grab is currently active on this device or vice versa. Likewise, a keycode or button already grabbed by an XI 1.x or XI2 client may not be grabbed with the same modifier combination by an XI2 or XI 1.x client, respectively.

7.3. Invisibility of Master Devices

XI 1.x was not designed with support for multiple master devices. As a result, only the first master pointer and master keyboard are visible to XI 1.x clients; all other master devices are invisible and cannot be accessed from XI 1.x calls.

7.4. Smooth scrolling

Historically, X implemented scrolling events by using button press events: button 4 was one “click” of the scroll wheel upwards, button 5 was downwards, button 6 was one unit of scrolling left, and button 7 was one unit of scrolling right. This is insufficient for e.g. touchpads which are able to provide scrolling events through multi-finger drag gestures, or simply dragging your finger along a designated strip along the side of the touchpad.

Newer X servers may provide scrolling information through valuators to provide clients with more precision than the legacy button events. This scrolling information is part of the valuator data in device events. Scrolling events do not have a specific event type.

Valuators for axes sending scrolling information must have one ScrollClass for each scrolling axis. If scrolling valuators are present on a device, the server must provide two-way emulation between these valuators and the legacy button events for each delta unit of scrolling.

One unit of scrolling in either direction is considered to be equivalent to one button event, e.g. for a unit size of 1.0, -2.0 on an valuator type Vertical sends two button press/release events for button 4. Likewise, a button press event for button 7 generates an event on the Horizontal valuator with a value of +1.0. The server may accumulate deltas of less than one unit of scrolling.

Any server providing this behaviour marks emulated button or valuator events with the XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag for raw events, to hint at applications which event is a hardware event.

If more than one scroll valuator of the same type is present on a device, the valuator marked with Preferred for the same scroll direction is used to convert legacy button events into scroll valuator events. If no valuator is marked Preferred or more than one valuator is marked with Preferred for this scroll direction, this should be considered a driver bug and the behaviour is implementation-dependent.

8. The Master/Slave device hierarchy

XI2 introduces a device hierarchy split up into so-called Master Devices (MD) and Slave Devices (SD).

8.1. Master devices

An MD is a virtual device created and managed by the server. MDs may send core events and XI events. However, an MD does not represent a physical device and relies on SDs for event generation. MDs come in two forms: as master pointers or as master keyboards. A master pointer is represented by a visible cursor on the screen. A master keyboard is represented by a keyboard focus.

Each master pointer is paired with the respective master keyboard and vice versa, and this pairing is constant for the lifetime of both input devices. Clients can use this pairing behaviour to implement input paradigms that require pointer and keyboard interation (e.g. SHIFT + Click).

8.2. Slave devices

An SD is usually a physical device configured in the server. SDs are not represented by a cursor or keyboard focus and may be attached to a master pointer or master keyboard. SDs can only be attached to any master of the same type (e.g. a physical pointer device can be attached to any master pointer).

If an event is generated by an SD

  • if the SD is attached to a master pointer, it changes the position and/or button state of the master pointer.

  • if the SD has a keyboard focus other than None, the key event is sent to the focus window.

  • if the SD is attached to a master keyboard, it sends events to this keyboard’s focus window (if applicable) and/or changes the modifier state of this keyboard.

  • if the SD is not attached to an MD ("floating"), it does not change any master device. The SD has its own (invisible) sprite and its own focus. Both the sprite and the focus must be managed explicitly by the client program.

Note: the keyboard focus of an attached slave device is independent to that of the master device. Two keyboard events are generated, once with deviceid and sourceid set to the slave device. This keyboard event is sent to the slave device’s focus window. The second event has a deviceid of the master and a sourceid of the slave device. This second event is delivered to the master keyboard’s focus window.

8.3. Event processing for attached slave devices

Whenever an SD changes its logical state,

  • the event is delivered as an XI event to any interested clients. If the device is floating, event processing stops. Otherwise, if the device is attached,

  • the master device changes its classes to reflect the SD’s capabilities. All interested clients are notified of this device change.

  • then, the event is delivered as an XI event from the MD to any interested clients. If the event has been delivered, event processing stops. Otherwise,

  • the event is delivered as a core event to any interested clients.

Given that W is the event window, and P the parent window of W, event delivery to P is only attempted if neither the XI event, nor the core event has been delivered on W. Once an event has been delivered as either XI or core event, event processing stops.

8.4. The ClientPointer principle

Many core protocol and some extension requests are ambiguous when multiple master devices are available (e.g. QueryPointer does not specify which pointer). The X server does not have the knowledge to chose the contextually correct master device. For each client, one master pointer is designated as this clients’s "ClientPointer". Whenever a client sends an ambiguous request (e.g. QueryPointer), the ClientPointer or the keyboard paired with the ClientPointer is chosen to provide the data for this request.

This ClientPointer may be explicitly assigned to a client with the SetClientPointer call. If no ClientPointer is set when a client issues an ambiguous request, the server choses one device as the ClientPointer. The method of chosing a ClientPointer from the available master pointers is implementation-specific.

If the master pointer currently set as ClientPointer for one or more clients is removed, the server may either unset the ClientPointer setting or change the ClientPointer to a different master pointer.

9. Touch device support

XI 2.2 introduces support for multi-touch devices. The traditional pointer/keyboard approach enforced by XI 2.0 with the master/slave device hierarchy is not always suitable for multi-touch devices that can provide a dynamic number of touchpoints per physical device; it is not known without client-specific interpretation whether the touchpoints must be considered separately or grouped together.

The additions in XI 2.2 aim to:

  • support a dynamic number of simultaneous touch points,

  • support devices that are both multi-touch and traditional pointer devices,

  • allow touchpoints to be either grouped together or handled separately,

  • be backwards-compatible to pre-XI 2.2 clients through emulation of XI 2.x/XI 1.x and core pointer events.

Touch events are only available to clients supporting version 2.2 or later of the X Input Extension. Clients must use the XIQueryVersion request to announce support for this version. Touch devices may generate emulated pointer events alongside XI 2.2 touch events to support older clients; see Section Touch event delivery.

Touch event processing differs from normal event processing in a few ways. The most notable differences are that touch events are processed partially out-of-band from pointer and keyboard events, and that touch events may be sent to multiple clients simultaneously. For more details see Section Touch event delivery.

9.1. Touch event sequences

Touch input follows a three-stage cycle:

begin - update - update - ... - end

i.e. “begin” the sequence by touching the device, “update” the current touch location or properties any number of times, and finally “end” the sequence by ceasing to touch the device. Within this document, the term "touch sequence" is used to describe the above sequence of events. In the protocol, the three stages are represented with the event types TouchBegin, TouchUpdate, and TouchEnd, respectively. A touch sequence always generates TouchBegin and TouchEnd events, and may also generate TouchUpdate events. Clients must select for all three of these events simultaneously.

When a touch starts, clients are sent a TouchBegin event detailing the position of the touchpoint, as well as the initial properties of the touchpoint. Note that the logical state of the device (as seen through the input protocol) may lag the physical state if event processing is affected by grabs. Multiple touchpoints may be active on the same device at any time, potentially owned by and/or delivered to a different set of clients.

Whenever the touch position or any other property of the touchpoint changes, a TouchUpdate event is sent to all clients listening to events for that touchpoint with the updated information.

When the touch has physically ended, or a client will otherwise not receive any more events for a given touchpoint, a TouchEnd event will be sent to that client.

Passive touch grabs are similar to standard input event grabs in that they take precedence over event selections and are searched from the root window to the child window (as opposed to selections, which start their search at the child window and continue up to the root window). When a touch grab activates, the client whose grab activates becomes the “owner” of this touch sequence, and must decide what to do with it, as per Section Ownership of touch sequences. See the XIPassiveGrabDevice request documentation for more information on passive grab activation.

Only one client may select for touch events from a given device on a window.

9.1.1. Ownership of touch sequences

Once a grabbing client becomes the owner of a touch, it must either “accept” or "reject" the touch sequence using the XIAllowEvents request. If a touch sequence is rejected, a TouchEnd event is sent to the rejecting client, and it will not receive any more events for this touch. The server then looks to the next window in the stack for another passive grab, and attempts to pass ownership on to the next candidate for a passive grab (i.e. the next window towards the final child window with a matching grab), or to the first applicable event selection if there are no more grabs.

If a touch sequence is accepted by its owner, all other clients receive TouchEnd events, and the touch sequence is exclusively delivered to the owner from that point on.

If the touch sequence physically ends while the owner of the touch sequence has not yet accepted or rejected ownership, the owner receives a TouchEnd event and all other clients receive a TouchUpdate event with the TouchPendingEnd flag set. The owner must still accept or reject the sequence nonetheless. If the owner rejects the touch sequence, the server will still attempt to exhaust all other passive grabs and/or event selections looking for a final owner.

If the touch sequence has not physically ended yet and the owner of the touch sequence rejects, the owner receives a TouchEnd event and ownership is passed to the next client.

Clients may opt for touch events to be delivered before they become the owner of the touch sequence. In this case, the logical state of the device (as seen by means of the protocol) always matches the physical state of the device. Clients must use caution if they opt for this feature; any action taken must be undone if the touch sequence ends without the client becoming the owner.

To select for touch events regardless of ownership, a client must set the TouchOwnership event mask in addition to the TouchBegin, TouchUpdate and TouchEnd mask. When selected, a client will receive touch events as they occur on the device. If and when the client becomes the owner of a touch sequence, a TouchOwnership event is sent to the client. If the client is the initial owner of the sequence, the TouchBegin is immediately followed by the TouchOwnership event. Otherwise, TouchUpdate events may preceed a TouchOwnership event. A client is not guaranteed to become the owner of any given touch sequence.

The server delivers touch events to all clients that have selected for TouchOwnership and to the current owner of the sequence in parallel.

If a client has selected for TouchOwnership and is not the current owner of the sequence and the current owner accepts the sequence, the client receives a TouchEnd event and no further events from this sequence are sent to this client.

If a client has selected for TouchOwnership and the physical touch ends before the current owner has accepted or rejected the sequence, the client receives a TouchUpdate event with the TouchPendingEnd flag set. No further TouchUpdate events will be sent for this sequence. If the current owner accepts the sequence, the client receives a TouchEnd event. Otherwise, if the current owner rejects the sequence, the client may become the owner of the touch sequence and receive a TouchOwnership event and a TouchEnd event.

9.2. Touch device modes

Touch devices come in many different forms with varying capabilities. The following device modes are defined for this protocol:

DirectTouch: These devices map their input region to a subset of the screen region. Touch events are delivered to window at the location of the touch. "direct" here refers to the user manipulating objects at their screen location. An example of a DirectTouch device is a touchscreen.

DependentTouch: These devices do not have a direct correlation between a touch location and a position on the screen. Touch events are delivered according to the location of the device’s cursor and often need to be interpreted relative to the current position of that cursor. Such interactions are usually the result of a gesture performed on the device, rather than direct manipulation. An example of a DependentTouch device is a trackpad.

A device is identified as only one of the device modes above at any time, and the touch mode may change at any time. If a device’s touch mode changes, an XIDeviceChangedEvent is generated.

9.3. Touch event delivery

For direct touch devices, the window set for event propagation is the set of windows from the root window to the topmost window lying at the co-ordinates of the touch.

For dependent devices, the window set for event propagation is the set of windows from the root window to the window that contains the device’s pointer. A dependent device may only have one window set at a time, for all touches. Any future touch sequence will use the same window set. The window set is cleared when all touch sequences on the device end.

A window set is calculated on TouchBegin and remains constant until the end of the sequence. Modifications to the window hierarchy, new grabs or changed event selection do not affect the window set.

9.3.1. Pointer control of dependent devices

On a dependent device, the device may differ between a pointer-controlling touch and a non-pointer-controlling touch. For example, on a touchpad the first touch is pointer-controlling (i.e. serves only to move the visible pointer). Multi-finger gestures on a touchpad cause all touches to be non-pointer-controlling.

For pointer-controlling touches, no touch events are sent; the touch generates regular pointer events instead. Non-pointer-controlling touches send touch events. A touch may change from pointer-controlling to non-pointer-controlling, or vice versa.

  • If a touch changes from pointer-controlling to non-pointer-controlling, a new touch ID is assigned and a TouchBegin is sent for the last known position of the touch. Further events are sent as TouchUpdate events, or as TouchEnd event if the touch terminates.

  • If a touch changes from non-pointer-controlling to pointer-controlling, a TouchEnd is sent for that touch at the last known position of the touch. Further events are sent as pointer events.

The conditions to switch from pointer-controlling to non-pointer-controlling touch is implementation-dependent. A device may support touches that are both pointer-controlling and a touch event.

In the dependent touch example event sequence below, touches are marked when switching to pointer-controlling (pc) or to non-pointer-controlling (np).

Table 1. Dependent touch example event sequence on a touchpad
Finger 1 Finger 2 Event generated(touchid)

down

Motion

move

Motion

move

Motion

(np)

down

TouchBegin(0), TouchBegin(1)

move

 — 

TouchUpdate(0)

 — 

move

TouchUpdate(1)

up

(pc)

TouchEnd(0), TouchEnd(1)

move

Motion

down

(np)

TouchBegin(2), TouchBegin(3)

move

 — 

TouchUpdate(2)

up

(pc)

TouchEnd(2), TouchEnd(3)

up

Motion

down

Motion

(np)

down

TouchBegin(4), TouchBegin(5)

(pc)

up

TouchEnd(4), TouchEnd(5)

move

Motion

up

Motion

9.3.2. Pointer emulation from multitouch events

Touch sequences from direct touch devices may emulate pointer events. Only one touch sequence from a device may emulate pointer events at a time; which touch sequence emulates pointer events is implementation-dependent.

Pointer events are emulated as follows:

  • A TouchBegin event generates a pointer motion event to the location of the touch with the same axis values of the touch event, followed by a button press event for button 1.

  • A TouchUpdate event generates a pointer motion event to the location of the touch and/or to update axis values of the pointer device. The button state as seen from the protocol includes button 1 set.

  • A TouchEnd event generates a pointer motion event to the location of the touch and/or to update the axis values if either have changed, followed by a button release event for button 1. The button state as seen from the protocol includes button 1 set.

If a touch sequence emulates pointer events and an emulated pointer event triggers the activation of a passive grab, the grabbing client becomes the owner of the touch sequence.

The touch sequence is considered to have been accepted if

  • the grab mode is asynchronous, or

  • the grab mode is synchronous and the device is thawed as a result of AllowEvents with AsyncPointer or AsyncDevice

Otherwise, if the button press is replayed by the client, the touch sequence is considered to be rejected.

Touch event delivery precedes pointer event delivery. A touch event emulating pointer events is delivered:

  • as a touch event to the top-most window of the current window set if a client has a touch grab on this window,

  • otherwise, as a pointer event to the top-most window of the current window set if a client has a pointer grab on this window,

  • otherwise, to the next child window in the window set until a grab has been found.

If no touch or pointer grab on any window is active and the last window in the window set has been reached, the event is delivered:

  • as a touch event to the window if a client has selected for touch events on this window

  • otherwise, as a pointer event to the window if a client has selected for pointer events.

  • otherwise, to the next parent window in the window set until a selection has been found.

Emulated pointer events will have the PointerEmulated flag set. A touch event that emulates pointer events has the TouchEmulatingPointer flag set.

9.3.3. Pointer barrier events

If a master pointer moves against a pointer barrier blocking movement in that pointer’s direction, the movement of the pointer is clamped to the x or y coordinate of the barrier, whichever applies. For a description of pointer barriers and barrier creation and destruction see the XFixes protocol specification v 5.0 or later. http://cgit.freedesktop.org/xorg/proto/fixesproto/plain/fixesproto.txt

A pointer hitting a blocking barrier creates a new barrier event sequence, identified by a unique event ID. A new event ID is assigned when the pointer first hits a barrier. Subsequent movements against or along the pointer barrier are assigned the same event ID. The event generated by the pointer leaving the barrier, or being released by a client request, is the last event with this event ID. Any future movements of this device blocked by this barrier will be assigned a new event ID.

Pointer barrier events are delivered exclusively to the client that created the barrier, and to the window specified in the CreatePointerBarrier request (the "barrier window"). A pointer barrier blocks pointer movement regardless of whether its window is mapped and/or viewable. If the pointer barrier window is destroyed, the pointer barrier remains blocking but a client will not receive further events.

If a device is actively grabbed by a client or a passive grab activated for this client, and the pointer moves against a pointer barrier created by this client and the grab-window is the barrier window, that client will receive pointer barrier events if: - owner-events is true or false and the grab’s event mask includes pointer barrier events, or - owner-events is true and the client has selected for barrier events on the barrier window.

If the grab-window is not the barrier window, the client will receive events if: - the client has selected for barrier events on the barrier window.

If the barrier is not owned by this client, no barrier events are sent to this client. The client owning the barrier will receive events if: - the client has pointer barrier events selected on the window associated with the pointer barrier

The BarrierDeviceIsGrabbed flag is set whenever a pointer barrier event is generated while the device is actively grabbed by any client or a passive grab has activated for this device prior to the event.

10. Notations used in this document

Notation for requests:

┌───
    Name of request
        name of request field:       type of request field
        name of request field:       type of request field
        ▶
        name of reply field:         type of reply field
└───

Notation for events:

┌───
    Name of event
        name of field:               type of field
        name of field:               type of field
└───

Complex fields are specified in the following notation:

name of field:                  COMPLEXFIELDTYPE

or, if multiple of these fields exist:

name of field:                  LISTofCOMPLEXFIELDTYPE
COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
                     name of subfield:   type of subfield }

11. Data types

BUTTONMASK
        A binary mask defined as (1 << button number).
        A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK.
DEVICE { DEVICEID, AllDevices, AllMasterDevices }
        A DEVICE specifies either a DEVICEID or AllDevices or
        AllMasterDevices.
DEVICEID { CARD16 }
        A DEVICEID is a numerical ID for a device currently available in the
        server. The server may re-use a device ID after a device's removal.
        The device IDs 0 and 1 are reserved.
        AllDevices ........ 0
        AllMasterDevices .. 1
DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer,
            SlaveKeyboard, FloatingSlave }
        A DEVICEUSE field specifies the current use of a device in the MD/SD
        device hierarchy. See Section "The Master/Slave device hierarchy"
        for more information.
EVENTMASK
        An EVENTMASK is a binary mask defined as (1 << event type).
        A SETofEVENTMASK is a binary OR of zero or more EVENTMASK.
FP1616
        Fixed point decimal in 16.16 format as one INT16 and one CARD16.
        The INT16 contains the integral part, the CARD16 the decimal fraction
        shifted by 16.
FP3232
        Fixed point decimal in 32.32 format as one INT32 and one CARD32.
        The INT32 contains the integral part, the CARD32 the decimal fraction
        shifted by 32.
MODIFIERMASK
        A MODIFIERMASK is a binary mask defined as (1 << modifier map index).
        A SETofMODIFIERMASK is a binary OR of zero or more MODIFIERMASK or
        GrabAnyModifier.
VALUATORMASK
        A binary mask defined as (1 << valuator number).
        A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK.

12. Errors

Errors are sent using core X error reports.

Device
        A value for a DEVICE argument does not specify a valid DEVICE.

13. Requests

The server does not guarantee that the length of a reply remains constant in future revisions of XI2. A client must always retrieve the exact length of the protocol reply from the connection, even if the reply is longer than defined for the XI2 version supported by the client. Additional bytes in a request may include data supported in later versions of XI2. Clients should ignore this data. Padding bytes in XI2 protocol requests are required to be 0.

13.1. Requests introduced in version 2.0

13.1.1. XIQueryVersion

┌───
    XIQueryVersion
    major_version:          CARD16
    minor_version:          CARD16
    ▶
    major_version:          CARD16
    minor_version:          CARD16
└───

The client sends the highest supported version to the server and the server sends the highest version it supports, but no higher than the requested version. Major versions changes can introduce incompatibilities in existing functionality, minor version changes introduce only backward compatible changes. It is the client’s responsibility to ensure that the server supports a version which is compatible with its expectations.

major_version
    Major XI2 version.
minor_version
    Minor XI2 version.

If major_version is less than 2, a BadValue error occurs.

13.1.2. XIQueryDevice

┌───
    XIQueryDevice
    DEVICE                  deviceid
    ▶
    num_devices:            CARD16
    deviceinfo:             LISTofDEVICEINFO
└───
DEVICEINFO { deviceid:              DEVICEID
             use:                   DEVICEUSE
             attachment:            DEVICEID
             enabled:               BOOL
             num_classes:           CARD16
             name_len:              CARD16
             name:                  LISTofCHAR8
             classes:               LISTofCLASS }
CLASS { BUTTONCLASS, KEYCLASS, VALUATORCLASS, SCROLLCLASS, TOUCHCLASS }
BUTTONCLASS   { type:                 ButtonClass
                length:               CARD16
                sourceid:             CARD16
                num_buttons:          CARD16
                state:                SETofBUTTONMASK
                labels:               LISTofATOM }
KEYCLASS      { type:                 KeyClass
                length:               CARD16
                sourceid:             CARD16
                num_keys:             CARD16
                keys:                 LISTofCARD32 }
VALUATORCLASS { type:                 ValuatorClass
                length:               CARD16
                sourceid:             CARD16
                number:               CARD16
                label:                ATOM
                min:                  FP3232
                max:                  FP3232
                value:                FP3232
                resolution:           CARD32
                mode:                 CARD8 }
SCROLLCLASS¹  { type:                 ScrollClass
                length:               CARD16
                sourceid:             CARD16
                number:               CARD16
                scroll_type:          SCROLLTYPE
                flags:                SETofSCROLLFLAGS
                increment:            FP3232 }
SCROLLTYPE { Vertical, Horizontal }
SCROLLFLAGS { NoEmulation, Preferred }
TOUCHCLASS² { type:                 TouchClass
              length:               CARD16
              sourceid:             CARD16
              mode:                 TOUCHMODE
              num_touches:          CARD16 }
TOUCHMODE { DirectTouch, DependentTouch }
¹ since XI 2.1
² since XI 2.2

XIQueryDevice details information about the requested input devices.

devices
    The device to list. If devices is AllDevices, all enabled and
    disabled devices are listed. If devices is AllMasterDevices, all
    enabled and disabled master devices are listed. If devices is a
    valid DEVICE, only this DEVICE is listed and num_devices is 1.
num_devices
    The number of deviceinfos returned.

Each deviceinfo is detailed as follows:

deviceid
    The unique ID of the device. Device IDs may get re-used when a device
    is removed.
use
    If the device is a master pointer, use is MasterPointer.
    If the device is a master keyboard, use is MasterKeyboard.
    If the device is a slave pointer, use is SlavePointer.
    If the device is a slave keyboard, use is SlaveKeyboard.
    If the device is a floating slave, use is FloatingSlave.
attachment
    If the device is a master pointer or a master keyboard, attachment
    specifies the paired master keyboard, or the paired master pointer,
    respectively.  If the device is a non-floating slave device
    attachment specifies the master device this device is attached to.
    If the device is a floating slave, attachment is undefined.
enabled
    Zero if the device is disabled, non-zero otherwise.
num_classes
    Number of classes provided.
name_len
    Length of the name in bytes not including padding.
classes
    Details the available classes provided by the device in an undefined
    order.
name
    The device's name. padded to a multiple of 4 bytes.

For all classes, type specifies the device class. Clients are required to ignore unknown device classes. The length field specifies the length of the class in 4 byte units. The following classes may occur only once: ButtonClass, KeyClass

ButtonClass:
type
    Always ButtonClass.
length
    Length in 4 byte units.
sourceid
    The device this class originates from.
num_buttons
    Number of buttons provided by the device.
labels
    List of Atoms specifying the label for each button. An Atom of None
    specifies an unlabeled button. Buttons are listed in the device-native
    order regardless of the current button mapping.
state
    The current button mask for this device after button mapping is
    applied. Each bit representing a button is 1 if this button is
    logically down, or 0 otherwise. State is a multiple of 4-byte units
    and always contains at least num_buttons bits.
KeyClass:
type
    Always KeyClass.
length
    Length in 4 byte units.
sourceid
    The device this class originates from.
num_keys
    Number of keycodes provided by the device.
keys
    List of keycodes provided.
ValuatorClass:
type
    Always ValuatorClass.
length
    Length in 4 byte units.
sourceid
    The device this class originates from.
number
    Valuator number of this axis. The valuator number is in device-native
    order and potential axis mappings are ignored.
label
    Atom specifying the axis name. An Atom of None specifies an unlabeled
    axis.
min
    Minimum value.
max
    Minimum value.
resolution
    Resolution in counts/meter.
mode
    Relative or Absolute.
value
    Last published axis value (if mode is absolute).

An axis in Relative mode may specify min and max as a hint to the client. If no min and max information is available, both must be 0.

ScrollClass:
type
    Always ScrollClass.
number
    Valuator number that is referred to. This valuator number must be listed in
    the ValuatorClassInfo.
scroll_type:
    Vertical for a vertical scrolling axis, Horizontal for a horizontal
    scrolling axis.
flags:
    A set of flags that apply to this scroll axis.
    NoEmulation: no legacy scroll button events are generated for events
                 on this scrolling axis.
    Preferred: This axis is the preferred axis for emulating valuator
               events from legacy scroll button events.
increment:
    The valuator delta equivalent to one positive unit of scrolling.

A ScrollClass may only exist if the device has at least one ValuatorClass and each valuator number listed in any ScrollClass. Only one ScrollClass may exist per ValuatorClass.

TouchClass:
type
    Always TouchClass.
length
    Length in 4 byte units.
sourceid
    The device this class originates from.
mode
    The device type of the touch device.  This mode may change at runtime.
num_touches
    The maximum number of simultaneous touchpoints the device may send.
    If num_touches is 0, the number of supported touches is unknown or
    unlimited.

Devices with a TouchClass emit touch events with the same axes as pointer events.

13.1.3. XISelectEvents

┌───
    XISelectEvents
        window:         Window
        num_masks:      CARD16
        masks:          LISTofEVENTMASK
└───
EVENTMASK { deviceid:          DEVICE,
            mask_len:          CARD16,
            mask:              SETofEVENTMASK
window
    The window to select the events on.
num_masks
    Number of items in masks.
deviceid
    Numerical deviceid, or AllDevices, or AllMasterDevices.
mask_len
    Length of mask in 4 byte units.
mask
    Event mask. An event mask for an event type T is defined as (1 << T).

XISelectEvents selects for XI2 events on window.

If num_masks is 0, a BadValue error occurs.

Each mask sets the (and overwrites a previous) event mask for the DEVICE specified through deviceid. The device AllDevices or AllMasterDevices is treated as a separate device by server. A client’s event mask is the union of AllDevices, AllMasterDevices and the per-device event mask. The removal of device from the server unsets the event masks for the device. If an event mask is set for AllDevices or AllMasterDevices, the event mask is not cleared on device removal and affects all future devices.

If mask_len is 0, the event mask for the given device is cleared.

The mask for XIHierarchyEvents may only be selected for XIAllDevices. Setting it for any other device results in a BadValue error.

A client selecting for any of XI_TouchBegin, XI_TouchUpdate, or XI_TouchEnd must select for all three events at the same time, else a BadValue error will be generated. A client selecting for XI_TouchOwnership must select for all three of the other touch events. If the selection for these touch events overlaps a current selection by another client (e.g. selecting for a specific device when another client has a selection for XIAllDevices), a BadAccess error occurs.

13.1.4. XIGetSelectedEvents

┌───
    XIGetSelectedEvents
        window:         Window
        ▶
        num_masks:      CARD16
        masks:          LISTofEVENTMASK
└───
window
    The window to select the events on.
num_masks
    Number of items in masks.
masks
    Selected event masks by this client.

Masks are returned on a per-device basis, with masks for AllDevices and AllMasterDevices returned separately. A client can calculate the effective mask for a device with a bitwise OR of the AllDevices, the AllMasterDevices and the device-specific mask.

If num_masks is 0, no events have been selected by this client on the given window.

13.1.5. XIQueryPointer

┌───
    XIQueryPointer
        window:         Window
        deviceid:       DEVICEID
        ▶
        root:           Window
        child:          Window
        root_x:         FP1616
        root_y:         FP1616
        win_x:          FP1616
        win_y:          FP1616
        same_screen:    BOOL
        mods:           MODIFIERINFO
        group:          GROUPINFO
        buttons_len:    CARD16
        buttons:        SETofBUTTONMASK
└───

Query a master pointer device for its current position.

root
    The root window the pointer is logically on.
child
    The child window of window that contains the pointer or None.
root_x
root_y
    Pointer position relative to the root window's origin.
win_x
win_y
    Pointer position relative to window or 0 if same_screen is false.
same_screen
    True if window is on the same screen as the pointer.
mods
    XKB modifier state on the paired device.
group
    XKB group state on the paired device.
buttons_len
    The length of buttons in 4 byte units.
buttons
    Button state.

If the device is not a master pointer device or not a floating slave pointer, a BadDevice error results.

13.1.6. XIWarpPointer

┌───
    XIWarpPointer
        src_win:         Window
        dst_win:         Window
        src_x:           FP1616
        src_y:           FP1616
        src_width:       INT16
        src_height:      INT16
        dst_x:           FP1616
        dst_y:           FP1616
        deviceid:        DEVICEID
└───

WarpPointer moves the pointer of deviceid as if the user had moved the pointer. WarpPointer can only be called for MasterPointer and FloatingSlave devices.

src_win
   If src_window is not None, the move only takes place if src_window
   contains the pointer and the pointer is contained in the specified
   rectangle of src_window.
dst_win
   If dst_win is None, this request moves the pointer by offsets
   dst_x/dst_y relative to the current position of the pointer. If
    dst_window is a window, this request moves the pointer to
   dst_x/dst_y relative to dst_win's origin.
src_x
src_y
src_width
src_height
   Specifies the source window rectangle.
dst_x
dst_y
    The relative coordinates to move the pointer if dst_win is None, or
    the absolute coordinates if dst_win is a window.
deviceid
    The device to warp.

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

This request will generate events just as if the user had instantaneously moved the pointer.

13.1.7. XIChangeCursor

┌───
    XIChangeCursor
        win:             Window
        cursor:          Cursor
        deviceid:        DEVICEID
└───

Change a master pointer’s cursor on the specified window.

window
    The window.
cursor
    The new cursor or None.
deviceid
    The master pointer device.

Whenever device enters a window W, the cursor shape is selected in the following order:

  • if the current window has a device cursor C(d) defined for device, display this cursor C(d).

  • otherwise, if the current window has a cursor C(w) defined in the core protocol’s window attributes, display cursor C(w).

  • repeat on parent window until a cursor has been found.

The device cursor for a given window is reset once the window is destroyed or the device is removed, whichever comes earlier.

If deviceid does not specify a master pointer, a BadDevice error is returned.

13.1.8. XIChangeHierarchy

┌───
    XIChangeHierarchy
        num_changes:     CARD8
        changes:         LISTofHIERARCHYCHANGES
└───
HIERARCHYCHANGE { ADDMASTER, REMOVEMASTER, ATTACHSLAVE, DETACHSLAVE }
HIERARCHYCHANGETYPE { AddMaster, RemoveMaster, AttachSlave, DetachSlave }
CHANGEMODE { Float, Attach }
ADDMASTER { type:        HIERARCHYCHANGETYPE
            length:      CARD16
            name_len:    CARD16
            send_core:   BOOL
            enable:      BOOL
            name:        LISTofCHAR8 }
REMOVEMASTER { type:            HIERARCHYCHANGETYPE
               length:          CARD16
               deviceid:        DEVICEID
               return_mode:     CHANGEMODE
               return_pointer:  DEVICEID
               return_keyboard: DEVICEID }
ATTACHSLAVE   { type:        HIERARCHYCHANGETYPE
                length:      CARD16
                deviceid:    DEVICEID
                master:      DEVICEID }
DETACHSLAVE { type:       HIERARCHYCHANGETYPE
              length:     CARD16
              deviceid:   DEVICEID }

XIChangeHierarchy allows a client to modify the Master/Slave device hierarchy.

num_changes
    The number of changes to apply to the current hierarchy.
changes
    The list of changes.

The server processes the changes in the order received from the client and applies each requested change immediately. If an error occurs, processing stops at the current change and returns the number of successfully applied changes in the error.

ADDMASTER creates a pair of master devices.
type
    Always AddMaster.
length
    Length in 4 byte units.
name_len
    Length of name in bytes.
send_core
    True if the device should send core events.
enable
    True if the device is to be enabled immediately.
name
    The name for the new master devices. The master pointer's name is
    automatically appended with " pointer", the master keyboard's name is
    automatically appended with " keyboard".
REMOVEMASTER removes an existing master device.
type
    Always RemoveMaster.
length
    Length in 4 byte units.
deviceid
    The device to remove.
return_mode
    Return mode for attached slave devices.
    If return_mode is Float, all slave devices are set to floating.
    If return_mode is Attach, slave pointers are attached to
    return_pointer and slave keyboards are attached to
    return_keyboard.
return_pointer
return_keyboard
    The master pointer and master keyboard to attach slave devices to, if
    return_mode is Attach. If return_mode is Float, return_pointer
    and return_keyboard are undefined.

Removing a master pointer removes the paired master keyboard and vice versa.

ATTACHSLAVE attaches a slave device to a given master device.
type
    Always ChangeAttachment.
length
    Length in 4 byte units.
deviceid
    Deviceid of the slave device.
master
    The new master device to attach this slave device to.

If any clients are selecting for touch events from the slave device, their selection will be canceled.

DETACHSLAVE detaches a slave device from its current master device.
type
    Always ChangeAttachment.
length
    Length in 4 byte units.
deviceid
    Deviceid of the slave device.

13.1.9. XISetClientPointer

┌───
    XISetClientPointer
        win:             Window
        deviceid:        DEVICEID
└───

Set the ClientPointer for the client owning win to the given device.

win
     Window or client ID.
deviceid
     The master pointer or master keyboard that acts as ClientPointer.

Some protocol requests are ambiguous and the server has to choose a device to provide data for a request or a reply. By default, the server will choose a client’s ClientPointer device to provide the data, unless the client currently has a grab on another device. See section The ClientPointer principle for more details.

If win is None, the ClientPointer for this client is set to the given device. Otherwise, if win is a valid window, the ClientPointer for the client owning this window is set to the given device. Otherwise, if win is not a valid window but a client with the client mask equal to win exists, this client’s ClientPointer is set to the given device.

If deviceid does not specify a master pointer or master keyboard, a BadDevice error is returned.

If window does not specify a valid window or client ID and is not None, a BadWindow error is returned.

13.1.10. XIGetClientPointer

┌───
    XIGetClientPointer
        win:             Window
        ▶
        set:             BOOL
        deviceid:        DEVICEID
└───

Query the ClientPointer for the client owning win.

win
    The window or client ID.
set
    True if the client has a ClientPointer set.
deviceid
    The master pointer that acts as a ClientPointer if set is True.

No difference is made between a ClientPointer set explicitly through XISetClientPointer and a ClientPointer implicitly assigned by the server in response to an ambiguous request.

13.1.11. XISetFocus

┌───
    XISetFocus
        focus:           Window
        deviceid:        DEVICEID
        time:            Time
└───

Set the focus for the given device to the given window. Future key events from this device are sent to this window. This request generates FocusIn and FocusOut events.

focus
    A viewable window or None.
deviceid
    The device to modify the focus window for.
time
    Specifies the time to change the focus or CurrentTime.

If focus is None, key events from this device are discarded until a new focus window is set. If focus is a viewable window, key events from this device are sent to this window. If the window becomes unviewable, the window’s first viewable ancestor automatically becomes the focus window and FocusIn and FocusOut events are sent as if a client had changed the focus window. This is equivalent to RevertToParent in the core XSetInputFocus window.

This request has no effect if the specified time is earlier than the current last-focus-change time or is later than the current X server time. Otherwise, the last-focus-change time is set to the specified time.

13.1.12. XIGetFocus

┌───
    XIGetFocus
        deviceid:        DEVICEID
        ▶
        focus:           Window
└───

Return the current focus window for the given device.

13.1.13. XIGrabDevice

┌───
    XIGrabDevice
        deviceid:        DEVICEID
        grab_window:     Window
        owner_events:    BOOL
        grab_mode:       { Synchronous, Asynchronous }
        paired_device_mode: { Synchronous, Asynchronous }
        time:            TIMESTAMP or CurrentTime
        cursor:          Cursor
        mask_len:        CARD16
        masks:           SETofEVENTMASK
        ▶
        status:          Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable
└───

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 overides any previous active grab by this client for this device. This request does not affect the processing of XI 2.2 touch events.

deviceid
    The device to grab.
grab_window
    Events are reported relative to the grab window.
owner_events
    Specifies whether event will be reported normally or relative to the
    grab window.
grab_mode
    Specifies if this device will be frozen as a result of the grab.
paired_device_mode
    Specifies if the master device paired with this device will be frozen
    as a result of the grab.
time
    A valid server time or CurrentTime.
cursor
    The cursor to display for the duration of the grab or None.
mask_len
    Length of mask in 4 byte units.
mask
    Event mask. An event mask for an event type T is defined as (1 << T).
status
    Success or the reason why the grab could not be established.

The masks parameter specifies which events the client wishes to receive while the device is grabbed.

If owner-events is False, 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 True, 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.

If grab-mode is Asynchronous, device event processing continues normally. If the device is currently frozen by this client, then processing of device events is resumed. If grab-mode is Synchronous, 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 XIAllowEvents 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.

If the device is a slave device, the paired-device-mode is ignored. Otherwise, if this device is a master device and paired-device-mode is Asynchronous, event processing is unaffected by activation of the grab. If this device is a master device and paired-device-mode is Synchronous, the state of the master device paired with this device (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 XIAllowEvents 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.

If the cursor is not None and the device is a master pointer device, the cursor will be displayed until the device is ungrabbed.

This request fails and returns:

AlreadyGrabbed: If the device is actively grabbed by some other client.
NotViewable: If grab-window is not viewable.
InvalidTime: 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 CurrentTime is replaced by the
             current X server time.
Frozen: If the device is frozen by an active grab of another client.

To release a grab of a device, use XIUngrabDevice.

13.1.14. XIUngrabDevice

┌───
    XIUngrabDevice
        deviceid:        DEVICEID
        time:            TIMESTAMP or CurrentTime
└───

This request releases the device if this client has it actively grabbed (from either XIGrabDevice or XIPassiveGrabDevice) and releases any queued events. If any devices were frozen by the grab, XIUngrabDevice thaws them.

deviceid
    The device to grab.
time
    A valid server time or CurrentTime.

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. This request generates FocusIn and FocusOut events. An XIUngrabDevice is performed automatically if the event window for an active device grab becomes not viewable.

13.1.15. XIAllowEvents

┌───
    XIAllowEvents
        deviceid:        DEVICEID
        time:            TIMESTAMP or CurrentTime
        event_mode:      { AsyncDevice, SyncDevice,
                           AsyncPairedDevice, SyncPairedDevice,
                           ReplayDevice, AsyncPair, SyncPair,
                           AcceptTouch¹, RejectTouch¹ }
        touchid¹:        CARD32
        grab_window¹:    Window
└───
¹ since XI 2.2

The XIAllowEvents request releases some queued events if the client has caused a device to freeze. It also is used to handle touch grab and ownership processing.

deviceid
    The device to grab.
time
    A valid server time or CurrentTime.
event_mode
    Specifies whether a device is to be thawed and events are to be
    replayed, or how to handle a grabbed touch sequence.
touchid
    The ID of the touch sequence to accept or reject. The value is undefined
    for event modes other than AcceptTouch and RejectTouch.
grab_window
    The window on which to accept or reject a touch sequence grab. The value
    is undefined for event modes other than AcceptTouch and RejectTouch.

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. The time parameter must be CurrentTime for requests with event modes of AcceptTouch and RejectTouch.

When event-mode is AcceptTouch, a BadValue error occurs if the touch ID is invalid. A BadAccess error occurs if this client is not the current or potential owner of the specified touch ID.

The following describes the processing that occurs depending on what constant you pass to the event-mode argument:

AsyncDevice:
    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, AsyncDevice thaws for
    all.
    AsyncDevice has no effect if the specified device is not frozen by the
    client, but the device need not be grabbed by the client.
SyncDevice:
    If the specified device is frozen and actively grabbed by the client,
    event processing for that device continues normally until the next
    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.
    SyncDevice has no effect if the specified device is not frozen by the
    client or is not grabbed by the client.
 ReplayDevice:
    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 XIGrabButton or from a previous XIAllowEvents with
    mode SyncDevice, 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.
 AsyncPairedDevice
    If the paired master device is frozen by the client, event processing
    for it continues as usual. If the paired device is frozen multiple
    times by the client on behalf of multiple separate grabs,
    AsyncPairedDevice thaws for all.
    AsyncPairedDevice has no effect if the device is not frozen by the
    client, but those devices need not be grabbed by the client.
    AsyncPairedDevice has no effect if deviceid specifies a slave device.
 SyncPairedDevice
    If the paired master device is frozen by the client, event processing (for
    the paired master device) continues normally until the next button or key
    event is reported to the client for the grabbed device (button event for
    the grabbed device, key or motion event for the device), at which time
    the device again appears to freeze. However, if the reported event causes
    the grab to be released, then the device does not freeze.
    SyncPairedDevice has no effect if the specified device is not grabbed
    by the client or if it is no frozen as the result of an event.
    SyncPairedDevice has no effect if deviceid specifies a slave device.
 SyncPair
    If both the device and the paired master device are frozen by the
    client, event processing (for both devices) continues normally until
    the next XIButtonPress, XIButtonRelease, XIKeyPress, or XIKeyRelease
    event is reported to the client for a grabbed device (button event for
    a pointer, key event for a keyboard), 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 the other device is
    still grabbed, then a subsequent event for it will still cause both
    devices to freeze).
    SyncPair has no effect unless both the device and the paired master
    device are frozen by the client. If the device or paired master device
    is frozen twice by the client on behalf of two separate grabs,
    SyncPair thaws for both (but a subsequent freeze for SyncPair will
    only freeze each device once).
    SyncPair has no effect if deviceid specifies a slave device.
 AsyncPair
    If the device and the paired master device are frozen by the client,
    event processing for both devices continues normally. If a device is
    frozen twice by the client on behalf of two separate grabs, AsyncBoth
    thaws for both. AsyncPair has no effect unless both the device and the
    paired master device frozen by the client.
    AsyncPair has no effect if deviceid specifies a slave device.
 AcceptTouch
    The client is deemed to have taken control of the touch sequence once it
    owns the sequence. TouchEnd events will be sent to all clients listening
    to the touch sequence that have either grabbed the touch sequence on a
    child window of the grab_window or have received events for the touch
    sequence through event selection. These clients will no longer receive
    any TouchUpdate events.
 RejectTouch
    The client is no longer interested in the touch sequence, and will
    receive a TouchEnd event. If the client is the current owner of the
    sequence, ownership will be passed on to the next listener.

13.1.16. XIPassiveGrabDevice

┌───
    XIPassiveGrabDevice
        deviceid:        DEVICE
        detail:          CARD32
        grab_type:       GRABTYPE
        grab_window:     Window
        cursor:          Cursor
        owner_events:    Bool
        grab_mode:       { Synchronous, Asynchronous, Touch¹ }
        paired_device_mode: { Synchronous, Asynchronous }
        num_modifiers:   INT16
        mask_len:        CARD16
        masks:           SETofEVENTMASK
        modifiers:       LISTofSETofMODIFIERMASK
        ▶
        num_modifiers_return:    INT16
        modifiers_return:        LISTofGRABMODIFIERINFO
└───
GRABTYPE         { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
                   GrabtypeFocusIn, GrabtypeTouchBegin¹ }
GRABMODIFIERINFO {   status:    Access
                     modifiers: SETofMODIFIERMASK }
¹ since XI 2.2

Establish an explicit passive grab for a button or keycode on the specified input device.

cursor
    The cursor to display for the duration of the grab. If grab_type
    is not GrabtypeButton, this argument is ignored.
deviceid
    The device to establish the passive grab on or AllDevices or
    AllMasterDevices.
detail
    The button number, or key symbol to grab for.
    Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
    GrabtypeTouchBegin.
grab_type
    The type of grab to establish.
grab_window
    Events are reported relative to the grab window.
grab_mode
    If grab-mode is Asynchronous, device event processing continues
    normally.  If the device is currently frozen by this client, then
    processing of device events is resumed. If grab-mode is
    Synchronous, 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 XIAllowEvents 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. If grab_type
    is GrabtypeTouchBegin, grab_mode must be set to Touch.
mask_len
    Length of mask in 4 byte units.
mask
    Event mask. An event mask for an event type T is defined as (1 << T).
modifiers
    XKB modifier state to activate this passive grab.
num_modifiers
    Number of elements in modifiers.
owner_events
    Specifies whether event will be reported normally or relative to the
    grab window.
num_modifiers_return
    Number of elements in modifiers_return
modifiers_return
    XKB modifier state that could not be grabbed.

If owner-events is False, 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 True, 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.

If deviceid specifies a master pointer, the modifiers of the paired master keyboard are used. If deviceid specifies a slave pointer the modifiers of the master keyboard paired with the attached master pointers are used. If deviceid specifies a slave keyboard, the modifiers of the attached master keyboard are used. Note that activating a grab on a slave device detaches the device from its master. In this case, the modifiers after activation of the grab are from the slave device only and may be different to the modifier state when the grab was triggered.

In the future, if grab_type is GrabtypeButton or GrabtypeKeyboard, the device is actively grabbed if:

  • the device is not grabbed, and

  • the specified modifier keys are down, and

  • the grab_type is GrabtypeButton and the button specified in detail is logically pressed or the grab_type is GrabtypeKeycode and the keycode specified in detail is logically pressed, and

  • the grab_window contains the pointer, and

  • a passive grab on the same button/keycode + modifier combination does not exist on an ancestor of grab_window.

Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the device is actively grabbed if:

  • the device is not actively grabbed, and

  • the specified modifier keys are down, and

  • the grab_type is GrabtypeEnter and the device’s pointer has moved into grab_window or a descendant of grab_window, or the grab_type is GrabtypeFocusIn and the device’s focus has been set to the grab_window or a descendant of grab_window, and

  • a passive grab of the same grab_type + modifier combination does not does not exist on an ancestor of grab_window.

Otherwise, if grab_type is GrabtypeTouchBegin, a touch grab begins if:

  • the device is not actively grabbed, and

  • the specified modifier keys are down

  • a touch begins in grab_window or a descendant of grab_window, and

  • a passive grab of the same grab_type + modifier combination does not does not exist on an ancestor of grab_window.

Ownership of the touch sequence is granted to the grabbing client if:

  • a TouchBegin or pointer grab for an emulated touch sequence of a direct touch device with the same modifier set does not exist on an ancestor of grab_window, or all applicable grabs have released ownership.

A modifier of GrabAnyModifier is equivalent to issuing the request for all possible modifier combinations (including no modifiers). A client may request a grab for GrabAnyModifier and explicit modifier combinations in the same request.

A GrabtypeButton or GrabtypeKeyboard grab is released when all buttons or keycode are released, independent of the state of modifier keys. A GrabtypeEnter or GrabtypeFocusIn grab is released when the pointer or focus leaves the window and all of its descendants, independent of the state of modifier keys. A GrabtypeTouchBegin grab is released when the touch sequence ends or the client uses XIAllowEvents with mode RejectTouch. 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.

This request overrides all previous passive grabs by the same client on the same button/key/enter/focus in + modifier combinations on the same window.

If some other client already has issued a XIPassiveGrabDevice request with the same button or keycode and modifier combination, the failed modifier combinations is returned in modifiers_return. If some other client already has issued an XIPassiveGrabDevice request of grab_type XIGrabtypeEnter, XIGrabtypeFocusIn, or XIGrabtypeTouchBegin with the same grab_window and the same modifier combination, the failed modifier combinations are returned in modifiers_return. If num_modifiers_return is zero, all passive grabs have been successful.

If a button grab or enter grab activates, EnterNotify and LeaveNotify events with mode Grab are generated as if the pointer were to suddenly warp from its current position some position in the grab_window. However, the pointer does not warp, and the pointer position is used as both the initial and final positions for the events.

If a keycode grab or focus grab activates, FocusIn and FocusOut events with mode Grab are generated as if the focus were to change from the current window to the grab_window.

If an enter or focus in grab activates, additional EnterNotify events with mode XIPassiveGrabNotify are generated as if the pointer or focus were to suddenly warp from its current position to some position in the grab window. These events are sent to the grabbing client only and only if the grab event mask has selected for it. If such a passive grab deactivates, addional LeaveNotify events with mode XIPassiveUngrabNotify are generated and sent to the grabbing client before the grab deactivates.

For GrabtypeTouchBegin, grab_mode must be Touch or a BadValue error is generated.

See section Ownership of touch sequences for additional notes on touch grabs, as they do not behave like traditional grabs: in particular, they do not freeze the device, and delivery of touch events continues even if the device is frozen due to a grab by another client.

13.1.17. XIPassiveUngrabDevice

┌───
    XIPassiveUngrabDevice
        deviceid:        DEVICEID
        detail:          CARD32
        grab_type:       GRABTYPE
        grab_window:     Window
        num_modifiers:   INT16
        modifiers:       LISTofSETofMODIFIERMASK
└───

Release an explicit passive grab on the specified input device.

deviceid
    The device to establish the passive grab on.
detail
    The button number or key symbol to ungrab.
    Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
    GrabtypeTouchBegin.
grab_type
    The type of grab to establish.
grab_window
    Events are reported relative to the grab window.
modifiers
    XKB modifier state to activate this passive grab.
num_modifiers
    Number of elements in modifiers.

This request has no effect if the client does not have a passive grab of the same type, same button or keycode (if applicable) and modifier combination on the grab_window.

13.1.18. XIListProperties

┌───
    XIListProperties
        deviceid:        DEVICEID
        ▶
        num_properties:  INT16
        properties:      LISTofATOM
└───

List the properties associated with the given device.

deviceid
    The device to list the properties for.
num_properties
    Number of properties in the reply
properties
    All properties on the device.

13.1.19. XIChangeProperty

┌───
    XIChangeProperty
        deviceid:        DEVICEID
        property:        ATOM
        type:            ATOM
        format:          { 8, 16, 32 }
        mode:            { Append, Prepend, Replace }
        num_items:       CARD32
        data:            LISTofINT8, or LISTofINT16, or LISTofINT32
└───

Change the given property on the given device.

deviceid
    The device to change the property on.
property
    The property to modify.
type
    The property's type.
mode
    One of Append, Prepend, or Replace
num_items
    Number of items following this request.
data
    Property data (nitems * format/8 bytes)

The type is uninterpreted by the server. The format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities so that the server can correctly byte-swap as necessary.

If the mode is Replace, the previous propert y value is discarded. If the mode is Prepend or Append, then the type and format must match the existing property value (or a Match error results). If the property is undefined, it is treated as defined with the correct type and format with zero-length data. For Prepend, the data is tacked on to the beginning of the existing data, and for Append, it is tacked on to the end of the existing data.

The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the device is removed, or until server reset.

A property cannot be deleted by setting nitems to zero. To delete a property, use XIDeleteProperty.

This request generates an XIPropertyEvent.

13.1.20. XIDeleteProperty

┌───
    XIDeleteProperty
        deviceid:        DEVICEID
        property:        ATOM
└───

Deletes the given property on the given device.

deviceid
    The device to delete the property on.
property
    The property to delete.

If the property is deleted, an XIPropertyEvent is generated on the device. If the property does not exist, this request does nothing.

13.1.21. XIGetProperty

┌───
    XIGetProperty
        deviceid:        DEVICEID
        property:        ATOM
        type:            Atom or AnyPropertyType
        offset:          CARD32
        len:             CARD32
        delete:          BOOL
        ▶
        type:            Atom
        bytes_after:     CARD32
        num_items:       CARD32
        format:          { 8, 16, 32 }
        data:            LISTofINT8, or LISTofINT16, or LISTofINT32
└───

Get the data for the given property on the given device.

deviceid
    The device to retrieve the property data from.
property
    The property to retrieve the data from..
type
    The property type to retrieve or AnyPropertyType
offset
    The offset in 4-byte units.
len
    Number of bytes to receive in 4-byte units.
delete
    Delete the property after retrieving the data.
bytes_after
    Number of unread bytes in the stored property
num_items
    Number of items in data
format
    8, 16, or 32
data
    Property data (nitems * format/8 bytes)

If the specified property does not exist for the specified device, then the return type is None, the format and bytes-after are zero, and the value is empty. The delete argument is ignored in this case. If the specified property exists but its type does not match the specified type, then the return type is the actual type of the property, the format is the actual format of the property (never zero), the bytes-after is the length of the property in bytes (even if the format is 16 or 32), and the value is empty. The delete argument is ignored in this case. If the specified property exists and either AnyPropertyType is specified or the specified type matches the actual type of the property, then the return type is the actual type of the property, the format is the actual format of the property (never zero), and the bytes-after and value are as follows, given: N = actual length of the stored property in bytes (even if the format is 16 or 32) I = 4 * long-offset T = N−I L = MINIMUM(T, 4 * long-length) A = N − (I + L) The returned value starts at byte index I in the property (indexing from 0), and its length in bytes is L. However, it is a Value error if offset is given such that L is negative. The value of bytes_after is A, giving the number of trailing unread bytes in the stored property. If delete is True and the bytes_after is zero, the property is also deleted from the device, and a XIPropertyNotify event is generated on the device.

13.2. Requests introduced in version 2.3

13.2.1. XIBarrierReleasePointer

┌───
    XIBarrierReleasePointer
        num_items:       CARD32
        ▶
        data:            LISTofBARRIERRELEASEINFO
└───
BARRIERRELEASEINFO { deviceid: DEVICEID,
                     barrier:  Barrier,
                     eventid: CARD32 }

Release a pointer currently blocked by a barrier. In the future, movement of this pointer against the barrier will not be blocked.

deviceid
    The device currently being blocked by a barrier
barrier
    The barrier currently blocking the device
eventid
    The unique event ID assigned to this barrier event sequence

If the barrier given does not currently block this device, or the eventid is invalid, this request does nothing.

Releasing a pointer barrier is only valid during one barrier event sequence, and only applies to the next movement of this device against this barrier. If the pointer moves away from the barrier following a XIBarrierReleasePointer request, the release request is discarded. In the future, if the pointer moves against the barrier again, a new eventid is assigned and the client must re-issue the XIBarrierReleasePointer request.

If the device is not a master pointer device, a BadDevice error results. If the barrier does not name a valid barrier, a BadValue error results.

14. Events

An event specifies its length in 4-byte units after the initial 32 bytes. Future versions of the protocol may provide additional information in the same event, thus increasing the event size. Clients are required to always read the number of bytes specified by the event, not the size of the event they may have been compiled against.

The following event types are available in XI2.

Version 2.0:

  • HierarchyChanged

  • DeviceChanged

  • KeyPress

  • KeyRelease

  • ButtonPress

  • ButtonRelease

  • Motion

  • RawKeyPress

  • RawKeyRelease

  • RawButtonPress

  • RawButtonRelease

  • RawMotion

  • Enter

  • Leave

  • FocusIn

  • FocusOut

  • PropertyEvent

Version 2.2:

  • TouchBegin

  • TouchUpdate

  • TouchOwnership

  • TouchEnd

  • RawTouchBegin

  • RawTouchUpdate

  • RawTouchEnd

Version 2.3:

  • BarrierHit

  • BarrierLeave

All events have a set of common fields specified as EVENTHEADER.

EVENTHEADER { type:                       BYTE
              extension:                  BYTE
              sequenceNumber:             CARD16
              length:                     CARD32
              evtype:                     CARD16
              deviceid:                   DEVICEID
              time:                       Time }
type
    Always GenericEvent.
extension
    Always the X Input extension offset.
sequenceNumber
    Sequence number of last request processed by the server.
length
    Length in 4-byte units after the initial 32 bytes.
evtype
    XI-specific event type.
deviceid
    Numerical device id for a device.
time
    Time in ms when the event occurred.

14.1. Events introduced in version 2.0

14.1.1. HierarchyEvent

┌───
    HierarchyEvent
        EVENTHEADER
        flags:                      SETofHIERARCHYMASK
        num_info:                   CARD16
        info:                       LISTofHIERARCHYINFO
└───
HIERARCHYMASK { MasterAdded, MasterRemoved, SlaveAttached, SlaveDetached,
                SlaveAdded, SlaveRemoved, DeviceEnabled, DeviceDisabled }
HIERARCHYINFO { deviceid:           DEVICEID,
                attachment:         DEVICEID,
                type:               DEVICEUSE
                enabled:            BOOL
                flags:              SETofHIERARCHYMASK}
flags
    Set of the changes that have occured, causing this event.
num_info
    The number of device info structs following the request.
info:
    The current hierarchy information.

An XIHierarchyEvent is sent whenever the device hierarchy been changed. The flags specify all types of hierarchy modifiations that have occured. For all devices, info details the hierarchy information after the modification of the hierarchy has occured. For each device specified with deviceid:

  • if type is MasterPointer or MasterKeyboard, attachment decribes the pairing of this device.

  • if type is SlavePointer or SlaveKeyboard, attachment describes the master device this device is attached to.

  • if type is FloatingSlave device, attachment is undefined.

    enabled
         True if the device is enabled and can send events. A disabled master
         device will not forward events from an attached, enabled slave
         device.

Note: Multiple devices may be affected in one hierarchy change, deviceid in an XIHierarchyEvent is always the first affected device. Clients should ignore deviceid and instead use the devices list.

14.1.2. DeviceChangedEvent

┌───
    DeviceChangedEvent
        EVENTHEADER
        reason:                CHANGEREASON
        source:                DEVICEID
        num_classes:           CARD16
        classes:               LISTofCLASS
└───
CHANGEREASON { SlaveSwitch, DeviceChange }

A DeviceChangeEvent is sent whenever a device changes it’s capabilities. This can happen either by a new slave device sending events through a master device, or by a physical device changing capabilities at runtime.

reason
    The reason for generating this event.
    If reason is SlaveSwitch, the slave device sending events through
    this device has changed and source specifies the new slave device.
    A SlaveSwitch reason can only occur on a master device.
    If reason is DeviceChange, the device itself has changed through
    other means (e.g. a physical device change) and source is
    the device itself.
source
    The source of the new classes.
num_classes
    Number of classes provided.
classes
    Details the available classes provided by the device.  The order the
    classes are provided in is undefined.

For a detailed description of classes, see the XIQueryDevice request.

14.1.3. DeviceEvent

┌───
    DeviceEvent
        EVENTHEADER
        detail:                     CARD32
        root:                       Window
        event:                      Window
        child:                      Window
        root_x:                     FP1616
        root_y:                     FP1616
        event_x:                    FP1616
        event_y:                    FP1616
        buttons_len:                CARD16
        valuators_len:              CARD16
        sourceid:                   DEVICEID
        mods:                       MODIFIERINFO
        group:                      GROUPINFO
        flags:                      DEVICEEEVENTFLAGS
        buttons:                    SETofBUTTONMASK
        valuators:                  SETofVALUATORMASK
        axisvalues:                 LISTofFP3232
└───
BUTTONBIT { (1 << Button1), (1 << Button2), ... , (1 << ButtonN) }
VALUATORBIT { (1 << 1), ( 1 << 2), ... ( 1 << n) }
MODIFIERINFO  { base_mods:           CARD32,
                latched_mods:        CARD32,
                locked_mods:         CARD32,
                effective_mods:      CARD32}
GROUPINFO     { base_group:          CARD8,
                latched_group:       CARD8,
                locked_group:        CARD8,
                effective_group:     CARD8}
DEVICEEVENTFLAGS (all events): none
DEVICEEVENTFLAGS (key events only): { KeyRepeat }
DEVICEEVENTFLAGS (pointer events only): { PointerEmulated }
DEVICEEVENTFLAGS (touch events only): { TouchPendingEnd,
                                        TouchEmulatingPointer }

An XIDeviceEvent is generated whenever the logical state of a device changes in response to a button press, a button release, a motion, a key press or a key release. The event type may be one of KeyPress, KeyRelease, ButtonPress, ButtonRelease, Motion.

XI 2.2: The event type may also be TouchBegin, TouchUpdate, or TouchEnd.

detail
    The button number, key code, touch ID, or 0.
root
event
child
    The root window, event window or subwindow, respectively. See core
    protocol specification for more detail.
root_x
root_y
    The position of the pointer in screen coordinates (16.16 fixed point).
event_x
event_y
    The position of the pointer in screen coordinates relative to the
    event window (16.16 fixed point).
buttons_len
    The length of buttons in 4 byte units.
valuators_len
    The length of valuators in 4 byte units.
sourceid
    The source device that originally generated the event.
mods
    XKB modifier state before the event occured.
group
    XKB group state before the event.
buttons
    Button state before the event.
valuators
    Bitmask of valuators provided in axisvalues.
axisvalues
    Valuator data in device-native resolution. This is a non-sparse
    array, value N represents the axis corresponding to the Nth bit set
    in valuators.
flags
    Miscellaneous information about this event; the union of the
    common flag set and either the key or pointer flag set,
    depending on the event type.
    KeyRepeat means that this event is for repeating purposes, and
    the physical state of the key has not changed.  This is only
    valid for KeyPress events.
    PointerEmulated signals that the event has been emulated from another
    XI 2.x event for legacy client support, and that this event should
    be ignored if the client listens for these events.  This flag is
    set on scroll ButtonPress and RawButtonPress events (buttons 4, 5, 6
    and 7) if a smooth-scrolling event on the Rel Vert Scroll or
    Rel Horiz Scroll axes was also generated. It is also set on Motion,
    ButtonPress, and ButtonRelease events generated by direct touch devices.
    TouchPendingEnd (for touch events only) means that the touch
    has physically ended, however another client still holds a grab, so the
    touch should be considered alive until all grabbing clients have
    accepted or passed on ownership.  The touch will not generate any
    further TouchUpdate events once an event with TouchPendingEnd has been
    received.
    TouchEmulatingPointer is set on touch events that emulate pointer
    events.

Modifier state in mods is detailed as follows:

base_mods
    XKB base modifier state.
latched_mods
    XKB latched modifier state.
locked_mods
    XKB locked modifier state.

Group state in group is detailed as follows:

base_group
    XKB base group state.
latched_group
    XKB latched group state.
locked_group
    XKB locked group state.

In servers supporting XI 2.2, a TouchBegin event is generated whenever a new touch sequence initializes. A TouchEnd event is generated whenever a touch sequence ceases. A TouchUpdate event is generated whenever a valuator value changes, or a flag flag (e.g. pending end) has changed for that touch sequence; this may result in a TouchUpdate event being sent with zero valuators.

The average finger size is significantly larger than one pixel. The selection of the hotspot of a touchpoint is implementation dependent and may not be the logical center of the touch.

Touch tracking IDs are provided in the detail field of touch events. Its value is always provided in every touch event. Tracking IDs are represented as unsigned 32-bit values and increase strictly monotonically in value for each new touch, wrapping back to 0 upon reaching the numerical limit of IDs. The increment between two touch IDs is indeterminate. Clients may not assume that any future touches will have specific touch IDs. IDs are globally unique.

The button state in touch events represents the state of the device’s physical buttons only, even if that sequence is emulating pointer events.

Touch events do not generate enter/leave events.

14.1.4. RawEvent

┌───
    RawEvent
        EVENTHEADER
        detail:                    CARD32
        sourceid¹:                 DEVICEID
        flags:                     DEVICEEVENTFLAGS
        valuators_len:             CARD16
        valuators:                 SETofVALUATORMASK
        axisvalues:                LISTofFP3232
        axisvalues_raw:            LISTofFP3232
└───
¹ since XI 2.1

A RawEvent provides the information provided by the driver to the client. RawEvent provides both the raw data as supplied by the driver and transformed data as used in the server. Transformations include, but are not limited to, axis clipping and acceleration. Transformed valuator data may be equivalent to raw data. In this case, both raw and transformed valuator data is provided. RawEvents are sent exclusively to all root windows. Clients supporting XI 2.0 receive raw events when the device is not grabbed, or when the device is grabbed by the client but not when the device is grabbed by another client. Clients supporting XI 2.1 or later receive raw events at all times, even when the device is grabbed by another client.

eventtype
    The type of event that occured on the device.
detail
    The button number, keycode or touch ID¹.
sourceid
    The source device that originally generated the event. The sourceid
    is undefined for clients not supporting XI 2.1.
flags
    Flags as described in DeviceEvent.
valuators_len
    The length of valuators in 4 byte units.
valuators
    Bitmask of valuators provided in axisvalues and axisvalues_raw.
axisvalues
    Valuator data in device-native resolution. This is a non-sparse
    array, value N represents the axis corresponding to the Nth bit set
    in valuators.
axisvalues_raw
    Untransformed valuator data in device-native resolution. This is a
    non-sparse array, value N represents the axis corresponding to the
    Nth bit set in valuators.
¹ since XI 2.2

14.1.5. Enter or Leave or FocusIn or FocusOut

┌───
    Enter or Leave or FocusIn or FocusOut
        EVENTHEADER
        root:               Window
        event:              Window
        child:              Window
        sourceid:           DEVICEID
        root_x:             FP1616
        root_y:             FP1616
        event_x             FP1616
        event_y:            FP1616
        mode:               NOTIFYMODE
        detail:             NOTIFYDETAIL
        same_screen:        BOOL
        focus:              BOOL
        mods:               MODIFIERINFO
        group:              GROUPINFO
        buttons_len:        CARD16
        buttons:            SETofBUTTONMASK
└───
NOTIFYMODE { Normal, Grab, Ungrab }
NOTIFYDETAIL { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual,
               Pointer, PointerRoot, None }

Enter or Leave events are sent whenever a device’s pointer enters or leaves a window. FocusIn or FocusOut events are sent whenever a device’s focus is set to or away from a window. The enter/leave and focus in/out model is described in the core protocol specification, Section 11. (EnterNotify, LeaveNotify events).

For enter and leave events, the modifier and group state is the state of the paired master device if the device is a master device, or the state of the attached master keyboard if the device is an attached slave device, or zero if the device is a floating slave device.

For focus in and out events, the button state is the state of the paired master device if the device is a master device, or the state of the attached master keyboard if the device is an attached slave device, or zero if the device is a floating slave device.

root
event
child
    The root window, event window, and child window, respectively. See the
    core protocol specification for more detail.
sourceid
    The device that caused the pointer to move.
root_x
root_y
    The pointer coordinates relative to the root window.
event_x
event_y
    The pointer coordinates relative to the event window.
mode
    Normal pointer motion events have mode Normal. Pseudo-motion events
    when a grab activates have mode Grab, and pseudo-motion events when a
    grab deactivates have mode Ungrab. Pseudo-motion events caused by the
    activation or deactivation of a passive enter or focus in grab have mode
    XIPassiveGrabNotify or XIPassiveUngrabNotify.
detail
    Specifies the relation of the event window to the window the pointer
    entered or left. See the core protocol spec for details.
same_screen
    True if the event window is on the same screen as the pointer's root
    window.
focus
    If the event window is the focus window or an inferior of the focus
    window, then focus is True. Otherwise, focus is False. This field is
    unspecified for focus in/out events.
mods
    XKB modifier state before the event occured.
group
    XKB group state before the event.
buttons_len
    The length of buttons in 4 byte units.
buttons
    Button state before the event.

14.1.6. XIPropertyEvent

┌───
    XIPropertyEvent
        EVENTHEADER
        property:           ATOM
        what:               { PropertyCreated, PropertyDeleted, PropertyModified }
└───

XIPropertyEvents are sent whenever a device property is created, deleted or modified by a client.

property
    The property that has been created, deleted, or modified
what
    Specifies what has been changed.

14.2. Events introduced in version 2.2

14.2.1. TouchOwnershipEvent

┌───
    TouchOwnershipEvent
        EVENTHEADER
        touchid:                    CARD32
        root:                       Window
        event:                      Window
        child:                      Window
        sourceid:                   DEVICEID
        flags:                      SETofTOUCHOWNERSHIPFLAGS
└───
TOUCHOWNERSHIPFLAGS:    (none currently defined)

A TouchOwnershipEvent indicates that ownership has changed, and the client is now the owner of the touch sequence specified by touchid.

touchid
    The identifier of the touch sequence.
root
event
child
    The root window, event window, and child window, respectively. See the
    core protocol specification for more detail.
sourceid
    The source device that originally generated the event.
flags
    A bitmask of flags for this event.

14.3. Events introduced in version 2.3

14.3.1. BarrierEvent

┌───
    BarrierEvent
        EVENTHEADER
        eventid:                    CARD32
        root:                       Window
        event:                      Window
        barrier:                    Barrier
        dtime:                      CARD32
        flags:                      SETofBARRIERFLAGS
        sourceid:                   DEVICEID
        root_x:                     FP1616
        root_y:                     FP1616
        dx:                         FP3232
        dy:                         FP3232
└───
BARRIERFLAGS { PointerReleased, DeviceIsGrabbed }

A BarrierEvent indicates interaction between a barrier and a pointer device. If the event type is BarrierHit, pointer movement has been blocked by a barrier. If the event type is BarrierLeave, a pointer previously blocked by a barrier has moved away from that barrier, or has moved through the blocking barrier following an earlier XIBarrierReleasePointer request.

eventid
   The unique event ID for this barrier event sequence.
root
event
    The root window or barrier window, respectively. The barrier window
    is always the drawable specified in in the CreatePointerBarrier request.
barrier
    The barrier blocking pointer movement.
dtime
    The relative time in milliseconds between the last event and this
    event.
flags
    A set of flags that apply to this barrier event
    PointerReleased:
       The pointer has moved through the barrier following a
       XIBarrierReleasePointer request (BarrierLeave only).
    DeviceIsGrabbed:
       The pointer device that generated this event is currently
       grabbed.
sourceid
    The source device that originally generated the event.
root_x
root_y
    The position of the pointer in screen coordinates (16.16 fixed
    point), after being constrained by barrier and/or screen extents.
dx
dy
    The relative movement of the pointer from its previous position to
    the new position if pointer movement were not constrained by this
    barrier.

Root coordinates in barrier events represent the position of the cursor after confinement by barriers, screens and RandR output extents.

Barrier event IDs are provided in the eventid field of barrier events. Its value is always provided in every barrier event. Event IDs are represented as unsigned 32-bit values and increase strictly monotonically in value for each new barrier event sequence, wrapping back to 0 upon reaching the numerical limit of IDs. The increment between two event IDs is indeterminate. Clients may not assume that any future barrier constraints will have specific event IDs. IDs are unique per device per barrier.

If a pointer is actively grabbed after a barrier event sequence has initiated, future barrier events of this sequence continue to use the same eventid, but all barrier events have the DeviceIsGrabbed flag set. If the pointer is ungrabbed, future events of this sequence have the same eventid and the DeviceIsGrabbed flag is unset.

The PointerReleased flag may only be set on a BarrierLeave event. A BarrierLeave(PointerReleased) event is generated when the pointer moves through the barrier following a XIBarrierReleasePointer request. The time between the XIBarrierReleasePointer and the BarrierLeave event thus depends on user input. A BarrierLeave(PointerReleased) event is also generated if the barrier is destroyed while pointer movement is constrained by the barrier, or the master pointer blocked by the barrier is removed. This event has a dx/dy of 0/0.

Appendix A: XI 2.2 Use-cases

All use-cases that include the receiving and processing of touch events require the client to announce XI 2.2 support in the XIQueryVersion request.

Client C wants to process touch events from a device D on window W.

  • C calls XISelectEvent for XI_Touch{Begin|Update|End} from D on W.

  • C receives TouchBegin whenever a touch sequence starts within W’s borders.

  • C receives TouchUpdate events whenever an axis valuator value changes for a touch sequence it received a TouchBegin event for.

  • C receives TouchEnd whenever a touch it received a TouchBegin event for ceases.

While client I wants to pre-process touch events from device D on the parent window of W.

  • C calls XISelectEvent for XI_Touch{Begin|Update|Ownership|End} from D on W.

  • I calls XIPassiveGrab for XI_Touch{Begin|Update|Ownership|End} from D on a parent window of W.

  • I receives TouchBegin whenever a touch begins within window W, as well as a TouchOwnership event indicating that it currently owns the touch sequence. C receives a TouchBegin event as well, but without TouchOwnership.

  • When an axis valuator changes in this touch sequence, both I and C receive a TouchUpdate event. I may process the event to determine if it is going to accept or reject the touch, whereas C may perform reversible processing.

  • If I decides it is going to claim the touch sequence for its exclusive processing, it calls XIAllowEvents with an event mode of XIAcceptTouch; at this point, C receives a TouchEnd event, and undoes any processing it has already performed due to the touch sequence. Further TouchUpdate events are delivered only to I.

  • Alternatively, if I decides it does not want to receive further events from this touch sequence, it calls XIAllowEvents with an event mode of XIRejectTouch; at this point, I receives a TouchEnd event confirming that it has rejected the touch. C receives a TouchOwnership event confirming that it is now the new owner of the touch, and further TouchUpdate events are delivered only to C. As C now owns the touch, it is free to perform irreversible processing of the sequence.

  • When the touch physically ceases, a TouchEnd event is sent to C.

While client I wants to process pointer events on window W’s parent, window Y.

  • I calls XIPassiveGrab for XI_{ButtonPress,MotionNotify,ButtonRelease} to create a synchronous pointer grab from D on Y.

  • C calls XISelectEvent for XI_Touch{Begin|Update|Ownership|End} from D on W.

  • I receives a ButtonPress event whenever a touch begins within W, and is considered the owner of the event. C receives a TouchBegin event, but does not receive a TouchOwnership event.

  • When the touchpoint moves, C will receive a TouchUpdate event. Event delivery to I is subject to the synchronous delivery mechanism. The emulated motion notify event is queued in the server while the device is frozen.

  • I may assert ownership by calling XIAllowEvents on Y with any mode other than ReplayDevice, which will cause all further events to be sent only to I, with a TouchEnd event being sent to C.

  • Alternatively, I may reject the touch sequence by calling XIAllowEvents on Y with mode ReplayDevice, which will cause no further events from that touch to be sent to I, and a TouchOwnership event to be sent to C, with subsequent motion events being sent as TouchUpdate events.

Driver DRV provides touch support from tracked device D:

  • DRV initializes a TouchClass for the device.

  • DRV parses D’s device protocol and selects one touch sequence to be emulated as pointer event.

  • DRV calls the respective input driver API with the touch sequence data. The touch sequence emulating a pointer has the respective flag set. DRV does not submit pointer data for any touchpoint.


0707010006235c000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000001700000000root/usr/local/include0707010006235d000041ed00000000000000000000000353c4dc4100000000000001000001001cffffffffffffffff0000001b00000000root/usr/local/include/X110707010006235e000041ed00000000000000000000000253c4dc4100000000000001000001001cffffffffffffffff0000002600000000root/usr/local/include/X11/extensions0707010006235f000081a400000000000000000000000153c4dc3e0000265f000001000001001cffffffffffffffff0000002b00000000root/usr/local/include/X11/extensions/XI.h/************************************************************ Copyright 1989, 1998 The Open Group Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP 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. Except as contained in this notice, the name of The Open Group 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 Open Group. Copyright 1989 by Hewlett-Packard Company, Palo Alto, California. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Hewlett-Packard not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. HEWLETT-PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL HEWLETT-PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ********************************************************/ /* Definitions used by the server, library and client */ #ifndef _XI_H_ #define _XI_H_ #define sz_xGetExtensionVersionReq 8 #define sz_xGetExtensionVersionReply 32 #define sz_xListInputDevicesReq 4 #define sz_xListInputDevicesReply 32 #define sz_xOpenDeviceReq 8 #define sz_xOpenDeviceReply 32 #define sz_xCloseDeviceReq 8 #define sz_xSetDeviceModeReq 8 #define sz_xSetDeviceModeReply 32 #define sz_xSelectExtensionEventReq 12 #define sz_xGetSelectedExtensionEventsReq 8 #define sz_xGetSelectedExtensionEventsReply 32 #define sz_xChangeDeviceDontPropagateListReq 12 #define sz_xGetDeviceDontPropagateListReq 8 #define sz_xGetDeviceDontPropagateListReply 32 #define sz_xGetDeviceMotionEventsReq 16 #define sz_xGetDeviceMotionEventsReply 32 #define sz_xChangeKeyboardDeviceReq 8 #define sz_xChangeKeyboardDeviceReply 32 #define sz_xChangePointerDeviceReq 8 #define sz_xChangePointerDeviceReply 32 #define sz_xGrabDeviceReq 20 #define sz_xGrabDeviceReply 32 #define sz_xUngrabDeviceReq 12 #define sz_xGrabDeviceKeyReq 20 #define sz_xGrabDeviceKeyReply 32 #define sz_xUngrabDeviceKeyReq 16 #define sz_xGrabDeviceButtonReq 20 #define sz_xGrabDeviceButtonReply 32 #define sz_xUngrabDeviceButtonReq 16 #define sz_xAllowDeviceEventsReq 12 #define sz_xGetDeviceFocusReq 8 #define sz_xGetDeviceFocusReply 32 #define sz_xSetDeviceFocusReq 16 #define sz_xGetFeedbackControlReq 8 #define sz_xGetFeedbackControlReply 32 #define sz_xChangeFeedbackControlReq 12 #define sz_xGetDeviceKeyMappingReq 8 #define sz_xGetDeviceKeyMappingReply 32 #define sz_xChangeDeviceKeyMappingReq 8 #define sz_xGetDeviceModifierMappingReq 8 #define sz_xSetDeviceModifierMappingReq 8 #define sz_xSetDeviceModifierMappingReply 32 #define sz_xGetDeviceButtonMappingReq 8 #define sz_xGetDeviceButtonMappingReply 32 #define sz_xSetDeviceButtonMappingReq 8 #define sz_xSetDeviceButtonMappingReply 32 #define sz_xQueryDeviceStateReq 8 #define sz_xQueryDeviceStateReply 32 #define sz_xSendExtensionEventReq 16 #define sz_xDeviceBellReq 8 #define sz_xSetDeviceValuatorsReq 8 #define sz_xSetDeviceValuatorsReply 32 #define sz_xGetDeviceControlReq 8 #define sz_xGetDeviceControlReply 32 #define sz_xChangeDeviceControlReq 8 #define sz_xChangeDeviceControlReply 32 #define sz_xListDevicePropertiesReq 8 #define sz_xListDevicePropertiesReply 32 #define sz_xChangeDevicePropertyReq 20 #define sz_xDeleteDevicePropertyReq 12 #define sz_xGetDevicePropertyReq 24 #define sz_xGetDevicePropertyReply 32 #define INAME "XInputExtension" #define XI_KEYBOARD "KEYBOARD" #define XI_MOUSE "MOUSE" #define XI_TABLET "TABLET" #define XI_TOUCHSCREEN "TOUCHSCREEN" #define XI_TOUCHPAD "TOUCHPAD" #define XI_BARCODE "BARCODE" #define XI_BUTTONBOX "BUTTONBOX" #define XI_KNOB_BOX "KNOB_BOX" #define XI_ONE_KNOB "ONE_KNOB" #define XI_NINE_KNOB "NINE_KNOB" #define XI_TRACKBALL "TRACKBALL" #define XI_QUADRATURE "QUADRATURE" #define XI_ID_MODULE "ID_MODULE" #define XI_SPACEBALL "SPACEBALL" #define XI_DATAGLOVE "DATAGLOVE" #define XI_EYETRACKER "EYETRACKER" #define XI_CURSORKEYS "CURSORKEYS" #define XI_FOOTMOUSE "FOOTMOUSE" #define XI_JOYSTICK "JOYSTICK" /* Indices into the versions[] array (XExtInt.c). Used as a index to * retrieve the minimum version of XI from _XiCheckExtInit */ #define Dont_Check 0 #define XInput_Initial_Release 1 #define XInput_Add_XDeviceBell 2 #define XInput_Add_XSetDeviceValuators 3 #define XInput_Add_XChangeDeviceControl 4 #define XInput_Add_DevicePresenceNotify 5 #define XInput_Add_DeviceProperties 6 /* DO NOT ADD TO HERE -> XI2 */ #define XI_Absent 0 #define XI_Present 1 #define XI_Initial_Release_Major 1 #define XI_Initial_Release_Minor 0 #define XI_Add_XDeviceBell_Major 1 #define XI_Add_XDeviceBell_Minor 1 #define XI_Add_XSetDeviceValuators_Major 1 #define XI_Add_XSetDeviceValuators_Minor 2 #define XI_Add_XChangeDeviceControl_Major 1 #define XI_Add_XChangeDeviceControl_Minor 3 #define XI_Add_DevicePresenceNotify_Major 1 #define XI_Add_DevicePresenceNotify_Minor 4 #define XI_Add_DeviceProperties_Major 1 #define XI_Add_DeviceProperties_Minor 5 #define DEVICE_RESOLUTION 1 #define DEVICE_ABS_CALIB 2 #define DEVICE_CORE 3 #define DEVICE_ENABLE 4 #define DEVICE_ABS_AREA 5 #define NoSuchExtension 1 #define COUNT 0 #define CREATE 1 #define NewPointer 0 #define NewKeyboard 1 #define XPOINTER 0 #define XKEYBOARD 1 #define UseXKeyboard 0xFF #define IsXPointer 0 #define IsXKeyboard 1 #define IsXExtensionDevice 2 #define IsXExtensionKeyboard 3 #define IsXExtensionPointer 4 #define AsyncThisDevice 0 #define SyncThisDevice 1 #define ReplayThisDevice 2 #define AsyncOtherDevices 3 #define AsyncAll 4 #define SyncAll 5 #define FollowKeyboard 3 #ifndef RevertToFollowKeyboard #define RevertToFollowKeyboard 3 #endif #define DvAccelNum (1L << 0) #define DvAccelDenom (1L << 1) #define DvThreshold (1L << 2) #define DvKeyClickPercent (1L<<0) #define DvPercent (1L<<1) #define DvPitch (1L<<2) #define DvDuration (1L<<3) #define DvLed (1L<<4) #define DvLedMode (1L<<5) #define DvKey (1L<<6) #define DvAutoRepeatMode (1L<<7) #define DvString (1L << 0) #define DvInteger (1L << 0) #define DeviceMode (1L << 0) #define Relative 0 #define Absolute 1 #define ProximityState (1L << 1) #define InProximity (0L << 1) #define OutOfProximity (1L << 1) #define AddToList 0 #define DeleteFromList 1 #define KeyClass 0 #define ButtonClass 1 #define ValuatorClass 2 #define FeedbackClass 3 #define ProximityClass 4 #define FocusClass 5 #define OtherClass 6 #define AttachClass 7 #define KbdFeedbackClass 0 #define PtrFeedbackClass 1 #define StringFeedbackClass 2 #define IntegerFeedbackClass 3 #define LedFeedbackClass 4 #define BellFeedbackClass 5 #define _devicePointerMotionHint 0 #define _deviceButton1Motion 1 #define _deviceButton2Motion 2 #define _deviceButton3Motion 3 #define _deviceButton4Motion 4 #define _deviceButton5Motion 5 #define _deviceButtonMotion 6 #define _deviceButtonGrab 7 #define _deviceOwnerGrabButton 8 #define _noExtensionEvent 9 #define _devicePresence 0 #define _deviceEnter 0 #define _deviceLeave 1 /* Device presence notify states */ #define DeviceAdded 0 #define DeviceRemoved 1 #define DeviceEnabled 2 #define DeviceDisabled 3 #define DeviceUnrecoverable 4 #define DeviceControlChanged 5 /* XI Errors */ #define XI_BadDevice 0 #define XI_BadEvent 1 #define XI_BadMode 2 #define XI_DeviceBusy 3 #define XI_BadClass 4 /* * Make XEventClass be a CARD32 for 64 bit servers. Don't affect client * definition of XEventClass since that would be a library interface change. * See the top of X.h for more _XSERVER64 magic. * * But, don't actually use the CARD32 type. We can't get it defined here * without polluting the namespace. */ #ifdef _XSERVER64 typedef unsigned int XEventClass; #else typedef unsigned long XEventClass; #endif /******************************************************************* * * Extension version structure. * */ typedef struct { int present; short major_version; short minor_version; } XExtensionVersion; #endif /* _XI_H_ */ 07070100062362000081a400000000000000000000000153c4dc3e0000a67e000001000001001cffffffffffffffff0000003000000000root/usr/local/include/X11/extensions/XIproto.h/************************************************************ Copyright 1989, 1998 The Open Group Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP 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. Except as contained in this notice, the name of The Open Group 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 Open Group. Copyright 1989 by Hewlett-Packard Company, Palo Alto, California. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Hewlett-Packard not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. HEWLETT-PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL HEWLETT-PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ********************************************************/ #ifndef _XIPROTO_H #define _XIPROTO_H #include #include /* make sure types have right sizes for protocol structures. */ #define Window CARD32 #define Time CARD32 #define KeyCode CARD8 #define Mask CARD32 #define Atom CARD32 #define Cursor CARD32 /********************************************************* * * number of events, errors, and extension name. * */ #define MORE_EVENTS 0x80 #define DEVICE_BITS 0x7F #define InputClassBits 0x3F /* bits in mode field for input classes */ #define ModeBitsShift 6 /* amount to shift the remaining bits */ #define numInputClasses 7 #define IEVENTS 17 /* does NOT include generic events */ #define IERRORS 5 #define IREQUESTS 39 #define CLIENT_REQ 1 typedef struct _XExtEventInfo { Mask mask; BYTE type; BYTE word; } XExtEventInfo; #ifndef _XITYPEDEF_POINTER typedef void *Pointer; #endif struct tmask { Mask mask; void *dev; }; /********************************************************* * * Event constants used by library. * */ #define XI_DeviceValuator 0 #define XI_DeviceKeyPress 1 #define XI_DeviceKeyRelease 2 #define XI_DeviceButtonPress 3 #define XI_DeviceButtonRelease 4 #define XI_DeviceMotionNotify 5 #define XI_DeviceFocusIn 6 #define XI_DeviceFocusOut 7 #define XI_ProximityIn 8 #define XI_ProximityOut 9 #define XI_DeviceStateNotify 10 #define XI_DeviceMappingNotify 11 #define XI_ChangeDeviceNotify 12 #define XI_DeviceKeystateNotify 13 #define XI_DeviceButtonstateNotify 14 #define XI_DevicePresenceNotify 15 #define XI_DevicePropertyNotify 16 /********************************************************* * * Protocol request constants * */ #define X_GetExtensionVersion 1 #define X_ListInputDevices 2 #define X_OpenDevice 3 #define X_CloseDevice 4 #define X_SetDeviceMode 5 #define X_SelectExtensionEvent 6 #define X_GetSelectedExtensionEvents 7 #define X_ChangeDeviceDontPropagateList 8 #define X_GetDeviceDontPropagateList 9 #define X_GetDeviceMotionEvents 10 #define X_ChangeKeyboardDevice 11 #define X_ChangePointerDevice 12 #define X_GrabDevice 13 #define X_UngrabDevice 14 #define X_GrabDeviceKey 15 #define X_UngrabDeviceKey 16 #define X_GrabDeviceButton 17 #define X_UngrabDeviceButton 18 #define X_AllowDeviceEvents 19 #define X_GetDeviceFocus 20 #define X_SetDeviceFocus 21 #define X_GetFeedbackControl 22 #define X_ChangeFeedbackControl 23 #define X_GetDeviceKeyMapping 24 #define X_ChangeDeviceKeyMapping 25 #define X_GetDeviceModifierMapping 26 #define X_SetDeviceModifierMapping 27 #define X_GetDeviceButtonMapping 28 #define X_SetDeviceButtonMapping 29 #define X_QueryDeviceState 30 #define X_SendExtensionEvent 31 #define X_DeviceBell 32 #define X_SetDeviceValuators 33 #define X_GetDeviceControl 34 #define X_ChangeDeviceControl 35 /* XI 1.5 */ #define X_ListDeviceProperties 36 #define X_ChangeDeviceProperty 37 #define X_DeleteDeviceProperty 38 #define X_GetDeviceProperty 39 /********************************************************* * * Protocol request and reply structures. * * GetExtensionVersion. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GetExtensionVersion */ CARD16 length B16; CARD16 nbytes B16; CARD8 pad1, pad2; } xGetExtensionVersionReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetExtensionVersion */ CARD16 sequenceNumber B16; CARD32 length B32; CARD16 major_version B16; CARD16 minor_version B16; BOOL present; CARD8 pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; } xGetExtensionVersionReply; /********************************************************* * * ListInputDevices. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_ListInputDevices */ CARD16 length B16; } xListInputDevicesReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_ListInputDevices */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 ndevices; CARD8 pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xListInputDevicesReply; typedef struct _xDeviceInfo *xDeviceInfoPtr; typedef struct _xAnyClassinfo *xAnyClassPtr; typedef struct _xAnyClassinfo { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; } xAnyClassInfo; typedef struct _xDeviceInfo { CARD32 type B32; CARD8 id; CARD8 num_classes; CARD8 use; /* IsXPointer | IsXKeyboard | IsXExtension... */ CARD8 attached; /* id of master dev (if IsXExtension..) */ } xDeviceInfo; typedef struct _xKeyInfo *xKeyInfoPtr; typedef struct _xKeyInfo { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; KeyCode min_keycode; KeyCode max_keycode; CARD16 num_keys B16; CARD8 pad1,pad2; } xKeyInfo; typedef struct _xButtonInfo *xButtonInfoPtr; typedef struct _xButtonInfo { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; CARD16 num_buttons B16; } xButtonInfo; typedef struct _xValuatorInfo *xValuatorInfoPtr; typedef struct _xValuatorInfo { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; CARD8 num_axes; CARD8 mode; CARD32 motion_buffer_size B32; } xValuatorInfo; typedef struct _xAxisInfo *xAxisInfoPtr; typedef struct _xAxisInfo { CARD32 resolution B32; CARD32 min_value B32; CARD32 max_value B32; } xAxisInfo; /********************************************************* * * OpenDevice. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_OpenDevice */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xOpenDeviceReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_OpenDevice */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 num_classes; BYTE pad1, pad2, pad3; CARD32 pad00 B32; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; } xOpenDeviceReply; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 event_type_base; } xInputClassInfo; /********************************************************* * * CloseDevice. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_CloseDevice */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xCloseDeviceReq; /********************************************************* * * SetDeviceMode. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_SetDeviceMode */ CARD16 length B16; CARD8 deviceid; CARD8 mode; BYTE pad1, pad2; } xSetDeviceModeReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_SetDeviceMode */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xSetDeviceModeReply; /********************************************************* * * SelectExtensionEvent. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_SelectExtensionEvent */ CARD16 length B16; Window window B32; CARD16 count B16; CARD16 pad00 B16; } xSelectExtensionEventReq; /********************************************************* * * GetSelectedExtensionEvent. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_GetSelectedExtensionEvents */ CARD16 length B16; Window window B32; } xGetSelectedExtensionEventsReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* GetSelectedExtensionEvents */ CARD16 sequenceNumber B16; CARD32 length B32; CARD16 this_client_count B16; CARD16 all_clients_count B16; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xGetSelectedExtensionEventsReply; /********************************************************* * * ChangeDeviceDontPropagateList. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_ChangeDeviceDontPropagateList */ CARD16 length B16; Window window B32; CARD16 count B16; CARD8 mode; BYTE pad; } xChangeDeviceDontPropagateListReq; /********************************************************* * * GetDeviceDontPropagateList. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_GetDeviceDontPropagateList */ CARD16 length B16; Window window B32; } xGetDeviceDontPropagateListReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* GetDeviceDontPropagateList */ CARD16 sequenceNumber B16; CARD32 length B32; CARD16 count B16; CARD16 pad00 B16; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xGetDeviceDontPropagateListReply; /********************************************************* * * GetDeviceMotionEvents. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GetDeviceMotionEvents*/ CARD16 length B16; Time start B32; Time stop B32; CARD8 deviceid; BYTE pad1, pad2, pad3; } xGetDeviceMotionEventsReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceMotionEvents */ CARD16 sequenceNumber B16; CARD32 length B32; CARD32 nEvents B32; CARD8 axes; CARD8 mode; BYTE pad1, pad2; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; } xGetDeviceMotionEventsReply; /********************************************************* * * ChangeKeyboardDevice. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_ChangeKeyboardDevice */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xChangeKeyboardDeviceReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_ChangeKeyboardDevice*/ CARD16 sequenceNumber B16; CARD32 length B32; /* 0 */ CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xChangeKeyboardDeviceReply; /********************************************************* * * ChangePointerDevice. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_ChangePointerDevice */ CARD16 length B16; CARD8 xaxis; CARD8 yaxis; CARD8 deviceid; BYTE pad1; } xChangePointerDeviceReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_ChangePointerDevice */ CARD16 sequenceNumber B16; CARD32 length B32; /* 0 */ CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xChangePointerDeviceReply; /********************************************************* * * GrabDevice. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GrabDevice */ CARD16 length B16; Window grabWindow B32; Time time B32; CARD16 event_count B16; CARD8 this_device_mode; CARD8 other_devices_mode; BOOL ownerEvents; CARD8 deviceid; CARD16 pad01 B16; } xGrabDeviceReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GrabDevice */ CARD16 sequenceNumber B16; CARD32 length B32; /* 0 */ CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xGrabDeviceReply; /********************************************************* * * UngrabDevice. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_UnGrabDevice */ CARD16 length B16; Time time B32; CARD8 deviceid; BYTE pad1, pad2, pad3; } xUngrabDeviceReq; /********************************************************* * * GrabDeviceKey. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GrabDeviceKey */ CARD16 length B16; Window grabWindow B32; CARD16 event_count B16; CARD16 modifiers B16; CARD8 modifier_device; CARD8 grabbed_device; CARD8 key; BYTE this_device_mode; BYTE other_devices_mode; BOOL ownerEvents; BYTE pad1, pad2; } xGrabDeviceKeyReq; /********************************************************* * * UngrabDeviceKey. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_UngrabDeviceKey */ CARD16 length B16; Window grabWindow B32; CARD16 modifiers B16; CARD8 modifier_device; CARD8 key; CARD8 grabbed_device; BYTE pad1, pad2, pad3; } xUngrabDeviceKeyReq; /********************************************************* * * GrabDeviceButton. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GrabDeviceButton */ CARD16 length B16; Window grabWindow B32; CARD8 grabbed_device; CARD8 modifier_device; CARD16 event_count B16; CARD16 modifiers B16; BYTE this_device_mode; BYTE other_devices_mode; CARD8 button; BOOL ownerEvents; BYTE pad1, pad2; } xGrabDeviceButtonReq; /********************************************************* * * UngrabDeviceButton. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_UngrabDeviceButton */ CARD16 length B16; Window grabWindow B32; CARD16 modifiers B16; CARD8 modifier_device; CARD8 button; CARD8 grabbed_device; BYTE pad1, pad2, pad3; } xUngrabDeviceButtonReq; /********************************************************* * * AllowDeviceEvents. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_AllowDeviceEvents */ CARD16 length B16; Time time B32; CARD8 mode; CARD8 deviceid; BYTE pad1, pad2; } xAllowDeviceEventsReq; /********************************************************* * * GetDeviceFocus. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GetDeviceFocus */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xGetDeviceFocusReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceFocus */ CARD16 sequenceNumber B16; CARD32 length B32; CARD32 focus B32; Time time B32; CARD8 revertTo; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; } xGetDeviceFocusReply; /********************************************************* * * SetDeviceFocus. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_SetDeviceFocus */ CARD16 length B16; Window focus B32; Time time B32; CARD8 revertTo; CARD8 device; CARD16 pad01 B16; } xSetDeviceFocusReq; /********************************************************* * * GetFeedbackControl. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_GetFeedbackControl */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xGetFeedbackControlReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetFeedbackControl */ CARD16 sequenceNumber B16; CARD32 length B32; CARD16 num_feedbacks B16; CARD16 pad01 B16; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; CARD32 pad06 B32; } xGetFeedbackControlReply; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class */ #else CARD8 class; /* feedback class */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ } xFeedbackState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 id; CARD16 length B16; CARD16 pitch B16; CARD16 duration B16; CARD32 led_mask B32; CARD32 led_values B32; BOOL global_auto_repeat; CARD8 click; CARD8 percent; BYTE pad; BYTE auto_repeats[32]; } xKbdFeedbackState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 id; CARD16 length B16; CARD8 pad1,pad2; CARD16 accelNum B16; CARD16 accelDenom B16; CARD16 threshold B16; } xPtrFeedbackState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; CARD16 length B16; /* feedback length */ CARD32 resolution B32; INT32 min_value B32; INT32 max_value B32; } xIntegerFeedbackState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; CARD16 length B16; /* feedback length */ CARD16 max_symbols B16; CARD16 num_syms_supported B16; } xStringFeedbackState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; CARD16 length B16; /* feedback length */ CARD8 percent; BYTE pad1, pad2, pad3; CARD16 pitch B16; CARD16 duration B16; } xBellFeedbackState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; CARD16 length B16; /* feedback length */ CARD32 led_mask B32; CARD32 led_values B32; } xLedFeedbackState; /********************************************************* * * ChangeFeedbackControl. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_ChangeFeedbackControl */ CARD16 length B16; CARD32 mask B32; CARD8 deviceid; CARD8 feedbackid; BYTE pad1, pad2; } xChangeFeedbackControlReq; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ } xFeedbackCtl; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback length */ CARD16 length B16; /* feedback length */ KeyCode key; CARD8 auto_repeat_mode; INT8 click; INT8 percent; INT16 pitch B16; INT16 duration B16; CARD32 led_mask B32; CARD32 led_values B32; } xKbdFeedbackCtl; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ CARD8 pad1,pad2; INT16 num B16; INT16 denom B16; INT16 thresh B16; } xPtrFeedbackCtl; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ INT32 int_to_display B32; } xIntegerFeedbackCtl; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ CARD8 pad1,pad2; CARD16 num_keysyms B16; } xStringFeedbackCtl; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ INT8 percent; BYTE pad1, pad2, pad3; INT16 pitch B16; INT16 duration B16; } xBellFeedbackCtl; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; /* feedback class id */ #else CARD8 class; /* feedback class id */ #endif CARD8 id; /* feedback id */ CARD16 length B16; /* feedback length */ CARD32 led_mask B32; CARD32 led_values B32; } xLedFeedbackCtl; /********************************************************* * * GetDeviceKeyMapping. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GetDeviceKeyMapping */ CARD16 length B16; CARD8 deviceid; KeyCode firstKeyCode; CARD8 count; BYTE pad1; } xGetDeviceKeyMappingReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceKeyMapping */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 keySymsPerKeyCode; CARD8 pad0; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; CARD32 pad6 B32; } xGetDeviceKeyMappingReply; /********************************************************* * * ChangeDeviceKeyMapping. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_ChangeDeviceKeyMapping */ CARD16 length B16; CARD8 deviceid; KeyCode firstKeyCode; CARD8 keySymsPerKeyCode; CARD8 keyCodes; } xChangeDeviceKeyMappingReq; /********************************************************* * * GetDeviceModifierMapping. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GetDeviceModifierMapping */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xGetDeviceModifierMappingReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceModifierMapping */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 numKeyPerModifier; CARD8 pad0; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; CARD32 pad6 B32; } xGetDeviceModifierMappingReply; /********************************************************* * * SetDeviceModifierMapping. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_SetDeviceModifierMapping */ CARD16 length B16; CARD8 deviceid; CARD8 numKeyPerModifier; CARD16 pad1 B16; } xSetDeviceModifierMappingReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_SetDeviceModifierMapping */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 success; CARD8 pad0; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; CARD32 pad6 B32; } xSetDeviceModifierMappingReply; /********************************************************* * * GetDeviceButtonMapping. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_GetDeviceButtonMapping */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xGetDeviceButtonMappingReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceButtonMapping */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 nElts; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xGetDeviceButtonMappingReply; /********************************************************* * * SetDeviceButtonMapping. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* X_SetDeviceButtonMapping */ CARD16 length B16; CARD8 deviceid; CARD8 map_length; BYTE pad1, pad2; } xSetDeviceButtonMappingReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_SetDeviceButtonMapping */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 status; BYTE pad0; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; CARD32 pad6 B32; } xSetDeviceButtonMappingReply; /********************************************************* * * QueryDeviceState. * */ typedef struct { CARD8 reqType; CARD8 ReqType; /* always X_QueryDeviceState */ CARD16 length B16; CARD8 deviceid; BYTE pad1, pad2, pad3; } xQueryDeviceStateReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_QueryDeviceState */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 num_classes; BYTE pad0; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; CARD32 pad6 B32; } xQueryDeviceStateReply; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; CARD8 num_keys; BYTE pad1; CARD8 keys[32]; } xKeyState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; CARD8 num_buttons; BYTE pad1; CARD8 buttons[32]; } xButtonState; typedef struct { #if defined(__cplusplus) || defined(c_plusplus) CARD8 c_class; #else CARD8 class; #endif CARD8 length; CARD8 num_valuators; CARD8 mode; } xValuatorState; /********************************************************* * * SendExtensionEvent. * THIS REQUEST MUST BE KEPT A MULTIPLE OF 8 BYTES IN LENGTH! * MORE EVENTS MAY FOLLOW AND THEY MUST BE QUAD-ALIGNED! * */ typedef struct { CARD8 reqType; CARD8 ReqType; /* always X_SendExtensionEvent */ CARD16 length B16; Window destination B32; CARD8 deviceid; BOOL propagate; CARD16 count B16; CARD8 num_events; BYTE pad1,pad2,pad3; } xSendExtensionEventReq; /********************************************************* * * DeviceBell. * */ typedef struct { CARD8 reqType; CARD8 ReqType; /* always X_DeviceBell */ CARD16 length B16; CARD8 deviceid; CARD8 feedbackid; CARD8 feedbackclass; INT8 percent; } xDeviceBellReq; /********************************************************* * * SetDeviceValuators. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_SetDeviceValuators */ CARD16 length B16; CARD8 deviceid; CARD8 first_valuator; CARD8 num_valuators; BYTE pad1; } xSetDeviceValuatorsReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_SetDeviceValuators */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xSetDeviceValuatorsReply; /********************************************************* * * GetDeviceControl. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_GetDeviceControl */ CARD16 length B16; CARD16 control B16; CARD8 deviceid; BYTE pad2; } xGetDeviceControlReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceControl */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xGetDeviceControlReply; typedef struct { CARD16 control B16; /* control type */ CARD16 length B16; /* control length */ } xDeviceState; typedef struct { CARD16 control B16; /* control type */ CARD16 length B16; /* control length */ CARD32 num_valuators B32; /* number of valuators */ } xDeviceResolutionState; typedef struct { CARD16 control B16; CARD16 length B16; INT32 min_x B32; INT32 max_x B32; INT32 min_y B32; INT32 max_y B32; CARD32 flip_x B32; CARD32 flip_y B32; CARD32 rotation B32; CARD32 button_threshold B32; } xDeviceAbsCalibState; typedef struct { CARD16 control B16; CARD16 length B16; CARD32 offset_x B32; CARD32 offset_y B32; CARD32 width B32; CARD32 height B32; CARD32 screen B32; CARD32 following B32; } xDeviceAbsAreaState; typedef struct { CARD16 control B16; /* control type */ CARD16 length B16; /* control length */ CARD8 status; CARD8 iscore; CARD16 pad1 B16; } xDeviceCoreState; typedef struct { CARD16 control B16; /* control type */ CARD16 length B16; /* control length */ CARD8 enable; CARD8 pad0; CARD16 pad1 B16; } xDeviceEnableState; /********************************************************* * * ChangeDeviceControl. * */ typedef struct { CARD8 reqType; /* input extension major code */ CARD8 ReqType; /* always X_ChangeDeviceControl */ CARD16 length B16; CARD16 control B16; CARD8 deviceid; BYTE pad0; } xChangeDeviceControlReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_ChangeDeviceControl */ CARD16 sequenceNumber B16; CARD32 length B32; CARD8 status; BYTE pad1, pad2, pad3; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; } xChangeDeviceControlReply; typedef struct { CARD16 control B16; /* control type */ CARD16 length B16; /* control length */ } xDeviceCtl; typedef struct { CARD16 control B16; /* control type */ CARD16 length B16; /* control length */ CARD8 first_valuator; /* first valuator to change */ CARD8 num_valuators; /* number of valuators to change*/ CARD8 pad1,pad2; } xDeviceResolutionCtl; typedef struct { CARD16 control B16; CARD16 length B16; INT32 min_x; INT32 max_x; INT32 min_y; INT32 max_y; CARD32 flip_x; CARD32 flip_y; CARD32 rotation; CARD32 button_threshold; } xDeviceAbsCalibCtl; typedef struct { CARD16 control B16; CARD16 length B16; CARD32 offset_x; CARD32 offset_y; INT32 width; INT32 height; INT32 screen; CARD32 following; } xDeviceAbsAreaCtl; typedef struct { CARD16 control B16; CARD16 length B16; CARD8 status; CARD8 pad0; CARD16 pad1 B16; } xDeviceCoreCtl; typedef struct { CARD16 control B16; CARD16 length B16; CARD8 enable; CARD8 pad0; CARD16 pad1 B16; } xDeviceEnableCtl; /* XI 1.5 */ /********************************************************* * * ListDeviceProperties. * */ typedef struct { CARD8 reqType; /* input extension major opcode */ CARD8 ReqType; /* always X_ListDeviceProperties */ CARD16 length B16; CARD8 deviceid; CARD8 pad0; CARD16 pad1 B16; } xListDevicePropertiesReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_ListDeviceProperties */ CARD16 sequenceNumber B16; CARD32 length B32; CARD16 nAtoms B16; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; CARD32 pad4 B32; CARD32 pad5 B32; CARD32 pad6 B32; } xListDevicePropertiesReply; /********************************************************* * * ChangeDeviceProperty. * */ typedef struct { CARD8 reqType; /* input extension major opcode */ CARD8 ReqType; /* always X_ChangeDeviceProperty */ CARD16 length B16; Atom property B32; Atom type B32; CARD8 deviceid; CARD8 format; CARD8 mode; CARD8 pad; CARD32 nUnits B32; } xChangeDevicePropertyReq; /********************************************************* * * DeleteDeviceProperty. * */ typedef struct { CARD8 reqType; /* input extension major opcode */ CARD8 ReqType; /* always X_DeleteDeviceProperty */ CARD16 length B16; Atom property B32; CARD8 deviceid; CARD8 pad0; CARD16 pad1 B16; } xDeleteDevicePropertyReq; /********************************************************* * * GetDeviceProperty. * */ typedef struct { CARD8 reqType; /* input extension major opcode */ CARD8 ReqType; /* always X_GetDeviceProperty */ CARD16 length B16; Atom property B32; Atom type B32; CARD32 longOffset B32; CARD32 longLength B32; CARD8 deviceid; #if defined(__cplusplus) || defined(c_plusplus) BOOL c_delete; #else BOOL delete; #endif CARD16 pad; } xGetDevicePropertyReq; typedef struct { CARD8 repType; /* X_Reply */ CARD8 RepType; /* always X_GetDeviceProperty */ CARD16 sequenceNumber B16; CARD32 length B32; Atom propertyType B32; CARD32 bytesAfter B32; CARD32 nItems B32; CARD8 format; CARD8 deviceid; CARD16 pad1 B16; CARD32 pad2 B32; CARD32 pad3 B32; } xGetDevicePropertyReply; /********************************************************** * * Input extension events. * * DeviceValuator * */ typedef struct { BYTE type; CARD8 deviceid; CARD16 sequenceNumber B16; KeyButMask device_state B16; CARD8 num_valuators; CARD8 first_valuator; INT32 valuator0 B32; INT32 valuator1 B32; INT32 valuator2 B32; INT32 valuator3 B32; INT32 valuator4 B32; INT32 valuator5 B32; } deviceValuator; /********************************************************** * * DeviceKeyButtonPointer. * * Used for: DeviceKeyPress, DeviceKeyRelease, * DeviceButtonPress, DeviceButtonRelease, * ProximityIn, ProximityOut * DeviceMotionNotify, * */ typedef struct { BYTE type; BYTE detail; CARD16 sequenceNumber B16; Time time B32; Window root B32; Window event B32; Window child B32; INT16 root_x B16; INT16 root_y B16; INT16 event_x B16; INT16 event_y B16; KeyButMask state B16; BOOL same_screen; CARD8 deviceid; } deviceKeyButtonPointer; /********************************************************** * * DeviceFocus. * */ typedef struct { BYTE type; BYTE detail; CARD16 sequenceNumber B16; Time time B32; Window window B32; BYTE mode; CARD8 deviceid; BYTE pad1, pad2; CARD32 pad00 B32; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; } deviceFocus; /********************************************************** * * DeviceStateNotify. * * Note that the two high-order bits in the classes_reported * field are the proximity state (InProximity or OutOfProximity), * and the device mode (Absolute or Relative), respectively. * */ typedef struct { BYTE type; BYTE deviceid; CARD16 sequenceNumber B16; Time time B32; CARD8 num_keys; CARD8 num_buttons; CARD8 num_valuators; CARD8 classes_reported; CARD8 buttons[4]; CARD8 keys[4]; INT32 valuator0 B32; INT32 valuator1 B32; INT32 valuator2 B32; } deviceStateNotify; /********************************************************** * * DeviceKeyStateNotify. * */ typedef struct { BYTE type; BYTE deviceid; CARD16 sequenceNumber B16; CARD8 keys[28]; } deviceKeyStateNotify; /********************************************************** * * DeviceButtonStateNotify. * */ typedef struct { BYTE type; BYTE deviceid; CARD16 sequenceNumber B16; CARD8 buttons[28]; } deviceButtonStateNotify; /********************************************************** * * DeviceMappingNotify. * Fields must be kept in sync with core mappingnotify event. * */ typedef struct { BYTE type; BYTE deviceid; CARD16 sequenceNumber B16; CARD8 request; KeyCode firstKeyCode; CARD8 count; BYTE pad1; Time time B32; CARD32 pad00 B32; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; } deviceMappingNotify; /********************************************************** * * ChangeDeviceNotify. * */ typedef struct { BYTE type; BYTE deviceid; CARD16 sequenceNumber B16; Time time B32; CARD8 request; BYTE pad1, pad2, pad3; CARD32 pad00 B32; CARD32 pad01 B32; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; } changeDeviceNotify; /********************************************************** * * devicePresenceNotify. * */ typedef struct { BYTE type; BYTE pad00; CARD16 sequenceNumber B16; Time time B32; BYTE devchange; /* Device{Added|Removed|Enabled|Disabled|ControlChanged} */ BYTE deviceid; CARD16 control B16; CARD32 pad02 B32; CARD32 pad03 B32; CARD32 pad04 B32; CARD32 pad05 B32; CARD32 pad06 B32; } devicePresenceNotify; /********************************************************* * DevicePropertyNotifyEvent * * Sent whenever a device's property changes. * */ typedef struct { BYTE type; BYTE state; /* NewValue or Deleted */ CARD16 sequenceNumber B16; CARD32 time B32; Atom atom B32; /* affected property */ CARD32 pad0 B32; CARD32 pad1 B32; CARD32 pad2 B32; CARD32 pad3 B32; CARD16 pad5 B16; CARD8 pad4; CARD8 deviceid; /* id of device */ } devicePropertyNotify; #undef Window #undef Time #undef KeyCode #undef Mask #undef Atom #undef Cursor #endif 07070100062360000081a400000000000000000000000153c4dc3e0000292e000001000001001cffffffffffffffff0000002c00000000root/usr/local/include/X11/extensions/XI2.h/* * Copyright © 2009 Red Hat, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice (including the next * paragraph) shall be included in all copies or substantial portions of the * Software. * * THE SOFTWARE IS PROVIDED "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. * */ #ifndef _XI2_H_ #define _XI2_H_ #define XInput_2_0 7 /* DO NOT ADD TO THIS LIST. These are libXi-specific defines. See commit libXi-1.4.2-21-ge8531dd */ #define XI_2_Major 2 #define XI_2_Minor 3 /* Property event flags */ #define XIPropertyDeleted 0 #define XIPropertyCreated 1 #define XIPropertyModified 2 /* Property modes */ #define XIPropModeReplace 0 #define XIPropModePrepend 1 #define XIPropModeAppend 2 /* Special property type used for XIGetProperty */ #define XIAnyPropertyType 0L /* Enter/Leave and Focus In/Out modes */ #define XINotifyNormal 0 #define XINotifyGrab 1 #define XINotifyUngrab 2 #define XINotifyWhileGrabbed 3 #define XINotifyPassiveGrab 4 #define XINotifyPassiveUngrab 5 /* Enter/Leave and focus In/out detail */ #define XINotifyAncestor 0 #define XINotifyVirtual 1 #define XINotifyInferior 2 #define XINotifyNonlinear 3 #define XINotifyNonlinearVirtual 4 #define XINotifyPointer 5 #define XINotifyPointerRoot 6 #define XINotifyDetailNone 7 /* Grab modes */ #define XIGrabModeSync 0 #define XIGrabModeAsync 1 #define XIGrabModeTouch 2 /* Grab reply status codes */ #define XIGrabSuccess 0 #define XIAlreadyGrabbed 1 #define XIGrabInvalidTime 2 #define XIGrabNotViewable 3 #define XIGrabFrozen 4 /* Grab owner events values */ #define XIOwnerEvents True #define XINoOwnerEvents False /* Passive grab types */ #define XIGrabtypeButton 0 #define XIGrabtypeKeycode 1 #define XIGrabtypeEnter 2 #define XIGrabtypeFocusIn 3 #define XIGrabtypeTouchBegin 4 /* Passive grab modifier */ #define XIAnyModifier (1U << 31) #define XIAnyButton 0 #define XIAnyKeycode 0 /* XIAllowEvents event-modes */ #define XIAsyncDevice 0 #define XISyncDevice 1 #define XIReplayDevice 2 #define XIAsyncPairedDevice 3 #define XIAsyncPair 4 #define XISyncPair 5 #define XIAcceptTouch 6 #define XIRejectTouch 7 /* DeviceChangedEvent change reasons */ #define XISlaveSwitch 1 #define XIDeviceChange 2 /* Hierarchy flags */ #define XIMasterAdded (1 << 0) #define XIMasterRemoved (1 << 1) #define XISlaveAdded (1 << 2) #define XISlaveRemoved (1 << 3) #define XISlaveAttached (1 << 4) #define XISlaveDetached (1 << 5) #define XIDeviceEnabled (1 << 6) #define XIDeviceDisabled (1 << 7) /* ChangeHierarchy constants */ #define XIAddMaster 1 #define XIRemoveMaster 2 #define XIAttachSlave 3 #define XIDetachSlave 4 #define XIAttachToMaster 1 #define XIFloating 2 /* Valuator modes */ #define XIModeRelative 0 #define XIModeAbsolute 1 /* Device types */ #define XIMasterPointer 1 #define XIMasterKeyboard 2 #define XISlavePointer 3 #define XISlaveKeyboard 4 #define XIFloatingSlave 5 /* Device classes: classes that are not identical to Xi 1.x classes must be * numbered starting from 8. */ #define XIKeyClass 0 #define XIButtonClass 1 #define XIValuatorClass 2 #define XIScrollClass 3 #define XITouchClass 8 /* Scroll class types */ #define XIScrollTypeVertical 1 #define XIScrollTypeHorizontal 2 /* Scroll class flags */ #define XIScrollFlagNoEmulation (1 << 0) #define XIScrollFlagPreferred (1 << 1) /* Device event flags (common) */ /* Device event flags (key events only) */ #define XIKeyRepeat (1 << 16) /* Device event flags (pointer events only) */ #define XIPointerEmulated (1 << 16) /* Device event flags (touch events only) */ #define XITouchPendingEnd (1 << 16) #define XITouchEmulatingPointer (1 << 17) /* Barrier event flags */ #define XIBarrierPointerReleased (1 << 0) #define XIBarrierDeviceIsGrabbed (1 << 1) /* Touch modes */ #define XIDirectTouch 1 #define XIDependentTouch 2 /* XI2 event mask macros */ #define XISetMask(ptr, event) (((unsigned char*)(ptr))[(event)>>3] |= (1 << ((event) & 7))) #define XIClearMask(ptr, event) (((unsigned char*)(ptr))[(event)>>3] &= ~(1 << ((event) & 7))) #define XIMaskIsSet(ptr, event) (((unsigned char*)(ptr))[(event)>>3] & (1 << ((event) & 7))) #define XIMaskLen(event) (((event) >> 3) + 1) /* Fake device ID's for event selection */ #define XIAllDevices 0 #define XIAllMasterDevices 1 /* Event types */ #define XI_DeviceChanged 1 #define XI_KeyPress 2 #define XI_KeyRelease 3 #define XI_ButtonPress 4 #define XI_ButtonRelease 5 #define XI_Motion 6 #define XI_Enter 7 #define XI_Leave 8 #define XI_FocusIn 9 #define XI_FocusOut 10 #define XI_HierarchyChanged 11 #define XI_PropertyEvent 12 #define XI_RawKeyPress 13 #define XI_RawKeyRelease 14 #define XI_RawButtonPress 15 #define XI_RawButtonRelease 16 #define XI_RawMotion 17 #define XI_TouchBegin 18 /* XI 2.2 */ #define XI_TouchUpdate 19 #define XI_TouchEnd 20 #define XI_TouchOwnership 21 #define XI_RawTouchBegin 22 #define XI_RawTouchUpdate 23 #define XI_RawTouchEnd 24 #define XI_BarrierHit 25 /* XI 2.3 */ #define XI_BarrierLeave 26 #define XI_LASTEVENT XI_BarrierLeave /* NOTE: XI2LASTEVENT in xserver/include/inputstr.h must be the same value * as XI_LASTEVENT if the server is supposed to handle masks etc. for this * type of event. */ /* Event masks. * Note: the protocol spec defines a mask to be of (1 << type). Clients are * free to create masks by bitshifting instead of using these defines. */ #define XI_DeviceChangedMask (1 << XI_DeviceChanged) #define XI_KeyPressMask (1 << XI_KeyPress) #define XI_KeyReleaseMask (1 << XI_KeyRelease) #define XI_ButtonPressMask (1 << XI_ButtonPress) #define XI_ButtonReleaseMask (1 << XI_ButtonRelease) #define XI_MotionMask (1 << XI_Motion) #define XI_EnterMask (1 << XI_Enter) #define XI_LeaveMask (1 << XI_Leave) #define XI_FocusInMask (1 << XI_FocusIn) #define XI_FocusOutMask (1 << XI_FocusOut) #define XI_HierarchyChangedMask (1 << XI_HierarchyChanged) #define XI_PropertyEventMask (1 << XI_PropertyEvent) #define XI_RawKeyPressMask (1 << XI_RawKeyPress) #define XI_RawKeyReleaseMask (1 << XI_RawKeyRelease) #define XI_RawButtonPressMask (1 << XI_RawButtonPress) #define XI_RawButtonReleaseMask (1 << XI_RawButtonRelease) #define XI_RawMotionMask (1 << XI_RawMotion) #define XI_TouchBeginMask (1 << XI_TouchBegin) #define XI_TouchEndMask (1 << XI_TouchEnd) #define XI_TouchOwnershipChangedMask (1 << XI_TouchOwnership) #define XI_TouchUpdateMask (1 << XI_TouchUpdate) #define XI_RawTouchBeginMask (1 << XI_RawTouchBegin) #define XI_RawTouchEndMask (1 << XI_RawTouchEnd) #define XI_RawTouchUpdateMask (1 << XI_RawTouchUpdate) #define XI_BarrierHitMask (1 << XI_BarrierHit) #define XI_BarrierLeaveMask (1 << XI_BarrierLeave) #endif /* _XI2_H_ */ 07070100062361000081a400000000000000000000000153c4dc3f0000928e000001000001001cffffffffffffffff0000003100000000root/usr/local/include/X11/extensions/XI2proto.h/* * Copyright © 2009 Red Hat, Inc. * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice (including the next * paragraph) shall be included in all copies or substantial portions of the * Software. * * THE SOFTWARE IS PROVIDED "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. * */ /* Conventions for this file: * Names: * structs: always typedef'd, prefixed with xXI, CamelCase * struct members: lower_case_with_underscores * Exceptions: reqType, ReqType, repType, RepType, sequenceNumber are * named as such for historical reasons. * request opcodes: X_XIRequestName as CamelCase * defines: defines used in client applications must go in XI2.h * defines used only in protocol handling: XISOMENAME * * Data types: unless there is a historical name for a datatype (e.g. * Window), use stdint types specifying the size of the datatype. * historical data type names must be defined and undefined at the top and * end of the file. * * General: * spaces, not tabs. * structs specific to a request or reply added before the request * definition. structs used in more than one request, reply or event * appended to the common structs section before the definition of the * first request. * members of structs vertically aligned on column 16 if datatypes permit. * otherwise alingned on next available 8n column. */ /** * Protocol definitions for the XI2 protocol. * This file should not be included by clients that merely use XI2, but do not * need the wire protocol. Such clients should include XI2.h, or the matching * header from the library. * */ #ifndef _XI2PROTO_H_ #define _XI2PROTO_H_ #include #include #include #include /* make sure types have right sizes for protocol structures. */ #define Window uint32_t #define Time uint32_t #define Atom uint32_t #define Cursor uint32_t #define Barrier uint32_t /** * XI2 Request opcodes */ #define X_XIQueryPointer 40 #define X_XIWarpPointer 41 #define X_XIChangeCursor 42 #define X_XIChangeHierarchy 43 #define X_XISetClientPointer 44 #define X_XIGetClientPointer 45 #define X_XISelectEvents 46 #define X_XIQueryVersion 47 #define X_XIQueryDevice 48 #define X_XISetFocus 49 #define X_XIGetFocus 50 #define X_XIGrabDevice 51 #define X_XIUngrabDevice 52 #define X_XIAllowEvents 53 #define X_XIPassiveGrabDevice 54 #define X_XIPassiveUngrabDevice 55 #define X_XIListProperties 56 #define X_XIChangeProperty 57 #define X_XIDeleteProperty 58 #define X_XIGetProperty 59 #define X_XIGetSelectedEvents 60 #define X_XIBarrierReleasePointer 61 /** Number of XI requests */ #define XI2REQUESTS (X_XIBarrierReleasePointer - X_XIQueryPointer + 1) /** Number of XI2 events */ #define XI2EVENTS (XI_LASTEVENT + 1) /************************************************************************************* * * * COMMON STRUCTS * * * *************************************************************************************/ /** Fixed point 16.16 */ typedef int32_t FP1616; /** Fixed point 32.32 */ typedef struct { int32_t integral; uint32_t frac; } FP3232; /** * Struct to describe a device. * * For a MasterPointer or a MasterKeyboard, 'attachment' specifies the * paired master device. * For a SlaveKeyboard or SlavePointer, 'attachment' specifies the master * device this device is attached to. * For a FloatingSlave, 'attachment' is undefined. */ typedef struct { uint16_t deviceid; uint16_t use; /**< ::XIMasterPointer, ::XIMasterKeyboard, ::XISlavePointer, ::XISlaveKeyboard, ::XIFloatingSlave */ uint16_t attachment; /**< Current attachment or pairing.*/ uint16_t num_classes; /**< Number of classes following this struct. */ uint16_t name_len; /**< Length of name in bytes. */ uint8_t enabled; /**< TRUE if device is enabled. */ uint8_t pad; } xXIDeviceInfo; /** * Default template for a device class. * A device class is equivalent to a device's capabilities. Multiple classes * are supported per device. */ typedef struct { uint16_t type; /**< One of *class */ uint16_t length; /**< Length in 4 byte units */ uint16_t sourceid; /**< source device for this class */ uint16_t pad; } xXIAnyInfo; /** * Denotes button capability on a device. * Struct is followed by num_buttons * Atom that names the buttons in the * device-native setup (i.e. ignoring button mappings). */ typedef struct { uint16_t type; /**< Always ButtonClass */ uint16_t length; /**< Length in 4 byte units */ uint16_t sourceid; /**< source device for this class */ uint16_t num_buttons; /**< Number of buttons provided */ } xXIButtonInfo; /** * Denotes key capability on a device. * Struct is followed by num_keys * CARD32 that lists the keycodes available * on the device. */ typedef struct { uint16_t type; /**< Always KeyClass */ uint16_t length; /**< Length in 4 byte units */ uint16_t sourceid; /**< source device for this class */ uint16_t num_keycodes; /**< Number of keys provided */ } xXIKeyInfo; /** * Denotes an valuator capability on a device. * One XIValuatorInfo describes exactly one valuator (axis) on the device. */ typedef struct { uint16_t type; /**< Always ValuatorClass */ uint16_t length; /**< Length in 4 byte units */ uint16_t sourceid; /**< source device for this class */ uint16_t number; /**< Valuator number */ Atom label; /**< Axis label */ FP3232 min; /**< Min value */ FP3232 max; /**< Max value */ FP3232 value; /**< Last published value */ uint32_t resolution; /**< Resolutions in units/m */ uint8_t mode; /**< ModeRelative or ModeAbsolute */ uint8_t pad1; uint16_t pad2; } xXIValuatorInfo; /*** * Denotes a scroll valuator on a device. * One XIScrollInfo describes exactly one scroll valuator that must have a * XIValuatorInfo struct. */ typedef struct { uint16_t type; /**< Always ValuatorClass */ uint16_t length; /**< Length in 4 byte units */ uint16_t sourceid; /**< source device for this class */ uint16_t number; /**< Valuator number */ uint16_t scroll_type; /**< ::XIScrollTypeVertical, ::XIScrollTypeHorizontal */ uint16_t pad0; uint32_t flags; /**< ::XIScrollFlagEmulate, ::XIScrollFlagPreferred */ FP3232 increment; /**< Increment for one unit of scrolling */ } xXIScrollInfo; /** * Denotes multitouch capability on a device. */ typedef struct { uint16_t type; /**< Always TouchClass */ uint16_t length; /**< Length in 4 byte units */ uint16_t sourceid; /**< source device for this class */ uint8_t mode; /**< DirectTouch or DependentTouch */ uint8_t num_touches; /**< Maximum number of touches (0==unlimited) */ } xXITouchInfo; /** * Used to select for events on a given window. * Struct is followed by (mask_len * CARD8), with each bit set representing * the event mask for the given type. A mask bit represents an event type if * (mask == (1 << type)). */ typedef struct { uint16_t deviceid; /**< Device id to select for */ uint16_t mask_len; /**< Length of mask in 4 byte units */ } xXIEventMask; /** * XKB modifier information. * The effective modifier is a binary mask of base, latched, and locked * modifiers. */ typedef struct { uint32_t base_mods; /**< Logically pressed modifiers */ uint32_t latched_mods; /**< Logically latched modifiers */ uint32_t locked_mods; /**< Logically locked modifiers */ uint32_t effective_mods; /**< Effective modifiers */ } xXIModifierInfo; /** * XKB group information. * The effective group is the mathematical sum of base, latched, and locked * group after group wrapping is taken into account. */ typedef struct { uint8_t base_group; /**< Logically "pressed" group */ uint8_t latched_group; /**< Logically latched group */ uint8_t locked_group; /**< Logically locked group */ uint8_t effective_group; /**< Effective group */ } xXIGroupInfo; /************************************************************************************* * * * REQUESTS * * * *************************************************************************************/ /** * Query the server for the supported X Input extension version. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIQueryVersion */ uint16_t length; /**< Length in 4 byte units */ uint16_t major_version; uint16_t minor_version; } xXIQueryVersionReq; #define sz_xXIQueryVersionReq 8 typedef struct { uint8_t repType; /**< ::X_Reply */ uint8_t RepType; /**< Always ::X_XIQueryVersion */ uint16_t sequenceNumber; uint32_t length; uint16_t major_version; uint16_t minor_version; uint32_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; } xXIQueryVersionReply; #define sz_xXIQueryVersionReply 32 /** * Query the server for information about a specific device or all input * devices. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIQueryDevice */ uint16_t length; /**< Length in 4 byte units */ uint16_t deviceid; uint16_t pad; } xXIQueryDeviceReq; #define sz_xXIQueryDeviceReq 8 typedef struct { uint8_t repType; /**< ::X_Reply */ uint8_t RepType; /**< Always ::X_XIQueryDevice */ uint16_t sequenceNumber; uint32_t length; uint16_t num_devices; uint16_t pad0; uint32_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; } xXIQueryDeviceReply; #define sz_xXIQueryDeviceReply 32 /** * Select for events on a given window. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XISelectEvents */ uint16_t length; /**< Length in 4 byte units */ Window win; uint16_t num_masks; uint16_t pad; } xXISelectEventsReq; #define sz_xXISelectEventsReq 12 /** * Query for selected events on a given window. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIGetSelectedEvents */ uint16_t length; /**< Length in 4 byte units */ Window win; } xXIGetSelectedEventsReq; #define sz_xXIGetSelectedEventsReq 8 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_XIGetSelectedEvents */ uint16_t sequenceNumber; uint32_t length; uint16_t num_masks; /**< Number of xXIEventMask structs trailing the reply */ uint16_t pad0; uint32_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; } xXIGetSelectedEventsReply; #define sz_xXIGetSelectedEventsReply 32 /** * Query the given device's screen/window coordinates. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIQueryPointer */ uint16_t length; /**< Length in 4 byte units */ Window win; uint16_t deviceid; uint16_t pad1; } xXIQueryPointerReq; #define sz_xXIQueryPointerReq 12 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_XIQueryPointer */ uint16_t sequenceNumber; uint32_t length; Window root; Window child; FP1616 root_x; FP1616 root_y; FP1616 win_x; FP1616 win_y; uint8_t same_screen; uint8_t pad0; uint16_t buttons_len; xXIModifierInfo mods; xXIGroupInfo group; } xXIQueryPointerReply; #define sz_xXIQueryPointerReply 56 /** * Warp the given device's pointer to the specified position. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIWarpPointer */ uint16_t length; /**< Length in 4 byte units */ Window src_win; Window dst_win; FP1616 src_x; FP1616 src_y; uint16_t src_width; uint16_t src_height; FP1616 dst_x; FP1616 dst_y; uint16_t deviceid; uint16_t pad1; } xXIWarpPointerReq; #define sz_xXIWarpPointerReq 36 /** * Change the given device's sprite to the given cursor. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIChangeCursor */ uint16_t length; /**< Length in 4 byte units */ Window win; Cursor cursor; uint16_t deviceid; uint16_t pad1; } xXIChangeCursorReq; #define sz_xXIChangeCursorReq 16 /** * Modify the device hierarchy. */ typedef struct { uint8_t reqType; /**< Input extension major code */ uint8_t ReqType; /**< Always ::X_XIChangeHierarchy */ uint16_t length; /**< Length in 4 byte units */ uint8_t num_changes; uint8_t pad0; uint16_t pad1; } xXIChangeHierarchyReq; #define sz_xXIChangeHierarchyReq 8 /** * Generic header for any hierarchy change. */ typedef struct { uint16_t type; uint16_t length; /**< Length in 4 byte units */ } xXIAnyHierarchyChangeInfo; /** * Create a new master device. * Name of new master follows struct (4-byte padded) */ typedef struct { uint16_t type; /**< Always ::XIAddMaster */ uint16_t length; /**< 2 + (namelen + padding)/4 */ uint16_t name_len; uint8_t send_core; uint8_t enable; } xXIAddMasterInfo; /** * Delete a master device. Will automatically delete the master device paired * with the given master device. */ typedef struct { uint16_t type; /**< Always ::XIRemoveMaster */ uint16_t length; /**< 3 */ uint16_t deviceid; uint8_t return_mode; /**< ::XIAttachToMaster, ::XIFloating */ uint8_t pad; uint16_t return_pointer; /**< Pointer to attach slave ptr devices to */ uint16_t return_keyboard; /**< keyboard to attach slave keybd devices to*/ } xXIRemoveMasterInfo; /** * Attach an SD to a new device. * NewMaster has to be of same type (pointer->pointer, keyboard->keyboard); */ typedef struct { uint16_t type; /**< Always ::XIAttachSlave */ uint16_t length; /**< 2 */ uint16_t deviceid; uint16_t new_master; /**< id of new master device */ } xXIAttachSlaveInfo; /** * Detach an SD from its current master device. */ typedef struct { uint16_t type; /**< Always ::XIDetachSlave */ uint16_t length; /**< 2 */ uint16_t deviceid; uint16_t pad; } xXIDetachSlaveInfo; /** * Set the window/client's ClientPointer. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XISetClientPointer */ uint16_t length; /**< Length in 4 byte units */ Window win; uint16_t deviceid; uint16_t pad1; } xXISetClientPointerReq; #define sz_xXISetClientPointerReq 12 /** * Query the given window/client's ClientPointer setting. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_GetClientPointer */ uint16_t length; /**< Length in 4 byte units */ Window win; } xXIGetClientPointerReq; #define sz_xXIGetClientPointerReq 8 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_GetClientPointer */ uint16_t sequenceNumber; uint32_t length; BOOL set; /**< client pointer is set? */ uint8_t pad0; uint16_t deviceid; uint32_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; } xXIGetClientPointerReply; #define sz_xXIGetClientPointerReply 32 /** * Set the input focus to the specified window. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XISetFocus */ uint16_t length; /**< Length in 4 byte units */ Window focus; Time time; uint16_t deviceid; uint16_t pad0; } xXISetFocusReq; #define sz_xXISetFocusReq 16 /** * Query the current input focus. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIGetDeviceFocus */ uint16_t length; /**< Length in 4 byte units */ uint16_t deviceid; uint16_t pad0; } xXIGetFocusReq; #define sz_xXIGetFocusReq 8 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_XIGetFocus */ uint16_t sequenceNumber; uint32_t length; Window focus; uint32_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; } xXIGetFocusReply; #define sz_xXIGetFocusReply 32 /** * Grab the given device. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIGrabDevice */ uint16_t length; /**< Length in 4 byte units */ Window grab_window; Time time; Cursor cursor; uint16_t deviceid; uint8_t grab_mode; uint8_t paired_device_mode; uint8_t owner_events; uint8_t pad; uint16_t mask_len; } xXIGrabDeviceReq; #define sz_xXIGrabDeviceReq 24 /** * Return codes from a XIPassiveGrabDevice request. */ typedef struct { uint32_t modifiers; /**< Modifier state */ uint8_t status; /**< Grab status code */ uint8_t pad0; uint16_t pad1; } xXIGrabModifierInfo; typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_XIGrabDevice */ uint16_t sequenceNumber; uint32_t length; uint8_t status; uint8_t pad0; uint16_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; uint32_t pad6; } xXIGrabDeviceReply; #define sz_xXIGrabDeviceReply 32 /** * Ungrab the specified device. * */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIUngrabDevice */ uint16_t length; /**< Length in 4 byte units */ Time time; uint16_t deviceid; uint16_t pad; } xXIUngrabDeviceReq; #define sz_xXIUngrabDeviceReq 12 /** * Allow or replay events on the specified grabbed device. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIAllowEvents */ uint16_t length; /**< Length in 4 byte units */ Time time; uint16_t deviceid; uint8_t mode; uint8_t pad; } xXIAllowEventsReq; #define sz_xXIAllowEventsReq 12 /** * Allow or replay events on the specified grabbed device. * Since XI 2.2 */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIAllowEvents */ uint16_t length; /**< Length in 4 byte units */ Time time; uint16_t deviceid; uint8_t mode; uint8_t pad; uint32_t touchid; /**< Since XI 2.2 */ Window grab_window; /**< Since XI 2.2 */ } xXI2_2AllowEventsReq; #define sz_xXI2_2AllowEventsReq 20 /** * Passively grab the device. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIPassiveGrabDevice */ uint16_t length; /**< Length in 4 byte units */ Time time; Window grab_window; Cursor cursor; uint32_t detail; uint16_t deviceid; uint16_t num_modifiers; uint16_t mask_len; uint8_t grab_type; uint8_t grab_mode; uint8_t paired_device_mode; uint8_t owner_events; uint16_t pad1; } xXIPassiveGrabDeviceReq; #define sz_xXIPassiveGrabDeviceReq 32 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_XIPassiveGrabDevice */ uint16_t sequenceNumber; uint32_t length; uint16_t num_modifiers; uint16_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; uint32_t pad6; } xXIPassiveGrabDeviceReply; #define sz_xXIPassiveGrabDeviceReply 32 /** * Delete a passive grab for the given device. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIPassiveUngrabDevice */ uint16_t length; /**< Length in 4 byte units */ Window grab_window; uint32_t detail; uint16_t deviceid; uint16_t num_modifiers; uint8_t grab_type; uint8_t pad0; uint16_t pad1; } xXIPassiveUngrabDeviceReq; #define sz_xXIPassiveUngrabDeviceReq 20 /** * List all device properties on the specified device. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIListProperties */ uint16_t length; /**< Length in 4 byte units */ uint16_t deviceid; uint16_t pad; } xXIListPropertiesReq; #define sz_xXIListPropertiesReq 8 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always ::X_XIListProperties */ uint16_t sequenceNumber; uint32_t length; uint16_t num_properties; uint16_t pad0; uint32_t pad1; uint32_t pad2; uint32_t pad3; uint32_t pad4; uint32_t pad5; } xXIListPropertiesReply; #define sz_xXIListPropertiesReply 32 /** * Change a property on the specified device. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always ::X_XIChangeProperty */ uint16_t length; /**< Length in 4 byte units */ uint16_t deviceid; uint8_t mode; uint8_t format; Atom property; Atom type; uint32_t num_items; } xXIChangePropertyReq; #define sz_xXIChangePropertyReq 20 /** * Delete the specified property. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always X_XIDeleteProperty */ uint16_t length; /**< Length in 4 byte units */ uint16_t deviceid; uint16_t pad0; Atom property; } xXIDeletePropertyReq; #define sz_xXIDeletePropertyReq 12 /** * Query the specified property's values. */ typedef struct { uint8_t reqType; uint8_t ReqType; /**< Always X_XIGetProperty */ uint16_t length; /**< Length in 4 byte units */ uint16_t deviceid; #if defined(__cplusplus) || defined(c_plusplus) uint8_t c_delete; #else uint8_t delete; #endif uint8_t pad0; Atom property; Atom type; uint32_t offset; uint32_t len; } xXIGetPropertyReq; #define sz_xXIGetPropertyReq 24 typedef struct { uint8_t repType; /**< Input extension major opcode */ uint8_t RepType; /**< Always X_XIGetProperty */ uint16_t sequenceNumber; uint32_t length; Atom type; uint32_t bytes_after; uint32_t num_items; uint8_t format; uint8_t pad0; uint16_t pad1; uint32_t pad2; uint32_t pad3; } xXIGetPropertyReply; #define sz_xXIGetPropertyReply 32 typedef struct { uint16_t deviceid; uint16_t pad; Barrier barrier; uint32_t eventid; } xXIBarrierReleasePointerInfo; typedef struct { uint8_t reqType; /**< Input extension major opcode */ uint8_t ReqType; /**< Always X_XIBarrierReleasePointer */ uint16_t length; uint32_t num_barriers; /* array of xXIBarrierReleasePointerInfo */ } xXIBarrierReleasePointerReq; #define sz_xXIBarrierReleasePointerReq 8 /************************************************************************************* * * * EVENTS * * * *************************************************************************************/ /** * Generic XI2 event header. All XI2 events use the same header. */ typedef struct { uint8_t type; uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; uint16_t evtype; uint16_t deviceid; Time time; } xXIGenericDeviceEvent; /** * Device hierarchy information. */ typedef struct { uint16_t deviceid; uint16_t attachment; /**< ID of master or paired device */ uint8_t use; /**< ::XIMasterKeyboard, ::XIMasterPointer, ::XISlaveKeyboard, ::XISlavePointer, ::XIFloatingSlave */ BOOL enabled; /**< TRUE if the device is enabled */ uint16_t pad; uint32_t flags; /**< ::XIMasterAdded, ::XIMasterRemoved, ::XISlaveAttached, ::XISlaveDetached, ::XISlaveAdded, ::XISlaveRemoved, ::XIDeviceEnabled, ::XIDeviceDisabled */ } xXIHierarchyInfo; /** * The device hierarchy has been modified. This event includes the device * hierarchy after the modification has been applied. */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte units */ uint16_t evtype; /**< ::XI_Hierarchy */ uint16_t deviceid; Time time; uint32_t flags; /**< ::XIMasterAdded, ::XIMasterDeleted, ::XISlaveAttached, ::XISlaveDetached, ::XISlaveAdded, ::XISlaveRemoved, ::XIDeviceEnabled, ::XIDeviceDisabled */ uint16_t num_info; uint16_t pad0; uint32_t pad1; uint32_t pad2; } xXIHierarchyEvent; /** * A device has changed capabilities. */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte units */ uint16_t evtype; /**< XI_DeviceChanged */ uint16_t deviceid; /**< Device that has changed */ Time time; uint16_t num_classes; /**< Number of classes that have changed */ uint16_t sourceid; /**< Source of the new classes */ uint8_t reason; /**< ::XISlaveSwitch, ::XIDeviceChange */ uint8_t pad0; uint16_t pad1; uint32_t pad2; uint32_t pad3; } xXIDeviceChangedEvent; /** * The owner of a touch stream has passed on ownership to another client. */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte units */ uint16_t evtype; /**< XI_TouchOwnership */ uint16_t deviceid; /**< Device that has changed */ Time time; uint32_t touchid; Window root; Window event; Window child; /* └──────── 32 byte boundary ────────┘ */ uint16_t sourceid; uint16_t pad0; uint32_t flags; uint32_t pad1; uint32_t pad2; } xXITouchOwnershipEvent; /** * Default input event for pointer, keyboard or touch input. */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte uints */ uint16_t evtype; uint16_t deviceid; Time time; uint32_t detail; /**< Keycode or button */ Window root; Window event; Window child; /* └──────── 32 byte boundary ────────┘ */ FP1616 root_x; /**< Always screen coords, 16.16 fixed point */ FP1616 root_y; FP1616 event_x; /**< Always screen coords, 16.16 fixed point */ FP1616 event_y; uint16_t buttons_len; /**< Len of button flags in 4 b units */ uint16_t valuators_len; /**< Len of val. flags in 4 b units */ uint16_t sourceid; /**< The source device */ uint16_t pad0; uint32_t flags; /**< ::XIKeyRepeat */ xXIModifierInfo mods; xXIGroupInfo group; } xXIDeviceEvent; /** * Sent when an input event is generated. RawEvents include valuator * information in both device-specific data (i.e. unaccelerated) and * processed data (i.e. accelerated, if applicable). */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte uints */ uint16_t evtype; /**< ::XI_RawEvent */ uint16_t deviceid; Time time; uint32_t detail; uint16_t sourceid; /**< The source device (XI 2.1) */ uint16_t valuators_len; /**< Length of trailing valuator mask in 4 byte units */ uint32_t flags; /**< ::XIKeyRepeat */ uint32_t pad2; } xXIRawEvent; /** * Note that the layout of root, event, child, root_x, root_y, event_x, * event_y must be identical to the xXIDeviceEvent. */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte uints */ uint16_t evtype; /**< ::XI_Enter */ uint16_t deviceid; Time time; uint16_t sourceid; uint8_t mode; uint8_t detail; Window root; Window event; Window child; /* └──────── 32 byte boundary ────────┘ */ FP1616 root_x; FP1616 root_y; FP1616 event_x; FP1616 event_y; BOOL same_screen; BOOL focus; uint16_t buttons_len; /**< Length of trailing button mask in 4 byte units */ xXIModifierInfo mods; xXIGroupInfo group; } xXIEnterEvent; typedef xXIEnterEvent xXILeaveEvent; typedef xXIEnterEvent xXIFocusInEvent; typedef xXIEnterEvent xXIFocusOutEvent; /** * Sent when a device property is created, modified or deleted. Does not * include property data, the client is required to query the data. */ typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte units */ uint16_t evtype; /**< ::XI_PropertyEvent */ uint16_t deviceid; Time time; Atom property; uint8_t what; /**< ::XIPropertyDeleted, ::XIPropertyCreated, ::XIPropertyMotified */ uint8_t pad0; uint16_t pad1; uint32_t pad2; uint32_t pad3; } xXIPropertyEvent; typedef struct { uint8_t type; /**< Always GenericEvent */ uint8_t extension; /**< XI extension offset */ uint16_t sequenceNumber; uint32_t length; /**< Length in 4 byte units */ uint16_t evtype; /**< ::XI_BarrierHit or ::XI_BarrierLeave */ uint16_t deviceid; Time time; uint32_t eventid; Window root; Window event; Barrier barrier; /* └──────── 32 byte boundary ────────┘ */ uint32_t dtime; uint32_t flags; /**< ::XIBarrierPointerReleased ::XIBarrierDeviceIsGrabbed */ uint16_t sourceid; int16_t pad; FP1616 root_x; FP1616 root_y; FP3232 dx; FP3232 dy; } xXIBarrierEvent; typedef xXIBarrierEvent xXIBarrierHitEvent; typedef xXIBarrierEvent xXIBarrierPointerReleasedEvent; typedef xXIBarrierEvent xXIBarrierLeaveEvent; #undef Window #undef Time #undef Atom #undef Cursor #undef Barrier #endif /* _XI2PROTO_H_ */ 07070100000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000b00000000TRAILER!!!