XI2proto.txt

   1
   2                             The X Input Extension
   3                                 Version 2.0
   4
   5                               Peter Hutterer
   6                          peter.hutterer@redhat.com
   7                                Red Hat, Inc.
   8
   9
  10
  11 1. Introduction
  12
  13 The X Input Extension version 2.0 (XI2) is the second major release of the X
  14 Input Extension.
  15
  16 XI2 provides a number of enhancements over version 1.5, including:
  17 - use of XGE and GenericEvents. GenericEvents are of flexible length with a
  18   minimum length of 32 bytes.
  19 - explicit device hierarchy of master and slave devices. See Section 4.
  20 - use of multiple independent master devices (Multi-Poiner X or MPX).
  21 - the ability for devices to change capabilities at runtime.
  22 - raw device events
  23
  24 XI2's intent is to replace both core input processing and prior versions of
  25 the X Input Extension. Historically, the majority of applications employed the
  26 core protocol requests and events to handle user input. The core protocol does
  27 not provide information about which device generated the event. The X Input
  28 Extension version up to 1.5 requires the differentiation between core and
  29 extended devices. Extended devices may not be core devices and thus cannot be
  30 used on applications employing the core protocol. XI2 addresses both of these
  31 issues by enabling devices to be both extended and core devices and providing
  32 device information in each event (with the exception of core events).
  33
  34                               ❧❧❧❧❧❧❧❧❧❧❧
  35
  36 2. Notations used in this document
  37
  38 Notation for requests:
  39 ┌───
  40     Name of request
  41         name of request field:       type of request field
  42         name of request field:       type of request field
  43         ▶
  44         name of reply field:         type of reply field
  45 └───
  46
  47 Notation for events:
  48 ┌───
  49     Name of event
  50         name of field:               type of field
  51         name of field:               type of field
  52 └───
  53
  54 Complex fields are specified in the following notation:
  55           name of field:                  COMPLEXFIELDTYPE
  56 or, if multiple of these fields exist:
  57           name of field:                  LISTofCOMPLEXFIELDTYPE
  58
  59 COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
  60                     name of subfield:   type of subfield }
  61
  62                               ❧❧❧❧❧❧❧❧❧❧❧
  63
  64 3. Interoperability between version 1.x and 2.0
  65
  66 There is little interaction between 1.x and 2.x versions of the X Input
  67 Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as
  68 possible. Several direct incompatibilities are observable:
  69
  70 3.1 Limitations resulting from different variable ranges
  71
  72 XI2 provides a larger range for some fields than XI1. As a result, XI1 clients
  73 may not receive data an XI2 client receives.
  74 These fields include:
  75 - devices with a deviceid of greater than 127 are invisible to XI1 clients.
  76 - key events and key grabs featuring larger than 255 can only be sent to XI2
  77   clients.
  78 - no subpixel information is avialable to XI1 clients. If motion events are in
  79   a subpixel range only, the server may omit these events and an XI 1.x client
  80   will not receive events until the pixel boundary is crossed.
  81
  82
  83 3.2 Blocking of grabs
  84
  85 XI1 grabs are different to XI2 grab and a device may not be grabbed through an
  86 XI2 grab if an XI1 grab is currently active on this device or vice versa.
  87 Likewise, a keycode or button already grabbed by an XI 1.x or XI2 client may
  88 not be grabbed with the same modifier combination by an XI2 or XI 1.x client,
  89 respectively.
  90
  91 3.3 Invisibility of Master Devices
  92
  93 XI 1.x was not designed with support for multiple master devices (see Section
  94 4). As a result, only the first master pointer and master keyboard are visible
  95 to XI 1.x clients, all other master devices are invisible and cannot be
  96 accessed from XI 1.x calls.
  97
  98                               ❧❧❧❧❧❧❧❧❧❧❧
  99
 100 4. The Master/Slave device hierarchy
 101
 102 XI2 introduces a device hierarchy split up into so-called Master Devices (MD)
 103 and Slave Devices (SD).
 104
 105 4.1 Master devices
 106 An MD is a virtual device created and managed by the server. MDs may send core
 107 events and XI events. However, an MD does not represent a physical device and
 108 relies on SDs for event generation. MDs come in two forms: as master pointers
 109 or as master keyboards. A master pointer is represented by a visible cursor on
 110 the screen. A master keyboard is represented by a keyboard focus.
 111
 112 Each master pointer is paired with the respective master keyboard and vice
 113 versa, and this pairing is constant for the lifetime of both input devices.
 114 Clients can use this pairing behaviour to implement input paradigms that
 115 require pointer and keyboard interation (e.g. SHIFT + Click).
 116
 117 4.2 Slave devices
 118 An SD is usually a physical device configured in the server. SDs are not
 119 represented by a cursor or keyboard focus and may be attached to a master
 120 pointer or master keyboard. SDs can only be attached to any master of the same
 121 type (e.g. a physical pointer device can be attached to any master pointer).
 122
 123 If an event is generated by an SD
 124 - if the SD is attached to a master pointer, it changes the position and/or
 125   button state of the master pointer.
 126 - if the SD is attached to a master keyboard, it sends events to this
 127   keyboard's focus window (if applicable) and/or changes the modifier state of
 128   this keyboard.
 129 - if the SD is not attached to an MD ("floating"), it does not change
 130   any master device. The SD has its own (invisible) sprite and its own focus.
 131   Both the sprite and the focus must be managed explicitly by the client
 132   program.
 133
 134 4.3 Event processing for attached slave devices
 135
 136 Whenever an SD changes its logical state,
 137 - the event is delivered as an XI event to any interested clients. If the
 138   device is floating, event processing stops.
 139   Otherwise, if the device is attached,
 140 - the master device changes its classes to reflect the SD's capabilities. All
 141   interested clients are notified of this device change.
 142 - then, the event is delivered as an XI event from the MD to any interested
 143   clients. If the event has been delivered, event processing stops.
 144   Otherwise,
 145 - the event is delivered as a core event to any interested clients.
 146
 147 Given that W is the event window, and P the parent window of W, event delivery
 148 to P is only attempted if neither the XI event, nor the core event has been
 149 delivered on W. Once an event has been delivered as either XI or core event,
 150 event processing stops.
 151
 152 4.4. The ClientPointer principle
 153
 154 Many core protocol and some extension requests are ambiguous when multiple
 155 master devices are available (e.g. QueryPointer does not specfy which pointer).
 156 The X server does not have the knowledge to chose the contextually correct
 157 master device. For each client, one master pointer is designated as this
 158 clients's "ClientPointer". Whenever a client sends an ambiguous request (e.g.
 159 QueryPointer), the ClientPointer or the keyboard paired with the ClientPointer
 160 is chosen to provide the data for this request.
 161
 162 This ClientPointer may be explicitly assigned to a client with the
 163 SetClientPointer call. If no ClientPointer is set when a client issues an
 164 ambiguous request, the server choses one device as the ClientPointer. The
 165 method of chosing a ClientPointer from the available master pointers is
 166 implementation-specific.
 167
 168 If the master pointer currently set as ClientPointer for one or more clients is
 169 removed, the server may either unset the ClientPointer setting or change the
 170 ClientPointer to a different master pointer.
 171
 172                               ❧❧❧❧❧❧❧❧❧❧❧
 173 5. Data types
 174
 175 BUTTONMASK
 176         A binary mask defined as (1 << button number).
 177         A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK.
 178
 179 DEVICE { DEVICEID, AllDevices, AllMasterDevices }
 180         A DEVICE specifies either a DEVICEID or AllDevices or
 181         AllMasterDevices.
 182
 183 DEVICEID { CARD16 }
 184         A DEVICEID is a numerical ID for a device currently available in the
 185         server. The server may re-use a device ID after a device's removal.
 186         The device IDs 0 and 1 are reserved.
 187         AllDevices ........ 0
 188         AllMasterDevices .. 1
 189
 190 DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer,
 191             SlaveKeyboard, FloatingSlave }
 192         A DEVICEUSE field specifies the current use of a device in the MD/SD
 193         device hierarchy. See Section 4 for more information.
 194
 195 EVENTMASK
 196         An EVENTMASK is a binary mask defined as (1 << event type).
 197         A SETofEVENTMASK is a binary OR of zero or more EVENTMASK.
 198
 199 FP1616
 200         Fixed point decimal in 16.16 format as one INT16 and one CARD16.
 201         The INT16 contains the integral part, the CARD32 the decimal fraction
 202         shifted by 16.
 203
 204 FP3232
 205         Fixed point decimal in 32.32 format as one INT32 and one CARD32.
 206         The INT32 contains the integral part, the CARD32 the decimal fraction
 207         shifted by 32.
 208
 209 VALUATORMASK
 210         A binary mask defined as (1 << valuator number).
 211         A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK.
 212
 213                               ❧❧❧❧❧❧❧❧❧❧❧
 214 6. Errors
 215
 216 Errors are sent using core X error reports.
 217
 218 Device
 219         A value for a DEVICE argument does not specify a valid DEVICE.
 220
 221                               ❧❧❧❧❧❧❧❧❧❧❧
 222 7. Requests:
 223
 224 The server does not guarantee that the length of a reply remains constant in
 225 future revisions of XI2. A client must always retrieve the exact length of the
 226 protocol reply from the connection, even if the reply is longer than defined
 227 for the XI2 version supported by the client.
 228 Additional bytes in a request may include data supported in later versions of
 229 XI2. Clients should ignore this data. Padding bytes in XI2 protocol requests
 230 are required to be 0.
 231
 232 7.1 Requests introduced in version 2.0
 233
 234     ┌───
 235         XIQueryVersion
 236         major_version:          CARD16
 237         minor_version:          CARD16
 238         ▶
 239         major_version:          CARD16
 240         minor_version:          CARD16
 241     └───
 242
 243     The client sends the highest supported version to the server and the
 244     server sends the highest version it supports, but no higher than the
 245     requested version. Major versions changes can introduce incompatibilities
 246     in existing functionality, minor version changes introduce only backward
 247     compatible changes.  It is the client's responsibility to ensure that the
 248     server supports a version which is compatible with its expectations.
 249
 250     major_version
 251         Major XI2 version.
 252     minor_version
 253         Minor XI2 version.
 254
 255     If major_version is less than 2, a BadValue error occurs.
 256
 257     ┌───
 258         XIQueryDevice
 259         DEVICE                  deviceid
 260         ▶
 261         num_devices:            CARD16
 262         deviceinfo:             LISTofDEVICEINFO
 263     └───
 264
 265     DEVICEINFO { deviceid:              DEVICEID
 266                  use:                   DEVICEUSE
 267                  attachment:            DEVICEID
 268                  enabled:               BOOL
 269                  num_classes:           CARD16
 270                  name_len:              CARD16
 271                  name:                  LISTofCHAR8
 272                  classes:               LISTofCLASS }
 273
 274     CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS }
 275
 276     BUTTONCLASS { type:                 ButtonClass
 277                   length:               CARD16
 278                   sourceid:             CARD16
 279                   buttons_len:          CARD16
 280                   state:                SETofBUTTONMASK
 281                   labels:               LISTofATOM }
 282
 283     KEYCLASS    { type:                 KeyClass
 284                   length:               CARD16
 285                   sourceid:             CARD16
 286                   num_keys:             CARD16
 287                   keys:                 LISTofCARD32 }
 288
 289     AXISCLASS   { type:                 AxisClass
 290                   length:               CARD16
 291                   sourceid:             CARD16
 292                   axisnumber:           CARD16
 293                   label:                ATOM
 294                   min:                  FP3232
 295                   max:                  FP3232
 296                   value:                FP3232
 297                   resolution:           CARD32 }
 298
 299     XIQueryDevice details information about the requested input devices.
 300
 301     devices
 302         The device to list. If devices is AllDevices, all enabled and
 303         disabled devices are listed. If devices is AllMasterDevices, all
 304         enabled and disabled master devices are listed. If devices is a
 305         valid DEVICE, only this DEVICE is listed and num_devices is 1.
 306     num_devices
 307         The number of deviceinfos returned.
 308
 309     Each deviceinfo is detailed as follows:
 310     deviceid
 311         The unique ID of the device. Device IDs may get re-used when a device
 312         is removed.
 313     use
 314         If the device is a master pointer, use is MasterPointer.
 315         If the device is a master keyboard, use is MasterKeyboard.
 316         If the device is a slave pointer, use is SlavePointer.
 317         If the device is a slave keyboard, use is SlaveKeyboard.
 318         If the device is a floating slave, use is FloatingSlave.
 319     attachment
 320         If the device is a master pointer or a master keyboard, attachment
 321         specifies the paired master keyboard, or the paired master pointer,
 322         respectively.  If the device is a non-floating slave device
 323         attachment specifies the master device this device is attached to.
 324         If the device is a floating slave, attachment is undefined.
 325     enabled
 326         Zero if the device is disabled, non-zero otherwise.
 327     num_classes
 328         Number of classes provided.
 329     name_len
 330         Length of the name in bytes not including padding.
 331     classes
 332         Details the available classes provided by the device in an undefined
 333         order.
 334     name
 335         The device's name. padded to a multiple of 4 bytes.
 336
 337     For all classes, type specifies the device class. Clients are required
 338     to ignore unknown device classes. The length field specifies the length
 339     of the class in 4 byte units.
 340     The following classes may occur only once: ButtonClass, KeyClass
 341
 342     ButtonClass:
 343     type
 344         Always ButtonClass.
 345     length
 346         Length in 4 byte units.
 347     sourceid
 348         The device this class originates from.
 349     num_buttons
 350         Number of buttons provided by the device.
 351     labels
 352         List of Atoms specifying the label for each button. An Atom of None
 353         specifies an unlabeled button. Buttons are listed in the device-native
 354         order regardless of the current button mapping.
 355     state
 356         The current button mask for this device after button mapping is
 357         applied. Each bit representing a button is 1 if this button is
 358         logically down, or 0 otherwise. State is a multiple of 4-byte units
 359         and always contains at least num_buttons bits.
 360
 361     KeyClass:
 362     type
 363         Always KeyClass.
 364     length
 365         Length in 4 byte units.
 366     sourceid
 367         The device this class originates from.
 368     num_keys
 369         Number of keycodes provided by the device.
 370     keys
 371         List of keycodes provided.
 372
 373     AxisClass:
 374     type
 375         Always AxisClass.
 376     length
 377         Length in 4 byte units.
 378     sourceid
 379         The device this class originates from.
 380     axisnumber
 381         Axis number of this axis. The axis number is in device-native
 382         order and potential axis mappings are ignored.
 383     label
 384         Atom specifying the axis name. An Atom of None specifies an unlabeled
 385         axis.
 386     min
 387         Minimum value.
 388     max
 389         Minimum value.
 390     resolution
 391         Resolution in counts/meter.
 392     mode
 393         Relative or Absolute.
 394     value
 395         Last published axis value (if mode is absolute).
 396
 397     An axis in Relative mode may specify min and max as a hint to the
 398     client. If no min and max information is available, both must be 0.
 399
 400     ┌───
 401         XISelectEvents
 402             window:         Window
 403             num_masks:      CARD16
 404             masks:          LISTofEVENTMASK
 405
 406     └───
 407
 408     EVENTMASK { deviceid:          DEVICE,
 409                 mask_len:          CARD16,
 410                 mask:              SETofEVENTMASK
 411
 412     window
 413         The window to select the events on.
 414     num_masks
 415         Number of items in masks.
 416     deviceid
 417         Numerical deviceid, or AllDevices, or AllMasterDevices.
 418     mask_len
 419         Length of mask in 4 byte units.
 420     mask
 421         Event mask. An event mask for an event type T is defined as (1 << T).
 422
 423     XISelectEvents selects for XI2 events on window.
 424
 425     If num_masks is 0, a BadValue error occurs.
 426
 427     Each mask sets the (and overwrites a previous) event mask for the DEVICE
 428     specified through deviceid. The device AllDevices or
 429     AllMasterDevices is treated as a separate device by server. A client's
 430     event mask is the union of AllDevices, AllMasterDevices and the
 431     per-device event mask.
 432     The removal of device from the server unsets the event masks for the
 433     device. If an event mask is set for AllDevices or AllMasterDevices, the
 434     event mask is not cleared on device removal and affects all future
 435     devices.
 436
 437     If mask_len is 0, the event mask for the given device is cleared.
 438
 439     The mask for XIHierarchyEvents may only be selected for XIAllDevices.
 440     Setting it for any other device results in a BadValue error.
 441
 442     ┌───
 443         XIGetSelectedEvents
 444             window:         Window
 445             ▶
 446             num_masks:      CARD16
 447             masks:          LISTofEVENTMASK
 448     └───
 449
 450     window
 451         The window to select the events on.
 452     num_masks
 453         Number of items in masks.
 454     masks
 455         Selected event masks by this client.
 456
 457     Masks are returned on a per-device basis, with masks for AllDevices and
 458     AllMasterDevices returned separately. A client can calculate the
 459     effective mask for a device with a bitwise OR of the AllDevices, the
 460     AllMasterDevices and the device-specific mask.
 461
 462     If num_masks is 0, no events have been selected by this client on the
 463     given window.
 464
 465     ┌───
 466         XIQueryPointer
 467             window:         Window
 468             deviceid:       DEVICEID
 469             ▶
 470             root:           Window
 471             child:          Window
 472             root_x:         FP1616
 473             root_y:         FP1616
 474             win_x:          FP1616
 475             win_y:          FP1616
 476             same_screen:    BOOL
 477             mods:           MODIFIERINFO
 478             group:          GROUPINFO
 479             buttons_len:    CARD16
 480             buttons:        SETofBUTTONMASK
 481     └───
 482
 483     Query a master pointer device for its current position.
 484
 485     root
 486         The root window the pointer is logically on.
 487     child
 488         The child window of window that contains the pointer or None.
 489     root_x
 490     root_y
 491         Pointer position relative to the root window's origin.
 492     win_x
 493     win_y
 494         Pointer position relative to window or 0 if same_screen is false.
 495     same_screen
 496         True if window is on the same screen as the pointer.
 497     mods
 498         XKB modifier state on the paired device.
 499     group
 500         XKB group state on the paired device.
 501     buttons_len
 502         The length of buttons in 4 byte units.
 503     buttons
 504         Button state.
 505
 506     If the device is not a master pointer device or not a floating slave
 507     pointer, a BadDevice error results.
 508
 509     ┌───
 510         XIWarpPointer
 511             src_win:         Window
 512             dst_win:         Window
 513             src_x:           FP1616
 514             src_y:           FP1616
 515             src_width:       INT16
 516             src_height:      INT16
 517             dst_x:           FP1616
 518             dst_y:           FP1616
 519             deviceid:        DEVICEID
 520     └───
 521
 522     WarpPointer moves the pointer of deviceid as if the user had moved
 523     the pointer. WarpPointer can only be called for MasterPointer and
 524     FloatingSlave devices.
 525
 526     src_win
 527        If src_window is not None, the move only takes place if src_window
 528        contains the pointer and the pointer is contained in the specified
 529        rectangle of src_window.
 530     dst_win
 531        If dst_win is None, this request moves the pointer by offsets
 532        dst_x/dst_y relative to the current position of the pointer. If
 533         dst_window is a window, this request moves the pointer to
 534        dst_x/dst_y relative to dst_win's origin.
 535     src_x
 536     src_y
 537     src_width
 538     src_height
 539        Specifies the source window rectangle.
 540     dst_x
 541     dst_y
 542         The relative coordinates to move the pointer if dst_win is None, or
 543         the absolute coordinates if dst_win is a window.
 544     deviceid
 545         The device to warp.
 546
 547     This request cannot be used to move the pointer outside the confine-to
 548     window of an active pointer grab. An attempt will only move the pointer as
 549     far as the closest edge of the confine-to window.
 550
 551     This request will generate events just as if the user had instantaneously
 552     moved the pointer.
 553
 554     ┌───
 555         XIChangeCursor
 556             win:             Window
 557             cursor:          Cursor
 558             deviceid:        DEVICEID
 559     └───
 560
 561     Change a master pointer's cursor on the specified window.
 562
 563     window
 564         The window.
 565     cursor
 566         The new cursor or None.
 567     deviceid
 568         The master pointer device.
 569
 570     Whenever device enters a window W, the cursor shape is selected in the
 571     following order:
 572     - if the current window has a device cursor C(d) defined for device,
 573       display this cursor C(d).
 574     - otherwise, if the current window has a cursor C(w) defined in the core
 575       protocol's window attributes, display cursor C(w).
 576     - repeat on parent window until a cursor has been found.
 577
 578     The device cursor for a given window is reset once the window is destroyed
 579     or the device is removed, whichever comes earlier.
 580
 581     If deviceid does not specify a master pointer, a BadDevice error
 582     is returned.
 583
 584     ┌───
 585         XIChangeHierarchy
 586             num_changes:     CARD8
 587             changes:         LISTofHIERARCHYCHANGES
 588     └───
 589
 590     HIERARCHYCHANGE { ADDMASTER, REMOVEMASTER, ATTACHSLAVE, DETACHSLAVE }
 591
 592     HIERARCHYCHANGETYPE { AddMaster, RemoveMaster, AttachSlave, DetachSlave }
 593
 594     CHANGEMODE { Float, Attach }
 595
 596     ADDMASTER { type:        HIERARCHYCHANGETYPE
 597                 length:      CARD16
 598                 name_len:    CARD16
 599                 send_core:   BOOL
 600                 enable:      BOOL
 601                 name:        LISTofCHAR8 }
 602
 603     REMOVEMASTER { type:            HIERARCHYCHANGETYPE
 604                    length:          CARD16
 605                    deviceid:        DEVICEID
 606                    return_mode:     CHANGEMODE
 607                    return_pointer:  DEVICEID
 608                    return_keyboard: DEVICEID }
 609
 610     ATTACHSLAVE   { type:        HIERARCHYCHANGETYPE
 611                     length:      CARD16
 612                     deviceid:    DEVICEID
 613                     master:      DEVICEID }
 614
 615     DETACHSLAVE { type:       HIERARCHYCHANGETYPE
 616                   length:     CARD16
 617                   deviceid:   DEVICEID }
 618
 619     XIChangeHierarchy allows a client to modify the MD/SD device
 620     hierarchy (see Section 4).
 621
 622     num_changes
 623         The number of changes to apply to the current hierarchy.
 624     changes
 625         The list of changes.
 626
 627     The server processes the changes in the order received from the client and
 628     applies each requested change immediately. If an error occurs, processing
 629     stops at the current change and returns the number of successfully applied
 630     changes in the error.
 631
 632     ADDMASTER creates a pair of master devices.
 633     type
 634         Always AddMaster.
 635     length
 636         Length in 4 byte units.
 637     name_len
 638         Length of name in bytes.
 639     send_core
 640         True if the device should send core events.
 641     enable
 642         True if the device is to be enabled immediately.
 643     name
 644         The name for the new master devices. The master pointer's name is
 645         automatically appended with " pointer", the master keyboard's name is
 646         automatically appended with " keyboard".
 647
 648     REMOVEMASTER removes an existing master device.
 649     type
 650         Always RemoveMaster.
 651     length
 652         Length in 4 byte units.
 653     deviceid
 654         The device to remove.
 655     return_mode
 656         Return mode for attached slave devices.
 657         If return_mode is Float, all slave devices are set to floating.
 658         If return_mode is Attach, slave pointers are attached to
 659         return_pointer and slave keyboards are attached to
 660         return_keyboard.
 661     return_pointer
 662     return_keyboard
 663         The master pointer and master keyboard to attach slave devices to, if
 664         return_mode is Attach. If return_mode is Float, return_pointer
 665         and return_keyboard are undefined.
 666
 667     Removing a master pointer removes the paired master keyboard and vice
 668     versa.
 669
 670     ATTACHSLAVE attaches a slave device to a given master device.
 671     type
 672         Always ChangeAttachment.
 673     length
 674         Length in 4 byte units.
 675     deviceid
 676         Deviceid of the slave device.
 677     master
 678         The new master device to attach this slave device to.
 679
 680     DETACHSLAVE detaches a slave device from its current master device.
 681     type
 682         Always ChangeAttachment.
 683     length
 684         Length in 4 byte units.
 685     deviceid
 686         Deviceid of the slave device.
 687
 688     ┌───
 689         XISetClientPointer
 690             win:             Window
 691             deviceid:        DEVICEID
 692     └───
 693
 694     Set the ClientPointer for the client owning win to the given device.
 695
 696     win
 697          Window or client ID.
 698     deviceid
 699          The master pointer or master keyboard that acts as ClientPointer.
 700
 701     Some protocol requests are ambiguous and the server has to choose a device
 702     to provide data for a request or a reply. By default, the server will
 703     choose a client's ClientPointer device to provide the data, unless the
 704     client currently has a grab on another device. See section 4.4 for more
 705     details.
 706
 707     If win is None, the ClientPointer for this client is set to the given
 708     device. Otherwise, if win is a valid window, the ClientPointer for the
 709     client owning this window is set to the given device. Otherwise, if win is
 710     not a valid window but a client with the client mask equal to win exists,
 711     this client's ClientPointer is set to the given device.
 712
 713     If deviceid does not specify a master pointer or master keyboard, a
 714     BadDevice error is returned.
 715
 716     If window does not specify a valid window or client ID and is not None, a
 717     BadWindow error is returned.
 718
 719     ┌───
 720         XIGetClientPointer
 721             win:             Window
 722             ▶
 723             set:             BOOL
 724             deviceid:        DEVICEID
 725     └───
 726
 727     Query the ClientPointer for the client owning win.
 728
 729     win
 730         The window or client ID.
 731     set
 732         True if the client has a ClientPointer set.
 733     deviceid
 734         The master pointer that acts as a ClientPointer if set is True.
 735
 736     No difference is made between a ClientPointer set explicitly through
 737     XISetClientPointer and a ClientPointer implicitly assigned by the server
 738     in response to an ambiguous request.
 739
 740     ┌───
 741         XISetFocus
 742             focus:           Window
 743             deviceid:        DEVICEID
 744             time:            Time
 745     └───
 746
 747     Set the focus for the given device to the given window. Future key events
 748     from this device are sent to this window.
 749     This request generates FocusIn and FocusOut events.
 750
 751     focus
 752         A viewable window or None.
 753     deviceid
 754         The device to modify the focus window for.
 755     time
 756         Specifies the time to change the focus or CurrentTime.
 757
 758     If focus is None, key events from this device are discarded until a new
 759     focus window is set. If focus is a viewable window, key events from this
 760     device are sent to this window. If the window becomes unviewable, the
 761     window's first viewable ancestor automatically becomes the focus window
 762     and FocusIn and FocusOut events are sent as if a client had changed the
 763     focus window.
 764     This is equivalent to RevertToParent in the core XSetInputFocus window.
 765
 766     This request has no effect if the specified time is earlier than the
 767     current last-focus-change time or is later than the current X server time.
 768     Otherwise, the last-focus-change time is set to the specified time.
 769
 770     ┌───
 771         XIGetFocus
 772             deviceid:        DEVICEID
 773             ▶
 774             focus:           Window
 775     └───
 776
 777     Return the current focus window for the given device.
 778
 779     ┌───
 780         XIGrabDevice
 781             deviceid:        DEVICEID
 782             grab_window:     Window
 783             owner_events:    BOOL
 784             grab_mode:       { Synchronous, Asynchronous }
 785             paired_device_mode: { Synchronous, Asynchronous }
 786             time:            TIMESTAMP or CurrentTime
 787             cursor:          Cursor
 788             mask_len:        CARD16
 789             masks:           SETofEVENTMASK
 790             ▶
 791             status:          Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable
 792     └───
 793
 794     This request actively grabs control of the specified input device. Further
 795     input events from this device are reported only to the grabbing client.
 796     This request overides any previous active grab by this client for this
 797     device.
 798
 799     deviceid
 800         The device to grab.
 801     grab_window
 802         Events are reported relative to the grab window.
 803     owner_events
 804         Specifies whether event will be reported normally or relative to the
 805         grab window.
 806     grab_mode
 807         Specifies if this device will be frozen as a result of the grab.
 808     paired_device_mode
 809         Specifies if the master device paired with this device will be frozen
 810         as a result of the grab.
 811     time
 812         A valid server time or CurrentTime.
 813     cursor
 814         The cursor to display for the duration of the grab or None.
 815     mask_len
 816         Length of mask in 4 byte units.
 817     mask
 818         Event mask. An event mask for an event type T is defined as (1 << T).
 819     status
 820         Success or the reason why the grab could not be established.
 821
 822     The masks parameter specifies which events the client wishes to receive
 823     while the device is grabbed.
 824
 825     If owner-events is False, input events generated from this device are
 826     reported with respect to grab-window, and are only reported if selected by
 827     being included in the event-list.  If owner-events is True, then if a
 828     generated event would normally be reported to this client, it is reported
 829     normally, otherwise the event is reported with respect to the grab-window,
 830     and is only reported if selected by being included in the event-list. For
 831     either value of owner-events, unreported events are discarded.
 832
 833     If grab-mode is Asynchronous, device event processing continues normally.
 834     If the device is currently frozen by this client, then processing of
 835     device events is resumed. If grab-mode is Synchronous, the state of the
 836     grabbed device (as seen by means of the protocol) appears to freeze,
 837     and no further device events are generated by the server until the
 838     grabbing client issues a releasing XIAllowEvents request or until the
 839     device grab is released. Actual device input events are not lost while the
 840     device is frozen; they are simply queued for later processing.
 841
 842     If the device is a slave device, the paired-device-mode is ignored.
 843     Otherwise, if this device is a master device and paired-device-mode is
 844     Asynchronous, event processing is unaffected by activation of the grab. If
 845     this device is a master device and paired-device-mode is Synchronous, the
 846     state of the master device paired with this device (as seen by means of the
 847     protocol) appears to freeze, and no further events are generated by the
 848     server until the grabbing client issues a releasing XIAllowEvents request
 849     or until the device grab is released. Actual events are not lost while the
 850     devices are frozen; they are simply queued for later processing.
 851
 852     If the cursor is not None and the device is a master pointer device, the
 853     cursor will be displayed until the device is ungrabbed.
 854
 855     This request fails and returns:
 856     AlreadyGrabbed: If the device is actively grabbed by some other client.
 857     NotViewable: If grab-window is not viewable.
 858     InvalidTime: If the specified time is earlier than the last-grab-time for
 859                  the specified device or later than the current X server time.
 860                  Otherwise, the last-grab-time for the specified device is set
 861                  to the specified time and CurrentTime is replaced by the
 862                  current X server time.
 863     Frozen: If the device is frozen by an active grab of another client.
 864
 865     To release a grab of a device, use XIUngrabDevice.
 866
 867     ┌───
 868         XIUngrabDevice
 869             deviceid:        DEVICEID
 870             time:            TIMESTAMP or CurrentTime
 871     └───
 872
 873     This request releases the device if this client has it actively grabbed
 874     (from either XIGrabDevice or  XIPassiveGrabDevice) and
 875     releases any queued events. If any devices were frozen by the grab,
 876     XIUngrabDevice thaws them.
 877
 878     deviceid
 879         The device to grab.
 880     time
 881         A valid server time or CurrentTime.
 882
 883     The request has no effect if the specified time is earlier than the
 884     last-device-grab time or is later than the current server time.
 885     This request generates FocusIn and FocusOut events.
 886     An XIUngrabDevice is performed automatically if the event window for an
 887     active device grab becomes not viewable.
 888
 889     ┌───
 890         XIAllowEvents:
 891             deviceid:        DEVICEID
 892             time:            TIMESTAMP or CurrentTime
 893             event_mode:      { AsyncDevice, SyncDevice,
 894                                AsyncPairedDevice, SyncPairedDevice,
 895                                ReplayDevice, AsyncPair, SyncPair }
 896     └───
 897
 898     The XIAllowEvents request releases some queued events if the client
 899     has caused a device to freeze.
 900
 901     deviceid
 902         The device to grab.
 903     time
 904         A valid server time or CurrentTime.
 905     event_mode
 906         Specifies whether a device is to be thawed and events are to be
 907         replayed.
 908
 909     The request has no effect if the specified time is earlier than the
 910     last-grab time of the most recent active grab for the client, or if the
 911     specified time is later than the current X server time.
 912
 913     The following describes the processing that occurs depending on what constant
 914     you pass to the event-mode argument:
 915     AsyncDevice:
 916         If the specified device is frozen by the client, event processing for that
 917         device continues as usual. If the device is frozen multiple times  by the
 918         client on behalf of multiple separate grabs, AsyncDevice thaws for
 919         all.
 920         AsyncDevice has no effect if the specified device is not frozen by the
 921         client, but the device need not be grabbed by the client.
 922     SyncDevice:
 923         If the specified device is frozen and actively grabbed by the client,
 924         event processing for that device continues normally until the next
 925         event is reported to the client. At this time, the specified device
 926         again appears to freeze. However, if the reported event causes the
 927         grab to be released, the specified device does not freeze.
 928         SyncDevice has no effect if the specified device is not frozen by the
 929         client or is not grabbed by the client.
 930      ReplayDevice:
 931         If the specified device is actively grabbed by the client and is frozen
 932         as the result of an event having been sent to the client (either from
 933         the activation of a XIGrabButton or from a previous XIAllowEvents with
 934         mode SyncDevice, but not from a Grab), the grab is released and
 935         that event is completely reprocessed.  This time, however, the request
 936         ignores any passive grabs at or above (towards the root) the
 937         grab-window of the grab just released.
 938         The request has no effect if the specified device is not grabbed by
 939         the client or if it is not frozen as the result of an event.
 940      AsyncPairedDevice
 941         If the paired master device is frozen by the client, event processing
 942         for it continues as usual. If the paired device is frozen multiple
 943         times by the client on behalf of multiple separate grabs,
 944         AsyncPairedDevice thaws for all.
 945         AsyncPairedDevice has no effect if the device is not frozen by the
 946         client, but those devices need not be grabbed by the client.
 947         AsyncPairedDevice has no effect if deviceid specifies a slave device.
 948      SyncPairedDevice
 949         If the paired master device is frozen by the client, event processing (for
 950         the paired master device) continues normally until the next button or key
 951         event is reported to the client for the grabbed device (button event for
 952         the grabbed device, key or motion event for the device), at which time
 953         the device again appears to freeze. However, if the reported event causes
 954         the grab to be released, then the device does not freeze.
 955         SyncPairedDevice has no effect if the specified device is not grabbed
 956         by the client or if it is no frozen as the result of an event.
 957         SyncPairedDevice has no effect if deviceid specifies a slave device.
 958      SyncPair
 959         If both the device and the paired master device are frozen by the
 960         client, event processing (for both devices) continues normally until
 961         the next XIButtonPress, XIButtonRelease, XIKeyPress, or XIKeyRelease
 962         event is reported to the client for a grabbed device (button event for
 963         a pointer, key event for a keyboard), at which time the devices again
 964         appear to freeze. However, if the reported event causes the grab to be
 965         released, then the devices do not freeze (but if the other device is
 966         still grabbed, then a subsequent event for it will still cause both
 967         devices to freeze).
 968         SyncPair has no effect unless both the device and the paired master
 969         device are frozen by the client. If the device or paired master device
 970         is frozen twice by the client on behalf of two separate grabs,
 971         SyncPair thaws for both (but a subsequent freeze for SyncPair will
 972         only freeze each device once).
 973         SyncPair has no effect if deviceid specifies a slave device.
 974      AsyncPair
 975         If the device and the paired master device are frozen by the client,
 976         event processing for both devices continues normally. If a device is
 977         frozen twice by the client on behalf of two separate grabs, AsyncBoth
 978         thaws for both. AsyncPair has no effect unless both the device and the
 979         paired master device frozen by the client.
 980         AsyncPair has no effect if deviceid specifies a slave device.
 981
 982     ┌───
 983         XIPassiveGrabDevice
 984             deviceid:        DEVICE
 985             detail:          CARD32
 986             grab_type:       GRABTYPE
 987             grab_window:     Window
 988             cursor:          Cursor
 989             owner_events:    Bool
 990             grab_mode:       { Synchronous, Asynchronous }
 991             paired_device_mode: { Synchronous, Asynchronous }
 992             num_modifiers:   INT16
 993             mask_len:        CARD16
 994             masks:           SETofEVENTMASK
 995             modifiers:       CARD32 or GrabAnyModifier
 996             ▶
 997             num_modifiers_return:    INT16
 998             modifiers_return:        GRABMODIFIERINFO
 999     └───
1000
1001         GRABTYPE         { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
1002                            GrabtypeFocusIn}
1003
1004         GRABMODIFIERINFO {   status:    Access
1005                              modifiers: CARD32 }
1006
1007         Establish an explicit passive grab for a button or keycode
1008         on the specified input device.
1009
1010         cursor
1011             The cursor to display for the duration of the grab. If grab_type
1012             is not GrabtypeButton, this argument is ignored.
1013         deviceid
1014             The device to establish the passive grab on or AllDevices or
1015             AllMasterDevices.
1016         detail
1017             The button number, or key symbol to grab for.
1018             Must be 0 for GrabtypeEnter and GrabtypeFocusIn.
1019         grab_type
1020             The type of grab to establish.
1021         grab_window
1022             Events are reported relative to the grab window.
1023         grab_mode
1024             If grab-mode is Asynchronous, device event processing continues
1025             normally.  If the device is currently frozen by this client, then
1026             processing of device events is resumed. If grab-mode is
1027             Synchronous, the state of the grabbed device (as seen by means of
1028             the protocol) appears to freeze, and no further device events are
1029             generated by the server until the grabbing client issues a
1030             releasing XIAllowEvents request or until the device grab is
1031             released. Actual device input events are not lost while the device
1032             is frozen; they are simply queued for later processing.
1033         mask_len
1034             Length of mask in 4 byte units.
1035         mask
1036             Event mask. An event mask for an event type T is defined as (1 << T).
1037         modifiers
1038             XKB modifier state to activate this passive grab.
1039         num_modifiers
1040             Number of elements in modifiers.
1041         owner_events
1042             Specifies whether event will be reported normally or relative to the
1043             grab window.
1044         num_modifiers_return
1045             Number of elements in modifiers_return
1046         modifiers_return
1047             XKB modifier state that could not be grabbed.
1048
1049         If owner-events is False, input events generated from this device are
1050         reported with respect to grab-window, and are only reported if
1051         selected by being included in the event-list.  If owner-events is
1052         True, then if a generated event would normally be reported to this
1053         client, it is reported normally, otherwise the event is reported
1054         with respect to the grab-window, and is only reported if selected
1055         by being included in the event-list. For either value of
1056         owner-events, unreported events are discarded.
1057
1058         If deviceid specifies a master pointer, the modifiers of the paired
1059         master keyboard are used. If deviceid specifies a slave pointer
1060         the modifiers of the master keyboard paired with the attached master
1061         pointers are used. If deviceid specifies a slave keyboard, the
1062         modifiers of the attached master keyboard are used. Note that
1063         activating a grab on a slave device detaches the device from its
1064         master. In this case, the modifiers after activation of the grab are
1065         from the slave device only and may be different to the modifier state
1066         when the grab was triggered.
1067
1068         In the future, if grab_type is GrabtypeButton or GrabtypeKeyboard, the
1069         device is actively grabbed if:
1070         - the device is not grabbed, and
1071         - the specified modifier keys are down, and
1072         - the grab_type is GrabtypeButton and the button specified in detail
1073           is logically pressed or the grab_type is GrabtypeKeycode and the
1074           keycode specified in detail is logically pressed, and
1075         - the grab_window contains the pointer, and
1076         - a passive grab on the same button/keycode + modifier
1077           combination does not exist on an ancestor of grab_window.
1078
1079         Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the
1080         device is actively grabbed if:
1081         - the device is not actively grabbed, and
1082         - the specified modifier keys are down, and
1083         - the grab_type is GrabtypeEnter and the device's pointer has moved
1084           into grab_window or a descendant of grab_window, or the grab_type is
1085           GrabtypeFocusIn and the device's focus has been set to the
1086           grab_window or a descendant of grab_window,
1087         - a passive grab of the same grab_type + modifier combination does not
1088           does not exist on an ancestor of grab_window.
1089
1090         A modifier of GrabAnyModifier is equivalent to issuing the request for
1091         all possible modifier combinations (including no modifiers). A client
1092         may request a grab for GrabAnyModifier and explicit modifier
1093         combinations in the same request.
1094
1095         A GrabtypeButton or GrabtypeKeyboard grab is released when all buttons
1096         or keycode are released, independent of the state of modifier keys.
1097         A GrabtypeEnter or GrabtypeFocusIn grab is released when the
1098         pointer or focus leaves the window and all of its descendants,
1099         independent of the state of modifier keys.
1100         Note that the logical state of a device (as seen by means of the
1101         protocol) may lag the physical state if device event processing is
1102         frozen.
1103
1104         This request overrides all previous passive grabs by the same
1105         client on the same button/key/enter/focus in + modifier combinations
1106         on the same window.
1107
1108         If some other client already has issued a XIPassiveGrabDevice request
1109         with the same button or keycode and modifier combination, the
1110         failed modifier combinations is returned in modifiers_return. If some
1111         other client already has issued an XIPassiveGrabDevice request of
1112         grab_type  XIGrabtypeEnter or XIGrabtypeFocusIn with the same
1113         grab_window and the same modifier combination, the failed modifier
1114         combinations are returned in modifiers_return. If num_modifiers_return
1115         is zero, all passive grabs have been successful.
1116
1117         If a button grab or enter grab activates, EnterNotify and LeaveNotify
1118         events with mode Grab are generated as if the pointer were to suddenly
1119         warp from its current position some position in the grab_window.
1120         However, the pointer does not warp, and the pointer position is used
1121         as both the initial and final positions for the events.
1122
1123         If a keycode grab or focus grab activates, FocusIn and FocusOut events
1124         with mode Grab are generated as if the focus were to change from the
1125         current window to the grab_window.
1126
1127         If an enter or focus in grab activates, additional EnterNotify events
1128         with mode XIPassiveGrabNotify are generated as if the pointer or focus
1129         were to suddenly warp from its current position to some position in
1130         the grab window.  These events are sent to the grabbing client only
1131         and only if the grab event mask has selected for it. If such a passive
1132         grab deactivates, addional LeaveNotify events with mode
1133         XIPassiveUngrabNotify are generated and sent to the grabbing client
1134         before the grab deactivates.
1135
1136     ┌───
1137         XIPassiveUngrabDevice
1138             deviceid:        DEVICEID
1139             detail:          CARD32
1140             grab_type:       GRABTYPE
1141             grab_window:     Window
1142             num_modifiers:   INT16
1143             modifiers:       MODIFIERINFO
1144     └───
1145
1146         Release an explicit passive grab on the specified input device.
1147
1148         deviceid
1149             The device to establish the passive grab on.
1150         detail
1151             The button number or key symbol to ungrab.
1152             Must be 0 for GrabtypeEnter and GrabtypeFocusIn.
1153         grab_type
1154             The type of grab to establish.
1155         grab_window
1156             Events are reported relative to the grab window.
1157         modifiers
1158             XKB modifier state to activate this passive grab.
1159         num_modifiers
1160             Number of elements in modifiers.
1161
1162         This request has no effect if the client does not have a passive grab
1163         of the same type, same button or keycode (if applicable) and modifier
1164         combination on the grab_window.
1165
1166     ┌───
1167         XIListProperties
1168             deviceid:        DEVICEID
1169             ▶
1170             num_properties:  INT16
1171             properties:      LISTofATOM
1172     └───
1173
1174         List the properties associated with the given device.
1175
1176         deviceid
1177             The device to list the properties for.
1178         num_atoms
1179             Number of atoms in the reply
1180         atoms
1181             All properties on the device.
1182
1183     ┌───
1184         XIChangeProperty
1185             deviceid:        DEVICEID
1186             property:        ATOM
1187             type:            ATOM
1188             format:          { 8, 16, 32 }
1189             mode:            { Append, Prepend, Replace }
1190             num_items:       CARD32
1191             data:            LISTofINT8, or LISTofINT16, or LISTofINT32
1192     └───
1193
1194         Change the given property on the given device.
1195
1196         deviceid
1197             The device to change the property on.
1198         property
1199             The property to modify.
1200         type
1201             The property's type.
1202         mode
1203             One of Append, Prepend, or Replace
1204         num_items
1205             Number of items following this request.
1206         data
1207             Property data (nitems * format/8 bytes)
1208
1209         The type is uninterpreted by the server. The format specifies whether
1210         the data should be viewed as a list of 8-bit, 16-bit, or 32-bit
1211         quantities so that the server can correctly byte-swap as necessary.
1212
1213         If the mode is Replace, the previous propert y value is discarded.  If
1214         the mode is Prepend or Append, then the type and format must match the
1215         existing property value (or a Match error results). If the property is
1216         undefined, it is treated as defined with the correct type and format
1217         with zero-length data. For Prepend, the data is tacked on to the
1218         beginning of the existing data, and for Append, it is tacked on to the
1219         end of the existing data.
1220
1221         The lifetime of a property is not tied to the storing client. Properties
1222         remain until explicitly deleted, until the device is removed, or
1223         until server reset.
1224
1225         A property cannot be deleted by setting nitems to zero. To delete a
1226         property, use XIDeleteProperty.
1227
1228         This request generates an XIPropertyEvent.
1229
1230     ┌───
1231         XIDeleteProperty
1232             deviceid:        DEVICEID
1233             property:        ATOM
1234     └───
1235
1236         Deletes the given property on the given device.
1237
1238         deviceid
1239             The device to delete the property on.
1240         property
1241             The property to delete.
1242
1243         If the property is deleted, an XIPropertyEvent is generated on the device.
1244         If the property does not exist, this request does nothing.
1245
1246     ┌───
1247         XIGetProperty
1248             deviceid:        DEVICEID
1249             property:        ATOM
1250             type:            Atom or AnyPropertyType
1251             offset:          CARD32
1252             len:             CARD32
1253             delete:          BOOL
1254             ▶
1255             type:            Atom
1256             bytes_after:     CARD32
1257             num_items:       CARD32
1258             format:          { 8, 16, 32 }
1259             data:            LISTofINT8, or LISTofINT16, or LISTofINT32
1260     └───
1261
1262         Get the data for the given property on the given device.
1263
1264         deviceid
1265             The device to retrieve the property data from.
1266         property
1267             The property to retrieve the data from..
1268         type
1269             The property type to retrieve or AnyPropertyType
1270         offset
1271             The offset in 4-byte units.
1272         len
1273             Number of bytes to receive in 4-byte units.
1274         delete
1275             Delete the property after retrieving the data.
1276         bytes_after
1277             Number of unread bytes in the stored property
1278         num_items
1279             Number of items in data
1280         format
1281             8, 16, or 32
1282         data
1283             Property data (nitems * format/8 bytes)
1284
1285         If the specified property does not exist for the specified device, then
1286         the return type is None, the format and bytes-after are zero, and the value is
1287         empty. The delete argument is ignored in this case. If the specified property
1288         exists but its type does not match the specified type, then the return
1289         type is the actual type of the property, the format is the actual format of the
1290         property (never zero), the bytes-after is the length of the property in bytes
1291         (even if the format is 16 or 32), and the value is empty. The delete
1292         argument is ignored in this case. If the specified property exists and
1293         either AnyPropertyType is specified or the specified type matches the actual
1294         type of the property, then the return type is the actual type of the property,
1295         the format is the actual format of the property
1296         (never zero), and the bytes-after and value are as follows, given:
1297                  N = actual length of the stored property in bytes
1298                     (even if the format is 16 or 32)
1299                  I = 4 * long-offset
1300                  T = N−I
1301                  L = MINIMUM(T, 4 * long-length)
1302                  A = N − (I + L)
1303         The returned value starts at byte index I in the property (indexing
1304         from 0), and its length in bytes is L. However, it is a Value error if
1305         offset is given such that L is negative. The value of bytes_after is A,
1306         giving the number of trailing unread bytes in the stored property. If
1307         delete is True and the bytes_after is zero, the property is also
1308         deleted from the device, and a XIPropertyNotify event is generated on
1309         the device.
1310
1311
1312 8. Events:
1313
1314 An event specifies its length in 4-byte units after the initial 32 bytes.
1315 Future versions of the protocol may provide additional information
1316 in the same event, thus increasing the event size. Clients are required to
1317 always read the number of bytes specified by the event, not the size of the
1318 event they may have been compiled against.
1319
1320
1321 The following event types are available in XI2.
1322
1323 Version 2.0:
1324         HierarchyChanged
1325         DeviceChanged
1326         KeyPress
1327         KeyRelease
1328         ButtonPress
1329         ButtonRelease
1330         Motion
1331         RawKeyPress
1332         RawKeyRelease
1333         RawButtonPress
1334         RawButtonRelease
1335         RawMotion
1336         Enter
1337         Leave
1338         FocusIn
1339         FocusOut
1340         PropertyEvent
1341
1342 All events have a set of common fields specified as EVENTHEADER.
1343
1344
1345 EVENTHEADER { type:                       BYTE
1346               extension:                  BYTE
1347               sequenceNumber:             CARD16
1348               length:                     CARD32
1349               evtype:                     CARD16
1350               deviceid:                   DEVICEID
1351               time:                       Time }
1352
1353     type
1354         Always GenericEvent.
1355     extension
1356         Always the X Input extension offset.
1357     sequenceNumber
1358         Sequence number of last request processed by the server.
1359     length
1360         Length in 4-byte units after the initial 32 bytes.
1361     evtype
1362         XI-specific event type.
1363     deviceid
1364         Numerical device id for a device.
1365     time
1366         Time in ms.
1367
1368
1369     ┌───
1370         HierarchyEvent:
1371             EVENTHEADER
1372             flags:                      SETofHIERARCHYMASK
1373             num_info:                   CARD16
1374             info:                       LISTofHIERARCHYINFO
1375     └───
1376
1377
1378     HIERARCHYMASK { MasterAdded, MasterRemoved, SlaveAttached, SlaveDetached,
1379                     SlaveAdded, SlaveRemoved, DeviceEnabled, DeviceDisabled }
1380
1381     HIERARCHYINFO { deviceid:           DEVICEID,
1382                     attachment:         DEVICEID,
1383                     type:               DEVICEUSE
1384                     enabled:            BOOL
1385                     flags:              SETofHIERARCHYMASK}
1386
1387     flags
1388         Set of the changes that have occured, causing this event.
1389     num_info
1390         The number of device info structs following the request.
1391     info:
1392         The current hierarchy information.
1393
1394     An XIHierarchyEvent is sent whenever the device hierarchy been
1395     changed. The flags specify all types of hierarchy modifiations that have
1396     occured.
1397     For all devices, info details the hierarchy information after the
1398     modification of the hierarchy has occured. For each device specified with
1399     deviceid:
1400     - if type is MasterPointer or MasterKeyboard, attachment decribes the
1401       pairing of this device.
1402     - if type is SlavePointer or SlaveKeyboard, attachment describes the
1403       master device this device is attached to.
1404     - if type is FloatingSlave device, attachment is undefined.
1405
1406     enabled
1407          True if the device is enabled and can send events. A disabled master
1408          device will not forward events from an attached, enabled slave
1409          device.
1410
1411     Note: Multiple devices may be affected in one hierarchy change,
1412     deviceid in an XIHierarchyEvent is always the first affected
1413     device. Clients should ignore deviceid and instead use the devices list.
1414
1415     ┌───
1416         DeviceChangedEvent:
1417             EVENTHEADER
1418             reason:                CHANGEREASON
1419             source:                DEVICEID
1420             num_classes:           CARD16
1421             classes:               LISTofCLASS
1422     └───
1423
1424     CHANGEREASON { SlaveSwitch, DeviceChange }
1425
1426     A DeviceChangeEvent is sent whenever a device changes it's capabilities.
1427     This can happen either by a new slave device sending events through a
1428     master device, or by a physical device changing capabilities at runtime.
1429
1430     reason
1431         The reason for generating this event.
1432         If reason is SlaveSwitch, the slave device sending events through
1433         this device has changed and source specifies the new slave device.
1434         A SlaveSwitch reason can only occur on a master device.
1435         If reason is DeviceChange, the device itself has changed through
1436         other means (e.g. a physical device change) and source is
1437         the device itself.
1438     source
1439         The source of the new classes.
1440     num_classes
1441         Number of classes provided.
1442     classes
1443         Details the available classes provided by the device.  The order the
1444         classes are provided in is undefined.
1445
1446     For a detailed description of classes, see the XQueryDevice request.
1447
1448     ┌───
1449         DeviceEvent:
1450             EVENTHEADER
1451             detail:                     CARD32
1452             root:                       Window
1453             event:                      Window
1454             child:                      Window
1455             root_x:                     FP1616
1456             root_y:                     FP1616
1457             event_x:                    FP1616
1458             event_y:                    FP1616
1459             buttons_len:                CARD16
1460             valuators_len:              CARD16
1461             sourceid:                   DEVICEID
1462             mods:                       MODIFIERINFO
1463             group:                      GROUPINFO
1464             flags:                      DEVICEEEVENTFLAGS
1465             buttons:                    SETofBUTTONMASK
1466             valuators:                  SETofVALUATORMASK
1467             axisvalues:                 LISTofFP3232
1468     └───
1469
1470     BUTTONBIT { (1 << Button1), (1 << Button2), ... , (1 << ButtonN) }
1471     VALUATORBIT { (1 << 1), ( 1 << 2), ... ( 1 << n) }
1472
1473     MODIFIERINFO  { base_mods:           CARD32,
1474                     latched_mods:        CARD32,
1475                     locked_mods:         CARD32,
1476                     effective_mods:      CARD32}
1477     GROUPINFO     { base_group:          CARD8,
1478                     latched_group:       CARD8,
1479                     locked_group:        CARD8,
1480                     effective_group:     CARD8}
1481
1482     DEVICEEVENTFLAGS (all events): none
1483     DEVICEEVENTFLAGS (key events only): { KeyRepeat }
1484     DEVICEEVENTFLAGS (pointer events only): none
1485
1486     An XIDeviceEvent is generated whenever the logical state of a device
1487     changes in response to a button press, a button release, a motion, a key
1488     press or a key release. The event type may be one of KeyPress,
1489     KeyRelease, ButtonPress, ButtonRelease, Motion.
1490
1491     detail
1492         The button number or key code, or 0.
1493     root
1494     event
1495     child
1496         The root window, event window or subwindow, respectively. See core
1497         protocol specification for more detail.
1498     root_x
1499     root_y
1500         The position of the pointer in screen coordinates (16.16 fixed point).
1501     event_x
1502     event_y
1503         The position of the pointer in screen coordinates relative to the
1504         event window (16.16 fixed point).
1505
1506     buttons_len
1507         The length of buttons in 4 byte units.
1508     valuators_len
1509         The length of valuators in 4 byte units.
1510     sourceid
1511         The source device that originally generated the event.
1512     mods
1513         XKB modifier state before the event occured.
1514     group
1515         XKB group state before the event.
1516     buttons
1517         Button state before the event.
1518     valuators
1519         Bitmask of valuators provided in axisvalues.
1520     axisvalues
1521         Valuator data in device-native resolution.
1522     flags
1523         Miscellaneous information about this event; the union of the
1524         common flag set and either the key or pointer flag set,
1525         depending on the event type.
1526         KeyRepeat means that this event is for repeating purposes, and
1527         the physical state of the key has not changed.  This is only
1528         valid for KeyPress events.
1529
1530     Modifier state in mods is detailed as follows:
1531     base_mods
1532         XKB base modifier state.
1533     latched_mods
1534         XKB latched modifier state.
1535     locked_mods
1536         XKB locked modifier state.
1537
1538     Group state in group is detailed as follows:
1539     base_group
1540         XKB base group state.
1541     latched_group
1542         XKB latched group state.
1543     locked_group
1544         XKB locked group state.
1545
1546     ┌───
1547         RawEvent
1548             EVENTHEADER
1549             detail:                    CARD32
1550             flags:                     DEVICEEVENTFLAGS
1551             valuators_len:             CARD16
1552             valuators:                 SETofVALUATORMASK
1553             axisvalues:                LISTofFP3232
1554             axisvalues_raw:            LISTofFP3232
1555     └───
1556
1557     A RawEvent provides the information provided by the driver to the
1558     client. RawEvent provides both the raw data as supplied by the driver and
1559     transformed data as used in the server. Transformations include, but are
1560     not limited to, axis clipping and acceleration.
1561     Transformed valuator data may be equivalent to raw data. In this case,
1562     both raw and transformed valuator data is provided.
1563     RawEvents are sent exclusively to all root windows or to the client
1564     that grabbed the device only.
1565
1566     eventtype
1567         The type of event that occured on the device.
1568     detail
1569         The button number or keycode.
1570     flags
1571         Flags as described in DeviceEvent.
1572     valuators_len
1573         The length of valuators in 4 byte units.
1574     valuators
1575         Bitmask of valuators provided in axisvalues and axisvalues_raw.
1576     axisvalues
1577         Valuator data in device-native resolution.
1578     axisvalues_raw
1579         Untransformed valuator data in device-native resolution.
1580
1581     ┌───
1582         Enter or Leave or FocusIn or FocusOut
1583             EVENTHEADER
1584             root:               Window
1585             event:              Window
1586             child:              Window
1587             sourceid:           DEVICEID
1588             root_x:             FP1616
1589             root_y:             FP1616
1590             event_x             FP1616
1591             event_y:            FP1616
1592             mode:               NOTIFYMODE
1593             detail:             NOTIFYDETAIL
1594             same_screen:        BOOL
1595             focus:              BOOL
1596             mods:               MODIFIERINFO
1597             group:              GROUPINFO
1598             buttons_len:        CARD16
1599             buttons:            SETofBUTTONMASK
1600     └───
1601
1602     NOTIFYMODE { Normal, Grab, Ungrab }
1603     NOTIFYDETAIL { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual,
1604                    Pointer, PointerRoot, None }
1605
1606     Enter or Leave events are sent whenever a device's pointer enters or
1607     leaves a window.
1608     FocusIn or FocusOut events are sent whenever a device's focus is set to or
1609     away from a window.
1610     The enter/leave and focus in/out model is described in the core protocol
1611     specification, Section 11. (EnterNotify, LeaveNotify events).
1612
1613     For enter and leave events, the modifier and group state is the state of
1614     the paired master device if the device is a master device, or the state of
1615     the attached master keyboard if the device is an attached slave device, or
1616     zero if the device is a floating slave device.
1617
1618     For focus in and out events, the button state is the state of the paired
1619     master device if the device is a master device, or the state of the
1620     attached master keyboard if the device is an attached slave device, or
1621     zero if the device is a floating slave device.
1622
1623     root
1624     event
1625     child
1626         The root window, event window, and child window, respectively. See the
1627         core protocol specification for more detail.
1628     sourceid
1629         The device that caused the pointer to move.
1630     root_x
1631     root_y
1632         The pointer coordinates relative to the root window.
1633     event_x
1634     event_y
1635         The pointer coordinates relative to the event window.
1636     mode
1637         Normal pointer motion events have mode Normal. Pseudo-motion events
1638         when a grab activates have mode Grab, and pseudo-motion events when a
1639         grab deactivates have mode Ungrab. Pseudo-motion events caused by the
1640         activation or deactivation of a passive enter or focus in grab have mode
1641         XIPassiveGrabNotify or XIPassiveUngrabNotify.
1642     detail
1643         Specifies the relation of the event window to the window the pointer
1644         entered or left. See the core protocol spec for details.
1645     same_screen
1646         True if the event window is on the same screen as the pointer's root
1647         window.
1648     focus
1649         If the event window is the focus window or an inferior of the focus
1650         window, then focus is True. Otherwise, focus is False. This field is
1651         unspecified for focus in/out events.
1652     mods
1653         XKB modifier state before the event occured.
1654     group
1655         XKB group state before the event.
1656     buttons_len
1657         The length of buttons in 4 byte units.
1658     buttons
1659         Button state before the event.
1660
1661     ┌───
1662         XIPropertyEvent
1663             EVENTHEADER
1664             property:           ATOM
1665             what:               { PropertyCreated, PropertyDeleted, PropertyModified }
1666     └───
1667
1668     XIPropertyEvents are sent whenever a device property is created, deleted or
1669     modified by a client.
1670
1671     property
1672         The property that has been created, deleted, or modified
1673     what
1674         Specifies what has been changed.
1675
1676
1677                               ❧❧❧❧❧❧❧❧❧❧❧