XI2proto.txt 107 KB
Newer Older
1 2
The X Input Extension 2.x
=========================
3
:toclevels: 3
4 5
:toc:
:numbered:
6

7
Authors:
8

9 10 11
- Peter Hutterer (Red Hat) <peter.hutterer@redhat.com>
- Daniel Stone (Collabora Ltd.) <daniel@fooishbar.org>
- Chase Douglas (Canonical, Ltd.) <chase.douglas@canonical.com>
12

13 14 15
[[history]]
History 
-------
16

17
- v2.3, December 2012: Pointer barrier events added
18
- v2.2, March 2012: Multitouch support added
19 20
- v2.1, December 2011: new raw event behaviour, smooth scrolling support
  added
21
- v2.0, October 2009: Initial release of XI2 protocol
22

23 24 25
[[intro-xi20]]
Introduction
------------
26 27 28 29

The X Input Extension version 2.0 (XI2) is the second major release of the X
Input Extension.

30
XI2 provides a number of enhancements over version 1.5, including:
Peter Hutterer's avatar
Peter Hutterer committed
31

32 33
- use of XGE and GenericEvents. GenericEvents are of flexible length with a
  minimum length of 32 bytes.
34
- explicit device hierarchy of master and slave devices. See Section
35
<<hierarchy,The Master/Slave device hierarchy>>.
Daniel Martin's avatar
Daniel Martin committed
36
- use of multiple independent master devices (Multi-Pointer X or MPX).
37 38 39 40 41 42 43 44 45 46 47 48 49
- the ability for devices to change capabilities at runtime.
- raw device events

XI2's intent is to replace both core input processing and prior versions of
the X Input Extension. Historically, the majority of applications employed the
core protocol requests and events to handle user input. The core protocol does
not provide information about which device generated the event. The X Input
Extension version up to 1.5 requires the differentiation between core and
extended devices. Extended devices may not be core devices and thus cannot be
used on applications employing the core protocol. XI2 addresses both of these
issues by enabling devices to be both extended and core devices and providing
device information in each event (with the exception of core events).

50 51
Changes in version 2.1
----------------------
52 53

- RawEvents are sent regardless of the grab state.
54
- Addition of the ScrollClass for smooth scrolling
55

56 57
Changes in version 2.2
----------------------
58

59
- Multitouch support added
60

61 62 63 64
Changes in version 2.3
----------------------

- Pointer barrier events added
Peter Hutterer's avatar
Peter Hutterer committed
65 66

//                            ❧❧❧❧❧❧❧❧❧❧❧
67

68 69
Notations used in this document
-------------------------------
70 71

Notation for requests:
Peter Hutterer's avatar
Peter Hutterer committed
72 73 74 75 76 77 78 79

    ┌───
        Name of request
            name of request field:       type of request field
            name of request field:       type of request field

            name of reply field:         type of reply field
    └───
80 81

Notation for events:
Peter Hutterer's avatar
Peter Hutterer committed
82 83 84 85 86 87

    ┌───
        Name of event
            name of field:               type of field
            name of field:               type of field
    └───
88 89

Complex fields are specified in the following notation:
Peter Hutterer's avatar
Peter Hutterer committed
90

91
          name of field:                  COMPLEXFIELDTYPE
Peter Hutterer's avatar
Peter Hutterer committed
92

93
or, if multiple of these fields exist:
Peter Hutterer's avatar
Peter Hutterer committed
94

95 96
          name of field:                  LISTofCOMPLEXFIELDTYPE

Peter Hutterer's avatar
Peter Hutterer committed
97 98
    COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
                         name of subfield:   type of subfield }
99

Peter Hutterer's avatar
Peter Hutterer committed
100
//                            ❧❧❧❧❧❧❧❧❧❧❧
101

102 103
Interoperability between version 1.x and 2.0
--------------------------------------------
104

105 106 107 108
There is little interaction between 1.x and 2.x versions of the X Input
Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as
possible. Several direct incompatibilities are observable:

109 110 111
[[interop-xi1-limitations]]
Limitations resulting from different variable ranges
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 113 114 115

XI2 provides a larger range for some fields than XI1. As a result, XI1 clients
may not receive data an XI2 client receives.
These fields include:
Peter Hutterer's avatar
Peter Hutterer committed
116

117 118 119
- devices with a deviceid of greater than 127 are invisible to XI1 clients.
- key events and key grabs featuring larger than 255 can only be sent to XI2
  clients.
120
- no subpixel information is available to XI1 clients. If motion events are in
121 122 123 124
  a subpixel range only, the server may omit these events and an XI 1.x client
  will not receive events until the pixel boundary is crossed.


125 126 127
[[interop-xi1-grabs]]
Blocking of grabs
~~~~~~~~~~~~~~~~~
128 129 130 131 132 133 134

XI1 grabs are different to XI2 grab and a device may not be grabbed through an
XI2 grab if an XI1 grab is currently active on this device or vice versa.
Likewise, a keycode or button already grabbed by an XI 1.x or XI2 client may
not be grabbed with the same modifier combination by an XI2 or XI 1.x client,
respectively.

135 136 137
[[interop-xi1-device-list]]
Invisibility of Master Devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138

139 140 141 142
XI 1.x was not designed with support for multiple master devices. As a
result, only the first master pointer and master keyboard are visible to XI
1.x clients; all other master devices are invisible and cannot be accessed
from XI 1.x calls.
143

144 145
Smooth scrolling
~~~~~~~~~~~~~~~~
146 147 148 149

Historically, X implemented scrolling events by using button press events:
button 4 was one “click” of the scroll wheel upwards, button 5 was downwards,
button 6 was one unit of scrolling left, and button 7 was one unit of scrolling
Peter Hutterer's avatar
Peter Hutterer committed
150 151 152
right.  This is insufficient for e.g. touchpads which are able to provide
scrolling events through multi-finger drag gestures, or simply dragging your
finger along a designated strip along the side of the touchpad.
153

