652 lines
19 KiB
Plaintext
652 lines
19 KiB
Plaintext
The XFIXES Extension
|
|
Version 5.0
|
|
Document Revision 1
|
|
2010-11-15
|
|
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, and for pointer barriers
|
|
|
|
+ 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-image: LISTofCARD32
|
|
cursor-name: LISTofCARD8
|
|
|
|
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 on the same screen as the specified window.
|
|
The sprite will be hidden if one or more clients have called
|
|
HideCursor and not ShowCursor.
|
|
|
|
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.
|
|
|
|
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 on the same
|
|
screen as the specified window. The sprite will be hidden
|
|
if one or more clients have called HideCursor and not ShowCursor.
|
|
|
|
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.
|
|
|
|
************* XFIXES VERSION 5 OR BETTER ***********
|
|
|
|
12. Pointer Barriers
|
|
|
|
Compositing managers and desktop environments may have UI elements in
|
|
particular screen locations such that for a single-headed display they
|
|
correspond to easy targets according to Fitt's Law, for example, the top
|
|
left corner. For a multi-headed environment these corners should still be
|
|
semi-impermeable. Pointer barriers allow the application to define
|
|
additional constraint on cursor motion so that these areas behave as
|
|
expected even in the face of multiple displays.
|
|
|
|
Absolute positioning devices like touchscreens do not obey pointer barriers.
|
|
There's no advantage to target acquisition to do so, since on a touchscreen
|
|
all points are in some sense equally large, whereas for a relative
|
|
positioning device the edges and corners are infinitely large.
|
|
|
|
WarpPointer and similar requests do not obey pointer barriers, for
|
|
essentially the same reason.
|
|
|
|
12.1 Types
|
|
|
|
BARRIER: XID
|
|
|
|
BarrierDirections
|
|
|
|
BarrierPositiveX: 1 << 0
|
|
BarrierPositiveY: 1 << 1
|
|
BarrierNegativeX: 1 << 2
|
|
BarrierNegativeY: 1 << 3
|
|
|
|
12.2 Errors
|
|
|
|
Barrier
|
|
|
|
12.3 Requests
|
|
|
|
CreatePointerBarrier
|
|
|
|
barrier: BARRIER
|
|
window: Window
|
|
x1, y2, x2, y2: INT16
|
|
directions: CARD32
|
|
devices: LISTofDEVICEID
|
|
|
|
Creates a pointer barrier along the line specified by the given
|
|
coordinates on the screen associated with the given window. The
|
|
barrier has no spatial extent; it is simply a line along the left
|
|
or top edge of the specified pixels. Barrier coordinates are in
|
|
screen space.
|
|
|
|
The coordinates must be axis aligned, either x1 == x2, or
|
|
y1 == y2, but not both. The varying coordinates may be specified
|
|
in any order. For x1 == x2, either y1 > y2 or y1 < y2 is valid.
|
|
If the coordinates are not valid BadValue is generated.
|
|
|
|
Motion is allowed through the barrier in the directions specified:
|
|
setting the BarrierPositiveX bit allows travel through the barrier
|
|
in the positive X direction, etc. Nonsensical values (forbidding Y
|
|
axis travel through a vertical barrier, for example) and excess set
|
|
bits are ignored.
|
|
|
|
If the server supports the X Input Extension version 2 or higher,
|
|
the devices element names a set of master device to apply the
|
|
barrier to. If XIAllDevices or XIAllMasterDevices are given, the
|
|
barrier applies to all master devices. If a slave device is named,
|
|
BadDevice is generated; this does not apply to slave devices named
|
|
implicitly by XIAllDevices. Naming a device multiple times is
|
|
legal, and is treated as though it were named only once. If a
|
|
device is removed, the barrier continues to apply to the remaining
|
|
devices, but will not apply to any future device with the same ID
|
|
as the removed device. Nothing special happens when all matching
|
|
devices are removed; barriers must be explicitly destroyed.
|
|
|
|
Errors: IDChoice, Window, Value, Device
|
|
|
|
DestroyPointerBarrier
|
|
|
|
barrier: BARRIER
|
|
|
|
Destroys the named barrier.
|
|
|
|
Errors: Barrier
|
|
|
|
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.
|