X Input Device Extension Library

X Consortium Standard

X Version 11, Release 6.4

Mark Patrick Ardent Computer

George Sachs Hewlett-Packard

Copyright © 1989, 1990, 1991 by Hewlett-Packard Company, 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 (c) 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 X Consortium, Inc.

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 inthe DeviceKeyPress event), and the DeviceKeyPress eventis reported.The interpretation of the remaining arguments is as forXGrabDevice. The active grab is terminated automaticallywhen the logical state of the device has the specified keyreleased (independent of the logical state of the modifierkeys).Note that the logical state of a device (as seen by means ofthe X protocol) may lag the physical state if device eventprocessing is frozen.A modifier of AnyModifier is equivalent to issuing therequest for all possible modifier combinations (includingthe combination of no modifiers). It is not required thatall modifiers specified have currently assigned keycodes. Akey of AnyKey is equivalent to issuing the request for allpossible keycodes. Otherwise, the key must be in the rangespecified by min_keycode and max_keycode in the informationreturned by the XListInputDevices function. If it is notwithin that range, XGrabDeviceKey generates a BadValueerror.XGrabDeviceKey generates a BadAccess error if some otherclient has issued a XGrabDeviceKey with the same device andkey combination on the same window. When using AnyModifieror AnyKey, the request fails completely and the X servergenerates a BadAccess error, and no grabs are established ifthere is a conflicting grab for any combination.XGrabDeviceKey returns Success upon successful completion ofthe request.XGrabDeviceKey can generate BadAccess, BadClass, BadDevice,BadMatch, BadValue, and BadWindow errors.To release a passive grab of a single key on an extensiondevice, use XUngrabDeviceKey.__│ int XUngrabDeviceKey(display, device, keycode, modifiers, modifier_device, ungrab_window)Display *display;XDevice *device;int keycode;unsigned int modifiers;XDevice *modifier_device;Window ungrab_window;display Specifies the connection to the X server.device Specifies the desired device.keycode Specifies the keycode of the key that is to beungrabbed. 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 ungrab key request for all possiblemodifier combinations (including the combinationof no modifiers).modifier_deviceSpecifies the device whose modifiers are tobe used. If NULL is specified, the core Xkeyboard is used as the modifier_device.ungrab_window Specifies the ID of a window associated withthe device specified above.│__ XUngrabDeviceKey is analogous to the core XUngrabKeyfunction. It releases an explicit passive grab for a key onan extension input device.XUngrabDeviceKey can generate BadAlloc, BadDevice, BadMatch,BadValue, and BadWindow errors.2.1.5. Passively Grabbing a ButtonTo establish a passive grab for a single button on anextension device, use XGrabDeviceButton. The specifieddevice must have previously been opened using theXOpenDevice function, or the request will fail with aBadDevice error. If the specified device does not supportinput class Buttons, the request will fail with a BadMatcherror.__│ int XGrabDeviceButton(display, device, button, modifiers, modifier_device , grab_window,owner_events, event_count, event_list, this_device_mode, other_device_mode)Display *display;XDevice *device;unsigned int button;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.button Specifies the code of the button that is to begrabbed. You can pass either the button orAnyButton.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 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 list of event classes that indicateswhich device events are to be reported to theclient.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.│__ XGrabDeviceButton is analogous to the core XGrabButtonfunction. It creates an explicit passive grab for a buttonon an extension input device. Because the server does nottrack extension devices, no cursor is specified with thisrequest. For the same reason, there is no confine_toparameter. The device must have previously been openedusing the XOpenDevice function.The XGrabDeviceButton function establishes a passive grab ona device. Consequently, in the future,• IF the device is not grabbed and the specified buttonis logically pressed when the specified modifier keyslogically are down (and no other buttons or modifierkeys 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 button/keycombination does not exist on any ancestor of the grabwindow,• THEN the device is actively grabbed, as forXGrabDevice, the last-grab time is set to the time atwhich the button was pressed (as transmitted in theDeviceButtonPress event), and the DeviceButtonPressevent is reported.The interpretation of the remaining arguments is as forXGrabDevice. The active grab is terminated automaticallywhen logical state of the device has all buttons released(independent of the logical state of the modifier keys).Note that the logical state of a device (as seen by means ofthe X protocol) may lag the physical state if device eventprocessing is frozen.A modifier of AnyModifier is equivalent to issuing therequest for all possible modifier combinations (includingthe combination of no modifiers). It is not required thatall modifiers specified have currently assigned keycodes. Abutton of AnyButton is equivalent to issuing the request forall possible buttons. Otherwise, it is not required thatthe specified button be assigned to a physical button.XGrabDeviceButton generates a BadAccess error if some otherclient has issued a XGrabDeviceButton with the same deviceand button combination on the same window. When usingAnyModifier or AnyButton, the request fails completely andthe X server generates a BadAccess error and no grabs areestablished if there is a conflicting grab for anycombination.XGrabDeviceButton can generate BadAccess, BadClass,BadDevice, BadMatch, BadValue, and BadWindow errors.To release a passive grab of a button on an extensiondevice, use XUngrabDeviceButton.__│ int XUngrabDeviceButton(display, device, button, modifiers, modifier_device, ungrab_window)Display *display;XDevice *device;unsigned int button;unsigned int modifiers;XDevice *modifier_device;Window ungrab_window;display Specifies the connection to the X server.device Specifies the desired device.button Specifies the code of the button that is to beungrabbed. You can pass either a button orAnyButton.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 ungrab 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.ungrab_windowSpecifies the ID of a window associated with thedevice specified above.│__ XUngrabDeviceButton is analogous to the core XUngrabButtonfunction. It releases an explicit passive grab for a buttonon an extension device. That device must have previouslybeen opened using the XOpenDevice function, or a BadDeviceerror will result.A modifier of AnyModifier is equivalent to issuing therequest for all possible modifier combinations (includingthe combination of no modifiers).XUngrabDeviceButton can generate BadAlloc, BadDevice,BadMatch, BadValue, and BadWindow errors.2.1.6. Thawing a DeviceTo allow further events to be processed when a device hasbeen frozen, use XAllowDeviceEvents.__│ int XAllowDeviceEvents(display, device, event_mode, time)Display *display;XDevice *device;int event_mode;Time time;display Specifies the connection to the X server.device Specifies the desired device.event_modeSpecifies the event mode. You can pass one ofthese constants: AsyncThisDevice, SyncThisDevice,AsyncOtherDevices, ReplayThisDevice, AsyncAll, orSyncAll.time Specifies the time. This may be either atimestamp expressed in milliseconds, orCurrentTime.│__ XAllowDeviceEvents releases some queued events if the clienthas caused a device to freeze. It has no effect if thespecified time is earlier than the last-grab time of themost recent active grab for the client and device, or if thespecified time is later than the current X server time. Thefollowing describes the processing that occurs depending onwhat constant you pass to the event_mode argument:• AsyncThisDeviceIf the specified device is frozen by the client, eventprocessing for that continues as usual. If the deviceis frozen multiple times by the client on behalf ofmultiple separate grabs, AsyncThisDevice thaws for all.AsyncThisDevice has no effect if the specified deviceis not frozen by the client, but the device need not begrabbed by the client.• SyncThisDeviceIf the specified device is frozen and actively grabbedby the client, event processing for that devicecontinues normally until the next key or button eventis reported to the client. At this time, the specifieddevice again appears to freeze. However, if thereported event causes the grab to be released, thespecified device does not freeze. SyncThisDevice hasno effect if the specified device is not frozen by theclient or is not grabbed by the client.• ReplayThisDeviceIf the specified device is actively grabbed by theclient and is frozen as the result of an event havingbeen sent to the client (either from the activation ofa GrabDeviceButton or from a previous AllowDeviceEventswith mode SyncThisDevice, but not from a Grab), thegrab is released and that event is completelyreprocessed. This time, however, the request ignoresany passive grabs at or above (toward the root) thegrab-window of the grab just released. The request hasno effect if the specified device is not grabbed by theclient or if it is not frozen as the result of anevent.• AsyncOtherDevicesIf the remaining devices are frozen by the client,event processing for them continues as usual. If theother devices are frozen multiple times by the clienton behalf of multiple separate grabs, AsyncOtherDevices‘‘thaws’’ for all. AsyncOtherDevices has no effect ifthe devices are not frozen by the client, but thosedevices need not be grabbed by the client.• SyncAllIf all devices are frozen by the client, eventprocessing (for all devices) continues normally untilthe next button or key event is reported to the clientfor a grabbed device, at which time the devices againappear to freeze. However, if the reported eventcauses the grab to be released, then the devices do notfreeze (but if any device is still grabbed, then asubsequent event for it will still cause all devices tofreeze). SyncAll has no effect unless all devices arefrozen by the client. If any device is frozen twice bythe client on behalf of two separate grabs, SyncAll"thaws" for both (but a subsequent freeze for SyncAllwill freeze each device only once).• AsyncAllIf all devices are frozen by the client, eventprocessing (for all devices) continues normally. Ifany device is frozen multiple times by the client onbehalf of multiple separate grabs, AsyncAll ‘‘thaws’’for all. If any device is frozen twice by the clienton behalf of two separate grabs, AsyncAll ‘‘thaws’’ forboth. AsyncAll has no effect unless all devices arefrozen by the client.AsyncThisDevice, SyncThisDevice, and ReplayThisDevice haveno effect on the processing of events from the remainingdevices. AsyncOtherDevices has no effect on the processingof events from the specified device. When the event_mode isSyncAll or AsyncAll, the device parameter is ignored.It is possible for several grabs of different devices (bythe same or different clients) to be active simultaneously.If a device is frozen on behalf of any grab, no eventprocessing is performed for the device. It is possible fora single device to be frozen because of several grabs. Inthis case, the freeze must be released on behalf of eachgrab before events can again be processed.XAllowDeviceEvents can generate BadDevice and BadValueerrors.2.1.7. Controlling Device FocusThe current focus window for an extension input device canbe determined using the XGetDeviceFocus function. Extensiondevices are focused using the XSetDeviceFocus function inthe same way that the keyboard is focused using the coreXSetInputFocus function, except that a device ID is passedas a function parameter. One additional focus state,FollowKeyboard, is provided for extension devices.To get the current focus state, revert state, and focus timeof an extension device, use XGetDeviceFocus.__│ int XGetDeviceFocus(display, device, focus_return, revert_to_return, focus_time_return)Display *display;XDevice *device;Window *focus_return;int *revert_to_return;Time *focus_time_return;display Specifies the connection to the X server.device Specifies the desired device.focus_returnSpecifies the address of a variable into which theserver can return the ID of the window thatcontains the device focus or one of the constantsNone, PointerRoot, or FollowKeyboard.revert_to_returnSpecifies the address of a variable into which theserver can return the current revert_to status forthe device.focus_time_returnSpecifies the address of a variable into which theserver can return the focus time last set for thedevice.│__ XGetDeviceFocus returns the focus state, the revert-tostate, and the last-focus-time for an extension inputdevice.XGetDeviceFocus can generate BadDevice and BadMatch errors.To set the focus of an extension device, useXSetDeviceFocus.__│ int XSetDeviceFocus(display, device, focus, revert_to, time)Display *display;XDevice *device;Window focus;int revert_to;Time time;display Specifies the connection to the X server.device Specifies the desired device.focus Specifies the ID of the window to which thedevice’s focus should be set. This may be awindow ID, or PointerRoot, FollowKeyboard, orNone.revert_to Specifies to which window the focus of the deviceshould revert if the focus window becomes notviewable. One of the following constants may bepassed: RevertToParent, RevertToPointerRoot,RevertToNone, or RevertToFollowKeyboard.time Specifies the time. You can pass either atimestamp, expressed in milliseconds, orCurrentTime.│__ XSetDeviceFocus changes the focus for an extension inputdevice and the last-focus-change-time. It has no effect ifthe specified time is earlier than thelast-focus-change-time or is later than the current X servertime. Otherwise, the last-focus-change-time is set to thespecified time. This function causes the X server togenerate DeviceFocusIn and DeviceFocusOut events.The action taken by the server when this function isrequested depends on the value of the focus argument:• If the focus argument is None, all input events fromthis device will be discarded until a new focus windowis set. In this case, the revert_to argument isignored.• If the focus argument is a window ID, it becomes thefocus window of the device. If an input event from thedevice would normally be reported to this window or toone of its inferiors, the event is reported normally.Otherwise, the event is reported relative to the focuswindow.• If the focus argument is PointerRoot, the focus windowis dynamically taken to be the root window of whateverscreen the pointer is on at each input event. In thiscase, the revert_to argument is ignored.• If the focus argument is FollowKeyboard, the focuswindow is dynamically taken to be the same as the focusof the X keyboard at each input event.The specified focus window must be viewable at the timeXSetDeviceFocus is called. Otherwise, it generates aBadMatch error. If the focus window later becomes notviewable, the X server evaluates the revert_to argument todetermine the new focus window.• If the revert_to argument is RevertToParent, the focusreverts to the parent (or the closest viewableancestor), and the new revert_to value is taken to beRevertToNone.• If the revert_to argument is RevertToPointerRoot,RevertToFollowKeyboard, or RevertToNone, the focusreverts to that value.When the focus reverts, the X server generates DeviceFocusInand DeviceFocusOut events, but the last-focus-change time isnot affected.XSetDeviceFocus can generate BadDevice, BadMatch, BadValue,and BadWindow errors.2.1.8. Controlling Device FeedbackTo determine the current feedback settings of an extensioninput device, use XGetFeedbackControl.__│ XFeedbackState * XGetFeedbackControl(display, device, num_feedbacks_return)Display *display;XDevice *device;int *num_feedbacks_return;display Specifies the connection to the X server.device Specifies the desired device.num_feedbacks_returnReturns the number of feedbacks supported by thedevice.│__ XGetFeedbackControl returns a list of FeedbackStatestructures that describe the feedbacks supported by thespecified device. There is an XFeedbackState structure foreach class of feedback. These are of variable length, butthe first three members are common to all.__│ typedef struct {XID class;int length;XID id;} XFeedbackState;│__ The common members are as follows:• The class member identifies the class of feedback. Itmay be compared to constants defined in the file<X11/extensions/XI.h>. Currently defined feedbackconstants include: KbdFeedbackClass, PtrFeedbackClass,StringFeedbackClass, IntegerFeedbackClass,LedFeedbackClass, and BellFeedbackClass.• The length member specifies the length of theFeedbackState structure and can be used by clients totraverse the list.• The id member uniquely identifies a feedback for agiven device and class. This allows a device tosupport more than one feedback of the same class.Other feedbacks of other classes or devices may havethe same ID.Those feedbacks equivalent to those supported by the corekeyboard are reported in class KbdFeedback using theXKbdFeedbackState structure, which is defined as follows:__│ typedef struct {XID class;int length;XID id;int click;int percent;int pitch;int duration;int led_mask;int global_auto_repeat;char auto_repeats[32];} XKbdFeedbackState;│__ The additional members of the XKbdFeedbackState structurereport the current state of the feedback:• The click member specifies the key-click volume and hasa value in the range 0 (off) to 100 (loud).• The percent member specifies the bell volume and has avalue in the range 0 (off) to 100 (loud).• The pitch member specifies the bell pitch in Hz. Therange of the value is implementation-dependent.• The duration member specifies the duration inmilliseconds of the bell.• The led_mask member is a bit mask that describes thecurrent state of up to 32 LEDs. A value of 1 in a bitindicates that the corresponding LED is on.• The global_auto_repeat member has a value ofAutoRepeatModeOn or AutoRepeatModeOff.• The auto_repeats member is a bit vector. Each bit setto 1 indicates that auto-repeat is enabled for thecorresponding key. The vector is represented as 32bytes. Byte N (from 0) contains the bits for keys 8Nto 8N + 7, with the least significant bit in the byterepresenting key 8N.Those feedbacks equivalent to those supported by the corepointer are reported in class PtrFeedback using theXPtrFeedbackState structure, which is defined as follows:__│ typedef struct {XID class;int length;XID id;int accelNum;int accelDenom;int threshold;} XPtrFeedbackState;│__ The additional members of the XPtrFeedbackState structurereport the current state of the feedback:• The accelNum member returns the numerator for theacceleration multiplier.• The accelDenom member returns the denominator for theacceleration multiplier.• The accelDenom member returns the threshold for theacceleration.Integer feedbacks are those capable of displaying integernumbers and reported via the XIntegerFeedbackStatestructure. The minimum and maximum values that they candisplay are reported.__│ typedef struct {XID class;int length;XID id;int resolution;int minVal;int maxVal;} XIntegerFeedbackState;│__ The additional members of the XIntegerFeedbackStatestructure report the capabilities of the feedback:• The resolution member specifies the number of digitsthat the feedback can display.• The minVal member specifies the minimum value that thefeedback can display.• The maxVal specifies the maximum value that thefeedback can display.String feedbacks are those that can display characterinformation and are reported via the XStringFeedbackStatestructure. Clients set these feedbacks by passing a list ofKeySyms to be displayed. The XGetFeedbackControl functionreturns the set of key symbols that the feedback candisplay, as well as the maximum number of symbols that canbe displayed. The XStringFeedbackState structure is definedas follows:__│ typedef struct {XID class;int length;XID id;int max_symbols;int num_syms_supported;KeySym *syms_supported;} XStringFeedbackState;│__ The additional members of the XStringFeedbackState structurereport the capabilities of the feedback:• The max_symbols member specifies the maximum number ofsymbols that can be displayed.• The syms_supported member is a pointer to the list ofsupported symbols.• The num_syms_supported member specifies the length ofthe list of supported symbols.Bell feedbacks are those that can generate a sound and arereported via the XBellFeedbackState structure. Someimplementations may support a bell as part of a KbdFeedbackfeedback. Class BellFeedback is provided forimplementations that do not choose to do so and for devicesthat support multiple feedbacks that can produce sound. Themeaning of the members is the same as that of thecorresponding fields in the XKbdFeedbackState structure.__│ typedef struct {XID class;int length;XID id;int percent;int pitch;int duration;} XBellFeedbackState;│__ Led feedbacks are those that can generate a light and arereported via the XLedFeedbackState structure. Up to 32lights per feedback are supported. Each bit in led_maskcorresponds to one supported light, and the correspondingbit in led_values indicates whether that light is currentlyon (1) or off (0). Some implementations may support leds aspart of a KbdFeedback feedback. Class LedFeedback isprovided for implementations that do not choose to do so andfor devices that support multiple led feedbacks.__│ typedef struct {XID class;int length;XID id;Mask led_values;Mask led_mask;} XLedFeedbackState;│__ XGetFeedbackControl can generate BadDevice and BadMatcherrors.To free the information returned by the XGetFeedbackControlfunction, use XFreeFeedbackList.__│ void XFreeFeedbackList(list)XFeedbackState *list;list Specifies the pointer to the XFeedbackStatestructure returned by a previous call toXGetFeedbackControl.│__ XFreeFeedbackList frees the list of feedback controlinformation.To change the settings of a feedback on an extension device,use XChangeFeedbackControl. This function modifies thecurrent control values of the specified feedback usinginformation passed in the appropriate XFeedbackControlstructure for the feedback. Which values are modifieddepends on the valuemask passed.__│ int XChangeFeedbackControl(display, device, valuemask, value)Display *display;XDevice *device;unsigned long valuemask;XFeedbackControl *value;display Specifies the connection to the X server.device Specifies the desired device.valuemask Specifies one value for each bit in the mask(least to most significant bit). The values areassociated with the feedbacks for the specifieddevice.value Specifies a pointer to the XFeedbackControlstructure.│__ XChangeFeedbackControl controls the device characteristicsdescribed by the XFeedbackControl structure. There is anXFeedbackControl structure for each class of feedback.These are of variable length, but the first three membersare common to all and are as follows:__│ typedef struct {XID class;int length;XID id;} XFeedbackControl;│__ Feedback class KbdFeedback controls feedbacks equivalent tothose provided by the core keyboard using theKbdFeedbackControl structure, which is defined as follows:.__│ typedef struct {XID class;int length;XID id;int click;int percent;int pitch;int duration;int led_mask;int led_value;int key;int auto_repeat_mode;} XKbdFeedbackControl;│__ This class controls the device characteristics described bythe XKbdFeedbackControl structure. These include thekey_click_percent, global_auto_repeat, and individual keyauto-repeat. Valid modes are AutoRepeatModeOn,AutoRepeatModeOff, and AutoRepeatModeDefault.Valid masks are as follows:__││__ Feedback class PtrFeedback controls feedbacks equivalent tothose provided by the core pointer using thePtrFeedbackControl structure, which is defined as follows:__│ typedef struct {XID class;int length;XID id;int accelNum;int accelDenom;int threshold;} XPtrFeedbackControl;│__ Which values are modified depends on the valuemask passed.Valid masks are as follows:__││__ The acceleration, expressed as a fraction, is a multiplierfor movement. For example, specifying 3/1 means that thedevice moves three times as fast as normal. The fractionmay be rounded arbitrarily by the X server. Accelerationtakes effect only if the device moves more than thresholdpixels at once and applies only to the amount beyond thevalue in the threshold argument. Setting a value to -1restores the default. The values of the accelNumerator andthreshold fields must be nonzero for the pointer values tobe set. Otherwise, the parameters will be unchanged.Negative values generate a BadValue error, as does a zerovalue for the accelDenominator field.This request fails with a BadMatch error if the specifieddevice is not currently reporting relative motion. If adevice that is capable of reporting both relative andabsolute motion has its mode changed from Relative toAbsolute by an XSetDeviceMode request, valuator controlvalues will be ignored by the server while the device is inthat mode.Feedback class IntegerFeedback controls integer feedbacksdisplayed on input devices and are reported via theIntegerFeedbackControl structure, which is defined asfollows:__│ typedef struct {XID class;int length;XID id;int int_to_display;} XIntegerFeedbackControl;│__ Valid masks are as follows:__││__ Feedback class StringFeedback controls string feedbacksdisplayed on input devices and reported via theStringFeedbackControl structure, which is defined asfollows:__│ typedef struct {XID class;int length;XID id;int num_keysyms;KeySym *syms_to_display;} XStringFeedbackControl;│__ Valid masks are as follows:__││__ Feedback class BellFeedback controls a bell on an inputdevice and is reported via the BellFeedbackControlstructure, which is defined as follows:__│ typedef struct {XID class;int length;XID id;int percent;int pitch;int duration;} XBellFeedbackControl;│__ Valid masks are as follows:__││__ Feedback class LedFeedback controls lights on an inputdevice and are reported via the LedFeedbackControlstructure, which is defined as follows:__│ typedef struct {XID class;int length;XID id;int led_mask;int led_values;} XLedFeedbackControl;│__ Valid masks are as follows:__││__ XChangeFeedbackControl can generate BadDevice, BadFeedBack,BadMatch, and BadValue errors.2.1.9. Ringing a Bell on an Input DeviceTo ring a bell on an extension input device, useXDeviceBell.__│ int XDeviceBell(display, device, feedbackclass, feedbackid, percent)Display *display;XDevice *device;XID feedbackclass, feedbackid;int percent;display Specifies the connection to the X server.device Specifies the desired device.feedbackclassSpecifies the feedbackclass. Valid values areKbdFeedbackClass and BellFeedbackClass.feedbackidSpecifies the ID of the feedback that has thebell.percent Specifies the volume in the range -100 (quiet) to100 percent (loud).│__ XDeviceBell is analogous to the core XBell function. Itrings the specified bell on the specified input devicefeedback, using the specified volume. The specified volumeis relative to the base volume for the feedback. If thevalue for the percent argument is not in the range -100 to100 inclusive, a BadValue error results. The volume atwhich the bell rings when the percent argument isnonnegative is:base - [(base * percent) / 100] + percentThe volume at which the bell rings when the percent argumentis negative is:base + [(base * percent) / 100]To change the base volume of the bell, useXChangeFeedbackControl.XDeviceBell can generate BadDevice and BadValue errors.2.1.10. Controlling Device EncodingTo get the key mapping of an extension device that supportsinput class Keys, use XGetDeviceKeyMapping.__│ KeySym * XGetDeviceKeyMapping(display, device, first_keycode_wanted, keycode_count,keysyms_per_keycode_return)Display *display;XDevice *device;KeyCode first_keycode_wanted;int keycode_count;int *keysyms_per_keycode_return;display Specifies the connection to the X server.device Specifies the desired device.first_keycode_wantedSpecifies the first keycode that is to bereturned.keycode_countSpecifies the number of keycodes that are to bereturned.keysyms_per_keycode_returnReturns the number of keysyms per keycode.│__ XGetDeviceKeyMapping is analogous to the coreXGetKeyboardMapping function. It returns the symbols forthe specified number of keycodes for the specified extensiondevice.XGetDeviceKeyMapping returns the symbols for the specifiednumber of keycodes for the specified extension device,starting with the specified keycode. Thefirst_keycode_wanted must be greater than or equal tomin-keycode as returned by the XListInputDevices request(else a BadValue error results). The following value:first_keycode_wanted + keycode_count − 1must be less than or equal to max-keycode as returned by theXListInputDevices request (else a BadValue error results).The number of elements in the keysyms list is as follows:keycode_count * keysyms_per_keycode_returnAnd KEYSYM number N (counting from zero) for keycode K hasan index (counting from zero), in keysyms, of the following:(K − first_keycode_wanted) * keysyms_per_keycode_return + NThe keysyms_per_keycode_return value is chosen arbitrarilyby the server to be large enough to report all requestedsymbols. A special KEYSYM value of NoSymbol is used to fillin unused elements for individual keycodes.To free the data returned by this function, use XFree.If the specified device has not first been opened by thisclient via XOpenDevice, this request will fail with aBadDevice error. If that device does not support inputclass Keys, this request will fail with a BadMatch error.XGetDeviceKeyMapping can generate BadDevice, BadMatch, andBadValue errors.To change the keyboard mapping of an extension device thatsupports input class Keys, use XChangeDeviceKeyMapping.__│ intXChangeDeviceKeyMapping(display, device, first_keycode, keysyms_per_keycode, keysyms,num_codes)Display *display;XDevice *device;int first_keycode;int keysyms_per_keycode;KeySym *keysyms;int num_codes;display Specifies the connection to the X server.device Specifies the desired device.first_keycodeSpecifies the first keycode that is to be changed.keysyms_per_keycodeSpecifies the keysyms that are to be used.keysyms Specifies a pointer to an array of keysyms.num_codes Specifies the number of keycodes that are to bechanged.│__ XChangeDeviceKeyMapping is analogous to the coreXChangeKeyboardMapping function. It defines the symbols forthe specified number of keycodes for the specified extensionkeyboard device.If the specified device has not first been opened by thisclient via XOpenDevice, this request will fail with aBadDevice error. If the specified device does not supportinput class Keys, this request will fail with a BadMatcherror.The number of elements in the keysyms list must be amultiple of keysyms_per_keycode. Otherwise,XChangeDeviceKeyMapping generates a BadLength error. Thespecified first_keycode must be greater than or equal to themin_keycode value returned by the ListInputDevices request,or this request will fail with a BadValue error. Inaddition, if the following expression is not less than themax_keycode value returned by the ListInputDevices request,the request will fail with a BadValue error:first_keycode + (num_codes / keysyms_per_keycode) - 1XChangeDeviceKeyMapping can generate BadAlloc, BadDevice,BadMatch, and BadValue errors.To obtain the keycodes that are used as modifiers on anextension device that supports input class Keys, useXGetDeviceModifierMapping.__│ XModifierKeymap * XGetDeviceModifierMapping(display, device)Display *display;XDevice *device;display Specifies the connection to the X server.device Specifies the desired device.│__ XGetDeviceModifierMapping is analogous to the coreXGetModifierMapping function. The XGetDeviceModifierMappingfunction returns a newly created XModifierKeymap structurethat contains the keys being used as modifiers for thespecified device. The structure should be freed after usewith XFreeModifierMapping. If only zero values appear inthe set for any modifier, that modifier is disabled.XGetDeviceModifierMapping can generate BadDevice andBadMatch errors.To set which keycodes are to be used as modifiers for anextension device, use XSetDeviceModifierMapping.__│ int XSetDeviceModifierMapping(display, device, modmap)Display *display;XDevice *device;XModifierKeymap *modmap;display Specifies the connection to the X server.device Specifies the desired device.modmap Specifies a pointer to the XModifierKeymapstructure.│__ XSetDeviceModifierMapping is analogous to the coreXSetModifierMapping function. The XSetDeviceModifierMappingfunction specifies the keycodes of the keys, if any, thatare to be used as modifiers. A zero value means that no keyshould be used. No two arguments can have the same nonzerokeycode value. Otherwise, XSetDeviceModifierMappinggenerates a BadValue error. There are eight modifiers, andthe modifiermap member of the XModifierKeymap structurecontains eight sets of max_keypermod keycodes, one for eachmodifier in the order Shift, Lock, Control, Mod1, Mod2,Mod3, Mod4, and Mod5. Only nonzero keycodes have meaning ineach set, and zero keycodes are ignored. In addition, allof the nonzero keycodes must be in the range specified bymin_keycode and max_keycode reported by theXListInputDevices function. Otherwise, XSetModifierMappinggenerates a BadValue error. No keycode may appear twice inthe entire map. Otherwise, it generates a BadValue error.A X server can impose restrictions on how modifiers can bechanged, for example, if certain keys do not generate uptransitions in hardware or if multiple modifier keys are notsupported. If some such restriction is violated, the statusreply is MappingFailed, and none of the modifiers arechanged. If the new keycodes specified for a modifierdiffer from those currently defined and any (current or new)keys for that modifier are in the logically down state, thestatus reply is MappingBusy, and none of the modifiers arechanged. XSetModifierMapping generates aDeviceMappingNotify event on a MappingSuccess status.XSetDeviceModifierMapping can generate BadAlloc, BadDevice,BadMatch, and BadValue errors.2.1.11. Controlling Button MappingTo set the mapping of the buttons on an extension device,use XSetDeviceButtonMapping.__│ int XSetDeviceButtonMapping(display, device, map, nmap)Display *display;XDevice *device;unsigned char map[];int nmap;display Specifies the connection to the X server.device Specifies the desired device.map Specifies the mapping list.nmap Specifies the number of items in the mapping list.│__ XSetDeviceButtonMapping sets the mapping of the buttons onan extension device. If it succeeds, the X server generatesa DeviceMappingNotify event, and XSetDeviceButtonMappingreturns MappingSuccess. Elements of the list are indexedstarting from one. The length of the list must be the sameas XGetDeviceButtonMapping would return, or a BadValue errorresults. The index is a button number, and the element ofthe list defines the effective number. A zero elementdisables a button, and elements are not restricted in valueby the number of physical buttons. However, no two elementscan have the same nonzero value, or a BadValue errorresults. If any of the buttons to be altered are logicallyin the down state, XSetDeviceButtonMapping returnsMappingBusy, and the mapping is not changed.XSetDeviceButtonMapping can generate BadDevice, BadMatch,and BadValue errors.To get the button mapping, use XGetDeviceButtonMapping.__│ int XGetDeviceButtonMapping(display, device, map_return, nmap)Display *display;XDevice *device;unsigned char map_return[];int nmap;display Specifies the connection to the X server.device Specifies the desired device.map_returnSpecifies the mapping list.nmap Specifies the number of items in the mapping list.│__ XGetDeviceButtonMapping returns the current mapping of thespecified extension device. Elements of the list areindexed starting from one. XGetDeviceButtonMapping returnsthe number of physical buttons actually on the pointer. Thenominal mapping for the buttons is the identity mapping:map[i]=i. The nmap argument specifies the length of thearray where the button mapping is returned, and only thefirst nmap elements are returned in map_return.XGetDeviceButtonMapping can generate BadDevice and BadMatcherrors.2.1.12. Obtaining the State of a DeviceTo obtain information that describes the state of the keys,buttons, and valuators of an extension device, useXQueryDeviceState.__│ XDeviceState * XQueryDeviceState(display, device)Display *display;XDevice *device;display Specifies the connection to the X server.device Specifies the desired device.│__ XQueryDeviceState returns a pointer to an XDeviceStatestructure, which points to a list of structures thatdescribe the state of the keys, buttons, and valuators onthe device:__│ typedef struct {XID device_id;int num_classes;XInputClass *data;} XDeviceState;│__ The structures are of variable length, but the first twomembers are common to all and are as follows:__│ typedef struct {unsigned char class;unsigned char length;} XInputClass;│__ The class member contains a class identifier. Thisidentifier can be compared with constants defined in thefile <X11/extensions/XI.h>. Currently defined constantsare: KeyClass, ButtonClass, and ValuatorClass.The length member contains the length of the structure andcan be used by clients to traverse the list.The XValuatorState structure describes the current state ofthe valuators on the device. The num_valuators membercontains the number of valuators on the device. The modemember is a mask whose bits report the data mode and otherstate information for the device. The following bits arecurrently defined:DeviceMode 1 << 0Relative = 0, Absolute = 1ProximityState 1 << 1InProximity = 0, OutOfProximity = 1The valuators member contains a pointer to an array ofintegers that describe the current value of the valuators.If the mode is Relative, these values are undefined.__│ typedef struct {unsigned char class;unsigned char length;unsigned char num_valuators;unsigned char mode;int *valuators;} XValuatorState;│__ The XKeyState structure describes the current state of thekeys on the device. Byte N (from 0) contains the bits forkey 8N to 8N + 7 with the least significant bit in the byterepresenting key 8N.__│ typedef struct {unsigned char class;unsigned char length;short num_keys;char keys[32];} XKeyState;│__ The XButtonState structure describes the current state ofthe buttons on the device. Byte N (from 0) contains thebits for button 8N to 8N + 7 with the least significant bitin the byte representing button 8N.__│ typedef struct {unsigned char class;unsigned char length;short num_buttons;char buttons[32];} XButtonState;│__ XQueryDeviceState can generate BadDevice errors.To free the data returned by this function, useXFreeDeviceState.__│ void XFreeDeviceState(state)XDeviceState *state;state Specifies the pointer to the XDeviceState datareturned by a previous call to XQueryDeviceState.│__ XFreeDeviceState frees the device state data.2.2. EventsThe input extension creates input events analogous to thecore input events. These extension input events aregenerated by manipulating one of the extension inputdevices. The remainder of this section discusses thefollowing X Input Extension event topics:• Event types• Event classes• Event structures2.2.1. Event TypesEvent types are integer numbers that a client can use todetermine what kind of event it has received. The clientcompares the type field of the event structure with knownevent types to make this determination.The core input event types are constants and are defined inthe header file <X11/X.h>. Extension event types are notconstants. Instead, they are dynamically allocated by theextension’s request to the X server when the extension isinitialized. Because of this, extension event types must beobtained by the client from the server.The client program determines the event type for anextension event by using the information returned by theXOpenDevice request. This type can then be used forcomparison with the type field of events received by theclient.Extension events propagate up the window hierarchy in thesame manner as core events. If a window is not interestedin an extension event, it usually propagates to the closestancestor that is interested, unless the dont_propagate listprohibits it. Grabs of extension devices may alter the setof windows that receive a particular extension event.The following table lists the event category and itsassociated event type or types.2.2.2. Event ClassesEvent classes are integer numbers that are used in the sameway as the core event masks. They are used by a clientprogram to indicate to the server which events that clientprogram wishes to receive.The core input event masks are constants and are defined inthe header file <X11/X.h>. Extension event classes are notconstants. Instead, they are dynamically allocated by theextension’s request to the X server when the extension isinitialized. Because of this, extension event classes mustbe obtained by the client from the server.The event class for an extension event and device isobtained from information returned by the XOpenDevicefunction. This class can then be used in anXSelectExtensionEvent request to ask that events of thattype from that device be sent to the client program.For DeviceButtonPress events, the client may specify whetheror not an implicit passive grab should be done when thebutton is pressed. If the client wants to guarantee that itwill receive a DeviceButtonRelease event for eachDeviceButtonPress event it receives, it should specify theDeviceButtonPressGrab class in addition to theDeviceButtonPress class. This restricts the client in thatonly one client at a time may request DeviceButtonPressevents from the same device and window if any clientspecifies this class.If any client has specified the DeviceButtonPressGrab class,any requests by any other client that specify the samedevice and window and specify either DeviceButtonPress orDeviceButtonPressGrab will cause an Access error to begenerated.If only the DeviceButtonPress class is specified, noimplicit passive grab will be done when a button is pressedon the device. Multiple clients may use this class tospecify the same device and window combination.The client may also select DeviceMotion events only when abutton is down. It does this by specifying the eventclasses DeviceButton1Motion through DeviceButton5Motion. Aninput device will support only as many button motion classesas it has buttons.2.2.3. Event StructuresEach extension event type has a corresponding structuredeclared in <X11/extensions/XInput.h>. All event structureshave the following common members:type Set to the event type number that uniquelyidentifies it. For example, when the X serverreports a DeviceKeyPress event to a clientapplication, it sends an XDeviceKeyPressEventstructure.serial Set from the serial number reported in theprotocol but expanded from the 16-bit leastsignificant bits to a full 32-bit value.send_eventSet to True if the event came from an XSendEventrequest.display Set to a pointer to a structure that defines thedisplay on which the event was read.Extension event structures report the current position ofthe X pointer. In addition, if the device reports motiondata and is reporting absolute data, the current value ofany valuators the device contains is also reported.2.2.3.1. Device Key EventsKey events from extension devices contain all theinformation that is contained in a key event from the Xkeyboard. In addition, they contain a device ID and reportthe current value of any valuators on the device, if thatdevice is reporting absolute data. If data for more thansix valuators is being reported, more than one key eventwill be sent. The axes_count member contains the number ofaxes that are being reported. The server sends as many ofthese events as are needed to report the device data. Eachevent contains the total number of axes reported in theaxes_count member and the first axis reported in the currentevent in the first_axis member. If the device supportsinput class Valuators, but is not reporting absolute modedata, the axes_count member contains zero (0).The location reported in the x, y and x_root, y_root membersis 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 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 keycode; /* 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];} XDeviceKeyEvent;typedef XDeviceKeyEvent XDeviceKeyPressedEvent;typedef XDeviceKeyEvent XDeviceKeyReleasedEvent;│__ 2.2.3.2. Device Button EventsButton events from extension devices contain all theinformation that is contained in a button event from the Xpointer. In addition, they contain a device ID and reportthe current value of any valuators on the device if thatdevice is reporting absolute data. If data for more thansix valuators is being reported, more than one button eventmay be sent. The axes_count member contains the number ofaxes that are being reported. The server sends as many ofthese events as are needed to report the device data. Eachevent contains the total number of axes reported in theaxes_count member and the first axis reported in the currentevent in the first_axis member. If the device supportsinput class Valuators, but is not reporting absolute modedata, the axes_count member contains zero (0).The location reported in the x, y and x_root, y_root membersis 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 int device_state;/* device key or button mask */unsigned char axes_count;unsigned char first_axis;int axis_data[6];} XDeviceButtonEvent;typedef XDeviceButtonEvent XDeviceButtonPressedEvent;typedef XDeviceButtonEvent XDeviceButtonReleasedEvent;│__ 2.2.3.3. Device Motion EventsMotion events from extension devices contain all theinformation that is contained in a motion event from the Xpointer. In addition, they contain a device ID and reportthe current value of any valuators on the device.The location reported in the x, y and x_root, y_root membersis the location of the core X pointer, and so is2-dimensional.Extension motion devices may report motion data for avariable number of axes. The axes_count member contains thenumber of axes that are being reported. The server sends asmany of these events as are needed to report the devicedata. Each event contains the total number of axes reportedin the axes_count member and the first axis reported in thecurrent event in the first_axis member.__│ 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 */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;│__ 2.2.3.4. Device Focus EventsThese events are equivalent to the core focus events. Theycontain the same information, with the addition of a deviceID to identify which device has had a focus change, and atimestamp.DeviceFocusIn and DeviceFocusOut events are generated forfocus changes of extension devices in the same manner ascore 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;│__ 2.2.3.5. Device StateNotify EventThis event is analogous to the core keymap event but reportsthe current state of the device for each input class that itsupports. It is generated after every DeviceFocusIn eventand EnterNotify event and is delivered to clients who haveselected XDeviceStateNotify events.If the device supports input class Valuators, the modemember in the XValuatorStatus structure is a bitmask thatreports the device mode, proximity state, and other stateinformation. The following bits are currently defined:0x01 Relative = 0, Absolute = 10x02 InProximity = 0, OutOfProximity = 1If the device supports more valuators than can be reportedin a single XEvent, multiple XDeviceStateNotify events willbe 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;│__ 2.2.3.6. Device Mapping EventThis 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;│__ 2.2.3.7. ChangeDeviceNotify EventThis event has no equivalent in the core protocol. Itnotifies client programs when one of the core devices hasbeen changed.__│ typedef struct {int type;unsigned long serial;Bool send_event;Display *display;Window window;XID deviceid;Time time;int request;} XChangeDeviceNotifyEvent;│__ 2.2.3.8. Proximity EventsThese events have no equivalent in the core protocol. Someinput devices such as graphics tablets or touchscreens maysend these events to indicate that a stylus has moved intoor out of contact with a positional sensing surface.The event contains the current value of any valuators on thedevice if that device is reporting absolute data. If datafor more than six valuators is being reported, more than oneproximity event may be sent. The axes_count member containsthe number of axes that are being reported. The serversends as many of these events as are needed to report thedevice data. Each event contains the total number of axesreported in the axes_count member and the first axisreported in the current event in the first_axis member. Ifthe device supports input class Valuators, but is notreporting absolute mode data, the axes_count member containszero (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 int device_state;/* device key or button mask */unsigned char axes_count;unsigned char first_axis;int axis_data[6];} XProximityNotifyEvent;typedef XProximityNotifyEvent XProximityInEvent;typedef XProximityNotifyEvent XProximityOutEvent;│__ 2.3. Event Handling FunctionsThis section discusses the X Input Extension event handlingfunctions that allow you to:• Determine the extension version• List the available devices• Enable and disable extension devices• Change the mode of a device• Initialize valuators on an input device• Get input device controls• Change input device controls• Select extension device events• Determine selected device events• Control event propogation• Send an event• Get motion history2.3.1. Determining the Extension Version__│ XExtensionVersion * XGetExtensionVersion(display, name)Display *display;char *name;display Specifies the connection to the X server.name Specifies the name of the desired extension.│__ XGetExtensionVersion allows a client to determine whether aserver supports the desired version of the input extension.The XExtensionVersion structure returns information aboutthe version of the extension supported by the server and isdefined as follows:__│ typedef struct {Bool present;short major_version;short minor_version;} XExtensionVersion;│__ The major and minor versions can be compared with constantsdefined in the header file <X11/extensions/XI.h>. Eachversion is a superset of the previous versions.You should use XFree to free the data returned by thisfunction.2.3.2. Listing Available DevicesA client program that wishes to access a specific devicemust first determine whether that device is connected to theX server. This is done through the XListInputDevicesfunction, which will return a list of all devices that canbe opened by the X server. The client program can use oneof the names defined in the <X11/extensions/XI.h> headerfile in an XInternAtom request to determine the device typeof the desired device. This type can then be compared withthe device types returned by the XListInputDevices request.__│ XDeviceInfo * XListInputDevices(display, ndevices)Display *display;int *ndevices; /* RETURN */display Specifies the connection to the X server.ndevices Specifies the address of a variable into which theserver can return the number of input devicesavailable to the X server.│__ XListInputDevices allows a client to determine which devicesare available for X input and information about thosedevices. An array of XDeviceInfo structures is returned,with one element in the array for each device. The numberof devices is returned in the ndevices argument.The X pointer device and X keyboard device are reported, aswell as all available extension input devices. The usemember of the XDeviceInfo structure specifies the currentuse of the device. If the value of this member isIsXPointer, the device is the X pointer device. If thevalue is IsXKeyboard, the device is the X keyboard device.If the value is IsXExtensionDevice, the device is availablefor use as an extension input device.Each XDeviceInfo entry contains a pointer to a list ofstructures that describe the characteristics of each classof input supported by that device. The num_classes membercontains the number of entries in that list.If the device supports input class Valuators, one of thestructures pointed to by the XDeviceInfo structure will bean XValuatorInfo structure. The axes member of thatstructure contains the address of an array of XAxisInfostructures. There is one element in this array for eachaxis of motion reported by the device. The number ofelements in this array is contained in the num_axes elementof the XValuatorInfo structure. The size of the motionbuffer for the device is reported in the motion_buffermember of the XValuatorInfo structure.The XDeviceInfo structure is defined as follows:__│ typedef struct _XDeviceInfo {XID id;Atom type;char *name;int num_classes;int use;XAnyClassPtr inputclassinfo;} XDeviceInfo;│__ The structures pointed to by the XDeviceInfo structure aredefined as follows:__│ typedef struct _XKeyInfo {XID class;int length;unsigned short min_keycode;unsigned short max_keycode;unsigned short num_keys;} XKeyInfo;typedef struct _XButtonInfo {XID class;int length;short num_buttons;} XButtonInfo;typedef struct _XValuatorInfo {XID class;int length;unsigned char num_axes;unsigned char mode;unsigned long motion_buffer;XAxisInfoPtr axes;} XValuatorInfo;│__ The XAxisInfo structure pointed to by the XValuatorInfostructure is defined as follows:__│ typedef struct _XAxisInfo {int resolution;int min_value;int max_value;} XAxisInfo;│__ The following atom names are defined in the<X11/extensions/XI.h> header file.MOUSE QUADRATURETABLET SPACEBALLKEYBOARD DATAGLOVETOUCHSCREEN EYETRACKERTOUCHPAD CURSORKEYSBUTTONBOX FOOTMOUSEBARCODE ID_MODULEKNOB_BOX ONE_KNOBTRACKBALL NINE_KNOBThese names can be used in an XInternAtom request to returnan atom that can be used for comparison with the type memberof the XDeviceInfo structure.XListInputDevices returns NULL if there are no input devicesto list.To free the data returned by XListInputDevices, useXFreeDeviceList.__│ void XFreeDeviceList(list)XDeviceInfo *list;list Specifies the pointer to the XDeviceInfo arrayreturned by a previous call to XListInputDevices.│__ XFreeDeviceList frees the list of input device information.2.3.3. Enabling and Disabling Extension DevicesEach client program that wishes to access an extensiondevice must request that the server open that device bycalling the XOpenDevice function.__│ XDevice * XOpenDevice(display, device_id)Display *display;XID device_id;display Specifies the connection to the X server.device_id Specifies the ID that uniquely identifies thedevice to be opened. This ID is obtained from theXListInputDevices request.│__ XOpenDevice opens the device for the requesting client and,on success, returns an XDevice structure, which is definedas follows:__│ typedef struct {XID device_id;int num_classes;XInputClassInfo *classes;} XDevice;│__ The XDevice structure contains a pointer to an array ofXInputClassInfo structures. Each element in that arraycontains information about events of a particular inputclass supported by the input device.The XInputClassInfo structure is defined as follows:__│ typedef struct {unsigned char input_class;unsigned char event_type_base;} XInputClassInfo;│__ A client program can determine the event type and eventclass for a given event by using macros defined by the inputextension. The name of the macro corresponds to the desiredevent, and the macro is passed the structure that describesthe device from which input is desired, for example:DeviceKeyPress(XDevice *device, event_type, event_class)The macro will fill in the values of the event class to beused in an XSelectExtensionEvent request to select the eventand the event type to be used in comparing with the eventtypes of events received via XNextEvent.XOpenDevice can generate BadDevice errors.Before terminating, the client program should request thatthe server close the device by calling the XCloseDevicefunction.__│ int XCloseDevice(display, device)Display *display;XDevice *device;display Specifies the connection to the X server.device Specifies the device to be closed.│__ XCloseDevice closes the device for the requesting client andfrees the associated XDevice structure.A client may open the same extension device more than once.Requests after the first successful one return an additionalXDevice structure with the same information as the first,but otherwise have no effect. A single XCloseDevice requestwill terminate that client’s access to the device.Closing a device releases any active or passive grabs therequesting client has established. If the device is frozenonly by an active grab of the requesting client, any queuedevents are released.If a client program terminates without closing a device, theserver will automatically close that device on behalf of theclient. This does not affect any other clients that may beaccessing that device.XCloseDevice can generate BadDevice errors.2.3.4. Changing the Mode of a DeviceSome devices are capable of reporting either relative orabsolute motion data. To change the mode of a device fromrelative to absolute, use XSetDeviceMode.__│ int XSetDeviceMode(display, device, mode)Display *display;XDevice *device;int mode;display Specifies the connection to the X server.device Specifies the device whose mode should be changed.mode Specifies the mode. You can pass Absolute orRelative.│__ XSetDeviceMode allows a client to request the server tochange the mode of a device that is capable of reportingeither absolute positional data or relative motion data. Ifthe device is invalid or if the client has not previouslyrequested that the server open the device via an XOpenDevicerequest, this request will fail with a BadDevice error. Ifthe device does not support input class Valuators or if itis not capable of reporting the specified mode, the requestwill fail with a BadMatch error.This request will fail and return DeviceBusy if anotherclient has already opened the device and requested adifferent mode.XSetDeviceMode can generate BadDevice, BadMatch, BadMode,and DeviceBusy errors.2.3.5. Initializing Valuators on an Input DeviceSome devices that report absolute positional data can beinitialized to a starting value. Devices that are capableof reporting relative motion or absolute positional data mayrequire that their valuators be initialized to a startingvalue after the mode of the device is changed to Absolute.To initialize the valuators on such a device, useXSetDeviceValuators.__│ Status XSetDeviceValuators(display, device, valuators, first_valuator, num_valuators)Display *display;XDevice *device;int *valuators, first_valuator, num_valuators;display Specifies the connection to the X server.device Specifies the device whose valuators should beinitialized.valuators Specifies the values to which each valuator shouldbe set.first_valuatorSpecifies the first valuator to be set.num_valuatorsSpecifies the number of valuators to be set.│__ XSetDeviceValuators initializes the specified valuators onthe specified extension input device. Valuators arenumbered beginning with zero. Only the valuators in therange specified by first_valuator and num_valuators are set.A BadValue error results if the number of valuatorssupported by the device is less than the followingexpression:first_valuator + num_valuatorsIf the request succeeds, Success is returned. If thespecified device is grabbed by some other client, therequest will fail and a status of AlreadyGrabbed will bereturned.XSetDeviceValuators can generate BadDevice, BadLength,BadMatch, and BadValue errors.2.3.6. Getting Input Device ControlsSome input devices support various configuration controlsthat can be queried or changed by clients. The set ofsupported controls will vary from one input device toanother. Requests to manipulate these controls will fail ifeither the target X server or the target input device doesnot support the requested device control.Each device control has a unique identifier. Informationpassed with each device control varies in length and ismapped by data structures unique to that device control.To query a device control, use XGetDeviceControl.__│ XDeviceControl * XGetDeviceControl(display, device, control)Display *display;XDevice *device;int control;display Specifies the connection to the X server.device Specifies the device whose configuration controlstatus is to be returned.control Identifies the specific device control to bequeried.│__ XGetDeviceControl returns the current state of the specifieddevice control. If the target X server does not supportthat device control, a BadValue error is returned. If thespecified device does not support that device control, aBadMatch error is returned.If the request is successful, a pointer to a genericXDeviceState structure is returned. The informationreturned varies according to the specified control and ismapped by a structure appropriate for that control. Thefirst two members are common to all device controls and aredefined as follows:__│ typedef struct {XID control;int length;} XDeviceState;│__ The control may be compared to constants defined in the file<X11/extensions/XI.h>. Currently defined device controlsinclude DEVICE_RESOLUTION.The information returned for the DEVICE_RESOLUTION controlis defined in the XDeviceResolutionState structure, which isdefined as follows:__│ typedef struct {XID control;int length;int num_valuators;int *resolutions;int *min_resolutions;int *max_resolutions;} XDeviceResolutionState;│__ This device control returns a list of valuators and therange of valid resolutions allowed for each. Valuators arenumbered beginning with zero (0). Resolutions for allvaluators on the device are returned. For each valuator ion the device, resolutions[i] returns the current setting ofthe resolution, min_resolutions[i] returns the minimum validsetting, and max_resolutions[i] returns the maximum validsetting.When this control is specified, XGetDeviceControl fails witha BadMatch error if the specified device has no valuators.XGetDeviceControl can generate BadMatch and BadValue errors.2.3.7. Changing Input Device ControlsSome input devices support various configuration controlsthat can be changed by clients. Typically, this would bedone to initialize the device to a known state orconfiguration. The set of supported controls will vary fromone input device to another. Requests to manipulate thesecontrols will fail if either the target X server or thetarget input device does not support the requested devicecontrol. Setting the device control will also fail if thetarget input device is grabbed by another client or is openby another client and has been set to a conflicting state.Each device control has a unique identifier. Informationpassed with each device control varies in length and ismapped by data structures unique to that device control.To change a device control, use XChangeDeviceControl.__│ Status XChangeDeviceControl(display, device, control, value)Display *display;XDevice *device;int control;XDeviceControl *value;display Specifies the connection to the X server.device Specifies the device whose configuration controlstatus is to be modified.control Identifies the specific device control to bechanged.value Specifies a pointer to an XDeviceControl structurethat describes which control is to be changed andhow it is to be changed.│__ XChangeDeviceControl changes the current state of thespecified device control. If the target X server does notsupport that device control, a BadValue error is returned.If the specified device does not support that devicecontrol, a BadMatch error is returned. If another clienthas the target device grabbed, a status of AlreadyGrabbed isreturned. If another client has the device open and has setit to a conflicting state, a status of DeviceBusy isreturned. If the request fails for any reason, the devicecontrol will not be changed.If the request is successful, the device control will bechanged and a status of Success is returned. Theinformation passed varies according to the specified controland is mapped by a structure appropriate for that control.The first two members are common to all device controls:__│ typedef struct {XID control;int length;} XDeviceControl;│__ The control may be set using constants defined in the<X11/extensions/XI.h> header file. Currently defined devicecontrols include DEVICE_RESOLUTION.The information that can be changed by the DEVICE_RESOLUTIONcontrol is defined in the XDeviceResolutionControlstructure, which is defined as follows:__│ typedef struct {XID control;int length;int first_valuator;int num_valuators;int *resolutions;} XDeviceResolutionControl;│__ This device control changes the resolution of the specifiedvaluators on the specified extension input device.Valuators are numbered beginning with zero. Only thevaluators in the range specified by first_valuator andnum_valuators are set. A value of -1 in the resolutionslist indicates that the resolution for this valuator is notto be changed. The num_valuators member specifies thenumber of valuators in the resolutions list.When this control is specified, XChangeDeviceControl failswith a BadMatch error if the specified device has novaluators. If a resolution is specified that is not withinthe range of valid values (as returned byXGetDeviceControl), XChangeDeviceControl fails with aBadValue error. A BadValue error results if the number ofvaluators supported by the device is less than the followingexpression:first_valuator + num_valuators,XChangeDeviceControl can generate BadMatch and BadValueerrors.2.3.8. Selecting Extension Device EventsTo select device input events, use XSelectExtensionEvent.The parameters passed are a pointer to a list of classesthat define the desired event types and devices, a count ofthe number of elements in the list, and the ID of the windowfrom which events are desired.__│ int XSelectExtensionEvent(display, window, event_list, event_count)Display *display;Window window;XEventClass *event_list;int event_count;display Specifies the connection to the X server.window Specifies the ID of the window from which theclient wishes to receive events.event_listSpecifies a pointer to an array of event classesthat specify which events are desired.event_countSpecifies the number of elements in theevent_list.│__ XSelectExtensionEvent requests the server to send eventsthat match the events and devices described by the eventlist and that come from the requested window. The elementsof the XEventClass array are the event_class values obtainedby invoking a macro with the pointer to an XDevice structurereturned by the XOpenDevice request. For example, theDeviceKeyPress macro would return the XEventClass forDeviceKeyPress events from the specified device if it wereinvoked in the following form:DeviceKeyPress (XDevice *device, event_type, event_class)Macros are defined for the following event classes:DeviceKeyPressDeviceKeyReleaseDeviceButtonPressDeviceButtonReleaseDeviceMotionNotifyDeviceFocusInDeviceFocusOutProximityInProximityOutDeviceStateNotifyDeviceMappingNotifyChangeDeviceNotifyDevicePointerMotionHintDeviceButton1MotionDeviceButton2MotionDeviceButton3Motion,DeviceButton4MotionDeviceButton5MotionDeviceButtonMotion,DeviceOwnerGrabButtonDeviceButtonPressGrabTo get the next available event from within a clientprogram, use the core XNextEvent function. This returns thenext event whether it came from a core device or anextension device.Succeeding XSelectExtensionEvent requests using eventclasses for the same device as was specified on a previousrequest will replace the previous set of selected eventsfrom that device with the new set.XSelectExtensionEvent can generate BadAccess, BadClass,BadLength, and BadWindow errors.2.3.9. Determining Selected Device EventsTo determine which extension events are currently selectedfrom a given window, use XGetSelectedExtensionEvents.__│ int XGetSelectedExtensionEvents(display, window, this_client_count, this_client,all_clients_count, all_clients)Display *display;Window window;int *this_client_count; /* RETURN */XEventClass **this_client; /* RETURN */int *all_clients_count; /* RETURN */XEventClass **all_clients; /* RETURN */display Specifies the connection to the X server.window Specifies the ID of the window from which theclient wishes to receive events.this_client_countReturns the number of elements in the this_clientlist.this_clientReturns a list of XEventClasses that specify whichevents are selected by this client.all_clients_countReturns the number of elements in the all_clientslist.all_clientsReturns a list of XEventClasses that specify whichevents are selected by all clients.│__ XGetSelectedExtensionEvents returns pointers to two eventclass arrays. One lists the extension events selected bythis client from the specified window. The other lists theextension events selected by all clients from the specifiedwindow. This information is analogous to that returned inyour_event_mask and all_event_masks of the XWindowAttributesstructure when an XGetWindowAttributes request is made. Tofree the two arrays returned by this function, use XFree.XGetSelectedExtensionEvents can generate BadWindow errors.2.3.10. Controlling Event PropagationExtension events propagate up the window hierarchy in thesame manner as core events. If a window is not interestedin an extension event, it usually propagates to the closestancestor that is interested, unless the dont_propagate listprohibits it. Grabs of extension devices may alter the setof windows that receive a particular extension event.Client programs may control event propagation through theuse of the following two functions:XChangeDeviceDontPropagateList andXGetDeviceDontPropagateList.__│ int XChangeDeviceDontPropagateList(display, window, event_count, events, mode)Display *display;Window window;int event_count;XEventClass *events;int mode;display Specifies the connection to the X server.window Specifies the desired window.event_countSpecifies the number of elements in the eventslist.events Specifies a pointer to the list of XEventClasses.mode Specifies the mode. You can pass AddToList orDeleteFromList.│__ XChangeDeviceDontPropagateList adds an event to or deletesan event from the do_not_propagate list of extension eventsfor the specified window. There is one list per window, andthe list remains for the life of the window. The list isnot altered if a client that changed the list terminates.Suppression of event propagation is not allowed for allevents. If a specified XEventClass is invalid becausesuppression of that event is not allowed, a BadClass errorresults.XChangeDeviceDontPropagateList can generate BadClass,BadMode, and BadWindow errors.__│ XEventClass * XGetDeviceDontPropagateList(display, window, event_count)Display *display;Window window;int *event_count; /*RETURN */display Specifies the connection to the X server.window Specifies the desired window.event_countReturns the number of elements in the arrayreturned by this function.│__ XGetDeviceDontPropagateList allows a client to determine thedo_not_propagate list of extension events for the specifiedwindow. It returns an array of XEventClass, eachXEventClass representing a device/event type pair. To freethe data returned by this function, use XFree.XGetDeviceDontPropagateList can generate BadWindow errors.2.3.11. Sending an EventTo send an extension event to another client, useXSendExtensionEvent.__│ int XSendExtensionEvent(display, device, window, propagate, event_count, event_list, event)Display *display;XDevice *device;Window window;Bool propagate;int event_count;XEventClass *event_list;XEvent *event;display Specifies the connection to the X server.device Specifies the device whose ID is recorded in theevent.window Specifies the destination window ID. You can passa window ID, PointerWindow or InputFocus.propagate Specifies a boolean value that is either True orFalse.event_countSpecifies the number of elements in the event_listarray.event_listSpecifies a pointer to an array of XEventClass.event Specifies a pointer to the event that is to besent.│__ XSendExtensionEvent identifies the destination window,determines which clients should receive the specified event,and ignores any active grabs. It requires a list ofXEventClass to be specified. These are obtained by openingan input device with the XOpenDevice request.XSendExtensionEvent uses the window argument to identify thedestination window as follows:• If you pass PointerWindow, the destination window isthe window that contains the pointer.• If you pass InputFocus and if the focus window containsthe pointer, the destination window is the window thatcontains the pointer. If the focus window does notcontain the pointer, the destination window is thefocus window.To determine which clients should receive the specifiedevents, XSendExtensionEvent uses the propagate argument asfollows:• If propagate is False, the event is sent to everyclient selecting from the destination window any of theevents specified in the event_list array.• If propagate is True and no clients have selected fromthe destination window any of the events specified inthe event_list array, the destination is replaced withthe closest ancestor of destination for which someclient has selected one of the specified events and forwhich no intervening window has that event in itsdo_not_propagate mask. If no such window exists, or ifthe window is an ancestor of the focus window, andInputFocus was originally specified as the destination,the event is not sent to any clients. Otherwise, theevent is reported to every client selecting on thefinal destination any of the events specified inevent_list.The event in the XEvent structure must be one of the eventsdefined by the input extension, so that the X server cancorrectly byte swap the contents as necessary. The contentsof the event are otherwise unaltered and unchecked by the Xserver except to force send_event to True in the forwardedevent and to set the sequence number in the event correctly.XSendExtensionEvent returns zero if the conversion-to-wireprotocol failed; otherwise, it returns nonzero.XSendExtensionEvent can generate BadClass, BadDevice,BadValue, and BadWindow errors.2.3.12. Getting Motion History__│ XDeviceTimeCoord * XGetDeviceMotionEvents(display, device, start, stop, nevents_return, mode_return,axis_count_return);Display *display;XDevice *device;Time start, stop;int *nevents_return;int *mode_return;int *axis_count_return;display Specifies the connection to the X server.device Specifies the desired device.start Specifies the start time.stop Specifies the stop time.nevents_returnReturns the number of positions in the motionbuffer returned for this request.mode_returnReturns the mode of the nevents information. Themode will be one of the following: Absolute orRelative.axis_count_returnReturns the number of axes reported in each of thepositions returned.│__ XGetDeviceMotionEvents returns all positions in the device’smotion history buffer that fall between the specified startand stop times inclusive. If the start time is in thefuture or is later than the stop time, no positions arereturned.The return type for this function is an XDeviceTimeCoordstructure, which is defined as follows:__│ typedef struct {Time time;unsigned int *data;} XDeviceTimeCoord;│__ The data member is a pointer to an array of data items.Each item is of type int, and there is one data item peraxis of motion reported by the device. The number of axesreported by the device is returned in the axis_countvariable.The value of the data items depends on the mode of thedevice. The mode is returned in the mode variable. If themode is Absolute, the data items are the raw valuesgenerated by the device. These may be scaled by the clientprogram using the maximum values that the device cangenerate for each axis of motion that it reports. Themaximum value for each axis is reported in the max_valmember of the XAxisInfo structure, which is part of theinformation returned by the XListInputDevices request.If the mode is Relative, the data items are the relativevalues generated by the device. The client program mustchoose an initial position for the device and maintain acurrent position by accumulating these relative values.Consecutive calls to XGetDeviceMotionEvents can return dataof different modes, that is, if some client program haschanged the mode of the device via an XSetDeviceModerequest.XGetDeviceMotionEvents can generate BadDevice and BadMatcherrors.To free the data returned by XGetDeviceMotionEvents, useXFreeDeviceMotionEvents.__│ void XFreeDeviceMotionEvents(events)XDeviceTimeCoord *events;events Specifies the pointer to the XDeviceTimeCoordarray returned by a previous call toXGetDeviceMotionEvents.│__ XFreeDeviceMotionEvents frees the specified array of motioninformation. 1