154
Newer X servers may provide scrolling information through valuators to
155 156 157 158 159 160 161 162
provide clients with more precision than the legacy button events. This
scrolling information is part of the valuator data in device events.
Scrolling events do not have a specific event type.

Valuators for axes sending scrolling information must have one
ScrollClass for each scrolling axis. If scrolling valuators are present on a
device, the server must provide two-way emulation between these valuators
and the legacy button events for each delta unit of scrolling.
163 164 165 166 167 168 169 170 171 172 173 174 175

One unit of scrolling in either direction is considered to be equivalent to
one button event, e.g. for a unit size of 1.0, -2.0 on an valuator type
Vertical sends two button press/release events for button 4. Likewise, a
button press event for button 7 generates an event on the Horizontal
valuator with a value of +1.0. The server may accumulate deltas of less than
one unit of scrolling.

Any server providing this behaviour marks emulated button or valuator events
with the XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag
for raw events, to hint at applications which event is a hardware event.

If more than one scroll valuator of the same type is present on a device,
176 177 178 179 180
the valuator marked with Preferred for the same scroll direction is used to
convert legacy button events into scroll valuator events. If no valuator is
marked Preferred or more than one valuator is marked with Preferred for this
scroll direction, this should be considered a driver bug and the behaviour
is implementation-dependent.
181

182
[[hierarchy]]
183 184
The Master/Slave device hierarchy
---------------------------------
185 186 187 188

XI2 introduces a device hierarchy split up into so-called Master Devices (MD)
and Slave Devices (SD).

189
[[hierarchy-master]]
190 191
Master devices
~~~~~~~~~~~~~~
192 193 194 195 196 197 198 199 200
An MD is a virtual device created and managed by the server. MDs may send core
events and XI events. However, an MD does not represent a physical device and
relies on SDs for event generation. MDs come in two forms: as master pointers
or as master keyboards. A master pointer is represented by a visible cursor on
the screen. A master keyboard is represented by a keyboard focus.

Each master pointer is paired with the respective master keyboard and vice
versa, and this pairing is constant for the lifetime of both input devices.
Clients can use this pairing behaviour to implement input paradigms that
Alan Coopersmith's avatar
Alan Coopersmith committed
201
require pointer and keyboard integration (e.g. SHIFT + Click).
202

203
[[hierarchy-slave]]
204 205
Slave devices
~~~~~~~~~~~~~
206 207 208 209 210 211
An SD is usually a physical device configured in the server. SDs are not
represented by a cursor or keyboard focus and may be attached to a master
pointer or master keyboard. SDs can only be attached to any master of the same
type (e.g. a physical pointer device can be attached to any master pointer).

If an event is generated by an SD
Peter Hutterer's avatar
Peter Hutterer committed
212

213 214
- if the SD is attached to a master pointer, it changes the position and/or
  button state of the master pointer.
215 216
- if the SD has a keyboard focus other than None, the key event is sent to
  the focus window.
217 218 219
- if the SD is attached to a master keyboard, it sends events to this
  keyboard's focus window (if applicable) and/or changes the modifier state of
  this keyboard.
220
- if the SD is not attached to an MD ("floating"), it does not change
221 222 223 224
  any master device. The SD has its own (invisible) sprite and its own focus.
  Both the sprite and the focus must be managed explicitly by the client
  program.

225 226 227 228 229 230 231
Note: the keyboard focus of an attached slave device is independent to that
of the master device. Two keyboard events are generated, once with deviceid
and sourceid set to the slave device. This keyboard event is sent to the
slave device's focus window. The second event has a deviceid of the master
and a sourceid of the slave device. This second event is delivered to the
master keyboard's focus window.

232
[[hierarchy-dcce]]
233 234
Event processing for attached slave devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235 236

Whenever an SD changes its logical state,
Peter Hutterer's avatar
Peter Hutterer committed
237

238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
- the event is delivered as an XI event to any interested clients. If the
  device is floating, event processing stops.
  Otherwise, if the device is attached,
- the master device changes its classes to reflect the SD's capabilities. All
  interested clients are notified of this device change.
- then, the event is delivered as an XI event from the MD to any interested
  clients. If the event has been delivered, event processing stops.
  Otherwise,
- the event is delivered as a core event to any interested clients.

Given that W is the event window, and P the parent window of W, event delivery
to P is only attempted if neither the XI event, nor the core event has been
delivered on W. Once an event has been delivered as either XI or core event,
event processing stops.

253 254 255
[[clientpointer]]
The ClientPointer principle
~~~~~~~~~~~~~~~~~~~~~~~~~~~
256 257

Many core protocol and some extension requests are ambiguous when multiple
Peter Hutterer's avatar
Peter Hutterer committed
258
master devices are available (e.g. QueryPointer does not specify which pointer).
259 260 261 262 263 264 265 266 267
The X server does not have the knowledge to chose the contextually correct
master device. For each client, one master pointer is designated as this
clients's "ClientPointer". Whenever a client sends an ambiguous request (e.g.
QueryPointer), the ClientPointer or the keyboard paired with the ClientPointer
is chosen to provide the data for this request.

This ClientPointer may be explicitly assigned to a client with the
SetClientPointer call. If no ClientPointer is set when a client issues an
ambiguous request, the server choses one device as the ClientPointer. The
Alan Coopersmith's avatar
Alan Coopersmith committed
268
method of choosing a ClientPointer from the available master pointers is
269 270 271 272 273 274
implementation-specific.

