From 0afb1fdaa1ddad7c71dcf5318f3f022ccb3ebba2 Mon Sep 17 00:00:00 2001 From: Eric Anholt Date: Tue, 9 Jan 2007 09:43:50 -0800 Subject: Move fixes protocol description to the new canonical location/name. --- Makefile.am | 4 +- fixesproto.txt | 494 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ protocol | 494 --------------------------------------------------------- 3 files changed, 496 insertions(+), 496 deletions(-) create mode 100644 fixesproto.txt delete mode 100644 protocol diff --git a/Makefile.am b/Makefile.am index 953e62a..44a88a9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -26,8 +26,8 @@ fixes_HEADERS = \ xfixesproto.h \ xfixeswire.h -fixesdocdir = $(datadir)/doc/XFixes -fixesdoc_DATA = protocol +fixesdocdir = $(datadir)/doc/$(PACKAGE) +fixesdoc_DATA = fixesproto.txt pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = fixesproto.pc 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. diff --git a/protocol b/protocol deleted file mode 100644 index cdea081..0000000 --- a/protocol +++ /dev/null @@ -1,494 +0,0 @@ - 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. -- cgit v1.2.3