fixesproto.txt revision d63b911f
1 The XFIXES Extension 2 Version 5.0 3 Document Revision 1 4 2010-11-15 5 Keith Packard 6 keithp@keithp.com 7 81. Introduction 9 10X applications have often needed to work around various shortcomings in the 11core X window system. This extension is designed to provide the minimal 12server-side support necessary to eliminate problems caused by these 13workarounds. 14 152. Acknowledgements 16 17This extension is a direct result of requests made by application 18developers, 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 323. Basic Premise 33 34Requests in this extension may seem to wander all over the map of X server 35capabilities, but they are tied by a simple rule -- resolving issues raised 36by application interaction with core protocol mechanisms that cannot be 37adequately worked around on the client side of the wire. 38 394. Extension initialization 40 41The client must negotiate the version of the extension before executing 42extension requests. Behavior of the server is undefined otherwise. 43 44QueryVersion 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 645. Save Set processing changes 65 66Embedding one application within another provides a way of unifying 67disparate documents and views within a single framework. From the X 68protocol perspective, this appears similar to nested window managers; the 69embedding application "manages" the embedded windows much as a window 70manager does for top-level windows. To protect the embedded application 71from embedding application failure, it is reasonable to use the core SaveSet 72mechanism so that embedding application failure causes embedded windows to 73be preserved instead of destroyed. 74 75The core save set mechanism defines the target for each save set member 76window as the nearest enclosing window not owned by the terminating client. 77For embedding applications, this nearest window is usually the window 78manager frame. The problem here is that the window manager will not 79generally expect to receive and correctly manage new windows appearing within 80that window by the save set mechanism, and will instead destroy the frame 81window in response to the client window destruction. This causes the 82embedded window to be destroyed. 83 84An easy fix for this problem is to change the target of the save set member 85to a window which won't be affected by the underlying window destruction. 86XFIXES chooses the root window as the target. 87 88Having embedded windows suddenly appear at the top level can confuse users, 89so XFIXES also lets the client select whether the window should end up 90unmapped after the save set processing instead of unconditionally making 91them be mapped. 92 935.1 Requests 94 95ChangeSaveSet 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 1106. Selection Tracking 111 112Applications wishing to monitor the contents of current selections must 113poll for selection changes. XFIXES improves this by providing an event 114delivered whenever the selection ownership changes. 115 1166.1 Types 117 118 SELECTIONEVENT { SetSelectionOwner, 119 SelectionWindowDestroy, 120 SelectionClientClose } 121 1226.1 Events 123 124SelectionNotify 125 126 subtype: SELECTIONEVENT 127 window: Window 128 owner: Window 129 selection: Atom 130 timestamp: Timestamp 131 selection-timestamp: Timestamp 132 1336.2 Requests 134 135SelectSelectionInput 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 1487. Cursor Image Monitoring 149 150Mirroring the screen contents is easily done with the core protocol or VNC 151addons, except for the current cursor image. There is no way using the core 152protocol to discover which cursor image is currently displayed. The 153cursor image often contains significant semantic content about the user 154interface. XFIXES provides a simple mechanism to discover when the cursor 155image changes and to fetch the current cursor image. 156 157As the current cursor may or may not have any XID associated with it, there 158is no stable name available. Instead, XFIXES returns only the image of the 159current cursor and provides a way to identify cursor images to avoid 160refetching the image each time it changes to a previously seen cursor. 161 1627.1 Types 163 CURSOREVENT { DisplayCursor } 164 1657.2 Events 166 167CursorNotify 168 169 subtype: CURSOREVENT 170 window: Window 171 cursor-serial: CARD32 172 timestamp: Timestamp 173 name: Atom (Version 2 only) 174 1757.3 Requests 176 177SelectCursorInput 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 specification). 194 195GetCursorImage 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 2238. Region Objects 224 225The core protocol doesn't expose regions as a primitive object and this 226makes many operations more complicated than they really need to be. Adding 227region objects simplifies expose handling, the Shape extension and other 228operations. These operations are also designed to support a separate 229extension, the X Damage Extension. 230 2318.1 Types 232 233 Region: XID 234 WINDOW_REGION_KIND: { Bounding, Clip } 235 2368.2 Errors 237 238 Region The specified region is invalid 239 2408.3 Requests 241 242CreateRegion 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 257CreateRegionFromBitmap 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 267CreateRegionFromWindow 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 278CreateRegionFromGC 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 288CreateRegionFromPicture 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 299DestroyRegion 300 301 region: Region 302 303 Destroys the specified region. 304 305 Errors: Region 306 307SetRegion 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 315CopyRegion 316 source: Region 317 destination: Region 318 319 This replaces the contents of destination with the contents of 320 source. 321 322UnionRegion 323IntersectRegion 324SubtractRegion 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 335InvertRegion 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 346TranslateRegion 347 348 region: Region 349 dx, dy: INT16 350 351 The region is translated by dx, dy in place. 352 353 Errors: Region 354 355RegionExtents 356 357 source: Region 358 destination: Region 359 360 The extents of the source region are placed in the destination 361 362FetchRegion 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 373SetGCClipRegion 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 388SetWindowShapeRegion 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 401SetPictureClipRegion 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 4169. Cursor Names 417 418Attaching names to cursors permits some abstract semantic content to be 419associated with specific cursor images. Reflecting those names back to 420applications allows that semantic content to be related to the user through 421non-visual means. 422 4239.1 Events 424 425CursorNotify 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 4369.2 Requests 437 438SetCursorName 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 448GetCursorName 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 460GetCursorImageAndName 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-image: LISTofCARD32 473 cursor-name: LISTofCARD8 474 475 This is similar to GetCursorImage except for including both 476 the atom and name of the current cursor. 477 478ChangeCursor 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 486ChangeCursorByName 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 49610. Region Expansion 497 498This update provides another operation on the region objects defined in 499Section 8 of this document. 500 50110.1 Requests 502 503ExpandRegion 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 51411. Cursor Visibility 515 516Composite managers may want to render the cursor themselves instead of 517relying on the X server sprite drawing, this provides a way for them to 518do so without getting a double cursor image. 519 52011.1 Requests 521 522HideCursor 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 on the same screen as the specified window. 529 The sprite will be hidden if one or more clients have called 530 HideCursor and not ShowCursor. 531 532 Note that even though cursor hiding causes the cursor image 533 to be invisible, CursorNotify events will still be sent 534 normally, as if the cursor image were visible. 535 536 When a client with outstanding cursor hiding requests 537 terminates its connection these requests will be deleted. 538 539 Servers supporting the X Input Extension Version 2.0 or higher hide 540 all visible cursors in response to a HideCursor request. If a master 541 pointer is created while the cursors are hidden, this master pointer's 542 cursor will be hidden as well. 543 544ShowCursor 545 546 window: WINDOW 547 548 A client sends this request to indicate that it wants the 549 cursor image to be displayed when the sprite is on the same 550 screen as the specified window. The sprite will be hidden 551 if one or more clients have called HideCursor and not ShowCursor. 552 553 If the client has made no outstanding HideCursor requests 554 a BadMatch error is generated. 555 556 Servers supporting the X Input Extension Version 2.0 or higher show 557 all visible cursors in response to a ShowCursor request. 558 559************* XFIXES VERSION 5 OR BETTER *********** 560 56112. Pointer Barriers 562 563Compositing managers and desktop environments may have UI elements in 564particular screen locations such that for a single-headed display they 565correspond to easy targets according to Fitt's Law, for example, the top 566left corner. For a multi-headed environment these corners should still be 567semi-impermeable. Pointer barriers allow the application to define 568additional constraint on cursor motion so that these areas behave as 569expected even in the face of multiple displays. 570 571Absolute positioning devices like touchscreens do not obey pointer barriers. 572There's no advantage to target acquisition to do so, since on a touchscreen 573all points are in some sense equally large, whereas for a relative 574positioning device the edges and corners are infinitely large. 575 576WarpPointer and similar requests do not obey pointer barriers, for 577essentially the same reason. 578 57912.1 Types 580 581 BARRIER: XID 582 583 BarrierDirections 584 585 BarrierPositiveX: 1 << 0 586 BarrierPositiveY: 1 << 1 587 BarrierNegativeX: 1 << 2 588 BarrierNegativeY: 1 << 3 589 59012.2 Errors 591 592 Barrier 593 59412.3 Requests 595 596CreatePointerBarrier 597 598 barrier: BARRIER 599 window: Window 600 x1, y2, x2, y2: INT16 601 directions: CARD32 602 devices: LISTofDEVICEID 603 604 Creates a pointer barrier along the line specified by the given 605 coordinates on the screen associated with the given window. The 606 barrier has no spatial extent; it is simply a line along the left 607 or top edge of the specified pixels. Barrier coordinates are in 608 screen space. 609 610 The coordinates must be axis aligned, either x1 == x2, or 611 y1 == y2, but not both. The varying coordinates may be specified 612 in any order. For x1 == x2, either y1 > y2 or y1 < y2 is valid. 613 If the coordinates are not valid BadValue is generated. 614 615 Motion is allowed through the barrier in the directions specified: 616 setting the BarrierPositiveX bit allows travel through the barrier 617 in the positive X direction, etc. Nonsensical values (forbidding Y 618 axis travel through a vertical barrier, for example) and excess set 619 bits are ignored. 620 621 If the server supports the X Input Extension version 2 or higher, 622 the devices element names a set of master device to apply the 623 barrier to. If XIAllDevices or XIAllMasterDevices are given, the 624 barrier applies to all master devices. If a slave device is named, 625 BadDevice is generated; this does not apply to slave devices named 626 implicitly by XIAllDevices. Naming a device multiple times is 627 legal, and is treated as though it were named only once. If a 628 device is removed, the barrier continues to apply to the remaining 629 devices, but will not apply to any future device with the same ID 630 as the removed device. Nothing special happens when all matching 631 devices are removed; barriers must be explicitly destroyed. 632 633 Errors: IDChoice, Window, Value, Device 634 635DestroyPointerBarrier 636 637 barrier: BARRIER 638 639 Destroys the named barrier. 640 641 Errors: Barrier 642 64399. Future compatibility 644 645This extension is not expected to remain fixed. Future changes will 646strive to remain compatible if at all possible. The X server will always 647support version 1 of the extension protocol if requested by a client. 648 649Additions to the protocol will always by marked by minor version number 650changes so that applications will be able to detect what requests are 651supported. 652