X Input Extension Library X11, Release 6.4

Appendix A

The following information is contained in the <X11/extensions/XInput.h> and <X11/extensions/XI.h> header files:

/************************************************************

Copyright 1989, 1998  The Open Group

Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation.

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
OPEN GROUP 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 Open Group 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 Open Group.

Copyright 1989 by Hewlett-Packard Company, Palo Alto, California.

               All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Hewlett-Packard not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.

HEWLETT-PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
HEWLETT-PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

********************************************************/
/* $XFree86: xc/doc/specs/Xi/library.ms,v 1.3 2006/01/09 14:56:34 dawes Exp $ */

/* Definitions used by the library and client */

#ifndef _XINPUT_H_
#define _XINPUT_H_

#include <X11/Xlib.h>
#include <X11/extensions/XI.h>

#define _deviceKeyPress       0
#define _deviceKeyRelease     1

#define _deviceButtonPress    0
#define _deviceButtonRelease  1

#define _deviceMotionNotify   0

#define _deviceFocusIn        0
#define _deviceFocusOut       1

#define _proximityIn          0
#define _proximityOut         1

#define _deviceStateNotify    0
#define _deviceMappingNotify  1
#define _changeDeviceNotify   2

#define FindTypeAndClass(d,type,_class,classid,offset)     { int _i; XInputClassInfo *_ip;     type = 0; _class = 0;     for (_i=0, _ip= ((XDevice *) d)->classes;    _i< ((XDevice *) d)->num_classes;       _i++, _ip++)  if (_ip->input_class == classid)       {type =  _ip->event_type_base + offset;       _class =  ((XDevice *) d)->device_id << 8 | type;}}

