1 The X Input Extension 2.x
2 =========================
8 - Peter Hutterer (Red Hat) <peter.hutterer@redhat.com>
9 - Daniel Stone (Collabora Ltd.) <daniel@fooishbar.org>
10 - Chase Douglas (Canonical, Ltd.) <chase.douglas@canonical.com>
16 - v2.2, March 2012: Multitouch support added
17 - v2.1, December 2011: new raw event behaviour, smooth scrolling support
19 - v2.0, October 2009: Initial release of XI2 protocol
25 The X Input Extension version 2.0 (XI2) is the second major release of the X
28 XI2 provides a number of enhancements over version 1.5, including:
30 - use of XGE and GenericEvents. GenericEvents are of flexible length with a
31 minimum length of 32 bytes.
32 - explicit device hierarchy of master and slave devices. See Section
33 <<hierarchy,The Master/Slave device hierarchy>>.
34 - use of multiple independent master devices (Multi-Poiner X or MPX).
35 - the ability for devices to change capabilities at runtime.
38 XI2's intent is to replace both core input processing and prior versions of
39 the X Input Extension. Historically, the majority of applications employed the
40 core protocol requests and events to handle user input. The core protocol does
41 not provide information about which device generated the event. The X Input
42 Extension version up to 1.5 requires the differentiation between core and
43 extended devices. Extended devices may not be core devices and thus cannot be
44 used on applications employing the core protocol. XI2 addresses both of these
45 issues by enabling devices to be both extended and core devices and providing
46 device information in each event (with the exception of core events).
48 Changes in version 2.1
49 ----------------------
51 - RawEvents are sent regardless of the grab state.
52 - Addition of the ScrollClass for smooth scrolling
54 Changes in version 2.2
55 ----------------------
57 - Multitouch support added
62 Notations used in this document
63 -------------------------------
65 Notation for requests:
69 name of request field: type of request field
70 name of request field: type of request field
72 name of reply field: type of reply field
79 name of field: type of field
80 name of field: type of field
83 Complex fields are specified in the following notation:
85 name of field: COMPLEXFIELDTYPE
87 or, if multiple of these fields exist:
89 name of field: LISTofCOMPLEXFIELDTYPE
91 COMPLEXFIELDTYPE: { name of subfield: type of subfield,
92 name of subfield: type of subfield }
96 Interoperability between version 1.x and 2.0
97 --------------------------------------------
99 There is little interaction between 1.x and 2.x versions of the X Input
100 Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as
101 possible. Several direct incompatibilities are observable:
103 [[interop-xi1-limitations]]
104 Limitations resulting from different variable ranges
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107 XI2 provides a larger range for some fields than XI1. As a result, XI1 clients
108 may not receive data an XI2 client receives.
109 These fields include:
111 - devices with a deviceid of greater than 127 are invisible to XI1 clients.
112 - key events and key grabs featuring larger than 255 can only be sent to XI2
114 - no subpixel information is available to XI1 clients. If motion events are in
115 a subpixel range only, the server may omit these events and an XI 1.x client
116 will not receive events until the pixel boundary is crossed.
119 [[interop-xi1-grabs]]
123 XI1 grabs are different to XI2 grab and a device may not be grabbed through an
124 XI2 grab if an XI1 grab is currently active on this device or vice versa.
125 Likewise, a keycode or button already grabbed by an XI 1.x or XI2 client may
126 not be grabbed with the same modifier combination by an XI2 or XI 1.x client,
129 [[interop-xi1-device-list]]
130 Invisibility of Master Devices
131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 XI 1.x was not designed with support for multiple master devices. As a
134 result, only the first master pointer and master keyboard are visible to XI
135 1.x clients; all other master devices are invisible and cannot be accessed
141 Historically, X implemented scrolling events by using button press events:
142 button 4 was one “click” of the scroll wheel upwards, button 5 was downwards,
143 button 6 was one unit of scrolling left, and button 7 was one unit of scrolling
144 right. This is insufficient for e.g. touchpads which are able to provide
145 scrolling events through multi-finger drag gestures, or simply dragging your
146 finger along a designated strip along the side of the touchpad.
148 Newer X servers may provide scrolling information through valuators to
149 provide clients with more precision than the legacy button events. This
150 scrolling information is part of the valuator data in device events.
151 Scrolling events do not have a specific event type.
153 Valuators for axes sending scrolling information must have one
154 ScrollClass for each scrolling axis. If scrolling valuators are present on a
155 device, the server must provide two-way emulation between these valuators
156 and the legacy button events for each delta unit of scrolling.
158 One unit of scrolling in either direction is considered to be equivalent to
159 one button event, e.g. for a unit size of 1.0, -2.0 on an valuator type
160 Vertical sends two button press/release events for button 4. Likewise, a
161 button press event for button 7 generates an event on the Horizontal
162 valuator with a value of +1.0. The server may accumulate deltas of less than
163 one unit of scrolling.
165 Any server providing this behaviour marks emulated button or valuator events
166 with the XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag
167 for raw events, to hint at applications which event is a hardware event.
169 If more than one scroll valuator of the same type is present on a device,
170 the valuator marked with Preferred for the same scroll direction is used to
171 convert legacy button events into scroll valuator events. If no valuator is
172 marked Preferred or more than one valuator is marked with Preferred for this
173 scroll direction, this should be considered a driver bug and the behaviour
174 is implementation-dependent.
177 The Master/Slave device hierarchy
178 ---------------------------------
180 XI2 introduces a device hierarchy split up into so-called Master Devices (MD)
181 and Slave Devices (SD).
186 An MD is a virtual device created and managed by the server. MDs may send core
187 events and XI events. However, an MD does not represent a physical device and
188 relies on SDs for event generation. MDs come in two forms: as master pointers
189 or as master keyboards. A master pointer is represented by a visible cursor on
190 the screen. A master keyboard is represented by a keyboard focus.
192 Each master pointer is paired with the respective master keyboard and vice
193 versa, and this pairing is constant for the lifetime of both input devices.
194 Clients can use this pairing behaviour to implement input paradigms that
195 require pointer and keyboard interation (e.g. SHIFT + Click).
200 An SD is usually a physical device configured in the server. SDs are not
201 represented by a cursor or keyboard focus and may be attached to a master
202 pointer or master keyboard. SDs can only be attached to any master of the same
203 type (e.g. a physical pointer device can be attached to any master pointer).
205 If an event is generated by an SD
207 - if the SD is attached to a master pointer, it changes the position and/or
208 button state of the master pointer.
209 - if the SD is attached to a master keyboard, it sends events to this
210 keyboard's focus window (if applicable) and/or changes the modifier state of
212 - if the SD is not attached to an MD ("floating"), it does not change
213 any master device. The SD has its own (invisible) sprite and its own focus.
214 Both the sprite and the focus must be managed explicitly by the client
218 Event processing for attached slave devices
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221 Whenever an SD changes its logical state,
223 - the event is delivered as an XI event to any interested clients. If the
224 device is floating, event processing stops.
225 Otherwise, if the device is attached,
226 - the master device changes its classes to reflect the SD's capabilities. All
227 interested clients are notified of this device change.
228 - then, the event is delivered as an XI event from the MD to any interested
229 clients. If the event has been delivered, event processing stops.
231 - the event is delivered as a core event to any interested clients.
233 Given that W is the event window, and P the parent window of W, event delivery
234 to P is only attempted if neither the XI event, nor the core event has been
235 delivered on W. Once an event has been delivered as either XI or core event,
236 event processing stops.
239 The ClientPointer principle
240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
242 Many core protocol and some extension requests are ambiguous when multiple
243 master devices are available (e.g. QueryPointer does not specify which pointer).
244 The X server does not have the knowledge to chose the contextually correct
245 master device. For each client, one master pointer is designated as this
246 clients's "ClientPointer". Whenever a client sends an ambiguous request (e.g.
247 QueryPointer), the ClientPointer or the keyboard paired with the ClientPointer
248 is chosen to provide the data for this request.
250 This ClientPointer may be explicitly assigned to a client with the
251 SetClientPointer call. If no ClientPointer is set when a client issues an
252 ambiguous request, the server choses one device as the ClientPointer. The
253 method of chosing a ClientPointer from the available master pointers is
254 implementation-specific.
256 If the master pointer currently set as ClientPointer for one or more clients is
257 removed, the server may either unset the ClientPointer setting or change the
258 ClientPointer to a different master pointer.
264 XI 2.2 introduces support for multi-touch devices. The traditional
265 pointer/keyboard approach enforced by XI 2.0 with the master/slave device
266 hierarchy is not always suitable for multi-touch devices that can provide a
267 dynamic number of touchpoints per physical device; it is not known without
268 client-specific interpretation whether the touchpoints must be considered
269 separately or grouped together.
271 The additions in XI 2.2 aim to:
273 - support a dynamic number of simultaneous touch points,
274 - support devices that are both multi-touch and traditional pointer devices,
275 - allow touchpoints to be either grouped together or handled separately,
276 - be backwards-compatible to pre-XI 2.2 clients through emulation of XI 2.x/XI 1.x and core
279 Touch events are only available to clients supporting version 2.2 or later of
280 the X Input Extension. Clients must use the XIQueryVersion request to announce
281 support for this version. Touch devices may generate emulated pointer events
282 alongside XI 2.2 touch events to support older clients; see Section
283 <<multitouch-processing,Touch event delivery>>.
285 Touch event processing differs from normal event processing in a few ways.
286 The most notable differences are that touch events are processed partially
287 out-of-band from pointer and keyboard events, and that touch events may be
288 sent to multiple clients simultaneously. For more details see Section
289 <<multitouch-processing, Touch event delivery>>.
291 [[multitouch-lifecycle]]
292 Touch event sequences
293 ~~~~~~~~~~~~~~~~~~~~~
295 Touch input follows a three-stage cycle:
297 begin - update - update - ... - end
299 i.e. “begin” the sequence by touching the device, “update” the current
300 touch location or properties any number of times, and finally “end” the
301 sequence by ceasing to touch the device. Within this document, the term
302 "touch sequence" is used to describe the above sequence of events.
303 In the protocol, the three stages are represented with the event
304 types TouchBegin, TouchUpdate, and TouchEnd, respectively. A touch sequence
305 always generates TouchBegin and TouchEnd events, and may also generate
306 TouchUpdate events. Clients must select for all three of these events
309 When a touch starts, clients are sent a TouchBegin event
310 detailing the position of the touchpoint, as well as the
311 initial properties of the touchpoint. Note that the logical state of the
312 device (as seen through the input protocol) may lag the physical state if event
313 processing is affected by grabs. Multiple touchpoints may be active on the
314 same device at any time, potentially owned by and/or delivered to a different
317 Whenever the touch position or any other property of the touchpoint changes,
318 a TouchUpdate event is sent to all clients listening
319 to events for that touchpoint with the updated information.
321 When the touch has physically ended, or a client will otherwise not receive
322 any more events for a given touchpoint, a TouchEnd event will be sent to
325 Passive touch grabs are similar to standard input event grabs in that they
326 take precedence over event selections and are searched from the root window
327 to the child window (as opposed to selections, which start their search at the
328 child window and continue up to the root window). When a touch grab activates,
329 the client whose grab activates becomes the “owner” of this touch sequence,
330 and must decide what to do with it, as per Section
331 <<multitouch-ownership,Ownership of touch sequences>>. See the
332 <<requests-passivegrabdevice,XIPassiveGrabDevice>> request
333 documentation for more information on passive grab activation.
335 Only one client may select for touch events from a given device on a window.
337 [[multitouch-ownership]]
338 Ownership of touch sequences
339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
341 Once a grabbing client becomes the owner of a touch, it must either “accept” or
342 "reject" the touch sequence using the XIAllowEvents request. If a touch sequence
343 is rejected, a TouchEnd event is sent to the rejecting client, and it will not
344 receive any more events for this touch. The server then looks to the next
345 window in the stack for another passive grab, and attempts to pass ownership
346 on to the next candidate for a passive grab (i.e. the next window towards
347 the final child window with a matching grab), or to the first applicable
348 event selection if there are no more grabs.
350 If a touch sequence is accepted by its owner, all other clients receive
351 TouchEnd events, and the touch sequence is exclusively delivered to the
352 owner from that point on.
354 If the touch sequence physically ends while the owner of the touch sequence
355 has not yet accepted or rejected ownership, the owner receives a TouchEnd
356 event and all other clients receive a TouchUpdate event with the
357 TouchPendingEnd flag set. The owner must still accept or reject the sequence
358 nonetheless. If the owner rejects the touch sequence, the server will still
359 attempt to exhaust all other passive grabs and/or event selections looking
362 If the touch sequence has not physically ended yet and the owner of the
363 touch sequence rejects, the owner receives a TouchEnd event and ownership is
364 passed to the next client.
366 Clients may opt for touch events to be delivered before they become the
367 owner of the touch sequence. In this case, the logical state of the device (as
368 seen by means of the protocol) always matches the physical state of the device.
369 Clients must use caution if they opt for this feature; any action taken must be
370 undone if the touch sequence ends without the client becoming the owner.
372 To select for touch events regardless of ownership, a client must set the
373 TouchOwnership event mask in addition to the
374 TouchBegin, TouchUpdate and TouchEnd mask. When selected, a client will receive
375 touch events as they occur on the device. If and when the client
376 becomes the owner of a touch sequence, a TouchOwnership event is sent to the
377 client. If the client is the initial owner of the sequence, the TouchBegin is
378 immediately followed by the TouchOwnership event. Otherwise, TouchUpdate events
379 may preceed a TouchOwnership event. A client is not guaranteed to become the
380 owner of any given touch sequence.
382 The server delivers touch events to all clients that have selected for
383 TouchOwnership and to the current owner of the sequence in parallel.
385 If a client has selected for TouchOwnership and is not the current owner of
386 the sequence and the current owner accepts the sequence, the client receives
387 a TouchEnd event and no further events from this sequence are sent to this
390 If a client has selected for TouchOwnership and the physical touch ends
391 before the current owner has accepted or rejected the sequence, the client
392 receives a TouchUpdate event with the TouchPendingEnd flag set. No further
393 TouchUpdate events will be sent for this sequence. If the current owner
394 accepts the sequence, the client receives a TouchEnd event. Otherwise, if
395 the current owner rejects the sequence, the client may become
396 the owner of the touch sequence and receive a TouchOwnership event and a
399 [[multitouch-device-modes]]
403 Touch devices come in many different forms with varying capabilities. The
404 following device modes are defined for this protocol:
407 These devices map their input region to a subset of the screen region. Touch
408 events are delivered to window at the location of the touch. "direct"
409 here refers to the user manipulating objects at their screen location.
410 An example of a DirectTouch device is a touchscreen.
413 These devices do not have a direct correlation between a touch location and
414 a position on the screen. Touch events are delivered according to the
415 location of the device's cursor and often need to be interpreted
416 relative to the current position of that cursor. Such interactions are
417 usually the result of a gesture performed on the device, rather than
418 direct manipulation. An example of a DependentTouch device is a
421 A device is identified as only one of the device modes above at any time, and
422 the touch mode may change at any time. If a device's touch mode changes, an
423 XIDeviceChangedEvent is generated.
425 [[multitouch-processing]]
429 For direct touch devices, the window set for event propagation is the set of
430 windows from the root window to the topmost window lying at the co-ordinates
433 For dependent devices, the window set for event propagation is the set of
434 windows from the root window to the window that contains the device's
435 pointer. A dependent device may only have one window set at a time, for all
436 touches. Any future touch sequence will use the same window set. The window set
437 is cleared when all touch sequences on the device end.
439 A window set is calculated on TouchBegin and remains constant until the end
440 of the sequence. Modifications to the window hierarchy, new grabs or changed
441 event selection do not affect the window set.
443 Pointer control of dependent devices
444 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
445 On a dependent device, the device may differ between a pointer-controlling
446 touch and a non-pointer-controlling touch. For example, on a touchpad the
447 first touch is pointer-controlling (i.e. serves only to move the visible
448 pointer). Multi-finger gestures on a touchpad cause all touches to be
449 non-pointer-controlling.
451 For pointer-controlling touches, no touch events are sent; the touch
452 generates regular pointer events instead. Non-pointer-controlling touches
453 send touch events. A touch may change from pointer-controlling to
454 non-pointer-controlling, or vice versa.
456 - If a touch changes from pointer-controlling to non-pointer-controlling,
457 a new touch ID is assigned and a TouchBegin is sent for the last known
458 position of the touch. Further events are sent as TouchUpdate events, or as
459 TouchEnd event if the touch terminates.
461 - If a touch changes from non-pointer-controlling to pointer-controlling, a
462 TouchEnd is sent for that touch at the last known position of the touch.
463 Further events are sent as pointer events.
465 The conditions to switch from pointer-controlling to non-pointer-controlling
466 touch is implementation-dependent. A device may support touches that are
467 both pointer-controlling and a touch event.
469 In the dependent touch example event sequence below, touches are marked when
470 switching to pointer-controlling (pc) or to non-pointer-controlling (np).
472 .Dependent touch example event sequence on a touchpad
473 [width="50%", options="header"]
474 |====================================================
475 | Finger 1 | Finger 2 | Event generated(touchid)
479 | (np) | down | TouchBegin(0), TouchBegin(1)
480 | move | -- | TouchUpdate(0)
481 | -- | move | TouchUpdate(1)
482 | up | (pc) | TouchEnd(0), TouchEnd(1)
484 | down | (np) | TouchBegin(2), TouchBegin(3)
485 | move | -- | TouchUpdate(2)
486 | up | (pc) | TouchEnd(2), TouchEnd(3)
489 | (np) | down | TouchBegin(4), TouchBegin(5)
490 | (pc) | up | TouchEnd(4), TouchEnd(5)
493 |====================================================
496 [[multitouch-emulation]]
497 Pointer emulation from multitouch events
498 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
500 Touch sequences from direct touch devices may emulate pointer events. Only one
501 touch sequence from a device may emulate pointer events at a time; which touch
502 sequence emulates pointer events is implementation-dependent.
504 Pointer events are emulated as follows:
506 - A TouchBegin event generates a pointer motion event to the location of the
507 touch with the same axis values of the touch event, followed by a button press
509 - A TouchUpdate event generates a pointer motion event to the location of the
510 touch and/or to update axis values of the pointer device. The button state
511 as seen from the protocol includes button 1 set.
512 - A TouchEnd event generates a pointer motion event to the location of the touch
513 and/or to update the axis values if either have changed, followed by a button
514 release event for button 1. The button state as seen from the protocol
515 includes button 1 set.
517 If a touch sequence emulates pointer events and an emulated pointer event
518 triggers the activation of a passive grab, the grabbing client becomes the
519 owner of the touch sequence.
521 The touch sequence is considered to have been accepted if
523 - the grab mode is asynchronous, or
524 - the grab mode is synchronous and the device is thawed as a result of
525 AllowEvents with AsyncPointer or AsyncDevice
527 Otherwise, if the button press is replayed by the client, the touch sequence
528 is considered to be rejected.
530 Touch event delivery precedes pointer event delivery. A touch event emulating
531 pointer events is delivered:
533 - as a touch event to the top-most window of the current window set if a
534 client has a touch grab on this window,
535 - otherwise, as a pointer event to the top-most window of the current window
536 set if a client has a pointer grab on this window,
537 - otherwise, to the next child window in the window set until a grab has been
540 If no touch or pointer grab on any window is active and the last window in the
541 window set has been reached, the event is delivered:
543 - as a touch event to the window if a client has selected for touch events
545 - otherwise, as a pointer event to the window if a client has selected for
547 - otherwise, to the next parent window in the window set until a selection has
550 Emulated pointer events will have the PointerEmulated flag set. A touch
551 event that emulates pointer events has the TouchEmulatingPointer flag set.
553 [[glossary-notations]]
554 Notations used in this document
555 -------------------------------
557 Notation for requests:
561 name of request field: type of request field
562 name of request field: type of request field
564 name of reply field: type of reply field
571 name of field: type of field
572 name of field: type of field
575 Complex fields are specified in the following notation:
577 name of field: COMPLEXFIELDTYPE
579 or, if multiple of these fields exist:
581 name of field: LISTofCOMPLEXFIELDTYPE
583 COMPLEXFIELDTYPE: { name of subfield: type of subfield,
584 name of subfield: type of subfield }
587 [[glossary-datatypes]]
592 A binary mask defined as (1 << button number).
593 A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK.
595 DEVICE { DEVICEID, AllDevices, AllMasterDevices }
596 A DEVICE specifies either a DEVICEID or AllDevices or
600 A DEVICEID is a numerical ID for a device currently available in the
601 server. The server may re-use a device ID after a device's removal.
602 The device IDs 0 and 1 are reserved.
603 AllDevices ........ 0
604 AllMasterDevices .. 1
606 DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer,
607 SlaveKeyboard, FloatingSlave }
608 A DEVICEUSE field specifies the current use of a device in the MD/SD
609 device hierarchy. See Section "The Master/Slave device hierarchy"
610 for more information.
613 An EVENTMASK is a binary mask defined as (1 << event type).
614 A SETofEVENTMASK is a binary OR of zero or more EVENTMASK.
617 Fixed point decimal in 16.16 format as one INT16 and one CARD16.
618 The INT16 contains the integral part, the CARD32 the decimal fraction
622 Fixed point decimal in 32.32 format as one INT32 and one CARD32.
623 The INT32 contains the integral part, the CARD32 the decimal fraction
627 A binary mask defined as (1 << valuator number).
628 A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK.
635 Errors are sent using core X error reports.
638 A value for a DEVICE argument does not specify a valid DEVICE.
645 The server does not guarantee that the length of a reply remains constant in
646 future revisions of XI2. A client must always retrieve the exact length of the
647 protocol reply from the connection, even if the reply is longer than defined
648 for the XI2 version supported by the client.
649 Additional bytes in a request may include data supported in later versions of
650 XI2. Clients should ignore this data. Padding bytes in XI2 protocol requests
651 are required to be 0.
654 Requests introduced in version 2.0
655 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
657 [[requests-queryversion]]
660 major_version: CARD16
661 minor_version: CARD16
663 major_version: CARD16
664 minor_version: CARD16
667 The client sends the highest supported version to the server and the
668 server sends the highest version it supports, but no higher than the
669 requested version. Major versions changes can introduce incompatibilities
670 in existing functionality, minor version changes introduce only backward
671 compatible changes. It is the client's responsibility to ensure that the
672 server supports a version which is compatible with its expectations.
679 If major_version is less than 2, a BadValue error occurs.
681 [[requests-querydevice]]
687 deviceinfo: LISTofDEVICEINFO
690 DEVICEINFO { deviceid: DEVICEID
697 classes: LISTofCLASS }
699 CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS, SCROLLCLASS, TOUCHCLASS }
701 BUTTONCLASS { type: ButtonClass
705 state: SETofBUTTONMASK
708 KEYCLASS { type: KeyClass
714 AXISCLASS { type: AxisClass
725 SCROLLCLASS¹ {type: ScrollClass
729 scroll_type: SCROLLTYPE
730 flags: SETofSCROLLFLAGS
733 SCROLLTYPE { Vertical, Horizontal }
735 SCROLLFLAGS { NoEmulation, Preferred }
737 TOUCHCLASS² { type: TouchClass
741 num_touches: CARD16 }
743 TOUCHMODE { DirectTouch, DependentTouch }
748 XIQueryDevice details information about the requested input devices.
751 The device to list. If devices is AllDevices, all enabled and
752 disabled devices are listed. If devices is AllMasterDevices, all
753 enabled and disabled master devices are listed. If devices is a
754 valid DEVICE, only this DEVICE is listed and num_devices is 1.
756 The number of deviceinfos returned.
758 Each deviceinfo is detailed as follows:
761 The unique ID of the device. Device IDs may get re-used when a device
764 If the device is a master pointer, use is MasterPointer.
765 If the device is a master keyboard, use is MasterKeyboard.
766 If the device is a slave pointer, use is SlavePointer.
767 If the device is a slave keyboard, use is SlaveKeyboard.
768 If the device is a floating slave, use is FloatingSlave.
770 If the device is a master pointer or a master keyboard, attachment
771 specifies the paired master keyboard, or the paired master pointer,
772 respectively. If the device is a non-floating slave device
773 attachment specifies the master device this device is attached to.
774 If the device is a floating slave, attachment is undefined.
776 Zero if the device is disabled, non-zero otherwise.
778 Number of classes provided.
780 Length of the name in bytes not including padding.
782 Details the available classes provided by the device in an undefined
785 The device's name. padded to a multiple of 4 bytes.
787 For all classes, type specifies the device class. Clients are required
788 to ignore unknown device classes. The length field specifies the length
789 of the class in 4 byte units.
790 The following classes may occur only once: ButtonClass, KeyClass
796 Length in 4 byte units.
798 The device this class originates from.
800 Number of buttons provided by the device.
802 List of Atoms specifying the label for each button. An Atom of None
803 specifies an unlabeled button. Buttons are listed in the device-native
804 order regardless of the current button mapping.
806 The current button mask for this device after button mapping is
807 applied. Each bit representing a button is 1 if this button is
808 logically down, or 0 otherwise. State is a multiple of 4-byte units
809 and always contains at least num_buttons bits.
815 Length in 4 byte units.
817 The device this class originates from.
819 Number of keycodes provided by the device.
821 List of keycodes provided.
827 Length in 4 byte units.
829 The device this class originates from.
831 Axis number of this axis. The axis number is in device-native
832 order and potential axis mappings are ignored.
834 Atom specifying the axis name. An Atom of None specifies an unlabeled
841 Resolution in counts/meter.
843 Relative or Absolute.
845 Last published axis value (if mode is absolute).
847 An axis in Relative mode may specify min and max as a hint to the
848 client. If no min and max information is available, both must be 0.
854 Axis number that is referred to. This axis number must be listed in
855 the ValuatorClassInfo.
857 Vertical for a vertical scrolling axis, Horizontal for a horizontal
860 A set of flags that apply to this scroll axis.
861 NoEmulation: no legacy scroll button events are generated for events
862 on this scrolling axis.
863 Preferred: This axis is the preferred axis for emulating valuator
864 events from legacy scroll button events.
866 The valuator delta equivalent to one positive unit of scrolling.
868 A ScrollClass may only exist if the device has at least one ValuatorClass
869 and each axisnumber listed in any ScrollClass. Only one ScrollClass may
870 exist per ValuatorClass.
876 Length in 4 byte units.
878 The device this class originates from.
880 The device type of the touch device. This mode may change at runtime.
882 The maximum number of simultaneous touchpoints the device may send.
883 If num_touches is 0, the number of supported touches is unknown or
886 Devices with a TouchClass emit touch events with the same axes as pointer
889 [[requests-selectevents]]
894 masks: LISTofEVENTMASK
898 EVENTMASK { deviceid: DEVICE,
903 The window to select the events on.
905 Number of items in masks.
907 Numerical deviceid, or AllDevices, or AllMasterDevices.
909 Length of mask in 4 byte units.
911 Event mask. An event mask for an event type T is defined as (1 << T).
913 XISelectEvents selects for XI2 events on window.
915 If num_masks is 0, a BadValue error occurs.
917 Each mask sets the (and overwrites a previous) event mask for the DEVICE
918 specified through deviceid. The device AllDevices or
919 AllMasterDevices is treated as a separate device by server. A client's
920 event mask is the union of AllDevices, AllMasterDevices and the
921 per-device event mask.
922 The removal of device from the server unsets the event masks for the
923 device. If an event mask is set for AllDevices or AllMasterDevices, the
924 event mask is not cleared on device removal and affects all future
927 If mask_len is 0, the event mask for the given device is cleared.
929 The mask for XIHierarchyEvents may only be selected for XIAllDevices.
930 Setting it for any other device results in a BadValue error.
932 A client selecting for any of XI_TouchBegin, XI_TouchUpdate, or XI_TouchEnd
933 must select for all three events at the same time, else a BadValue error
934 will be generated. A client selecting for XI_TouchOwnership must select for
935 all three of the other touch events. If the selection for these touch events
936 overlaps a current selection by another client (e.g. selecting for a
937 specific device when another client has a selection for XIAllDevices), a
938 BadAccess error occurs.
940 [[requests-getselectedevents]]
946 masks: LISTofEVENTMASK
950 The window to select the events on.
952 Number of items in masks.
954 Selected event masks by this client.
956 Masks are returned on a per-device basis, with masks for AllDevices and
957 AllMasterDevices returned separately. A client can calculate the
958 effective mask for a device with a bitwise OR of the AllDevices, the
959 AllMasterDevices and the device-specific mask.
961 If num_masks is 0, no events have been selected by this client on the
964 [[requests-querypointer]]
980 buttons: SETofBUTTONMASK
983 Query a master pointer device for its current position.
986 The root window the pointer is logically on.
988 The child window of window that contains the pointer or None.
991 Pointer position relative to the root window's origin.
994 Pointer position relative to window or 0 if same_screen is false.
996 True if window is on the same screen as the pointer.
998 XKB modifier state on the paired device.
1000 XKB group state on the paired device.
1002 The length of buttons in 4 byte units.
1006 If the device is not a master pointer device or not a floating slave
1007 pointer, a BadDevice error results.
1009 [[requests-warppointer]]
1023 WarpPointer moves the pointer of deviceid as if the user had moved
1024 the pointer. WarpPointer can only be called for MasterPointer and
1025 FloatingSlave devices.
1028 If src_window is not None, the move only takes place if src_window
1029 contains the pointer and the pointer is contained in the specified
1030 rectangle of src_window.
1032 If dst_win is None, this request moves the pointer by offsets
1033 dst_x/dst_y relative to the current position of the pointer. If
1034 dst_window is a window, this request moves the pointer to
1035 dst_x/dst_y relative to dst_win's origin.
1040 Specifies the source window rectangle.
1043 The relative coordinates to move the pointer if dst_win is None, or
1044 the absolute coordinates if dst_win is a window.
1048 This request cannot be used to move the pointer outside the confine-to
1049 window of an active pointer grab. An attempt will only move the pointer as
1050 far as the closest edge of the confine-to window.
1052 This request will generate events just as if the user had instantaneously
1055 [[requests-changecursor]]
1063 Change a master pointer's cursor on the specified window.
1068 The new cursor or None.
1070 The master pointer device.
1072 Whenever device enters a window W, the cursor shape is selected in the
1075 - if the current window has a device cursor C(d) defined for device,
1076 display this cursor C(d).
1077 - otherwise, if the current window has a cursor C(w) defined in the core
1078 protocol's window attributes, display cursor C(w).
1079 - repeat on parent window until a cursor has been found.
1081 The device cursor for a given window is reset once the window is destroyed
1082 or the device is removed, whichever comes earlier.
1084 If deviceid does not specify a master pointer, a BadDevice error
1087 [[requests-changehierarchy]]
1091 changes: LISTofHIERARCHYCHANGES
1094 HIERARCHYCHANGE { ADDMASTER, REMOVEMASTER, ATTACHSLAVE, DETACHSLAVE }
1096 HIERARCHYCHANGETYPE { AddMaster, RemoveMaster, AttachSlave, DetachSlave }
1098 CHANGEMODE { Float, Attach }
1100 ADDMASTER { type: HIERARCHYCHANGETYPE
1107 REMOVEMASTER { type: HIERARCHYCHANGETYPE
1110 return_mode: CHANGEMODE
1111 return_pointer: DEVICEID
1112 return_keyboard: DEVICEID }
1114 ATTACHSLAVE { type: HIERARCHYCHANGETYPE
1119 DETACHSLAVE { type: HIERARCHYCHANGETYPE
1121 deviceid: DEVICEID }
1123 XIChangeHierarchy allows a client to modify the
1124 <<hierarchy,Master/Slave device hierarchy>>.
1127 The number of changes to apply to the current hierarchy.
1129 The list of changes.
1131 The server processes the changes in the order received from the client and
1132 applies each requested change immediately. If an error occurs, processing
1133 stops at the current change and returns the number of successfully applied
1134 changes in the error.
1136 ADDMASTER creates a pair of master devices.
1140 Length in 4 byte units.
1142 Length of name in bytes.
1144 True if the device should send core events.
1146 True if the device is to be enabled immediately.
1148 The name for the new master devices. The master pointer's name is
1149 automatically appended with " pointer", the master keyboard's name is
1150 automatically appended with " keyboard".
1152 REMOVEMASTER removes an existing master device.
1154 Always RemoveMaster.
1156 Length in 4 byte units.
1158 The device to remove.
1160 Return mode for attached slave devices.
1161 If return_mode is Float, all slave devices are set to floating.
1162 If return_mode is Attach, slave pointers are attached to
1163 return_pointer and slave keyboards are attached to
1167 The master pointer and master keyboard to attach slave devices to, if
1168 return_mode is Attach. If return_mode is Float, return_pointer
1169 and return_keyboard are undefined.
1171 Removing a master pointer removes the paired master keyboard and vice
1174 ATTACHSLAVE attaches a slave device to a given master device.
1176 Always ChangeAttachment.
1178 Length in 4 byte units.
1180 Deviceid of the slave device.
1182 The new master device to attach this slave device to.
1184 If any clients are selecting for touch events from the slave device, their
1185 selection will be canceled.
1187 DETACHSLAVE detaches a slave device from its current master device.
1189 Always ChangeAttachment.
1191 Length in 4 byte units.
1193 Deviceid of the slave device.
1195 [[requests-setclientpointer]]
1202 Set the ClientPointer for the client owning win to the given device.
1205 Window or client ID.
1207 The master pointer or master keyboard that acts as ClientPointer.
1209 Some protocol requests are ambiguous and the server has to choose a device
1210 to provide data for a request or a reply. By default, the server will
1211 choose a client's ClientPointer device to provide the data, unless the
1212 client currently has a grab on another device. See section
1213 <<clientpointer,The ClientPointer principle>> for more details.
1215 If win is None, the ClientPointer for this client is set to the given
1216 device. Otherwise, if win is a valid window, the ClientPointer for the
1217 client owning this window is set to the given device. Otherwise, if win is
1218 not a valid window but a client with the client mask equal to win exists,
1219 this client's ClientPointer is set to the given device.
1221 If deviceid does not specify a master pointer or master keyboard, a
1222 BadDevice error is returned.
1224 If window does not specify a valid window or client ID and is not None, a
1225 BadWindow error is returned.
1227 [[requests-getclientpointer]]
1236 Query the ClientPointer for the client owning win.
1239 The window or client ID.
1241 True if the client has a ClientPointer set.
1243 The master pointer that acts as a ClientPointer if set is True.
1245 No difference is made between a ClientPointer set explicitly through
1246 XISetClientPointer and a ClientPointer implicitly assigned by the server
1247 in response to an ambiguous request.
1249 [[requests-setfocus]]
1257 Set the focus for the given device to the given window. Future key events
1258 from this device are sent to this window.
1259 This request generates FocusIn and FocusOut events.
1262 A viewable window or None.
1264 The device to modify the focus window for.
1266 Specifies the time to change the focus or CurrentTime.
1268 If focus is None, key events from this device are discarded until a new
1269 focus window is set. If focus is a viewable window, key events from this
1270 device are sent to this window. If the window becomes unviewable, the
1271 window's first viewable ancestor automatically becomes the focus window
1272 and FocusIn and FocusOut events are sent as if a client had changed the
1274 This is equivalent to RevertToParent in the core XSetInputFocus window.
1276 This request has no effect if the specified time is earlier than the
1277 current last-focus-change time or is later than the current X server time.
1278 Otherwise, the last-focus-change time is set to the specified time.
1280 [[requests-getfocus]]
1288 Return the current focus window for the given device.
1290 [[requests-grabdevice]]
1296 grab_mode: { Synchronous, Asynchronous }
1297 paired_device_mode: { Synchronous, Asynchronous }
1298 time: TIMESTAMP or CurrentTime
1301 masks: SETofEVENTMASK
1303 status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable
1306 This request actively grabs control of the specified input device. Further
1307 input events from this device are reported only to the grabbing client.
1308 This request overides any previous active grab by this client for this
1309 device. This request does not affect the processing of XI 2.2
1315 Events are reported relative to the grab window.
1317 Specifies whether event will be reported normally or relative to the
1320 Specifies if this device will be frozen as a result of the grab.
1322 Specifies if the master device paired with this device will be frozen
1323 as a result of the grab.
1325 A valid server time or CurrentTime.
1327 The cursor to display for the duration of the grab or None.
1329 Length of mask in 4 byte units.
1331 Event mask. An event mask for an event type T is defined as (1 << T).
1333 Success or the reason why the grab could not be established.
1335 The masks parameter specifies which events the client wishes to receive
1336 while the device is grabbed.
1338 If owner-events is False, input events generated from this device are
1339 reported with respect to grab-window, and are only reported if selected by
1340 being included in the event-list. If owner-events is True, then if a
1341 generated event would normally be reported to this client, it is reported
1342 normally, otherwise the event is reported with respect to the grab-window,
1343 and is only reported if selected by being included in the event-list. For
1344 either value of owner-events, unreported events are discarded.
1346 If grab-mode is Asynchronous, device event processing continues normally.
1347 If the device is currently frozen by this client, then processing of
1348 device events is resumed. If grab-mode is Synchronous, the state of the
1349 grabbed device (as seen by means of the protocol) appears to freeze,
1350 and no further device events are generated by the server until the
1351 grabbing client issues a releasing XIAllowEvents request or until the
1352 device grab is released. Actual device input events are not lost while the
1353 device is frozen; they are simply queued for later processing.
1355 If the device is a slave device, the paired-device-mode is ignored.
1356 Otherwise, if this device is a master device and paired-device-mode is
1357 Asynchronous, event processing is unaffected by activation of the grab. If
1358 this device is a master device and paired-device-mode is Synchronous, the
1359 state of the master device paired with this device (as seen by means of the
1360 protocol) appears to freeze, and no further events are generated by the
1361 server until the grabbing client issues a releasing XIAllowEvents request
1362 or until the device grab is released. Actual events are not lost while the
1363 devices are frozen; they are simply queued for later processing.
1365 If the cursor is not None and the device is a master pointer device, the
1366 cursor will be displayed until the device is ungrabbed.
1368 This request fails and returns:
1370 AlreadyGrabbed: If the device is actively grabbed by some other client.
1371 NotViewable: If grab-window is not viewable.
1372 InvalidTime: If the specified time is earlier than the last-grab-time for
1373 the specified device or later than the current X server time.
1374 Otherwise, the last-grab-time for the specified device is set
1375 to the specified time and CurrentTime is replaced by the
1376 current X server time.
1377 Frozen: If the device is frozen by an active grab of another client.
1379 To release a grab of a device, use XIUngrabDevice.
1381 [[requests-ungrabdevice]]
1385 time: TIMESTAMP or CurrentTime
1388 This request releases the device if this client has it actively grabbed
1389 (from either XIGrabDevice or XIPassiveGrabDevice) and
1390 releases any queued events. If any devices were frozen by the grab,
1391 XIUngrabDevice thaws them.
1396 A valid server time or CurrentTime.
1398 The request has no effect if the specified time is earlier than the
1399 last-device-grab time or is later than the current server time.
1400 This request generates FocusIn and FocusOut events.
1401 An XIUngrabDevice is performed automatically if the event window for an
1402 active device grab becomes not viewable.
1404 [[requests-allowevents]]
1408 time: TIMESTAMP or CurrentTime
1409 event_mode: { AsyncDevice, SyncDevice,
1410 AsyncPairedDevice, SyncPairedDevice,
1411 ReplayDevice, AsyncPair, SyncPair,
1412 AcceptTouch¹, RejectTouch¹ }
1414 grab_window¹: Window
1419 The XIAllowEvents request releases some queued events if the client
1420 has caused a device to freeze. It also is used to handle touch grab and
1421 ownership processing.
1426 A valid server time or CurrentTime.
1428 Specifies whether a device is to be thawed and events are to be
1429 replayed, or how to handle a grabbed touch sequence.
1431 The ID of the touch sequence to accept or reject. The value is undefined
1432 for event modes other than AcceptTouch and RejectTouch.
1434 The window on which to accept or reject a touch sequence grab. The value
1435 is undefined for event modes other than AcceptTouch and RejectTouch.
1437 The request has no effect if the specified time is earlier than the last-grab
1438 time of the most recent active grab for the client, or if the specified time is
1439 later than the current X server time. The time parameter must be CurrentTime for
1440 requests with event modes of AcceptTouch and RejectTouch.
1442 When event-mode is AcceptTouch, a BadValue error occurs if the touch ID is
1443 invalid. A BadAccess error occurs if this client is not the current or potential
1444 owner of the specified touch ID.
1446 The following describes the processing that occurs depending on what constant
1447 you pass to the event-mode argument:
1450 If the specified device is frozen by the client, event processing for that
1451 device continues as usual. If the device is frozen multiple times by the
1452 client on behalf of multiple separate grabs, AsyncDevice thaws for
1454 AsyncDevice has no effect if the specified device is not frozen by the
1455 client, but the device need not be grabbed by the client.
1457 If the specified device is frozen and actively grabbed by the client,
1458 event processing for that device continues normally until the next
1459 event is reported to the client. At this time, the specified device
1460 again appears to freeze. However, if the reported event causes the
1461 grab to be released, the specified device does not freeze.
1462 SyncDevice has no effect if the specified device is not frozen by the
1463 client or is not grabbed by the client.
1465 If the specified device is actively grabbed by the client and is frozen
1466 as the result of an event having been sent to the client (either from
1467 the activation of a XIGrabButton or from a previous XIAllowEvents with
1468 mode SyncDevice, but not from a Grab), the grab is released and
1469 that event is completely reprocessed. This time, however, the request
1470 ignores any passive grabs at or above (towards the root) the
1471 grab-window of the grab just released.
1472 The request has no effect if the specified device is not grabbed by
1473 the client or if it is not frozen as the result of an event.
1475 If the paired master device is frozen by the client, event processing
1476 for it continues as usual. If the paired device is frozen multiple
1477 times by the client on behalf of multiple separate grabs,
1478 AsyncPairedDevice thaws for all.
1479 AsyncPairedDevice has no effect if the device is not frozen by the
1480 client, but those devices need not be grabbed by the client.
1481 AsyncPairedDevice has no effect if deviceid specifies a slave device.
1483 If the paired master device is frozen by the client, event processing (for
1484 the paired master device) continues normally until the next button or key
1485 event is reported to the client for the grabbed device (button event for
1486 the grabbed device, key or motion event for the device), at which time
1487 the device again appears to freeze. However, if the reported event causes
1488 the grab to be released, then the device does not freeze.
1489 SyncPairedDevice has no effect if the specified device is not grabbed
1490 by the client or if it is no frozen as the result of an event.
1491 SyncPairedDevice has no effect if deviceid specifies a slave device.
1493 If both the device and the paired master device are frozen by the
1494 client, event processing (for both devices) continues normally until
1495 the next XIButtonPress, XIButtonRelease, XIKeyPress, or XIKeyRelease
1496 event is reported to the client for a grabbed device (button event for
1497 a pointer, key event for a keyboard), at which time the devices again
1498 appear to freeze. However, if the reported event causes the grab to be
1499 released, then the devices do not freeze (but if the other device is
1500 still grabbed, then a subsequent event for it will still cause both
1502 SyncPair has no effect unless both the device and the paired master
1503 device are frozen by the client. If the device or paired master device
1504 is frozen twice by the client on behalf of two separate grabs,
1505 SyncPair thaws for both (but a subsequent freeze for SyncPair will
1506 only freeze each device once).
1507 SyncPair has no effect if deviceid specifies a slave device.
1509 If the device and the paired master device are frozen by the client,
1510 event processing for both devices continues normally. If a device is
1511 frozen twice by the client on behalf of two separate grabs, AsyncBoth
1512 thaws for both. AsyncPair has no effect unless both the device and the
1513 paired master device frozen by the client.
1514 AsyncPair has no effect if deviceid specifies a slave device.
1516 The client is deemed to have taken control of the touch sequence once it
1517 owns the sequence. TouchEnd events will be sent to all clients listening
1518 to the touch sequence that have either grabbed the touch sequence on a
1519 child window of the grab_window or have received events for the touch
1520 sequence through event selection. These clients will no longer receive
1521 any TouchUpdate events.
1523 The client is no longer interested in the touch sequence, and will
1524 receive a TouchEnd event. If the client is the current owner of the
1525 sequence, ownership will be passed on to the next listener.
1527 [[requests-passivegrabdevice]]
1536 grab_mode: { Synchronous, Asynchronous, Touch¹ }
1537 paired_device_mode: { Synchronous, Asynchronous }
1538 num_modifiers: INT16
1540 masks: SETofEVENTMASK
1541 modifiers: CARD32 or GrabAnyModifier
1543 num_modifiers_return: INT16
1544 modifiers_return: GRABMODIFIERINFO
1547 GRABTYPE { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
1548 GrabtypeFocusIn, GrabtypeTouchBegin¹ }
1550 GRABMODIFIERINFO { status: Access
1555 Establish an explicit passive grab for a button or keycode
1556 on the specified input device.
1559 The cursor to display for the duration of the grab. If grab_type
1560 is not GrabtypeButton, this argument is ignored.
1562 The device to establish the passive grab on or AllDevices or
1565 The button number, or key symbol to grab for.
1566 Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
1569 The type of grab to establish.
1571 Events are reported relative to the grab window.
1573 If grab-mode is Asynchronous, device event processing continues
1574 normally. If the device is currently frozen by this client, then
1575 processing of device events is resumed. If grab-mode is
1576 Synchronous, the state of the grabbed device (as seen by means of
1577 the protocol) appears to freeze, and no further device events are
1578 generated by the server until the grabbing client issues a
1579 releasing XIAllowEvents request or until the device grab is
1580 released. Actual device input events are not lost while the device
1581 is frozen; they are simply queued for later processing. If grab_type
1582 is GrabtypeTouchBegin, grab_mode must be set to Touch.
1584 Length of mask in 4 byte units.
1586 Event mask. An event mask for an event type T is defined as (1 << T).
1588 XKB modifier state to activate this passive grab.
1590 Number of elements in modifiers.
1592 Specifies whether event will be reported normally or relative to the
1594 num_modifiers_return
1595 Number of elements in modifiers_return
1597 XKB modifier state that could not be grabbed.
1599 If owner-events is False, input events generated from this device are
1600 reported with respect to grab-window, and are only reported if
1601 selected by being included in the event-list. If owner-events is
1602 True, then if a generated event would normally be reported to this
1603 client, it is reported normally, otherwise the event is reported
1604 with respect to the grab-window, and is only reported if selected
1605 by being included in the event-list. For either value of
1606 owner-events, unreported events are discarded.
1608 If deviceid specifies a master pointer, the modifiers of the paired
1609 master keyboard are used. If deviceid specifies a slave pointer
1610 the modifiers of the master keyboard paired with the attached master
1611 pointers are used. If deviceid specifies a slave keyboard, the
1612 modifiers of the attached master keyboard are used. Note that
1613 activating a grab on a slave device detaches the device from its
1614 master. In this case, the modifiers after activation of the grab are
1615 from the slave device only and may be different to the modifier state
1616 when the grab was triggered.
1618 In the future, if grab_type is GrabtypeButton or GrabtypeKeyboard, the
1619 device is actively grabbed if:
1621 - the device is not grabbed, and
1622 - the specified modifier keys are down, and
1623 - the grab_type is GrabtypeButton and the button specified in detail
1624 is logically pressed or the grab_type is GrabtypeKeycode and the
1625 keycode specified in detail is logically pressed, and
1626 - the grab_window contains the pointer, and
1627 - a passive grab on the same button/keycode + modifier
1628 combination does not exist on an ancestor of grab_window.
1630 Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the
1631 device is actively grabbed if:
1633 - the device is not actively grabbed, and
1634 - the specified modifier keys are down, and
1635 - the grab_type is GrabtypeEnter and the device's pointer has moved
1636 into grab_window or a descendant of grab_window, or the grab_type is
1637 GrabtypeFocusIn and the device's focus has been set to the
1638 grab_window or a descendant of grab_window, and
1639 - a passive grab of the same grab_type + modifier combination does not
1640 does not exist on an ancestor of grab_window.
1642 Otherwise, if grab_type is GrabtypeTouchBegin, a touch grab begins if:
1644 - the device is not actively grabbed, and
1645 - the specified modifier keys are down
1646 - a touch begins in grab_window or a descendant of grab_window, and
1647 - a passive grab of the same grab_type + modifier combination does not
1648 does not exist on an ancestor of grab_window.
1650 Ownership of the touch sequence is granted to the grabbing client if:
1652 - a TouchBegin or pointer grab for an emulated touch sequence of a
1653 direct touch device with the same modifier set does not exist on
1654 an ancestor of grab_window, or all applicable grabs have released
1657 A modifier of GrabAnyModifier is equivalent to issuing the request for
1658 all possible modifier combinations (including no modifiers). A client
1659 may request a grab for GrabAnyModifier and explicit modifier
1660 combinations in the same request.
1662 A GrabtypeButton or GrabtypeKeyboard grab is released when all buttons
1663 or keycode are released, independent of the state of modifier keys.
1664 A GrabtypeEnter or GrabtypeFocusIn grab is released when the
1665 pointer or focus leaves the window and all of its descendants,
1666 independent of the state of modifier keys.
1667 A GrabtypeTouchBegin grab is released when the touch sequence ends or
1668 the client uses XIAllowEvents with mode RejectTouch.
1669 Note that the logical state of a device (as seen by means of the
1670 protocol) may lag the physical state if device event processing is
1673 This request overrides all previous passive grabs by the same
1674 client on the same button/key/enter/focus in + modifier combinations
1677 If some other client already has issued a XIPassiveGrabDevice request
1678 with the same button or keycode and modifier combination, the
1679 failed modifier combinations is returned in modifiers_return. If some
1680 other client already has issued an XIPassiveGrabDevice request of
1681 grab_type XIGrabtypeEnter, XIGrabtypeFocusIn, or
1682 XIGrabtypeTouchBegin with the same grab_window and the same
1683 modifier combination, the failed modifier combinations are returned
1684 in modifiers_return. If num_modifiers_return is zero, all passive
1685 grabs have been successful.
1687 If a button grab or enter grab activates, EnterNotify and LeaveNotify
1688 events with mode Grab are generated as if the pointer were to suddenly
1689 warp from its current position some position in the grab_window.
1690 However, the pointer does not warp, and the pointer position is used
1691 as both the initial and final positions for the events.
1693 If a keycode grab or focus grab activates, FocusIn and FocusOut events
1694 with mode Grab are generated as if the focus were to change from the
1695 current window to the grab_window.
1697 If an enter or focus in grab activates, additional EnterNotify events
1698 with mode XIPassiveGrabNotify are generated as if the pointer or focus
1699 were to suddenly warp from its current position to some position in
1700 the grab window. These events are sent to the grabbing client only
1701 and only if the grab event mask has selected for it. If such a passive
1702 grab deactivates, addional LeaveNotify events with mode
1703 XIPassiveUngrabNotify are generated and sent to the grabbing client
1704 before the grab deactivates.
1706 For GrabtypeTouchBegin, grab_mode must be Touch or a BadValue error
1709 See section <<multitouch-ownership, Ownership of touch sequences>> for
1710 additional notes on touch grabs, as they do not behave like traditional
1711 grabs: in particular, they do not freeze the device, and delivery of touch
1712 events continues even if the device is frozen due to a grab by another
1715 [[requests-passiveungrabdevice]]
1717 XIPassiveUngrabDevice
1722 num_modifiers: INT16
1723 modifiers: MODIFIERINFO
1726 Release an explicit passive grab on the specified input device.
1729 The device to establish the passive grab on.
1731 The button number or key symbol to ungrab.
1732 Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
1735 The type of grab to establish.
1737 Events are reported relative to the grab window.
1739 XKB modifier state to activate this passive grab.
1741 Number of elements in modifiers.
1743 This request has no effect if the client does not have a passive grab
1744 of the same type, same button or keycode (if applicable) and modifier
1745 combination on the grab_window.
1747 [[requests-listproperties]]
1752 num_properties: INT16
1753 properties: LISTofATOM
1756 List the properties associated with the given device.
1759 The device to list the properties for.
1761 Number of atoms in the reply
1763 All properties on the device.
1765 [[requests-changeproperty]]
1771 format: { 8, 16, 32 }
1772 mode: { Append, Prepend, Replace }
1774 data: LISTofINT8, or LISTofINT16, or LISTofINT32
1777 Change the given property on the given device.
1780 The device to change the property on.
1782 The property to modify.
1784 The property's type.
1786 One of Append, Prepend, or Replace
1788 Number of items following this request.
1790 Property data (nitems * format/8 bytes)
1792 The type is uninterpreted by the server. The format specifies whether
1793 the data should be viewed as a list of 8-bit, 16-bit, or 32-bit
1794 quantities so that the server can correctly byte-swap as necessary.
1796 If the mode is Replace, the previous propert y value is discarded. If
1797 the mode is Prepend or Append, then the type and format must match the
1798 existing property value (or a Match error results). If the property is
1799 undefined, it is treated as defined with the correct type and format
1800 with zero-length data. For Prepend, the data is tacked on to the
1801 beginning of the existing data, and for Append, it is tacked on to the
1802 end of the existing data.
1804 The lifetime of a property is not tied to the storing client. Properties
1805 remain until explicitly deleted, until the device is removed, or
1808 A property cannot be deleted by setting nitems to zero. To delete a
1809 property, use XIDeleteProperty.
1811 This request generates an XIPropertyEvent.
1813 [[requests-deleteproperty]]
1820 Deletes the given property on the given device.
1823 The device to delete the property on.
1825 The property to delete.
1827 If the property is deleted, an XIPropertyEvent is generated on the device.
1828 If the property does not exist, this request does nothing.
1830 [[requests-getproperty]]
1835 type: Atom or AnyPropertyType
1843 format: { 8, 16, 32 }
1844 data: LISTofINT8, or LISTofINT16, or LISTofINT32
1847 Get the data for the given property on the given device.
1850 The device to retrieve the property data from.
1852 The property to retrieve the data from..
1854 The property type to retrieve or AnyPropertyType
1856 The offset in 4-byte units.
1858 Number of bytes to receive in 4-byte units.
1860 Delete the property after retrieving the data.
1862 Number of unread bytes in the stored property
1864 Number of items in data
1868 Property data (nitems * format/8 bytes)
1870 If the specified property does not exist for the specified device, then
1871 the return type is None, the format and bytes-after are zero, and the value is
1872 empty. The delete argument is ignored in this case. If the specified property
1873 exists but its type does not match the specified type, then the return
1874 type is the actual type of the property, the format is the actual format of the
1875 property (never zero), the bytes-after is the length of the property in bytes
1876 (even if the format is 16 or 32), and the value is empty. The delete
1877 argument is ignored in this case. If the specified property exists and
1878 either AnyPropertyType is specified or the specified type matches the actual
1879 type of the property, then the return type is the actual type of the property,
1880 the format is the actual format of the property
1881 (never zero), and the bytes-after and value are as follows, given:
1882 N = actual length of the stored property in bytes
1883 (even if the format is 16 or 32)
1886 L = MINIMUM(T, 4 * long-length)
1888 The returned value starts at byte index I in the property (indexing
1889 from 0), and its length in bytes is L. However, it is a Value error if
1890 offset is given such that L is negative. The value of bytes_after is A,
1891 giving the number of trailing unread bytes in the stored property. If
1892 delete is True and the bytes_after is zero, the property is also
1893 deleted from the device, and a XIPropertyNotify event is generated on
1900 An event specifies its length in 4-byte units after the initial 32 bytes.
1901 Future versions of the protocol may provide additional information
1902 in the same event, thus increasing the event size. Clients are required to
1903 always read the number of bytes specified by the event, not the size of the
1904 event they may have been compiled against.
1907 The following event types are available in XI2.
1939 All events have a set of common fields specified as EVENTHEADER.
1942 EVENTHEADER { type: BYTE
1944 sequenceNumber: CARD16
1951 Always GenericEvent.
1953 Always the X Input extension offset.
1955 Sequence number of last request processed by the server.
1957 Length in 4-byte units after the initial 32 bytes.
1959 XI-specific event type.
1961 Numerical device id for a device.
1963 Time in ms when the event occurred.
1967 Events introduced in version 2.0
1968 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1970 [[events-hierarchyevent]]
1974 flags: SETofHIERARCHYMASK
1976 info: LISTofHIERARCHYINFO
1980 HIERARCHYMASK { MasterAdded, MasterRemoved, SlaveAttached, SlaveDetached,
1981 SlaveAdded, SlaveRemoved, DeviceEnabled, DeviceDisabled }
1983 HIERARCHYINFO { deviceid: DEVICEID,
1984 attachment: DEVICEID,
1987 flags: SETofHIERARCHYMASK}
1990 Set of the changes that have occured, causing this event.
1992 The number of device info structs following the request.
1994 The current hierarchy information.
1996 An XIHierarchyEvent is sent whenever the device hierarchy been
1997 changed. The flags specify all types of hierarchy modifiations that have
1999 For all devices, info details the hierarchy information after the
2000 modification of the hierarchy has occured. For each device specified with
2003 - if type is MasterPointer or MasterKeyboard, attachment decribes the
2004 pairing of this device.
2005 - if type is SlavePointer or SlaveKeyboard, attachment describes the
2006 master device this device is attached to.
2007 - if type is FloatingSlave device, attachment is undefined.
2010 True if the device is enabled and can send events. A disabled master
2011 device will not forward events from an attached, enabled slave
2014 Note: Multiple devices may be affected in one hierarchy change,
2015 deviceid in an XIHierarchyEvent is always the first affected
2016 device. Clients should ignore deviceid and instead use the devices list.
2018 [[events-devicechangedevent]]
2022 reason: CHANGEREASON
2025 classes: LISTofCLASS
2028 CHANGEREASON { SlaveSwitch, DeviceChange }
2030 A DeviceChangeEvent is sent whenever a device changes it's capabilities.
2031 This can happen either by a new slave device sending events through a
2032 master device, or by a physical device changing capabilities at runtime.
2035 The reason for generating this event.
2036 If reason is SlaveSwitch, the slave device sending events through
2037 this device has changed and source specifies the new slave device.
2038 A SlaveSwitch reason can only occur on a master device.
2039 If reason is DeviceChange, the device itself has changed through
2040 other means (e.g. a physical device change) and source is
2043 The source of the new classes.
2045 Number of classes provided.
2047 Details the available classes provided by the device. The order the
2048 classes are provided in is undefined.
2050 For a detailed description of classes, see the XIQueryDevice request.
2052 [[events-deviceevent]]
2065 valuators_len: CARD16
2069 flags: DEVICEEEVENTFLAGS
2070 buttons: SETofBUTTONMASK
2071 valuators: SETofVALUATORMASK
2072 axisvalues: LISTofFP3232
2075 BUTTONBIT { (1 << Button1), (1 << Button2), ... , (1 << ButtonN) }
2076 VALUATORBIT { (1 << 1), ( 1 << 2), ... ( 1 << n) }
2078 MODIFIERINFO { base_mods: CARD32,
2079 latched_mods: CARD32,
2080 locked_mods: CARD32,
2081 effective_mods: CARD32}
2082 GROUPINFO { base_group: CARD8,
2083 latched_group: CARD8,
2084 locked_group: CARD8,
2085 effective_group: CARD8}
2087 DEVICEEVENTFLAGS (all events): none
2088 DEVICEEVENTFLAGS (key events only): { KeyRepeat }
2089 DEVICEEVENTFLAGS (pointer events only): { PointerEmulated }
2090 DEVICEEVENTFLAGS (touch events only): { TouchPendingEnd,
2091 TouchEmulatingPointer }
2093 An XIDeviceEvent is generated whenever the logical state of a device
2094 changes in response to a button press, a button release, a motion, a key
2095 press or a key release. The event type may be one of KeyPress,
2096 KeyRelease, ButtonPress, ButtonRelease, Motion.
2098 XI 2.2: The event type may also be TouchBegin, TouchUpdate, or TouchEnd.
2101 The button number, key code, touch ID, or 0.
2105 The root window, event window or subwindow, respectively. See core
2106 protocol specification for more detail.
2109 The position of the pointer in screen coordinates (16.16 fixed point).
2112 The position of the pointer in screen coordinates relative to the
2113 event window (16.16 fixed point).
2116 The length of buttons in 4 byte units.
2118 The length of valuators in 4 byte units.
2120 The source device that originally generated the event.
2122 XKB modifier state before the event occured.
2124 XKB group state before the event.
2126 Button state before the event.
2128 Bitmask of valuators provided in axisvalues.
2130 Valuator data in device-native resolution.
2132 Miscellaneous information about this event; the union of the
2133 common flag set and either the key or pointer flag set,
2134 depending on the event type.
2135 KeyRepeat means that this event is for repeating purposes, and
2136 the physical state of the key has not changed. This is only
2137 valid for KeyPress events.
2138 PointerEmulated signals that the event has been emulated from another
2139 XI 2.x event for legacy client support, and that this event should
2140 be ignored if the client listens for these events. This flag is
2141 set on scroll ButtonPress and RawButtonPress events (buttons 4, 5, 6
2142 and 7) if a smooth-scrolling event on the Rel Vert Scroll or
2143 Rel Horiz Scroll axes was also generated. It is also set on Motion,
2144 ButtonPress, and ButtonRelease events generated by direct touch devices.
2145 TouchPendingEnd (for touch events only) means that the touch
2146 has physically ended, however another client still holds a grab, so the
2147 touch should be considered alive until all grabbing clients have
2148 accepted or passed on ownership. The touch will not generate any
2149 further TouchUpdate events once an event with TouchPendingEnd has been
2151 TouchEmulatingPointer is set on touch events that emulate pointer
2154 Modifier state in mods is detailed as follows:
2157 XKB base modifier state.
2159 XKB latched modifier state.
2161 XKB locked modifier state.
2163 Group state in group is detailed as follows:
2165 XKB base group state.
2167 XKB latched group state.
2169 XKB locked group state.
2171 In servers supporting XI 2.2, a TouchBegin event is generated whenever a new
2172 touch sequence initializes.
2173 A TouchEnd event is generated whenever a touch sequence ceases. A
2174 TouchUpdate event is generated whenever a valuator value changes, or a flag
2175 flag (e.g. pending end) has changed for that touch sequence; this may result
2176 in a TouchUpdate event being sent with zero valuators.
2178 The average finger size is significantly larger than one pixel. The
2179 selection of the hotspot of a touchpoint is implementation dependent and
2180 may not be the logical center of the touch.
2182 Touch tracking IDs are provided in the detail field of touch events. Its
2183 value is always provided in every touch event. Tracking IDs are
2184 represented as unsigned 32-bit values and increase strictly monotonically in
2185 value for each new touch, wrapping back to 0 upon reaching the numerical limit
2186 of IDs. The increment between two touch IDs is indeterminate. Clients may not
2187 assume that any future touches will have specific touch IDs. IDs are globally
2190 The button state in touch events represents the state of the device's
2191 physical buttons only, even if that sequence is emulating pointer events.
2193 Touch events do not generate enter/leave events.
2201 flags: DEVICEEVENTFLAGS
2202 valuators_len: CARD16
2203 valuators: SETofVALUATORMASK
2204 axisvalues: LISTofFP3232
2205 axisvalues_raw: LISTofFP3232
2210 A RawEvent provides the information provided by the driver to the
2211 client. RawEvent provides both the raw data as supplied by the driver and
2212 transformed data as used in the server. Transformations include, but are
2213 not limited to, axis clipping and acceleration.
2214 Transformed valuator data may be equivalent to raw data. In this case,
2215 both raw and transformed valuator data is provided.
2216 RawEvents are sent exclusively to all root windows.
2217 Clients supporting XI 2.0 receive raw events when the device is not grabbed,
2218 or when the device is grabbed by the client but not when the device is
2219 grabbed by another client.
2220 Clients supporting XI 2.1 or later receive raw events at all times, even
2221 when the device is grabbed by another client.
2225 The type of event that occured on the device.
2227 The button number, keycode or touch ID¹.
2229 The source device that originally generated the event. The sourceid
2230 is undefined for clients not supporting XI 2.1.
2232 Flags as described in DeviceEvent.
2234 The length of valuators in 4 byte units.
2236 Bitmask of valuators provided in axisvalues and axisvalues_raw.
2238 Valuator data in device-native resolution.
2240 Untransformed valuator data in device-native resolution.
2244 [[events-enterleave]]
2246 Enter or Leave or FocusIn or FocusOut
2257 detail: NOTIFYDETAIL
2263 buttons: SETofBUTTONMASK
2266 NOTIFYMODE { Normal, Grab, Ungrab }
2267 NOTIFYDETAIL { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual,
2268 Pointer, PointerRoot, None }
2270 Enter or Leave events are sent whenever a device's pointer enters or
2272 FocusIn or FocusOut events are sent whenever a device's focus is set to or
2274 The enter/leave and focus in/out model is described in the core protocol
2275 specification, Section 11. (EnterNotify, LeaveNotify events).
2277 For enter and leave events, the modifier and group state is the state of
2278 the paired master device if the device is a master device, or the state of
2279 the attached master keyboard if the device is an attached slave device, or
2280 zero if the device is a floating slave device.
2282 For focus in and out events, the button state is the state of the paired
2283 master device if the device is a master device, or the state of the
2284 attached master keyboard if the device is an attached slave device, or
2285 zero if the device is a floating slave device.
2290 The root window, event window, and child window, respectively. See the
2291 core protocol specification for more detail.
2293 The device that caused the pointer to move.
2296 The pointer coordinates relative to the root window.
2299 The pointer coordinates relative to the event window.
2301 Normal pointer motion events have mode Normal. Pseudo-motion events
2302 when a grab activates have mode Grab, and pseudo-motion events when a
2303 grab deactivates have mode Ungrab. Pseudo-motion events caused by the
2304 activation or deactivation of a passive enter or focus in grab have mode
2305 XIPassiveGrabNotify or XIPassiveUngrabNotify.
2307 Specifies the relation of the event window to the window the pointer
2308 entered or left. See the core protocol spec for details.
2310 True if the event window is on the same screen as the pointer's root
2313 If the event window is the focus window or an inferior of the focus
2314 window, then focus is True. Otherwise, focus is False. This field is
2315 unspecified for focus in/out events.
2317 XKB modifier state before the event occured.
2319 XKB group state before the event.
2321 The length of buttons in 4 byte units.
2323 Button state before the event.
2325 [[events-propertyevent]]
2330 what: { PropertyCreated, PropertyDeleted, PropertyModified }
2333 XIPropertyEvents are sent whenever a device property is created, deleted or
2334 modified by a client.
2337 The property that has been created, deleted, or modified
2339 Specifies what has been changed.
2342 Events introduced in version 2.2
2343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2345 [[events-touchownershipevent]]
2354 flags: SETofTOUCHOWNERSHIPFLAGS
2357 TOUCHOWNERSHIPFLAGS: (none currently defined)
2359 A TouchOwnershipEvent indicates that ownership has changed, and the client
2360 is now the owner of the touch sequence specified by touchid.
2363 The identifier of the touch sequence.
2367 The root window, event window, and child window, respectively. See the
2368 core protocol specification for more detail.
2370 The source device that originally generated the event.
2372 A bitmask of flags for this event.
2381 All use-cases that include the receiving and processing of touch events
2382 require the client to announce XI 2.2 support in the XIQueryVersion request.
2384 Client C wants to process touch events from a device D on window W.
2385 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2386 * C calls XISelectEvent for XI_Touch{Begin|Update|End} from D on W.
2387 * C receives TouchBegin whenever a touch sequence starts within W's borders.
2388 * C receives TouchUpdate events whenever an axis valuator value changes for a
2389 touch sequence it received a TouchBegin event for.
2390 * C receives TouchEnd whenever a touch it received a TouchBegin event for
2393 While client I wants to pre-process touch events from device D on the parent window of W.
2394 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2395 * C calls XISelectEvent for XI_Touch{Begin|Update|Ownership|End} from D on W.
2396 * I calls XIPassiveGrab for XI_Touch{Begin|Update|Ownership|End} from D on a
2398 * I receives TouchBegin whenever a touch begins within window W, as well as a
2399 TouchOwnership event indicating that it currently owns the touch sequence.
2400 C receives a TouchBegin event as well, but without TouchOwnership.
2401 * When an axis valuator changes in this touch sequence, both I and C receive a
2402 TouchUpdate event. I may process the event to determine if it is going to
2403 accept or reject the touch, whereas C may perform reversible processing.
2404 * If I decides it is going to claim the touch sequence for its exclusive
2405 processing, it calls XIAllowEvents with an event mode of XIAcceptTouch; at
2406 this point, C receives a TouchEnd event, and undoes any processing it has
2407 already performed due to the touch sequence. Further TouchUpdate events are
2408 delivered only to I.
2409 * Alternatively, if I decides it does not want to receive further events
2410 from this touch sequence, it calls XIAllowEvents with an event mode of
2411 XIRejectTouch; at this point, I receives a TouchEnd event confirming that it
2412 has rejected the touch. C receives a TouchOwnership event confirming that it
2413 is now the new owner of the touch, and further TouchUpdate events are
2414 delivered only to C. As C now owns the touch, it is free to perform
2415 irreversible processing of the sequence.
2416 * When the touch physically ceases, a TouchEnd event is sent to C.
2418 While client I wants to process pointer events on window W's parent, window Y.
2419 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2420 * I calls XIPassiveGrab for XI_{ButtonPress,MotionNotify,ButtonRelease} to
2421 create a synchronous pointer grab from D on Y.
2422 * C calls XISelectEvent for XI_Touch{Begin|Update|Ownership|End} from D on W.
2423 * I receives a ButtonPress event whenever a touch begins within W, and is
2424 considered the owner of the event. C receives a TouchBegin event, but does
2425 not receive a TouchOwnership event.
2426 * When the touchpoint moves, C will receive a TouchUpdate event. Event
2427 delivery to I is subject to the synchronous delivery mechanism. The
2428 emulated motion notify event is queued in the server while the device is
2430 * I may assert ownership by calling XIAllowEvents on Y with any mode other
2431 than ReplayDevice, which will cause all further events to be sent only to I,
2432 with a TouchEnd event being sent to C.
2433 * Alternatively, I may reject the touch sequence by calling XIAllowEvents on
2434 Y with mode ReplayDevice, which will cause no further events from that touch
2435 to be sent to I, and a TouchOwnership event to be sent to C, with subsequent
2436 motion events being sent as TouchUpdate events.
2438 Driver DRV provides touch support from tracked device D:
2439 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2440 * DRV initializes a TouchClass for the device.
2441 * DRV parses D's device protocol and selects one touch sequence to be emulated
2443 * DRV calls the respective input driver API with the touch sequence data. The
2444 touch sequence emulating a pointer has the respective flag set. DRV does not
2445 submit pointer data for any touchpoint.
projects / framework / uifw / xorg / proto / x11proto-input.git / blob