diff options
Diffstat (limited to 'libXext/specs/shapelib.xml')
| -rw-r--r-- | libXext/specs/shapelib.xml | 1154 |
1 files changed, 577 insertions, 577 deletions
diff --git a/libXext/specs/shapelib.xml b/libXext/specs/shapelib.xml index 1d89cf1e1..a357da40b 100644 --- a/libXext/specs/shapelib.xml +++ b/libXext/specs/shapelib.xml @@ -1,577 +1,577 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-
-<!-- lifted from troff+ms+XMan by doclifter -->
-<book id="shapelib">
-
-<bookinfo>
- <title>X Nonrectangular Window Shape Extension Library</title>
- <subtitle>X Consortium Standard</subtitle>
- <releaseinfo>X Version 11, Release 6.4</releaseinfo>
- <authorgroup>
- <author>
- <firstname>Keith</firstname><surname>Packard</surname>
- </author>
- </authorgroup>
- <corpname>MIT X Consortium</corpname>
- <copyright><year>1989</year><holder>X Consortium</holder></copyright>
- <releaseinfo>Version 1.0</releaseinfo>
- <affiliation><orgname>MIT X Consortium</orgname></affiliation>
- <productnumber>X Version 11, Release 6.4</productnumber>
-
-<legalnotice>
-
-<para>
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files
-(the “Software”), to deal in the Software without restriction,
-including without limitation the rights to use, copy, modify, merge,
-publish, distribute, sublicense, and/or sell copies of the Software, and
-to permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-</para>
-
-<para>
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-</para>
-
-<para>
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY
-KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-</para>
-
-<para>
-Except as contained in this notice, the name of the X Consortium shall not be
-used in advertising or otherwise to promote the sale, use or other dealings
-in this Software without prior written authorization from the X Consortium.
-</para>
-</legalnotice>
-</bookinfo>
-
-<chapter id='overview'>
-<title>Overview</title>
-
-<para>This extension provides arbitrary window and border shapes within
-the X11 protocol.
-</para>
-
-<para>
-The restriction of rectangular windows within the X protocol is a significant
-limitation in the implementation of many styles of user interface. For
-example, many transient windows would like to display a
-“drop shadow” to give the illusion of 3 dimensions. As
-another example, some user interface style guides call for buttons with
-rounded corners; the full simulation of a nonrectangular shape,
-particularly with respect to event distribution and cursor shape, is not
-possible within the core X protocol. As a final example, round clocks
-and nonrectangular icons are desirable visual addition to the desktop.
-</para>
-
-<para>
-This extension provides mechanisms for changing the visible shape of a
-window to an arbitrary, possibly disjoint, nonrectangular form. The intent
-of the extension is to supplement the existing semantics, not replace them.
-In particular, it is desirable for clients that are unaware of the
-extension to still be able to cope reasonably with shaped windows. For
-example, window managers should still be able to negotiate screen
-real estate in rectangular pieces. Toward this end, any shape specified for
-a window is clipped by the bounding rectangle for the window as specified by
-the window's geometry in the core protocol. An expected convention would be
-that client programs expand their shape to fill the area offered by the
-window manager.
-</para>
-</chapter>
-
-<chapter id='description'>
-<title>Description</title>
-
-<para>
-Each window (even with no shapes specified) is defined by two regions: the
-<emphasis remap='I'>bounding region</emphasis> and the
-<emphasis remap='I'>clip region</emphasis>. The bounding region is the
-area of the parent window that the window will occupy (including border).
-The clip region is the subset of the bounding region that is available for
-subwindows and graphics. The area between the bounding region and the
-clip region is defined to be the border of the window.
-</para>
-
-<para>
-A nonshaped window will have a bounding region that is a rectangle spanning
-the window, including its border; the clip region will be a rectangle
-filling the inside dimensions (not including the border). In this document,
-these areas are referred to as the
-<emphasis remap='I'>default bounding region</emphasis> and the
-<emphasis remap='I'>default clip region</emphasis>. For a window with
-inside size of <emphasis remap='I'>width</emphasis> by
-<emphasis remap='I'>height</emphasis> and border width
-<emphasis remap='I'>bwidth</emphasis>, the default bounding and clip
-regions are the rectangles (relative to the window origin):
-</para>
-
-<literallayout remap='Ds'>
-bounding.x = -<emphasis remap='I'>bwidth</emphasis>
-bounding.y = -<emphasis remap='I'>bwidth</emphasis>
-bounding.width = <emphasis remap='I'>width</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
-bounding.height = <emphasis remap='I'>height</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
-
-clip.x = 0
-clip.y = 0
-clip.width = <emphasis remap='I'>width</emphasis>
-clip.height = <emphasis remap='I'>height</emphasis>
-</literallayout>
-
-<para>
-This extension allows a client to modify either or both of the bounding or
-clip regions by specifying new regions that combine with the default
-regions. These new regions are called the
-<emphasis remap='I'>client bounding region</emphasis> and the
-<emphasis remap='I'>client clip region</emphasis>. They are specified
-relative to the origin of the window and are always defined by offsets
-relative to the window origin (that is, region adjustments are not
-required when the window is moved). Three mechanisms for specifying
-regions are provided: a list of rectangles, a bitmap, and an existing
-bounding or clip region from a window. This is modeled on the specification
-of regions in graphics contexts in the core protocol and allows a variety
-of different uses of the extension.
-</para>
-
-<para>
-When using an existing window shape as an operand in specifying a new shape,
-the client region is used, unless none has been set, in which case the
-default region is used instead.
-</para>
-
-<para>
-The <emphasis remap='I'>effective bounding region</emphasis> of a window is
-defined to be the intersection of the client bounding region with the default
-bounding region. Any portion of the client bounding region that is not
-included in the default bounding region will not be included in the
-effective bounding region on the screen. This means that window managers
-(or other geometry managers) used to dealing with rectangular client windows
-will be able to constrain the client to a rectangular area of the screen.
-</para>
-
-<para>
-Construction of the effective bounding region is dynamic; the client bounding
-region is not mutated to obtain the effective bounding region. If a client
-bounding region is specified that extends beyond the current default bounding
-region, and the window is later enlarged, the effective bounding region will
-be enlarged to include more of the client bounding region.
-</para>
-
-<para>
-The <emphasis remap='I'>effective clip region</emphasis> of a window is
-defined to be the intersection of the client clip region with both the
-default clip region and the client bounding region. Any portion of the
-client clip region that is not included in both the default clip region
-and the client bounding region will not be included in the effective clip
-region on the screen.
-</para>
-
-<para>
-Construction of the effective clip region is dynamic; the client clip region is
-not mutated to obtain the effective clip region. If a client clip region is
-specified that extends beyond the current default clip region and the
-window or its bounding region is later enlarged, the effective clip region will
-be enlarged to include more of the client clip region if it is included in
-the effective bounding region.
-</para>
-
-<para>
-The border of a window is defined to be the difference between the effective
-bounding region and the effective clip region. If this region is empty, no
-border is displayed. If this region is nonempty, the border is filled
-using the border-tile or border-pixel of the window as specified in the core
-protocol. Note that a window with a nonzero border width will never be able
-to draw beyond the default clip region of the window. Also note that a zero
-border width does not prevent a window from having a border, since the clip
-shape can still be made smaller than the bounding shape.
-</para>
-
-<para>
-All output to the window and visible regions of any subwindows will be
-clipped to the effective clip region. The server must not retain window
-contents beyond the effective bounding region with backing store. The window's
-origin (for graphics operations, background tiling, and subwindow placement)
-is not affected by the existence of a bounding region or clip region.
-</para>
-
-<para>
-Areas that are inside the default bounding region but outside the effective
-bounding region are not part of the window; these areas of the screen will
-be occupied by other windows. Input events that occur within the default
-bounding region but outside the effective bounding region will be delivered as
-if the window was not occluding the event position. Events that occur in
-a nonrectangular border of a window will be delivered to that window, just
-as for events that occur in a normal rectangular border.
-</para>
-
-<para>An
-<function>InputOnly</function>
-window can have its bounding region set, but it is a
-<function>Match</function>
-error to attempt to set a clip region on an
-<function>InputOnly</function>
-window or to specify its clip region as a source to a request
-in this extension.
-</para>
-
-<para>
-The server must accept changes to the clip region of a root window, but
-the server is permitted to ignore requested changes to the bounding region
-of a root window. If the server accepts bounding region changes, the contents
-of the screen outside the bounding region are implementation dependent.
-</para>
-</chapter>
-
-<chapter id='c_language_binding'>
-<title>C Language Binding</title>
-
-<para>
-The C functions provide direct access to the protocol and add no additional
-semantics.
-</para>
-
-<para>The include file for this extension is
-<<symbol role='Pn'>X11/extensions/shape.h</symbol>>.
-The defined shape kinds are
-<function>ShapeBounding</function>
-and
-<function>ShapeClip</function>
-The defined region operations are
-<function>ShapeSet</function>
-<function>ShapeUnion</function>
-<function>ShapeIntersect</function>
-<function>ShapeSubtract</function>
-and
-<function>ShapeInvert</function>.</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef>Bool<function> XShapeQueryExtension</function></funcdef>
-<paramdef>Display <parameter>*display</parameter></paramdef>
-<paramdef>int <parameter>*event_base</parameter></paramdef>
-<paramdef>int <parameter>*error_base</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-<function>XShapeQueryExtension</function>
-returns
-<function>True</function>
-if the specified display supports the SHAPE extension else
-<function>False</function>
-If the extension is supported, *event_base is set to the event number for
-<function>ShapeNotify</function>
-events and *error_base would be set to the error number for the first error for
-this extension. Because no errors are defined for this version of
-the extension, the value returned here is not defined (nor useful).
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef>Status<function> XShapeQueryVersion</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>int<parameter> *major_version</parameter></paramdef>
-<paramdef>int<parameter> *minor_version</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is supported,
-<function>XShapeQueryVersion</function>
-sets the major and minor version numbers of the
-extension supported by the display and returns a nonzero value.
-Otherwise, the arguments are not set and zero is returned.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef><function>XShapeCombineRegion</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> dest</parameter></paramdef>
-<paramdef>int<parameter> dest_kind</parameter></paramdef>
-<paramdef>int<parameter> x_off</parameter></paramdef>
-<paramdef>int<parameter> y_off</parameter></paramdef>
-<paramdef>int<parameter> region</parameter></paramdef>
-<paramdef>int<parameter> op</parameter></paramdef>
-<paramdef>REGION<parameter> *region</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-<function>XShapeCombineRegion</function>
-converts the specified region into a list of rectangles and calls
-<function>XShapeCombineRectangles</function>
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef><function>XShapeCombineRectangles</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> dest</parameter></paramdef>
-<paramdef>int<parameter> dest_kind</parameter></paramdef>
-<paramdef>int<parameter> x_off</parameter></paramdef>
-<paramdef>int<parameter> y_off</parameter></paramdef>
-<paramdef>XRectangle<parameter> *rectangles</parameter></paramdef>
-<paramdef>int<parameter> n_rects</parameter></paramdef>
-<paramdef>int<parameter> op</parameter></paramdef>
-<paramdef>int<parameter> ordering</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is supported,
-<function>XShapeCombineRectangles</function>
-performs a
-<function>ShapeRectangles</function>
-operation; otherwise, the request is ignored.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef><function>XShapeCombineMask</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>int<parameter> dest</parameter></paramdef>
-<paramdef>int<parameter> dest_kind</parameter></paramdef>
-<paramdef>int<parameter> x_off</parameter></paramdef>
-<paramdef>int<parameter> y_off</parameter></paramdef>
-<paramdef>Pixmap<parameter> src</parameter></paramdef>
-<paramdef>int<parameter> op</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is supported,
-<function>XShapeCombineMask</function>
-performs a
-<function>ShapeMask</function>
-operation; otherwise, the request is ignored.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef><function>XShapeCombineShape</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> dest</parameter></paramdef>
-<paramdef>int<parameter> dest_kind</parameter></paramdef>
-<paramdef>int<parameter> x_off</parameter></paramdef>
-<paramdef>int<parameter> y_off</parameter></paramdef>
-<paramdef>Window<parameter> src</parameter></paramdef>
-<paramdef>int<parameter> src_kind</parameter></paramdef>
-<paramdef>int<parameter> op</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is supported,
-<function>XShapeCombineShape</function>
-performs a
-<function>ShapeCombine</function>
-operation; otherwise, the request is ignored.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef><function>XShapeOffsetShape</function></funcdef>
-<paramdef><parameter>display</parameter></paramdef>
-<paramdef><parameter>dest</parameter></paramdef>
-<paramdef><parameter>dest_kind</parameter></paramdef>
-<paramdef><parameter>x_off</parameter></paramdef>
-<paramdef><parameter>y_off</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is supported,
-<function>XShapeOffsetShape</function>
-performs a
-<function>ShapeOffset</function>
-operation; otherwise, the request is ignored.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef>Status <function>XShapeQueryExtents</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> window</parameter></paramdef>
-<paramdef>Bool<parameter> *bounding_shaped</parameter></paramdef>
-<paramdef>int<parameter> *x_bounding</parameter></paramdef>
-<paramdef>int<parameter> *y_bounding</parameter></paramdef>
-<paramdef>unsigned int<parameter> *w_bounding</parameter></paramdef>
-<paramdef>unsigned int<parameter> *h_bounding</parameter></paramdef>
-<paramdef>Bool<parameter> *clip_shaped</parameter></paramdef>
-<paramdef>int<parameter> *x_clip</parameter></paramdef>
-<paramdef>int<parameter> *y_clip</parameter></paramdef>
-<paramdef>unsigned int<parameter> *w_clip</parameter></paramdef>
-<paramdef>unsigned int<parameter> *h_clip</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is supported,
-<function>XShapeQueryExtents</function>
-sets x_bounding, y_bounding, w_bounding, h_bounding to the extents of the
-bounding shape and sets x_clip, y_clip, w_clip, h_clip to the extents of
-the clip shape. For unspecified client regions, the extents of the
-corresponding default region are used.
-</para>
-
-<para>
-If the extension is supported, a nonzero value is returned; otherwise,
-zero is returned.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef><function>XShapeSelectInput</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> window</parameter></paramdef>
-<paramdef>unsigned long<parameter> mask</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-To make this extension more compatible with other interfaces, although
-only one event type can be selected via the extension,
-<function>XShapeSelectInput</function>
-provides a general mechanism similar to the standard Xlib binding for
-window events. A mask value has been defined,
-<function>ShapeNotifyMask</function>
-that is the only valid bit in mask that may be specified.
-The structure for this event is defined as follows:
-</para>
-
-<literallayout remap='Ds'>
-typedef struct {
- int type; /* of event */
- unsigned long serial; /* # of last request processed by server */
- Bool send_event; /* true if this came frome a SendEvent request */
- Display *display; /* Display the event was read from */
- Window window; /* window of event */
- int kind; /* ShapeBounding or ShapeClip */
- int x, y; /* extents of new region */
- unsigned width, height;
- Time time; /* server timestamp when region changed */
- Bool shaped; /* true if the region exists */
-} XShapeEvent;
-</literallayout>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef>unsigned long <function>XShapeInputSelected</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> window</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-<function>XShapeInputSelected</function>
-returns the current input mask for extension events on the specified
-window; the value returned if
-<function>ShapeNotify</function>
-is selected for is
-<function>ShapeNotifyMask</function>
-otherwise, it returns zero.
-If the extension is not supported, it returns zero.
-</para>
-
-<funcsynopsis>
-<funcprototype>
-<funcdef>XRectangle<function> *XShapeGetRectangles</function></funcdef>
-<paramdef>Display<parameter> *display</parameter></paramdef>
-<paramdef>Window<parameter> window</parameter></paramdef>
-<paramdef>int<parameter> kind</parameter></paramdef>
-<paramdef>int<parameter> *count</parameter></paramdef>
-<paramdef>int<parameter> *ordering</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<para>
-If the extension is not supported,
-<function>XShapeGetRectangles</function>
-returns NULL. Otherwise, it returns a list of rectangles that describe the
-region specified by kind.
-</para>
-</chapter>
-
-<glossary id='glossary'>
-
-<glossentry id='bounding_region'>
- <glossterm>bounding region</glossterm>
- <glossdef><para>The area of the parent window that this window will occupy.
-This area is divided into two parts: the border and the interior.</para>
- </glossdef>
-</glossentry>
-
-<glossentry id='clip_region'>
- <glossterm>clip region</glossterm>
- <glossdef><para>The interior of the window, as a subset of the bounding
-region. This region describes the area that will be painted with the
-window background when the window is cleared, will contain all graphics
-output to the window, and will clip any subwindows.</para></glossdef>
-</glossentry>
-
-<glossentry id='default_bounding_region'>
- <glossterm>default bounding region</glossterm>
- <glossdef><para>The rectangular area, as described by the core protocol
-window size, that covers the interior of the window and its border.</para>
- </glossdef>
-</glossentry>
-
-<glossentry id='default_clip_region'>
- <glossterm>default clip region</glossterm>
- <glossdef><para>The rectangular area, as described by the core protocol
-window size, that covers the interior of the window and excludes the border.
- </para></glossdef>
-</glossentry>
-
-<glossentry id='client_bounding_region'>
- <glossterm>client bounding region</glossterm>
- <glossdef><para>The region associated with a window that is directly
-modified via this extension when specified by
-<function>ShapeBounding</function>
-This region is used in conjunction with the default bounding region
-to produce the effective bounding region.</para></glossdef>
-</glossentry>
-
-<glossentry id='client_clip_region'>
- <glossterm>client clip region</glossterm>
- <glossdef><para>The region associated with a window that is directly
-modified via this extension when specified by
-<function>ShapeClip</function>
-This region is used in conjunction with the default clip region
-and the client bounding region to produce the effective clip region.</para>
- </glossdef>
-</glossentry>
-
-<glossentry id='effective_bounding_region'>
- <glossterm>effective bounding region</glossterm>
- <glossdef><para>The actual shape of the window on the screen, including
-border and interior (but excluding the effects of overlapping windows).
-When a window has a client bounding region, the effective bounding region
-is the intersection of the default bounding region and the client bounding
-region. Otherwise, the effective bounding region is the same as the
-default bounding region.</para>
- </glossdef>
-</glossentry>
-
-<glossentry id='effective_clip_region'>
- <glossterm>effective clip region</glossterm>
- <glossdef><para>The actual shape of the interior of the window on the
-screen (excluding the effects of overlapping windows). When a window
-has a client clip region or a client bounding region, the effective
-clip region is the intersection of the default clip region, the client
-clip region (if any) and the client bounding region (if any). Otherwise,
-the effective clip region is the same as the default clip region.</para>
- </glossdef>
-</glossentry>
-</glossary>
-</book>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<!-- lifted from troff+ms+XMan by doclifter --> +<book id="shapelib"> + +<bookinfo> + <title>X Nonrectangular Window Shape Extension Library</title> + <subtitle>X Consortium Standard</subtitle> + <releaseinfo>X Version 11, Release 6.4</releaseinfo> + <authorgroup> + <author> + <firstname>Keith</firstname><surname>Packard</surname> + </author> + </authorgroup> + <corpname>MIT X Consortium</corpname> + <copyright><year>1989</year><holder>X Consortium</holder></copyright> + <releaseinfo>Version 1.0</releaseinfo> + <affiliation><orgname>MIT X Consortium</orgname></affiliation> + <productnumber>X Version 11, Release 6.4</productnumber> + +<legalnotice> + +<para> +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files +(the “Software”), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of the Software, and +to permit persons to whom the Software is furnished to do so, subject to +the following conditions: +</para> + +<para> +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +</para> + +<para> +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY +KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. +</para> + +<para> +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +</para> +</legalnotice> +</bookinfo> + +<chapter id='overview'> +<title>Overview</title> + +<para>This extension provides arbitrary window and border shapes within +the X11 protocol. +</para> + +<para> +The restriction of rectangular windows within the X protocol is a significant +limitation in the implementation of many styles of user interface. For +example, many transient windows would like to display a +“drop shadow” to give the illusion of 3 dimensions. As +another example, some user interface style guides call for buttons with +rounded corners; the full simulation of a nonrectangular shape, +particularly with respect to event distribution and cursor shape, is not +possible within the core X protocol. As a final example, round clocks +and nonrectangular icons are desirable visual addition to the desktop. +</para> + +<para> +This extension provides mechanisms for changing the visible shape of a +window to an arbitrary, possibly disjoint, nonrectangular form. The intent +of the extension is to supplement the existing semantics, not replace them. +In particular, it is desirable for clients that are unaware of the +extension to still be able to cope reasonably with shaped windows. For +example, window managers should still be able to negotiate screen +real estate in rectangular pieces. Toward this end, any shape specified for +a window is clipped by the bounding rectangle for the window as specified by +the window's geometry in the core protocol. An expected convention would be +that client programs expand their shape to fill the area offered by the +window manager. +</para> +</chapter> + +<chapter id='description'> +<title>Description</title> + +<para> +Each window (even with no shapes specified) is defined by two regions: the +<emphasis remap='I'>bounding region</emphasis> and the +<emphasis remap='I'>clip region</emphasis>. The bounding region is the +area of the parent window that the window will occupy (including border). +The clip region is the subset of the bounding region that is available for +subwindows and graphics. The area between the bounding region and the +clip region is defined to be the border of the window. +</para> + +<para> +A nonshaped window will have a bounding region that is a rectangle spanning +the window, including its border; the clip region will be a rectangle +filling the inside dimensions (not including the border). In this document, +these areas are referred to as the +<emphasis remap='I'>default bounding region</emphasis> and the +<emphasis remap='I'>default clip region</emphasis>. For a window with +inside size of <emphasis remap='I'>width</emphasis> by +<emphasis remap='I'>height</emphasis> and border width +<emphasis remap='I'>bwidth</emphasis>, the default bounding and clip +regions are the rectangles (relative to the window origin): +</para> + +<literallayout remap='Ds'> +bounding.x = -<emphasis remap='I'>bwidth</emphasis> +bounding.y = -<emphasis remap='I'>bwidth</emphasis> +bounding.width = <emphasis remap='I'>width</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis> +bounding.height = <emphasis remap='I'>height</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis> + +clip.x = 0 +clip.y = 0 +clip.width = <emphasis remap='I'>width</emphasis> +clip.height = <emphasis remap='I'>height</emphasis> +</literallayout> + +<para> +This extension allows a client to modify either or both of the bounding or +clip regions by specifying new regions that combine with the default +regions. These new regions are called the +<emphasis remap='I'>client bounding region</emphasis> and the +<emphasis remap='I'>client clip region</emphasis>. They are specified +relative to the origin of the window and are always defined by offsets +relative to the window origin (that is, region adjustments are not +required when the window is moved). Three mechanisms for specifying +regions are provided: a list of rectangles, a bitmap, and an existing +bounding or clip region from a window. This is modeled on the specification +of regions in graphics contexts in the core protocol and allows a variety +of different uses of the extension. +</para> + +<para> +When using an existing window shape as an operand in specifying a new shape, +the client region is used, unless none has been set, in which case the +default region is used instead. +</para> + +<para> +The <emphasis remap='I'>effective bounding region</emphasis> of a window is +defined to be the intersection of the client bounding region with the default +bounding region. Any portion of the client bounding region that is not +included in the default bounding region will not be included in the +effective bounding region on the screen. This means that window managers +(or other geometry managers) used to dealing with rectangular client windows +will be able to constrain the client to a rectangular area of the screen. +</para> + +<para> +Construction of the effective bounding region is dynamic; the client bounding +region is not mutated to obtain the effective bounding region. If a client +bounding region is specified that extends beyond the current default bounding +region, and the window is later enlarged, the effective bounding region will +be enlarged to include more of the client bounding region. +</para> + +<para> +The <emphasis remap='I'>effective clip region</emphasis> of a window is +defined to be the intersection of the client clip region with both the +default clip region and the client bounding region. Any portion of the +client clip region that is not included in both the default clip region +and the client bounding region will not be included in the effective clip +region on the screen. +</para> + +<para> +Construction of the effective clip region is dynamic; the client clip region is +not mutated to obtain the effective clip region. If a client clip region is +specified that extends beyond the current default clip region and the +window or its bounding region is later enlarged, the effective clip region will +be enlarged to include more of the client clip region if it is included in +the effective bounding region. +</para> + +<para> +The border of a window is defined to be the difference between the effective +bounding region and the effective clip region. If this region is empty, no +border is displayed. If this region is nonempty, the border is filled +using the border-tile or border-pixel of the window as specified in the core +protocol. Note that a window with a nonzero border width will never be able +to draw beyond the default clip region of the window. Also note that a zero +border width does not prevent a window from having a border, since the clip +shape can still be made smaller than the bounding shape. +</para> + +<para> +All output to the window and visible regions of any subwindows will be +clipped to the effective clip region. The server must not retain window +contents beyond the effective bounding region with backing store. The window's +origin (for graphics operations, background tiling, and subwindow placement) +is not affected by the existence of a bounding region or clip region. +</para> + +<para> +Areas that are inside the default bounding region but outside the effective +bounding region are not part of the window; these areas of the screen will +be occupied by other windows. Input events that occur within the default +bounding region but outside the effective bounding region will be delivered as +if the window was not occluding the event position. Events that occur in +a nonrectangular border of a window will be delivered to that window, just +as for events that occur in a normal rectangular border. +</para> + +<para>An +<function>InputOnly</function> +window can have its bounding region set, but it is a +<function>Match</function> +error to attempt to set a clip region on an +<function>InputOnly</function> +window or to specify its clip region as a source to a request +in this extension. +</para> + +<para> +The server must accept changes to the clip region of a root window, but +the server is permitted to ignore requested changes to the bounding region +of a root window. If the server accepts bounding region changes, the contents +of the screen outside the bounding region are implementation dependent. +</para> +</chapter> + +<chapter id='c_language_binding'> +<title>C Language Binding</title> + +<para> +The C functions provide direct access to the protocol and add no additional +semantics. +</para> + +<para>The include file for this extension is +<<symbol role='Pn'>X11/extensions/shape.h</symbol>>. +The defined shape kinds are +<function>ShapeBounding</function> +and +<function>ShapeClip</function> +The defined region operations are +<function>ShapeSet</function> +<function>ShapeUnion</function> +<function>ShapeIntersect</function> +<function>ShapeSubtract</function> +and +<function>ShapeInvert</function>.</para> + +<funcsynopsis id='xshapequeryextension'> +<funcprototype> +<funcdef>Bool<function> XShapeQueryExtension</function></funcdef> +<paramdef>Display <parameter>*display</parameter></paramdef> +<paramdef>int <parameter>*event_base</parameter></paramdef> +<paramdef>int <parameter>*error_base</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XShapeQueryExtension</function> +returns +<function>True</function> +if the specified display supports the SHAPE extension else +<function>False</function> +If the extension is supported, *event_base is set to the event number for +<function>ShapeNotify</function> +events and *error_base would be set to the error number for the first error for +this extension. Because no errors are defined for this version of +the extension, the value returned here is not defined (nor useful). +</para> + +<funcsynopsis id='xshapequeryversion'> +<funcprototype> +<funcdef>Status<function> XShapeQueryVersion</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>int<parameter> *major_version</parameter></paramdef> +<paramdef>int<parameter> *minor_version</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is supported, +<function>XShapeQueryVersion</function> +sets the major and minor version numbers of the +extension supported by the display and returns a nonzero value. +Otherwise, the arguments are not set and zero is returned. +</para> + +<funcsynopsis id='xshapecombineregion'> +<funcprototype> +<funcdef><function>XShapeCombineRegion</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> dest</parameter></paramdef> +<paramdef>int<parameter> dest_kind</parameter></paramdef> +<paramdef>int<parameter> x_off</parameter></paramdef> +<paramdef>int<parameter> y_off</parameter></paramdef> +<paramdef>int<parameter> region</parameter></paramdef> +<paramdef>int<parameter> op</parameter></paramdef> +<paramdef>REGION<parameter> *region</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XShapeCombineRegion</function> +converts the specified region into a list of rectangles and calls +<function>XShapeCombineRectangles</function> +</para> + +<funcsynopsis id='xshapecombinerectangles'> +<funcprototype> +<funcdef><function>XShapeCombineRectangles</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> dest</parameter></paramdef> +<paramdef>int<parameter> dest_kind</parameter></paramdef> +<paramdef>int<parameter> x_off</parameter></paramdef> +<paramdef>int<parameter> y_off</parameter></paramdef> +<paramdef>XRectangle<parameter> *rectangles</parameter></paramdef> +<paramdef>int<parameter> n_rects</parameter></paramdef> +<paramdef>int<parameter> op</parameter></paramdef> +<paramdef>int<parameter> ordering</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is supported, +<function>XShapeCombineRectangles</function> +performs a +<function>ShapeRectangles</function> +operation; otherwise, the request is ignored. +</para> + +<funcsynopsis id='xshapecombinemask'> +<funcprototype> +<funcdef><function>XShapeCombineMask</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>int<parameter> dest</parameter></paramdef> +<paramdef>int<parameter> dest_kind</parameter></paramdef> +<paramdef>int<parameter> x_off</parameter></paramdef> +<paramdef>int<parameter> y_off</parameter></paramdef> +<paramdef>Pixmap<parameter> src</parameter></paramdef> +<paramdef>int<parameter> op</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is supported, +<function>XShapeCombineMask</function> +performs a +<function>ShapeMask</function> +operation; otherwise, the request is ignored. +</para> + +<funcsynopsis id='xshapecombineshape'> +<funcprototype> +<funcdef><function>XShapeCombineShape</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> dest</parameter></paramdef> +<paramdef>int<parameter> dest_kind</parameter></paramdef> +<paramdef>int<parameter> x_off</parameter></paramdef> +<paramdef>int<parameter> y_off</parameter></paramdef> +<paramdef>Window<parameter> src</parameter></paramdef> +<paramdef>int<parameter> src_kind</parameter></paramdef> +<paramdef>int<parameter> op</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is supported, +<function>XShapeCombineShape</function> +performs a +<function>ShapeCombine</function> +operation; otherwise, the request is ignored. +</para> + +<funcsynopsis id='xshapeoffsetshape'> +<funcprototype> +<funcdef><function>XShapeOffsetShape</function></funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>dest</parameter></paramdef> +<paramdef><parameter>dest_kind</parameter></paramdef> +<paramdef><parameter>x_off</parameter></paramdef> +<paramdef><parameter>y_off</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is supported, +<function>XShapeOffsetShape</function> +performs a +<function>ShapeOffset</function> +operation; otherwise, the request is ignored. +</para> + +<funcsynopsis id='xshapequeryextents'> +<funcprototype> +<funcdef>Status <function>XShapeQueryExtents</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> window</parameter></paramdef> +<paramdef>Bool<parameter> *bounding_shaped</parameter></paramdef> +<paramdef>int<parameter> *x_bounding</parameter></paramdef> +<paramdef>int<parameter> *y_bounding</parameter></paramdef> +<paramdef>unsigned int<parameter> *w_bounding</parameter></paramdef> +<paramdef>unsigned int<parameter> *h_bounding</parameter></paramdef> +<paramdef>Bool<parameter> *clip_shaped</parameter></paramdef> +<paramdef>int<parameter> *x_clip</parameter></paramdef> +<paramdef>int<parameter> *y_clip</parameter></paramdef> +<paramdef>unsigned int<parameter> *w_clip</parameter></paramdef> +<paramdef>unsigned int<parameter> *h_clip</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is supported, +<function>XShapeQueryExtents</function> +sets x_bounding, y_bounding, w_bounding, h_bounding to the extents of the +bounding shape and sets x_clip, y_clip, w_clip, h_clip to the extents of +the clip shape. For unspecified client regions, the extents of the +corresponding default region are used. +</para> + +<para> +If the extension is supported, a nonzero value is returned; otherwise, +zero is returned. +</para> + +<funcsynopsis id='xshapeselectinput'> +<funcprototype> +<funcdef><function>XShapeSelectInput</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> window</parameter></paramdef> +<paramdef>unsigned long<parameter> mask</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +To make this extension more compatible with other interfaces, although +only one event type can be selected via the extension, +<function>XShapeSelectInput</function> +provides a general mechanism similar to the standard Xlib binding for +window events. A mask value has been defined, +<function>ShapeNotifyMask</function> +that is the only valid bit in mask that may be specified. +The structure for this event is defined as follows: +</para> + +<literallayout remap='Ds'> +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came frome a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* window of event */ + int kind; /* ShapeBounding or ShapeClip */ + int x, y; /* extents of new region */ + unsigned width, height; + Time time; /* server timestamp when region changed */ + Bool shaped; /* true if the region exists */ +} XShapeEvent; +</literallayout> + +<funcsynopsis id='xshapeinputselected'> +<funcprototype> +<funcdef>unsigned long <function>XShapeInputSelected</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> window</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<function>XShapeInputSelected</function> +returns the current input mask for extension events on the specified +window; the value returned if +<function>ShapeNotify</function> +is selected for is +<function>ShapeNotifyMask</function> +otherwise, it returns zero. +If the extension is not supported, it returns zero. +</para> + +<funcsynopsis id='xshapegetrectangles'> +<funcprototype> +<funcdef>XRectangle<function> *XShapeGetRectangles</function></funcdef> +<paramdef>Display<parameter> *display</parameter></paramdef> +<paramdef>Window<parameter> window</parameter></paramdef> +<paramdef>int<parameter> kind</parameter></paramdef> +<paramdef>int<parameter> *count</parameter></paramdef> +<paramdef>int<parameter> *ordering</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +If the extension is not supported, +<function>XShapeGetRectangles</function> +returns NULL. Otherwise, it returns a list of rectangles that describe the +region specified by kind. +</para> +</chapter> + +<glossary id='glossary'> + +<glossentry id='bounding_region'> + <glossterm>bounding region</glossterm> + <glossdef><para>The area of the parent window that this window will occupy. +This area is divided into two parts: the border and the interior.</para> + </glossdef> +</glossentry> + +<glossentry id='clip_region'> + <glossterm>clip region</glossterm> + <glossdef><para>The interior of the window, as a subset of the bounding +region. This region describes the area that will be painted with the +window background when the window is cleared, will contain all graphics +output to the window, and will clip any subwindows.</para></glossdef> +</glossentry> + +<glossentry id='default_bounding_region'> + <glossterm>default bounding region</glossterm> + <glossdef><para>The rectangular area, as described by the core protocol +window size, that covers the interior of the window and its border.</para> + </glossdef> +</glossentry> + +<glossentry id='default_clip_region'> + <glossterm>default clip region</glossterm> + <glossdef><para>The rectangular area, as described by the core protocol +window size, that covers the interior of the window and excludes the border. + </para></glossdef> +</glossentry> + +<glossentry id='client_bounding_region'> + <glossterm>client bounding region</glossterm> + <glossdef><para>The region associated with a window that is directly +modified via this extension when specified by +<function>ShapeBounding</function> +This region is used in conjunction with the default bounding region +to produce the effective bounding region.</para></glossdef> +</glossentry> + +<glossentry id='client_clip_region'> + <glossterm>client clip region</glossterm> + <glossdef><para>The region associated with a window that is directly +modified via this extension when specified by +<function>ShapeClip</function> +This region is used in conjunction with the default clip region +and the client bounding region to produce the effective clip region.</para> + </glossdef> +</glossentry> + +<glossentry id='effective_bounding_region'> + <glossterm>effective bounding region</glossterm> + <glossdef><para>The actual shape of the window on the screen, including +border and interior (but excluding the effects of overlapping windows). +When a window has a client bounding region, the effective bounding region +is the intersection of the default bounding region and the client bounding +region. Otherwise, the effective bounding region is the same as the +default bounding region.</para> + </glossdef> +</glossentry> + +<glossentry id='effective_clip_region'> + <glossterm>effective clip region</glossterm> + <glossdef><para>The actual shape of the interior of the window on the +screen (excluding the effects of overlapping windows). When a window +has a client clip region or a client bounding region, the effective +clip region is the intersection of the default clip region, the client +clip region (if any) and the client bounding region (if any). Otherwise, +the effective clip region is the same as the default clip region.</para> + </glossdef> +</glossentry> +</glossary> +</book> |