fixesproto.txt

   1                         The XFIXES Extension
   2                             Version 5.0
   3                          Document Revision 1
   4                              2010-11-15
   5                             Keith Packard
   6                           keithp@keithp.com
   7
   8 1. Introduction
   9
  10 X applications have often needed to work around various shortcomings in the
  11 core X window system.  This extension is designed to provide the minimal
  12 server-side support necessary to eliminate problems caused by these
  13 workarounds.
  14
  15 2. Acknowledgements
  16
  17 This extension is a direct result of requests made by application
  18 developers, in particular,
  19
  20  +      Owen Taylor for describing the issues raised with the XEMBED
  21         mechanisms and SaveSet processing and his initial extension
  22         to handle this issue, and for pointer barriers
  23
  24  +      Bill Haneman for the design for cursor image tracking.
  25
  26  +      Havoc Pennington
  27
  28  +      Fredrik Höglund for cursor names
  29
  30  +      Deron Johnson for cursor visibility
  31
  32 3. Basic Premise
  33
  34 Requests in this extension may seem to wander all over the map of X server
  35 capabilities, but they are tied by a simple rule -- resolving issues raised
  36 by application interaction with core protocol mechanisms that cannot be
  37 adequately worked around on the client side of the wire.
  38
  39 4. Extension initialization
  40
  41 The client must negotiate the version of the extension before executing
  42 extension requests.  Behavior of the server is undefined otherwise.
  43
  44 QueryVersion
  45
  46         client-major-version:           CARD32
  47         client-minor-version:           CARD32
  48
  49         ->
  50
  51         major-version:                  CARD32
  52         minor-version:                  CARD32
  53
  54         The client sends the highest supported version to the server and
  55         the server sends the highest version it supports, but no higher than
  56         the requested version.  Major versions changes can introduce
  57         new requests, minor version changes introduce only adjustments to
  58         existing requests or backward compatible changes.  It is
  59         the clients responsibility to ensure that the server supports
  60         a version which is compatible with its expectations.
  61
  62 ************* XFIXES VERSION 1 OR BETTER ***********
  63
  64 5. Save Set processing changes
  65
  66 Embedding one application within another provides a way of unifying
  67 disparate documents and views within a single framework.  From the X
  68 protocol perspective, this appears similar to nested window managers; the
  69 embedding application "manages" the embedded windows much as a window
  70 manager does for top-level windows.  To protect the embedded application
  71 from embedding application failure, it is reasonable to use the core SaveSet
  72 mechanism so that embedding application failure causes embedded windows to
  73 be preserved instead of destroyed.
  74
  75 The core save set mechanism defines the target for each save set member
  76 window as the nearest enclosing window not owned by the terminating client.
  77 For embedding applications, this nearest window is usually the window
  78 manager frame.  The problem here is that the window manager will not
  79 generally expect to receive and correctly manage new windows appearing within
  80 that window by the save set mechanism, and will instead destroy the frame
  81 window in response to the client window destruction.  This causes the
  82 embedded window to be destroyed.
  83
  84 An easy fix for this problem is to change the target of the save set member
  85 to a window which won't be affected by the underlying window destruction.
  86 XFIXES chooses the root window as the target.
  87
  88 Having embedded windows suddenly appear at the top level can confuse users,
  89 so XFIXES also lets the client select whether the window should end up
  90 unmapped after the save set processing instead of unconditionally making
  91 them be mapped.
  92
  93 5.1 Requests
  94
  95 ChangeSaveSet
  96
  97                 window:                         Window
  98                 mode:                           { Insert, Delete }
  99                 target:                         { Nearest, Root }
 100                 map:                            { Map, Unmap }
 101
 102         ChangeSaveSet is an extension of the core protocol ChangeSaveSet
 103         request.  As in that request, mode specifies whether the indicated
 104         window is inserted or deleted from the save-set.  Target specifies
 105         whether the window is reparented to the nearest non-client window as
 106         in the core protocol, or reparented to the root window.  Map
 107         specifies whether the window is mapped as in the core protocol or
 108         unmapped.
 109
 110 6. Selection Tracking
 111
 112 Applications wishing to monitor the contents of current selections must
 113 poll for selection changes.  XFIXES improves this by providing an event
 114 delivered whenever the selection ownership changes.
 115
 116 6.1 Types
 117
 118         SELECTIONEVENT                  { SetSelectionOwner,
 119                                           SelectionWindowDestroy,
 120                                           SelectionClientClose }
 121
 122 6.1 Events
 123
 124 SelectionNotify
 125
 126         subtype:                        SELECTIONEVENT
 127         window:                         Window
 128         owner:                          Window
 129         selection:                      Atom
 130         timestamp:                      Timestamp
 131         selection-timestamp:            Timestamp
 132
 133 6.2 Requests
 134
 135 SelectSelectionInput
 136
 137                 window:                         Window
 138                 selection:                      Atom
 139                 event-mask:                     SETofSELECTIONEVENT
 140
 141         Selects for events to be delivered to window when various causes of
 142         ownership of selection occur.  Subtype indicates the cause of the
 143         selection ownership change.  Owner is set to the current selection
 144         owner, or None.  Timestamp indicates the time the event was
 145         generated while selection-timestamp indicates the timestamp used to
 146         own the selection.
 147
 148 7. Cursor Image Monitoring
 149
 150 Mirroring the screen contents is easily done with the core protocol or VNC
 151 addons, except for the current cursor image.  There is no way using the core
 152 protocol to discover which cursor image is currently displayed.  The
 153 cursor image often contains significant semantic content about the user
 154 interface.  XFIXES provides a simple mechanism to discover when the cursor
 155 image changes and to fetch the current cursor image.
 156
 157 As the current cursor may or may not have any XID associated with it, there
 158 is no stable name available.  Instead, XFIXES returns only the image of the
 159 current cursor and provides a way to identify cursor images to avoid
 160 refetching the image each time it changes to a previously seen cursor.
 161
 162 7.1 Types
 163         CURSOREVENT                     { DisplayCursor }
 164
 165 7.2 Events
 166
 167 CursorNotify
 168
 169         subtype:                CURSOREVENT
 170         window:                 Window
 171         cursor-serial:          CARD32
 172         timestamp:              Timestamp
 173         name:                   Atom            (Version 2 only)
 174
 175 7.3 Requests
 176
 177 SelectCursorInput
 178
 179                 window:                 Window
 180                 event-mask:             SETofCURSOREVENT
 181
 182         This request directs cursor change events to the named window.
 183         Events will be delivered irrespective of the screen on which they
 184         occur.  Subtype indicates the cause of the cursor image change
 185         (there is only one subtype at present).  Cursor-serial is a number
 186         assigned to the cursor image which identifies the image.  Cursors
 187         with different serial numbers may have different images.  Timestamp
 188         is the time of the cursor change.
 189
 190         Servers supporting the X Input Extension Version 2.0 or higher only
 191         notify the clients of cursor change events for the ClientPointer, not
 192         of any other master pointer (see Section 4.4. in the XI2 protocol
 193         specificiation).
 194
 195 GetCursorImage
 196
 197                 ->
 198
 199                 x:                      INT16
 200                 y:                      INT16
 201                 width:                  CARD16
 202                 height:                 CARD16
 203                 x-hot:                  CARD16
 204                 y-hot:                  CARD16
 205                 cursor-serial:          CARD32
 206                 cursor-image:           LISTofCARD32
 207
 208         GetCursorImage returns the image of the current cursor.  X and y are
 209         the current cursor position.  Width and height are the size of the
 210         cursor image.  X-hot and y-hot mark the hotspot within the cursor
 211         image.  Cursor-serial provides the number assigned to this cursor
 212         image, this same serial number will be reported in a CursorNotify
 213         event if this cursor image is redisplayed in the future.
 214
 215         The cursor image itself is returned as a single image at 32 bits per
 216         pixel with 8 bits of alpha in the most significant 8 bits of the
 217         pixel followed by 8 bits each of red, green and finally 8 bits of
 218         blue in the least significant 8 bits.  The color components are
 219         pre-multiplied with the alpha component.
 220
 221 ************* XFIXES VERSION 2 OR BETTER ***********
 222
 223 8. Region Objects
 224
 225 The core protocol doesn't expose regions as a primitive object and this
 226 makes many operations more complicated than they really need to be.  Adding
 227 region objects simplifies expose handling, the Shape extension and other
 228 operations. These operations are also designed to support a separate
 229 extension, the X Damage Extension.
 230
 231 8.1 Types
 232
 233         Region:                         XID
 234         WINDOW_REGION_KIND:             { Bounding, Clip }
 235
 236 8.2 Errors
 237
 238         Region                          The specified region is invalid
 239
 240 8.3 Requests
 241
 242 CreateRegion
 243
 244                 region:                         REGION
 245                 rects:                          LISTofRECTANGLE
 246
 247         Creates a region initialized to the specified list of rectangles.
 248         The rectangles may be specified in any order, their union becomes
 249         the region.  The core protocol allows applications to specify an
 250         order for the rectangles, but it turns out to be just as hard to
 251         verify the rectangles are actually in that order as it is to simply
 252         ignore the ordering information and union them together.  Hence,
 253         this request dispenses with the ordering information.
 254
 255         Errors: IDChoice
 256
 257 CreateRegionFromBitmap
 258
 259                 region:                         REGION
 260                 bitmap:                         PIXMAP
 261
 262         Creates a region initialized to the set of 'one' pixels in bitmap
 263         (which must be depth 1, else Match error).
 264
 265         Errors: Pixmap, IDChoice, Match
 266
 267 CreateRegionFromWindow
 268
 269                 window:                         Window
 270                 kind:                           WINDOW_REGION_KIND
 271                 region:                         Region
 272
 273         Creates a region initialized to the specified window region.  See the
 274         Shape extension for the definition of Bounding and Clip regions.
 275
 276         Errors: Window, IDChoice, Value
 277
 278 CreateRegionFromGC
 279
 280                 gc:                             GContext
 281                 region:                         Region
 282
 283         Creates a region initialized from the clip list of the specified
 284         GContext.
 285
 286         Errors: GContext, IDChoice
 287
 288 CreateRegionFromPicture
 289
 290                 picture:                        Picture
 291                 region:                         Region
 292
 293
 294         Creates a region initialized from the clip list of the specified
 295         Picture.
 296
 297         Errors: Picture, IDChoice
 298
 299 DestroyRegion
 300
 301                 region:                         Region
 302
 303         Destroys the specified region.
 304
 305         Errors: Region
 306
 307 SetRegion
 308
 309                 region:                         Region
 310                 rects:                          LISTofRECTANGLE
 311
 312         This replaces the current contents of region with the region formed
 313         by the union of rects.
 314
 315 CopyRegion
 316                 source:                         Region
 317                 destination:                    Region
 318
 319         This replaces the contents of destination with the contents of
 320         source.
 321
 322 UnionRegion
 323 IntersectRegion
 324 SubtractRegion
 325
 326                 source1:                        Region
 327                 source2:                        Region
 328                 destination:                    Region
 329
 330         Combines source1 and source2, placing the result in destination.
 331         Destination may be the same as either source1 or source2.
 332
 333         Errors: Region, Value
 334
 335 InvertRegion
 336
 337                 source:                         Region
 338                 bounds:                         RECTANGLE
 339                 destination:                    Region
 340
 341         The source region is subtracted from the region specified by
 342         bounds.  The result is placed in destination, replacing its contents.
 343
 344         Errors: Region
 345
 346 TranslateRegion
 347
 348                 region:                         Region
 349                 dx, dy:                         INT16
 350
 351         The region is translated by dx, dy in place.
 352
 353         Errors: Region
 354
 355 RegionExtents
 356
 357                 source:                         Region
 358                 destination:                    Region
 359
 360         The extents of the source region are placed in the destination
 361
 362 FetchRegion
 363
 364                 region:                         Region
 365                 ->
 366                 extents:                        RECTANGLE
 367                 rectangles:                     LISTofRECTANGLE
 368
 369         The region is returned as a list of rectangles in YX-banded order.
 370
 371         Errors: Region
 372
 373 SetGCClipRegion
 374
 375                 gc:                             GCONTEXT
 376                 clip-x-origin, clip-y-origin:   INT16
 377                 region:                         Region or None
 378
 379         This request changes clip-mask in gc to the specified region and
 380         sets the clip origin.  Output will be clipped to remain contained
 381         within the region.  The clip origin is interpreted relative to the
 382         origin of whatever destination drawable is specified in a graphics
 383         request.  The region is interpreted relative to the clip origin.
 384         Future changes to region have no effect on the gc clip-mask.
 385
 386         Errors: GContext, Region
 387
 388 SetWindowShapeRegion
 389
 390                 dest:                           Window
 391                 destKind:                       SHAPE_KIND
 392                 xOff, yOff:                     INT16
 393                 region:                         Region or None
 394
 395         This request sets the specified (by destKind) Shape extension region
 396         of the window to region, offset by xOff and yOff.   Future changes to
 397         region have no effect on the window shape.
 398
 399         Errors: Window, Value, Region
 400
 401 SetPictureClipRegion
 402
 403                 picture:                        Picture
 404                 clip-x-origin, clip-y-origin:   INT16
 405                 region:                         Region or None
 406
 407         This request changes clip-mask in picture to the specified region
 408         and sets the clip origin.  Input and output will be clipped to
 409         remain contained within the region.  The clip origin is interpreted
 410         relative to the origin of the drawable associated with picture.  The
 411         region is interpreted relative to the clip origin.  Future changes
 412         to region have no effect on the picture clip-mask.
 413
 414         Errors: Picture, Region
 415
 416 9. Cursor Names
 417
 418 Attaching names to cursors permits some abstract semantic content to be
 419 associated with specific cursor images.  Reflecting those names back to
 420 applications allows that semantic content to be related to the user through
 421 non-visual means.
 422
 423 9.1 Events
 424
 425 CursorNotify
 426
 427                 subtype:                CURSOREVENT
 428                 window:                 Window
 429                 cursor-serial:          CARD32
 430                 timestamp:              Timestamp
 431                 name:                   Atom or None
 432
 433         In Version 2 of the XFIXES protocol, this event adds the atom
 434         of any name associated with the current cursor (else None).
 435
 436 9.2 Requests
 437
 438 SetCursorName
 439
 440                 cursor:                 CURSOR
 441                 name:                   LISTofCARD8
 442
 443         This request interns name as an atom and sets that atom as the name
 444         of cursor.
 445
 446         Errors: Cursor
 447
 448 GetCursorName
 449
 450                 cursor:                 CURSOR
 451                 ->
 452                 atom:                   ATOM or None
 453                 name:                   LISTofCARD8
 454
 455         This request returns the name and atom of cursor.  If no name is
 456         set, atom is None and name is empty.
 457
 458         Errors: Cursor
 459
 460 GetCursorImageAndName
 461
 462                 ->
 463
 464                 x:                      INT16
 465                 y:                      INT16
 466                 width:                  CARD16
 467                 height:                 CARD16
 468                 x-hot:                  CARD16
 469                 y-hot:                  CARD16
 470                 cursor-serial:          CARD32
 471                 cursor-atom:            ATOM
 472                 cursor-name:            LISTofCARD8
 473                 cursor-image:           LISTofCARD32
 474
 475         This is similar to GetCursorImage except for including both
 476         the atom and name of the current cursor.
 477
 478 ChangeCursor
 479
 480                 source, destination:    CURSOR
 481
 482         This request replaces all references to the destination with a
 483         reference to source.  Any existing uses of the destination cursor
 484         object will now show the source cursor image.
 485
 486 ChangeCursorByName
 487
 488                 src:                    CURSOR
 489                 name:                   LISTofCARD8
 490
 491         This request replaces the contents of all cursors with the specified
 492         name with the src cursor.
 493
 494 ************* XFIXES VERSION 3 OR BETTER ***********
 495
 496 10. Region Expansion
 497
 498 This update provides another operation on the region objects defined in
 499 Section 8 of this document.
 500
 501 10.1 Requests
 502
 503 ExpandRegion
 504                 source:                         REGION
 505                 destination:                    REGION
 506                 left, right, top, bottom:       CARD16
 507
 508         Creates destination region containing the area specified by
 509         expanding each rectangle in the source region by the specified
 510         number of pixels to the left, right, top and bottom.
 511
 512 ************* XFIXES VERSION 4 OR BETTER ***********
 513
 514 11. Cursor Visibility
 515
 516 Composite managers may want to render the cursor themselves instead of
 517 relying on the X server sprite drawing, this provides a way for them to
 518 do so without getting a double cursor image.
 519
 520 11.1 Requests
 521
 522 HideCursor
 523
 524                 window:                 WINDOW
 525
 526         A client sends this request to indicate that it wants the
 527         cursor image to be hidden (i.e. to not be displayed) when
 528         the sprite is inside the specified window, or one of its
 529         subwindows. If the sprite is inside a window for which one
 530         or more active clients have requested cursor hiding then the
 531         cursor image will not be displayed.
 532
 533         Note that even though cursor hiding causes the cursor image
 534         to be invisible, CursorNotify events will still be sent
 535         normally, as if the cursor image were visible.
 536
 537         If, during a grab, one or more active clients have requested
 538         cursor hiding for grab window, or one of its ancestors, the
 539         cursor image of the grab cursor will not be displayed during
 540         the lifetime of that grab.
 541
 542         When a client with outstanding cursor hiding requests
 543         terminates its connection these requests will be deleted.
 544
 545         Servers supporting the X Input Extension Version 2.0 or higher hide
 546         all visible cursors in response to a HideCursor request. If a master
 547         pointer is created while the cursors are hidden, this master pointer's
 548         cursor will be hidden as well.
 549
 550 ShowCursor
 551
 552                 window:                 WINDOW
 553
 554         A client sends this request to indicate that it wants the
 555         cursor image to be displayed when the sprite is inside the
 556         specified window, or one of its subwindows. If the sprite
 557         is inside a window for which no active clients have requested
 558         cursor hiding then the cursor image for that window will be
 559         displayed. In other words, if a client calls HideCursor for
 560         a specified window, or window subtree, this request reverses
 561         the effects of the HideCursor request.
 562
 563         If the client has made no outstanding HideCursor requests
 564         a BadMatch error is generated.
 565
 566         Servers supporting the X Input Extension Version 2.0 or higher show
 567         all visible cursors in response to a ShowCursor request.
 568
 569 ************* XFIXES VERSION 5 OR BETTER ***********
 570
 571 12. Pointer Barriers
 572
 573 Compositing managers and desktop environments may have UI elements in
 574 particular screen locations such that for a single-headed display they
 575 correspond to easy targets according to Fitt's Law, for example, the top
 576 left corner.  For a multi-headed environment these corners should still be
 577 semi-impermeable.  Pointer barriers allow the application to define
 578 additional constraint on cursor motion so that these areas behave as
 579 expected even in the face of multiple displays.
 580
 581 Absolute positioning devices like touchscreens do not obey pointer barriers.
 582 There's no advantage to target acquisition to do so, since on a touchscreen
 583 all points are in some sense equally large, whereas for a relative
 584 positioning device the edges and corners are infinitely large.
 585
 586 WarpPointer and similar requests do not obey pointer barriers, for
 587 essentially the same reason.
 588
 589 12.1 Types
 590
 591         BARRIER:        XID
 592
 593         BarrierDirections
 594
 595                 BarrierPositiveX:           1 << 0
 596                 BarrierPositiveY:           1 << 1
 597                 BarrierNegativeX:           1 << 2
 598                 BarrierNegativeY:           1 << 3
 599
 600 12.2 Errors
 601
 602         Barrier
 603
 604 12.3 Requests
 605
 606 CreatePointerBarrier
 607
 608                 barrier:                    BARRIER
 609                 drawable:                   DRAWABLE
 610                 x1, y2, x2, y2:             INT16
 611                 directions:                 CARD32
 612                 devices:                    LISTofDEVICEID
 613
 614         Creates a pointer barrier along the line specified by the given
 615         coordinates on the screen associated with the given drawable.  The
 616         barrier has no spatial extent; it is simply a line along the left
 617         or top edge of the specified pixels.  Barrier coordinates are in
 618         screen space.
 619
 620         The coordinates must be axis aligned, either x1 == x2, or
 621         y1 == y2, but not both.  The varying coordinates may be specified
 622         in any order.  For x1 == x2, either y1 > y2 or y1 < y2 is valid.
 623         If the coordinates are not valid BadValue is generated.
 624
 625         Motion is allowed through the barrier in the directions specified:
 626         setting the BarrierPositiveX bit allows travel through the barrier
 627         in the positive X direction, etc.  Nonsensical values (forbidding Y
 628         axis travel through a vertical barrier, for example) and excess set
 629         bits are ignored.
 630
 631         If the server supports the X Input Extension version 2 or higher,
 632         the devices element names a set of master device to apply the
 633         barrier to.  If XIAllDevices or XIAllMasterDevices are given, the
 634         barrier applies to all master devices.  If a slave device is named,
 635         BadDevice is generated; this does not apply to slave devices named
 636         implicitly by XIAllDevices.  Naming a device multiple times is
 637         legal, and is treated as though it were named only once.  If a
 638         device is removed, the barrier continues to apply to the remaining
 639         devices, but will not apply to any future device with the same ID
 640         as the removed device.  Nothing special happens when all matching
 641         devices are removed; barriers must be explicitly destroyed.
 642
 643         Errors: IDChoice, Window, Value, Device
 644
 645 DestroyPointerBarrier
 646
 647                 barrier:                    BARRIER
 648
 649         Destroys the named barrier.
 650
 651         Errors: Barrier
 652
 653 99. Future compatibility
 654
 655 This extension is not expected to remain fixed.  Future changes will
 656 strive to remain compatible if at all possible.  The X server will always
 657 support version 1 of the extension protocol if requested by a client.
 658
 659 Additions to the protocol will always by marked by minor version number
 660 changes so that applications will be able to detect what requests are
 661 supported.