diff options
Diffstat (limited to 'X11/extensions/fixesproto.txt')
| -rw-r--r-- | X11/extensions/fixesproto.txt | 577 |
1 files changed, 577 insertions, 0 deletions
diff --git a/X11/extensions/fixesproto.txt b/X11/extensions/fixesproto.txt new file mode 100644 index 000000000..5ef815385 --- /dev/null +++ b/X11/extensions/fixesproto.txt @@ -0,0 +1,577 @@ + The XFIXES Extension + Version 4.0 + Document Revision 2 + 2006-12-14 + Keith Packard + keithp@keithp.com + +1. Introduction + +X applications have often needed to work around various shortcomings in the +core X window system. This extension is designed to provide the minimal +server-side support necessary to eliminate problems caused by these +workarounds. + +2. Acknowledgements + +This extension is a direct result of requests made by application +developers, in particular, + + + Owen Taylor for describing the issues raised with the XEMBED + mechanisms and SaveSet processing and his initial extension + to handle this issue. + + + Bill Haneman for the design for cursor image tracking. + + + Havoc Pennington + + + Fredrik Höglund for cursor names + + + Deron Johnson for cursor visibility + +3. Basic Premise + +Requests in this extension may seem to wander all over the map of X server +capabilities, but they are tied by a simple rule -- resolving issues raised +by application interaction with core protocol mechanisms that cannot be +adequately worked around on the client side of the wire. + +4. Extension initialization + +The client must negotiate the version of the extension before executing +extension requests. Behavior of the server is undefined otherwise. + +QueryVersion + + client-major-version: CARD32 + client-minor-version: CARD32 + + -> + + major-version: CARD32 + minor-version: CARD32 + + The client sends the highest supported version to the server and + the server sends the highest version it supports, but no higher than + the requested version. Major versions changes can introduce + new requests, minor version changes introduce only adjustments to + existing requests or backward compatible changes. It is + the clients responsibility to ensure that the server supports + a version which is compatible with its expectations. + +************* XFIXES VERSION 1 OR BETTER *********** + +5. Save Set processing changes + +Embedding one application within another provides a way of unifying +disparate documents and views within a single framework. From the X +protocol perspective, this appears similar to nested window managers; the +embedding application "manages" the embedded windows much as a window +manager does for top-level windows. To protect the embedded application +from embedding application failure, it is reasonable to use the core SaveSet +mechanism so that embedding application failure causes embedded windows to +be preserved instead of destroyed. + +The core save set mechanism defines the target for each save set member +window as the nearest enclosing window not owned by the terminating client. +For embedding applications, this nearest window is usually the window +manager frame. The problem here is that the window manager will not +generally expect to receive and correctly manage new windows appearing within +that window by the save set mechanism, and will instead destroy the frame +window in response to the client window destruction. This causes the +embedded window to be destroyed. + +An easy fix for this problem is to change the target of the save set member +to a window which won't be affected by the underlying window destruction. +XFIXES chooses the root window as the target. + +Having embedded windows suddenly appear at the top level can confuse users, +so XFIXES also lets the client select whether the window should end up +unmapped after the save set processing instead of unconditionally making +them be mapped. + +5.1 Requests + +ChangeSaveSet + + window: Window + mode: { Insert, Delete } + target: { Nearest, Root } + map: { Map, Unmap } + + ChangeSaveSet is an extension of the core protocol ChangeSaveSet + request. As in that request, mode specifies whether the indicated + window is inserted or deleted from the save-set. Target specifies + whether the window is reparented to the nearest non-client window as + in the core protocol, or reparented to the root window. Map + specifies whether the window is mapped as in the core protocol or + unmapped. + +6. Selection Tracking + +Applications wishing to monitor the contents of current selections must +poll for selection changes. XFIXES improves this by providing an event +delivered whenever the selection ownership changes. + +6.1 Types + + SELECTIONEVENT { SetSelectionOwner, + SelectionWindowDestroy, + SelectionClientClose } + +6.1 Events + +SelectionNotify + + subtype: SELECTIONEVENT + window: Window + owner: Window + selection: Atom + timestamp: Timestamp + selection-timestamp: Timestamp + +6.2 Requests + +SelectSelectionInput + + window: Window + selection: Atom + event-mask: SETofSELECTIONEVENT + + Selects for events to be delivered to window when various causes of + ownership of selection occur. Subtype indicates the cause of the + selection ownership change. Owner is set to the current selection + owner, or None. Timestamp indicates the time the event was + generated while selection-timestamp indicates the timestamp used to + own the selection. + +7. Cursor Image Monitoring + +Mirroring the screen contents is easily done with the core protocol or VNC +addons, except for the current cursor image. There is no way using the core +protocol to discover which cursor image is currently displayed. The +cursor image often contains significant semantic content about the user +interface. XFIXES provides a simple mechanism to discover when the cursor +image changes and to fetch the current cursor image. + +As the current cursor may or may not have any XID associated with it, there +is no stable name available. Instead, XFIXES returns only the image of the +current cursor and provides a way to identify cursor images to avoid +refetching the image each time it changes to a previously seen cursor. + +7.1 Types + CURSOREVENT { DisplayCursor } + +7.2 Events + +CursorNotify + + subtype: CURSOREVENT + window: Window + cursor-serial: CARD32 + timestamp: Timestamp + name: Atom (Version 2 only) + +7.3 Requests + +SelectCursorInput + + window: Window + event-mask: SETofCURSOREVENT + + This request directs cursor change events to the named window. + Events will be delivered irrespective of the screen on which they + occur. Subtype indicates the cause of the cursor image change + (there is only one subtype at present). Cursor-serial is a number + assigned to the cursor image which identifies the image. Cursors + with different serial numbers may have different images. Timestamp + is the time of the cursor change. + + Servers supporting the X Input Extension Version 2.0 or higher only + notify the clients of cursor change events for the ClientPointer, not + of any other master pointer (see Section 4.4. in the XI2 protocol + specificiation). + +GetCursorImage + + -> + + x: INT16 + y: INT16 + width: CARD16 + height: CARD16 + x-hot: CARD16 + y-hot: CARD16 + cursor-serial: CARD32 + cursor-image: LISTofCARD32 + + GetCursorImage returns the image of the current cursor. X and y are + the current cursor position. Width and height are the size of the + cursor image. X-hot and y-hot mark the hotspot within the cursor + image. Cursor-serial provides the number assigned to this cursor + image, this same serial number will be reported in a CursorNotify + event if this cursor image is redisplayed in the future. + + The cursor image itself is returned as a single image at 32 bits per + pixel with 8 bits of alpha in the most significant 8 bits of the + pixel followed by 8 bits each of red, green and finally 8 bits of + blue in the least significant 8 bits. The color components are + pre-multiplied with the alpha component. + +************* XFIXES VERSION 2 OR BETTER *********** + +8. Region Objects + +The core protocol doesn't expose regions as a primitive object and this +makes many operations more complicated than they really need to be. Adding +region objects simplifies expose handling, the Shape extension and other +operations. These operations are also designed to support a separate +extension, the X Damage Extension. + +8.1 Types + + Region: XID + WINDOW_REGION_KIND: { Bounding, Clip } + +8.2 Errors + + Region The specified region is invalid + +8.3 Requests + +CreateRegion + + region: REGION + rects: LISTofRECTANGLE + + Creates a region initialized to the specified list of rectangles. + The rectangles may be specified in any order, their union becomes + the region. The core protocol allows applications to specify an + order for the rectangles, but it turns out to be just as hard to + verify the rectangles are actually in that order as it is to simply + ignore the ordering information and union them together. Hence, + this request dispenses with the ordering information. + + Errors: IDChoice + +CreateRegionFromBitmap + + region: REGION + bitmap: PIXMAP + + Creates a region initialized to the set of 'one' pixels in bitmap + (which must be depth 1, else Match error). + + Errors: Pixmap, IDChoice, Match + +CreateRegionFromWindow + + window: Window + kind: WINDOW_REGION_KIND + region: Region + + Creates a region initialized to the specified window region. See the + Shape extension for the definition of Bounding and Clip regions. + + Errors: Window, IDChoice, Value + +CreateRegionFromGC + + gc: GContext + region: Region + + Creates a region initialized from the clip list of the specified + GContext. + + Errors: GContext, IDChoice + +CreateRegionFromPicture + + picture: Picture + region: Region + + + Creates a region initialized from the clip list of the specified + Picture. + + Errors: Picture, IDChoice + +DestroyRegion + + region: Region + + Destroys the specified region. + + Errors: Region + +SetRegion + + region: Region + rects: LISTofRECTANGLE + + This replaces the current contents of region with the region formed + by the union of rects. + +CopyRegion + source: Region + destination: Region + + This replaces the contents of destination with the contents of + source. + +UnionRegion +IntersectRegion +SubtractRegion + + source1: Region + source2: Region + destination: Region + + Combines source1 and source2, placing the result in destination. + Destination may be the same as either source1 or source2. + + Errors: Region, Value + +InvertRegion + + source: Region + bounds: RECTANGLE + destination: Region + + The source region is subtracted from the region specified by + bounds. The result is placed in destination, replacing its contents. + + Errors: Region + +TranslateRegion + + region: Region + dx, dy: INT16 + + The region is translated by dx, dy in place. + + Errors: Region + +RegionExtents + + source: Region + destination: Region + + The extents of the source region are placed in the destination + +FetchRegion + + region: Region + -> + extents: RECTANGLE + rectangles: LISTofRECTANGLE + + The region is returned as a list of rectangles in YX-banded order. + + Errors: Region + +SetGCClipRegion + + gc: GCONTEXT + clip-x-origin, clip-y-origin: INT16 + region: Region or None + + This request changes clip-mask in gc to the specified region and + sets the clip origin. Output will be clipped to remain contained + within the region. The clip origin is interpreted relative to the + origin of whatever destination drawable is specified in a graphics + request. The region is interpreted relative to the clip origin. + Future changes to region have no effect on the gc clip-mask. + + Errors: GContext, Region + +SetWindowShapeRegion + + dest: Window + destKind: SHAPE_KIND + xOff, yOff: INT16 + region: Region or None + + This request sets the specified (by destKind) Shape extension region + of the window to region, offset by xOff and yOff. Future changes to + region have no effect on the window shape. + + Errors: Window, Value, Region + +SetPictureClipRegion + + picture: Picture + clip-x-origin, clip-y-origin: INT16 + region: Region or None + + This request changes clip-mask in picture to the specified region + and sets the clip origin. Input and output will be clipped to + remain contained within the region. The clip origin is interpreted + relative to the origin of the drawable associated with picture. The + region is interpreted relative to the clip origin. Future changes + to region have no effect on the picture clip-mask. + + Errors: Picture, Region + +9. Cursor Names + +Attaching names to cursors permits some abstract semantic content to be +associated with specific cursor images. Reflecting those names back to +applications allows that semantic content to be related to the user through +non-visual means. + +9.1 Events + +CursorNotify + + subtype: CURSOREVENT + window: Window + cursor-serial: CARD32 + timestamp: Timestamp + name: Atom or None + + In Version 2 of the XFIXES protocol, this event adds the atom + of any name associated with the current cursor (else None). + +9.2 Requests + +SetCursorName + + cursor: CURSOR + name: LISTofCARD8 + + This request interns name as an atom and sets that atom as the name + of cursor. + + Errors: Cursor + +GetCursorName + + cursor: CURSOR + -> + atom: ATOM or None + name: LISTofCARD8 + + This request returns the name and atom of cursor. If no name is + set, atom is None and name is empty. + + Errors: Cursor + +GetCursorImageAndName + + -> + + x: INT16 + y: INT16 + width: CARD16 + height: CARD16 + x-hot: CARD16 + y-hot: CARD16 + cursor-serial: CARD32 + cursor-atom: ATOM + cursor-name: LISTofCARD8 + cursor-image: LISTofCARD32 + + This is similar to GetCursorImage except for including both + the atom and name of the current cursor. + +ChangeCursor + + source, destination: CURSOR + + This request replaces all references to the destination with a + reference to source. Any existing uses of the destination cursor + object will now show the source cursor image. + +ChangeCursorByName + + src: CURSOR + name: LISTofCARD8 + + This request replaces the contents of all cursors with the specified + name with the src cursor. + +************* XFIXES VERSION 3 OR BETTER *********** + +10. Region Expansion + +This update provides another operation on the region objects defined in +Section 8 of this document. + +10.1 Requests + +ExpandRegion + source: REGION + destination: REGION + left, right, top, bottom: CARD16 + + Creates destination region containing the area specified by + expanding each rectangle in the source region by the specified + number of pixels to the left, right, top and bottom. + +************* XFIXES VERSION 4 OR BETTER *********** + +11. Cursor Visibility + +Composite managers may want to render the cursor themselves instead of +relying on the X server sprite drawing, this provides a way for them to +do so without getting a double cursor image. + +11.1 Requests + +HideCursor + + window: WINDOW + + A client sends this request to indicate that it wants the + cursor image to be hidden (i.e. to not be displayed) when + the sprite is inside the specified window, or one of its + subwindows. If the sprite is inside a window for which one + or more active clients have requested cursor hiding then the + cursor image will not be displayed. + + Note that even though cursor hiding causes the cursor image + to be invisible, CursorNotify events will still be sent + normally, as if the cursor image were visible. + + If, during a grab, one or more active clients have requested + cursor hiding for grab window, or one of its ancestors, the + cursor image of the grab cursor will not be displayed during + the lifetime of that grab. + + When a client with outstanding cursor hiding requests + terminates its connection these requests will be deleted. + + Servers supporting the X Input Extension Version 2.0 or higher hide + all visible cursors in response to a HideCursor request. If a master + pointer is created while the cursors are hidden, this master pointer's + cursor will be hidden as well. + +ShowCursor + + window: WINDOW + + A client sends this request to indicate that it wants the + cursor image to be displayed when the sprite is inside the + specified window, or one of its subwindows. If the sprite + is inside a window for which no active clients have requested + cursor hiding then the cursor image for that window will be + displayed. In other words, if a client calls HideCursor for + a specified window, or window subtree, this request reverses + the effects of the HideCursor request. + + If the client has made no outstanding HideCursor requests + a BadMatch error is generated. + + Servers supporting the X Input Extension Version 2.0 or higher show + all visible cursors in response to a ShowCursor request. + +99. Future compatibility + +This extension is not expected to remain fixed. Future changes will +strive to remain compatible if at all possible. The X server will always +support version 1 of the extension protocol if requested by a client. + +Additions to the protocol will always by marked by minor version number +changes so that applications will be able to detect what requests are +supported. |