If the master pointer currently set as ClientPointer for one or more clients is
removed, the server may either unset the ClientPointer setting or change the
ClientPointer to a different master pointer.

275 276 277
[[multitouch]]
Touch device support
--------------------
278

279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
XI 2.2 introduces support for multi-touch devices. The traditional
pointer/keyboard approach enforced by XI 2.0 with the master/slave device
hierarchy is not always suitable for multi-touch devices that can provide a
dynamic number of touchpoints per physical device; it is not known without
client-specific interpretation whether the touchpoints must be considered
separately or grouped together.

The additions in XI 2.2 aim to:

- support a dynamic number of simultaneous touch points,
- support devices that are both multi-touch and traditional pointer devices,
- allow touchpoints to be either grouped together or handled separately,
- be backwards-compatible to pre-XI 2.2 clients through emulation of XI 2.x/XI 1.x and core
  pointer events.

Touch events are only available to clients supporting version 2.2 or later of
the X Input Extension. Clients must use the XIQueryVersion request to announce
support for this version. Touch devices may generate emulated pointer events
alongside XI 2.2 touch events to support older clients; see Section
<<multitouch-processing,Touch event delivery>>.

300
Touch event processing differs from normal event processing in a few ways.
301 302 303
The most notable differences are that touch events are processed partially
out-of-band from pointer and keyboard events, and that touch events may be
sent to multiple clients simultaneously. For more details see Section
304
<<multitouch-processing, Touch event delivery>>.
305

306 307 308
[[multitouch-lifecycle]]
Touch event sequences
~~~~~~~~~~~~~~~~~~~~~
309

310
Touch input follows a three-stage cycle:
311 312 313 314 315 316

        begin - update - update - ... - end

i.e. “begin” the sequence by touching the device, “update” the current
touch location or properties any number of times, and finally “end” the
sequence by ceasing to touch the device.  Within this document, the term
317
"touch sequence" is used to describe the above sequence of events.
318
In the protocol, the three stages are represented with the event
319 320 321 322
types TouchBegin, TouchUpdate, and TouchEnd, respectively. A touch sequence
always generates TouchBegin and TouchEnd events, and may also generate
TouchUpdate events.  Clients must select for all three of these events
simultaneously.
323

324
When a touch starts, clients are sent a TouchBegin event
325
detailing the position of the touchpoint, as well as the
326 327
initial properties of the touchpoint.  Note that the logical state of the
device (as seen through the input protocol) may lag the physical state if event
Daniel Stone's avatar
Daniel Stone committed
328 329 330
processing is affected by grabs.  Multiple touchpoints may be active on the
same device at any time, potentially owned by and/or delivered to a different
set of clients.
331 332

Whenever the touch position or any other property of the touchpoint changes,
333
a TouchUpdate event is sent to all clients listening
334
to events for that touchpoint with the updated information.
335 336

When the touch has physically ended, or a client will otherwise not receive
337 338
any more events for a given touchpoint, a TouchEnd event will be sent to
that client.
339 340 341

Passive touch grabs are similar to standard input event grabs in that they
take precedence over event selections and are searched from the root window
342 343
to the child window (as opposed to selections, which start their search at the
child window and continue up to the root window).  When a touch grab activates,
344
the client whose grab activates becomes the “owner” of this touch sequence,
345 346 347
and must decide what to do with it, as per Section
<<multitouch-ownership,Ownership of touch sequences>>.  See the
<<requests-passivegrabdevice,XIPassiveGrabDevice>> request
Daniel Stone's avatar
Daniel Stone committed
348
documentation for more information on passive grab activation.
349

350
Only one client may select for touch events from a given device on a window.
351 352 353 354 355

[[multitouch-ownership]]
Ownership of touch sequences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

356
Once a grabbing client becomes the owner of a touch, it must either “accept” or
357 358
"reject" the touch sequence using the XIAllowEvents request. If a touch sequence
is rejected, a TouchEnd event is sent to the rejecting client, and it will not
359 360
receive any more events for this touch.  The server then looks to the next
window in the stack for another passive grab, and attempts to pass ownership
361 362 363 364 365 366 367
on to the next candidate for a passive grab (i.e. the next window towards
the final child window with a matching grab), or to the first applicable
event selection if there are no more grabs.

If a touch sequence is accepted by its owner, all other clients receive
TouchEnd events, and the touch sequence is exclusively delivered to the
owner from that point on.
368

369
If the touch sequence physically ends while the owner of the touch sequence
370 371 372 373 374 375 376 377 378 379
has not yet accepted or rejected ownership, the owner receives a TouchEnd
event and all other clients receive a TouchUpdate event with the
TouchPendingEnd flag set. The owner must still accept or reject the sequence
nonetheless. If the owner rejects the touch sequence, the server will still
attempt to exhaust all other passive grabs and/or event selections looking
for a final owner.

If the touch sequence has not physically ended yet and the owner of the
touch sequence rejects, the owner receives a TouchEnd event and ownership is
passed to the next client.
380 381

Clients may opt for touch events to be delivered before they become the
382 383 384 385
owner of the touch sequence. In this case, the logical state of the device (as
seen by means of the protocol) always matches the physical state of the device.
Clients must use caution if they opt for this feature; any action taken must be
undone if the touch sequence ends without the client becoming the owner.
386 387

To select for touch events regardless of ownership, a client must set the
388
TouchOwnership event mask in addition to the
389
TouchBegin, TouchUpdate and TouchEnd mask. When selected, a client will receive
Peter Hutterer's avatar
Peter Hutterer committed
390
touch events as they occur on the device. If and when the client
391 392 393
becomes the owner of a touch sequence, a TouchOwnership event is sent to the
client. If the client is the initial owner of the sequence, the TouchBegin is
immediately followed by the TouchOwnership event. Otherwise, TouchUpdate events
Alan Coopersmith's avatar
Alan Coopersmith committed
394
may precede a TouchOwnership event. A client is not guaranteed to become the
395
owner of any given touch sequence.
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411

