1. Input Extension OverviewThis document describes an extension to the X11 server. Thepurpose of this extension is to support the use ofadditional input devices beyond the pointer and keyboarddevices defined by the core X protocol. This first sectiongives an overview of the input extension. The followingsections correspond to chapters 9, 10, and 11, ‘‘Window andSession Manager Functions’’, ‘‘Events’’, and ‘‘EventHandling Functions’’ of the ‘‘Xlib - C Language Interface’’manual and describe how to use the input device extension.1.1. Design ApproachThe design approach of the extension is to define functionsand events analogous to the core functions and events. Thisallows extension input devices and events to be individuallydistinguishable from each other and from the core inputdevices and events. These functions and events make use ofa device identifier and support the reporting ofn-dimensional motion data as well as other data that is notcurrently reportable via the core input events.1.2. Core Input DevicesThe X server core protocol supports two input devices: apointer and a keyboard. The pointer device has two majorfunctions. First, it may be used to generate motioninformation that client programs can detect. Second, it mayalso be used to indicate the current location and focus ofthe X keyboard. To accomplish this, the server echoes acursor at the current position of the X pointer. Unless theX keyboard has been explicitly focused, this cursor alsoshows the current location and focus of the X keyboard.The X keyboard is used to generate input that clientprograms can detect.The X keyboard and X pointer are referred to in thisdocument as the core devices, and the input events theygenerate (KeyPress, KeyRelease, ButtonPress, ButtonRelease,and MotionNotify) are known as the core input events. Allother input devices are referred to as extension inputdevices, and the input events they generate are referred toas extension input events. NoteThis input extension does not change the behavioror functionality of the core input devices, coreevents, or core protocol requests, with theexception of the core grab requests. Theserequests may affect the synchronization of eventsfrom extension devices. See the explanation inthe section titled ‘‘Event Synchronization andCore Grabs.’’Selection of the physical devices to be initially used bythe server as the core devices is left implementationdependent. Functions are defined that allow client programsto change which physical devices are used as the coredevices.1.3. Extension Input DevicesThe input extension controls access to input devices otherthan the X keyboard and X pointer. It allows clientprograms to select input from these devices independentlyfrom 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) andcontain a device identifier so that events of the same typecoming from different input devices can be distinguished.Extension input events are not limited in size by the sizeof the server 32-byte wire events. Extension input eventsmay be constructed by the server sending as many wire-sizedevents as necessary to return the information required forthat event. The library event reformatting routines areresponsible for combining these into one or more clientXEvents.Any input device that generates key, button, or motion datamay be used as an extension input device. Extension inputdevices may have zero or more keys, zero or more buttons,and may report zero or more axes of motion. Motion may bereported as relative movements from a previous position oras an absolute position. All valuators reporting motioninformation for a given extension input device must reportthe same kind of motion information (absolute or relative).This extension is designed to accommodate new types of inputdevices that may be added in the future. The protocolrequests that refer to specific characteristics of inputdevices organize that information by input device classes.Server implementors may add new classes of input deviceswithout changing the protocol requests.All extension input devices are treated like the core Xkeyboard in determining their location and focus. Theserver does not track the location of these devices on anindividual basis and, therefore, does not echo a cursor toindicate their current location. Instead, their location isdetermined by the location of the core X pointer. Like thecore X keyboard, some may be explicitly focused. If they arenot explicitly focused, their focus is determined by thelocation of the core X pointer.1.3.1. Input Device ClassesSome of the input extension requests divide input devicesinto classes based on their functionality. This is intendedto allow new classes of input devices to be defined at alater time without changing the semantics of thesefunctions. The following input device classes are currentlydefined: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. Functionsthat support multiple input classes, such as theXListInputDevices function that lists all available inputdevices, organize the data they return by input class.Client programs that use these functions should not accessdata unless it matches a class defined at the time thoseclients were compiled. In this way, new classes can beadded without forcing existing clients that use thesefunctions to be recompiled.1.4. Using Extension Input DevicesA client that wishes to access an input device does sothrough the library functions defined in the followingsections. A typical sequence of requests that a clientwould make is as follows:• XListInputDevices − lists all of the available inputdevices. From the information returned by thisrequest, determine whether the desired input device isattached to the server. For a description of theXListInputDevices request, see the section entitled‘‘Listing Available Devices.’’• XOpenDevice − requests that the server open the devicefor access by this client. This request returns anXDevice structure that is used by most other inputextension requests to identify the specified device.For a description of the XOpenDevice request, see thesection entitled ‘‘Enabling and Disabling ExtensionDevices.’’• Determine the event types and event classes needed toselect the desired input extension events, and identifythem when they are received. This is done via macroswhose name corresponds to the desired event, forexample, DeviceKeyPress. For a description of thesemacros, see the section entitled ‘‘Selecting ExtensionDevice Events.’’• XSelectExtensionEvent − selects the desired events fromthe server. For a description of theXSelextExtensionEvent request, see the section entitled‘‘Selecting Extension Device Events.’’• XNextEvent − receives the next available event. Thisis the core XNextEvent function provided by thestandard X libarary.Other requests are defined to grab and focus extensiondevices, to change their key, button, or modifier mappings,to control the propagation of input extension events, to getmotion history from an extension device, and to send inputextension events to another client. These functions aredescribed in the following sections.2. Library Extension RequestsExtension input devices are accessed by client programsthrough the use of new protocol requests. The followingrequests are provided as extensions to Xlib. Constants andstructures referenced by these functions may be found in thefiles <X11/extensions/XI.h> and <X11/extensions/XInput.h>,which are attached to this document as Appendix A.The library will return NoSuchExtension if an extensionrequest is made to a server that does not support the inputextension.Input extension requests cannot be used to access the Xkeyboard and X pointer devices.2.1. Window Manager FunctionsThis section discusses the following X Input ExtensionWindow Manager topics:• Changing the core devices• Event synchronization and core grabs• Extension active grabs• Passively grabbing a key• Passively grabbing a button• Thawing a device• Controlling device focus• Controlling device feedback• Ringing a bell on an input device• Controlling device encoding• Controlling button mapping• Obtaining the state of a device2.1.1. Changing the Core DevicesThese functions are provided to change which physical deviceis used as the X pointer or X keyboard.NoteUsing these functions may change thecharacteristics of the core devices. The newpointer device may have a different number ofbuttons from the old one, or the new keyboarddevice may have a different number of keys orreport a different range of keycodes. Clientprograms may be running that depend on thosecharacteristics. For example, a client programcould allocate an array based on the number ofbuttons on the pointer device and then use thebutton numbers received in button events asindices into that array. Changing the coredevices could cause such client programs to behaveimproperly or to terminate abnormally if theyignore the ChangeDeviceNotify event generated bythese requests.These functions change the X keyboard or X pointer deviceand generate an XChangeDeviceNotify event and aMappingNotify event. The specified device becomes the new Xkeyboard or X pointer device. The location of the coredevice does not change as a result of this request.These requests fail and return AlreadyGrabbed if either thespecified device or the core device it would replace aregrabbed by some other client. They fail and returnGrabFrozen if either device is frozen by the active grab ofanother client.These requests fail with a BadDevice error if the specifieddevice is invalid, has not previously been opened viaXOpenDevice, or is not supported as a core device by theserver implementation.Once the device has successfully replaced one of the coredevices, it is treated as a core device until it is in turnreplaced by another ChangeDevice request or until the serverterminates. The termination of the client that changed thedevice will not cause it to change back. Attempts to usethe XCloseDevice request to close the new core device willfail with a BadDevice error.To change which physical device is used as the X keyboard,use the XChangeKeyboardDevice function. The specifieddevice must support input class Keys (as reported in theListInputDevices request) or the request will fail with aBadMatch error.__│ int XChangeKeyboardDevice(display, device)Display *display;XDevice *device;display Specifies the connection to the X server.device Specifies the desired device.│__ If no error occurs, XChangeKeyboardDevice returns Success.A ChangeDeviceNotify event with the request field set toNewKeyboard is sent to all clients selecting that event. AMappingNotify event with the request field set toMappingKeyboard is sent to all clients. The requesteddevice becomes the X keyboard, and the old keyboard becomesavailable as an extension input device. The focus state ofthe new keyboard is the same as the focus state of the old Xkeyboard.XChangeKeyboardDevice can generate AlreadyGrabbed,BadDevice, BadMatch, and GrabFrozen errors.To change which physical device is used as the X pointer,use the XChangePointerDevice function. The specified devicemust support input class Valuators (as reported in theXListInputDevices request) and report at least two axes ofmotion, or the request will fail with a BadMatch error. Ifthe specified device reports more than two axes, the twospecified in the xaxis and yaxis arguments will be used.Data from other valuators on the device will be ignored.If the specified device reports absolute positionalinformation, and the server implementation does not allowsuch a device to be used as the X pointer, the request willfail with a BadDevice error.__│ int XChangePointerDevice(display, device, xaxis, yaxis)Display *display;XDevice *device;int xaxis;int yaxis;display Specifies the connection to the X server.device Specifies the desired device.xaxis Specifies the zero-based index of the axis to beused as the x-axis of the pointer device.yaxis Specifies the zero-based index of the axis to beused as the y-axis of the pointer device.│__ If no error occurs, XChangePointerDevice returns Success. AChangeDeviceNotify event with the request field set toNewPointer is sent to all clients selecting that event. AMappingNotify event with the request field set toMappingPointer is sent to all clients. The requested devicebecomes the X pointer, and the old pointer becomes availableas an extension input device.XChangePointerDevice can generate AlreadyGrabbed, BadDevice,BadMatch, and GrabFrozen errors.2.1.2. Event Synchronization and Core GrabsImplementation of the input extension requires an extensionof the meaning of event synchronization for the core grabrequests. This is necessary in order to allow windowmanagers to freeze all input devices with a single request.The core grab requests require a pointer_mode andkeyboard_mode argument. The meaning of these modes ischanged by the input extension. For the XGrabPointer andXGrabButton requests, pointer_mode controls synchronizationof the pointer device, and keyboard_mode controls thesynchronization of all other input devices. For theXGrabKeyboard and XGrabKey requests, pointer_mode controlsthe synchronization of all input devices, except the Xkeyboard, while keyboard_mode controls the synchronizationof the keyboard. When using one of the core grab requests,the synchronization of extension devices is controlled bythe mode specified for the device not being grabbed.2.1.3. Extension Active GrabsActive grabs of extension devices are supported via theXGrabDevice function in the same way that core devices aregrabbed using the core XGrabKeyboard function, except thatan extension input device is passed as a function parameter.The XUngrabDevice function allows a previous active grab foran extension device to be released.Passive grabs of buttons and keys on extension devices aresupported via the XGrabDeviceButton and XGrabDeviceKeyfunctions. These passive grabs are released via theXUngrabDeviceKey and XUngrabDeviceButton functions.To grab an extension device, use the XGrabDevice function.The device must have previously been opened using theXOpenDevice function.__│ int XGrabDevice(display, device, grab_window, owner_events, event_count, event_list,this_device_mode, other_device_mode, time)Display *display;XDevice *device;Window grab_window;Bool owner_events;int event_count;XEventClass *event_list;int this_device_mode;int other_device_mode;Time time;display Specifies the connection to the X server.device Specifies the desired device.grab_windowSpecifies the ID of a window associated with thedevice specified above.owner_eventsSpecifies a boolean value of either True or False.event_countSpecifies the number of elements in the event_listarray.event_listSpecifies a pointer to a list of event classesthat indicate which events the client wishes toreceive. These event classes must have beenobtained using the device being grabbed.this_device_modeControls further processing of events from thisdevice. You can pass one of these constants:GrabModeSync or GrabModeAsync.other_device_modeControls further processing of events from allother devices. You can pass one of theseconstants: GrabModeSync or GrabModeAsync.time Specifies the time. This may be either atimestamp expressed in milliseconds orCurrentTime.│__ XGrabDevice actively grabs an extension input device andgenerates DeviceFocusIn and DeviceFocusOut events. Furtherinput events from this device are reported only to thegrabbing client. This function overrides any previousactive grab by this client for this device.The event_list parameter is a pointer to a list of eventclasses. This list indicates which events the client wishesto receive while the grab is active. If owner_events isFalse, input events from this device are reported withrespect to grab_window and are reported only if specified inevent_list. If owner_events is True, then if a generatedevent would normally be reported to this client, it isreported normally. Otherwise, the event is reported withrespect to the grab_window and is only reported if specifiedin event_list.The this_device_mode argument controls the furtherprocessing of events from this device, and theother_device_mode argument controls the further processingof input events from all other devices.• If the this_device_mode argument is GrabModeAsync,device event processing continues normally; if thedevice is currently frozen by this client, thenprocessing of device events is resumed. If thethis_device_mode argument is GrabModeSync, the stateof the grabbed device (as seen by client applications)appears to freeze, and no further device events aregenerated by the server until the grabbing clientissues a releasing XAllowDeviceEvents call or until thedevice grab is released. Actual device input eventsare not lost while the device is frozen; they aresimply queued for later processing.• If the other_device_mode is GrabModeAsync, eventprocessing from other input devices is unaffected byactivation of the grab. If other_device_mode isGrabModeSync, the state of all devices except thegrabbed device (as seen by client applications) appearsto freeze, and no further events are generated by theserver until the grabbing client issues a releasingXAllowEvents or XAllowDeviceEvents call or until thedevice grab is released. Actual events are not lostwhile the other devices are frozen; they are simplyqueued for later processing.XGrabDevice fails on the following conditions:• If the device is actively grabbed by some other client,it returns AlreadyGrabbed.• If grab_window is not viewable, it returnsGrabNotViewable.• If the specified time is earlier than thelast-grab-time for the specified device or later thanthe current X server time, it returns GrabInvalidTime.Otherwise, the last-grab-time for the specified deviceis set to the specified time and CurrentTime isreplaced by the current X server time.• If the device is frozen by an active grab of anotherclient, it returns GrabFrozen.If a grabbed device is closed by a client while an activegrab by that client is in effect, that active grab will bereleased. Any passive grabs established by that client willbe released. If the device is frozen only by an active grabof the requesting client, it is thawed.XGrabDevice can generate BadClass, BadDevice, BadValue, andBadWindow errors.To release a grab of an extension device, use theXUngrabDevice function.__│ int XUngrabDevice(display, device, time)Display *display;XDevice *device;Time time;display Specifies the connection to the X server.device Specifies the desired device.time Specifies the time. This may be either atimestamp expressed in milliseconds, orCurrentTime.│__ XUngrabDevice allows a client to release an extension inputdevice and any queued events if this client has it grabbedfrom either XGrabDevice or XGrabDeviceKey. If any otherdevices are frozen by the grab, XUngrabDevice thaws them.This function does not release the device and any queuedevents if the specified time is earlier than thelast-device-grab time or is later than the current X servertime. It also generates DeviceFocusIn and DeviceFocusOutevents. The X server automatically performs anXUngrabDevice if the event window for an active device grabbecomes not viewable or if the client terminates withoutreleasing the grab.XUngrabDevice can generate BadDevice errors.2.1.4. Passively Grabbing a KeyTo passively grab a single key on an extension device, useXGrabDeviceKey. That device must have previously beenopened using the XOpenDevice function, or the request willfail with a BadDevice error. If the specified device doesnot support input class Keys, the request will fail with aBadMatch error.__│ int XGrabDeviceKey(display, device, keycode, modifiers, modifier_device, grab_window,owner_events, event_count, event_list, this_device_mode, other_device_mode)Display *display;XDevice *device;int keycode;unsigned int modifiers;XDevice *modifier_device;Window grab_window;Bool owner_events;int event_count;XEventClass *event_list;int this_device_mode;int other_device_mode;display Specifies the connection to the X server.device Specifies the desired device.keycode Specifies the keycode of the key that is to begrabbed. You can pass either the keycode orAnyKey.modifiers Specifies the set of keymasks. This mask is thebitwise inclusive OR of these keymask bits:ShiftMask, LockMask, ControlMask, Mod1Mask,Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.You can also pass AnyModifier, which is equivalentto issuing the grab key request for all possiblemodifier combinations (including the combinationof no modifiers).modifier_deviceSpecifies the device whose modifiers are to beused. If NULL is specified, the core X keyboardis used as the modifier_device.grab_windowSpecifies the ID of a window associated with thedevice specified above.owner_eventsSpecifies a boolean value of either True or False.event_countSpecifies the number of elements in the event_listarray.event_listSpecifies a pointer to a list of event classesthat indicate which events the client wishes toreceive.this_device_modeControls further processing of events from thisdevice. You can pass one of these constants:GrabModeSync or GrabModeAsync.other_device_modeControls further processing of events from allother devices. You can pass one of theseconstants: GrabModeSync or GrabModeAsync.│__ XGrabDeviceKey is analogous to the core XGrabKey function.It creates an explicit passive grab for a key on anextension device. The XGrabDeviceKey function establishes apassive 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 logicallypressed when the specified modifier keys logically aredown on the specified modifier device (and no otherkeys 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 ofthe focus window and contains the pointer,• AND a passive grab on the same device and keycombination does not exist on any ancestor of the grabwindow,• THEN the device is actively grabbed, as forXGrabDevice, the last-device-grab time is set to thetime at which the key was pressed (as transmitted int