1237 lines
37 KiB
XML
1237 lines
37 KiB
XML
<?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="shape">
|
|
|
|
<bookinfo>
|
|
<title>X Nonrectangular Window Shape Extension Protocol</title>
|
|
<subtitle>X.Org Standard</subtitle>
|
|
<releaseinfo>Version 1.1</releaseinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Keith</firstname><surname>Packard</surname>
|
|
<affiliation><orgname>MIT X Consortium Intel Corporation</orgname></affiliation>
|
|
</author>
|
|
<othercredit>
|
|
<firstname>Hideki</firstname><surname>Hiura</surname>
|
|
<affiliation><orgname>SunSoft, Inc.</orgname></affiliation>
|
|
</othercredit>
|
|
</authorgroup>
|
|
<corpname>X Consortium Standard</corpname>
|
|
<copyright><year>1989</year><holder>The Open Group</holder></copyright>
|
|
<copyright><year>2004</year><holder>The Open Group</holder></copyright>
|
|
<copyright><year>2006</year><holder>Keith Packard</holder></copyright>
|
|
<affiliation><orgname>X Consortium</orgname></affiliation>
|
|
<productnumber>X Version 11, Release 7</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
|
|
COPYRIGHT HOLDERS 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 copyright holders
|
|
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
|
|
copyright holders.
|
|
</para>
|
|
</legalnotice>
|
|
</bookinfo>
|
|
|
|
<chapter><title>TITLE</title>
|
|
<sect1 id="Overview">
|
|
<title>Overview</title>
|
|
<para>
|
|
<!-- .LP -->
|
|
This extension provides arbitrary window and border shapes within the X11
|
|
protocol.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
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>
|
|
<!-- .LP -->
|
|
This extension provides mechanisms for changing both the visible and interactive shape of a
|
|
window to arbitrary, possibly disjoint, nonrectangular forms. 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>
|
|
</sect1>
|
|
|
|
<sect1 id="Description">
|
|
<title>Description</title>
|
|
<para>
|
|
Each window (even with no shapes specified) is defined by three regions: the
|
|
<emphasis remap='I'>bounding region</emphasis>, the <emphasis remap='I'>clip
|
|
region</emphasis> and the <emphasis remap='I'>input 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. The input region is the subset of the
|
|
bounding region that can "contain" the pointer.
|
|
</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); the input
|
|
region will match the bounding region. In this document,
|
|
these areas are referred to as the
|
|
<emphasis remap='I'>default bounding region</emphasis>, the
|
|
<emphasis remap='I'>default clip region</emphasis> and the
|
|
<emphasis remap='I'>default input 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, clip
|
|
and input regions are the rectangles (relative to the window origin):
|
|
</para>
|
|
|
|
<literallayout class="monospaced">
|
|
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>
|
|
|
|
input.x = -<emphasis remap='I'>bwidth</emphasis>
|
|
input.y = -<emphasis remap='I'>bwidth</emphasis>
|
|
input.width = <emphasis remap='I'>width</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
|
|
input.height = <emphasis remap='I'>height</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
|
|
</literallayout>
|
|
|
|
<para>
|
|
This extension allows a client to modify any combination of the bounding,
|
|
clip or input regions by specifying new regions that combine with the default
|
|
regions. These new regions are called the
|
|
<emphasis remap='I'>client bounding region</emphasis>,
|
|
the <emphasis remap='I'>client clip region</emphasis> and the
|
|
<emphasis remap='I'>client input 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>
|
|
The <emphasis remap='I'>effective input region</emphasis> of a window is
|
|
defined to be the intersection of the
|
|
client input region with both the default input region and the client bounding
|
|
region. Any portion of the client input region that is not included in both
|
|
the default input region and the client bounding region will not be included in
|
|
the effective input region on the screen.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
Construction of the effective input region is dynamic; the client input region is
|
|
not mutated to obtain the effective input region. If a client input region is
|
|
specified that extends beyond the current default input region and the
|
|
window or its bounding region is later enlarged, the effective input region will
|
|
be enlarged to include more of the client input region if it is included in
|
|
the effective bounding region.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
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>
|
|
<!-- .LP -->
|
|
An
|
|
<function>InputOnly</function>
|
|
window can have its bounding or input 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>
|
|
<!-- .LP -->
|
|
The server must accept changes to the clip and input regions 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>
|
|
</sect1>
|
|
|
|
<sect1 id="Types">
|
|
<title>Types</title>
|
|
<para>
|
|
<!-- .LP -->
|
|
The following types are used in the request and event definitions in
|
|
subsequent sections.
|
|
</para>
|
|
|
|
<para>
|
|
SHAPE_KIND:
|
|
{ <function>Bounding</function>,
|
|
<function>Clip</function>,
|
|
<function>Input</function> }
|
|
</para>
|
|
|
|
<para>
|
|
SHAPE_OP:
|
|
{ <function>Set</function>,
|
|
<function>Union</function>,
|
|
<function>Intersect</function>,
|
|
<function>Subtract</function>,
|
|
<function>Invert</function> }
|
|
</para>
|
|
|
|
<para>
|
|
<function>Set</function>
|
|
indicates that the region specified as an explicit source in the request is
|
|
stored unaltered as the new destination client region.
|
|
<function>Union</function>
|
|
indicates that the source and destination regions are unioned together to
|
|
produce the new destination client region.
|
|
<function>Intersect</function>
|
|
indicates that the source and destination regions are intersected together to
|
|
produce the new destination client region.
|
|
<function>Subtract</function>
|
|
indicates that the source region is subtracted from the destination region to
|
|
produce the new destination region.
|
|
<function>Invert</function>
|
|
indicates that the destination region is subtracted from the source region to
|
|
produce the new destination region.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="Requests">
|
|
<title>Requests</title>
|
|
<para>
|
|
<function>ShapeQueryVersion</function>
|
|
</para>
|
|
|
|
<para>
|
|
=>
|
|
</para>
|
|
|
|
<para>
|
|
majorVersion: CARD16
|
|
</para>
|
|
<para>
|
|
minorVersion: CARD16
|
|
</para>
|
|
|
|
<para>
|
|
This request can be used to ensure that the server version of the SHAPE
|
|
extension is usable by the client. This document defines major version one
|
|
(1), minor version one (1).
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeRectangles</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry><emphasis remap='I'>dest</emphasis>: WINDOW</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry><emphasis remap='I'>destKind</emphasis>: SHAPE_KIND</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry><emphasis remap='I'>op</emphasis>: SHAPE_OP</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry><emphasis remap='I'>xOff, yOff</emphasis>: INT16</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry><emphasis remap='I'>rectangles</emphasis>: LISTofRECTANGLES</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry><emphasis remap='I'>ordering</emphasis>:
|
|
{ <function>UnSorted</function>,
|
|
<function>YSorted</function>,
|
|
<function>YXSorted</function>,
|
|
<function>YXBanded</function> }
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>,
|
|
<function>Length</function>,
|
|
<function>Match</function>,
|
|
<function>Value</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
This request specifies an array of rectangles, relative to the origin of the
|
|
window plus the specified offset (xOff and yOff) that together
|
|
define a region. This region is combined (as specified by the operator
|
|
op) with the existing client region (specified by destKind) of the
|
|
destination window, and the result is stored as the specified client region of
|
|
the destination window. Note that the list of rectangles can be empty,
|
|
specifying an empty region; this is not the same as passing
|
|
<function>None</function> to
|
|
<function>ShapeMask</function>,
|
|
</para>
|
|
|
|
<para>
|
|
If known by the client,
|
|
ordering relations on the rectangles can be specified with the ordering
|
|
argument.
|
|
This may provide faster operation by the server.
|
|
The meanings of the ordering values are the same as in the core protocol
|
|
<function>SetClipRectangles</function>
|
|
request.
|
|
If an incorrect ordering is specified,
|
|
the server may generate a
|
|
<function>Match </function>
|
|
error, but it is not required to do so.
|
|
If no error is generated,
|
|
the graphics results are undefined.
|
|
Except for
|
|
<function>UnSorted ,</function>
|
|
the rectangles should be nonintersecting, or the resulting region will
|
|
be undefined.
|
|
<function>UnSorted </function>
|
|
means that the rectangles are in arbitrary order.
|
|
<function>YSorted </function>
|
|
means that the rectangles are nondecreasing in their Y origin.
|
|
<function>YXSorted </function>
|
|
additionally constrains
|
|
<function>YSorted </function>
|
|
order in that all rectangles with an equal Y origin are
|
|
nondecreasing in their X origin.
|
|
<function>YXBanded </function>
|
|
additionally constrains
|
|
<function>YXSorted </function>
|
|
by requiring that, for every possible Y scanline,
|
|
all rectangles that include that scanline have identical Y origins and Y
|
|
extents.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeMask</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>dest</emphasis>: WINDOW
|
|
<emphasis remap='I'>destKind</emphasis>: SHAPE_KIND
|
|
<emphasis remap='I'>op</emphasis>: SHAPE_OP
|
|
<emphasis remap='I'>xOff, yOff</emphasis>: INT16
|
|
<emphasis remap='I'>source</emphasis>: PIXMAP or
|
|
<function>None</function>
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>,
|
|
<function>Pixmap</function>,
|
|
<function>Match</function>,
|
|
<function>Value</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The source in this request is a 1-bit deep pixmap, or
|
|
<function>None .</function>
|
|
If source is
|
|
<function>None ,</function>
|
|
the specified client region is removed from the window, causing the effective
|
|
region to revert to the default region. The
|
|
<function>ShapeNotify</function>
|
|
event generated by this request and subsequent
|
|
<function>ShapeQueryExtents</function>
|
|
will report that a client shape has not been specified.
|
|
If a valid pixmap is specified, it is converted
|
|
to a region, with bits set to one included in the region and bits set to
|
|
zero excluded, and an offset from the window origin as specified by
|
|
xOff and yOff. The resulting region is then combined (as
|
|
specified by the operator op) with the existing client region
|
|
(indicated by destKind) of the destination window, and the result is
|
|
stored as the specified client region of the destination window. The source
|
|
pixmap and destination window must have been created on the same screen,
|
|
or else a
|
|
<function>Match</function>
|
|
error results.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeCombine</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>dest</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>destKind</emphasis>: SHAPE_KIND
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>op</emphasis>: SHAPE_OP
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>xOff, yOff</emphasis>: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>source</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>sourceKind</emphasis>: SHAPE_KIND
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>,
|
|
<function>Match</function>,
|
|
<function>Value</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The client region, indicated by sourceKind, of the source window is
|
|
offset from the window origin by xOff and yOff and combined with
|
|
the client region, indicated by destKind, of the destination window.
|
|
The result is stored as the specified client region of the destination
|
|
window.
|
|
The source and destination windows must be on the same screen, or else a
|
|
<function>Match</function>
|
|
error results.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeOffset</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>dest</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>destKind</emphasis>: SHAPE_KIND
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>xOff, yOff</emphasis>: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>,
|
|
<function>Match</function>,
|
|
<function>Value</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The client region, indicated by destKind, is moved relative to its
|
|
current position by the amounts xOff and yOff.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeQueryExtents</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>dest</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
=>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
boundingShaped: BOOL
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
clipShaped: BOOL
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
xBoundingShape: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
yBoundingShape: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
widthBoundingShape: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
heightBoundingShape: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
xClipShape: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
yClipShape: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
widthClipShape: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
heightClipShape: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The boundingShaped and clipShaped results are
|
|
<function>True</function>
|
|
if the corresponding client regions have been specified, else they are
|
|
<function>False .</function>
|
|
The x, y, width, and height values define the extents of the client regions,
|
|
when a client region has not been specified, the extents of the
|
|
corresponding default region are reported.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeSelectInput</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>window</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>enable</emphasis>: BOOL
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>,
|
|
<function>Value</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
Specifying enable as
|
|
<function>True</function>
|
|
causes the server to send the requesting client a
|
|
<function>ShapeNotify</function>
|
|
event whenever the bounding, clip or input region of the specified window is
|
|
altered by any client.
|
|
Specifying enable as
|
|
<function>False</function>
|
|
causes the server to stop sending such events.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeInputSelected</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>window</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
=>
|
|
enable: BOOL
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
If enable is
|
|
<function>True</function>, then
|
|
<function>ShapeNotify</function>
|
|
events for the window are generated for this client.
|
|
</para>
|
|
|
|
<para>
|
|
<function>ShapeGetRectangles</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>window</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>kind</emphasis>: SHAPE_KIND
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
=>
|
|
rectangles: LISTofRECTANGLE
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
ordering:
|
|
{ <function>UnSorted</function>,
|
|
<function>YSorted</function>,
|
|
<function>YXSorted</function>,
|
|
<function>YXBanded</function> }
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
Errors:
|
|
<function>Window,</function>
|
|
<function>Match</function>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
A list of rectangles describing the region indicated by kind, and the
|
|
ordering of those rectangles, is returned. The meaning of the ordering
|
|
values is the same as in the
|
|
<function>ShapeRectangles</function>
|
|
request.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="Events">
|
|
<title>Events</title>
|
|
<para>
|
|
<function>ShapeNotify</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>window</emphasis>: WINDOW
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>kind</emphasis>: SHAPE_KIND
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>shaped</emphasis>: BOOL
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>x, y</emphasis>: INT16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>width</emphasis>,
|
|
<emphasis remap='I'>height</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>time</emphasis>: TIMESTAMP
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
Whenever the client bounding, clip or input shape of a window is modified, a
|
|
<function>ShapeNotify</function>
|
|
event is sent to each client that has used
|
|
<function>ShapeSelectInput</function>
|
|
to request it.
|
|
</para>
|
|
|
|
<para>
|
|
Kind indicates which client region (bounding or clip) has been modified;
|
|
shaped is
|
|
<function>True</function>
|
|
when the window has a client shape of type kind, and is
|
|
<function>False</function>
|
|
when the window no longer has a client shape of this type.
|
|
The x, y, width, and height indicate the extents of the
|
|
current shape. When shaped is
|
|
<function>False</function>
|
|
these will indicate the extents of the default region. The timestamp
|
|
indicates the server time when the shape was changed.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="Encoding">
|
|
<title>Encoding</title>
|
|
<para>
|
|
Please refer to the X11 Protocol Encoding document as this document uses
|
|
conventions established there.
|
|
</para>
|
|
|
|
<para>
|
|
The name of this extension is "SHAPE".
|
|
</para>
|
|
|
|
<sect2 id="New_Types">
|
|
<title>New Types</title>
|
|
|
|
<literallayout class="monospaced">
|
|
SHAPE_KIND
|
|
0 Bounding
|
|
1 Clip
|
|
2 Input
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
SHAPE_OP
|
|
0 Set
|
|
1 Union
|
|
2 Intersect
|
|
3 Subtract
|
|
4 Invert
|
|
</literallayout>
|
|
</sect2>
|
|
|
|
<sect2 id="Requests_2">
|
|
<title>Requests</title>
|
|
<literallayout class="monospaced">
|
|
<function>ShapeQueryVersion</function>
|
|
1 CARD8 opcode
|
|
1 0 shape opcode
|
|
2 1 request length
|
|
|
|
=>
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 length
|
|
2 CARD16 major version
|
|
2 CARD16 minor version
|
|
20 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeRectangles</function>
|
|
1 CARD8 opcode
|
|
1 1 shape opcode
|
|
2 4+2n request length
|
|
1 SHAPE_OP operation
|
|
1 SHAPE_KIND destination kind
|
|
1 ordering
|
|
0 UnSorted
|
|
1 YSorted
|
|
2 YXSorted
|
|
3 YXBanded
|
|
1 unused
|
|
4 WINDOW destination window
|
|
2 INT16 x offset
|
|
2 INT16 y offset
|
|
8n LISTofRECTANGLE rectangles
|
|
</literallayout>
|
|
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeMask</function>
|
|
1 CARD8 opcode
|
|
1 2 shape opcode
|
|
2 5 request length
|
|
1 SHAPE_OP operation
|
|
1 SHAPE_KIND destination kind
|
|
2 unused
|
|
4 WINDOW destination window
|
|
2 INT16 x offset
|
|
2 INT16 y offset
|
|
4 PIXMAP source bitmap
|
|
0 None
|
|
</literallayout>
|
|
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeCombine</function>
|
|
1 CARD8 opcode
|
|
1 3 shape opcode
|
|
2 5 request length
|
|
1 SHAPE_OP operation
|
|
1 SHAPE_KIND destination kind
|
|
1 SHAPE_KIND source kind
|
|
1 unused
|
|
4 WINDOW destination window
|
|
2 INT16 x offset
|
|
2 INT16 y offset
|
|
4 WINDOW source window
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeOffset</function>
|
|
1 CARD8 opcode
|
|
1 4 shape opcode
|
|
2 4 request length
|
|
1 SHAPE_KIND destination kind
|
|
3 unused
|
|
4 WINDOW destination window
|
|
2 INT16 x offset
|
|
2 INT16 y offset
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeQueryExtents</function>
|
|
1 CARD8 opcode
|
|
1 5 shape opcode
|
|
2 2 request length
|
|
4 WINDOW destination window
|
|
|
|
=>
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 reply length
|
|
1 BOOL bounding shaped
|
|
1 BOOL clip shaped
|
|
2 unused
|
|
2 INT16 bounding shape extents x
|
|
2 INT16 bounding shape extents y
|
|
2 CARD16 bounding shape extents width
|
|
2 CARD16 bounding shape extents height
|
|
2 INT16 clip shape extents x
|
|
2 INT16 clip shape extents y
|
|
2 CARD16 clip shape extents width
|
|
2 CARD16 clip shape extents height
|
|
4 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeSelectInput</function>
|
|
1 CARD8 opcode
|
|
1 6 shape opcode
|
|
2 3 request length
|
|
4 WINDOW destination window
|
|
1 BOOL enable
|
|
3 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeInputSelected</function>
|
|
1 CARD8 opcode
|
|
1 7 shape opcode
|
|
2 2 request length
|
|
4 WINDOW destination window
|
|
=>
|
|
1 1 Reply
|
|
1 BOOL enabled
|
|
2 CARD16 sequence number
|
|
4 0 reply length
|
|
24 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>ShapeGetRectangles</function>
|
|
1 CARD8 opcode
|
|
1 8 shape opcode
|
|
2 3 request length
|
|
4 WINDOW window
|
|
1 SHAPE_KIND source kind
|
|
3 unused
|
|
=>
|
|
1 1 Reply
|
|
1 ordering
|
|
0 UnSorted
|
|
1 YSorted
|
|
2 YXSorted
|
|
3 YXBanded
|
|
2 CARD16 sequence number
|
|
4 2n reply length
|
|
4 CARD32 nrects
|
|
20 unused
|
|
8n LISTofRECTANGLE rectangles
|
|
</literallayout>
|
|
</sect2>
|
|
|
|
<sect2 id="Events_2">
|
|
<title>Events</title>
|
|
<literallayout class="monospaced">
|
|
<function>ShapeNotify</function>
|
|
1 CARD8 type (0 + extension event base)
|
|
1 SHAPE_KIND shape kind
|
|
2 CARD16 sequence number
|
|
4 WINDOW affected window
|
|
2 INT16 x value of extents
|
|
2 INT16 y value of extents
|
|
2 CARD16 width of extents
|
|
2 CARD16 height of extents
|
|
4 TIMESTAMP server time
|
|
1 BOOL shaped
|
|
11 unused
|
|
</literallayout>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<glossary id="glossary">
|
|
<title>Glossary</title>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>input region</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The subset of the bounding region which can ``contain'' the
|
|
pointer.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>default input 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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>client input region</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The region associated with a window that is directly modified via this
|
|
extension when specified by
|
|
<function> ShapeInput . </function>
|
|
This region is used in conjunction with the default input region
|
|
and the client bounding region to produce the effective input region.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<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.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>effective input region</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The actual shape of the window on the screen (excluding the
|
|
effects of overlapping windows) which can ``contain'' the pointer.
|
|
When a window has a client input region or
|
|
a client bounding region, the effective input region is the intersection of
|
|
the default input region, the client input region (if any) and the client
|
|
bounding region (if any). Otherwise, the effective input region is the
|
|
same as the default input region.
|
|
<!-- .KE -->
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<!--
|
|
Revision History
|
|
.LP
|
|
1.0 - 1989 - Original Revision
|
|
.LP
|
|
1.0.1 - March 2004 - Corrected misnumbering of \fIShapeInputSelected
|
|
and \fIShapeGetRectangles requests in encoding section.
|
|
.LP
|
|
1.1 - February 2006 - Added Input regions.
|
|
-->
|
|
</glossary>
|
|
</book>
|