Move fixes protocol description to the new canonical location/name.

1 files changed, 494 insertions, 0 deletions

diff --git a/fixesproto.txt b/fixesproto.txt
new file mode 100644
index 0000000..cdea081
--- /dev/null
+++ b/fixesproto.txt
@@ -0,0 +1,494 @@
+                        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.