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.
Note: 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, and so on) 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 zero or more keys, zero or more buttons, and may report zero 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:
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:
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.
Extension input devices are accessed by client programs through the use of new protocol requests. The following requests are provided as extensions to Xlib. Constants and structures referenced by these functions may be found in the files XI.h and XInput.h, which are attached to this document as appendix A.
The library returns NoSuchExtension if an extension request is made to a server that does not support the input extension. Input extension requests cannot be used to access the X keyboard and X pointer devices.
These functions are provided to change which physical device is used as the X pointer or X keyboard.
Note: Using these functions 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 indices into that array. Changing the core devices could cause such client programs to behave improperly or abnormally terminate, if they ignore the ChangeDeviceNotify event generated by these requests.
These functions change the X keyboard or X pointer device and generate an XChangeDeviceNotify event and a MappingNotify event. 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, has not previously been opened via an XOpenDevice request, or is not supported as a core device by the server implementation.
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 does not cause it to change back. Attempts to use the XCloseDevice request to close the new core device fails with a BadDevice error.
The XChangeKeyboardDevice function is used to change which physical device is used as the X keyboard.
The XChangePointerDevice function is used to change which physical device is used as the X pointer.
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 PointerMode and KeyboardMode argument. The meaning of these modes is changed by the input extension. For the XGrabPointer and XGrabButton requests, PointerMode controls synchronization of the pointer device, and KeyboardMode controls the synchronization of all other input devices. For the XGrabKeyboard and XGrabKey requests, PointerMode controls the synchronization of all input devices except the X keyboard, while KeyboardMode 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.
Active grabs of extension devices are supported through the XGrabDevice function in the same way that core devices are grabbed using the core XGrabKeyboard function, except that a device is passed as a function parameter. The XUngrabDevice function allows a previous active grab for an extension device to be released.
Passive grabs of buttons and keys on extension devices are supported through the XGrabDeviceButton and XGrabDeviceKey functions. These passive grabs are released through the XUngrabDeviceKey and XUngrabDeviceButton functions.
The XAllowDeviceEvents function allows further events to be processed when a device has been frozen.
The current focus window for an extension input device can be determined using the XGetDeviceFocus function. Extension devices are focused using the XSetDeviceFocus function in the same way that the keyboard is focused using the core XSetInputFocus function, except that a device ID is passed as a function parameter. One additional focus state, FollowKeyboard, is provided for extension devices.
The current feedback settings of an extension input device are determined using the XGetFeedbackControl function. The XFreeFeedbackList function frees the list of feedback control information returned by the XGetFeedbackControl function.
The settings of a feedback on an extension device can be changed using the XChangeFeedbackControl function. This function modifies the current control values of the specified feedback using information passed in the appropriate XFeedbackControl structure for the feedback. Which values are modified depends on the valuemask passed.
A bell on a specified extension input device can be set to ring using the XDeviceBell function.
The keyboard mapping of an extension device that supports input class Keys can be obtained by using the XGetDeviceKeyMapping function. The XFree function frees the data returned by the XGetDeviceKeyMapping function.The keyboard mapping of an extension device that supports input class Keys can be changed using the XChangeDeviceKeyMapping function.
The keycodes that are used as modifiers on an extension device that supports input class Keys are obtained by using the XGetDeviceModifierMapping function. The keycodes that are to be used as modifiers for an extension device are set using the XSetDeviceModifierMapping function.
The mapping of the buttons on an extension device is set using the XSetDeviceButtonMapping function. The button mapping on an extension device is obtained using the XGetDeviceButtonMapping function.
To obtain information that describes the state of the keys, buttons and valuators of an extension device, use the XQueryDeviceState function. The XFreeDeviceState function frees the device state data.
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. The following sections describe these events and explain how a client program can receive them.
Event types are integer numbers that a client can use to determine what kind of event it has received. The client compares the type field of the event structure with known event types to make this determination. The core input event types are constants and are defined in the header file <X11/X.h>. Extension event types are not constants. Instead, they are dynamically allocated by the extension's request to the X server when the extension is initialized. Because of this, extension event types must be obtained by the client from the server. The client program determines the event type for an extension event by using the information returned by the XOpenDevice request. This type can then be used for comparison with the type field of events received by the client. 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. The following lists the event category and its associated event type or types.
Event classes are integer numbers that are used in the same way as the core event masks. They are used by a client program to indicate to the server which events that client program wishes to receive.
The core input event masks are constants and are defined in the header file <X11/X.h>. Extension event classes are not constants. Instead, they are dynamically allocated by the extension's request to the X server when the extension is initialized. Because of this, extension event classes must be obtained by the client from the server.
The event class for an extension event and device is obtained from information returned by the XOpenDevice function. This class can then be used in an XSelectExtensionEvent request to ask that events of that type from that device be sent to the client program.
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 receives a DeviceButtonRelease event for each DeviceButtonPress event it receives, it should specify the DeviceButtonPressGrab class in addition to the DeviceButtonPress 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 either DeviceButtonPress or DeviceButtonPressGrab causes an Access error to be generated.
If only the DeviceButtonPress class is specified, no implicit passive grab is done when a button is pressed on the device. Multiple clients may use this class to specify the same device and window combination.
The client may also select DeviceMotion events only when a button is down. It does this by specifying the event classes DeviceButton1Motion through DeviceButton5Motion. An input device only supports as many button motion classes as it has buttons.
Each extension event type has a corresponding structure declared in <X11/XInput.h>. All event structures have the following members:
Extension event structures report the current position of the X pointer. In addition, if the device reports motion data and is reporting absolute data, the current value of any valuators the device contains is also reported.
Key events from extension devices contain all the information that is contained in a key event from the X keyboard. In addition, they contain a device ID and report the current value of any valuators on the device, if that device is reporting absolute data. If data for more than six valuators is being reported, more than one key event is sent. The axes_count field contains the number of axes that are being reported. The server sends as many of these events as are needed to report the device data. Each event contains the total number of axes reported in the axes_count field, and the first axis reported in the current event in the first_axis field. If the device supports input class Valuators, but is not reporting absolute mode data, the axes_count field contains 0 (zero). The location reported in the x , y and x_root , y_root fields is the location of the core X pointer. The XDeviceKeyEvent structure is defined as follows:
typedef struct
{
int type; /* of event */
unsigned long serial; /* # of last request processed*/
Bool send_event; /* true if from SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* "event" window reported relative to */
XID deviceid;
Window root; /* root window event occurred on*/
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* x, y coordinates in eventwindow */
int x_root; /* coordinates relative to root */
int y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
unsigned int keycode; /* detail */
Bool same_screen; /* same screen flag */
unsigned char axes_count;
unsigned char first_axis;
unsigned int device_state; /* device key or button mask */
int axis_data[6];
} XDeviceKeyEvent;
typedef XDeviceKeyEvent XDeviceKeyPressedEvent;
typedef XDeviceKeyEvent XDeviceKeyReleasedEvent;
Button events from extension devices contain all the information that is contained in a button event from the X pointer. In addition, they contain a device ID and report the current value of any valuators on the device, if that device is reporting absolute data. If data for more than six valuators is being reported, more than one button event may be sent. The axes_count field contains the number of axes that are being reported. The server sends as many of these events as are needed to report the device data. Each event contains the total number of axes reported in the axes_count field, and the first axis reported in the current event in the first_axis field. If the device supports input class Valuators, but is not reporting absolute mode data, the axes_count field contains 0. The location reported in the x , y and x_root , y_root fields is the location of the core X pointer.
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by
server*/
Bool send_event; /* true if from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* "event" window reported relative to */
XID deviceid;
Window root; /* root window that the event occurred
on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* x, y coordinates in event window */
int x_root; /* coordinates relative to root */
int y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
unsigned int button; /* detail */
Bool same_screen; /* same screen flag */
unsigned char axes_count;
unsigned char first_axis;
unsigned int device_state; /* device key or button mask */
int axis_data[6];
} XDeviceButtonEvent;
typedef XDeviceButtonEvent XDeviceButtonPressedEvent;
typedef XDeviceButtonEvent XDeviceButtonReleasedEvent;
Motion events from extension devices contain all the information that is contained in a motion event from the X pointer. In addition, they contain a device ID and report the current value of any valuators on the device. The location reported in the x , y and x_root , y_root fields is the location of the core X pointer, and so is 2-dimensional. Extension motion devices may report motion data for a variable number of axes. The axes_count field contains the number of axes that are being reported. The server sends as many of these events as are needed to report the device data. Each event contains the total number of axes reported in the axes_count field, and the first axis reported in the current event in the first_axis field.
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* "event" window reportedrelative to */
XID deviceid;
Window root; /* root window that the eventoccurred on */
Window subwindow; /* child window */
Time time; /* milliseconds */
int x, y; /* x, y coordinates in eventwindow */
int x_root; /* coordinates relative to root */
int y_root; /* coordinates relative to root */
unsigned int state; /* key or button mask */
char is_hint; /* detail */
Bool same_screen; /* same screen flag */
unsigned int device_state; /* device key or button mask */
unsigned char axes_count;
unsigned char first_axis;
int axis_data[6];
} XDeviceMotionEvent;
These events are equivalent to the core focus events. They contain the same information, with the addition of a device ID to identify which device has had a focus change, and a time stamp. DeviceFocusIn and DeviceFocusOut events are generated for focus changes of extension devices in the same manner as core focus events are generated.
typedef struct
{
int type; /* of event */
unsigned long serial; /* # of last request processed by
server */
Bool send_event; /* true if this came from a SendEvent
request */
Display *display; /* Display the event was read from */
Window window; /* "event" window it is reported
relative to */
XID deviceid;
int mode; /* NotifyNormal, NotifyGrab,NotifyUngrab */
int detail; /*
* NotifyAncestor, NotifyVirtual, NotifyInferior,
* NotifyNonLinear,NotifyNonLinearVirtual, NotifyPointer,
* NotifyPointerRoot, NotifyDetailNone
*/
Time time;
} XDeviceFocusChangeEvent;
typedef XDeviceFocusChangeEvent XDeviceFocusInEvent;
typedef XDeviceFocusChangeEvent XDeviceFocusOutEvent;
This event is analogous to the core keymap event, but reports the current state of the device for each input class that it supports. It is generated after every DeviceFocusIn event and EnterNotify event and is delivered to clients who have selected XDeviceStateNotify events. If the device supports input class Valuators, the mode field in the XValuatorStatus structure is a bitmask that reports the device mode, proximity state and other state information. The following bits are currently defined:
0x01 Relative = 0, Absolute = 1 0x02 InProximity = 0, OutOfProximity = 1
If the device supports more valuators than can be reported in a single XEvent, multiple XDeviceStateNotify events are generated.
typedef struct
{
unsigned char class;
unsigned char length;
} XInputClass;
typedef struct {
int type;
unsigned long serial; /* # of last request processed by
server */
Bool send_event; /* true if this came from a SendEvent
request */
Display *display; /* Display the event was read from */
Window window;
XID deviceid;
Time time;
int num_classes;
char data[64];
} XDeviceStateNotifyEvent;
typedef struct {
unsigned char class;
unsigned char length;
unsigned char num_valuators;
unsigned char mode;
int valuators[6];
} XValuatorStatus;
typedef struct {
unsigned char class;
unsigned char length;
short num_keys;
char keys[32];
} XKeyStatus;
typedef struct {
unsigned char class;
unsigned char length;
short num_buttons;
char buttons[32];
} XButtonStatus;
This event is equivalent to the core MappingNotify event. It notifies client programs when the mapping of keys, modifiers, or buttons on an extension device has changed.
typedef struct {
int type;
unsigned long serial;
Bool send_event;
Display *display;
Window window;
XID deviceid;
Time time;
int request;
int first_keycode;
int count;
} XDeviceMappingEvent;
This event has no equivalent in the core protocol. It notifies client programs when one of the core devices has been changed.
typedef struct {
int type;
unsigned long serial;
Bool send_event;
Display *display;
Window window;
XID deviceid;
Time time;
int request;
} XChangeDeviceNotifyEvent;
These events have no equivalent in the core protocol. Some input devices such as graphics tablets or touch screens may send these events to indicate that a stylus has moved into or out of contact with a positional sensing surface. The event contains the current value of any valuators on the device, if that device is reporting absolute data. If data for more than six valuators is being reported, more than one proximity event may be sent. The axes_count field contains the number of axes that are being reported. The server sends as many of these events as are needed to report the device data. Each event contains the total number of axes reported in the axes_count field, and the first axis reported in the current event in the first_axis field. If the device supports input class Valuators, but is not reporting absolute mode data, the axes_count field contains 0.
typedef struct
{
int type; /* ProximityIn or ProximityOut */
unsigned long serial; /* # of last request processed
by server */
Bool send_event; /* true if this came from a
SendEvent request */
Display *display; /* Display the event was read from */
Window window;
XID deviceid;
Window root;
Window subwindow;
Time time;
int x, y;
int x_root, y_root;
unsigned int state;
Bool same_screen;
unsigned char axes_count;
unsigned char first_axis;
unsigned int device_state; /* device key or button mask */
int axis_data[6];
} XProximityNotifyEvent;
typedef XProximityNotifyEvent XProximityInEvent;
typedef XProximityNotifyEvent XProximityOutEvent;
The XExtensionVersion function allows a client to determine if a server supports the desired version of the input extension. The XExtensionVersion structure returns information about the version of the extension supported by the server.
A client program that wishes to access a specific device must first determine whether that device is connected to the X server. This is done through the XListInputDevices function, which returns a list of all devices that can be opened by the X server. The client program can use one of the names defined in the XI.h header file in an XInternAtom request, to determine the device type of the desired device. This type can then be compared with the device types returned by the XListInputDevices request. The XFreeDeviceList function frees the list of input device information.
Each client program that wishes to access an extension device must request that the server open that device. This is done through the XOpenDevice request.
Before terminating, the client program should request that the server close the device. This is done through the XCloseDevice 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 XCloseDevice request terminates 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, any queued events are released. If a client program terminates without closing a device, the server automatically closes that device on behalf of the client. This does not affect any other clients that may be accessing that device.
Some devices are capable of reporting either relative or absolute motion data. The mode of a device is changed from relative to absolute using the XSetDeviceMode function. The valid values are Absolute or Relative.
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. The valuators on such a device are initialized using the XSetDeviceValuators function.
Some input devices support various configuration controls that can be queried or changed by clients. The set of supported controls varies from one input device to another. Requests to manipulate these controls fail if either the target X server or the target input device does not support the requested device control. Each device control has a unique identifier. Information passed with each device control varies in length and is mapped by data structures unique to that device control. Device controls are queried using the XGetDeviceControl function.
Some input devices support various configuration controls that can be changed by clients using the XChangeDeviceControl function. Typically, this would be done to initialize the device to a known state or configuration. The set of supported controls vary from one input device to another. Requests to manipulate these controls fail if either the target X server or the target input device does not support the requested device control. Setting the device control also fails if the target input device is grabbed by another client, or is open by another client and has been set to a conflicting state.
Device input events are selected using the XSelectExtensionEvent function. The parameters passed are a pointer to a list of classes that define the desired event types and devices, a count of the number of elements in the list, and the ID of the window from which events are desired.
The extension events that are currently selected from a given window can be determined using the XGetSelectedExtensionEvents function.
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 can control event propagation through the use of the XChangeDeviceDontPropagateList and XGetDeviceDontPropagateList functions.
The XChangeDeviceDontPropagateList function adds an event to or deletes an event from the do_not_propagate list of extension events for the specified window. There is one list per window, and the list remains for the life of the window. The list is not altered if a client that changed the list terminates. The XGetDeviceDontPropagateList function allows a
client to determine the do_not_propagate list of extension events for the specified window. The XSendExtensionEvent function allows a client to send an extension event to another client.
The XGetDeviceMotionEvents function 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 XFreeDeviceMotionEvents function frees the array of motion information.
#endif /* _XI_H_ */