The server delivers touch events to all clients that have selected for
TouchOwnership and to the current owner of the sequence in parallel.

If a client has selected for TouchOwnership and is not the current owner of
the sequence and the current owner accepts the sequence, the client receives
a TouchEnd event and no further events from this sequence are sent to this
client.

If a client has selected for TouchOwnership and the physical touch ends
before the current owner has accepted or rejected the sequence, the client
receives a TouchUpdate event with the TouchPendingEnd flag set. No further
TouchUpdate events will be sent for this sequence. If the current owner
accepts the sequence, the client receives a TouchEnd event. Otherwise, if
the current owner rejects the sequence, the client may become 
the owner of the touch sequence and receive a TouchOwnership event and a
412
TouchEnd event.
413

414 415 416
[[multitouch-device-modes]]
Touch device modes
~~~~~~~~~~~~~~~~~~
417 418 419 420

Touch devices come in many different forms with varying capabilities. The
following device modes are defined for this protocol:

Chase Douglas's avatar
Chase Douglas committed
421
'DirectTouch':
422
    These devices map their input region to a subset of the screen region. Touch
423
    events are delivered to window at the location of the touch. "direct"
Peter Hutterer's avatar
Peter Hutterer committed
424 425
    here refers to the user manipulating objects at their screen location.
    An example of a DirectTouch device is a touchscreen.
426

Chase Douglas's avatar
Chase Douglas committed
427
'DependentTouch':
428 429
    These devices do not have a direct correlation between a touch location and
    a position on the screen. Touch events are delivered according to the
430 431 432 433
    location of the device's cursor and often need to be interpreted
    relative to the current position of that cursor. Such interactions are
    usually the result of a gesture performed on the device, rather than
    direct manipulation. An example of a DependentTouch device is a
434
    trackpad.
435

436
A device is identified as only one of the device modes above at any time, and
437 438
the touch mode may change at any time. If a device's touch mode changes, an
XIDeviceChangedEvent is generated.
439

440 441 442
[[multitouch-processing]]
Touch event delivery
~~~~~~~~~~~~~~~~~~~~
443

444
For direct touch devices, the window set for event propagation is the set of
445 446
windows from the root window to the topmost window lying at the co-ordinates
of the touch.
447

Chase Douglas's avatar
Chase Douglas committed
448
For dependent devices, the window set for event propagation is the set of
449
windows from the root window to the window that contains the device's
Chase Douglas's avatar
Chase Douglas committed
450
pointer. A dependent device may only have one window set at a time, for all
451 452
touches. Any future touch sequence will use the same window set. The window set
is cleared when all touch sequences on the device end.
453 454

A window set is calculated on TouchBegin and remains constant until the end
455
of the sequence. Modifications to the window hierarchy, new grabs or changed
456 457
event selection do not affect the window set.

458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
Pointer control of dependent devices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On a dependent device, the device may differ between a pointer-controlling
touch and a non-pointer-controlling touch. For example, on a touchpad the
first touch is pointer-controlling (i.e. serves only to move the visible
pointer). Multi-finger gestures on a touchpad cause all touches to be
non-pointer-controlling.

For pointer-controlling touches, no touch events are sent; the touch
generates regular pointer events instead. Non-pointer-controlling touches
send touch events. A touch may change from pointer-controlling to
non-pointer-controlling, or vice versa.

- If a touch changes from pointer-controlling to non-pointer-controlling,
 a new touch ID is assigned and a TouchBegin is sent for the last known
 position of the touch. Further events are sent as TouchUpdate events, or as
 TouchEnd event if the touch terminates.

- If a touch changes from non-pointer-controlling to pointer-controlling, a
  TouchEnd is sent for that touch at the last known position of the touch.
  Further events are sent as pointer events.

The conditions to switch from pointer-controlling to non-pointer-controlling
touch is implementation-dependent. A device may support touches that are
both pointer-controlling and a touch event.

Peter Hutterer's avatar
Peter Hutterer committed
484 485 486 487
In the dependent touch example event sequence below, touches are marked when
switching to pointer-controlling (pc) or to non-pointer-controlling (np).

.Dependent touch example event sequence on a touchpad
488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509
[width="50%", options="header"]
|====================================================
| Finger 1 | Finger 2 | Event generated(touchid)
|  down    |          | Motion
|  move    |          | Motion
|  move    |          | Motion
|  (np)    |   down   | TouchBegin(0), TouchBegin(1)
|  move    |    --    | TouchUpdate(0)
|   --     |   move   | TouchUpdate(1)
|   up     |   (pc)   | TouchEnd(0), TouchEnd(1)
|          |   move   | Motion
|  down    |   (np)   | TouchBegin(2), TouchBegin(3)
|  move    |    --    | TouchUpdate(2)
|   up     |   (pc)   | TouchEnd(2), TouchEnd(3)
|          |    up    | Motion
|  down    |          | Motion
|  (np)    |   down   | TouchBegin(4), TouchBegin(5)
|  (pc)    |    up    | TouchEnd(4), TouchEnd(5)
|  move    |          | Motion
|   up     |          | Motion
|====================================================

510

511 512 513
[[multitouch-emulation]]
Pointer emulation from multitouch events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
514

515 516
Touch sequences from direct touch devices may emulate pointer events. Only one
touch sequence from a device may emulate pointer events at a time; which touch
Peter Hutterer's avatar
Peter Hutterer committed
517
sequence emulates pointer events is implementation-dependent.
518 519 520

Pointer events are emulated as follows:

