xenocara/doc/xorg-docs/specs/Fixes/protocol

                        The XFIXES Extension
			    Version 2.0
			 Document Revision 1
			     2003-11-20
			    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

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.

************* 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 permits these windows to remain unmapped instead of being
remapped.

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.

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 clp origin.  Output will be clippped 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.
		
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.