inputproto-2.2.tar.gz

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