This document describes an extension to the X11 server. The purpose of this extension is to support the use of additional input devices beyond the pointer and keyboard devices defined by the core X protocol. This first section gives an overview of the input extension. The following sections correspond to chapters 7 and 8, “Window Manager functions” and “Events and Event-Handling Functions” of the “Xlib - C Language Interface” manual and describe how to use the input extension.
The design approach of the extension is to define functions and events analogous to the core functions and events. This allows extension input devices and events to be individually distinguishable from each other and from the core input devices and events. These functions 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 currently reportable via the core input events.
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.
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.
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. Functions are defined that allow client programs to change which physical devices are used as the core devices.
The input extension 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. 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.
Extension input events are not limited in size by the size of the server 32-byte wire events. Extension input events may be constructed by the server sending as many wire sized events as necessary to return the information required for that event. The library event reformatting routines are responsible for combining these into one or more client XEvents.
Any input device that generates key, button or motion data 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 device classes. Server implementors may add new classes of input devices without changing the protocol requests.
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.
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 functions. 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. | |
| FEEDBACK | The device supports feedbacks. |
Additional classes may be added in the future. Functions that support multiple input classes, such as the XListInputDevices function that lists all available input devices, organize the data they return by input class. Client programs that use these functions 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 functions to be recompiled.
A client that wishes to access an input device does so through the library functions defined in the following sections. A typical sequence of requests that a client would make is as follows:
XListInputDevices - list all of the available input devices. From the information returned by this request, determine whether the desired input device is attached to the server. For a description of the XListInputDevices request, see the section entitled “Listing Available Devices.”
XOpenDevice - request that the server open the device for access by this client. This request returns an XDevice structure that is used by most other input extension requests to identify the specified device. For a description of the XOpenDevice request, see the section entitled “Enabling and Disabling Extension Devices.”
Determine the event types and event clases needed to select the desired input extension events, and identify them when they are received. This is done via macros whose name corresponds to the desired event, i.e. DeviceKeyPress. For a description of these macros, see the section entitled “Selecting Extension Device Events.”
XSelectExtensionEvent - select the desired events from the server. For a description of the XSelextExtensionEvent request, see the section entitled “Selecting Extension Device Events.”
XNextEvent - receive the next available event. This is the core XNextEvent function provided by the standard X libarary.
Other requests are defined to grab and focus extension devices, to change their key, button, or modifier mappings, to control the propagation of input extension events, to get motion history from an extension device, and to send input extension events to another client. These functions are described in the following sections.