521 522 523 524
- A TouchBegin event generates a pointer motion event to the location of the
  touch with the same axis values of the touch event, followed by a button press
  event for button 1.
- A TouchUpdate event generates a pointer motion event to the location of the
525 526
  touch and/or to update axis values of the pointer device. The button state
  as seen from the protocol includes button 1 set.
527 528
- A TouchEnd event generates a pointer motion event to the location of the touch
  and/or to update the axis values if either have changed, followed by a button
529 530
  release event for button 1. The button state as seen from the protocol
  includes button 1 set.
531

532 533
If a touch sequence emulates pointer events and an emulated pointer event
triggers the activation of a passive grab, the grabbing client becomes the
534
owner of the touch sequence.
535

536
The touch sequence is considered to have been accepted if
537 538 539

- the grab mode is asynchronous, or
- the grab mode is synchronous and the device is thawed as a result of
540
  AllowEvents with AsyncPointer or AsyncDevice
541 542 543 544

Otherwise, if the button press is replayed by the client, the touch sequence
is considered to be rejected.

545 546
Touch event delivery precedes pointer event delivery. A touch event emulating
pointer events is delivered:
547

548
- as a touch event to the top-most window of the current window set if a
549
  client has a touch grab on this window,
550 551
- otherwise, as a pointer event to the top-most window of the current window
  set if a client has a pointer grab on this window,
552 553
- otherwise, to the next child window in the window set until a grab has been
  found.
554

555 556
If no touch or pointer grab on any window is active and the last window in the
window set has been reached, the event is delivered:
557

558 559 560 561
- as a touch event to the window if a client has selected for touch events
  on this window
- otherwise, as a pointer event to the window if a client has selected for
  pointer events.
562 563
- otherwise, to the next parent window in the window set until a selection has
  been found.
Peter Hutterer's avatar
Peter Hutterer committed
564

565 566
Emulated pointer events will have the PointerEmulated flag set. A touch
event that emulates pointer events has the TouchEmulatingPointer flag set.
Peter Hutterer's avatar
Peter Hutterer committed
567

568 569 570 571 572 573 574 575 576

[[barrier-events]]
Pointer barrier events
^^^^^^^^^^^^^^^^^^^^^^
If a master pointer moves against a pointer barrier blocking movement in
that pointer's direction, the movement of the pointer is clamped to the x or
y coordinate of the barrier, whichever applies. For a description of pointer
barriers and barrier creation and destruction see the XFixes protocol
specification v 5.0 or later.
577
https://gitlab.freedesktop.org/xorg/proto/xorgproto/raw/master/fixesproto.txt
578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615

A pointer hitting a blocking barrier creates a new barrier event sequence,
identified by a unique event ID. A new event ID is assigned when the pointer
first hits a barrier. Subsequent movements against or along the pointer
barrier are assigned the same event ID. The event generated by the pointer
leaving the barrier, or being released by a client request, is the last
event with this event ID. Any future movements of this device blocked by
this barrier will be assigned a new event ID.

Pointer barrier events are delivered exclusively to the client that created
the barrier, and to the window specified in the CreatePointerBarrier
request (the "barrier window"). A pointer barrier blocks pointer movement
regardless of whether its window is mapped and/or viewable. If the pointer
barrier window is destroyed, the pointer barrier remains blocking but a
client will not receive further events.

If a device is actively grabbed by a client or a passive grab activated
for this client, and the pointer moves against a pointer barrier created by
this client and the grab-window is the barrier window, that client will
receive pointer barrier events if:
- owner-events is true or false and the grab's event mask includes
  pointer barrier events, or
- owner-events is true and the client has selected for barrier events on the
  barrier window.

If the grab-window is not the barrier window, the client will receive events
if:
- the client has selected for barrier events on the barrier window.

If the barrier is not owned by this client, no barrier events are sent to
this client. The client owning the barrier will receive events if:
- the client has pointer barrier events selected on the window associated
  with the pointer barrier

The BarrierDeviceIsGrabbed flag is set whenever a pointer barrier event is
generated while the device is actively grabbed by any client or a passive
grab has activated for this device prior to the event.

616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652
[[glossary-notations]]
Notations used in this document
-------------------------------

Notation for requests:

    ┌───
        Name of request
            name of request field:       type of request field
            name of request field:       type of request field

            name of reply field:         type of reply field
    └───

Notation for events:

    ┌───
        Name of event
            name of field:               type of field
            name of field:               type of field
    └───

Complex fields are specified in the following notation:

          name of field:                  COMPLEXFIELDTYPE

or, if multiple of these fields exist:

          name of field:                  LISTofCOMPLEXFIELDTYPE

    COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
                         name of subfield:   type of subfield }


[[glossary-datatypes]]
Data types
----------
Peter Hutterer's avatar
Peter Hutterer committed
653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671

    BUTTONMASK
            A binary mask defined as (1 << button number).
            A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK.

    DEVICE { DEVICEID, AllDevices, AllMasterDevices }
            A DEVICE specifies either a DEVICEID or AllDevices or
            AllMasterDevices.

    DEVICEID { CARD16 }
            A DEVICEID is a numerical ID for a device currently available in the
            server. The server may re-use a device ID after a device's removal.
            The device IDs 0 and 1 are reserved.
            AllDevices ........ 0
            AllMasterDevices .. 1

    DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer,
                SlaveKeyboard, FloatingSlave }
            A DEVICEUSE field specifies the current use of a device in the MD/SD
672 673
            device hierarchy. See Section "The Master/Slave device hierarchy"
            for more information.
Peter Hutterer's avatar
Peter Hutterer committed
674

675 676 677
    EVTYPEMASK
            An EVTYPEMASK is a binary mask defined as (1 << event type).
            A SETofEVTYPEMASK is a binary OR of zero or more EVTYPEMASK.