#define DeviceKeyPress(d,type,_class)     FindTypeAndClass(d, type, _class, KeyClass, _deviceKeyPress)

#define DeviceKeyRelease(d,type,_class)     FindTypeAndClass(d, type, _class, KeyClass, _deviceKeyRelease)

#define DeviceButtonPress(d,type,_class)     FindTypeAndClass(d, type, _class, ButtonClass, _deviceButtonPress)

#define DeviceButtonRelease(d,type,_class)     FindTypeAndClass(d, type, _class, ButtonClass, _deviceButtonRelease)

#define DeviceMotionNotify(d,type,_class)     FindTypeAndClass(d, type, _class, ValuatorClass, _deviceMotionNotify)

#define DeviceFocusIn(d,type,_class)     FindTypeAndClass(d, type, _class, FocusClass, _deviceFocusIn)

#define DeviceFocusOut(d,type,_class)     FindTypeAndClass(d, type, _class, FocusClass, _deviceFocusOut)

#define ProximityIn(d,type,_class)     FindTypeAndClass(d, type, _class, ProximityClass, _proximityIn)

#define ProximityOut(d,type,_class)     FindTypeAndClass(d, type, _class, ProximityClass, _proximityOut)

#define DeviceStateNotify(d,type,_class)     FindTypeAndClass(d, type, _class, OtherClass, _deviceStateNotify)

