upload tizen2.0 source
[framework/uifw/xorg/proto/x11proto-input.git] / specs / XIproto.txt
1 X11 Input Extension Protocol Specification
2 ==========================================
3
4                       Version 1.0
5                    X Consortium Standard
6                  X Version 11, Release 6.8
7                Mark Patrick, Ardent Computer
8                George Sachs, Hewlett-Packard
9
10                       Version 1.5
11                     Peter Hutterer
12
13    Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and
14    Ardent Computer
15
16    Permission to use, copy, modify, and distribute this
17    documentation for any purpose and without fee is hereby
18    granted, provided that the above copyright notice and this
19    permission notice appear in all copies. Ardent and
20    Hewlett-Packard make no representations about the suitability
21    for any purpose of the information in this document. It is
22    provided "as is" without express or implied warranty. Copyright
23    © 1989, 1990, 1991, 1992 X Consortium
24
25    Permission is hereby granted, free of charge, to any person
26    obtaining a copy of this software and associated documentation
27    files (the “Software”), to deal in the Software without
28    restriction, including without limitation the rights to use,
29    copy, modify, merge, publish, distribute, sublicense, and/or
30    sell copies of the Software, and to permit persons to whom the
31    Software is furnished to do so, subject to the following
32    conditions:
33
34    The above copyright notice and this permission notice shall be
35    included in all copies or substantial portions of the Software.
36
37    THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
38    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
39    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
40    NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE
41    FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
42    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
43    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
44    THE SOFTWARE.
45
46    Except as contained in this notice, the name of the X
47    Consortium shall not be used in advertising or otherwise to
48    promote the sale, use or other dealings in this Software
49    without prior written authorization from the X Consortium. X
50    Window System is a trademark of The Open Group.
51
52    Copyright © 2008 by Peter Hutterer
53
54    Permission is hereby granted, free of charge, to any person
55    obtaining a copy of this software and associated documentation
56    files (the "Software"), to deal in the Software without
57    restriction, including without limitation the rights to use,
58    copy, modify, merge, publish, distribute, sublicense, and/or
59    sell copies of the Software, and to permit persons to whom the
60    Software is furnished to do so, subject to the following
61    conditions:
62
63    The above copyright notice and this permission notice
64    (including the next paragraph) shall be included in all copies
65    or substantial portions of the Software.
66
67    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
68    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
69    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
70    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
71    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
72    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
73    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
74    OTHER DEALINGS IN THE SOFTWARE.
75
76 1. Input Extension Overview
77 ---------------------------
78
79 This document defines an extension to the X11 protocol to
80 support input devices other than the core X keyboard and
81 pointer. An accompanying document defines a corresponding
82 extension to Xlib (similar extensions for languages other than
83 C are anticipated). This first section gives an overview of the
84 input extension. The next section defines the new protocol
85 requests defined by the extension. We conclude with a
86 description of the new input events generated by the additional
87 input devices.
88
89 This document only describes the behaviour of servers supporting
90 up to the X Input Extension 1.5. For servers supporting the X
91 Input Extensions 2.0, see XI2proto.txt. New clients are discouraged
92 from using this protocol specification. Instead, the use of XI 2.x
93 is recommended.
94
95 1.1 Design Approach
96 ~~~~~~~~~~~~~~~~~~~
97
98 The design approach of the extension is to define requests and
99 events analogous to the core requests and events. This allows
100 extension input devices to be individually distinguishable from
101 each other and from the core input devices. These requests and
102 events make use of a device identifier and support the
103 reporting of n-dimensional motion data as well as other data
104 that is not reportable via the core input events.
105
106 1.2 Core Input Devices
107 ~~~~~~~~~~~~~~~~~~~~~~
108
109 The X server core protocol supports two input devices: a
110 pointer and a keyboard. The pointer device has two major
111 functions. First, it may be used to generate motion information
112 that client programs can detect. Second, it may also be used to
113 indicate the current location and focus of the X keyboard. To
114 accomplish this, the server echoes a cursor at the current
115 position of the X pointer. Unless the X keyboard has been
116 explicitly focused, this cursor also shows the current location
117 and focus of the X keyboard. The X keyboard is used to generate
118 input that client programs can detect.
119
120 In servers supporting XI 1.4 and above, the core pointer and
121 the core keyboard are virtual devices that do not represent a
122 physical device connected to the host computer.
123 In servers supporting XI 2.0 and above, there may be multiple
124 core pointers and keyboards. Refer to XI2proto.txt for more
125 information.
126
127 The X keyboard and X pointer are referred to in this document
128 as the core devices, and the input events they generate
129 (KeyPress, KeyRelease, ButtonPress, ButtonRelease, and
130 MotionNotify) are known as the core input events. All other
131 input devices are referred to as extension input devices and
132 the input events they generate are referred to as extension
133 input events.
134
135 In servers supporting only XI 1.x, this input extension does
136 not change the behavior or functionality of the core input
137 devices, core events, or core protocol requests, with the
138 exception of the core grab requests. These requests may affect
139 the synchronization of events from extension devices. See the
140 explanation in the section titled "Event Synchronization and
141 Core Grabs".
142
143 Selection of the physical devices to be initially used by the
144 server as the core devices is left implementation-dependent.
145 Requests are defined that allow client programs to change which
146 physical devices are used as the core devices.
147
148 1.3 Extension Input Devices
149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
150
151 The input extension v1.x controls access to input devices other
152 than the X keyboard and X pointer. It allows client programs to
153 select input from these devices independently from each other
154 and independently from the core devices.
155
156 A client that wishes to access a specific device must first
157 determine whether that device is connected to the X server.
158 This is done through the ListInputDevices request, which will
159 return a list of all devices that can be opened by the X
160 server. A client can then open one or more of these devices
161 using the OpenDevice request, specify what events they are
162 interested in receiving, and receive and process input events
163 from extension devices in the same way as events from the X
164 keyboard and X pointer. Input events from these devices are of
165 extension types ( DeviceKeyPress, DeviceKeyRelease,
166 DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify,
167 etc.) and contain a device identifier so that events of the
168 same type coming from different input devices can be
169 distinguished.
170
171 Any kind of input device may be used as an extension input
172 device. Extension input devices may have 0 or more keys, 0 or
173 more buttons, and may report 0 or more axes of motion. Motion
174 may be reported as relative movements from a previous position
175 or as an absolute position. All valuators reporting motion
176 information for a given extension input device must report the
177 same kind of motion information (absolute or relative).
178
179 This extension is designed to accommodate new types of input
180 devices that may be added in the future. The protocol requests
181 that refer to specific characteristics of input devices
182 organize that information by input classes. Server implementors
183 may add new classes of input devices without changing the
184 protocol requests. Input classes are unique numbers registered
185 with the X Consortium. Each extension input device may support
186 multiple input classes.
187
188 In XI 1.x, all extension input devices are treated like the
189 core X keyboard in determining their location and focus. The
190 server does not track the location of these devices on an
191 individual basis, and therefore does not echo a cursor to
192 indicate their current location. Instead, their location is
193 determined by the location of the core X pointer. Like the core
194 X keyboard, some may be explicitly focused. If they are not
195 explicitly focused, their focus is determined by the location
196 of the core X pointer.
197
198 Most input events reported by the server to a client are of
199 fixed size (32 bytes). In order to represent the change in
200 state of an input device the extension may need to generate a
201 sequence of input events. A client side library (such as Xlib)
202 will typically take these raw input events and format them into
203 a form more convenient to the client.
204
205 1.4 Event Classes
206 -----------------
207
208 In the core protocol a client registers interest in receiving
209 certain input events directed to a window by modifying that
210 window's event-mask. Most of the bits in the event mask are
211 already used to specify interest in core X events. The input
212 extension specifies a different mechanism by which a client can
213 express interest in events generated by this extension.
214
215 When a client opens a extension input device via the OpenDevice
216 request, an XDevice structure is returned. Macros are provided
217 that extract 32-bit numbers called event classes from that
218 structure, that a client can use to register interest in
219 extension events via the SelectExtensionEvent request. The
220 event class combines the desired event type and device id, and
221 may be thought of as the equivalent of core event masks.
222
223 1.5 Input Classes
224 ~~~~~~~~~~~~~~~~~
225
226 Some of the input extension requests divide input devices into
227 classes based on their functionality. This is intended to allow
228 new classes of input devices to be defined at a later time
229 without changing the semantics of these requests. The following
230 input device classes are currently defined:
231
232    KEY
233           The device reports key events.
234
235    BUTTON
236           The device reports button events.
237
238    VALUATOR
239           The device reports valuator data in motion events.
240
241    PROXIMITY
242           The device reports proximity events.
243
244    FOCUS
245           The device can be focused and reports focus events.
246
247    FEEDBACK
248           The device supports feedbacks.
249
250    OTHER
251           The ChangeDeviceNotify, DeviceMappingNotify, and
252           DeviceStateNotify macros may be invoked passing the
253           XDevice structure returned for this device.
254
255 Each extension input device may support multiple input classes.
256 Additional classes may be added in the future. Requests that
257 support multiple input classes, such as the ListInputDevices
258 function that lists all available input devices, organize the
259 data they return by input class. Client programs that use these
260 requests should not access data unless it matches a class
261 defined at the time those clients were compiled. In this way,
262 new classes can be added without forcing existing clients that
263 use these requests to be recompiled.
264
265 2. Requests
266 -----------
267
268 Extension input devices are accessed by client programs through
269 the use of new protocol requests. This section summarizes the
270 new requests defined by this extension. The syntax and type
271 definitions used below follow the notation used for the X11
272 core protocol.
273
274 2.1 Getting the Extension Version
275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276
277 The GetExtensionVersion request returns version information
278 about the input extension.
279
280                     GetExtensionVersion
281                             name: STRING
282                     =>
283                             present: BOOL
284                             protocol-major-version: CARD16
285                             protocol-minor-version: CARD16
286
287 The protocol version numbers returned indicate the version of
288 the input extension supported by the target X server. The
289 version numbers can be compared to constants defined in the
290 header file XI.h. Each version is a superset of the previous
291 versions.
292
293 The name must be the name of the Input Extension as defined
294 in the header file XI.h.
295
296 2.2 Listing Available Devices
297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
298
299 A client that wishes to access a specific device must first
300 determine whether that device is connected to the X server.
301 This is done through the ListInputDevices request, which will
302 return a list of all devices that can be opened by the X
303 server.
304
305                 ListInputDevices
306                 =>
307                 input-devices: ListOfDeviceInfo
308
309 where
310
311                 DEVICEINFO:
312                         [type: ATOM
313                          id: CARD8
314                          num_classes: CARD8
315                          use: {IsXKeyboard, IsXPointer, IsXExtensionPointer,
316                                IsXExtensionKeyboard, IsExtensionDevice}
317                          info: LISTofINPUTINFO
318                          name: STRING8]
319
320                 INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO}
321                 KEYINFO:
322                         [class: CARD8
323                          length: CARD8
324                          min-keycode: KEYCODE
325                          max-keycode: KEYCODE
326                          num-keys: CARD16]
327                 BUTTONINFO:
328                         [class: CARD8
329                          length: CARD8
330                          num-buttons: CARD16]
331                 VALUATORINFO:
332                         [class: CARD8
333                          length: CARD8
334                          num_axes: CARD8
335                          mode: SETofDEVICEMODE
336                          motion_buffer_size: CARD32
337                          axes: LISTofAXISINFO]
338
339                 AXISINFO:
340                         [resolution: CARD32
341                          min-val: CARD32
342                          max-val: CARD32]
343                 DEVICEMODE: {Absolute, Relative}
344
345    Errors: None
346
347 This request returns a list of all devices that can be opened
348 by the X server, including the core X keyboard and X pointer.
349 Some implementations may open all input devices as part of X
350 initialization, while others may not open an input device until
351 requested to do so by a client program.
352
353 The information returned for each device is as follows:
354
355    type
356           The type field is of type Atom and indicates the nature
357           of the device. Clients may determine device types by
358           invoking the XInternAtom request passing one of the
359           names defined in the header file XI.h. The following
360           names have been defined to date:
361
362                                       MOUSE
363                                       TABLET
364                                       KEYBOARD
365                                       TOUCHSCREEN
366                                       TOUCHPAD
367                                       BUTTONBOX
368                                       BARCODE
369                                       KNOB_BOX
370                                       TRACKBALL
371                                       QUADRATURE
372                                       SPACEBALL
373                                       DATAGLOVE
374                                       EYETRACKER
375                                       CURSORKEYS
376                                       FOOTMOUSE
377                                       ID_MODULE
378                                       ONE_KNOB
379                                       NINE_KNOB
380                                       JOYSTICK
381
382
383    id
384           The id is a small cardinal value in the range 0-128 that
385           uniquely identifies the device. It is assigned to the
386           device when it is initialized by the server. Some
387           implementations may not open an input device until
388           requested by a client program, and may close the device
389           when the last client accessing it requests that it be
390           closed. If a device is opened by a client program via
391           XOpenDevice, then closed via XCloseDevice, then opened
392           again, it is not guaranteed to have the same id after
393           the second open request.
394
395    num_classes
396           The num_classes field is a small cardinal value in the
397           range 0-255 that specifies the number of input classes
398           supported by the device for which information is
399           returned by ListInputDevices. Some input classes, such
400           as class Focus and class Proximity do not have any
401           information to be returned by ListInputDevices.
402
403    use
404           The use field specifies how the device is currently
405           being used. If the value is IsXKeyboard, the device is
406           currently being used as the X keyboard. If the value is
407           IsXPointer, the device is currently being used as the X
408           pointer. If the value is IsXExtensionPointer, the device
409           is available for use as an extension pointer. If the value
410           is IsXExtensionKeyboard, the device is available for use as
411           and extension keyboard.
412           Older versions of XI report all extension devices as
413           IsXExtensionDevice.
414
415    name
416           The name field contains a pointer to a null-terminated
417           string that corresponds to one of the defined device
418           types.
419
420    InputInfo
421           InputInfo is one of: KeyInfo, ButtonInfo or
422           ValuatorInfo. The first two fields are common to all
423           three:
424
425         class
426                 The class field is a cardinal value in the range
427                 0-255. It uniquely identifies the class of input
428                 for which information is returned.
429
430         length
431                 The length field is a cardinal value in the range
432                 0-255. It specifies the number of bytes of data
433                 that are contained in this input class. The length
434                 includes the class and length fields.
435
436 The remaining information returned for input class
437 KEYCLASS is as follows:
438
439         min_keycode
440                 min_keycode is of type KEYCODE. It specifies the
441                 minimum keycode that the device will report. The
442                 minimum keycode will not be smaller than 8.
443
444         max_keycode
445                 max_keycode is of type KEYCODE. It specifies the
446                 maximum keycode that the device will report. The
447                 maximum keycode will not be larger than 255.
448
449         num_keys
450                 num_keys is a cardinal value that specifies the
451                 number of keys that the device has.
452
453 The remaining information returned for input class
454 BUTTONCLASS is as follows:
455
456         num_buttons
457                 num_buttons is a cardinal value that specifies the
458                 number of buttons that the device has.
459
460 The remaining information returned for input class
461 VALUATORCLASS is as follows:
462
463         mode
464                 mode is a constant that has one of the following
465                 values: Absolute or Relative. Some devices allow
466                 the mode to be changed dynamically via the
467                 SetDeviceMode request.
468
469         motion_buffer_size
470                 motion_buffer_size is a cardinal number that
471                 specifies the number of elements that can be
472                 contained in the motion history buffer for the
473                 device.
474
475         axes
476                 The axes field contains a pointer to an AXISINFO
477                 struture.
478
479 The information returned for each axis reported by the
480 device is:
481
482         resolution
483                 The resolution is a cardinal value in
484                 counts/meter.
485
486         min_val
487                 The min_val field is a cardinal value in that
488                 contains the minimum value the device reports for
489                 this axis. For devices whose mode is Relative, the
490                 min_val field will contain 0.
491
492         max_val
493                 The max_val field is a cardinal value in that
494                 contains the maximum value the device reports for
495                 this axis. For devices whose mode is Relative, the
496                 max_val field will contain 0.
497
498 2.3 Enabling Devices
499 ~~~~~~~~~~~~~~~~~~~~
500
501 Client programs that wish to access an extension device must
502 request that the server open that device. This is done via the
503 OpenDevice request.
504
505                 OpenDevice
506                         id: CARD8
507                 =>
508                 DEVICE:
509                         [device_id: XID
510                          num_classes: INT32
511                          classes: LISTofINPUTCLASSINFO]
512                 INPUTCLASSINFO:
513                          [input_class: CARD8
514                          event_type_base: CARD8]
515
516    Errors: Device
517
518 This request returns the event classes to be used by the client
519 to indicate which events the client program wishes to receive.
520 Each input class may report several event classes. For example,
521 input class Keys reports DeviceKeyPress and DeviceKeyRelease
522 event classes. Input classes are unique numbers registered with
523 the X Consortium. Input class Other exists to report event
524 classes that are not specific to any one input class, such as
525 DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify.
526
527 The information returned for each device is as follows:
528
529    device_id
530           The device_id is a number that uniquely identifies the
531           device.
532
533    num_classes
534           The num_classes field contains the number of input
535           classes supported by this device.
536
537    For each class of input supported by the device, the
538    InputClassInfo structure contains the following information:
539
540    input_class
541           The input_class is a small cardinal number that
542           identifies the class of input.
543
544    event_type_base
545           The event_type_base is a small cardinal number that
546           specifies the event type of one of the events reported
547           by this input class. This information is not directly
548           used by client programs. Instead, the Device is used by
549           macros that return extension event types and event
550           classes. This is described in the section of this
551           document entitled "Selecting Extension Device Events".
552
553 The information in the InputClassInfo reflects the state of
554 this device at the time the request was processed.
555
556 Before it exits, the client program should explicitly request
557 that the server close the device. This is done via the
558 CloseDevice request.
559
560 A client may open the same extension device more than once.
561 Requests after the first successful one return an additional
562 XDevice structure with the same information as the first, but
563 otherwise have no effect. A single CloseDevice request will
564 terminate that client's access to the device.
565
566 Closing a device releases any active or passive grabs the
567 requesting client has established. If the device is frozen only
568 by an active grab of the requesting client, the queued events
569 are released when the client terminates.
570
571 If a client program terminates without closing a device, the
572 server will automatically close that device on behalf of the
573 client. This does not affect any other clients that may be
574 accessing that device.
575
576                     CloseDevice:
577                             device: DEVICE
578
579    Errors: Device
580
581 2.4 Changing The Mode Of A Device
582 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
583
584 Some devices are capable of reporting either relative or
585 absolute motion data. To change the mode of a device from
586 relative to absolute, use the SetDeviceMode request. The valid
587 values are Absolute or Relative.
588
589 This request will fail and return DeviceBusy if another client
590 already has the device open with a different mode. It will fail
591 and return AlreadyGrabbed if another client has the device
592 grabbed. The request will fail with a BadMatch error if the
593 device has no valuators and reports no axes of motion. The
594 request will fail with a BadMode error if the requested mode
595 is not supported by the device.
596
597                     SetDeviceMode
598                             device:DEVICE
599                             mode: {Absolute, Relative}
600                     =>
601                             status: {Success, DeviceBusy, AlreadyGrabbed}
602
603    Errors: Device, Match, Mode
604
605 2.5 Initializing Valuators on an Input Device
606 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
607
608 Some devices that report absolute positional data can be
609 initialized to a starting value. Devices that are capable of
610 reporting relative motion or absolute positional data may
611 require that their valuators be initialized to a starting value
612 after the mode of the device is changed to Absolute. To
613 initialize the valuators on such a device, use the
614 SetDeviceValuators request.
615
616                 SetDeviceValuators
617                         device: DEVICE
618                         first_valuator: CARD8
619                         num_valuators: CARD8
620                         valuators: LISTOFINT32
621                 =>
622                         status: {Success, AlreadyGrabbed}
623
624    Errors: Length, Device, Match, Value
625
626 This request initializes the specified valuators on the
627 specified extension input device. Valuators are numbered
628 beginning with zero. Only the valuators in the range specified
629 by first_valuator and num_valuators are set. If the number of
630 valuators supported by the device is less than the expression
631 first_valuator + num_valuators, a Value error will result.
632
633 If the request succeeds, Success is returned. If the specifed
634 device is grabbed by some other client, the request will fail
635 and a status of AlreadyGrabbed will be returned.
636
637 2.6 Getting Input Device Controls
638 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
639
640                 GetDeviceControl
641                         device: DEVICE
642                         control: XID
643                 =>
644                 controlState: {DeviceState}
645
646 where
647
648                 DeviceState: DeviceResolutionState
649
650    Errors: Length, Device, Match, Value
651
652 This request returns the current state of the specified device
653 control. The device control must be supported by the target
654 server and device or an error will result.
655
656 If the request is successful, a pointer to a generic
657 DeviceState structure will be returned. The information
658 returned varies according to the specified control and is
659 mapped by a structure appropriate for that control.
660
661 GetDeviceControl will fail with a BadValue error if the server
662 does not support the specified control. It will fail with a
663 BadMatch error if the device does not support the specified
664 control.
665
666 Supported device controls and the information returned for them
667 include:
668
669                 DEVICE_RESOLUTION:
670                     [control: CARD16
671                     length: CARD16
672                     num_valuators: CARD8
673                     resolutions: LISTofCARD32
674                     min_resolutions: LISTofCARD32
675                     max_resolutions: LISTofCARD32]
676
677 This device control returns a list of valuators and the range
678 of valid resolutions allowed for each. Valuators are numbered
679 beginning with 0. Resolutions for all valuators on the device
680 are returned. For each valuator i on the device, resolutions[i]
681 returns the current setting of the resolution,
682 min_resolutions[i] returns the minimum valid setting, and
683 max_resolutions[i] returns the maximum valid setting.
684
685 When this control is specified, XGetDeviceControl will fail
686 with a BadMatch error if the specified device has no valuators.
687
688                 ChangeDeviceControl:
689                         device: DEVICE
690                         XID: controlId
691                         control: DeviceControl
692
693 where
694
695                 DeviceControl: DeviceResolutionControl
696                 =>
697                         status: {Success, DeviceBusy, AlreadyGrabbed}
698
699    Errors: Length, Device, Match, Value
700
701 ChangeDeviceControl changes the specifed device control
702 according to the values specified in the DeviceControl
703 structure. The device control must be supported by the target
704 server and device or an error will result.
705
706 The information passed with this request varies according to
707 the specified control and is mapped by a structure appropriate
708 for that control.
709
710 ChangeDeviceControl will fail with a BadValue error if the
711 server does not support the specified control. It will fail
712 with a BadMatch error if the server supports the specified
713 control, but the requested device does not. The request will
714 fail and return a status of DeviceBusy if another client
715 already has the device open with a device control state that
716 conflicts with the one specified in the request. It will fail
717 with a status of AlreadyGrabbed if some other client has
718 grabbed the specified device. If the request succeeds, Success
719 is returned. If it fails, the device control is left unchanged.
720
721 Supported device controls and the information specified for
722 them include:
723
724                 DEVICE_RESOLUTION:
725                         [control: CARD16
726                          length: CARD16
727                          first_valuator: CARD8
728                          num_valuators: CARD8
729                          resolutions: LISTofCARD32]
730
731 This device control changes the resolution of the specified
732 valuators on the specified extension input device. Valuators
733 are numbered beginning with zero. Only the valuators in the
734 range specified by first_valuator and num_valuators are set. A
735 value of -1 in the resolutions list indicates that the
736 resolution for this valuator is not to be changed.
737 num_valuators specifies the number of valuators in the
738 resolutions list.
739
740 When this control is specified, XChangeDeviceControl will fail
741 with a BadMatch error if the specified device has no valuators.
742 If a resolution is specified that is not within the range of
743 valid values (as returned by XGetDeviceControl) the request
744 will fail with a BadValue error. If the number of valuators
745 supported by the device is less than the expression
746 first_valuator + num_valuators, a BadValue error will result.
747
748 If the request fails for any reason, none of the valuator
749 resolutions will be changed.
750
751 ChangeDeviceControl causes the server to send a DevicePresence
752 event to interested clients.
753
754 2.7 Selecting Extension Device Events
755 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
756
757 Extension input events are selected using the
758 SelectExtensionEvent request.
759
760                 SelectExtensionEvent
761                         interest: LISTofEVENTCLASS
762                         window: WINDOW
763
764    Errors: Window, Class, Access
765
766 This request specifies to the server the events within the
767 specified window which are of interest to the client. As with
768 the core XSelectInput function, multiple clients can select
769 input on the same window.
770
771 XSelectExtensionEvent requires a list of event classes. An
772 event class is a 32-bit number that combines an event type and
773 device id, and is used to indicate which event a client wishes
774 to receive and from which device it wishes to receive it.
775 Macros are provided to obtain event classes from the data
776 returned by the XOpenDevice request. The names of these macros
777 correspond to the desired events, i.e. the DeviceKeyPress is
778 used to obtain the event class for DeviceKeyPress events. The
779 syntax of the macro invocation is:
780
781                  DeviceKeyPress (device, event_type, event_class);
782                      device: DEVICE
783                      event_type: INT
784                      event_class: INT
785
786 The value returned in event_type is the value that will be
787 contained in the event type field of the XDeviceKeyPressEvent
788 when it is received by the client. The value returned in
789 event_class is the value that should be passed in making an
790 XSelectExtensionEvent request to receive DeviceKeyPress events.
791
792 For DeviceButtonPress events, the client may specify whether or
793 not an implicit passive grab should be done when the button is
794 pressed. If the client wants to guarantee that it will receive
795 a DeviceButtonRelease event for each DeviceButtonPress event it
796 receives, it should specify the DeviceButtonPressGrab event
797 class as well as the DeviceButtonPress event class. This
798 restricts the client in that only one client at a time may
799 request DeviceButtonPress events from the same device and
800 window if any client specifies this class.
801
802 If any client has specified the DeviceButtonPressGrab class,
803 any requests by any other client that specify the same device
804 and window and specify DeviceButtonPress or
805 DeviceButtonPressGrab will cause an Access error to be
806 generated.
807
808 If only the DeviceButtonPress class is specified, no implicit
809 passive grab will be done when a button is pressed on the
810 device. Multiple clients may use this class to specify the same
811 device and window combination.
812
813 A client may also specify the DeviceOwnerGrabButton class. If
814 it has specified both the DeviceButtonPressGrab and the
815 DeviceOwnerGrabButton classes, implicit passive grabs will
816 activate with owner_events set to True. If only the
817 DeviceButtonPressGrab class is specified, implicit passive
818 grabs will activate with owner_events set to False.
819
820 The client may select DeviceMotion events only when a button is
821 down. It does this by specifying the event classes
822 Button1Motion through Button5Motion, or ButtonMotion. An input
823 device will only support as many button motion classes as it
824 has buttons.
825
826 2.8 Determining Selected Events
827 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
828
829 To determine which extension events are currently selected from
830 a given window, use GetSelectedExtensionEvents.
831
832                 GetSelectedExtensionEvents
833                         window: WINDOW
834                 =>
835                         this-client: LISTofEVENTCLASS
836                         all-clients: LISTofEVENTCLASS
837
838    Errors: Window
839
840 This request returns two lists specifying the events selected
841 on the specified window. One list gives the extension events
842 selected by this client from the specified window. The other
843 list gives the extension events selected by all clients from
844 the specified window. This information is equivalent to that
845 returned by your-event-mask and all-event-masks in a
846 GetWindowAttributes request.
847
848 2.9 Controlling Event Propagation
849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
850
851 Extension events propagate up the window hierarchy in the same
852 manner as core events. If a window is not interested in an
853 extension event, it usually propagates to the closest ancestor
854 that is interested, unless the dont_propagate list prohibits
855 it. Grabs of extension devices may alter the set of windows
856 that receive a particular extension event.
857
858 Client programs may control extension event propagation through
859 the use of the following two requests.
860
861 XChangeDeviceDontPropagateList adds an event to or deletes an
862 event from the do_not_propagate list of extension events for
863 the specified window. This list is maintained for the life of
864 the window, and is not altered if the client terminates.
865
866                 ChangeDeviceDontPropagateList
867                         window: WINDOW
868                         eventclass: LISTofEVENTCLASS
869                         mode: {AddToList, DeleteFromList}
870
871    Errors: Window, Class, Mode
872
873 This function modifies the list specifying the events that are
874 not propagated to the ancestors of the specified window. You
875 may use the modes AddToList or DeleteFromList.
876
877                 GetDeviceDontPropagateList
878                         window: WINDOW
879                 =>
880                         dont-propagate-list: LISTofEVENTCLASS
881
882    Errors: Window
883
884 This function returns a list specifying the events that are not
885 propagated to the ancestors of the specified window.
886
887 2.10 Sending Extension Events
888 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
889
890 One client program may send an event to another via the
891 XSendExtensionEvent function.
892
893 The event in the XEvent structure must be one of the events
894 defined by the input extension, so that the X server can
895 correctly byte swap the contents as necessary. The contents of
896 the event are otherwise unaltered and unchecked by the X server
897 except to force send_event to True in the forwarded event and
898 to set the sequence number in the event correctly.
899
900 XSendExtensionEvent returns zero if the conversion-to-wire
901 protocol failed, otherwise it returns nonzero.
902
903                 SendExtensionEvent
904                         device: DEVICE
905                         destination: WINDOW
906                         propagate: BOOL
907                         eventclass: LISTofEVENTCLASS
908                         event: XEVENT
909
910    Errors: Device, Value, Class, Window
911
912 2.11 Getting Motion History
913 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
914
915                 GetDeviceMotionEvents
916                         device: DEVICE
917                         start, stop: TIMESTAMP or CurrentTime
918                 =>
919                         nevents_return: CARD32
920                         mode_return: {Absolute, Relative}
921                         axis_count_return: CARD8
922                         events: LISTofDEVICETIMECOORD
923
924 where
925
926                 DEVICETIMECOORD:
927                         [data: LISTofINT32
928                          time: TIMESTAMP]
929
930    Errors: Device, Match
931
932 This request returns all positions in the device's motion
933 history buffer that fall between the specified start and stop
934 times inclusive. If the start time is in the future, or is
935 later than the stop time, no positions are returned.
936
937 The data field of the DEVICETIMECOORD structure is a sequence
938 of data items. Each item is of type INT32, and there is one
939 data item per axis of motion reported by the device. The number
940 of axes reported by the device is returned in the axis_count
941 variable.
942
943 The value of the data items depends on the mode of the device,
944 which is returned in the mode variable. If the mode is
945 Absolute, the data items are the raw values generated by the
946 device. These may be scaled by the client program using the
947 maximum values that the device can generate for each axis of
948 motion that it reports. The maximum and minimum values for each
949 axis are reported by the ListInputDevices request.
950
951 If the mode is Relative, the data items are the relative values
952 generated by the device. The client program must choose an
953 initial position for the device and maintain a current position
954 by accumulating these relative values.
955
956 2.12 Changing The Core Devices
957 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
958
959 These requests are provided to change which physical device is
960 used as the X pointer or X keyboard. These requests are
961 deprecated in servers supporting XI 1.4 and above, and will
962 always return a a BadDevice error.
963
964 Using these requests may change the characteristics of the core
965 devices. The new pointer device may have a different number of
966 buttons than the old one did, or the new keyboard device may
967 have a different number of keys or report a different range of
968 keycodes. Client programs may be running that depend on those
969 characteristics. For example, a client program could allocate
970 an array based on the number of buttons on the pointer device,
971 and then use the button numbers received in button events as
972 indicies into that array. Changing the core devices could cause
973 such client programs to behave improperly or abnormally
974 terminate.
975
976 These requests change the X keyboard or X pointer device and
977 generate an ChangeDeviceNotify event and a MappingNotify event.
978 The ChangeDeviceNotify event is sent only to those clients that
979 have expressed an interest in receiving that event via the
980 XSelectExtensionEvent request. The specified device becomes the
981 new X keyboard or X pointer device. The location of the core
982 device does not change as a result of this request.
983
984 These requests fail and return AlreadyGrabbed if either the
985 specified device or the core device it would replace are
986 grabbed by some other client. They fail and return GrabFrozen
987 if either device is frozen by the active grab of another
988 client.
989
990 These requests fail with a BadDevice error if the specified
991 device is invalid, or has not previously been opened via
992 OpenDevice. To change the X keyboard device, use the
993 ChangeKeyboardDevice request. The specified device must support
994 input class Keys (as reported in the ListInputDevices request)
995 or the request will fail with a BadMatch error. Once the device
996 has successfully replaced one of the core devices, it is
997 treated as a core device until it is in turn replaced by
998 another ChangeDevice request, or until the server terminates.
999 The termination of the client that changed the device will not
1000 cause it to change back. Attempts to use the CloseDevice
1001 request to close the new core device will fail with a BadDevice
1002 error.
1003
1004 The focus state of the new keyboard is the same as the focus
1005 state of the old X keyboard. If the new keyboard was not
1006 initialized with a FocusRec, one is added by the
1007 ChangeKeyboardDevice request. The X keyboard is assumed to have
1008 a KbdFeedbackClassRec. If the device was initialized without a
1009 KbdFeedbackClassRec, one will be added by this request. The
1010 KbdFeedbackClassRec will specify a null routine as the control
1011 procedure and the bell procedure.
1012
1013                 ChangeKeyboardDevice
1014                         device: DEVICE
1015                 =>
1016                         status: Success, AlreadyGrabbed, Frozen
1017
1018    Errors: Device, Match
1019
1020 To change the X pointer device, use the ChangePointerDevice
1021 request. The specified device must support input class
1022 Valuators (as reported in the ListInputDevices request) or the
1023 request will fail with a BadMatch error. The valuators to be
1024 used as the x- and y-axes of the pointer device must be
1025 specified. Data from other valuators on the device will be
1026 ignored.
1027
1028 The X pointer device does not contain a FocusRec. If the new
1029 pointer was initialized with a FocusRec, it is freed by the
1030 ChangePointerDevice request. The X pointer is assumed to have a
1031 ButtonClassRec and a PtrFeedbackClassRec. If the device was
1032 initialized without a ButtonClassRec or a PtrFeedbackClassRec,
1033 one will be added by this request. The ButtonClassRec added
1034 will have no buttons, and the PtrFeedbackClassRec will specify
1035 a null routine as the control procedure.
1036
1037 If the specified device reports absolute positional
1038 information, and the server implementation does not allow such
1039 a device to be used as the X pointer, the request will fail
1040 with a BadDevice error.
1041
1042 Once the device has successfully replaced one of the core
1043 devices, it is treated as a core device until it is in turn
1044 replaced by another ChangeDevice request, or until the server
1045 terminates. The termination of the client that changed the
1046 device will not cause it to change back. Attempts to use the
1047 CloseDevice request to close the new core device will fail with
1048 a BadDevice error.
1049
1050                 ChangePointerDevice
1051                         device: DEVICE
1052                         xaxis: CARD8
1053                         yaxis: CARD8
1054                 =>
1055                      status: Success, AlreadyGrabbed, Frozen
1056
1057    Errors: Device, Match
1058
1059 2.12 Event Synchronization And Core Grabs
1060 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1061
1062 Implementation of the input extension requires an extension of
1063 the meaning of event synchronization for the core grab
1064 requests. This is necessary in order to allow window managers
1065 to freeze all input devices with a single request.
1066
1067 The core grab requests require a pointer_mode and keyboard_mode
1068 argument. The meaning of these modes is changed by the input
1069 extension. For the XGrabPointer and XGrabButton requests,
1070 pointer_mode controls synchronization of the pointer device,
1071 and keyboard_mode controls the synchronization of all other
1072 input devices. For the XGrabKeyboard and XGrabKey requests,
1073 pointer_mode controls the synchronization of all input devices
1074 except the X keyboard, while keyboard_mode controls the
1075 synchronization of the keyboard. When using one of the core
1076 grab requests, the synchronization of extension devices is
1077 controlled by the mode specified for the device not being
1078 grabbed.
1079
1080 2.13 Extension Active Grabs
1081 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1082
1083 Active grabs of extension devices are supported via the
1084 GrabDevice request in the same way that core devices are
1085 grabbed using the core GrabKeyboard request, except that a
1086 Device is passed as a function parameter. A list of events that
1087 the client wishes to receive is also passed. The UngrabDevice
1088 request allows a previous active grab for an extension device
1089 to be released.
1090
1091 To grab an extension device, use the GrabDevice request. The
1092 device must have previously been opened using the OpenDevice
1093 request.
1094
1095                 GrabDevice
1096                         device: DEVICE
1097                         grab-window: WINDOW
1098                         owner-events: BOOL
1099                         event-list: LISTofEVENTCLASS
1100                         this-device-mode: {Synchronous, Asynchronous}
1101                         other-device-mode: {Synchronous, Asynchronous}
1102                         time:TIMESTAMP or CurrentTime
1103                 =>
1104                         status: Success, AlreadyGrabbed, Frozen,
1105                                 InvalidTime, NotViewable
1106
1107    Errors: Device, Window, Value
1108
1109 This request actively grabs control of the specified input
1110 device. Further input events from this device are reported only
1111 to the grabbing client. This request overrides any previous
1112 active grab by this client for this device.
1113
1114 The event-list parameter is a pointer to a list of event
1115 classes. These are used to indicate which events the client
1116 wishes to receive while the device is grabbed. Only event
1117 classes obtained from the grabbed device are valid.
1118
1119 If owner-events is False, input events generated from this
1120 device are reported with respect to grab-window, and are only
1121 reported if selected by being included in the event-list. If
1122 owner-events is True, then if a generated event would normally
1123 be reported to this client, it is reported normally, otherwise
1124 the event is reported with respect to the grab-window, and is
1125 only reported if selected by being included in the event-list.
1126 For either value of owner-events, unreported events are
1127 discarded.
1128
1129 If this-device-mode is Asynchronous, device event processing
1130 continues normally. If the device is currently frozen by this
1131 client, then processing of device events is resumed. If
1132 this-device-mode is Synchronous, the state of the grabbed
1133 device (as seen by means of the protocol) appears to freeze,
1134 and no further device events are generated by the server until
1135 the grabbing client issues a releasing AllowDeviceEvents
1136 request or until the device grab is released. Actual device
1137 input events are not lost while the device is frozen; they are
1138 simply queued for later processing.
1139
1140 If other-device-mode is Asynchronous, event processing is
1141 unaffected by activation of the grab. If other-device-mode is
1142 Synchronous, the state of all input devices except the grabbed
1143 one (as seen by means of the protocol) appears to freeze, and
1144 no further events are generated by the server until the
1145 grabbing client issues a releasing AllowDeviceEvents request or
1146 until the device grab is released. Actual events are not lost
1147 while the devices are frozen; they are simply queued for later
1148 processing.
1149
1150 This request generates DeviceFocusIn and DeviceFocusOut events.
1151
1152 This request fails and returns:
1153
1154    AlreadyGrabbed
1155           If the device is actively grabbed by some other client.
1156
1157    NotViewable
1158           If grab-window is not viewable.
1159
1160    InvalidTime
1161           If the specified time is earlier than the last-grab-time
1162           for the specified device or later than the current X
1163           server time. Otherwise, the last-grab-time for the
1164           specified device is set to the specified time and
1165           CurrentTime is replaced by the current X server time.
1166
1167    Frozen
1168           If the device is frozen by an active grab of another
1169           client.
1170
1171 If a grabbed device is closed by a client while an active grab
1172 by that client is in effect, that active grab will be released.
1173 Any passive grabs established by that client will be released.
1174 If the device is frozen only by an active grab of the
1175 requesting client, it is thawed.
1176
1177 To release a grab of an extension device, use UngrabDevice.
1178
1179                UngrabDevice
1180                        device: DEVICE
1181                        time: TIMESTAMP or CurrentTime
1182
1183    Errors: Device
1184
1185 This request releases the device if this client has it actively
1186 grabbed (from either GrabDevice or GrabDeviceKey) and releases
1187 any queued events. If any devices were frozen by the grab,
1188 UngrabDevice thaws them. The request has no effect if the
1189 specified time is earlier than the last-device-grab time or is
1190 later than the current server time.
1191
1192 This request generates DeviceFocusIn and DeviceFocusOut events.
1193
1194 An UngrabDevice is performed automatically if the event window
1195 for an active device grab becomes not viewable.
1196
1197 2.14 Passively Grabbing A Key
1198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1199
1200 Passive grabs of buttons and keys on extension devices are
1201 supported via the GrabDeviceButton and GrabDeviceKey requests.
1202 These passive grabs are released via the UngrabDeviceKey and
1203 UngrabDeviceButton requests.
1204
1205 To passively grab a single key on an extension device, use
1206 GrabDeviceKey. That device must have previously been opened
1207 using the OpenDevice request.
1208
1209             GrabDeviceKey
1210                     device: DEVICE
1211                     keycode: KEYCODE or AnyKey
1212                     modifiers: SETofKEYMASK or AnyModifier
1213                     modifier-device: DEVICE or NULL
1214                     grab-window: WINDOW
1215                     owner-events: BOOL
1216                     event-list: LISTofEVENTCLASS
1217                     this-device-mode: {Synchronous, Asynchronous}
1218                     other-device-mode: {Synchronous, Asynchronous}
1219
1220    Errors: Device, Match, Access, Window, Value
1221
1222 This request is analogous to the core GrabKey request. It
1223 establishes a passive grab on a device. Consequently, in the
1224 future:
1225
1226      * IF the device is not grabbed and the specified key, which
1227        itself can be a modifier key, is logically pressed when the
1228        specified modifier keys logically are down on the specified
1229        modifier device (and no other keys are down),
1230      * AND no other modifier keys logically are down,
1231      * AND EITHER the grab window is an ancestor of (or is) the
1232        focus window OR the grab window is a descendent of the
1233        focus window and contains the pointer,
1234      * AND a passive grab on the same device and key combination
1235        does not exist on any ancestor of the grab window,
1236      * THEN the device is actively grabbed, as for GrabDevice, the
1237        last-device-grab time is set to the time at which the key
1238        was pressed (as transmitted in the DeviceKeyPress event),
1239        and the DeviceKeyPress event is reported.
1240
1241 The interpretation of the remaining arguments is as for
1242 GrabDevice. The active grab is terminated automatically when
1243 logical state of the device has the specified key released
1244 (independent of the logical state of the modifier keys).
1245
1246 Note that the logical state of a device (as seen by means of
1247 the X protocol) may lag the physical state if device event
1248 processing is frozen.
1249
1250 A modifier of AnyModifier is equivalent to issuing the request
1251 for all possible modifier combinations (including the
1252 combination of no modifiers). It is not required that all
1253 modifiers specified have currently assigned keycodes. A key of
1254 AnyKey is equivalent to issuing the request for all possible
1255 keycodes. Otherwise, the key must be in the range specified by
1256 min-keycode and max-keycode in the ListInputDevices request. If
1257 it is not within that range, GrabDeviceKey generates a Value
1258 error.
1259
1260 NULL may be passed for the modifier_device. If the
1261 modifier_device is NULL, the core X keyboard is used as the
1262 modifier_device.
1263
1264 An Access error is generated if some other client has issued a
1265 GrabDeviceKey with the same device and key combination on the
1266 same window. When using AnyModifier or AnyKey, the request
1267 fails completely and the X server generates a Access error and
1268 no grabs are established if there is a conflicting grab for any
1269 combination.
1270
1271 This request cannot be used to grab a key on the X keyboard
1272 device. The core GrabKey request should be used for that
1273 purpose.
1274
1275 To release a passive grab of a single key on an extension
1276 device, use UngrabDeviceKey.
1277
1278            UngrabDeviceKey
1279                    device: DEVICE
1280                    keycode: KEYCODE or AnyKey
1281                    modifiers: SETofKEYMASK or AnyModifier
1282                    modifier-device: DEVICE or NULL
1283                    grab-window: WINDOW
1284
1285    Errors: Device, Match, Window, Value, Alloc
1286
1287 This request is analogous to the core UngrabKey request. It
1288 releases the key combination on the specified window if it was
1289 grabbed by this client. A modifier of AnyModifier is equivalent
1290 to issuing the request for all possible modifier combinations
1291 (including the combination of no modifiers). A key of AnyKey is
1292 equivalent to issuing the request for all possible keycodes.
1293 This request has no effect on an active grab.
1294
1295 NULL may be passed for the modifier_device. If the
1296 modifier_device is NULL, the core X keyboard is used as the
1297 modifier_device.
1298
1299 2.15 Passively Grabbing A Button
1300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1301
1302 To establish a passive grab for a single button on an extension
1303 device, use GrabDeviceButton.
1304
1305                 GrabDeviceButton
1306                         device: DEVICE
1307                         button: BUTTON or AnyButton
1308                         modifiers: SETofKEYMASK or AnyModifier
1309                         modifier-device: DEVICE or NULL
1310                         grab-window: WINDOW
1311                         owner-events: BOOL
1312                         event-list: LISTofEVENTCLASS
1313                         this-device-mode: {Synchronous, Asynchronous}
1314                         other-device-mode: {Synchronous, Asynchronous}
1315
1316    Errors: Device, Match, Window, Access, Value
1317
1318 This request is analogous to the core GrabButton request. It
1319 establishes an explicit passive grab for a button on an
1320 extension input device. Since the server does not track
1321 extension devices, no cursor is specified with this request.
1322 For the same reason, there is no confine-to parameter. The
1323 device must have previously been opened using the OpenDevice
1324 request.
1325
1326 The GrabDeviceButton request establishes a passive grab on a
1327 device. Consequently, in the future,
1328
1329    * IF the device is not grabbed and the specified button is
1330      logically pressed when the specified modifier keys
1331      logically are down (and no other buttons or modifier
1332      keys are down),
1333
1334    * AND the grab window contains the device,
1335
1336    * AND a passive grab on the same device and button/ key
1337      combination does not exist on any ancestor of the grab
1338      window,
1339
1340    * THEN the device is actively grabbed, as for GrabDevice,
1341      the last-grab time is set to the time at which the
1342      button was pressed (as transmitted in the
1343      DeviceButtonPress event), and the DeviceButtonPress
1344      event is reported.
1345
1346 The interpretation of the remaining arguments is as for
1347 GrabDevice. The active grab is terminated automatically when
1348 logical state of the device has all buttons released
1349 (independent of the logical state of the modifier keys).
1350
1351 Note that the logical state of a device (as seen by means of
1352 the X protocol) may lag the physical state if device event
1353 processing is frozen.
1354
1355 A modifier of AnyModifier is equivalent to issuing the request
1356 for all possible modifier combinations (including the
1357 combination of no modifiers). It is not required that all
1358 modifiers specified have currently assigned keycodes. A button
1359 of AnyButton is equivalent to issuing the request for all
1360 possible buttons. It is not required that the specified button
1361 be assigned to a physical button.
1362
1363 NULL may be passed for the modifier_device. If the
1364 modifier_device is NULL, the core X keyboard is used as the
1365 modifier_device.
1366
1367 An Access error is generated if some other client has issued a
1368 GrabDeviceButton with the same device and button combination on
1369 the same window. When using AnyModifier or AnyButton, the
1370 request fails completely and the X server generates a Access
1371 error and no grabs are established if there is a conflicting
1372 grab for any combination. The request has no effect on an
1373 active grab.
1374
1375 This request cannot be used to grab a button on the X pointer
1376 device. The core GrabButton request should be used for that
1377 purpose.
1378
1379 To release a passive grab of a button on an extension device,
1380 use UngrabDeviceButton.
1381
1382                 UngrabDeviceButton
1383                         device: DEVICE
1384                         button: BUTTON or AnyButton
1385                         modifiers: SETofKEYMASK or AnyModifier
1386                         modifier-device: DEVICE or NULL
1387                         grab-window: WINDOW
1388
1389    Errors: Device, Match, Window, Value, Alloc
1390
1391 This request is analogous to the core UngrabButton request. It
1392 releases the passive button/key combination on the specified
1393 window if it was grabbed by the client. A modifiers of
1394 AnyModifier is equivalent to issuing the request for all
1395 possible modifier combinations (including the combination of no
1396 modifiers). A button of AnyButton is equivalent to issuing the
1397 request for all possible buttons. This request has no effect on
1398 an active grab. The device must have previously been opened
1399 using the OpenDevice request otherwise a Device error will be
1400 generated.
1401
1402 NULL may be passed for the modifier_device. If the
1403 modifier_device is NULL, the core X keyboard is used as the
1404 modifier_device.
1405
1406 This request cannot be used to ungrab a button on the X pointer
1407 device. The core UngrabButton request should be used for that
1408 purpose.
1409
1410 2.16 Thawing A Device
1411 ~~~~~~~~~~~~~~~~~~~~~
1412
1413 To allow further events to be processed when a device has been
1414 frozen, use AllowDeviceEvents.
1415
1416                 AllowDeviceEvents
1417                         device: DEVICE
1418                         event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices,
1419                         ReplayThisdevice, AsyncAll, or SyncAll}
1420                         time:TIMESTAMP or CurrentTime
1421
1422    Errors: Device, Value
1423
1424 The AllowDeviceEvents request releases some queued events if
1425 the client has caused a device to freeze. The request has no
1426 effect if the specified time is earlier than the last-grab time
1427 of the most recent active grab for the client, or if the
1428 specified time is later than the current X server time.
1429
1430 The following describes the processing that occurs depending on
1431 what constant you pass to the event-mode argument:
1432
1433    * If the specified device is frozen by the client, event
1434      processing for that device continues as usual. If the
1435      device is frozen multiple times by the client on behalf
1436      of multiple separate grabs, AsyncThisDevice thaws for
1437      all. AsyncThisDevice has no effect if the specified
1438      device is not frozen by the client, but the device need
1439      not be grabbed by the client.
1440
1441    * If the specified device is frozen and actively grabbed
1442      by the client, event processing for that device
1443      continues normally until the next button or key event is
1444      reported to the client. At this time, the specified
1445      device again appears to freeze. However, if the reported
1446      event causes the grab to be released, the specified
1447      device does not freeze. SyncThisDevice has no effect if
1448      the specified device is not frozen by the client or is
1449      not grabbed by the client.
1450
1451    * If the specified device is actively grabbed by the
1452      client and is frozen as the result of an event having
1453      been sent to the client (either from the activation of a
1454      GrabDeviceButton or from a previous AllowDeviceEvents
1455      with mode SyncThisDevice, but not from a Grab), the grab
1456      is released and that event is completely reprocessed.
1457      This time, however, the request ignores any passive
1458      grabs at or above (towards the root) the grab-window of
1459      the grab just released. The request has no effect if the
1460      specified device is not grabbed by the client or if it
1461      is not frozen as the result of an event.
1462
1463    * If the remaining devices are frozen by the client, event
1464      processing for them continues as usual. If the other
1465      devices are frozen multiple times by the client on
1466      behalf of multiple separate grabs, AsyncOtherDevices
1467      “thaws” for all. AsyncOtherDevices has no effect if the
1468      devices are not frozen by the client, but those devices
1469      need not be grabbed by the client.
1470
1471    * If all devices are frozen by the client, event
1472      processing (for all devices) continues normally until
1473      the next button or key event is reported to the client
1474      for a grabbed device (button event for the grabbed
1475      device, key or motion event for the device), at which
1476      time the devices again appear to freeze. However, if the
1477      reported event causes the grab to be released, then the
1478      devices do not freeze (but if any device is still
1479      grabbed, then a subsequent event for it will still cause
1480      all devices to freeze). SyncAll has no effect unless all
1481      devices are frozen by the client. If any device is
1482      frozen twice by the client on behalf of two separate
1483      grabs, SyncAll "thaws" for both (but a subsequent freeze
1484      for SyncAll will only freeze each device once).
1485
1486    * If all devices are frozen by the client, event
1487      processing (for all devices) continues normally. If any
1488      device is frozen multiple times by the client on behalf
1489      of multiple separate grabs, AsyncAll "thaws" for all.
1490      AsyncAll has no effect unless all devices are frozen by
1491      the client.
1492
1493 AsyncThisDevice, SyncThisDevice, and ReplayThisDevice
1494 have no effect on the processing of events from the
1495 remaining devices. AsyncOtherDevices has no effect on
1496 the processing of events from the specified device. When
1497 the event_mode is SyncAll or AsyncAll, the device
1498 parameter is ignored.
1499
1500 It is possible for several grabs of different devices
1501 (by the same or different clients) to be active
1502 simultaneously. If a device is frozen on behalf of any
1503 grab, no event processing is performed for the device.
1504 It is possible for a single device to be frozen because
1505 of several grabs. In this case, the freeze must be
1506 released on behalf of each grab before events can again
1507 be processed.
1508
1509 2.17 Controlling Device Focus
1510 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1511
1512 The current focus window for an extension input device can be
1513 determined using the GetDeviceFocus request. Extension devices
1514 are focused using the SetDeviceFocus request in the same way
1515 that the keyboard is focused using the SetInputFocus request,
1516 except that a device is specified as part of the request. One
1517 additional focus state, FollowKeyboard, is provided for
1518 extension devices.
1519
1520 To get the current focus state, revert state, and focus time of
1521 an extension device, use GetDeviceFocus.
1522
1523                 GetDeviceFocus
1524                         device: DEVICE
1525                 =>
1526                         focus: WINDOW, PointerRoot, FollowKeyboard, or None
1527                         revert-to: Parent, PointerRoot, FollowKeyboard, or None
1528                         focus-time: TIMESTAMP
1529
1530    Errors: Device, Match
1531
1532 This request returns the current focus state, revert-to state,
1533 and last-focus-time of an extension device.
1534
1535 To set the focus of an extension device, use SetDeviceFocus.
1536
1537                 SetDeviceFocus
1538                         device: DEVICE
1539                         focus: WINDOW, PointerRoot, FollowKeyboard, or None
1540                         revert-to: Parent, PointerRoot, FollowKeyboard, or None
1541                         focus-time: TIMESTAMP
1542
1543    Errors: Device, Window, Value, Match
1544
1545 This request changes the focus for an extension input device
1546 and the last-focus-change-time. The request has no effect if
1547 the specified time is earlier than the last-focus-change-time
1548 or is later than the current X server time. Otherwise, the
1549 last-focus-change-time is set to the specified time, with
1550 CurrentTime replaced by the current server time.
1551
1552 The action taken by the server when this request is requested
1553 depends on the value of the focus argument:
1554
1555    * If the focus argument is None, all input events from
1556      this device will be discarded until a new focus window
1557      is set. In this case, the revert-to argument is ignored.
1558
1559    * If a window ID is assigned to the focus argument, it
1560      becomes the focus window of the device. If an input
1561      event from the device would normally be reported to this
1562      window or to one of its inferiors, the event is reported
1563      normally. Otherwise, the event is reported relative to
1564      the focus window.
1565
1566    * If you assign PointerRoot to the focus argument, the
1567      focus window is dynamically taken to be the root window
1568      of whatever screen the pointer is on at each input
1569      event. In this case, the revert-to argument is ignored.
1570
1571    * If you assign FollowKeyboard to the focus argument, the
1572      focus window is dynamically taken to be the same as the
1573      focus of the X keyboard at each input event.
1574      The specified focus window must be viewable at the time
1575      of the request (else a Match error). If the focus window
1576      later becomes not viewable, the X server evaluates the
1577      revert-to argument to determine the new focus window.
1578
1579    * If you assign RevertToParent to the revert-to argument,
1580      the focus reverts to the parent (or the closest viewable
1581      ancestor), and the new revert-to value is taken to be
1582      RevertToNone.
1583
1584    * If you assign RevertToPointerRoot,
1585      RevertToFollowKeyboard, or RevertToNone to the revert-to
1586      argument, the focus reverts to that value.
1587
1588 When the focus reverts, the X server generates DeviceFocusIn
1589 and DeviceFocusOut events, but the last-focus-change time is
1590 not affected.
1591
1592 This request causes the X server to generate DeviceFocusIn and
1593 DeviceFocusOut events.
1594
1595 2.18 Controlling Device Feedback
1596 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1597
1598 To get the settings of feedbacks on an extension device, use
1599 GetFeedbackControl. This request provides functionality
1600 equivalent to the core GetKeyboardControl and GetPointerControl
1601 functions. It also provides a way to control displays
1602 associated with an input device that are capable of displaying
1603 an integer or string.
1604
1605                 GetFeedbackControl
1606                         device: DEVICE
1607                 =>
1608                         num_feedbacks_return: CARD16
1609                         return_value: LISTofFEEDBACKSTATE
1610
1611 where
1612
1613                     FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState,
1614                                     IntegerFeedbackState, StringFeedbackState,
1615                                     BellFeedbackState, LedFeedbackState}
1616
1617 Feedbacks are reported by class. Those feedbacks that are
1618 reported for the core keyboard device are in class KbdFeedback,
1619 and are returned in the KbdFeedbackState structure. The members
1620 of that structure are as follows:
1621
1622                 CLASS Kbd:
1623                         [class: CARD8
1624                          length: CARD16
1625                          feedback id: CARD8
1626                          key_click_percent: CARD8
1627                          bell_percent: CARD8
1628                          bell_pitch: CARD16
1629                          bell_duration: CARD16
1630                          led_value: BITMASK
1631                          global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff}
1632                          auto_repeats: LISTofCARD8]
1633
1634 Those feedbacks that are equivalent to those reported for the
1635 core pointer are in feedback class PtrFeedback and are reported
1636 in the PtrFeedbackState structure. The members of that
1637 structure are:
1638
1639                 CLASS Ptr:
1640                         [class: CARD8
1641                          length: CARD16
1642                          feedback id: CARD8
1643                          accelNumerator: CARD16
1644                          accelDenominator: CARD16
1645                          threshold: CARD16]
1646
1647 Some input devices provide a means of displaying an integer.
1648 Those devices will support feedback class IntegerFeedback,
1649 which is reported in the IntegerFeedbackState structure. The
1650 members of that structure are:
1651
1652                   CLASS Integer:
1653                         [class: CARD8
1654                          length: CARD16
1655                          feedback id: CARD8
1656                          resolution: CARD32
1657                          min-val: INT32
1658                          max-val: INT32]
1659
1660 Some input devices provide a means of displaying a string.
1661 Those devices will support feedback class StringFeedback, which
1662 is reported in the StringFeedbackState structure. The members
1663 of that structure are:
1664
1665                   CLASS String:
1666                         [class: CARD8
1667                          length: CARD16
1668                          feedback id: CARD8
1669                          max_symbols: CARD16
1670                          num_keysyms_supported: CARD16
1671                          keysyms_supported: LISTofKEYSYM]
1672
1673 Some input devices contain a bell. Those devices will support
1674 feedback class BellFeedback, which is reported in the
1675 BellFeedbackState structure. The members of that structure are:
1676
1677                   CLASS Bell:
1678                         [class: CARD8
1679                          length: CARD16
1680                          feedback id: CARD8
1681                          percent: CARD8
1682                          pitch: CARD16
1683                          duration: CARD16]
1684
1685 The percent sets the base volume for the bell between 0 (off)
1686 and 100 (loud) inclusive, if possible. Setting to -1 restores
1687 the default. Other negative values generate a Value error.
1688
1689 The pitch sets the pitch (specified in Hz) of the bell, if
1690 possible. Setting to -1 restores the default. Other negative
1691 values generate a Value error.
1692
1693 The duration sets the duration (specified in milliseconds) of
1694 the bell, if possible. Setting to -1 restores the default.
1695 Other negative values generate a Value error.
1696
1697 A bell generator connected with the console but not directly on
1698 the device is treated as if it were part of the device. Some
1699 input devices contain LEDs. Those devices will support feedback
1700 class Led, which is reported in the LedFeedbackState structure.
1701 The members of that structure are:
1702
1703                   CLASS Led:
1704                         [class: CARD8
1705                          length: CARD16
1706                          feedback id: CARD8
1707                          led_mask: BITMASK
1708                          led_value: BITMASK]
1709
1710 Each bit in led_mask indicates that the corresponding led is
1711 supported by the feedback. At most 32 LEDs per feedback are
1712 supported. No standard interpretation of LEDs is defined.
1713
1714 This function will fail with a BadMatch error if the device
1715 specified in the request does not support feedbacks.
1716
1717    Errors: Device, Match
1718
1719 To change the settings of a feedback on an extension device,
1720 use ChangeFeedbackControl.
1721
1722                 ChangeFeedbackControl
1723                         device: DEVICE
1724                         feedbackid: CARD8
1725                         value-mask: BITMASK
1726                         value: FEEDBACKCONTROL
1727                         FEEDBACKCONTROL: {KBDFEEDBACKCONTROL,
1728                                           PTRFEEDBACKCONTROL,
1729                                           INTEGERFEEDBACKCONTROL,
1730                                           STRINGFEEDBACKCONTROL,
1731                                           BELLFEEDBACKCONTROL,
1732                                           LEDFEEDBACKCONTROL}
1733
1734    Errors: Device, Match, Value
1735
1736 Feedback controls are grouped by class. Those feedbacks that
1737 are equivalent to those supported by the core keyboard are
1738 controlled by feedback class KbdFeedbackClass using the
1739 KbdFeedbackControl structure. The members of that structure
1740 are:
1741
1742                 KBDFEEDBACKCTL
1743                         [class: CARD8
1744                          length: CARD16
1745                          feedback id: CARD8
1746                          key_click_percent: INT8
1747                          bell_percent: INT8
1748                          bell_pitch: INT16
1749                          bell_duration: INT16
1750                          led_mask: INT32
1751                          led_value: INT32
1752                          key: KEYCODE
1753                          auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff,
1754                                             AutoRepeatModeDefault}]
1755
1756 The key_click_percent sets the volume for key clicks between 0
1757 (off) and 100 (loud) inclusive, if possible. Setting to -1
1758 restores the default. Other negative values generate a Value
1759 error.
1760
1761 If both auto_repeat_mode and key are specified, then the
1762 auto_repeat_mode of that key is changed, if possible. If only
1763 auto_repeat_mode is specified, then the global auto-repeat mode
1764 for the entire keyboard is changed, if possible, without
1765 affecting the per-key settings. It is a Match error if a key is
1766 specified without an auto_repeat_mode.
1767
1768 The order in which controls are verified and altered is
1769 server-dependent. If an error is generated, a subset of the
1770 controls may have been altered.
1771
1772 Those feedback controls equivalent to those of the core pointer
1773 are controlled by feedback class PtrFeedbackClass using the
1774 PtrFeedbackControl structure. The members of that structure are
1775 as follows:
1776
1777                 PTRFEEDBACKCTL:
1778                         [class: CARD8
1779                          length: CARD16
1780                          feedback id: CARD8
1781                          accelNumerator: INT16
1782                          accelDenominator: INT16
1783                          threshold: INT16]
1784
1785 The acceleration, expressed as a fraction, is a multiplier for
1786 movement. For example, specifying 3/1 means the device moves
1787 three times as fast as normal. The fraction may be rounded
1788 arbitrarily by the X server. Acceleration only takes effect if
1789 the device moves more than threshold pixels at once and only
1790 applies to the amount beyond the value in the threshold
1791 argument. Setting a value to -1 restores the default. The
1792 values of the do-accel and do-threshold arguments must be
1793 nonzero for the device values to be set. Otherwise, the
1794 parameters will be unchanged. Negative values generate a Value
1795 error, as does a zero value for the accel-denominator argument.
1796
1797 Some devices are capable of displaying an integer. This is done
1798 using feedback class IntegerFeedbackClass using the
1799 IntegerFeedbackControl structure. The members of that structure
1800 are as follows:
1801
1802                 INTEGERCTL:
1803                         [class: CARD8
1804                          length: CARD16
1805                          feedback id: CARD8
1806                          int_to_display: INT32]
1807
1808 Some devices are capable of displaying a string. This is done
1809 using feedback class StringFeedbackClass using the
1810 StringFeedbackCtl structure. The members of that structure are
1811 as follows:
1812
1813                 STRINGCTL:
1814                         [class: CARD8
1815                          length: CARD16
1816                          feedback id: CARD8
1817                          syms_to_display: LISTofKEYSYMS]
1818
1819 Some devices contain a bell. This is done using feedback class
1820 BellFeedbackClass using the BellFeedbackControl structure. The
1821 members of that structure are as follows:
1822
1823                 BELLCTL:
1824                         [class: CARD8
1825                          length: CARD16
1826                          feedback id: CARD8
1827                          percent: INT8
1828                          pitch: INT16
1829                          duration: INT16]
1830
1831 Some devices contain leds. These can be turned on and off using
1832 the LedFeedbackControl structure. The members of that structure
1833 are as follows:
1834
1835                 LEDCTL:
1836                         [class: CARD8
1837                          length: CARD16
1838                          feedback id: CARD8
1839                          led_mask: BITMASK
1840                          led_value: BITMASK]
1841
1842    Errors: Device, Match, Value
1843
1844 2.20 Ringing a Bell on an Input Device
1845 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1846
1847 To ring a bell on an extension input device, use DeviceBell.
1848
1849                 DeviceBell:
1850                         device: DEVICE
1851                         feedbackclass: CARD8
1852                         feedbackid: CARD8
1853                         percent: INT8
1854
1855    Errors: Device, Value
1856
1857 This request is analogous to the core Bell request. It rings
1858 the specified bell on the specified input device feedback,
1859 using the specified volume. The specified volume is relative to
1860 the base volume for the feedback. If the value for the percent
1861 argument is not in the range -100 to 100 inclusive, a Value
1862 error results. The volume at which the bell rings when the
1863 percent argument is nonnegative is:
1864
1865                 base - [(base * percent) / 100] + percent
1866
1867 The volume at which the bell rings when the percent argument is
1868 negative is:
1869
1870                 base + [(base * percent) / 100]
1871
1872 To change the base volume of the bell, use
1873 ChangeFeedbackControl request.
1874
1875 Controlling Device Encoding
1876
1877 To get the keyboard mapping of an extension device that has
1878 keys, use GetDeviceKeyMapping.
1879
1880                 GetDeviceKeyMapping
1881                         device: DEVICE
1882                         first-keycode: KEYCODE
1883                         count: CARD8
1884                 =>
1885                         keysyms-per-keycode: CARD8
1886                         keysyms: LISTofKEYSYM
1887
1888    Errors: Device, Match, Value
1889
1890 This request returns the symbols for the specified number of
1891 keycodes for the specified extension device, starting with the
1892 specified keycode. The first-keycode must be greater than or
1893 equal to min-keycode as returned in the connection setup (else
1894 a Value error), and
1895
1896                 first-keycode + count - 1
1897
1898 must be less than or equal to max-keycode as returned in the
1899 connection setup (else a Value error). The number of elements
1900 in the keysyms list is
1901
1902                 count * keysyms-per-keycode
1903
1904 and KEYSYM number N (counting from zero) for keycode K has an
1905 index (counting from zero) of
1906
1907                 (K - first-keycode) * keysyms-per-keycode + N
1908
1909 in keysyms. The keysyms-per-keycode value is chosen arbitrarily
1910 by the server to be large enough to report all requested
1911 symbols. A special KEYSYM value of NoSymbol is used to fill in
1912 unused elements for individual keycodes.
1913
1914 If the specified device has not first been opened by this
1915 client via OpenDevice, or if that device does not support input
1916 class Keys, this request will fail with a Device error.
1917
1918 To change the keyboard mapping of an extension device that has
1919 keys, use ChangeDeviceKeyMapping.
1920
1921                 ChangeDeviceKeyMapping
1922                         device: DEVICE
1923                         first-keycode: KEYCODE
1924                         keysyms-per-keycode: CARD8
1925                         keysyms: LISTofKEYSYM
1926                         num_codes: CARD8
1927
1928    Errors: Device, Match, Value, Alloc
1929
1930 This request is analogous to the core ChangeKeyMapping request.
1931 It defines the symbols for the specified number of keycodes for
1932 the specified extension device. If the specified device has not
1933 first been opened by this client via OpenDevice, or if that
1934 device does not support input class Keys, this request will
1935 fail with a Device error.
1936
1937 The number of elements in the keysyms list must be a multiple
1938 of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping
1939 generates a Length error. The specified first_keycode must be
1940 greater than or equal to the min_keycode value returned by the
1941 ListInputDevices request, or this request will fail with a
1942 Value error. In addition, if the following expression is not
1943 less than the max_keycode value returned by the
1944 ListInputDevices request, the request will fail with a Value
1945 error:
1946
1947                 first_keycode + (num_codes / keysyms_per_keycode) - 1
1948
1949 To obtain the keycodes that are used as modifiers on an
1950 extension device that has keys, use GetDeviceModifierMapping.
1951
1952                 GetDeviceModifierMapping
1953                         device: DEVICE
1954                 =>
1955                         keycodes-per-modifier: CARD8
1956                         keycodes: LISTofKEYCODE
1957
1958    Errors: Device, Match
1959
1960 This request is analogous to the core GetModifierMapping
1961 request. This request returns the keycodes of the keys being
1962 used as modifiers. The number of keycodes in the list is
1963 8*keycodes-per-modifier. The keycodes are divided into eight
1964 sets, with each set containing keycodes-per-modifier elements.
1965 The sets are assigned in order to the modifiers Shift, Lock,
1966 Control, Mod1, Mod2, Mod3, Mod4, and Mod5. The
1967 keycodes-per-modifier value is chosen arbitrarily by the
1968 server; zeroes are used to fill in unused elements within each
1969 set. If only zero values are given in a set, the use of the
1970 corresponding modifier has been disabled. The order of keycodes
1971 within each set is chosen arbitrarily by the server.
1972
1973 To set which keycodes that are to be used as modifiers for an
1974 extension device, use SetDeviceModifierMapping.
1975
1976                 SetDeviceModifierMapping
1977                         device: DEVICE
1978                         keycodes-per-modifier: CARD8
1979                         keycodes: LISTofKEYCODE
1980                 =>
1981                         status: {Success, Busy, Failed}
1982
1983    Errors: Device, Match, Value, Alloc
1984
1985 This request is analogous to the core SetModifierMapping
1986 request. This request specifies the keycodes (if any) of the
1987 keys to be used as modifiers. The number of keycodes in the
1988 list must be 8*keycodes-per-modifier (else a Length error). The
1989 keycodes are divided into eight sets, with the sets, with each
1990 set containing keycodes-per-modifier elements. The sets are
1991 assigned in order to the modifiers Shift, Lock, Control, Mod1,
1992 Mod2, Mod3, Mod4, and Mod5. Only non-zero keycode values are
1993 used within each set; zero values are ignored. All of the
1994 non-zero keycodes must be in the range specified by min-keycode
1995 and max-keycode in the ListInputDevices request (else a Value
1996 error). The order of keycodes within a set does not matter. If
1997 no non-zero values are specified in a set, the use of the
1998 corresponding modifier is disabled, and the modifier bit will
1999 always be zero. Otherwise, the modifier bit will be one
2000 whenever at least one of the keys in the corresponding set is
2001 in the down position.
2002
2003 A server can impose restrictions on how modifiers can be
2004 changed (for example, if certain keys do not generate up
2005 transitions in hardware or if multiple keys per modifier are
2006 not supported). If some such restriction is violated, the status
2007 reply is MappingFailed, and none of the modifiers are changed.
2008
2009 If the new keycodes specified for a modifier differ from those
2010 currently defined and any (current or new) keys for that
2011 modifier are in the logically down state, the status reply is
2012 MappingBusy, and none of the modifiers are changed.
2013
2014 This request generates a DeviceMappingNotify event on a Success
2015 status. The DeviceMappingNotify event will be sent only to
2016 those clients that have expressed an interest in receiving that
2017 event via the XSelectExtensionEvent request.
2018
2019 2.20 Controlling Button Mapping
2020 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2021
2022 These requests are analogous to the core GetPointerMapping and
2023 ChangePointerMapping requests. They allow a client to determine
2024 the current mapping of buttons on an extension device, and to
2025 change that mapping.
2026
2027 To get the current button mapping for an extension device, use
2028 GetDeviceButtonMapping.
2029
2030                 GetDeviceButtonMapping
2031                         device: DEVICE
2032                         nmap: CARD8
2033                 =>
2034                         map_return: LISTofCARD8
2035
2036    Errors: Device, Match
2037
2038 The GetDeviceButtonMapping function returns the current mapping
2039 of the buttons on the specified device. Elements of the list
2040 are indexed starting from one. The length of the list indicates
2041 the number of physical buttons. The nominal mapping is the
2042 identity mapping map[i]=i.
2043
2044 nmap indicates the number of elements in the map_return array.
2045 Only the first nmap entries will be copied by the library into
2046 the map_return array.
2047
2048 To set the button mapping for an extension device, use
2049 SetDeviceButtonMapping.
2050
2051                 SetDeviceButtonMapping
2052                         device: DEVICE
2053                         map: LISTofCARD8
2054                         nmap: CARD8
2055                 =>
2056                         status: CARD8
2057
2058    Errors: Device, Match, Value
2059
2060 The SetDeviceButtonMapping function sets the mapping of the
2061 specified device and causes the X server to generate a
2062 DeviceMappingNotify event on a status of MappingSuccess.
2063 Elements of the list are indexed starting from one. The length
2064 of the list, specified in nmap, must be the same as
2065 GetDeviceButtonMapping would return. Otherwise,
2066 SetDeviceButtonMapping generates a Value error. A zero element
2067 disables a button, and elements are not restricted in value by
2068 the number of physical buttons. If any of the buttons to be
2069 altered are in the down state, the status reply is MappingBusy
2070 and the mapping is not changed.
2071
2072 In servers supporting XI 1.x, no two elements can have the same
2073 nonzero value. Otherwise, this function generates a Value
2074 error.
2075
2076 2.21 Obtaining The State Of A Device
2077 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2078
2079 To obtain vectors that describe the state of the keys, buttons
2080 and valuators of an extension device, use QueryDeviceState.
2081
2082                 QueryDeviceState
2083                         device: DEVICE
2084                 =>
2085                         device-id: CARD8
2086                         data: LISTofINPUTCLASS
2087
2088 where
2089
2090                 INPUTCLASS: {VALUATOR, BUTTON, KEY}
2091                 CLASS VALUATOR:
2092                             [class: CARD8
2093                              num_valuators: CARD8
2094                              mode: CARD8
2095                              #x01 device mode (0 = Relative, 1 = Absolute)
2096                              #x02 proximity state (0 = InProximity, 1 = OutOfProximity)
2097                              valuators: LISTofINT32]
2098                 CLASS BUTTON:
2099                             [class: CARD8
2100                              num_buttons: CARD8
2101                              buttons: LISTofCARD8]
2102                 CLASS KEY:
2103                             [class: CARD8
2104                              num_keys: CARD8
2105                              keys: LISTofCARD8]
2106
2107    Errors: Device
2108
2109 The QueryDeviceState request returns the current logical state
2110 of the buttons, keys, and valuators on the specified input
2111 device. The buttons and keys arrays, byte N (from 0) contains
2112 the bits for key or button 8N to 8N+7 with the least
2113 significant bit in the byte representing key or button 8N.
2114
2115 If the device has valuators, a bit in the mode field indicates
2116 whether the device is reporting Absolute or Relative data. If
2117 it is reporting Absolute data, the valuators array will contain
2118 the current value of the valuators. If it is reporting Relative
2119 data, the valuators array will contain undefined data.
2120
2121 If the device reports proximity information, a bit in the mode
2122 field indicates whether the device is InProximity or
2123 OutOfProximity.
2124
2125 2.22 Listing Device Properties
2126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2127
2128 Introduced with XI 1.5
2129
2130             ListDeviceProperties
2131                      deviceid: CARD8
2132             =>
2133                      nAtoms: CARD16
2134                      Atoms: LISTofATOM
2135
2136    Errors: Device
2137
2138 Each device can store an arbitrary number of properties. These
2139 properties can be allocated by either the client or the driver.
2140 The client can change device properties and the server
2141 guarantees that the device driver is notified about a change of
2142 the device's properties.
2143
2144 ListDeviceProperties returns all properties of a device. The
2145 client is expected to retrieve details about the properties it
2146 is interested in separately.
2147
2148 2.23 Getting a Device Property
2149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2150
2151 Introduced with XI 1.5
2152
2153             GetDeviceProperty:
2154                      property: ATOM
2155                      type: ATOM
2156                      longOffset: CARD32
2157                      longLength: CARD32
2158                      deviceid: CARD8
2159                      delete: BOOL
2160             =>
2161                      propertyType: ATOM
2162                      bytesAfter: CARD32
2163                      nItems: CARD32
2164                      format: CARD8
2165                      deviceid: CARD8
2166                      data: [LISTofCARD8]
2167
2168    Errors: Atom, Device, Value, Access
2169
2170 Retrieve the value for a property. If the property does not
2171 exist, propertyType is None and all other fields are undefined.
2172
2173 If type is not AnyPropertyType and does not match the
2174 property's actual type, the propertyType, bytesAfter, and
2175 format are returned but not the actual data.
2176
2177 longOffset and longLength specify the offset and length
2178 respectively in 32-bit multiples of the data to retrieve.
2179
2180 If delete is True, the property is deleted after querying its
2181 data. If the property cannot be deleted, a BadAccess error is
2182 returned.
2183
2184 propertyType returns the atom identifier that defines the
2185 actual type of the property.
2186
2187 If bytesAfter is non-zero, it specifies the number of data
2188 4-byte units after the retrieved chunk of data.
2189
2190 format specifies whether the data should be viewed as a list of
2191 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16,
2192 and 32. This information allows the X server to correctly
2193 perform byte-swap operations as necessary.
2194
2195 nItem specifies the number of 8-bit, 16-bit, or 32-bit items
2196 returned after the request.
2197
2198 2.24 Changing a Device Property
2199 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2200
2201 Introduced with XI 1.5
2202
2203             ChangeDeviceProperty:
2204                      property: ATOM
2205                      type: ATOM
2206                      deviceid: CARD8
2207                      format: CARD8
2208                      mode: CARD8
2209                      nUnits: CARD32
2210
2211    Errors: Atom, Device, Value, Match, Access
2212
2213 Changes the value of a specified property.
2214
2215 The type specifies the atom identifier that defines the type of
2216 the property. If mode is not PropModeReplace, the type must
2217 match the current type of the property or a BadMatch error is
2218 returned.
2219
2220 format specifies whether the data should be viewed as a list of
2221 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16,
2222 and 32. This information allows the X server to correctly
2223 perform byte-swap operations as necessary.
2224
2225 If mode is PropModeReplace, a preexising value for this
2226 property is replaced with the new value. If mode is
2227 PropModePrepend or PropModeAppend, the value is prepended or
2228 appended, respectively, to the current value of the property.
2229
2230 nUnits specifies the number of 8-bit, 16-bit, or 32-bit items
2231 supplied after the reply.
2232
2233 Changing a device property results in a
2234 DevicePropertyNotifyEvent being sent to all clients.
2235
2236 2.25 Deleting a Device Property
2237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2238
2239 Introduced with XI 1.5
2240
2241             DeleteDeviceProperty:
2242                      property: ATOM
2243                      deviceid: CARD8
2244
2245    Errors: Atom, Device, Match, Access.
2246
2247 Deletes the specified property. If the property cannot be
2248 deleted by the client, a BadAccess error is returned.
2249
2250 3. Events
2251 ---------
2252
2253 The input extension creates input events analogous to the core
2254 input events. These extension input events are generated by
2255 manipulating one of the extension input devices.
2256
2257 3.1 Button, Key, and Motion Events
2258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2259
2260             DeviceKeyPress
2261             DeviceKeyRelease
2262             DeviceButtonPress,
2263             DeviceButtonRelease
2264             DeviceMotionNotify
2265                     device: CARD8
2266                     root, event: WINDOW
2267                     child: Window or None
2268                     same-screen: BOOL
2269                     root-x, root-y, event-x, event-y: INT16
2270                     detail: <see below>
2271                     state: SETofKEYBUTMASK
2272                     time: TIMESTAMP
2273
2274 These events are generated when a key, button, or valuator
2275 logically changes state. The generation of these logical
2276 changes may lag the physical changes, if device event
2277 processing is frozen. Note that DeviceKeyPress and
2278 DeviceKeyRelease are generated for all keys, even those mapped
2279 to modifier bits. The “source” of the event is the window the
2280 pointer is in. The window with respect to which the event is
2281 normally reported is found by looking up the hierarchy
2282 (starting with the source window) for the first window on which
2283 any client has selected interest in the event. The actual
2284 window used for reporting can be modified by active grabs and
2285 by the focus window.The window the event is reported with
2286 respect to is called the “event” window.
2287
2288 The root is the root window of the “source” window, and root-x
2289 and root-y are the pointer coordinates relative to root's
2290 origin at the time of the event. Event is the “event” window.
2291 If the event window is on the same screen as root, then event-x
2292 and event-y are the pointer coordinates relative to the event
2293 window's origin. Otherwise, event-x and event-y are zero. If
2294 the source window is an inferior of the event window, then
2295 child is set to the child of the event window that is an
2296 ancestor of (or is) the source window. Otherwise, it is set to
2297 None.
2298
2299 The state component gives the logical state of the buttons on
2300 the X pointer and modifier keys on the core X keyboard just
2301 before the event.
2302
2303 The detail component type varies with the event type:
2304 Event               Component
2305 DeviceKeyPress      KEYCODE
2306 DeviceKeyRelease    KEYCODE
2307 DeviceButtonPress   BUTTON
2308 DeviceButtonRelease BUTTON
2309 DeviceMotionNotify  { Normal , Hint }
2310
2311 The granularity of motion events is not guaranteed, but a
2312 client selecting for motion events is guaranteed to get at
2313 least one event when a valuator changes. If DeviceMotionHint is
2314 selected, the server is free to send only one
2315 DeviceMotionNotify event (with detail Hint) to the client for
2316 the event window, until either a key or button changes state,
2317 the pointer leaves the event window, or the client issues a
2318 QueryDeviceState or GetDeviceMotionEvents request.
2319
2320 3.2 DeviceValuator Event
2321 ~~~~~~~~~~~~~~~~~~~~~~~~
2322
2323                 DeviceValuator
2324                         device: CARD8
2325                         device_state: SETofKEYBUTMASK
2326                         num_valuators: CARD8
2327                         first_valuator: CARD8
2328                         valuators: LISTofINT32
2329
2330 DeviceValuator events are generated to contain valuator
2331 information for which there is insufficient space in DeviceKey,
2332 DeviceButton, DeviceMotion, and Proximity wire events. For
2333 events of these types, a second event of type DeviceValuator
2334 follows immediately. The library combines these events into a
2335 single event that a client can receive via XNextEvent.
2336 DeviceValuator events are not selected for by clients, they
2337 only exist to contain information that will not fit into some
2338 event selected by clients.
2339
2340 The device_state component gives the state of the buttons and
2341 modifiers on the device generating the event.
2342
2343 Extension motion devices may report motion data for a variable
2344 number of axes. The valuators array contains the values of all
2345 axes reported by the device. If more than 6 axes are reported,
2346 more than one DeviceValuator event will be sent by the server,
2347 and more than one DeviceKey, DeviceButton, DeviceMotion, or
2348 Proximity event will be reported by the library. Clients should
2349 examine the corresponding fields of the event reported by the
2350 library to determine the total number of axes reported, and the
2351 first axis reported in the current event. Axes are numbered
2352 beginning with zero.
2353
2354 For Button, Key and Motion events on a device reporting
2355 absolute motion data the current value of the device's
2356 valuators is reported. For devices that report relative data,
2357 Button and Key events may be followed by a DeviceValuator event
2358 that contains 0s in the num_valuators field. In this case, only
2359 the device_state component will have meaning.
2360
2361 3.3 Device Focus Events
2362 ~~~~~~~~~~~~~~~~~~~~~~~
2363
2364                 DeviceFocusIn
2365                 DeviceFocusOut
2366                         device: CARD8
2367                         time: TIMESTAMP
2368                         event: WINDOW
2369                         mode: { Normal, WhileGrabbed, Grab, Ungrab}
2370                         detail: { Ancestor, Virtual, Inferior, Nonlinear,
2371                                   NonlinearVirtual, Pointer, PointerRoot, None}
2372
2373 These events are generated when the input focus changes and are
2374 reported to clients selecting DeviceFocusChange for the
2375 specified device and window. Events generated by SetDeviceFocus
2376 when the device is not grabbed have mode Normal. Events
2377 generated by SetDeviceFocus when the device is grabbed have
2378 mode WhileGrabbed. Events generated when a device grab activates
2379 have mode Grab, and events generated when a device grab
2380 deactivates have mode Ungrab.
2381
2382 All DeviceFocusOut events caused by a window unmap are
2383 generated after any UnmapNotify event, but the ordering of
2384 DeviceFocusOut with respect to generated EnterNotify,
2385 LeaveNotify, VisibilityNotify and Expose events is not
2386 constrained.
2387
2388 DeviceFocusIn and DeviceFocusOut events are generated for focus
2389 changes of extension devices in the same manner as focus events
2390 for the core devices are generated.
2391
2392 3.4 Device State Notify Event
2393 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2394
2395                 DeviceStateNotify
2396                 time: TIMESTAMP
2397                 device: CARD8
2398                 num_keys: CARD8
2399                 num_buttons: CARD8
2400                 num_valuators: CARD8
2401                 classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass}
2402                     SetOfDeviceMode:
2403                         #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity
2404                         #x40 Device Mode (0 = Relative, 1 = Absolute)
2405                     SetOfInputClass: #x04 reporting valuators
2406                         #x02 reporting buttons
2407                         #x01 reporting keys
2408                 buttons: LISTofCARD8
2409                 keys: LISTofCARD8
2410                 valuators: LISTofCARD32
2411
2412 This event reports the state of the device just as in the
2413 QueryDeviceState request. This event is reported to clients
2414 selecting DeviceStateNotify for the device and window and is
2415 generated immediately after every EnterNotify and
2416 DeviceFocusIn. If the device has no more than 32 buttons, no
2417 more than 32 keys, and no more than 3 valuators, This event can
2418 report the state of the device. If the device has more than 32
2419 buttons, the event will be immediately followed by a
2420 DeviceButtonStateNotify event. If the device has more than 32
2421 keys, the event will be followed by a DeviceKeyStateNotify
2422 event. If the device has more than 3 valuators, the event will
2423 be followed by one or more DeviceValuator events.
2424
2425 3.5 Device KeyState and ButtonState Notify Events
2426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2427
2428                 DeviceKeyStateNotify
2429                         device: CARD8
2430                         keys: LISTofCARD8
2431                 DeviceButtonStateNotify
2432                         device: CARD8
2433                         buttons: LISTofCARD8
2434
2435 These events contain information about the state of keys and
2436 buttons on a device that will not fit into the
2437 DeviceStateNotify wire event. These events are not selected by
2438 clients, rather they may immediately follow a DeviceStateNotify
2439 wire event and be combined with it into a single
2440 DeviceStateNotify client event that a client may receive via
2441 XNextEvent.
2442
2443 3.6 DeviceMappingNotify Event
2444 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2445
2446                 DeviceMappingNotify
2447                         time: TIMESTAMP
2448                         device: CARD8
2449                         request: CARD8
2450                         first_keycode: CARD8
2451                         count: CARD8
2452
2453 This event reports a change in the mapping of keys, modifiers,
2454 or buttons on an extension device. This event is reported to
2455 clients selecting DeviceMappingNotify for the device and window
2456 and is generated after every client SetDeviceButtonMapping,
2457 ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request.
2458
2459 3.7 ChangeDeviceNotify Event
2460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2461
2462                 ChangeDeviceNotify
2463                         device: CARD8
2464                         time: TIMESTAMP
2465                         request: CARD8
2466
2467 This event reports a change in the physical device being used
2468 as the core X keyboard or X pointer device. ChangeDeviceNotify
2469 events are reported to clients selecting ChangeDeviceNotify for
2470 the device and window and is generated after every client
2471 ChangeKeyboardDevice or ChangePointerDevice request.
2472
2473 3.7 Proximity Events
2474 ~~~~~~~~~~~~~~~~~~~~
2475
2476                 ProximityIn
2477                 ProximityOut
2478                         device: CARD8
2479                         root, event: WINDOW
2480                         child: Window or None
2481                         same-screen: BOOL
2482                         root-x, root-y, event-x, event-y: INT16
2483                         state: SETofKEYBUTMASK
2484                         time: TIMESTAMP
2485                         device-state: SETofKEYBUTMASK
2486                         axis-count: CARD8
2487                         first-axis: CARD8
2488                         axis-data: LISTofINT32
2489
2490 These events are generated by some devices (such as graphics
2491 tablets or touchscreens) to indicate that a stylus has moved
2492 into or out of contact with a positional sensing surface.
2493
2494 The “source” of the event is the window the pointer is in. The
2495 window with respect to which the event is normally reported is
2496 found by looking up the hierarchy (starting with the source
2497 window) for the first window on which any client has selected
2498 interest in the event. The actual window used for reporting can
2499 be modified by active grabs and by the focus window.The window
2500 the event is reported with respect to is called the “event”
2501 window.
2502
2503 The root is the root window of the “source” window, and root-x
2504 and root-y are the pointer coordinates relative to root's
2505 origin at the time of the event. Event is the “event” window.
2506 If the event window is on the same screen as root, then event-x
2507 and event-y are the pointer coordinates relative to the event
2508 window's origin. Otherwise, event-x and event-y are zero. If
2509 the source window is an inferior of the event window, then
2510 child is set to the child of the event window that is an
2511 ancestor of (or is) the source window. Otherwise, it is set to
2512 None. The state component gives the logical state of the
2513 buttons on the core X pointer and modifier keys on the core X
2514 keyboard just before the event. The device-state component
2515 gives the state of the buttons and modifiers on the device
2516 generating the event.
2517
2518 3.8 DevicePresenceEvents
2519 ~~~~~~~~~~~~~~~~~~~~~~~~
2520
2521 Introduced with XI 1.4.
2522
2523                 DevicePresence
2524                         time: TIMESTAMP
2525                         devchange: BYTE
2526                             #x00: DeviceAdded
2527                             #x01: DeviceRemoved
2528                             #x02: DeviceEnabled
2529                             #x03: DeviceDisabled
2530                             #x04: DeviceUnrecoverable
2531                             #x05: DeviceControlChanged
2532                         deviceid: BYTE
2533                         control: CARD16
2534
2535 DevicePresence events are sent when the server adds or removes,
2536 or enables or disables an input device. The client is expected
2537 to query the server for the list of input devices using the
2538 ListInputDevices request to obtain the updated list of input
2539 devices. DevicePresence events are also sent when a control on
2540 the device has been changed.
2541
2542 The devchange field specifies the type of operation. In case of
2543 DeviceAdded, a new device has been added to the server, but
2544 this device does not yet send events. If devchange is set to
2545 DeviceEnabled, the device is enabled and will generate events.
2546 If the field is DeviceDisabled or DeviceRemoved, the given
2547 device is disabled and stops sending events or was removed from
2548 the server, respectively. If the field is DeviceUnrecoverable,
2549 an IO-error has occured on the device and the device is
2550 forcibly disabled and removed by the server. If devchange is
2551 DeviceControlChanged, control specifies the type of control
2552 that has been changed.
2553
2554 3.9 DevicePropertyNotifyEvent
2555 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2556
2557 Introduced with XI 1.5.
2558
2559                 DevicePropertyNotifyEvent
2560                         deviceid: CARD8
2561                         state: CARD8
2562                         time: TIMESTAMP
2563                         atom: ATOM
2564
2565 A DevicePropertyNotifyEvent is sent to all clients when a
2566 property on the device is created, deleted, or changes value.
2567
2568 The deviceid specifies the device which's property has been
2569 modified.
2570
2571 The atom specifies the named identifier of the property that
2572 has been altered.
2573
2574 If state is PropertyNewValue, the given property has a new
2575 value or has been newly created. If state is PropertyDeleted,
2576 the given property has been deleted.