Peter Hutterer's avatar
Peter Hutterer committed
678 679 680

    FP1616
            Fixed point decimal in 16.16 format as one INT16 and one CARD16.
Daniel Martin's avatar
Daniel Martin committed
681
            The INT16 contains the integral part, the CARD16 the decimal fraction
Peter Hutterer's avatar
Peter Hutterer committed
682 683 684 685 686 687 688
            shifted by 16.

    FP3232
            Fixed point decimal in 32.32 format as one INT32 and one CARD32.
            The INT32 contains the integral part, the CARD32 the decimal fraction
            shifted by 32.

689 690 691 692 693
    MODIFIERMASK
            A MODIFIERMASK is a binary mask defined as (1 << modifier map index).
            A SETofMODIFIERMASK is a binary OR of zero or more MODIFIERMASK or
            GrabAnyModifier.

Peter Hutterer's avatar
Peter Hutterer committed
694 695 696 697
    VALUATORMASK
            A binary mask defined as (1 << valuator number).
            A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK.

698

699 700 701
[[errors]]
Errors
------
702 703 704

Errors are sent using core X error reports.

Peter Hutterer's avatar
Peter Hutterer committed
705 706 707
    Device
            A value for a DEVICE argument does not specify a valid DEVICE.

708

709
[[requests]]
710 711
Requests
--------
712 713 714 715 716 717

The server does not guarantee that the length of a reply remains constant in
future revisions of XI2. A client must always retrieve the exact length of the
protocol reply from the connection, even if the reply is longer than defined
for the XI2 version supported by the client.
Additional bytes in a request may include data supported in later versions of
718 719
XI2. Clients should ignore this data. Padding bytes in XI2 protocol requests
are required to be 0.
720

721 722 723
[[requests-xi20]]
Requests introduced in version 2.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
724

725
[[requests-queryversion]]
726 727
XIQueryVersion
^^^^^^^^^^^^^^
728 729 730 731 732 733 734 735 736
    ┌───
        XIQueryVersion
        major_version:          CARD16
        minor_version:          CARD16

        major_version:          CARD16
        minor_version:          CARD16
    └───

Peter Hutterer's avatar
Peter Hutterer committed
737 738 739 740 741 742
The client sends the highest supported version to the server and the
server sends the highest version it supports, but no higher than the
requested version. Major versions changes can introduce incompatibilities
in existing functionality, minor version changes introduce only backward
compatible changes.  It is the client's responsibility to ensure that the
server supports a version which is compatible with its expectations.
743 744 745 746 747 748

    major_version
        Major XI2 version.
    minor_version
        Minor XI2 version.

Peter Hutterer's avatar
Peter Hutterer committed
749
If major_version is less than 2, a BadValue error occurs.
750

751
[[requests-querydevice]]
752 753
XIQueryDevice
^^^^^^^^^^^^^
754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770
    ┌───
        XIQueryDevice
        DEVICE                  deviceid

        num_devices:            CARD16
        deviceinfo:             LISTofDEVICEINFO
    └───

    DEVICEINFO { deviceid:              DEVICEID
                 use:                   DEVICEUSE
                 attachment:            DEVICEID
                 enabled:               BOOL
                 num_classes:           CARD16
                 name_len:              CARD16
                 name:                  LISTofCHAR8
                 classes:               LISTofCLASS }

771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
    CLASS { BUTTONCLASS, KEYCLASS, VALUATORCLASS, SCROLLCLASS, TOUCHCLASS }

    BUTTONCLASS   { type:                 ButtonClass
                    length:               CARD16
                    sourceid:             CARD16
                    num_buttons:          CARD16
                    state:                SETofBUTTONMASK
                    labels:               LISTofATOM }

    KEYCLASS      { type:                 KeyClass
                    length:               CARD16
                    sourceid:             CARD16
                    num_keys:             CARD16
                    keys:                 LISTofCARD32 }

    VALUATORCLASS { type:                 ValuatorClass
                    length:               CARD16
                    sourceid:             CARD16
                    number:               CARD16
                    label:                ATOM
                    min:                  FP3232
                    max:                  FP3232
                    value:                FP3232
                    resolution:           CARD32
                    mode:                 CARD8 }

    SCROLLCLASS¹  { type:                 ScrollClass
                    length:               CARD16
                    sourceid:             CARD16
                    number:               CARD16
                    scroll_type:          SCROLLTYPE
                    flags:                SETofSCROLLFLAGS
                    increment:            FP3232 }
804 805 806 807 808

    SCROLLTYPE { Vertical, Horizontal }

    SCROLLFLAGS { NoEmulation, Preferred }

Peter Hutterer's avatar
Peter Hutterer committed
809
    TOUCHCLASS² { type:                 TouchClass
810 811 812
                  length:               CARD16
                  sourceid:             CARD16
                  mode:                 TOUCHMODE
813
                  num_touches:          CARD16 }
814

815
    TOUCHMODE { DirectTouch, DependentTouch }
816

Peter Hutterer's avatar
Peter Hutterer committed
817 818
    ¹ since XI 2.1
    ² since XI 2.2
819

Peter Hutterer's avatar
Peter Hutterer committed
820
XIQueryDevice details information about the requested input devices.
821 822

    devices
823 824 825 826
        The device to list. If devices is AllDevices, all enabled and
        disabled devices are listed. If devices is AllMasterDevices, all
        enabled and disabled master devices are listed. If devices is a
        valid DEVICE, only this DEVICE is listed and num_devices is 1.
827
    num_devices
828
        The number of deviceinfos returned.
829

Peter Hutterer's avatar
Peter Hutterer committed
830 831
Each deviceinfo is detailed as follows:

832 833 834 835
    deviceid
        The unique ID of the device. Device IDs may get re-used when a device
        is removed.
    use