#define DeviceMappingNotify(d,type,_class)     FindTypeAndClass(d, type, _class, OtherClass, _deviceMappingNotify)

#define ChangeDeviceNotify(d,type,_class)     FindTypeAndClass(d, type, _class, OtherClass, _changeDeviceNotify)

#define DevicePointerMotionHint(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _devicePointerMotionHint;}

#define DeviceButton1Motion(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButton1Motion;}

#define DeviceButton2Motion(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButton2Motion;}

#define DeviceButton3Motion(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButton3Motion;}

#define DeviceButton4Motion(d,type, _class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButton4Motion;}

#define DeviceButton5Motion(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButton5Motion;}

#define DeviceButtonMotion(d,type, _class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButtonMotion;}

#define DeviceOwnerGrabButton(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceOwnerGrabButton;}

#define DeviceButtonPressGrab(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _deviceButtonGrab;}

#define NoExtensionEvent(d,type,_class)     { _class =  ((XDevice *) d)->device_id << 8 | _noExtensionEvent;}

#define BadDevice(dpy,error) _xibaddevice(dpy, &error)

#define BadClass(dpy,error) _xibadclass(dpy, &error)

#define BadEvent(dpy,error) _xibadevent(dpy, &error)

#define BadMode(dpy,error) _xibadmode(dpy, &error)

