1 X11 Input Extension Protocol Specification
4 X Version 11, Release 6.8
5 Mark Patrick, Ardent Computer
6 George Sachs, Hewlett-Packard
11 Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and
14 Permission to use, copy, modify, and distribute this
15 documentation for any purpose and without fee is hereby
16 granted, provided that the above copyright notice and this
17 permission notice appear in all copies. Ardent and
18 Hewlett-Packard make no representations about the suitability
19 for any purpose of the information in this document. It is
20 provided "as is" without express or implied warranty. Copyright
21 © 1989, 1990, 1991, 1992 X Consortium
23 Permission is hereby granted, free of charge, to any person
24 obtaining a copy of this software and associated documentation
25 files (the “Software”), to deal in the Software without
26 restriction, including without limitation the rights to use,
27 copy, modify, merge, publish, distribute, sublicense, and/or
28 sell copies of the Software, and to permit persons to whom the
29 Software is furnished to do so, subject to the following
32 The above copyright notice and this permission notice shall be
33 included in all copies or substantial portions of the Software.
35 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
36 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
37 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
38 NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE
39 FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
40 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
41 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
44 Except as contained in this notice, the name of the X
45 Consortium shall not be used in advertising or otherwise to
46 promote the sale, use or other dealings in this Software
47 without prior written authorization from the X Consortium. X
48 Window System is a trademark of The Open Group.
50 Copyright © 2008 by Peter Hutterer
52 Permission is hereby granted, free of charge, to any person
53 obtaining a copy of this software and associated documentation
54 files (the "Software"), to deal in the Software without
55 restriction, including without limitation the rights to use,
56 copy, modify, merge, publish, distribute, sublicense, and/or
57 sell copies of the Software, and to permit persons to whom the
58 Software is furnished to do so, subject to the following
61 The above copyright notice and this permission notice
62 (including the next paragraph) shall be included in all copies
63 or substantial portions of the Software.
65 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
66 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
67 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
68 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
69 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
70 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
71 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
72 OTHER DEALINGS IN THE SOFTWARE.
74 1. Input Extension Overview
76 This document defines an extension to the X11 protocol to
77 support input devices other than the core X keyboard and
78 pointer. An accompanying document defines a corresponding
79 extension to Xlib (similar extensions for languages other than
80 C are anticipated). This first section gives an overview of the
81 input extension. The next section defines the new protocol
82 requests defined by the extension. We conclude with a
83 description of the new input events generated by the additional
86 This document only describes the behaviour of servers supporting
87 up to the X Input Extension 1.5. For servers supporting the X
88 Input Extensions 2.0, see XI2proto.txt. New clients are discouraged
89 from using this protocol specification. Instead, the use of XI 2.x
94 The design approach of the extension is to define requests and
95 events analogous to the core requests and events. This allows
96 extension input devices to be individually distinguishable from
97 each other and from the core input devices. These requests and
98 events make use of a device identifier and support the
99 reporting of n-dimensional motion data as well as other data
100 that is not reportable via the core input events.
102 1.2 Core Input Devices
104 The X server core protocol supports two input devices: a
105 pointer and a keyboard. The pointer device has two major
106 functions. First, it may be used to generate motion information
107 that client programs can detect. Second, it may also be used to
108 indicate the current location and focus of the X keyboard. To
109 accomplish this, the server echoes a cursor at the current
110 position of the X pointer. Unless the X keyboard has been
111 explicitly focused, this cursor also shows the current location
112 and focus of the X keyboard. The X keyboard is used to generate
113 input that client programs can detect.
115 In servers supporting XI 1.4 and above, the core pointer and
116 the core keyboard are virtual devices that do not represent a
117 physical device connected to the host computer.
118 In servers supporting XI 2.0 and above, there may be multiple
119 core pointers and keyboards. Refer to XI2proto.txt for more
122 The X keyboard and X pointer are referred to in this document
123 as the core devices, and the input events they generate
124 (KeyPress, KeyRelease, ButtonPress, ButtonRelease, and
125 MotionNotify) are known as the core input events. All other
126 input devices are referred to as extension input devices and
127 the input events they generate are referred to as extension
130 In servers supporting only XI 1.x, this input extension does
131 not change the behavior or functionality of the core input
132 devices, core events, or core protocol requests, with the
133 exception of the core grab requests. These requests may affect
134 the synchronization of events from extension devices. See the
135 explanation in the section titled "Event Synchronization and
138 Selection of the physical devices to be initially used by the
139 server as the core devices is left implementation-dependent.
140 Requests are defined that allow client programs to change which
141 physical devices are used as the core devices.
143 1.3 Extension Input Devices
145 The input extension v1.x controls access to input devices other
146 than the X keyboard and X pointer. It allows client programs to
147 select input from these devices independently from each other
148 and independently from the core devices.
150 A client that wishes to access a specific device must first
151 determine whether that device is connected to the X server.
152 This is done through the ListInputDevices request, which will
153 return a list of all devices that can be opened by the X
154 server. A client can then open one or more of these devices
155 using the OpenDevice request, specify what events they are
156 interested in receiving, and receive and process input events
157 from extension devices in the same way as events from the X
158 keyboard and X pointer. Input events from these devices are of
159 extension types ( DeviceKeyPress, DeviceKeyRelease,
160 DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify,
161 etc.) and contain a device identifier so that events of the
162 same type coming from different input devices can be
165 Any kind of input device may be used as an extension input
166 device. Extension input devices may have 0 or more keys, 0 or
167 more buttons, and may report 0 or more axes of motion. Motion
168 may be reported as relative movements from a previous position
169 or as an absolute position. All valuators reporting motion
170 information for a given extension input device must report the
171 same kind of motion information (absolute or relative).
173 This extension is designed to accommodate new types of input
174 devices that may be added in the future. The protocol requests
175 that refer to specific characteristics of input devices
176 organize that information by input classes. Server implementors
177 may add new classes of input devices without changing the
178 protocol requests. Input classes are unique numbers registered
179 with the X Consortium. Each extension input device may support
180 multiple input classes.
182 In XI 1.x, all extension input devices are treated like the
183 core X keyboard in determining their location and focus. The
184 server does not track the location of these devices on an
185 individual basis, and therefore does not echo a cursor to
186 indicate their current location. Instead, their location is
187 determined by the location of the core X pointer. Like the core
188 X keyboard, some may be explicitly focused. If they are not
189 explicitly focused, their focus is determined by the location
190 of the core X pointer.
192 Most input events reported by the server to a client are of
193 fixed size (32 bytes). In order to represent the change in
194 state of an input device the extension may need to generate a
195 sequence of input events. A client side library (such as Xlib)
196 will typically take these raw input events and format them into
197 a form more convenient to the client.
201 In the core protocol a client registers interest in receiving
202 certain input events directed to a window by modifying that
203 window's event-mask. Most of the bits in the event mask are
204 already used to specify interest in core X events. The input
205 extension specifies a different mechanism by which a client can
206 express interest in events generated by this extension.
208 When a client opens a extension input device via the OpenDevice
209 request, an XDevice structure is returned. Macros are provided
210 that extract 32-bit numbers called event classes from that
211 structure, that a client can use to register interest in
212 extension events via the SelectExtensionEvent request. The
213 event class combines the desired event type and device id, and
214 may be thought of as the equivalent of core event masks.
218 Some of the input extension requests divide input devices into
219 classes based on their functionality. This is intended to allow
220 new classes of input devices to be defined at a later time
221 without changing the semantics of these requests. The following
222 input device classes are currently defined:
225 The device reports key events.
228 The device reports button events.
231 The device reports valuator data in motion events.
234 The device reports proximity events.
237 The device can be focused and reports focus events.
240 The device supports feedbacks.
243 The ChangeDeviceNotify, DeviceMappingNotify, and
244 DeviceStateNotify macros may be invoked passing the
245 XDevice structure returned for this device.
247 Each extension input device may support multiple input classes.
248 Additional classes may be added in the future. Requests that
249 support multiple input classes, such as the ListInputDevices
250 function that lists all available input devices, organize the
251 data they return by input class. Client programs that use these
252 requests should not access data unless it matches a class
253 defined at the time those clients were compiled. In this way,
254 new classes can be added without forcing existing clients that
255 use these requests to be recompiled.
259 Extension input devices are accessed by client programs through
260 the use of new protocol requests. This section summarizes the
261 new requests defined by this extension. The syntax and type
262 definitions used below follow the notation used for the X11
265 2.1 Getting the Extension Version
267 The GetExtensionVersion request returns version information
268 about the input extension.
274 protocol-major-version: CARD16
275 protocol-minor-version: CARD16
277 The protocol version numbers returned indicate the version of
278 the input extension supported by the target X server. The
279 version numbers can be compared to constants defined in the
280 header file XI.h. Each version is a superset of the previous
283 The name must be the name of the Input Extension as defined
284 in the header file XI.h.
286 2.2 Listing Available Devices
288 A client that wishes to access a specific device must first
289 determine whether that device is connected to the X server.
290 This is done through the ListInputDevices request, which will
291 return a list of all devices that can be opened by the X
296 input-devices: ListOfDeviceInfo
304 use: {IsXKeyboard, IsXPointer, IsXExtensionPointer,
305 IsXExtensionKeyboard, IsExtensionDevice}
306 info: LISTofINPUTINFO
309 INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO}
324 mode: SETofDEVICEMODE
325 motion_buffer_size: CARD32
326 axes: LISTofAXISINFO]
332 DEVICEMODE: {Absolute, Relative}
336 This request returns a list of all devices that can be opened
337 by the X server, including the core X keyboard and X pointer.
338 Some implementations may open all input devices as part of X
339 initialization, while others may not open an input device until
340 requested to do so by a client program.
342 The information returned for each device is as follows:
345 The type field is of type Atom and indicates the nature
346 of the device. Clients may determine device types by
347 invoking the XInternAtom request passing one of the
348 names defined in the header file XI.h. The following
349 names have been defined to date:
373 The id is a small cardinal value in the range 0-128 that
374 uniquely identifies the device. It is assigned to the
375 device when it is initialized by the server. Some
376 implementations may not open an input device until
377 requested by a client program, and may close the device
378 when the last client accessing it requests that it be
379 closed. If a device is opened by a client program via
380 XOpenDevice, then closed via XCloseDevice, then opened
381 again, it is not guaranteed to have the same id after
382 the second open request.
385 The num_classes field is a small cardinal value in the
386 range 0-255 that specifies the number of input classes
387 supported by the device for which information is
388 returned by ListInputDevices. Some input classes, such
389 as class Focus and class Proximity do not have any
390 information to be returned by ListInputDevices.
393 The use field specifies how the device is currently
394 being used. If the value is IsXKeyboard, the device is
395 currently being used as the X keyboard. If the value is
396 IsXPointer, the device is currently being used as the X
397 pointer. If the value is IsXExtensionPointer, the device
398 is available for use as an extension pointer. If the value
399 is IsXExtensionKeyboard, the device is available for use as
400 and extension keyboard.
401 Older versions of XI report all extension devices as
405 The name field contains a pointer to a null-terminated
406 string that corresponds to one of the defined device
410 InputInfo is one of: KeyInfo, ButtonInfo or
411 ValuatorInfo. The first two fields are common to all
415 The class field is a cardinal value in the range
416 0-255. It uniquely identifies the class of input
417 for which information is returned.
420 The length field is a cardinal value in the range
421 0-255. It specifies the number of bytes of data
422 that are contained in this input class. The length
423 includes the class and length fields.
425 The remaining information returned for input class
426 KEYCLASS is as follows:
429 min_keycode is of type KEYCODE. It specifies the
430 minimum keycode that the device will report. The
431 minimum keycode will not be smaller than 8.
434 max_keycode is of type KEYCODE. It specifies the
435 maximum keycode that the device will report. The
436 maximum keycode will not be larger than 255.
439 num_keys is a cardinal value that specifies the
440 number of keys that the device has.
442 The remaining information returned for input class
443 BUTTONCLASS is as follows:
446 num_buttons is a cardinal value that specifies the
447 number of buttons that the device has.
449 The remaining information returned for input class
450 VALUATORCLASS is as follows:
453 mode is a constant that has one of the following
454 values: Absolute or Relative. Some devices allow
455 the mode to be changed dynamically via the
456 SetDeviceMode request.
459 motion_buffer_size is a cardinal number that
460 specifies the number of elements that can be
461 contained in the motion history buffer for the
465 The axes field contains a pointer to an AXISINFO
468 The information returned for each axis reported by the
472 The resolution is a cardinal value in
476 The min_val field is a cardinal value in that
477 contains the minimum value the device reports for
478 this axis. For devices whose mode is Relative, the
479 min_val field will contain 0.
482 The max_val field is a cardinal value in that
483 contains the maximum value the device reports for
484 this axis. For devices whose mode is Relative, the
485 max_val field will contain 0.
489 Client programs that wish to access an extension device must
490 request that the server open that device. This is done via the
499 classes: LISTofINPUTCLASSINFO]
502 event_type_base: CARD8]
506 This request returns the event classes to be used by the client
507 to indicate which events the client program wishes to receive.
508 Each input class may report several event classes. For example,
509 input class Keys reports DeviceKeyPress and DeviceKeyRelease
510 event classes. Input classes are unique numbers registered with
511 the X Consortium. Input class Other exists to report event
512 classes that are not specific to any one input class, such as
513 DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify.
515 The information returned for each device is as follows:
518 The device_id is a number that uniquely identifies the
522 The num_classes field contains the number of input
523 classes supported by this device.
525 For each class of input supported by the device, the
526 InputClassInfo structure contains the following information:
529 The input_class is a small cardinal number that
530 identifies the class of input.
533 The event_type_base is a small cardinal number that
534 specifies the event type of one of the events reported
535 by this input class. This information is not directly
536 used by client programs. Instead, the Device is used by
537 macros that return extension event types and event
538 classes. This is described in the section of this
539 document entitled "Selecting Extension Device Events".
541 The information in the InputClassInfo reflects the state of
542 this device at the time the request was processed.
544 Before it exits, the client program should explicitly request
545 that the server close the device. This is done via the
548 A client may open the same extension device more than once.
549 Requests after the first successful one return an additional
550 XDevice structure with the same information as the first, but
551 otherwise have no effect. A single CloseDevice request will
552 terminate that client's access to the device.
554 Closing a device releases any active or passive grabs the
555 requesting client has established. If the device is frozen only
556 by an active grab of the requesting client, the queued events
557 are released when the client terminates.
559 If a client program terminates without closing a device, the
560 server will automatically close that device on behalf of the
561 client. This does not affect any other clients that may be
562 accessing that device.
569 2.4 Changing The Mode Of A Device
571 Some devices are capable of reporting either relative or
572 absolute motion data. To change the mode of a device from
573 relative to absolute, use the SetDeviceMode request. The valid
574 values are Absolute or Relative.
576 This request will fail and return DeviceBusy if another client
577 already has the device open with a different mode. It will fail
578 and return AlreadyGrabbed if another client has the device
579 grabbed. The request will fail with a BadMatch error if the
580 device has no valuators and reports no axes of motion. The
581 request will fail with a BadMode error if the requested mode
582 is not supported by the device.
586 mode: {Absolute, Relative}
588 status: {Success, DeviceBusy, AlreadyGrabbed}
590 Errors: Device, Match, Mode
592 2.5 Initializing Valuators on an Input Device
594 Some devices that report absolute positional data can be
595 initialized to a starting value. Devices that are capable of
596 reporting relative motion or absolute positional data may
597 require that their valuators be initialized to a starting value
598 after the mode of the device is changed to Absolute. To
599 initialize the valuators on such a device, use the
600 SetDeviceValuators request.
604 first_valuator: CARD8
606 valuators: LISTOFINT32
608 status: {Success, AlreadyGrabbed}
610 Errors: Length, Device, Match, Value
612 This request initializes the specified valuators on the
613 specified extension input device. Valuators are numbered
614 beginning with zero. Only the valuators in the range specified
615 by first_valuator and num_valuators are set. If the number of
616 valuators supported by the device is less than the expression
617 first_valuator + num_valuators, a Value error will result.
619 If the request succeeds, Success is returned. If the specifed
620 device is grabbed by some other client, the request will fail
621 and a status of AlreadyGrabbed will be returned.
623 2.6 Getting Input Device Controls
629 controlState: {DeviceState}
633 DeviceState: DeviceResolutionState
635 Errors: Length, Device, Match, Value
637 This request returns the current state of the specified device
638 control. The device control must be supported by the target
639 server and device or an error will result.
641 If the request is successful, a pointer to a generic
642 DeviceState structure will be returned. The information
643 returned varies according to the specified control and is
644 mapped by a structure appropriate for that control.
646 GetDeviceControl will fail with a BadValue error if the server
647 does not support the specified control. It will fail with a
648 BadMatch error if the device does not support the specified
651 Supported device controls and the information returned for them
658 resolutions: LISTofCARD32
659 min_resolutions: LISTofCARD32
660 max_resolutions: LISTofCARD32]
662 This device control returns a list of valuators and the range
663 of valid resolutions allowed for each. Valuators are numbered
664 beginning with 0. Resolutions for all valuators on the device
665 are returned. For each valuator i on the device, resolutions[i]
666 returns the current setting of the resolution,
667 min_resolutions[i] returns the minimum valid setting, and
668 max_resolutions[i] returns the maximum valid setting.
670 When this control is specified, XGetDeviceControl will fail
671 with a BadMatch error if the specified device has no valuators.
676 control: DeviceControl
680 DeviceControl: DeviceResolutionControl
682 status: {Success, DeviceBusy, AlreadyGrabbed}
684 Errors: Length, Device, Match, Value
686 ChangeDeviceControl changes the specifed device control
687 according to the values specified in the DeviceControl
688 structure. The device control must be supported by the target
689 server and device or an error will result.
691 The information passed with this request varies according to
692 the specified control and is mapped by a structure appropriate
695 ChangeDeviceControl will fail with a BadValue error if the
696 server does not support the specified control. It will fail
697 with a BadMatch error if the server supports the specified
698 control, but the requested device does not. The request will
699 fail and return a status of DeviceBusy if another client
700 already has the device open with a device control state that
701 conflicts with the one specified in the request. It will fail
702 with a status of AlreadyGrabbed if some other client has
703 grabbed the specified device. If the request succeeds, Success
704 is returned. If it fails, the device control is left unchanged.
706 Supported device controls and the information specified for
712 first_valuator: CARD8
714 resolutions: LISTofCARD32]
716 This device control changes the resolution of the specified
717 valuators on the specified extension input device. Valuators
718 are numbered beginning with zero. Only the valuators in the
719 range specified by first_valuator and num_valuators are set. A
720 value of -1 in the resolutions list indicates that the
721 resolution for this valuator is not to be changed.
722 num_valuators specifies the number of valuators in the
725 When this control is specified, XChangeDeviceControl will fail
726 with a BadMatch error if the specified device has no valuators.
727 If a resolution is specified that is not within the range of
728 valid values (as returned by XGetDeviceControl) the request
729 will fail with a BadValue error. If the number of valuators
730 supported by the device is less than the expression
731 first_valuator + num_valuators, a BadValue error will result.
733 If the request fails for any reason, none of the valuator
734 resolutions will be changed.
736 ChangeDeviceControl causes the server to send a DevicePresence
737 event to interested clients.
739 2.7 Selecting Extension Device Events
741 Extension input events are selected using the
742 SelectExtensionEvent request.
745 interest: LISTofEVENTCLASS
748 Errors: Window, Class, Access
750 This request specifies to the server the events within the
751 specified window which are of interest to the client. As with
752 the core XSelectInput function, multiple clients can select
753 input on the same window.
755 XSelectExtensionEvent requires a list of event classes. An
756 event class is a 32-bit number that combines an event type and
757 device id, and is used to indicate which event a client wishes
758 to receive and from which device it wishes to receive it.
759 Macros are provided to obtain event classes from the data
760 returned by the XOpenDevice request. The names of these macros
761 correspond to the desired events, i.e. the DeviceKeyPress is
762 used to obtain the event class for DeviceKeyPress events. The
763 syntax of the macro invocation is:
764 DeviceKeyPress (device, event_type, event_class);
769 The value returned in event_type is the value that will be
770 contained in the event type field of the XDeviceKeyPressEvent
771 when it is received by the client. The value returned in
772 event_class is the value that should be passed in making an
773 XSelectExtensionEvent request to receive DeviceKeyPress events.
775 For DeviceButtonPress events, the client may specify whether or
776 not an implicit passive grab should be done when the button is
777 pressed. If the client wants to guarantee that it will receive
778 a DeviceButtonRelease event for each DeviceButtonPress event it
779 receives, it should specify the DeviceButtonPressGrab event
780 class as well as the DeviceButtonPress event class. This
781 restricts the client in that only one client at a time may
782 request DeviceButtonPress events from the same device and
783 window if any client specifies this class.
785 If any client has specified the DeviceButtonPressGrab class,
786 any requests by any other client that specify the same device
787 and window and specify DeviceButtonPress or
788 DeviceButtonPressGrab will cause an Access error to be
791 If only the DeviceButtonPress class is specified, no implicit
792 passive grab will be done when a button is pressed on the
793 device. Multiple clients may use this class to specify the same
794 device and window combination.
796 A client may also specify the DeviceOwnerGrabButton class. If
797 it has specified both the DeviceButtonPressGrab and the
798 DeviceOwnerGrabButton classes, implicit passive grabs will
799 activate with owner_events set to True. If only the
800 DeviceButtonPressGrab class is specified, implicit passive
801 grabs will activate with owner_events set to False.
803 The client may select DeviceMotion events only when a button is
804 down. It does this by specifying the event classes
805 Button1Motion through Button5Motion, or ButtonMotion. An input
806 device will only support as many button motion classes as it
809 2.8 Determining Selected Events
811 To determine which extension events are currently selected from
812 a given window, use GetSelectedExtensionEvents.
814 GetSelectedExtensionEvents
817 this-client: LISTofEVENTCLASS
818 all-clients: LISTofEVENTCLASS
822 This request returns two lists specifying the events selected
823 on the specified window. One list gives the extension events
824 selected by this client from the specified window. The other
825 list gives the extension events selected by all clients from
826 the specified window. This information is equivalent to that
827 returned by your-event-mask and all-event-masks in a
828 GetWindowAttributes request.
830 2.9 Controlling Event Propagation
832 Extension events propagate up the window hierarchy in the same
833 manner as core events. If a window is not interested in an
834 extension event, it usually propagates to the closest ancestor
835 that is interested, unless the dont_propagate list prohibits
836 it. Grabs of extension devices may alter the set of windows
837 that receive a particular extension event.
839 Client programs may control extension event propagation through
840 the use of the following two requests.
842 XChangeDeviceDontPropagateList adds an event to or deletes an
843 event from the do_not_propagate list of extension events for
844 the specified window. This list is maintained for the life of
845 the window, and is not altered if the client terminates.
847 ChangeDeviceDontPropagateList
849 eventclass: LISTofEVENTCLASS
850 mode: {AddToList, DeleteFromList}
852 Errors: Window, Class, Mode
854 This function modifies the list specifying the events that are
855 not propagated to the ancestors of the specified window. You
856 may use the modes AddToList or DeleteFromList.
858 GetDeviceDontPropagateList
862 dont-propagate-list: LISTofEVENTCLASS
864 This function returns a list specifying the events that are not
865 propagated to the ancestors of the specified window.
867 2.10 Sending Extension Events
869 One client program may send an event to another via the
870 XSendExtensionEvent function.
872 The event in the XEvent structure must be one of the events
873 defined by the input extension, so that the X server can
874 correctly byte swap the contents as necessary. The contents of
875 the event are otherwise unaltered and unchecked by the X server
876 except to force send_event to True in the forwarded event and
877 to set the sequence number in the event correctly.
879 XSendExtensionEvent returns zero if the conversion-to-wire
880 protocol failed, otherwise it returns nonzero.
886 eventclass: LISTofEVENTCLASS
889 Errors: Device, Value, Class, Window
891 2.11 Getting Motion History
893 GetDeviceMotionEvents
895 start, stop: TIMESTAMP or CurrentTime
897 nevents_return: CARD32
898 mode_return: {Absolute, Relative}
899 axis_count_return: CARD8
900 events: LISTofDEVICETIMECOORD
908 Errors: Device, Match
910 This request returns all positions in the device's motion
911 history buffer that fall between the specified start and stop
912 times inclusive. If the start time is in the future, or is
913 later than the stop time, no positions are returned.
915 The data field of the DEVICETIMECOORD structure is a sequence
916 of data items. Each item is of type INT32, and there is one
917 data item per axis of motion reported by the device. The number
918 of axes reported by the device is returned in the axis_count
921 The value of the data items depends on the mode of the device,
922 which is returned in the mode variable. If the mode is
923 Absolute, the data items are the raw values generated by the
924 device. These may be scaled by the client program using the
925 maximum values that the device can generate for each axis of
926 motion that it reports. The maximum and minimum values for each
927 axis are reported by the ListInputDevices request.
929 If the mode is Relative, the data items are the relative values
930 generated by the device. The client program must choose an
931 initial position for the device and maintain a current position
932 by accumulating these relative values.
934 2.12 Changing The Core Devices
936 These requests are provided to change which physical device is
937 used as the X pointer or X keyboard. These requests are
938 deprecated in servers supporting XI 1.4 and above, and will
939 always return a a BadDevice error.
941 Using these requests may change the characteristics of the core
942 devices. The new pointer device may have a different number of
943 buttons than the old one did, or the new keyboard device may
944 have a different number of keys or report a different range of
945 keycodes. Client programs may be running that depend on those
946 characteristics. For example, a client program could allocate
947 an array based on the number of buttons on the pointer device,
948 and then use the button numbers received in button events as
949 indicies into that array. Changing the core devices could cause
950 such client programs to behave improperly or abnormally
953 These requests change the X keyboard or X pointer device and
954 generate an ChangeDeviceNotify event and a MappingNotify event.
955 The ChangeDeviceNotify event is sent only to those clients that
956 have expressed an interest in receiving that event via the
957 XSelectExtensionEvent request. The specified device becomes the
958 new X keyboard or X pointer device. The location of the core
959 device does not change as a result of this request.
961 These requests fail and return AlreadyGrabbed if either the
962 specified device or the core device it would replace are
963 grabbed by some other client. They fail and return GrabFrozen
964 if either device is frozen by the active grab of another
967 These requests fail with a BadDevice error if the specified
968 device is invalid, or has not previously been opened via
969 OpenDevice. To change the X keyboard device, use the
970 ChangeKeyboardDevice request. The specified device must support
971 input class Keys (as reported in the ListInputDevices request)
972 or the request will fail with a BadMatch error. Once the device
973 has successfully replaced one of the core devices, it is
974 treated as a core device until it is in turn replaced by
975 another ChangeDevice request, or until the server terminates.
976 The termination of the client that changed the device will not
977 cause it to change back. Attempts to use the CloseDevice
978 request to close the new core device will fail with a BadDevice
981 The focus state of the new keyboard is the same as the focus
982 state of the old X keyboard. If the new keyboard was not
983 initialized with a FocusRec, one is added by the
984 ChangeKeyboardDevice request. The X keyboard is assumed to have
985 a KbdFeedbackClassRec. If the device was initialized without a
986 KbdFeedbackClassRec, one will be added by this request. The
987 KbdFeedbackClassRec will specify a null routine as the control
988 procedure and the bell procedure.
992 Errors: Device, Match
994 status: Success, AlreadyGrabbed, Frozen
996 To change the X pointer device, use the ChangePointerDevice
997 request. The specified device must support input class
998 Valuators (as reported in the ListInputDevices request) or the
999 request will fail with a BadMatch error. The valuators to be
1000 used as the x- and y-axes of the pointer device must be
1001 specified. Data from other valuators on the device will be
1004 The X pointer device does not contain a FocusRec. If the new
1005 pointer was initialized with a FocusRec, it is freed by the
1006 ChangePointerDevice request. The X pointer is assumed to have a
1007 ButtonClassRec and a PtrFeedbackClassRec. If the device was
1008 initialized without a ButtonClassRec or a PtrFeedbackClassRec,
1009 one will be added by this request. The ButtonClassRec added
1010 will have no buttons, and the PtrFeedbackClassRec will specify
1011 a null routine as the control procedure.
1013 If the specified device reports absolute positional
1014 information, and the server implementation does not allow such
1015 a device to be used as the X pointer, the request will fail
1016 with a BadDevice error.
1018 Once the device has successfully replaced one of the core
1019 devices, it is treated as a core device until it is in turn
1020 replaced by another ChangeDevice request, or until the server
1021 terminates. The termination of the client that changed the
1022 device will not cause it to change back. Attempts to use the
1023 CloseDevice request to close the new core device will fail with
1031 status: Success, AlreadyGrabbed, Frozen
1033 Errors: Device, Match
1035 2.12 Event Synchronization And Core Grabs
1037 Implementation of the input extension requires an extension of
1038 the meaning of event synchronization for the core grab
1039 requests. This is necessary in order to allow window managers
1040 to freeze all input devices with a single request.
1042 The core grab requests require a pointer_mode and keyboard_mode
1043 argument. The meaning of these modes is changed by the input
1044 extension. For the XGrabPointer and XGrabButton requests,
1045 pointer_mode controls synchronization of the pointer device,
1046 and keyboard_mode controls the synchronization of all other
1047 input devices. For the XGrabKeyboard and XGrabKey requests,
1048 pointer_mode controls the synchronization of all input devices
1049 except the X keyboard, while keyboard_mode controls the
1050 synchronization of the keyboard. When using one of the core
1051 grab requests, the synchronization of extension devices is
1052 controlled by the mode specified for the device not being
1055 2.13 Extension Active Grabs
1057 Active grabs of extension devices are supported via the
1058 GrabDevice request in the same way that core devices are
1059 grabbed using the core GrabKeyboard request, except that a
1060 Device is passed as a function parameter. A list of events that
1061 the client wishes to receive is also passed. The UngrabDevice
1062 request allows a previous active grab for an extension device
1065 To grab an extension device, use the GrabDevice request. The
1066 device must have previously been opened using the OpenDevice
1073 event-list: LISTofEVENTCLASS
1074 this-device-mode: {Synchronous, Asynchronous}
1075 other-device-mode: {Synchronous, Asynchronous}
1076 time:TIMESTAMP or CurrentTime
1078 status: Success, AlreadyGrabbed, Frozen,
1079 InvalidTime, NotViewable
1081 Errors: Device, Window, Value
1083 This request actively grabs control of the specified input
1084 device. Further input events from this device are reported only
1085 to the grabbing client. This request overrides any previous
1086 active grab by this client for this device.
1088 The event-list parameter is a pointer to a list of event
1089 classes. These are used to indicate which events the client
1090 wishes to receive while the device is grabbed. Only event
1091 classes obtained from the grabbed device are valid.
1093 If owner-events is False, input events generated from this
1094 device are reported with respect to grab-window, and are only
1095 reported if selected by being included in the event-list. If
1096 owner-events is True, then if a generated event would normally
1097 be reported to this client, it is reported normally, otherwise
1098 the event is reported with respect to the grab-window, and is
1099 only reported if selected by being included in the event-list.
1100 For either value of owner-events, unreported events are
1103 If this-device-mode is Asynchronous, device event processing
1104 continues normally. If the device is currently frozen by this
1105 client, then processing of device events is resumed. If
1106 this-device-mode is Synchronous, the state of the grabbed
1107 device (as seen by means of the protocol) appears to freeze,
1108 and no further device events are generated by the server until
1109 the grabbing client issues a releasing AllowDeviceEvents
1110 request or until the device grab is released. Actual device
1111 input events are not lost while the device is frozen; they are
1112 simply queued for later processing.
1114 If other-device-mode is Asynchronous, event processing is
1115 unaffected by activation of the grab. If other-device-mode is
1116 Synchronous, the state of all input devices except the grabbed
1117 one (as seen by means of the protocol) appears to freeze, and
1118 no further events are generated by the server until the
1119 grabbing client issues a releasing AllowDeviceEvents request or
1120 until the device grab is released. Actual events are not lost
1121 while the devices are frozen; they are simply queued for later
1124 This request generates DeviceFocusIn and DeviceFocusOut events.
1126 This request fails and returns:
1129 If the device is actively grabbed by some other client.
1132 If grab-window is not viewable.
1135 If the specified time is earlier than the last-grab-time
1136 for the specified device or later than the current X
1137 server time. Otherwise, the last-grab-time for the
1138 specified device is set to the specified time and
1139 CurrentTime is replaced by the current X server time.
1142 If the device is frozen by an active grab of another
1145 If a grabbed device is closed by a client while an active grab
1146 by that client is in effect, that active grab will be released.
1147 Any passive grabs established by that client will be released.
1148 If the device is frozen only by an active grab of the
1149 requesting client, it is thawed.
1151 To release a grab of an extension device, use UngrabDevice.
1155 time: TIMESTAMP or CurrentTime
1159 This request releases the device if this client has it actively
1160 grabbed (from either GrabDevice or GrabDeviceKey) and releases
1161 any queued events. If any devices were frozen by the grab,
1162 UngrabDevice thaws them. The request has no effect if the
1163 specified time is earlier than the last-device-grab time or is
1164 later than the current server time.
1166 This request generates DeviceFocusIn and DeviceFocusOut events.
1168 An UngrabDevice is performed automatically if the event window
1169 for an active device grab becomes not viewable.
1171 2.14 Passively Grabbing A Key
1173 Passive grabs of buttons and keys on extension devices are
1174 supported via the GrabDeviceButton and GrabDeviceKey requests.
1175 These passive grabs are released via the UngrabDeviceKey and
1176 UngrabDeviceButton requests.
1178 To passively grab a single key on an extension device, use
1179 GrabDeviceKey. That device must have previously been opened
1180 using the OpenDevice request.
1184 keycode: KEYCODE or AnyKey
1185 modifiers: SETofKEYMASK or AnyModifier
1186 modifier-device: DEVICE or NULL
1189 event-list: LISTofEVENTCLASS
1190 this-device-mode: {Synchronous, Asynchronous}
1191 other-device-mode: {Synchronous, Asynchronous}
1193 Errors: Device, Match, Access, Window, Value
1195 This request is analogous to the core GrabKey request. It
1196 establishes a passive grab on a device. Consequently, in the
1198 * IF the device is not grabbed and the specified key, which
1199 itself can be a modifier key, is logically pressed when the
1200 specified modifier keys logically are down on the specified
1201 modifier device (and no other keys are down),
1202 * AND no other modifier keys logically are down,
1203 * AND EITHER the grab window is an ancestor of (or is) the
1204 focus window OR the grab window is a descendent of the
1205 focus window and contains the pointer,
1206 * AND a passive grab on the same device and key combination
1207 does not exist on any ancestor of the grab window,
1208 * THEN the device is actively grabbed, as for GrabDevice, the
1209 last-device-grab time is set to the time at which the key
1210 was pressed (as transmitted in the DeviceKeyPress event),
1211 and the DeviceKeyPress event is reported.
1213 The interpretation of the remaining arguments is as for
1214 GrabDevice. The active grab is terminated automatically when
1215 logical state of the device has the specified key released
1216 (independent of the logical state of the modifier keys).
1218 Note that the logical state of a device (as seen by means of
1219 the X protocol) may lag the physical state if device event
1220 processing is frozen.
1222 A modifier of AnyModifier is equivalent to issuing the request
1223 for all possible modifier combinations (including the
1224 combination of no modifiers). It is not required that all
1225 modifiers specified have currently assigned keycodes. A key of
1226 AnyKey is equivalent to issuing the request for all possible
1227 keycodes. Otherwise, the key must be in the range specified by
1228 min-keycode and max-keycode in the ListInputDevices request. If
1229 it is not within that range, GrabDeviceKey generates a Value
1232 NULL may be passed for the modifier_device. If the
1233 modifier_device is NULL, the core X keyboard is used as the
1236 An Access error is generated if some other client has issued a
1237 GrabDeviceKey with the same device and key combination on the
1238 same window. When using AnyModifier or AnyKey, the request
1239 fails completely and the X server generates a Access error and
1240 no grabs are established if there is a conflicting grab for any
1243 This request cannot be used to grab a key on the X keyboard
1244 device. The core GrabKey request should be used for that
1247 To release a passive grab of a single key on an extension
1248 device, use UngrabDeviceKey.
1252 keycode: KEYCODE or AnyKey
1253 modifiers: SETofKEYMASK or AnyModifier
1254 modifier-device: DEVICE or NULL
1257 Errors: Device, Match, Window, Value, Alloc
1259 This request is analogous to the core UngrabKey request. It
1260 releases the key combination on the specified window if it was
1261 grabbed by this client. A modifier of AnyModifier is equivalent
1262 to issuing the request for all possible modifier combinations
1263 (including the combination of no modifiers). A key of AnyKey is
1264 equivalent to issuing the request for all possible keycodes.
1265 This request has no effect on an active grab.
1267 NULL may be passed for the modifier_device. If the
1268 modifier_device is NULL, the core X keyboard is used as the
1271 2.15 Passively Grabbing A Button
1273 To establish a passive grab for a single button on an extension
1274 device, use GrabDeviceButton.
1278 button: BUTTON or AnyButton
1279 modifiers: SETofKEYMASK or AnyModifier
1280 modifier-device: DEVICE or NULL
1283 event-list: LISTofEVENTCLASS
1284 this-device-mode: {Synchronous, Asynchr
1286 other-device-mode: {Synchronous, Asynch
1289 Errors: Device, Match, Window, Access, Value
1291 This request is analogous to the core GrabButton request. It
1292 establishes an explicit passive grab for a button on an
1293 extension input device. Since the server does not track
1294 extension devices, no cursor is specified with this request.
1295 For the same reason, there is no confine-to parameter. The
1296 device must have previously been opened using the OpenDevice
1299 The GrabDeviceButton request establishes a passive grab on a
1300 device. Consequently, in the future,
1303 IF the device is not grabbed and the specified button is
1304 logically pressed when the specified modifier keys
1305 logically are down (and no other buttons or modifier
1309 AND the grab window contains the device,
1312 AND a passive grab on the same device and button/ key
1313 combination does not exist on any ancestor of the grab
1317 THEN the device is actively grabbed, as for GrabDevice,
1318 the last-grab time is set to the time at which the
1319 button was pressed (as transmitted in the
1320 DeviceButtonPress event), and the DeviceButtonPress
1323 The interpretation of the remaining arguments is as for
1324 GrabDevice. The active grab is terminated automatically when
1325 logical state of the device has all buttons released
1326 (independent of the logical state of the modifier keys).
1328 Note that the logical state of a device (as seen by means of
1329 the X protocol) may lag the physical state if device event
1330 processing is frozen.
1332 A modifier of AnyModifier is equivalent to issuing the request
1333 for all possible modifier combinations (including the
1334 combination of no modifiers). It is not required that all
1335 modifiers specified have currently assigned keycodes. A button
1336 of AnyButton is equivalent to issuing the request for all
1337 possible buttons. It is not required that the specified button
1338 be assigned to a physical button.
1340 NULL may be passed for the modifier_device. If the
1341 modifier_device is NULL, the core X keyboard is used as the
1344 An Access error is generated if some other client has issued a
1345 GrabDeviceButton with the same device and button combination on
1346 the same window. When using AnyModifier or AnyButton, the
1347 request fails completely and the X server generates a Access
1348 error and no grabs are established if there is a conflicting
1349 grab for any combination. The request has no effect on an
1352 This request cannot be used to grab a button on the X pointer
1353 device. The core GrabButton request should be used for that
1356 To release a passive grab of a button on an extension device,
1357 use UngrabDeviceButton.
1361 button: BUTTON or AnyButton
1362 modifiers: SETofKEYMASK or AnyModifier
1363 modifier-device: DEVICE or NULL
1366 Errors: Device, Match, Window, Value, Alloc
1368 This request is analogous to the core UngrabButton request. It
1369 releases the passive button/key combination on the specified
1370 window if it was grabbed by the client. A modifiers of
1371 AnyModifier is equivalent to issuing the request for all
1372 possible modifier combinations (including the combination of no
1373 modifiers). A button of AnyButton is equivalent to issuing the
1374 request for all possible buttons. This request has no effect on
1375 an active grab. The device must have previously been opened
1376 using the OpenDevice request otherwise a Device error will be
1379 NULL may be passed for the modifier_device. If the
1380 modifier_device is NULL, the core X keyboard is used as the
1383 This request cannot be used to ungrab a button on the X pointer
1384 device. The core UngrabButton request should be used for that
1387 2.16 Thawing A Device
1389 To allow further events to be processed when a device has been
1390 frozen, use AllowDeviceEvents.
1394 event-mode: {AsyncThisDevice, SyncThisD
1395 evice, AsyncOtherDevices,
1396 ReplayThisdevice, AsyncAll, or SyncAll}
1397 time:TIMESTAMP or CurrentTime
1399 Errors: Device, Value
1401 The AllowDeviceEvents request releases some queued events if
1402 the client has caused a device to freeze. The request has no
1403 effect if the specified time is earlier than the last-grab time
1404 of the most recent active grab for the client, or if the
1405 specified time is later than the current X server time.
1407 The following describes the processing that occurs depending on
1408 what constant you pass to the event-mode argument:
1410 * If the specified device is frozen by the client, event
1411 processing for that device continues as usual. If the
1412 device is frozen multiple times by the client on behalf
1413 of multiple separate grabs, AsyncThisDevice thaws for
1414 all. AsyncThisDevice has no effect if the specified
1415 device is not frozen by the client, but the device need
1416 not be grabbed by the client.
1418 * If the specified device is frozen and actively grabbed
1419 by the client, event processing for that device
1420 continues normally until the next button or key event is
1421 reported to the client. At this time, the specified
1422 device again appears to freeze. However, if the reported
1423 event causes the grab to be released, the specified
1424 device does not freeze. SyncThisDevice has no effect if
1425 the specified device is not frozen by the client or is
1426 not grabbed by the client.
1428 * If the specified device is actively grabbed by the
1429 client and is frozen as the result of an event having
1430 been sent to the client (either from the activation of a
1431 GrabDeviceButton or from a previous AllowDeviceEvents
1432 with mode SyncThisDevice, but not from a Grab), the grab
1433 is released and that event is completely reprocessed.
1434 This time, however, the request ignores any passive
1435 grabs at or above (towards the root) the grab-window of
1436 the grab just released. The request has no effect if the
1437 specified device is not grabbed by the client or if it
1438 is not frozen as the result of an event.
1440 * If the remaining devices are frozen by the client, event
1441 processing for them continues as usual. If the other
1442 devices are frozen multiple times by the client on
1443 behalf of multiple separate grabs, AsyncOtherDevices
1444 “thaws” for all. AsyncOtherDevices has no effect if the
1445 devices are not frozen by the client, but those devices
1446 need not be grabbed by the client.
1448 * If all devices are frozen by the client, event
1449 processing (for all devices) continues normally until
1450 the next button or key event is reported to the client
1451 for a grabbed device (button event for the grabbed
1452 device, key or motion event for the device), at which
1453 time the devices again appear to freeze. However, if the
1454 reported event causes the grab to be released, then the
1455 devices do not freeze (but if any device is still
1456 grabbed, then a subsequent event for it will still cause
1457 all devices to freeze). SyncAll has no effect unless all
1458 devices are frozen by the client. If any device is
1459 frozen twice by the client on behalf of two separate
1460 grabs, SyncAll "thaws" for both (but a subsequent freeze
1461 for SyncAll will only freeze each device once).
1463 * If all devices are frozen by the client, event
1464 processing (for all devices) continues normally. If any
1465 device is frozen multiple times by the client on behalf
1466 of multiple separate grabs, AsyncAll "thaws" for all.
1467 AsyncAll has no effect unless all devices are frozen by
1470 AsyncThisDevice, SyncThisDevice, and ReplayThisDevice
1471 have no effect on the processing of events from the
1472 remaining devices. AsyncOtherDevices has no effect on
1473 the processing of events from the specified device. When
1474 the event_mode is SyncAll or AsyncAll, the device
1475 parameter is ignored.
1477 It is possible for several grabs of different devices
1478 (by the same or different clients) to be active
1479 simultaneously. If a device is frozen on behalf of any
1480 grab, no event processing is performed for the device.
1481 It is possible for a single device to be frozen because
1482 of several grabs. In this case, the freeze must be
1483 released on behalf of each grab before events can again
1486 2.17 Controlling Device Focus
1488 The current focus window for an extension input device can be
1489 determined using the GetDeviceFocus request. Extension devices
1490 are focused using the SetDeviceFocus request in the same way
1491 that the keyboard is focused using the SetInputFocus request,
1492 except that a device is specified as part of the request. One
1493 additional focus state, FollowKeyboard, is provided for
1496 To get the current focus state, revert state, and focus time of
1497 an extension device, use GetDeviceFocus.
1502 focus: WINDOW, PointerRoot, FollowKeyboard, or None
1503 revert-to: Parent, PointerRoot, FollowKeyboard, or None
1504 focus-time: TIMESTAMP
1506 Errors: Device, Match
1508 This request returns the current focus state, revert-to state,
1509 and last-focus-time of an extension device.
1511 To set the focus of an extension device, use SetDeviceFocus.
1515 focus: WINDOW, PointerRoot, FollowKeyboard, or None
1516 revert-to: Parent, PointerRoot, FollowKeyboard, or None
1517 focus-time: TIMESTAMP
1519 Errors: Device, Window, Value, Match
1521 This request changes the focus for an extension input device
1522 and the last-focus-change-time. The request has no effect if
1523 the specified time is earlier than the last-focus-change-time
1524 or is later than the current X server time. Otherwise, the
1525 last-focus-change-time is set to the specified time, with
1526 CurrentTime replaced by the current server time.
1528 The action taken by the server when this request is requested
1529 depends on the value of the focus argument:
1531 * If the focus argument is None, all input events from
1532 this device will be discarded until a new focus window
1533 is set. In this case, the revert-to argument is ignored.
1535 * If a window ID is assigned to the focus argument, it
1536 becomes the focus window of the device. If an input
1537 event from the device would normally be reported to this
1538 window or to one of its inferiors, the event is reported
1539 normally. Otherwise, the event is reported relative to
1542 * If you assign PointerRoot to the focus argument, the
1543 focus window is dynamically taken to be the root window
1544 of whatever screen the pointer is on at each input
1545 event. In this case, the revert-to argument is ignored.
1547 * If you assign FollowKeyboard to the focus argument, the
1548 focus window is dynamically taken to be the same as the
1549 focus of the X keyboard at each input event.
1551 The specified focus window must be viewable at the time
1552 of the request (else a Match error). If the focus window
1553 later becomes not viewable, the X server evaluates the
1554 revert-to argument to determine the new focus window.
1556 * If you assign RevertToParent to the revert-to argument,
1557 the focus reverts to the parent (or the closest viewable
1558 ancestor), and the new revert-to value is taken to be
1561 * If you assign RevertToPointerRoot,
1562 RevertToFollowKeyboard, or RevertToNone to the revert-to
1563 argument, the focus reverts to that value.
1565 When the focus reverts, the X server generates DeviceFocusIn
1566 and DeviceFocusOut events, but the last-focus-change time is
1569 This request causes the X server to generate DeviceFocusIn and
1570 DeviceFocusOut events.
1572 2.18 Controlling Device Feedback
1574 To get the settings of feedbacks on an extension device, use
1575 GetFeedbackControl. This request provides functionality
1576 equivalent to the core GetKeyboardControl and GetPointerControl
1577 functions. It also provides a way to control displays
1578 associated with an input device that are capable of displaying
1579 an integer or string.
1584 num_feedbacks_return: CARD16
1585 return_value: LISTofFEEDBACKSTATE
1589 FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState,
1590 IntegerFeedbackState, StringFeedbackState,
1591 BellFeedbackState, LedFeedbackState}
1593 Feedbacks are reported by class. Those feedbacks that are
1594 reported for the core keyboard device are in class KbdFeedback,
1595 and are returned in the KbdFeedbackState structure. The members
1596 of that structure are as follows:
1602 key_click_percent: CARD8
1605 bell_duration: CARD16
1607 global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff}
1608 auto_repeats: LISTofCARD8]
1610 Those feedbacks that are equivalent to those reported for the
1611 core pointer are in feedback class PtrFeedback and are reported
1612 in the PtrFeedbackState structure. The members of that
1619 accelNumerator: CARD16
1620 accelDenominator: CARD16
1623 Some input devices provide a means of displaying an integer.
1624 Those devices will support feedback class IntegerFeedback,
1625 which is reported in the IntegerFeedbackState structure. The
1626 members of that structure are:
1636 Some input devices provide a means of displaying a string.
1637 Those devices will support feedback class StringFeedback, which
1638 is reported in the StringFeedbackState structure. The members
1639 of that structure are:
1646 num_keysyms_supported: CARD16
1647 keysyms_supported: LISTofKEYSYM]
1649 Some input devices contain a bell. Those devices will support
1650 feedback class BellFeedback, which is reported in the
1651 BellFeedbackState structure. The members of that structure are:
1661 The percent sets the base volume for the bell between 0 (off)
1662 and 100 (loud) inclusive, if possible. Setting to -1 restores
1663 the default. Other negative values generate a Value error.
1665 The pitch sets the pitch (specified in Hz) of the bell, if
1666 possible. Setting to -1 restores the default. Other negative
1667 values generate a Value error.
1669 The duration sets the duration (specified in milliseconds) of
1670 the bell, if possible. Setting to -1 restores the default.
1671 Other negative values generate a Value error.
1673 A bell generator connected with the console but not directly on
1674 the device is treated as if it were part of the device. Some
1675 input devices contain LEDs. Those devices will support feedback
1676 class Led, which is reported in the LedFeedbackState structure.
1677 The members of that structure are:
1686 Each bit in led_mask indicates that the corresponding led is
1687 supported by the feedback. At most 32 LEDs per feedback are
1688 supported. No standard interpretation of LEDs is defined.
1690 This function will fail with a BadMatch error if the device
1691 specified in the request does not support feedbacks.
1693 Errors: Device, Match
1695 To change the settings of a feedback on an extension device,
1696 use ChangeFeedbackControl.
1698 ChangeFeedbackControl
1702 value: FEEDBACKCONTROL
1703 FEEDBACKCONTROL: {KBDFEEDBACKCONTROL,
1705 INTEGERFEEDBACKCONTROL,
1706 STRINGFEEDBACKCONTROL,
1707 BELLFEEDBACKCONTROL,
1710 Errors: Device, Match, Value
1712 Feedback controls are grouped by class. Those feedbacks that
1713 are equivalent to those supported by the core keyboard are
1714 controlled by feedback class KbdFeedbackClass using the
1715 KbdFeedbackControl structure. The members of that structure
1722 key_click_percent: INT8
1725 bell_duration: INT16
1729 auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff,
1730 AutoRepeatModeDefault}]
1732 The key_click_percent sets the volume for key clicks between 0
1733 (off) and 100 (loud) inclusive, if possible. Setting to -1
1734 restores the default. Other negative values generate a Value
1737 If both auto_repeat_mode and key are specified, then the
1738 auto_repeat_mode of that key is changed, if possible. If only
1739 auto_repeat_mode is specified, then the global auto-repeat mode
1740 for the entire keyboard is changed, if possible, without
1741 affecting the per-key settings. It is a Match error if a key is
1742 specified without an auto_repeat_mode.
1744 The order in which controls are verified and altered is
1745 server-dependent. If an error is generated, a subset of the
1746 controls may have been altered.
1748 Those feedback controls equivalent to those of the core pointer
1749 are controlled by feedback class PtrFeedbackClass using the
1750 PtrFeedbackControl structure. The members of that structure are
1757 accelNumerator: INT16
1758 accelDenominator: INT16
1761 The acceleration, expressed as a fraction, is a multiplier for
1762 movement. For example, specifying 3/1 means the device moves
1763 three times as fast as normal. The fraction may be rounded
1764 arbitrarily by the X server. Acceleration only takes effect if
1765 the device moves more than threshold pixels at once and only
1766 applies to the amount beyond the value in the threshold
1767 argument. Setting a value to -1 restores the default. The
1768 values of the do-accel and do-threshold arguments must be
1769 nonzero for the device values to be set. Otherwise, the
1770 parameters will be unchanged. Negative values generate a Value
1771 error, as does a zero value for the accel-denominator argument.
1773 Some devices are capable of displaying an integer. This is done
1774 using feedback class IntegerFeedbackClass using the
1775 IntegerFeedbackControl structure. The members of that structure
1782 int_to_display: INT32]
1784 Some devices are capable of displaying an string. This is done
1785 using feedback class StringFeedbackClass using the
1786 StringFeedbackCtl structure. The members of that structure are
1793 syms_to_display: LISTofKEYSYMS]
1795 Some devices contain a bell. This is done using feedback class
1796 BellFeedbackClass using the BellFeedbackControl structure. The
1797 members of that structure are as follows:
1807 Some devices contain leds. These can be turned on and off using
1808 the LedFeedbackControl structure. The members of that structure
1818 Errors: Device, Match, Value
1820 2.20 Ringing a Bell on an Input Device
1822 To ring a bell on an extension input device, use DeviceBell.
1826 feedbackclass: CARD8
1830 Errors: Device, Value
1832 This request is analogous to the core Bell request. It rings
1833 the specified bell on the specified input device feedback,
1834 using the specified volume. The specified volume is relative to
1835 the base volume for the feedback. If the value for the percent
1836 argument is not in the range -100 to 100 inclusive, a Value
1837 error results. The volume at which the bell rings when the
1838 percent argument is nonnegative is:
1840 base - [(base * percent) / 100] + percent
1842 The volume at which the bell rings when the percent argument is
1845 base + [(base * percent) / 100]
1847 To change the base volume of the bell, use
1848 ChangeFeedbackControl request.
1850 Controlling Device Encoding
1852 To get the keyboard mapping of an extension device that has
1853 keys, use GetDeviceKeyMapping.
1857 first-keycode: KEYCODE
1860 keysyms-per-keycode: CARD8
1861 keysyms: LISTofKEYSYM
1863 Errors: Device, Match, Value
1865 This request returns the symbols for the specified number of
1866 keycodes for the specified extension device, starting with the
1867 specified keycode. The first-keycode must be greater than or
1868 equal to min-keycode as returned in the connection setup (else
1871 first-keycode + count - 1
1873 must be less than or equal to max-keycode as returned in the
1874 connection setup (else a Value error). The number of elements
1875 in the keysyms list is
1877 count * keysyms-per-keycode
1879 and KEYSYM number N (counting from zero) for keycode K has an
1880 index (counting from zero) of
1882 (K - first-keycode) * keysyms-per-keycode + N
1884 in keysyms. The keysyms-per-keycode value is chosen arbitrarily
1885 by the server to be large enough to report all requested
1886 symbols. A special KEYSYM value of NoSymbol is used to fill in
1887 unused elements for individual keycodes.
1889 If the specified device has not first been opened by this
1890 client via OpenDevice, or if that device does not support input
1891 class Keys, this request will fail with a Device error.
1893 To change the keyboard mapping of an extension device that has
1894 keys, use ChangeDeviceKeyMapping.
1896 ChangeDeviceKeyMapping
1898 first-keycode: KEYCODE
1899 keysyms-per-keycode: CARD8
1900 keysyms: LISTofKEYSYM
1903 Errors: Device, Match, Value, Alloc
1905 This request is analogous to the core ChangeKeyMapping request.
1906 It defines the symbols for the specified number of keycodes for
1907 the specified extension device. If the specified device has not
1908 first been opened by this client via OpenDevice, or if that
1909 device does not support input class Keys, this request will
1910 fail with a Device error.
1912 The number of elements in the keysyms list must be a multiple
1913 of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping
1914 generates a Length error. The specified first_keycode must be
1915 greater than or equal to the min_keycode value returned by the
1916 ListInputDevices request, or this request will fail with a
1917 Value error. In addition, if the following expression is not
1918 less than the max_keycode value returned by the
1919 ListInputDevices request, the request will fail with a Value
1922 first_keycode + (num_codes / keysyms_per_keycode) - 1
1924 To obtain the keycodes that are used as modifiers on an
1925 extension device that has keys, use GetDeviceModifierMapping.
1927 GetDeviceModifierMapping
1930 keycodes-per-modifier: CARD8
1931 keycodes: LISTofKEYCODE
1933 Errors: Device, Match
1935 This request is analogous to the core GetModifierMapping
1936 request. This request returns the keycodes of the keys being
1937 used as modifiers. The number of keycodes in the list is
1938 8*keycodes-per-modifier. The keycodes are divided into eight
1939 sets, with each set containing keycodes-per-modifier elements.
1940 The sets are assigned in order to the modifiers Shift, Lock,
1941 Control, Mod1, Mod2, Mod3, Mod4, and Mod5. The
1942 keycodes-per-modifier value is chosen arbitrarily by the
1943 server; zeroes are used to fill in unused elements within each
1944 set. If only zero values are given in a set, the use of the
1945 corresponding modifier has been disabled. The order of keycodes
1946 within each set is chosen arbitrarily by the server.
1948 To set which keycodes that are to be used as modifiers for an
1949 extension device, use SetDeviceModifierMapping.
1951 SetDeviceModifierMapping
1953 keycodes-per-modifier: CARD8
1954 keycodes: LISTofKEYCODE
1956 status: {Success, Busy, Failed}
1958 Errors: Device, Match, Value, Alloc
1960 This request is analogous to the core SetModifierMapping
1961 request. This request specifies the keycodes (if any) of the
1962 keys to be used as modifiers. The number of keycodes in the
1963 list must be 8*keycodes-per-modifier (else a Length error). The
1964 keycodes are divided into eight sets, with the sets, with each
1965 set containing keycodes-per-modifier elements. The sets are
1966 assigned in order to the modifiers Shift, Lock, Control, Mod1,
1967 Mod2, Mod3, Mod4, and Mod5. Only non-zero keycode values are
1968 used within each set; zero values are ignored. All of the
1969 non-zero keycodes must be in the range specified by min-keycode
1970 and max-keycode in the ListInputDevices request (else a Value
1971 error). The order of keycodes within a set does not matter. If
1972 no non-zero values are specified in a set, the use of the
1973 corresponding modifier is disabled, and the modifier bit will
1974 always be zero. Otherwise, the modifier bit will be one
1975 whenever at least one of the keys in the corresponding set is
1976 in the down position.
1978 A server can impose restrictions on how modifiers can be
1979 changed (for example, if certain keys do not generate up
1980 transitions in hardware or if multiple keys per modifier are
1981 not supported). The status reply is Failed if some such
1982 restriction is violated, and none of the modifiers are changed.
1984 If the new non-zero keycodes specified for a modifier differ
1985 from those currently defined, and any (current or new) keys for
1986 that modifier are logically in the down state, then the status
1987 reply is Busy, and none of the modifiers are changed.
1989 This request generates a DeviceMappingNotify event on a Success
1990 status. The DeviceMappingNotify event will be sent only to
1991 those clients that have expressed an interest in receiving that
1992 event via the XSelectExtensionEvent request.
1994 A X server can impose restrictions on how modifiers can be
1995 changed, for example, if certain keys do not generate up
1996 transitions in hardware or if multiple modifier keys are not
1997 supported. If some such restriction is violated, the status
1998 reply is MappingFailed , and none of the modifiers are changed.
1999 If the new keycodes specified for a modifier differ from those
2000 currently defined and any (current or new) keys for that
2001 modifier are in the logically down state, the status reply is
2002 MappingBusy, and none of the modifiers are changed.
2004 2.20 Controlling Button Mapping
2006 These requests are analogous to the core GetPointerMapping and
2007 ChangePointerMapping requests. They allow a client to determine
2008 the current mapping of buttons on an extension device, and to
2009 change that mapping.
2011 To get the current button mapping for an extension device, use
2012 GetDeviceButtonMapping.
2014 GetDeviceButtonMapping
2018 map_return: LISTofCARD8
2020 Errors: Device, Match
2022 The GetDeviceButtonMapping function returns the current mapping
2023 of the buttons on the specified device. Elements of the list
2024 are indexed starting from one. The length of the list indicates
2025 the number of physical buttons. The nominal mapping is the
2026 identity mapping map[i]=i.
2028 nmap indicates the number of elements in the map_return array.
2029 Only the first nmap entries will be copied by the library into
2030 the map_return array.
2032 To set the button mapping for an extension device, use
2033 SetDeviceButtonMapping.
2035 SetDeviceButtonMapping
2042 Errors: Device, Match, Value
2044 The SetDeviceButtonMapping function sets the mapping of the
2045 specified device and causes the X server to generate a
2046 DeviceMappingNotify event on a status of MappingSuccess.
2047 Elements of the list are indexed starting from one. The length
2048 of the list, specified in nmap, must be the same as
2049 GetDeviceButtonMapping would return. Otherwise,
2050 SetDeviceButtonMapping generates a Value error. A zero element
2051 disables a button, and elements are not restricted in value by
2052 the number of physical buttons. If any of the buttons to be
2053 altered are in the down state, the status reply is MappingBusy
2054 and the mapping is not changed.
2056 In servers supporting XI 1.x, no two elements can have the same
2057 nonzero value. Otherwise, this function generates a Value
2060 2.21 Obtaining The State Of A Device
2062 To obtain vectors that describe the state of the keys, buttons
2063 and valuators of an extension device, use QueryDeviceState.
2069 data: LISTofINPUTCLASS
2073 INPUTCLASS: {VALUATOR, BUTTON, KEY}
2076 num_valuators: CARD8
2078 #x01 device mode (0 = Relative, 1 = Absolute)
2079 #x02 proximity state (0 = InProximity, 1 = OutOfProximity)
2080 valuators: LISTofINT32]
2084 buttons: LISTofCARD8]
2092 The QueryDeviceState request returns the current logical state
2093 of the buttons, keys, and valuators on the specified input
2094 device. The buttons and keys arrays, byte N (from 0) contains
2095 the bits for key or button 8N to 8N+7 with the least
2096 significant bit in the byte representing key or button 8N.
2098 If the device has valuators, a bit in the mode field indicates
2099 whether the device is reporting Absolute or Relative data. If
2100 it is reporting Absolute data, the valuators array will contain
2101 the current value of the valuators. If it is reporting Relative
2102 data, the valuators array will contain undefined data.
2104 If the device reports proximity information, a bit in the mode
2105 field indicates whether the device is InProximity or
2108 2.22 Listing Device Properties
2110 Introduced with XI 1.5
2112 ListDeviceProperties
2120 Each device can store an arbitrary number of properties. These
2121 properties can be allocated by either the client or the driver.
2122 The client can change device properties and the server
2123 guarantees that the device driver is notified about a change of
2124 the device's properties.
2126 ListDeviceProperties returns all properties of a device. The
2127 client is expected to retrieve details about the properties it
2128 is interested in separately.
2130 2.23 Getting a Device Property
2132 Introduced with XI 1.5
2149 Errors: Atom, Device, Value, Access
2151 Retrieve the value for a property. If the property does not
2152 exist, propertyType is None and all other fields are undefined.
2154 If type is not AnyPropertyType and does not match the
2155 property's actual type, the propertyType, bytesAfter, and
2156 format are returned but not the actual data.
2158 longOffset and longLength specify the offset and length
2159 respectively in 32-bit multiples of the data to retrieve.
2161 If delete is True, the property is deleted after querying its
2162 data. If the property cannot be deleted, a BadAccess error is
2165 propertyType returns the atom identifier that defines the
2166 actual type of the property.
2168 If bytesAfter is non-zero, it specifies the number of data
2169 4-byte units after the retrieved chunk of data.
2171 format specifies whether the data should be viewed as a list of
2172 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16,
2173 and 32. This information allows the X server to correctly
2174 perform byte-swap operations as necessary.
2176 nItem specifies the number of 8-bit, 16-bit, or 32-bit items
2177 returned after the request.
2179 2.24 Changing a Device Property
2181 Introduced with XI 1.5
2183 ChangeDeviceProperty:
2191 Errors: Atom, Device, Value, Match, Access
2193 Changes the value of a specified property.
2195 The type specifies the atom identifier that defines the type of
2196 the property. If mode is not PropModeReplace, the type must
2197 match the current type of the property or a BadMatch error is
2200 format specifies whether the data should be viewed as a list of
2201 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16,
2202 and 32. This information allows the X server to correctly
2203 perform byte-swap operations as necessary.
2205 If mode is PropModeReplace, a preexising value for this
2206 property is replaced with the new value. If mode is
2207 PropModePrepend or PropModeAppend, the value is prepended or
2208 appended, respectively, to the current value of the property.
2210 nUnits specifies the number of 8-bit, 16-bit, or 32-bit items
2211 supplied after the reply.
2213 Changing a device property results in a
2214 DevicePropertyNotifyEvent being sent to all clients.
2216 2.25 Deleting a Device Property
2218 Introduced with XI 1.5
2220 DeleteDeviceProperty:
2224 Errors: Atom, Device, Match, Access.
2226 Deletes the specified property. If the property cannot be
2227 deleted by the client, a BadAccess error is returned.
2231 The input extension creates input events analogous to the core
2232 input events. These extension input events are generated by
2233 manipulating one of the extension input devices.
2235 3.1 Button, Key, and Motion Events
2244 child: Window or None
2246 root-x, root-y, event-x, event-y: INT16
2248 state: SETofKEYBUTMASK
2251 These events are generated when a key, button, or valuator
2252 logically changes state. The generation of these logical
2253 changes may lag the physical changes, if device event
2254 processing is frozen. Note that DeviceKeyPress and
2255 DeviceKeyRelease are generated for all keys, even those mapped
2256 to modifier bits. The “source” of the event is the window the
2257 pointer is in. The window with respect to which the event is
2258 normally reported is found by looking up the hierarchy
2259 (starting with the source window) for the first window on which
2260 any client has selected interest in the event. The actual
2261 window used for reporting can be modified by active grabs and
2262 by the focus window.The window the event is reported with
2263 respect to is called the “event” window.
2265 The root is the root window of the “source” window, and root-x
2266 and root-y are the pointer coordinates relative to root's
2267 origin at the time of the event. Event is the “event” window.
2268 If the event window is on the same screen as root, then event-x
2269 and event-y are the pointer coordinates relative to the event
2270 window's origin. Otherwise, event-x and event-y are zero. If
2271 the source window is an inferior of the event window, then
2272 child is set to the child of the event window that is an
2273 ancestor of (or is) the source window. Otherwise, it is set to
2276 The state component gives the logical state of the buttons on
2277 the X pointer and modifier keys on the core X keyboard just
2280 The detail component type varies with the event type:
2282 DeviceKeyPress KEYCODE
2283 DeviceKeyRelease KEYCODE
2284 DeviceButtonPress BUTTON
2285 DeviceButtonRelease BUTTON
2286 DeviceMotionNotify { Normal , Hint }
2288 The granularity of motion events is not guaranteed, but a
2289 client selecting for motion events is guaranteed to get at
2290 least one event when a valuator changes. If DeviceMotionHint is
2291 selected, the server is free to send only one
2292 DeviceMotionNotify event (with detail Hint) to the client for
2293 the event window, until either a key or button changes state,
2294 the pointer leaves the event window, or the client issues a
2295 QueryDeviceState or GetDeviceMotionEvents request.
2297 3.2 DeviceValuator Event
2301 device_state: SETofKEYBUTMASK
2302 num_valuators: CARD8
2303 first_valuator: CARD8
2304 valuators: LISTofINT32
2306 DeviceValuator events are generated to contain valuator
2307 information for which there is insufficient space in DeviceKey,
2308 DeviceButton, DeviceMotion, and Proximity wire events. For
2309 events of these types, a second event of type DeviceValuator
2310 follows immediately. The library combines these events into a
2311 single event that a client can receive via XNextEvent.
2312 DeviceValuator events are not selected for by clients, they
2313 only exist to contain information that will not fit into some
2314 event selected by clients.
2316 The device_state component gives the state of the buttons and
2317 modifiers on the device generating the event.
2319 Extension motion devices may report motion data for a variable
2320 number of axes. The valuators array contains the values of all
2321 axes reported by the device. If more than 6 axes are reported,
2322 more than one DeviceValuator event will be sent by the server,
2323 and more than one DeviceKey, DeviceButton, DeviceMotion, or
2324 Proximity event will be reported by the library. Clients should
2325 examine the corresponding fields of the event reported by the
2326 library to determine the total number of axes reported, and the
2327 first axis reported in the current event. Axes are numbered
2328 beginning with zero.
2330 For Button, Key and Motion events on a device reporting
2331 absolute motion data the current value of the device's
2332 valuators is reported. For devices that report relative data,
2333 Button and Key events may be followed by a DeviceValuator event
2334 that contains 0s in the num_valuators field. In this case, only
2335 the device_state component will have meaning.
2337 3.3 Device Focus Events
2344 mode: { Normal, WhileGrabbed, Grab, Ungrab}
2345 detail: { Ancestor, Virtual, Inferior, Nonlinear,
2346 NonlinearVirtual, Pointer, PointerRoot, None}
2348 These events are generated when the input focus changes and are
2349 reported to clients selecting DeviceFocusChange for the
2350 specified device and window. Events generated by SetDeviceFocus
2351 when the device is not grabbed have mode Normal. Events
2352 generated by SetDeviceFocus when the device is grabbed have
2353 mode WhileGrabbed. Events generated when a device grab actives
2354 have mode Grab, and events generated when a device grab
2355 deactivates have mode Ungrab.
2357 All DeviceFocusOut events caused by a window unmap are
2358 generated after any UnmapNotify event, but the ordering of
2359 DeviceFocusOut with respect to generated EnterNotify,
2360 LeaveNotify, VisibilityNotify and Expose events is not
2363 DeviceFocusIn and DeviceFocusOut events are generated for focus
2364 changes of extension devices in the same manner as focus events
2365 for the core devices are generated.
2367 3.4 Device State Notify Event
2374 num_valuators: CARD8
2375 classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass}
2377 #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity
2378 #x40 Device Mode (0 = Relative, 1 = Absolute)
2379 SetOfInputClass: #x04 reporting valuators
2380 #x02 reporting buttons
2382 buttons: LISTofCARD8
2384 valuators: LISTofCARD32
2386 This event reports the state of the device just as in the
2387 QueryDeviceState request. This event is reported to clients
2388 selecting DeviceStateNotify for the device and window and is
2389 generated immediately after every EnterNotify and
2390 DeviceFocusIn. If the device has no more than 32 buttons, no
2391 more than 32 keys, and no more than 3 valuators, This event can
2392 report the state of the device. If the device has more than 32
2393 buttons, the event will be immediately followed by a
2394 DeviceButtonStateNotify event. If the device has more than 32
2395 keys, the event will be followed by a DeviceKeyStateNotify
2396 event. If the device has more than 3 valuators, the event will
2397 be followed by one or more DeviceValuator events.
2399 3.5 Device KeyState and ButtonState Notify Events
2401 DeviceKeyStateNotify
2404 DeviceButtonStateNotify
2406 buttons: LISTofCARD8
2408 These events contain information about the state of keys and
2409 buttons on a device that will not fit into the
2410 DeviceStateNotify wire event. These events are not selected by
2411 clients, rather they may immediately follow a DeviceStateNotify
2412 wire event and be combined with it into a single
2413 DeviceStateNotify client event that a client may receive via
2416 3.6 DeviceMappingNotify Event
2422 first_keycode: CARD8
2425 This event reports a change in the mapping of keys, modifiers,
2426 or buttons on an extension device. This event is reported to
2427 clients selecting DeviceMappingNotify for the device and window
2428 and is generated after every client SetDeviceButtonMapping,
2429 ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request.
2431 3.7 ChangeDeviceNotify Event
2438 This event reports a change in the physical device being used
2439 as the core X keyboard or X pointer device. ChangeDeviceNotify
2440 events are reported to clients selecting ChangeDeviceNotify for
2441 the device and window and is generated after every client
2442 ChangeKeyboardDevice or ChangePointerDevice request.
2444 3.7 Proximity Events
2450 child: Window or None
2452 root-x, root-y, event-x, event-y: INT16
2453 state: SETofKEYBUTMASK
2455 device-state: SETofKEYBUTMASK
2458 axis-data: LISTofINT32
2460 These events are generated by some devices (such as graphics
2461 tablets or touchscreens) to indicate that a stylus has moved
2462 into or out of contact with a positional sensing surface.
2464 The “source” of the event is the window the pointer is in. The
2465 window with respect to which the event is normally reported is
2466 found by looking up the hierarchy (starting with the source
2467 window) for the first window on which any client has selected
2468 interest in the event. The actual window used for reporting can
2469 be modified by active grabs and by the focus window.The window
2470 the event is reported with respect to is called the “event”
2473 The root is the root window of the “source” window, and root-x
2474 and root-y are the pointer coordinates relative to root's
2475 origin at the time of the event. Event is the “event” window.
2476 If the event window is on the same screen as root, then event-x
2477 and event-y are the pointer coordinates relative to the event
2478 window's origin. Otherwise, event-x and event-y are zero. If
2479 the source window is an inferior of the event window, then
2480 child is set to the child of the event window that is an
2481 ancestor of (or is) the source window. Otherwise, it is set to
2482 None. The state component gives the logical state of the
2483 buttons on the core X pointer and modifier keys on the core X
2484 keyboard just before the event. The device-state component
2485 gives the state of the buttons and modifiers on the device
2486 generating the event.
2488 3.8 DevicePresenceEvents
2490 Introduced with XI 1.4.
2498 #x03: DeviceDisabled
2499 #x04: DeviceUnrecoverable
2500 #x05: DeviceControlChanged
2504 DevicePresence events are sent when the server adds or removes,
2505 or enables or disables an input device. The client is expected
2506 to query the server for the list of input devices using the
2507 ListInputDevices request to obtain the updated list of input
2508 devices. DevicePresence events are also sent when a control on
2509 the device has been changed.
2511 The devchange field specifies the type of operation. In case of
2512 DeviceAdded, a new device has been added to the server, but
2513 this device does not yet send events. If devchange is set to
2514 DeviceEnabled, the device is enabled and will generate events.
2515 If the field is DeviceDisabled or DeviceRemoved, the given
2516 device is disabled and stops sending events or was removed from
2517 the server, respectively. If the field is DeviceUnrecoverable,
2518 an IO-error has occured on the device and the device is
2519 forcibly disabled and removed by the server. If devchange is
2520 DeviceControlChanged, control specifies the type of control
2521 that has been changed.
2523 3.9 DevicePropertyNotifyEvent
2525 Introduced with XI 1.5.
2527 DevicePropertyNotifyEvent
2533 A DevicePropertyNotifyEvent is sent to all clients when a
2534 property on the device is created, deleted, or changes value.
2536 The deviceid specifies the device which's property has been
2539 The atom specifies the named identifier of the property that
2542 If state is PropertyNewValue, the given property has a new
2543 value or has been newly created. If state is PropertyDeleted,
2544 the given property has been deleted.
projects / framework / uifw / xorg / proto / x11proto-input.git / blob