836 837 838 839 840
        If the device is a master pointer, use is MasterPointer.
        If the device is a master keyboard, use is MasterKeyboard.
        If the device is a slave pointer, use is SlavePointer.
        If the device is a slave keyboard, use is SlaveKeyboard.
        If the device is a floating slave, use is FloatingSlave.
841
    attachment
842
        If the device is a master pointer or a master keyboard, attachment
843 844
        specifies the paired master keyboard, or the paired master pointer,
        respectively.  If the device is a non-floating slave device
845 846
        attachment specifies the master device this device is attached to.
        If the device is a floating slave, attachment is undefined.
847
    enabled
848
        Zero if the device is disabled, nonzero otherwise.
849
    num_classes
850
        Number of classes provided.
851
    name_len
852
        Length of the name in bytes not including padding.
853 854 855 856
    classes
        Details the available classes provided by the device in an undefined
        order.
    name
857
        The device's name. padded to a multiple of 4 bytes.
858

Peter Hutterer's avatar
Peter Hutterer committed
859 860 861 862
For all classes, type specifies the device class. Clients are required
to ignore unknown device classes. The length field specifies the length
of the class in 4 byte units.
The following classes may occur only once: ButtonClass, KeyClass
863 864 865 866 867 868

    ButtonClass:
    type
        Always ButtonClass.
    length
        Length in 4 byte units.
869 870
    sourceid
        The device this class originates from.
871 872
    num_buttons
        Number of buttons provided by the device.
873
    labels
874
        List of Atoms specifying the label for each button. An Atom of None
875
        specifies an unlabeled button. Buttons are listed in the device-native
876
        order regardless of the current button mapping.
877
    state
878 879 880 881
        The current button mask for this device after button mapping is
        applied. Each bit representing a button is 1 if this button is
        logically down, or 0 otherwise. State is a multiple of 4-byte units
        and always contains at least num_buttons bits.
882 883 884 885 886 887

    KeyClass:
    type
        Always KeyClass.
    length
        Length in 4 byte units.
888 889
    sourceid
        The device this class originates from.
890 891 892 893 894
    num_keys
        Number of keycodes provided by the device.
    keys
        List of keycodes provided.

895
    ValuatorClass:
896
    type
897
        Always ValuatorClass.
898 899
    length
        Length in 4 byte units.
900 901
    sourceid
        The device this class originates from.
902 903
    number
        Valuator number of this axis. The valuator number is in device-native
904
        order and potential axis mappings are ignored.
905 906
    label
        Atom specifying the axis name. An Atom of None specifies an unlabeled
907 908 909 910 911 912 913 914 915
        axis.
    min
        Minimum value.
    max
        Minimum value.
    resolution
        Resolution in counts/meter.
    mode
        Relative or Absolute.
916 917
    value
        Last published axis value (if mode is absolute).
918

Peter Hutterer's avatar
Peter Hutterer committed
919 920
An axis in Relative mode may specify min and max as a hint to the
client. If no min and max information is available, both must be 0.
921

922 923 924
    ScrollClass:
    type
        Always ScrollClass.
925 926
    number
        Valuator number that is referred to. This valuator number must be listed in
927 928 929 930 931 932 933 934 935 936 937 938 939 940
        the ValuatorClassInfo.
    scroll_type:
        Vertical for a vertical scrolling axis, Horizontal for a horizontal
        scrolling axis.
    flags:
        A set of flags that apply to this scroll axis.
        NoEmulation: no legacy scroll button events are generated for events
                     on this scrolling axis.
        Preferred: This axis is the preferred axis for emulating valuator
                   events from legacy scroll button events.
    increment:
        The valuator delta equivalent to one positive unit of scrolling.

A ScrollClass may only exist if the device has at least one ValuatorClass
941
and each valuator number listed in any ScrollClass. Only one ScrollClass may
942 943
exist per ValuatorClass.

944 945 946 947 948 949 950 951
    TouchClass:
    type
        Always TouchClass.
    length
        Length in 4 byte units.
    sourceid
        The device this class originates from.
    mode
952
        The device type of the touch device.  This mode may change at runtime.
953 954 955 956 957
    num_touches
        The maximum number of simultaneous touchpoints the device may send.
        If num_touches is 0, the number of supported touches is unknown or
        unlimited.

958
Devices with a TouchClass emit touch events with the same axes as pointer
959
events.
960

961
[[requests-selectevents]]
962 963
XISelectEvents
^^^^^^^^^^^^^^
964 965 966 967
    ┌───
        XISelectEvents
            window:         Window
            num_masks:      CARD16
968
            masks:          LISTofEVENTMASK
969 970 971

    └───

972 973
    EVENTMASK { deviceid:          DEVICE,
                mask_len:          CARD16,
974
                mask:              SETofEVTYPEMASK }
975 976 977 978

    window
        The window to select the events on.
    num_masks
979
        Number of items in masks.
980 981 982
    deviceid
        Numerical deviceid, or AllDevices, or AllMasterDevices.
    mask_len
983
        Length of mask in 4 byte units.
984 985 986
    mask
        Event mask. An event mask for an event type T is defined as (1 << T).

Peter Hutterer's avatar
Peter Hutterer committed
987
XISelectEvents selects for XI2 events on window.
988

Peter Hutterer's avatar
Peter Hutterer committed
989
If num_masks is 0, a BadValue error occurs.
990

Peter Hutterer's avatar
Peter Hutterer committed
991 992 993 994 995 996 997 998 999
Each mask sets the (and overwrites a previous) event mask for the DEVICE
specified through deviceid. The device AllDevices or
AllMasterDevices is treated as a separate device by server. A client's
event mask is the union of AllDevices, AllMasterDevices and the
per-device event mask.
The removal of device from the server unsets the event masks for the
device. If an event mask is set for AllDevices or AllMasterDevices, the
event mask is not cleared on device removal and affects all future
devices.
1000