#define DeviceBusy(dpy,error) _xidevicebusy(dpy, &error)

/***************************************************************
 *
 * DeviceKey events.  These events are sent by input devices that
 * support input class Keys.
 * The location of the X pointer is reported in the coordinate
 * fields of the x,y and x_root,y_root fields.
 *
 */

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 occured 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   keycode;      /* 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];
    } XDeviceKeyEvent;

typedef XDeviceKeyEvent XDeviceKeyPressedEvent;
typedef XDeviceKeyEvent XDeviceKeyReleasedEvent;

/*******************************************************************
 *
 * DeviceButton events.  These events are sent by extension devices
 * that support input class Buttons.
 *
 */

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 occured 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 int  device_state; /* device key or button mask */
    unsigned char axes_count;
    unsigned char first_axis;
    int           axis_data[6];
    } XDeviceButtonEvent;

typedef XDeviceButtonEvent XDeviceButtonPressedEvent;
typedef XDeviceButtonEvent XDeviceButtonReleasedEvent;

/*******************************************************************
 *
 * DeviceMotionNotify event.  These events are sent by extension devices
 * that support input class Valuators.
 *
 */

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 occured 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 */
    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;

/*******************************************************************
 *
 * DeviceFocusChange events.  These events are sent when the focus
 * of an extension device that can be focused is changed.
 *
 */

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;
    int           mode;       /* NotifyNormal, NotifyGrab, NotifyUngrab */
    int           detail;
     /*
      * NotifyAncestor, NotifyVirtual, NotifyInferior,
      * NotifyNonLinear,NotifyNonLinearVirtual, NotifyPointer,
      * NotifyPointerRoot, NotifyDetailNone
      */
    Time                time;
    } XDeviceFocusChangeEvent;

