diff options
Diffstat (limited to 'protocol')
-rw-r--r-- | protocol | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/protocol b/protocol new file mode 100644 index 0000000..70fc146 --- /dev/null +++ b/protocol @@ -0,0 +1,198 @@ + The XFIXES Extension + Version 1.0 + 2002-11-30 + Keith Packard + keithp@xfree86.org + +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 + +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 + incompatibilities in existing functionality, minor version + changes introduce only backward compatible changes. It is + the clients responsibility to ensure that the server supports + a version which is compatible with its expectations. + +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 permits these windows to remain unmapped instead of being +remapped. + +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. + + SELECTIONEVENT { SetSelectionOwner, + SelectionWindowDestroy, + SelectionClientClose } + +SelectionNotify + + subtype: SELECTIONEVENT + window: Window + owner: Window + selection: Atom + timestamp: Timestamp + selection-timestamp: Timestamp + +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. + + CURSOREVENT { DisplayCursor } + +CursorNotify + + subtype: CURSOREVENT + window: Window + cursor-serial: CARD32 + timestamp: Timestamp + +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. + +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. + +8. 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. |