Peter Hutterer's avatar
Peter Hutterer committed
1001
If mask_len is 0, the event mask for the given device is cleared.
1002

Peter Hutterer's avatar
Peter Hutterer committed
1003 1004
The mask for XIHierarchyEvents may only be selected for XIAllDevices.
Setting it for any other device results in a BadValue error.
1005

1006
A client selecting for any of XI_TouchBegin, XI_TouchUpdate, or XI_TouchEnd
1007 1008 1009 1010 1011 1012
must select for all three events at the same time, else a BadValue error
will be generated. A client selecting for XI_TouchOwnership must select for
all three of the other touch events. If the selection for these touch events
overlaps a current selection by another client (e.g. selecting for a
specific device when another client has a selection for XIAllDevices), a
BadAccess error occurs.
1013

1014
[[requests-getselectedevents]]
1015 1016
XIGetSelectedEvents
^^^^^^^^^^^^^^^^^^^
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027
    ┌───
        XIGetSelectedEvents
            window:         Window

            num_masks:      CARD16
            masks:          LISTofEVENTMASK
    └───

    window
        The window to select the events on.
    num_masks
1028
        Number of items in masks.
1029 1030 1031
    masks
        Selected event masks by this client.

Peter Hutterer's avatar
Peter Hutterer committed
1032 1033 1034 1035
Masks are returned on a per-device basis, with masks for AllDevices and
AllMasterDevices returned separately. A client can calculate the
effective mask for a device with a bitwise OR of the AllDevices, the
AllMasterDevices and the device-specific mask.
1036

Peter Hutterer's avatar
Peter Hutterer committed
1037 1038
If num_masks is 0, no events have been selected by this client on the
given window.
1039

1040
[[requests-querypointer]]
1041 1042
XIQueryPointer
^^^^^^^^^^^^^^
1043
    ┌───
1044
        XIQueryPointer
1045 1046 1047 1048 1049 1050 1051 1052 1053 1054
            window:         Window
            deviceid:       DEVICEID

            root:           Window
            child:          Window
            root_x:         FP1616
            root_y:         FP1616
            win_x:          FP1616
            win_y:          FP1616
            same_screen:    BOOL
1055 1056 1057 1058
            mods:           MODIFIERINFO
            group:          GROUPINFO
            buttons_len:    CARD16
            buttons:        SETofBUTTONMASK
1059 1060
    └───

Peter Hutterer's avatar
Peter Hutterer committed
1061
Query a master pointer device for its current position.
1062 1063 1064 1065

    root
        The root window the pointer is logically on.
    child
1066
        The child window of window that contains the pointer or None.
1067 1068 1069 1070 1071
    root_x
    root_y
        Pointer position relative to the root window's origin.
    win_x
    win_y
1072
        Pointer position relative to window or 0 if same_screen is false.
1073
    same_screen
1074
        True if window is on the same screen as the pointer.
1075 1076 1077 1078 1079
    mods
        XKB modifier state on the paired device.
    group
        XKB group state on the paired device.
    buttons_len
1080
        The length of buttons in 4 byte units.
1081 1082
    buttons
        Button state.
1083

Peter Hutterer's avatar
Peter Hutterer committed
1084 1085
If the device is not a master pointer device or not a floating slave
pointer, a BadDevice error results.
1086

1087
[[requests-warppointer]]
1088 1089
XIWarpPointer
^^^^^^^^^^^^^
1090
    ┌───
1091
        XIWarpPointer
1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102
            src_win:         Window
            dst_win:         Window
            src_x:           FP1616
            src_y:           FP1616
            src_width:       INT16
            src_height:      INT16
            dst_x:           FP1616
            dst_y:           FP1616
            deviceid:        DEVICEID
    └───

Peter Hutterer's avatar
Peter Hutterer committed
1103 1104 1105
WarpPointer moves the pointer of deviceid as if the user had moved
the pointer. WarpPointer can only be called for MasterPointer and
FloatingSlave devices.
1106 1107 1108 1109 1110 1111 1112

    src_win
       If src_window is not None, the move only takes place if src_window
       contains the pointer and the pointer is contained in the specified
       rectangle of src_window.
    dst_win
       If dst_win is None, this request moves the pointer by offsets
1113
       dst_x/dst_y relative to the current position of the pointer. If
1114
        dst_window is a window, this request moves the pointer to
1115
       dst_x/dst_y relative to dst_win's origin.
1116 1117 1118 1119 1120 1121 1122
    src_x
    src_y
    src_width
    src_height
       Specifies the source window rectangle.
    dst_x
    dst_y
1123 1124
        The relative coordinates to move the pointer if dst_win is None, or
        the absolute coordinates if dst_win is a window.
1125 1126 1127
    deviceid
        The device to warp.

Peter Hutterer's avatar
Peter Hutterer committed
1128 1129 1130
This request cannot be used to move the pointer outside the confine-to
window of an active pointer grab. An attempt will only move the pointer as
far as the closest edge of the confine-to window.
1131

Peter Hutterer's avatar
Peter Hutterer committed
1132 1133
This request will generate events just as if the user had instantaneously
moved the pointer.
1134

1135
[[requests-changecursor]]
1136 1137
XIChangeCursor
^^^^^^^^^^^^^^
1138
    ┌───
1139
        XIChangeCursor
1140 1141 1142 1143 1144
            win:             Window
            cursor:          Cursor
            deviceid:        DEVICEID
    └───

Peter Hutterer's avatar
Peter Hutterer committed
1145
Change a master pointer's cursor on the specified window.
1146