typedef XDeviceFocusChangeEvent XDeviceFocusInEvent;
typedef XDeviceFocusChangeEvent XDeviceFocusOutEvent;

/*******************************************************************
 *
 * ProximityNotify events.  These events are sent by those absolute
 * positioning devices that are capable of generating proximity information.
 *
 */

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 int    device_state; /* device key or button mask */
    unsigned char   axes_count;
    unsigned char   first_axis;
    int             axis_data[6];
    } XProximityNotifyEvent;
typedef XProximityNotifyEvent XProximityInEvent;
typedef XProximityNotifyEvent XProximityOutEvent;

/*******************************************************************
 *
 * DeviceStateNotify events are generated on EnterWindow and FocusIn
 * for those clients who have selected DeviceState.
 *
 */

typedef struct
    {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    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 {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    unsigned char   length;
    unsigned char   num_valuators;
    unsigned char   mode;
    int                  valuators[6];
} XValuatorStatus;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    unsigned char   length;
    short      num_keys;
    char            keys[32];
} XKeyStatus;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    unsigned char   length;
    short      num_buttons;
    char            buttons[32];
} XButtonStatus;

/*******************************************************************
 *
 * DeviceMappingNotify event.  This event is sent when the key mapping,
 * modifier mapping, or button mapping of an extension device is changed.
 *
 */

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;       /* unused */
    XID           deviceid;
    Time          time;
    int           request;      /* one of MappingModifier, MappingKeyboard,
                                    MappingPointer */
    int           first_keycode;/* first keycode */
    int           count;        /* defines range of change w. first_keycode*/
} XDeviceMappingEvent;

/*******************************************************************
 *
 * ChangeDeviceNotify event.  This event is sent when an
 * XChangeKeyboard or XChangePointer request is made.
 *
 */

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;       /* unused */
    XID           deviceid;
    Time          time;
    int           request;      /* NewPointer or NewKeyboard */
} XChangeDeviceNotifyEvent;

/*******************************************************************
 *
 * Control structures for input devices that support input class
 * Feedback.  These are used by the XGetFeedbackControl and
 * XChangeFeedbackControl functions.
 *
 */

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
     XID            c_class;
#else
     XID            class;
#endif
     int            length;
     XID            id;
} XFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     click;
    int     percent;
    int     pitch;
    int     duration;
    int     led_mask;
    int     global_auto_repeat;
    char    auto_repeats[32];
} XKbdFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     accelNum;
    int     accelDenom;
    int     threshold;
} XPtrFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     resolution;
    int     minVal;
    int     maxVal;
} XIntegerFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     max_symbols;
    int     num_syms_supported;
    KeySym  *syms_supported;
} XStringFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     percent;
    int     pitch;
    int     duration;
} XBellFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     led_values;
    int     led_mask;
} XLedFeedbackState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
     XID            c_class;
#else
     XID            class;
#endif
     int            length;
     XID      id;
} XFeedbackControl;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     accelNum;
    int     accelDenom;
    int     threshold;
} XPtrFeedbackControl;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     click;
    int     percent;
    int     pitch;
    int     duration;
    int     led_mask;
    int     led_value;
    int     key;
    int     auto_repeat_mode;
} XKbdFeedbackControl;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     num_keysyms;
    KeySym  *syms_to_display;
} XStringFeedbackControl;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     int_to_display;
} XIntegerFeedbackControl;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     percent;
    int     pitch;
    int     duration;
} XBellFeedbackControl;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    XID     c_class;
#else
    XID     class;
#endif
    int     length;
    XID     id;
    int     led_mask;
    int     led_values;
} XLedFeedbackControl;

/*******************************************************************
 *
 * Device control structures.
 *
 */

typedef struct {
     XID            control;
     int            length;
} XDeviceControl;

typedef struct {
     XID            control;
     int            length;
     int            first_valuator;
     int            num_valuators;
     int            *resolutions;
} XDeviceResolutionControl;

typedef struct {
     XID            control;
     int            length;
     int            num_valuators;
     int            *resolutions;
     int            *min_resolutions;
     int            *max_resolutions;
} XDeviceResolutionState;

/*******************************************************************
 *
 * An array of XDeviceList structures is returned by the
 * XListInputDevices function.  Each entry contains information
 * about one input device.  Among that information is an array of
 * pointers to structures that describe the characteristics of
 * the input device.
 *
 */

typedef struct _XAnyClassinfo *XAnyClassPtr;

typedef struct _XAnyClassinfo {
#if defined(__cplusplus) || defined(c_plusplus)
    XID   c_class;
#else
    XID   class;
#endif
    int   length;
    } XAnyClassInfo;

typedef struct _XDeviceInfo *XDeviceInfoPtr;

typedef struct _XDeviceInfo
    {
    XID                 id;
    Atom                type;
    char                *name;
    int                 num_classes;
    int                 use;
    XAnyClassPtr    inputclassinfo;
    } XDeviceInfo;

typedef struct _XKeyInfo *XKeyInfoPtr;

typedef struct _XKeyInfo
    {
#if defined(__cplusplus) || defined(c_plusplus)
    XID             c_class;
#else
    XID             class;
#endif
    int             length;
    unsigned short      min_keycode;
    unsigned short      max_keycode;
    unsigned short      num_keys;
    } XKeyInfo;

typedef struct _XButtonInfo *XButtonInfoPtr;

typedef struct _XButtonInfo {
#if defined(__cplusplus) || defined(c_plusplus)
    XID        c_class;
#else
    XID        class;
#endif
    int        length;
    short      num_buttons;
    } XButtonInfo;

typedef struct _XAxisInfo *XAxisInfoPtr;

typedef struct _XAxisInfo {
    int   resolution;
    int   min_value;
    int   max_value;
    } XAxisInfo;

typedef struct _XValuatorInfo *XValuatorInfoPtr;

typedef struct _XValuatorInfo
    {
#if defined(__cplusplus) || defined(c_plusplus)
    XID             c_class;
#else
    XID             class;
#endif
    int             length;
    unsigned char       num_axes;
    unsigned char       mode;
    unsigned long       motion_buffer;
    XAxisInfoPtr        axes;
    } XValuatorInfo;


/*******************************************************************
 *
 * An XDevice structure is returned by the XOpenDevice function.
 * It contains an array of pointers to XInputClassInfo structures.
 * Each contains information about a class of input supported by the
 * device, including a pointer to an array of data for each type of event
 * the device reports.
 *
 */


typedef struct {
        unsigned char   input_class;
        unsigned char   event_type_base;
} XInputClassInfo;

typedef struct {
        XID                    device_id;
        int                    num_classes;
        XInputClassInfo        *classes;
} XDevice;


/*******************************************************************
 *
 * The following structure is used to return information for the
 * XGetSelectedExtensionEvents function.
 *
 */

typedef struct {
        XEventClass     event_type;
        XID             device;
} XEventList;

/*******************************************************************
 *
 * The following structure is used to return motion history data from
 * an input device that supports the input class Valuators.
 * This information is returned by the XGetDeviceMotionEvents function.
 *
 */

typedef struct {
        Time   time;
        int    *data;
} XDeviceTimeCoord;


/*******************************************************************
 *
 * Device state structure.
 * This is returned by the XQueryDeviceState request.
 *
 */

typedef struct {
        XID         device_id;
        int         num_classes;
        XInputClass *data;
} XDeviceState;

/*******************************************************************
 *
 * Note that the mode field is a bitfield that reports the Proximity
 * status of the device as well as the mode.  The mode field should
 * be OR’d with the mask DeviceMode and compared with the values
 * Absolute and Relative to determine the mode, and should be OR’d
 * with the mask ProximityState and compared with the values InProximity
 * and OutOfProximity to determine the proximity state.
 *
 */

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    unsigned char   length;
    unsigned char   num_valuators;
    unsigned char   mode;
    int                  *valuators;
} XValuatorState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    unsigned char   length;
    short      num_keys;
    char            keys[32];
} XKeyState;

typedef struct {
#if defined(__cplusplus) || defined(c_plusplus)
    unsigned char   c_class;
#else
    unsigned char   class;
#endif
    unsigned char   length;
    short      num_buttons;
    char            buttons[32];
} XButtonState;

/*******************************************************************
 *
 * Function definitions.
 *
 */

_XFUNCPROTOBEGIN

extern int     XChangeKeyboardDevice(
    Display*        /* display */,
    XDevice*        /* device */
);

extern int     XChangePointerDevice(
    Display*        /* display */,
    XDevice*        /* device */,
    int             /* xaxis */,
    int             /* yaxis */
);

extern int     XGrabDevice(
    Display*        /* display */,
    XDevice*        /* device */,
    Window          /* grab_window */,
    Bool       /* ownerEvents */,
    int             /* event count */,
    XEventClass*    /* event_list */,
    int             /* this_device_mode */,
    int             /* other_devices_mode */,
    Time       /* time */
);

extern int     XUngrabDevice(
    Display*        /* display */,
    XDevice*        /* device */,
    Time       /* time */
);

extern int     XGrabDeviceKey(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned int    /* key */,
    unsigned int    /* modifiers */,
    XDevice*        /* modifier_device */,
    Window          /* grab_window */,
    Bool       /* owner_events */,
    unsigned int    /* event_count */,
    XEventClass*    /* event_list */,
    int             /* this_device_mode */,
    int             /* other_devices_mode */
);

extern int     XUngrabDeviceKey(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned int    /* key */,
    unsigned int    /* modifiers */,
    XDevice*        /* modifier_dev */,
    Window          /* grab_window */
);

extern int     XGrabDeviceButton(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned int    /* button */,
    unsigned int    /* modifiers */,
    XDevice*        /* modifier_device */,
    Window          /* grab_window */,
    Bool       /* owner_events */,
    unsigned int    /* event_count */,
    XEventClass*    /* event_list */,
    int             /* this_device_mode */,
    int             /* other_devices_mode */
);

extern int     XUngrabDeviceButton(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned int    /* button */,
    unsigned int    /* modifiers */,
    XDevice*        /* modifier_dev */,
    Window          /* grab_window */
);

extern int     XAllowDeviceEvents(
    Display*        /* display */,
    XDevice*        /* device */,
    int             /* event_mode */,
    Time       /* time */
);

extern int     XGetDeviceFocus(
    Display*        /* display */,
    XDevice*        /* device */,
    Window*         /* focus */,
    int*       /* revert_to */,
    Time*      /* time */
);

extern int     XSetDeviceFocus(
    Display*        /* display */,
    XDevice*        /* device */,
    Window          /* focus */,
    int             /* revert_to */,
    Time       /* time */
);

extern XFeedbackState    *XGetFeedbackControl(
    Display*        /* display */,
    XDevice*        /* device */,
    int*       /* num_feedbacks */
);

extern void    XFreeFeedbackList(
    XFeedbackState* /* list */
);

extern int     XChangeFeedbackControl(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned long   /* mask */,
    XFeedbackControl*    /* f */
);

extern int     XDeviceBell(
    Display*        /* display */,
    XDevice*        /* device */,
    XID             /* feedbackclass */,
    XID             /* feedbackid */,
    int             /* percent */
);

extern KeySym  *XGetDeviceKeyMapping(
    Display*        /* display */,
    XDevice*        /* device */,
#if NeedWidePrototypes
    unsigned int    /* first */,
#else
    KeyCode         /* first */,
#endif
    int             /* keycount */,
    int*       /* syms_per_code */
);

extern int     XChangeDeviceKeyMapping(
    Display*        /* display */,
    XDevice*        /* device */,
    int             /* first */,
    int             /* syms_per_code */,
    KeySym*         /* keysyms */,
    int             /* count */
);

extern XModifierKeymap   *XGetDeviceModifierMapping(
    Display*        /* display */,
    XDevice*        /* device */
);

extern int     XSetDeviceModifierMapping(
    Display*        /* display */,
    XDevice*        /* device */,
    XModifierKeymap*     /* modmap */
);

extern int     XSetDeviceButtonMapping(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned char*  /* map[] */,
    int             /* nmap */
);

extern int     XGetDeviceButtonMapping(
    Display*        /* display */,
    XDevice*        /* device */,
    unsigned char*  /* map[] */,
    unsigned int    /* nmap */
);

extern XDeviceState *XQueryDeviceState(
    Display*        /* display */,
    XDevice*        /* device */
);

extern void    XFreeDeviceState(
    XDeviceState*   /* list */
);

extern XExtensionVersion *XGetExtensionVersion(
    Display*        /* display */,
    _Xconst char*   /* name */
);

extern XDeviceInfo  *XListInputDevices(
    Display*        /* display */,
    int*       /* ndevices */
);

extern void    XFreeDeviceList(
    XDeviceInfo*    /* list */
);

extern XDevice *XOpenDevice(
    Display*        /* display */,
    XID             /* id */
);

extern int     XCloseDevice(
    Display*        /* display */,
    XDevice*        /* device */
);

extern int     XSetDeviceMode(
    Display*        /* display */,
    XDevice*        /* device */,
    int             /* mode */
);

extern int     XSetDeviceValuators(
    Display*        /* display */,
    XDevice*        /* device */,
    int*       /* valuators */,
    int             /* first_valuator */,
    int             /* num_valuators */
);

extern XDeviceControl    *XGetDeviceControl(
    Display*        /* display */,
    XDevice*        /* device */,
    int             /* control */
);

extern int     XChangeDeviceControl(
    Display*        /* display */,
    XDevice*        /* device */,
    int             /* control */,
    XDeviceControl* /* d */
);

extern int     XSelectExtensionEvent(
    Display*        /* display */,
    Window          /* w */,
    XEventClass*    /* event_list */,
    int             /* count */
);

extern int XGetSelectedExtensionEvents(
    Display*        /* display */,
    Window          /* w */,
    int*       /* this_client_count */,
    XEventClass**   /* this_client_list */,
    int*       /* all_clients_count */,
    XEventClass**   /* all_clients_list */
);

extern int     XChangeDeviceDontPropagateList(
    Display*        /* display */,
    Window          /* window */,
    int             /* count */,
    XEventClass*    /* events */,
    int             /* mode */
);

extern XEventClass  *XGetDeviceDontPropagateList(
    Display*        /* display */,
    Window          /* window */,
    int*       /* count */
);

extern Status  XSendExtensionEvent(
    Display*        /* display */,
    XDevice*        /* device */,
    Window          /* dest */,
    Bool       /* prop */,
    int             /* count */,
    XEventClass*    /* list */,
    XEvent*         /* event */
);

extern XDeviceTimeCoord  *XGetDeviceMotionEvents(
    Display*        /* display */,
    XDevice*        /* device */,
    Time       /* start */,
    Time       /* stop */,
    int*       /* nEvents */,
    int*       /* mode */,
    int*       /* axis_count */
);

extern void    XFreeDeviceMotionEvents(
    XDeviceTimeCoord*    /* events */
);

extern void    XFreeDeviceControl(
    XDeviceControl* /* control */
);

extern void _xibaddevice(Display *dpy, int *error);
extern void _xibadclass(Display *dpy, int *error);
extern void _xibadevent(Display *dpy, int *error);
extern void _xibadmode(Display *dpy, int *error);
extern void _xidevicebusy(Display *dpy, int *error);


_XFUNCPROTOEND

#endif /* _XINPUT_H_ */

/************************************************************

Copyright 1989, 1998  The Open Group

Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation.

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
OPEN GROUP 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 Open Group 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 Open Group.

Copyright 1989 by Hewlett-Packard Company, Palo Alto, California.

               All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Hewlett-Packard not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.

HEWLETT-PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
HEWLETT-PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

********************************************************/
/* $XFree86: xc/doc/specs/Xi/library.ms,v 1.3 2006/01/09 14:56:34 dawes Exp $ */

/* Definitions used by the server, library and client */

#ifndef _XI_H_

#define _XI_H_

#define sz_xGetExtensionVersionReq      8
#define sz_xGetExtensionVersionReply         32
#define sz_xListInputDevicesReq              4
#define sz_xListInputDevicesReply       32
#define sz_xOpenDeviceReq               8
#define sz_xOpenDeviceReply             32
#define sz_xCloseDeviceReq              8
#define sz_xSetDeviceModeReq            8
#define sz_xSetDeviceModeReply               32
#define sz_xSelectExtensionEventReq          12
#define sz_xGetSelectedExtensionEventsReq    8
#define sz_xGetSelectedExtensionEventsReply  32
#define sz_xChangeDeviceDontPropagateListReq 12
#define sz_xGetDeviceDontPropagateListReq    8
#define sz_xGetDeviceDontPropagateListReply  32
#define sz_xGetDeviceMotionEventsReq         16
#define sz_xGetDeviceMotionEventsReply       32
#define sz_xChangeKeyboardDeviceReq          8
#define sz_xChangeKeyboardDeviceReply        32
#define sz_xChangePointerDeviceReq      8
#define sz_xChangePointerDeviceReply         32
#define sz_xGrabDeviceReq               20
#define sz_xGrabDeviceReply             32
#define sz_xUngrabDeviceReq             12
#define sz_xGrabDeviceKeyReq            20
#define sz_xGrabDeviceKeyReply               32
#define sz_xUngrabDeviceKeyReq               16
#define sz_xGrabDeviceButtonReq              20
#define sz_xGrabDeviceButtonReply       32
#define sz_xUngrabDeviceButtonReq       16
#define sz_xAllowDeviceEventsReq        12
#define sz_xGetDeviceFocusReq           8
#define sz_xGetDeviceFocusReply              32
#define sz_xSetDeviceFocusReq           16
#define sz_xGetFeedbackControlReq       8
#define sz_xGetFeedbackControlReply          32
#define sz_xChangeFeedbackControlReq         12
#define sz_xGetDeviceKeyMappingReq      8
#define sz_xGetDeviceKeyMappingReply         32
#define sz_xChangeDeviceKeyMappingReq        8
#define sz_xGetDeviceModifierMappingReq      8
#define sz_xSetDeviceModifierMappingReq      8
#define sz_xSetDeviceModifierMappingReply    32
#define sz_xGetDeviceButtonMappingReq        8
#define sz_xGetDeviceButtonMappingReply      32
#define sz_xSetDeviceButtonMappingReq        8
#define sz_xSetDeviceButtonMappingReply      32
#define sz_xQueryDeviceStateReq              8
#define sz_xQueryDeviceStateReply       32
#define sz_xSendExtensionEventReq       16
#define sz_xDeviceBellReq               8
#define sz_xSetDeviceValuatorsReq       8
#define sz_xSetDeviceValuatorsReply          32
#define sz_xGetDeviceControlReq              8
#define sz_xGetDeviceControlReply       32
#define sz_xChangeDeviceControlReq      8
#define sz_xChangeDeviceControlReply         32

#define INAME            "XInputExtension"

#define XI_KEYBOARD "KEYBOARD"
#define XI_MOUSE    "MOUSE"
#define XI_TABLET   "TABLET"
#define XI_TOUCHSCREEN   "TOUCHSCREEN"
#define XI_TOUCHPAD "TOUCHPAD"
#define XI_BARCODE  "BARCODE"
#define XI_BUTTONBOX     "BUTTONBOX"
#define XI_KNOB_BOX "KNOB_BOX"
#define XI_ONE_KNOB "ONE_KNOB"
#define XI_NINE_KNOB     "NINE_KNOB"
#define XI_TRACKBALL     "TRACKBALL"
#define XI_QUADRATURE    "QUADRATURE"
#define XI_ID_MODULE     "ID_MODULE"
#define XI_SPACEBALL     "SPACEBALL"
#define XI_DATAGLOVE     "DATAGLOVE"
#define XI_EYETRACKER    "EYETRACKER"
#define XI_CURSORKEYS    "CURSORKEYS"
#define XI_FOOTMOUSE     "FOOTMOUSE"

#define Dont_Check            0
#define XInput_Initial_Release          1
#define XInput_Add_XDeviceBell          2
#define XInput_Add_XSetDeviceValuators  3
#define XInput_Add_XChangeDeviceControl 4

#define XI_Absent        0
#define XI_Present       1

#define XI_Initial_Release_Major        1
#define XI_Initial_Release_Minor        0

#define XI_Add_XDeviceBell_Major        1
#define XI_Add_XDeviceBell_Minor        1

#define XI_Add_XSetDeviceValuators_Major     1
#define XI_Add_XSetDeviceValuators_Minor     2

#define XI_Add_XChangeDeviceControl_Major    1
#define XI_Add_XChangeDeviceControl_Minor    3

#define DEVICE_RESOLUTION     1

#define NoSuchExtension       1

#define COUNT            0
#define CREATE           1

#define NewPointer       0
#define NewKeyboard      1

#define XPOINTER         0
#define XKEYBOARD        1

#define UseXKeyboard          0xFF

#define IsXPointer       0
#define IsXKeyboard      1
#define IsXExtensionDevice    2

#define AsyncThisDevice       0
#define SyncThisDevice        1
#define ReplayThisDevice 2
#define AsyncOtherDevices     3
#define AsyncAll         4
#define SyncAll               5

#define FollowKeyboard        3
#ifndef RevertToFollowKeyboard
#define RevertToFollowKeyboard     3
#endif

#define DvAccelNum              (1L << 0)
#define DvAccelDenom            (1L << 1)
#define DvThreshold             (1L << 2)

#define DvKeyClickPercent     (1L<<0)
#define DvPercent        (1L<<1)
#define DvPitch               (1L<<2)
#define DvDuration       (1L<<3)
#define DvLed            (1L<<4)
#define DvLedMode        (1L<<5)
#define DvKey            (1L<<6)
#define DvAutoRepeatMode (1L<<7)

#define DvString                (1L << 0)

#define DvInteger               (1L << 0)

#define DeviceMode              (1L << 0)
#define Relative                0
#define Absolute                1
/* Merged from Metrolink tree for XINPUT stuff    */
#define TS_Raw                     57
#define TS_Scaled                  58
#define SendCoreEvents             59
#define DontSendCoreEvents         60
/* End of merged section */

#define ProximityState          (1L << 1)
#define InProximity             (0L << 1)
#define OutOfProximity          (1L << 1)

#define AddToList               0
#define DeleteFromList          1

#define KeyClass         0
#define ButtonClass           1
#define ValuatorClass         2
#define FeedbackClass         3
#define ProximityClass   4
#define FocusClass            5
#define OtherClass            6

#define KbdFeedbackClass      0
#define PtrFeedbackClass      1
#define StringFeedbackClass   2
#define IntegerFeedbackClass       3
#define LedFeedbackClass      4
#define BellFeedbackClass     5

#define _devicePointerMotionHint 0
#define _deviceButton1Motion   1
#define _deviceButton2Motion   2
#define _deviceButton3Motion   3
#define _deviceButton4Motion   4
#define _deviceButton5Motion   5
#define _deviceButtonMotion    6
#define _deviceButtonGrab      7
#define _deviceOwnerGrabButton      8
#define _noExtensionEvent      9

#define XI_BadDevice     0
#define XI_BadEvent 1
#define XI_BadMode  2
#define XI_DeviceBusy    3
#define XI_BadClass 4

/* Make XEventClass be a CARD32 for 64 bit servers.  Don’t affect client
 * definition of XEventClass since that would be a library interface change.
 * See the top of X.h for more _XSERVER64 magic.
 */
#ifdef _XSERVER64
typedef   CARD32         XEventClass;
#else
typedef   unsigned long  XEventClass;
#endif

/*******************************************************************
 *
 * Extension version structure.
 *
 */

typedef struct {
        int    present;
        short  major_version;
        short  minor_version;
} XExtensionVersion;

#endif /* _XI_H_ */                              2

Table of Contents




1. Input Extension Overview


 . . . . . . . . . . . . . . 

1




1.1. Design Approach


 . . . . . . . . . . . . . . . . . . 

1




1.2. Core Input Devices


 . . . . . . . . . . . . . . . . 

1




1.3. Extension Input Devices


 . . . . . . . . . . . . . . 

1




1.3.1. Input Device Classes


 . . . . . . . . . . . . . . 

1




1.4. Using Extension Input Devices


 . . . . . . . . . . . 

1




2. Library Extension Requests


 . . . . . . . . . . . . . 

1




2.1. Window Manager Functions


 . . . . . . . . . . . . . 

1




2.1.1. Changing the Core Devices


 . . . . . . . . . . . . 

1




2.1.2. Event Synchronization and Core Grabs


 . . . . . . 

1




2.1.3. Extension Active Grabs


 . . . . . . . . . . . . . 

1




2.1.4. Passively Grabbing a Key


 . . . . . . . . . . . . 

1




2.1.5. Passively Grabbing a Button


 . . . . . . . . . . . 

1




2.1.6. Thawing a Device


 . . . . . . . . . . . . . . . . 

1




2.1.7. Controlling Device Focus


 . . . . . . . . . . . . 

1




2.1.8. Controlling Device Feedback


 . . . . . . . . . . . 

1




2.1.9. Ringing a Bell on an Input Device


 . . . . . . . . 

1




2.1.10. Controlling Device Encoding


 . . . . . . . . . . 

1




2.1.11. Controlling Button Mapping


 . . . . . . . . . . . 

1




2.1.12. Obtaining the State of a Device


 . . . . . . . . 

1




2.2. Events


 . . . . . . . . . . . . . . . . . . . . . .


1




2.2.1. Event Types


 . . . . . . . . . . . . . . . . . . . 

1




2.2.2. Event Classes


 . . . . . . . . . . . . . . . . . . 

1




2.2.3. Event Structures


 . . . . . . . . . . . . . . . . 

1




2.2.3.1. Device Key Events


 . . . . . . . . . . . . . . . 

1




2.2.3.2. Device Button Events


 . . . . . . . . . . . . . 

1




2.2.3.3. Device Motion Events


 . . . . . . . . . . . . . 

1




2.2.3.4. Device Focus Events


 . . . . . . . . . . . . . . 

1




2.2.3.5. Device StateNotify Event


 . . . . . . . . . . . 

1




2.2.3.6. Device Mapping Event


 . . . . . . . . . . . . . 

1




2.2.3.7. ChangeDeviceNotify Event


 . . . . . . . . . . . 

1




2.2.3.8. Proximity Events


 . . . . . . . . . . . . . . . 

1




2.3. Event Handling Functions


 . . . . . . . . . . . . . 

1




2.3.1. Determining the Extension Version


 . . . . . . . . 

1




2.3.2. Listing Available Devices


 . . . . . . . . . . . . 

1




2.3.3. Enabling and Disabling Extension
Devices 


 . . . . 

1




2.3.4. Changing the Mode of a Device


 . . . . . . . . . . 

1




2.3.5. Initializing Valuators on an Input
Device 


 . . . . 

1




2.3.6. Getting Input Device Controls


 . . . . . . . . . . 

1




2.3.7. Changing Input Device Controls


 . . . . . . . . . 

1




2.3.8. Selecting Extension Device Events


 . . . . . . . . 

1




2.3.9. Determining Selected Device Events


 . . . . . . . 

1




2.3.10. Controlling Event Propagation


 . . . . . . . . . 

1




2.3.11. Sending an Event


 . . . . . . . . . . . . . . . . 

1




2.3.12. Getting Motion History


 . . . . . . . . . . . . . 

1




2.3.12. Appendix A


 . . . . . . . . . . . . . . . . . . . 

2
 
i