1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/fixesproto.txt	Fri Jan 29 10:23:08 2016 +0200
     1.3 @@ -0,0 +1,577 @@
     1.4 +                        The XFIXES Extension
     1.5 +			    Version 4.0
     1.6 +			 Document Revision 2
     1.7 +			     2006-12-14
     1.8 +			    Keith Packard
     1.9 +			  keithp@keithp.com
    1.10 +
    1.11 +1. Introduction
    1.12 +
    1.13 +X applications have often needed to work around various shortcomings in the
    1.14 +core X window system.  This extension is designed to provide the minimal
    1.15 +server-side support necessary to eliminate problems caused by these
    1.16 +workarounds.
    1.17 +
    1.18 +2. Acknowledgements
    1.19 +
    1.20 +This extension is a direct result of requests made by application
    1.21 +developers, in particular,
    1.22 +
    1.23 + +	Owen Taylor for describing the issues raised with the XEMBED
    1.24 + 	mechanisms and SaveSet processing and his initial extension
    1.25 +	to handle this issue.
    1.26 +
    1.27 + +	Bill Haneman for the design for cursor image tracking.
    1.28 +
    1.29 + +	Havoc Pennington 
    1.30 +
    1.31 + +	Fredrik Höglund for cursor names
    1.32 +
    1.33 + +	Deron Johnson for cursor visibility
    1.34 +
    1.35 +3. Basic Premise
    1.36 +
    1.37 +Requests in this extension may seem to wander all over the map of X server
    1.38 +capabilities, but they are tied by a simple rule -- resolving issues raised
    1.39 +by application interaction with core protocol mechanisms that cannot be
    1.40 +adequately worked around on the client side of the wire.
    1.41 +
    1.42 +4. Extension initialization
    1.43 +
    1.44 +The client must negotiate the version of the extension before executing
    1.45 +extension requests.  Behavior of the server is undefined otherwise.
    1.46 +
    1.47 +QueryVersion
    1.48 +
    1.49 +	client-major-version:		CARD32
    1.50 +	client-minor-version:		CARD32
    1.51 +
    1.52 +	->
    1.53 +
    1.54 +	major-version:			CARD32
    1.55 +	minor-version:			CARD32
    1.56 +
    1.57 +	The client sends the highest supported version to the server and
    1.58 +	the server sends the highest version it supports, but no higher than
    1.59 +	the requested version.  Major versions changes can introduce
    1.60 +	new requests, minor version changes introduce only adjustments to
    1.61 +	existing requests or backward compatible changes.  It is
    1.62 +	the clients responsibility to ensure that the server supports
    1.63 +	a version which is compatible with its expectations.
    1.64 +
    1.65 +************* XFIXES VERSION 1 OR BETTER ***********
    1.66 +
    1.67 +5. Save Set processing changes
    1.68 +
    1.69 +Embedding one application within another provides a way of unifying
    1.70 +disparate documents and views within a single framework.  From the X
    1.71 +protocol perspective, this appears similar to nested window managers; the
    1.72 +embedding application "manages" the embedded windows much as a window
    1.73 +manager does for top-level windows.  To protect the embedded application
    1.74 +from embedding application failure, it is reasonable to use the core SaveSet
    1.75 +mechanism so that embedding application failure causes embedded windows to
    1.76 +be preserved instead of destroyed.
    1.77 +
    1.78 +The core save set mechanism defines the target for each save set member
    1.79 +window as the nearest enclosing window not owned by the terminating client.
    1.80 +For embedding applications, this nearest window is usually the window
    1.81 +manager frame.  The problem here is that the window manager will not
    1.82 +generally expect to receive and correctly manage new windows appearing within
    1.83 +that window by the save set mechanism, and will instead destroy the frame
    1.84 +window in response to the client window destruction.  This causes the
    1.85 +embedded window to be destroyed.
    1.86 +
    1.87 +An easy fix for this problem is to change the target of the save set member
    1.88 +to a window which won't be affected by the underlying window destruction.
    1.89 +XFIXES chooses the root window as the target.
    1.90 +
    1.91 +Having embedded windows suddenly appear at the top level can confuse users,
    1.92 +so XFIXES also lets the client select whether the window should end up
    1.93 +unmapped after the save set processing instead of unconditionally making
    1.94 +them be mapped.
    1.95 +
    1.96 +5.1 Requests
    1.97 +
    1.98 +ChangeSaveSet
    1.99 +
   1.100 +		window:				Window
   1.101 +		mode:				{ Insert, Delete }
   1.102 +		target:				{ Nearest, Root }
   1.103 +		map:				{ Map, Unmap }
   1.104 +
   1.105 +	ChangeSaveSet is an extension of the core protocol ChangeSaveSet
   1.106 +	request.  As in that request, mode specifies whether the indicated
   1.107 +	window is inserted or deleted from the save-set.  Target specifies
   1.108 +	whether the window is reparented to the nearest non-client window as
   1.109 +	in the core protocol, or reparented to the root window.  Map
   1.110 +	specifies whether the window is mapped as in the core protocol or
   1.111 +	unmapped.
   1.112 +
   1.113 +6. Selection Tracking
   1.114 +
   1.115 +Applications wishing to monitor the contents of current selections must
   1.116 +poll for selection changes.  XFIXES improves this by providing an event
   1.117 +delivered whenever the selection ownership changes.
   1.118 +
   1.119 +6.1 Types
   1.120 +
   1.121 +	SELECTIONEVENT			{ SetSelectionOwner,
   1.122 +					  SelectionWindowDestroy,
   1.123 +					  SelectionClientClose }
   1.124 +
   1.125 +6.1 Events
   1.126 +
   1.127 +SelectionNotify
   1.128 +
   1.129 +	subtype:			SELECTIONEVENT
   1.130 +	window:				Window
   1.131 +	owner:				Window
   1.132 +	selection:			Atom
   1.133 +	timestamp:			Timestamp
   1.134 +	selection-timestamp:		Timestamp
   1.135 +
   1.136 +6.2 Requests
   1.137 +
   1.138 +SelectSelectionInput
   1.139 +
   1.140 +		window:				Window
   1.141 +		selection:			Atom
   1.142 +		event-mask:			SETofSELECTIONEVENT
   1.143 +
   1.144 +	Selects for events to be delivered to window when various causes of
   1.145 +	ownership of selection occur.  Subtype indicates the cause of the
   1.146 +	selection ownership change.  Owner is set to the current selection
   1.147 +	owner, or None.  Timestamp indicates the time the event was
   1.148 +	generated while selection-timestamp indicates the timestamp used to
   1.149 +	own the selection.
   1.150 +
   1.151 +7. Cursor Image Monitoring
   1.152 +
   1.153 +Mirroring the screen contents is easily done with the core protocol or VNC
   1.154 +addons, except for the current cursor image.  There is no way using the core
   1.155 +protocol to discover which cursor image is currently displayed.  The
   1.156 +cursor image often contains significant semantic content about the user
   1.157 +interface.  XFIXES provides a simple mechanism to discover when the cursor
   1.158 +image changes and to fetch the current cursor image.
   1.159 +
   1.160 +As the current cursor may or may not have any XID associated with it, there
   1.161 +is no stable name available.  Instead, XFIXES returns only the image of the
   1.162 +current cursor and provides a way to identify cursor images to avoid
   1.163 +refetching the image each time it changes to a previously seen cursor.
   1.164 +
   1.165 +7.1 Types
   1.166 +	CURSOREVENT			{ DisplayCursor }
   1.167 +
   1.168 +7.2 Events
   1.169 +
   1.170 +CursorNotify
   1.171 +
   1.172 +	subtype:		CURSOREVENT
   1.173 +	window:			Window
   1.174 +	cursor-serial:		CARD32
   1.175 +	timestamp:		Timestamp
   1.176 +	name:			Atom		(Version 2 only)
   1.177 +
   1.178 +7.3 Requests
   1.179 +
   1.180 +SelectCursorInput
   1.181 +
   1.182 +		window:			Window
   1.183 +		event-mask:		SETofCURSOREVENT
   1.184 +
   1.185 +	This request directs cursor change events to the named window.
   1.186 +	Events will be delivered irrespective of the screen on which they
   1.187 +	occur.  Subtype indicates the cause of the cursor image change
   1.188 +	(there is only one subtype at present).  Cursor-serial is a number
   1.189 +	assigned to the cursor image which identifies the image.  Cursors
   1.190 +	with different serial numbers may have different images.  Timestamp
   1.191 +	is the time of the cursor change.
   1.192 +
   1.193 +	Servers supporting the X Input Extension Version 2.0 or higher only
   1.194 +	notify the clients of cursor change events for the ClientPointer, not
   1.195 +	of any other master pointer (see Section 4.4. in the XI2 protocol
   1.196 +	specificiation).
   1.197 +
   1.198 +GetCursorImage
   1.199 +
   1.200 +		->
   1.201 +
   1.202 +		x:			INT16
   1.203 +		y:			INT16
   1.204 +		width:			CARD16
   1.205 +		height:			CARD16
   1.206 +		x-hot:			CARD16
   1.207 +		y-hot:			CARD16
   1.208 +		cursor-serial:		CARD32
   1.209 +		cursor-image:		LISTofCARD32
   1.210 +
   1.211 +	GetCursorImage returns the image of the current cursor.  X and y are
   1.212 +	the current cursor position.  Width and height are the size of the
   1.213 +	cursor image.  X-hot and y-hot mark the hotspot within the cursor
   1.214 +	image.  Cursor-serial provides the number assigned to this cursor
   1.215 +	image, this same serial number will be reported in a CursorNotify
   1.216 +	event if this cursor image is redisplayed in the future.
   1.217 +
   1.218 +	The cursor image itself is returned as a single image at 32 bits per
   1.219 +	pixel with 8 bits of alpha in the most significant 8 bits of the
   1.220 +	pixel followed by 8 bits each of red, green and finally 8 bits of
   1.221 +	blue in the least significant 8 bits.  The color components are
   1.222 +	pre-multiplied with the alpha component.
   1.223 +	
   1.224 +************* XFIXES VERSION 2 OR BETTER ***********
   1.225 +
   1.226 +8. Region Objects
   1.227 +
   1.228 +The core protocol doesn't expose regions as a primitive object and this
   1.229 +makes many operations more complicated than they really need to be.  Adding
   1.230 +region objects simplifies expose handling, the Shape extension and other
   1.231 +operations. These operations are also designed to support a separate
   1.232 +extension, the X Damage Extension.
   1.233 +
   1.234 +8.1 Types
   1.235 +
   1.236 +	Region:				XID
   1.237 +	WINDOW_REGION_KIND:		{ Bounding, Clip }
   1.238 +	
   1.239 +8.2 Errors
   1.240 +
   1.241 +	Region				The specified region is invalid
   1.242 +
   1.243 +8.3 Requests
   1.244 +
   1.245 +CreateRegion
   1.246 +
   1.247 +		region:				REGION
   1.248 +		rects:				LISTofRECTANGLE
   1.249 +
   1.250 +	Creates a region initialized to the specified list of rectangles.
   1.251 +	The rectangles may be specified in any order, their union becomes
   1.252 +	the region.  The core protocol allows applications to specify an
   1.253 +	order for the rectangles, but it turns out to be just as hard to
   1.254 +	verify the rectangles are actually in that order as it is to simply
   1.255 +	ignore the ordering information and union them together.  Hence,
   1.256 +	this request dispenses with the ordering information.
   1.257 +
   1.258 +	Errors: IDChoice
   1.259 +
   1.260 +CreateRegionFromBitmap
   1.261 +
   1.262 +		region:				REGION
   1.263 +		bitmap:				PIXMAP
   1.264 +
   1.265 +	Creates a region initialized to the set of 'one' pixels in bitmap
   1.266 +	(which must be depth 1, else Match error).
   1.267 +
   1.268 +	Errors: Pixmap, IDChoice, Match
   1.269 +
   1.270 +CreateRegionFromWindow
   1.271 +
   1.272 +		window:				Window
   1.273 +		kind:				WINDOW_REGION_KIND
   1.274 +		region:				Region
   1.275 +
   1.276 +	Creates a region initialized to the specified window region.  See the
   1.277 +	Shape extension for the definition of Bounding and Clip regions.
   1.278 +
   1.279 +	Errors: Window, IDChoice, Value
   1.280 +
   1.281 +CreateRegionFromGC
   1.282 +
   1.283 +		gc:				GContext
   1.284 +		region:				Region
   1.285 +
   1.286 +	Creates a region initialized from the clip list of the specified
   1.287 +	GContext.
   1.288 +
   1.289 +	Errors: GContext, IDChoice
   1.290 +
   1.291 +CreateRegionFromPicture
   1.292 +
   1.293 +		picture:			Picture
   1.294 +		region:				Region
   1.295 +
   1.296 +
   1.297 +	Creates a region initialized from the clip list of the specified
   1.298 +	Picture.
   1.299 +
   1.300 +	Errors: Picture, IDChoice
   1.301 +
   1.302 +DestroyRegion
   1.303 +
   1.304 +		region:				Region
   1.305 +
   1.306 +	Destroys the specified region.
   1.307 +
   1.308 +	Errors: Region
   1.309 +
   1.310 +SetRegion
   1.311 +
   1.312 +		region:				Region
   1.313 +		rects:				LISTofRECTANGLE
   1.314 +
   1.315 +	This replaces the current contents of region with the region formed
   1.316 +	by the union of rects.
   1.317 +
   1.318 +CopyRegion
   1.319 +		source:				Region
   1.320 +		destination:			Region
   1.321 +
   1.322 +	This replaces the contents of destination with the contents of 
   1.323 +	source.
   1.324 +
   1.325 +UnionRegion
   1.326 +IntersectRegion
   1.327 +SubtractRegion
   1.328 +
   1.329 +		source1:			Region
   1.330 +		source2:			Region
   1.331 +		destination:			Region
   1.332 +	
   1.333 +	Combines source1 and source2, placing the result in destination.
   1.334 +	Destination may be the same as either source1 or source2.
   1.335 +
   1.336 +	Errors: Region, Value
   1.337 +	
   1.338 +InvertRegion
   1.339 +
   1.340 +		source:				Region
   1.341 +		bounds:				RECTANGLE
   1.342 +		destination:			Region
   1.343 +	
   1.344 +	The source region is subtracted from the region specified by
   1.345 +	bounds.  The result is placed in destination, replacing its contents.
   1.346 +
   1.347 +	Errors: Region
   1.348 +	
   1.349 +TranslateRegion
   1.350 +
   1.351 +		region:				Region
   1.352 +		dx, dy:				INT16
   1.353 +
   1.354 +	The region is translated by dx, dy in place.
   1.355 +
   1.356 +	Errors: Region
   1.357 +
   1.358 +RegionExtents
   1.359 +
   1.360 +		source:				Region
   1.361 +		destination:			Region
   1.362 +
   1.363 +	The extents of the source region are placed in the destination
   1.364 +
   1.365 +FetchRegion
   1.366 +
   1.367 +		region:				Region
   1.368 +		->
   1.369 +		extents:			RECTANGLE
   1.370 +		rectangles:			LISTofRECTANGLE
   1.371 +
   1.372 +	The region is returned as a list of rectangles in YX-banded order.
   1.373 +
   1.374 +	Errors: Region
   1.375 +
   1.376 +SetGCClipRegion
   1.377 +
   1.378 +		gc:				GCONTEXT
   1.379 +		clip-x-origin, clip-y-origin:	INT16
   1.380 +		region:				Region or None
   1.381 +
   1.382 +	This request changes clip-mask in gc to the specified region and
   1.383 +	sets the clip origin.  Output will be clipped to remain contained
   1.384 +	within the region.  The clip origin is interpreted relative to the
   1.385 +	origin of whatever destination drawable is specified in a graphics
   1.386 +	request.  The region is interpreted relative to the clip origin.
   1.387 +	Future changes to region have no effect on the gc clip-mask.
   1.388 +
   1.389 +	Errors: GContext, Region
   1.390 +
   1.391 +SetWindowShapeRegion
   1.392 +
   1.393 +		dest:				Window
   1.394 +		destKind:			SHAPE_KIND
   1.395 +		xOff, yOff:			INT16
   1.396 +		region:				Region or None
   1.397 +
   1.398 +	This request sets the specified (by destKind) Shape extension region
   1.399 +	of the window to region, offset by xOff and yOff.   Future changes to
   1.400 +	region have no effect on the window shape.
   1.401 +
   1.402 +	Errors: Window, Value, Region
   1.403 +
   1.404 +SetPictureClipRegion
   1.405 +
   1.406 +		picture:			Picture
   1.407 +		clip-x-origin, clip-y-origin:	INT16
   1.408 +		region:				Region or None
   1.409 +
   1.410 +	This request changes clip-mask in picture to the specified region
   1.411 +	and sets the clip origin.  Input and output will be clipped to
   1.412 +	remain contained within the region.  The clip origin is interpreted
   1.413 +	relative to the origin of the drawable associated with picture.  The
   1.414 +	region is interpreted relative to the clip origin.  Future changes
   1.415 +	to region have no effect on the picture clip-mask.
   1.416 +
   1.417 +	Errors: Picture, Region
   1.418 +
   1.419 +9. Cursor Names
   1.420 +
   1.421 +Attaching names to cursors permits some abstract semantic content to be
   1.422 +associated with specific cursor images.  Reflecting those names back to
   1.423 +applications allows that semantic content to be related to the user through
   1.424 +non-visual means.
   1.425 +
   1.426 +9.1 Events
   1.427 +
   1.428 +CursorNotify
   1.429 +
   1.430 +		subtype:		CURSOREVENT
   1.431 +		window:			Window
   1.432 +		cursor-serial:		CARD32
   1.433 +		timestamp:		Timestamp
   1.434 +		name:			Atom or None
   1.435 +	
   1.436 +	In Version 2 of the XFIXES protocol, this event adds the atom
   1.437 +	of any name associated with the current cursor (else None).
   1.438 +
   1.439 +9.2 Requests
   1.440 +
   1.441 +SetCursorName
   1.442 +
   1.443 +		cursor:			CURSOR
   1.444 +		name:			LISTofCARD8
   1.445 +
   1.446 +	This request interns name as an atom and sets that atom as the name
   1.447 +	of cursor.
   1.448 +
   1.449 +	Errors: Cursor
   1.450 +
   1.451 +GetCursorName
   1.452 +
   1.453 +		cursor:			CURSOR
   1.454 +		->
   1.455 +		atom:			ATOM or None
   1.456 +		name:			LISTofCARD8
   1.457 +
   1.458 +	This request returns the name and atom of cursor.  If no name is
   1.459 +	set, atom is None and name is empty.
   1.460 +
   1.461 +	Errors: Cursor
   1.462 +
   1.463 +GetCursorImageAndName
   1.464 +
   1.465 +		->
   1.466 +
   1.467 +		x:			INT16
   1.468 +		y:			INT16
   1.469 +		width:			CARD16
   1.470 +		height:			CARD16
   1.471 +		x-hot:			CARD16
   1.472 +		y-hot:			CARD16
   1.473 +		cursor-serial:		CARD32
   1.474 +		cursor-atom:		ATOM
   1.475 +		cursor-name:		LISTofCARD8
   1.476 +		cursor-image:		LISTofCARD32
   1.477 +
   1.478 +	This is similar to GetCursorImage except for including both
   1.479 +	the atom and name of the current cursor.
   1.480 +
   1.481 +ChangeCursor
   1.482 +
   1.483 +		source, destination:	CURSOR
   1.484 +
   1.485 +	This request replaces all references to the destination with a
   1.486 +	reference to source.  Any existing uses of the destination cursor
   1.487 +	object will now show the source cursor image.
   1.488 +
   1.489 +ChangeCursorByName
   1.490 +
   1.491 +		src:			CURSOR
   1.492 +		name:			LISTofCARD8
   1.493 +
   1.494 +	This request replaces the contents of all cursors with the specified
   1.495 +	name with the src cursor.
   1.496 +
   1.497 +************* XFIXES VERSION 3 OR BETTER ***********
   1.498 +
   1.499 +10. Region Expansion
   1.500 +
   1.501 +This update provides another operation on the region objects defined in
   1.502 +Section 8 of this document.
   1.503 +
   1.504 +10.1 Requests
   1.505 +
   1.506 +ExpandRegion
   1.507 +		source:				REGION
   1.508 +		destination:			REGION
   1.509 +		left, right, top, bottom:	CARD16
   1.510 +
   1.511 +	Creates destination region containing the area specified by
   1.512 +	expanding each rectangle in the source region by the specified
   1.513 +	number of pixels to the left, right, top and bottom.
   1.514 +
   1.515 +************* XFIXES VERSION 4 OR BETTER ***********
   1.516 +
   1.517 +11. Cursor Visibility
   1.518 +
   1.519 +Composite managers may want to render the cursor themselves instead of
   1.520 +relying on the X server sprite drawing, this provides a way for them to
   1.521 +do so without getting a double cursor image.
   1.522 +
   1.523 +11.1 Requests
   1.524 +
   1.525 +HideCursor
   1.526 +
   1.527 +		window:			WINDOW
   1.528 +
   1.529 +	A client sends this request to indicate that it wants the
   1.530 +	cursor image to be hidden (i.e. to not be displayed) when
   1.531 +	the sprite is inside the specified window, or one of its
   1.532 +	subwindows. If the sprite is inside a window for which one
   1.533 +	or more active clients have requested cursor hiding then the
   1.534 +	cursor image will not be displayed.
   1.535 +
   1.536 +	Note that even though cursor hiding causes the cursor image
   1.537 +	to be invisible, CursorNotify events will still be sent
   1.538 +	normally, as if the cursor image were visible.
   1.539 +
   1.540 +	If, during a grab, one or more active clients have requested
   1.541 +	cursor hiding for grab window, or one of its ancestors, the
   1.542 +	cursor image of the grab cursor will not be displayed during
   1.543 +	the lifetime of that grab.
   1.544 +
   1.545 +	When a client with outstanding cursor hiding requests
   1.546 +	terminates its connection these requests will be deleted.
   1.547 +
   1.548 +	Servers supporting the X Input Extension Version 2.0 or higher hide
   1.549 +	all visible cursors in response to a HideCursor request. If a master
   1.550 +	pointer is created while the cursors are hidden, this master pointer's
   1.551 +	cursor will be hidden as well.
   1.552 +
   1.553 +ShowCursor
   1.554 +
   1.555 +		window:			WINDOW
   1.556 +
   1.557 +	A client sends this request to indicate that it wants the
   1.558 +	cursor image to be displayed when the sprite is inside the
   1.559 +	specified window, or one of its subwindows. If the sprite
   1.560 +	is inside a window for which no active clients have requested
   1.561 +	cursor hiding then the cursor image for that window will be
   1.562 +	displayed. In other words, if a client calls HideCursor for
   1.563 +	a specified window, or window subtree, this request reverses
   1.564 +	the effects of the HideCursor request.
   1.565 +
   1.566 +	If the client has made no outstanding HideCursor requests
   1.567 +	a BadMatch error is generated.
   1.568 +
   1.569 +	Servers supporting the X Input Extension Version 2.0 or higher show
   1.570 +	all visible cursors in response to a ShowCursor request.
   1.571 +
   1.572 +99. Future compatibility
   1.573 +
   1.574 +This extension is not expected to remain fixed.  Future changes will
   1.575 +strive to remain compatible if at all possible.  The X server will always
   1.576 +support version 1 of the extension protocol if requested by a client.
   1.577 +
   1.578 +Additions to the protocol will always by marked by minor version number
   1.579 +changes so that applications will be able to detect what requests are
   1.580 +supported.