xglcomp
view doc/fixesproto.txt @ 6:3f908f812ec7
added docs
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Fri, 29 Jan 2016 10:23:08 +0200 |
| parents | |
| children |
line source
1 The XFIXES Extension
2 Version 4.0
3 Document Revision 2
4 2006-12-14
5 Keith Packard
6 keithp@keithp.com
8 1. Introduction
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.
15 2. Acknowledgements
17 This extension is a direct result of requests made by application
18 developers, in particular,
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.
24 + Bill Haneman for the design for cursor image tracking.
26 + Havoc Pennington
28 + Fredrik Höglund for cursor names
30 + Deron Johnson for cursor visibility
32 3. Basic Premise
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.
39 4. Extension initialization
41 The client must negotiate the version of the extension before executing
42 extension requests. Behavior of the server is undefined otherwise.
44 QueryVersion
46 client-major-version: CARD32
47 client-minor-version: CARD32
49 ->
51 major-version: CARD32
52 minor-version: CARD32
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.
62 ************* XFIXES VERSION 1 OR BETTER ***********
64 5. Save Set processing changes
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.
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.
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.
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.
93 5.1 Requests
95 ChangeSaveSet
97 window: Window
98 mode: { Insert, Delete }
99 target: { Nearest, Root }
100 map: { Map, Unmap }
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.
110 6. Selection Tracking
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.
116 6.1 Types
118 SELECTIONEVENT { SetSelectionOwner,
119 SelectionWindowDestroy,
120 SelectionClientClose }
122 6.1 Events
124 SelectionNotify
126 subtype: SELECTIONEVENT
127 window: Window
128 owner: Window
129 selection: Atom
130 timestamp: Timestamp
131 selection-timestamp: Timestamp
133 6.2 Requests
135 SelectSelectionInput
137 window: Window
138 selection: Atom
139 event-mask: SETofSELECTIONEVENT
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.
148 7. Cursor Image Monitoring
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.
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.
162 7.1 Types
163 CURSOREVENT { DisplayCursor }
165 7.2 Events
167 CursorNotify
169 subtype: CURSOREVENT
170 window: Window
171 cursor-serial: CARD32
172 timestamp: Timestamp
173 name: Atom (Version 2 only)
175 7.3 Requests
177 SelectCursorInput
179 window: Window
180 event-mask: SETofCURSOREVENT
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.
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).
195 GetCursorImage
197 ->
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
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.
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.
221 ************* XFIXES VERSION 2 OR BETTER ***********
223 8. Region Objects
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.
231 8.1 Types
233 Region: XID
234 WINDOW_REGION_KIND: { Bounding, Clip }
236 8.2 Errors
238 Region The specified region is invalid
240 8.3 Requests
242 CreateRegion
244 region: REGION
245 rects: LISTofRECTANGLE
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.
255 Errors: IDChoice
257 CreateRegionFromBitmap
259 region: REGION
260 bitmap: PIXMAP
262 Creates a region initialized to the set of 'one' pixels in bitmap
263 (which must be depth 1, else Match error).
265 Errors: Pixmap, IDChoice, Match
267 CreateRegionFromWindow
269 window: Window
270 kind: WINDOW_REGION_KIND
271 region: Region
273 Creates a region initialized to the specified window region. See the
274 Shape extension for the definition of Bounding and Clip regions.
276 Errors: Window, IDChoice, Value
278 CreateRegionFromGC
280 gc: GContext
281 region: Region
283 Creates a region initialized from the clip list of the specified
284 GContext.
286 Errors: GContext, IDChoice
288 CreateRegionFromPicture
290 picture: Picture
291 region: Region
294 Creates a region initialized from the clip list of the specified
295 Picture.
297 Errors: Picture, IDChoice
299 DestroyRegion
301 region: Region
303 Destroys the specified region.
305 Errors: Region
307 SetRegion
309 region: Region
310 rects: LISTofRECTANGLE
312 This replaces the current contents of region with the region formed
313 by the union of rects.
315 CopyRegion
316 source: Region
317 destination: Region
319 This replaces the contents of destination with the contents of
320 source.
322 UnionRegion
323 IntersectRegion
324 SubtractRegion
326 source1: Region
327 source2: Region
328 destination: Region
330 Combines source1 and source2, placing the result in destination.
331 Destination may be the same as either source1 or source2.
333 Errors: Region, Value
335 InvertRegion
337 source: Region
338 bounds: RECTANGLE
339 destination: Region
341 The source region is subtracted from the region specified by
342 bounds. The result is placed in destination, replacing its contents.
344 Errors: Region
346 TranslateRegion
348 region: Region
349 dx, dy: INT16
351 The region is translated by dx, dy in place.
353 Errors: Region
355 RegionExtents
357 source: Region
358 destination: Region
360 The extents of the source region are placed in the destination
362 FetchRegion
364 region: Region
365 ->
366 extents: RECTANGLE
367 rectangles: LISTofRECTANGLE
369 The region is returned as a list of rectangles in YX-banded order.
371 Errors: Region
373 SetGCClipRegion
375 gc: GCONTEXT
376 clip-x-origin, clip-y-origin: INT16
377 region: Region or None
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.
386 Errors: GContext, Region
388 SetWindowShapeRegion
390 dest: Window
391 destKind: SHAPE_KIND
392 xOff, yOff: INT16
393 region: Region or None
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.
399 Errors: Window, Value, Region
401 SetPictureClipRegion
403 picture: Picture
404 clip-x-origin, clip-y-origin: INT16
405 region: Region or None
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.
414 Errors: Picture, Region
416 9. Cursor Names
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.
423 9.1 Events
425 CursorNotify
427 subtype: CURSOREVENT
428 window: Window
429 cursor-serial: CARD32
430 timestamp: Timestamp
431 name: Atom or None
433 In Version 2 of the XFIXES protocol, this event adds the atom
434 of any name associated with the current cursor (else None).
436 9.2 Requests
438 SetCursorName
440 cursor: CURSOR
441 name: LISTofCARD8
443 This request interns name as an atom and sets that atom as the name
444 of cursor.
446 Errors: Cursor
448 GetCursorName
450 cursor: CURSOR
451 ->
452 atom: ATOM or None
453 name: LISTofCARD8
455 This request returns the name and atom of cursor. If no name is
456 set, atom is None and name is empty.
458 Errors: Cursor
460 GetCursorImageAndName
462 ->
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
475 This is similar to GetCursorImage except for including both
476 the atom and name of the current cursor.
478 ChangeCursor
480 source, destination: CURSOR
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.
486 ChangeCursorByName
488 src: CURSOR
489 name: LISTofCARD8
491 This request replaces the contents of all cursors with the specified
492 name with the src cursor.
494 ************* XFIXES VERSION 3 OR BETTER ***********
496 10. Region Expansion
498 This update provides another operation on the region objects defined in
499 Section 8 of this document.
501 10.1 Requests
503 ExpandRegion
504 source: REGION
505 destination: REGION
506 left, right, top, bottom: CARD16
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.
512 ************* XFIXES VERSION 4 OR BETTER ***********
514 11. Cursor Visibility
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.
520 11.1 Requests
522 HideCursor
524 window: WINDOW
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.
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.
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.
542 When a client with outstanding cursor hiding requests
543 terminates its connection these requests will be deleted.
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.
550 ShowCursor
552 window: WINDOW
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.
563 If the client has made no outstanding HideCursor requests
564 a BadMatch error is generated.
566 Servers supporting the X Input Extension Version 2.0 or higher show
567 all visible cursors in response to a ShowCursor request.
569 99. Future compatibility
571 This extension is not expected to remain fixed. Future changes will
572 strive to remain compatible if at all possible. The X server will always
573 support version 1 of the extension protocol if requested by a client.
575 Additions to the protocol will always by marked by minor version number
576 changes so that applications will be able to detect what requests are
577 supported.