x11proto-input: Changes to 'upstream-experimental'
Makefile.am | 2
XIproto.txt | 2542 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
configure.ac | 12
3 files changed, 2549 insertions(+), 7 deletions(-)
New commits:
commit 34a9ab1151fb7b35a371cc98a34a20993816f78a
Author: Peter Hutterer <peter.hutterer@who-t.net>
Date: Fri Oct 2 11:38:12 2009 +1000
inputproto 2.0
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
diff --git a/configure.ac b/configure.ac
index 5c43cca..1052dc2 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,5 +1,5 @@
AC_PREREQ([2.57])
-AC_INIT([InputProto], [1.9.99.902], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
+AC_INIT([InputProto], [2.0], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AM_INIT_AUTOMAKE([foreign dist-bzip2])
# Require xorg-macros: XORG_DEFAULT_OPTIONS
commit 0470d29c1e690f3784ca1a42f6d27aa322f9b37a
Author: Peter Hutterer <peter.hutterer@who-t.net>
Date: Thu Oct 1 16:47:11 2009 +1000
Add XIproto.txt
This is the XI protocol specification document that used to be in xorg-docs.
It's now moved here, and if it ever sees updates, the updates will only
apply to here.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
diff --git a/Makefile.am b/Makefile.am
index f41d768..85ca02f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -10,7 +10,7 @@ pkgconfig_DATA = inputproto.pc
EXTRA_DIST = inputproto.pc.in
-EXTRA_DIST += ChangeLog XI2proto.txt
+EXTRA_DIST += ChangeLog XI2proto.txt XIproto.txt
MAINTAINERCLEANFILES = ChangeLog
.PHONY: ChangeLog
diff --git a/XIproto.txt b/XIproto.txt
new file mode 100644
index 0000000..20cc02a
--- /dev/null
+++ b/XIproto.txt
@@ -0,0 +1,2542 @@
+ 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
+ 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
+ Errors: Window
+ =>
+ dont-propagate-list: LISTofEVENTCLASS
+
+ 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
Reply to: