specs/shape.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4
   5
   6 <!-- lifted from troff+ms+XMan by doclifter -->
   7 <book id="shape">
   8
   9 <bookinfo>
  10    <title>X Nonrectangular Window Shape Extension Protocol</title>
  11    <subtitle>X.Org Standard</subtitle>
  12    <releaseinfo>Version 1.1</releaseinfo>
  13    <authorgroup>
  14       <author>
  15          <firstname>Keith</firstname><surname>Packard</surname>
  16 <affiliation><orgname>MIT X Consortium Intel Corporation</orgname></affiliation>
  17       </author>
  18       <othercredit>
  19          <firstname>Hideki</firstname><surname>Hiura</surname>
  20          <affiliation><orgname>SunSoft, Inc.</orgname></affiliation>
  21       </othercredit>
  22    </authorgroup>
  23    <corpname>X Consortium Standard</corpname>
  24    <copyright><year>1989</year><holder>The Open Group</holder></copyright>
  25    <copyright><year>2004</year><holder>The Open Group</holder></copyright>
  26    <copyright><year>2006</year><holder>Keith Packard</holder></copyright>
  27    <affiliation><orgname>X Consortium</orgname></affiliation>
  28    <productnumber>X Version 11, Release 7</productnumber>
  29
  30 <legalnotice>
  31
  32 <para>
  33 Permission is hereby granted, free of charge, to any person obtaining a copy
  34 of this software and associated documentation files (the "Software"), to deal
  35 in the Software without restriction, including without limitation the rights
  36 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  37 copies of the Software, and to permit persons to whom the Software is
  38 furnished to do so, subject to the following conditions:
  39 </para>
  40 <para>
  41 The above copyright notice and this permission notice shall be included in
  42 all copies or substantial portions of the Software.
  43 </para>
  44 <para>
  45 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  46 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  47 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  48 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  49 WHETHER IN
  50 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  51 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  52 </para>
  53 <para>
  54 Except as contained in this notice, the name of the copyright holders
  55 shall not be
  56 used in advertising or otherwise to promote the sale, use or other dealings
  57 in this Software without prior written authorization from the
  58 copyright holders.
  59 </para>
  60 </legalnotice>
  61 </bookinfo>
  62
  63 <chapter><title>TITLE</title>
  64 <sect1 id="Overview">
  65 <title>Overview</title>
  66 <para>
  67 <!-- .LP -->
  68 This extension provides arbitrary window and border shapes within the X11
  69 protocol.
  70 </para>
  71 <para>
  72 <!-- .LP -->
  73 The restriction of rectangular windows within the X protocol is a significant
  74 limitation in the implementation of many styles of user interface.  For
  75 example, many transient windows would like to display a "drop shadow'' to
  76 give the illusion of 3 dimensions.  As another example, some user interface
  77 style guides call for buttons with rounded corners; the full simulation of a
  78 nonrectangular shape, particularly with respect to event distribution and
  79 cursor shape, is not possible within the core X protocol.  As a final
  80 example, round clocks and nonrectangular icons are desirable visual addition
  81 to the desktop.
  82 </para>
  83 <para>
  84 <!-- .LP -->
  85 This extension provides mechanisms for changing both the visible and interactive shape of a
  86 window to arbitrary, possibly disjoint, nonrectangular forms.  The intent
  87 of the extension is to supplement the existing semantics, not replace them.
  88 In particular, it is desirable for clients that are unaware of the
  89 extension to still be able to cope reasonably with shaped windows.  For
  90 example, window managers should still be able to negotiate screen
  91 real estate in rectangular pieces.  Toward this end, any shape specified for
  92 a window is clipped by the bounding rectangle for the window as specified by
  93 the window's geometry in the core protocol.  An expected convention would be
  94 that client programs expand their shape to fill the area offered by the
  95 window manager.
  96 </para>
  97 </sect1>
  98
  99 <sect1 id="Description">
 100 <title>Description</title>
 101 <para>
 102 Each window (even with no shapes specified) is defined by three regions:  the
 103 <emphasis remap='I'>bounding region</emphasis>, the <emphasis remap='I'>clip
 104 region</emphasis> and the <emphasis remap='I'>input region</emphasis>.  The
 105 bounding region is the area of the
 106 parent window that the window will occupy (including border). The clip region
 107 is the subset of the bounding region that is available for subwindows and
 108 graphics.  The area between the bounding region and the clip region is defined
 109 to be the border of the window. The input region is the subset of the
 110 bounding region that can "contain" the pointer.
 111 </para>
 112
 113 <para>
 114 A nonshaped window will have a bounding region that is a rectangle
 115 spanning the window, including its border; the clip region will be a rectangle
 116 filling the inside dimensions (not including the border); the input
 117 region will match the bounding region.  In this document,
 118 these areas are referred to as the
 119 <emphasis remap='I'>default bounding region</emphasis>, the
 120 <emphasis remap='I'>default clip region</emphasis> and the
 121 <emphasis remap='I'>default input region</emphasis>.  For a window with inside
 122 size of <emphasis remap='I'>width</emphasis> by
 123 <emphasis remap='I'>height</emphasis> and border width
 124 <emphasis remap='I'>bwidth</emphasis>, the default bounding, clip
 125 and input regions are the rectangles (relative to the window origin):
 126 </para>
 127
 128 <literallayout class="monospaced">
 129 bounding.x = -<emphasis remap='I'>bwidth</emphasis>
 130 bounding.y = -<emphasis remap='I'>bwidth</emphasis>
 131 bounding.width = <emphasis remap='I'>width</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
 132 bounding.height = <emphasis remap='I'>height</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
 133
 134 clip.x = 0
 135 clip.y = 0
 136 clip.width = <emphasis remap='I'>width</emphasis>
 137 clip.height = <emphasis remap='I'>height</emphasis>
 138
 139 input.x = -<emphasis remap='I'>bwidth</emphasis>
 140 input.y = -<emphasis remap='I'>bwidth</emphasis>
 141 input.width = <emphasis remap='I'>width</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
 142 input.height = <emphasis remap='I'>height</emphasis> + 2 * <emphasis remap='I'>bwidth</emphasis>
 143 </literallayout>
 144
 145 <para>
 146 This extension allows a client to modify any combination of the bounding,
 147 clip or input regions by specifying new regions that combine with the default
 148 regions.  These new regions are called the
 149 <emphasis remap='I'>client bounding region</emphasis>,
 150 the <emphasis remap='I'>client clip region</emphasis> and the
 151 <emphasis remap='I'>client input region</emphasis>.  They are specified
 152 relative to the origin of
 153 the window and are always defined by offsets relative to the window origin
 154 (that is, region adjustments are not required when the window is moved).
 155 Three mechanisms for specifying regions are provided:  a list of rectangles,
 156 a bitmap, and an existing bounding or clip region from a window.  This is
 157 modeled on the specification of regions in graphics contexts in the core
 158 protocol and allows a variety of different uses of the extension.
 159 </para>
 160
 161 <para>
 162 When using an existing window shape as an operand in specifying a new shape,
 163 the client region is used, unless none has been set, in which case the
 164 default region is used instead.
 165 </para>
 166
 167 <para>
 168 The <emphasis remap='I'>effective bounding region</emphasis> of a window
 169 is defined to be the intersection of
 170 the client bounding region with the default bounding region.  Any portion of
 171 the client bounding region that is not included in the default bounding
 172 region will not be included in the effective bounding region on the screen.
 173 This means that window managers (or other geometry managers) used to dealing
 174 with rectangular client windows will be able to constrain the client to a
 175 rectangular area of the screen.
 176 </para>
 177
 178 <para>
 179 Construction of the effective bounding region is dynamic; the client bounding
 180 region is not mutated to obtain the effective bounding region.  If a client
 181 bounding region is specified that extends beyond the current default bounding
 182 region, and the window is later enlarged, the effective bounding region will
 183 be enlarged to include more of the client bounding region.
 184 </para>
 185
 186 <para>
 187 The <emphasis remap='I'>effective clip region</emphasis> of a window is defined to be the intersection of the
 188 client clip region with both the default clip region and the client bounding
 189 region.  Any portion of the client clip region that is not included in both
 190 the default clip region and the client bounding region will not be included in
 191 the effective clip region on the screen.
 192 </para>
 193
 194 <para>
 195 Construction of the effective clip region is dynamic; the client clip region is
 196 not mutated to obtain the effective clip region.  If a client clip region is
 197 specified that extends beyond the current default clip region and the
 198 window or its bounding region is later enlarged, the effective clip region will
 199 be enlarged to include more of the client clip region if it is included in
 200 the effective bounding region.
 201 </para>
 202
 203 <para>
 204 The border of a window is defined to be the difference between the effective
 205 bounding region and the effective clip region.  If this region is empty, no
 206 border is displayed.  If this region is nonempty, the border is filled
 207 using the border-tile or border-pixel of the window as specified in the core
 208 protocol.  Note that a window with a nonzero border width will never be able
 209 to draw beyond the default clip region of the window.  Also note that a zero
 210 border width does not prevent a window from having a border, since the clip
 211 shape can still be made smaller than the bounding shape.
 212 </para>
 213
 214 <para>
 215 All output to the window and visible regions of any subwindows will be
 216 clipped to the effective clip region.  The server must not retain window
 217 contents beyond the effective bounding region with backing store.  The window's
 218 origin (for graphics operations, background tiling, and subwindow placement)
 219 is not affected by the existence of a bounding region or clip region.
 220 </para>
 221
 222 <para>
 223 The <emphasis remap='I'>effective input region</emphasis> of a window is
 224 defined to be the intersection of the
 225 client input region with both the default input region and the client bounding
 226 region.  Any portion of the client input region that is not included in both
 227 the default input region and the client bounding region will not be included in
 228 the effective input region on the screen.
 229 </para>
 230 <para>
 231 <!-- .LP -->
 232 Construction of the effective input region is dynamic; the client input region is
 233 not mutated to obtain the effective input region.  If a client input region is
 234 specified that extends beyond the current default input region and the
 235 window or its bounding region is later enlarged, the effective input region will
 236 be enlarged to include more of the client input region if it is included in
 237 the effective bounding region.
 238 </para>
 239 <para>
 240 <!-- .LP  -->
 241 Areas that are inside the default bounding region but outside the effective
 242 bounding region are not part of the window; these areas of the screen will
 243 be occupied by other windows.  Input events that occur within the default
 244 bounding region but outside the effective bounding region will be delivered as
 245 if the window was not occluding the event position.  Events that occur in
 246 a nonrectangular border of a window will be delivered to that window, just
 247 as for events that occur in a normal rectangular border.
 248 </para>
 249 <para>
 250 <!-- .LP -->
 251 An
 252 <function>InputOnly</function>
 253 window can have its bounding or input region set, but it is a
 254 <function>Match</function>
 255 error to attempt to set a clip region on an
 256 <function>InputOnly</function>
 257 window or to specify its clip region as a source to a request
 258 in this extension.
 259 </para>
 260 <para>
 261 <!-- .LP -->
 262 The server must accept changes to the clip and input regions of a root window, but
 263 the server is permitted to ignore requested changes to the bounding region
 264 of a root window.  If the server accepts bounding region changes, the contents
 265 of the screen outside the bounding region are implementation dependent.
 266 </para>
 267 </sect1>
 268
 269 <sect1 id="Types">
 270 <title>Types</title>
 271 <para>
 272 <!-- .LP -->
 273 The following types are used in the request and event definitions in
 274 subsequent sections.
 275 </para>
 276
 277 <para>
 278 SHAPE_KIND:
 279 { <function>Bounding</function>,
 280 <function>Clip</function>,
 281 <function>Input</function> }
 282 </para>
 283
 284 <para>
 285 SHAPE_OP:
 286 { <function>Set</function>,
 287 <function>Union</function>,
 288 <function>Intersect</function>,
 289 <function>Subtract</function>,
 290 <function>Invert</function> }
 291 </para>
 292
 293 <para>
 294 <function>Set</function>
 295 indicates that the region specified as an explicit source in the request is
 296 stored unaltered as the new destination client region.
 297 <function>Union</function>
 298 indicates that the source and destination regions are unioned together to
 299 produce the new destination client region.
 300 <function>Intersect</function>
 301 indicates that the source and destination regions are intersected together to
 302 produce the new destination client region.
 303 <function>Subtract</function>
 304 indicates that the source region is subtracted from the destination region to
 305 produce the new destination region.
 306 <function>Invert</function>
 307 indicates that the destination region is subtracted from the source region to
 308 produce the new destination region.
 309 </para>
 310 </sect1>
 311
 312 <sect1 id="Requests">
 313 <title>Requests</title>
 314 <para>
 315 <function>ShapeQueryVersion</function>
 316 </para>
 317
 318 <para>
 319    =&gt;
 320 </para>
 321
 322 <para>
 323 majorVersion: CARD16
 324 </para>
 325 <para>
 326 minorVersion: CARD16
 327 </para>
 328
 329 <para>
 330 This request can be used to ensure that the server version of the SHAPE
 331 extension is usable by the client.  This document defines major version one
 332 (1), minor version one (1).
 333 </para>
 334
 335 <para>
 336 <function>ShapeRectangles</function>
 337 </para>
 338
 339 <informaltable frame="none">
 340   <tgroup cols='1' align='left'>
 341   <colspec colname='c1' colsep="0" colwidth="1*"/>
 342   <tbody>
 343     <row rowsep="0">
 344       <entry><emphasis remap='I'>dest</emphasis>: WINDOW</entry>
 345     </row>
 346     <row rowsep="0">
 347       <entry><emphasis remap='I'>destKind</emphasis>: SHAPE_KIND</entry>
 348     </row>
 349     <row rowsep="0">
 350       <entry><emphasis remap='I'>op</emphasis>: SHAPE_OP</entry>
 351     </row>
 352     <row rowsep="0">
 353       <entry><emphasis remap='I'>xOff, yOff</emphasis>: INT16</entry>
 354     </row>
 355     <row rowsep="0">
 356       <entry><emphasis remap='I'>rectangles</emphasis>: LISTofRECTANGLES</entry>
 357     </row>
 358     <row rowsep="0">
 359       <entry><emphasis remap='I'>ordering</emphasis>:
 360 { <function>UnSorted</function>,
 361 <function>YSorted</function>,
 362 <function>YXSorted</function>,
 363 <function>YXBanded</function> }
 364       </entry>
 365     </row>
 366     <row rowsep="0">
 367       <entry>
 368 Errors:
 369 <function>Window</function>,
 370 <function>Length</function>,
 371 <function>Match</function>,
 372 <function>Value</function>
 373       </entry>
 374     </row>
 375   </tbody>
 376   </tgroup>
 377 </informaltable>
 378
 379 <para>
 380 This request specifies an array of rectangles, relative to the origin of the
 381 window plus the specified offset (xOff and yOff) that together
 382 define a region.  This region is combined (as specified by the operator
 383 op) with the existing client region (specified by destKind) of the
 384 destination window, and the result is stored as the specified client region of
 385 the destination window.  Note that the list of rectangles can be empty,
 386 specifying an empty region; this is not the same as passing
 387 <function>None</function> to
 388 <function>ShapeMask</function>,
 389 </para>
 390
 391 <para>
 392 If known by the client,
 393 ordering relations on the rectangles can be specified with the ordering
 394 argument.
 395 This may provide faster operation by the server.
 396 The meanings of the ordering values are the same as in the core protocol
 397 <function>SetClipRectangles</function>
 398 request.
 399 If an incorrect ordering is specified,
 400 the server may generate a
 401 <function>Match </function>
 402 error, but it is not required to do so.
 403 If no error is generated,
 404 the graphics results are undefined.
 405 Except for
 406 <function>UnSorted ,</function>
 407 the rectangles should be nonintersecting, or the resulting region will
 408 be undefined.
 409 <function>UnSorted </function>
 410 means that the rectangles are in arbitrary order.
 411 <function>YSorted </function>
 412 means that the rectangles are nondecreasing in their Y origin.
 413 <function>YXSorted </function>
 414 additionally constrains
 415 <function>YSorted </function>
 416 order in that all rectangles with an equal Y origin are
 417 nondecreasing in their X origin.
 418 <function>YXBanded </function>
 419 additionally constrains
 420 <function>YXSorted </function>
 421 by requiring that, for every possible Y scanline,
 422 all rectangles that include that scanline have identical Y origins and Y
 423 extents.
 424 </para>
 425
 426 <para>
 427 <function>ShapeMask</function>
 428 </para>
 429
 430 <informaltable frame="none">
 431   <tgroup cols='1' align='left'>
 432   <colspec colname='c1' colsep="0" colwidth="1*"/>
 433   <tbody>
 434     <row rowsep="0">
 435       <entry>
 436 <emphasis remap='I'>dest</emphasis>: WINDOW
 437 <emphasis remap='I'>destKind</emphasis>: SHAPE_KIND
 438 <emphasis remap='I'>op</emphasis>: SHAPE_OP
 439 <emphasis remap='I'>xOff, yOff</emphasis>: INT16
 440 <emphasis remap='I'>source</emphasis>: PIXMAP or
 441 <function>None</function>
 442       </entry>
 443     </row>
 444     <row rowsep="0">
 445       <entry>
 446 Errors:
 447 <function>Window</function>,
 448 <function>Pixmap</function>,
 449 <function>Match</function>,
 450 <function>Value</function>
 451       </entry>
 452     </row>
 453   </tbody>
 454   </tgroup>
 455 </informaltable>
 456
 457 <para>
 458 The source in this request is a 1-bit deep pixmap, or
 459 <function>None .</function>
 460 If source is
 461 <function>None ,</function>
 462 the specified client region is removed from the window, causing the effective
 463 region to revert to the default region.  The
 464 <function>ShapeNotify</function>
 465 event generated by this request and subsequent
 466 <function>ShapeQueryExtents</function>
 467 will report that a client shape has not been specified.
 468 If a valid pixmap is specified, it is converted
 469 to a region, with bits set to one included in the region and bits set to
 470 zero excluded, and an offset from the window origin as specified by
 471 xOff and yOff.  The resulting region is then combined (as
 472 specified by the operator op) with the existing client region
 473 (indicated by destKind) of the destination window, and the result is
 474 stored as the specified client region of the destination window.  The source
 475 pixmap and destination window must have been created on the same screen,
 476 or else a
 477 <function>Match</function>
 478 error results.
 479 </para>
 480
 481 <para>
 482 <function>ShapeCombine</function>
 483 </para>
 484
 485 <informaltable frame="none">
 486   <tgroup cols='1' align='left'>
 487   <colspec colname='c1' colsep="0" colwidth="1*"/>
 488   <tbody>
 489     <row rowsep="0">
 490       <entry>
 491 <emphasis remap='I'>dest</emphasis>: WINDOW
 492       </entry>
 493     </row>
 494     <row rowsep="0">
 495       <entry>
 496 <emphasis remap='I'>destKind</emphasis>: SHAPE_KIND
 497       </entry>
 498     </row>
 499     <row rowsep="0">
 500       <entry>
 501 <emphasis remap='I'>op</emphasis>: SHAPE_OP
 502       </entry>
 503     </row>
 504     <row rowsep="0">
 505       <entry>
 506 <emphasis remap='I'>xOff, yOff</emphasis>: INT16
 507       </entry>
 508     </row>
 509     <row rowsep="0">
 510       <entry>
 511 <emphasis remap='I'>source</emphasis>: WINDOW
 512       </entry>
 513     </row>
 514     <row rowsep="0">
 515       <entry>
 516 <emphasis remap='I'>sourceKind</emphasis>: SHAPE_KIND
 517       </entry>
 518     </row>
 519     <row rowsep="0">
 520       <entry>
 521 Errors:
 522 <function>Window</function>,
 523 <function>Match</function>,
 524 <function>Value</function>
 525       </entry>
 526     </row>
 527   </tbody>
 528   </tgroup>
 529 </informaltable>
 530
 531 <para>
 532 The client region, indicated by sourceKind, of the source window is
 533 offset from the window origin by xOff and yOff and combined with
 534 the client region, indicated by destKind, of the destination window.
 535 The result is stored as the specified client region of the destination
 536 window.
 537 The source and destination windows must be on the same screen, or else a
 538 <function>Match</function>
 539 error results.
 540 </para>
 541
 542 <para>
 543 <function>ShapeOffset</function>
 544 </para>
 545
 546 <informaltable frame="none">
 547   <tgroup cols='1' align='left'>
 548   <colspec colname='c1' colsep="0" colwidth="1*"/>
 549   <tbody>
 550     <row rowsep="0">
 551       <entry>
 552 <emphasis remap='I'>dest</emphasis>: WINDOW
 553       </entry>
 554     </row>
 555     <row rowsep="0">
 556       <entry>
 557 <emphasis remap='I'>destKind</emphasis>: SHAPE_KIND
 558       </entry>
 559     </row>
 560     <row rowsep="0">
 561       <entry>
 562 <emphasis remap='I'>xOff, yOff</emphasis>: INT16
 563       </entry>
 564     </row>
 565     <row rowsep="0">
 566       <entry>
 567 Errors:
 568 <function>Window</function>,
 569 <function>Match</function>,
 570 <function>Value</function>
 571       </entry>
 572     </row>
 573   </tbody>
 574   </tgroup>
 575 </informaltable>
 576
 577 <para>
 578 The client region, indicated by destKind, is moved relative to its
 579 current position by the amounts xOff and yOff.
 580 </para>
 581
 582 <para>
 583 <function>ShapeQueryExtents</function>
 584 </para>
 585
 586 <informaltable frame="none">
 587   <tgroup cols='1' align='left'>
 588   <colspec colname='c1' colsep="0" colwidth="1*"/>
 589   <tbody>
 590     <row rowsep="0">
 591       <entry>
 592 <emphasis remap='I'>dest</emphasis>: WINDOW
 593       </entry>
 594     </row>
 595   </tbody>
 596   </tgroup>
 597 </informaltable>
 598
 599 <para>
 600    =&gt;
 601 </para>
 602
 603 <informaltable frame="none">
 604   <tgroup cols='1' align='left'>
 605   <colspec colname='c1' colsep="0" colwidth="1*"/>
 606   <tbody>
 607     <row rowsep="0">
 608       <entry>
 609 boundingShaped: BOOL
 610       </entry>
 611     </row>
 612     <row rowsep="0">
 613       <entry>
 614 clipShaped: BOOL
 615       </entry>
 616     </row>
 617     <row rowsep="0">
 618       <entry>
 619 xBoundingShape: INT16
 620       </entry>
 621     </row>
 622     <row rowsep="0">
 623       <entry>
 624 yBoundingShape: INT16
 625       </entry>
 626     </row>
 627     <row rowsep="0">
 628       <entry>
 629 widthBoundingShape: CARD16
 630       </entry>
 631     </row>
 632     <row rowsep="0">
 633       <entry>
 634 heightBoundingShape: CARD16
 635       </entry>
 636     </row>
 637     <row rowsep="0">
 638       <entry>
 639 xClipShape: INT16
 640       </entry>
 641     </row>
 642     <row rowsep="0">
 643       <entry>
 644 yClipShape: INT16
 645       </entry>
 646     </row>
 647     <row rowsep="0">
 648       <entry>
 649 widthClipShape: CARD16
 650       </entry>
 651     </row>
 652     <row rowsep="0">
 653       <entry>
 654 heightClipShape: CARD16
 655       </entry>
 656     </row>
 657     <row rowsep="0">
 658       <entry>
 659 Errors:
 660 <function>Window</function>
 661       </entry>
 662     </row>
 663   </tbody>
 664   </tgroup>
 665 </informaltable>
 666
 667 <para>
 668 The boundingShaped and clipShaped results are
 669 <function>True</function>
 670 if the corresponding client regions have been specified, else they are
 671 <function>False .</function>
 672 The x, y, width, and height values define the extents of the client regions,
 673 when a client region has not been specified, the extents of the
 674 corresponding default region are reported.
 675 </para>
 676
 677 <para>
 678 <function>ShapeSelectInput</function>
 679 </para>
 680
 681 <informaltable frame="none">
 682   <tgroup cols='1' align='left'>
 683   <colspec colname='c1' colsep="0" colwidth="1*"/>
 684   <tbody>
 685     <row rowsep="0">
 686       <entry>
 687 <emphasis remap='I'>window</emphasis>: WINDOW
 688       </entry>
 689     </row>
 690     <row rowsep="0">
 691       <entry>
 692 <emphasis remap='I'>enable</emphasis>: BOOL
 693       </entry>
 694     </row>
 695     <row rowsep="0">
 696       <entry>
 697 Errors:
 698 <function>Window</function>,
 699 <function>Value</function>
 700       </entry>
 701     </row>
 702   </tbody>
 703   </tgroup>
 704 </informaltable>
 705
 706 <para>
 707 Specifying enable as
 708 <function>True</function>
 709 causes the server to send the requesting client a
 710 <function>ShapeNotify</function>
 711 event whenever the bounding, clip or input region of the specified window is
 712 altered by any client.
 713 Specifying enable as
 714 <function>False</function>
 715 causes the server to stop sending such events.
 716 </para>
 717
 718 <para>
 719 <function>ShapeInputSelected</function>
 720 </para>
 721
 722 <informaltable frame="none">
 723   <tgroup cols='1' align='left'>
 724   <colspec colname='c1' colsep="0" colwidth="1*"/>
 725   <tbody>
 726     <row rowsep="0">
 727       <entry>
 728 <emphasis remap='I'>window</emphasis>: WINDOW
 729       </entry>
 730     </row>
 731     <row rowsep="0">
 732       <entry>
 733 =&gt;
 734 enable: BOOL
 735       </entry>
 736     </row>
 737     <row rowsep="0">
 738       <entry>
 739 Errors:
 740 <function>Window</function>
 741       </entry>
 742     </row>
 743   </tbody>
 744   </tgroup>
 745 </informaltable>
 746
 747 <para>
 748 If enable is
 749 <function>True</function>, then
 750 <function>ShapeNotify</function>
 751 events for the window are generated for this client.
 752 </para>
 753
 754 <para>
 755 <function>ShapeGetRectangles</function>
 756 </para>
 757
 758 <informaltable frame="none">
 759   <tgroup cols='1' align='left'>
 760   <colspec colname='c1' colsep="0" colwidth="1*"/>
 761   <tbody>
 762     <row rowsep="0">
 763       <entry>
 764 <emphasis remap='I'>window</emphasis>: WINDOW
 765       </entry>
 766     </row>
 767     <row rowsep="0">
 768       <entry>
 769 <emphasis remap='I'>kind</emphasis>: SHAPE_KIND
 770       </entry>
 771     </row>
 772     <row rowsep="0">
 773       <entry>
 774    =&gt;
 775 rectangles: LISTofRECTANGLE
 776       </entry>
 777     </row>
 778     <row rowsep="0">
 779       <entry>
 780 ordering:
 781 { <function>UnSorted</function>,
 782 <function>YSorted</function>,
 783 <function>YXSorted</function>,
 784 <function>YXBanded</function> }
 785       </entry>
 786     </row>
 787     <row rowsep="0">
 788       <entry>
 789 Errors:
 790 <function>Window,</function>
 791 <function>Match</function>
 792       </entry>
 793     </row>
 794   </tbody>
 795   </tgroup>
 796 </informaltable>
 797
 798 <para>
 799 A list of rectangles describing the region indicated by kind, and the
 800 ordering of those rectangles, is returned.  The meaning of the ordering
 801 values is the same as in the
 802 <function>ShapeRectangles</function>
 803 request.
 804 </para>
 805 </sect1>
 806
 807 <sect1 id="Events">
 808 <title>Events</title>
 809 <para>
 810 <function>ShapeNotify</function>
 811 </para>
 812
 813 <informaltable frame="none">
 814   <tgroup cols='1' align='left'>
 815   <colspec colname='c1' colsep="0" colwidth="1*"/>
 816   <tbody>
 817     <row rowsep="0">
 818       <entry>
 819 <emphasis remap='I'>window</emphasis>: WINDOW
 820       </entry>
 821     </row>
 822     <row rowsep="0">
 823       <entry>
 824 <emphasis remap='I'>kind</emphasis>: SHAPE_KIND
 825       </entry>
 826     </row>
 827     <row rowsep="0">
 828       <entry>
 829 <emphasis remap='I'>shaped</emphasis>: BOOL
 830       </entry>
 831     </row>
 832     <row rowsep="0">
 833       <entry>
 834 <emphasis remap='I'>x, y</emphasis>: INT16
 835       </entry>
 836     </row>
 837     <row rowsep="0">
 838       <entry>
 839 <emphasis remap='I'>width</emphasis>,
 840 <emphasis remap='I'>height</emphasis>: CARD16
 841       </entry>
 842     </row>
 843     <row rowsep="0">
 844       <entry>
 845 <emphasis remap='I'>time</emphasis>: TIMESTAMP
 846       </entry>
 847     </row>
 848   </tbody>
 849   </tgroup>
 850 </informaltable>
 851
 852 <para>
 853 Whenever the client bounding, clip or input shape of a window is modified, a
 854 <function>ShapeNotify</function>
 855 event is sent to each client that has used
 856 <function>ShapeSelectInput</function>
 857 to request it.
 858 </para>
 859
 860 <para>
 861 Kind indicates which client region (bounding or clip) has been modified;
 862 shaped is
 863 <function>True</function>
 864 when the window has a client shape of type kind, and is
 865 <function>False</function>
 866 when the window no longer has a client shape of this type.
 867 The x, y, width, and height indicate the extents of the
 868 current shape.  When shaped is
 869 <function>False</function>
 870 these will indicate the extents of the default region.  The timestamp
 871 indicates the server time when the shape was changed.
 872 </para>
 873 </sect1>
 874
 875 <sect1 id="Encoding">
 876 <title>Encoding</title>
 877 <para>
 878 Please refer to the X11 Protocol Encoding document as this document uses
 879 conventions established there.
 880 </para>
 881
 882 <para>
 883 The name of this extension is "SHAPE".
 884 </para>
 885
 886 <sect2 id="New_Types">
 887 <title>New Types</title>
 888
 889 <literallayout class="monospaced">
 890 SHAPE_KIND
 891      0     Bounding
 892      1     Clip
 893      2     Input
 894 </literallayout>
 895
 896 <literallayout class="monospaced">
 897 SHAPE_OP
 898      0     Set
 899      1     Union
 900      2     Intersect
 901      3     Subtract
 902      4     Invert
 903 </literallayout>
 904 </sect2>
 905
 906 <sect2 id="Requests_2">
 907 <title>Requests</title>
 908 <literallayout class="monospaced">
 909 <function>ShapeQueryVersion</function>
 910      1     CARD8              opcode
 911      1     0                  shape opcode
 912      2     1                  request length
 913
 914 =&gt;
 915      1     1                  Reply
 916      1                        unused
 917      2     CARD16             sequence number
 918      4     0                  length
 919      2     CARD16             major version
 920      2     CARD16             minor version
 921      20                       unused
 922 </literallayout>
 923
 924 <literallayout class="monospaced">
 925 <function>ShapeRectangles</function>
 926      1     CARD8              opcode
 927      1     1                  shape opcode
 928      2     4+2n               request length
 929      1     SHAPE_OP           operation
 930      1     SHAPE_KIND         destination kind
 931      1                        ordering
 932            0     UnSorted
 933            1     YSorted
 934            2     YXSorted
 935            3     YXBanded
 936      1                        unused
 937      4     WINDOW             destination window
 938      2     INT16              x offset
 939      2     INT16              y offset
 940      8n    LISTofRECTANGLE    rectangles
 941 </literallayout>
 942
 943
 944 <literallayout class="monospaced">
 945 <function>ShapeMask</function>
 946      1     CARD8              opcode
 947      1     2                  shape opcode
 948      2     5                  request length
 949      1     SHAPE_OP           operation
 950      1     SHAPE_KIND         destination kind
 951      2                        unused
 952      4     WINDOW             destination window
 953      2     INT16              x offset
 954      2     INT16              y offset
 955      4     PIXMAP             source bitmap
 956            0     None
 957 </literallayout>
 958
 959
 960 <literallayout class="monospaced">
 961 <function>ShapeCombine</function>
 962      1     CARD8              opcode
 963      1     3                  shape opcode
 964      2     5                  request length
 965      1     SHAPE_OP           operation
 966      1     SHAPE_KIND         destination kind
 967      1     SHAPE_KIND         source kind
 968      1                        unused
 969      4     WINDOW             destination window
 970      2     INT16              x offset
 971      2     INT16              y offset
 972      4     WINDOW             source window
 973 </literallayout>
 974
 975 <literallayout class="monospaced">
 976 <function>ShapeOffset</function>
 977      1     CARD8              opcode
 978      1     4                  shape opcode
 979      2     4                  request length
 980      1     SHAPE_KIND         destination kind
 981      3                        unused
 982      4     WINDOW             destination window
 983      2     INT16              x offset
 984      2     INT16              y offset
 985 </literallayout>
 986
 987 <literallayout class="monospaced">
 988 <function>ShapeQueryExtents</function>
 989      1     CARD8              opcode
 990      1     5                  shape opcode
 991      2     2                  request length
 992      4     WINDOW             destination window
 993
 994  =&gt;
 995      1     1                  Reply
 996      1                        unused
 997      2     CARD16             sequence number
 998      4     0                  reply length
 999      1     BOOL               bounding shaped
1000      1     BOOL               clip shaped
1001      2                        unused
1002      2     INT16              bounding shape extents x
1003      2     INT16              bounding shape extents y
1004      2     CARD16             bounding shape extents width
1005      2     CARD16             bounding shape extents height
1006      2     INT16              clip shape extents x
1007      2     INT16              clip shape extents y
1008      2     CARD16             clip shape extents width
1009      2     CARD16             clip shape extents height
1010      4                        unused
1011 </literallayout>
1012
1013 <literallayout class="monospaced">
1014 <function>ShapeSelectInput</function>
1015      1     CARD8              opcode
1016      1     6                  shape opcode
1017      2     3                  request length
1018      4     WINDOW             destination window
1019      1     BOOL               enable
1020      3                        unused
1021 </literallayout>
1022
1023 <literallayout class="monospaced">
1024 <function>ShapeInputSelected</function>
1025      1     CARD8              opcode
1026      1     7                  shape opcode
1027      2     2                  request length
1028      4     WINDOW             destination window
1029  =&gt;
1030      1     1                  Reply
1031      1     BOOL               enabled
1032      2     CARD16             sequence number
1033      4     0                  reply length
1034      24                       unused
1035 </literallayout>
1036
1037 <literallayout class="monospaced">
1038 <function>ShapeGetRectangles</function>
1039      1     CARD8              opcode
1040      1     8                  shape opcode
1041      2     3                  request length
1042      4     WINDOW             window
1043      1     SHAPE_KIND         source kind
1044      3                        unused
1045  =&gt;
1046      1     1                  Reply
1047      1                        ordering
1048            0     UnSorted
1049            1     YSorted
1050            2     YXSorted
1051            3     YXBanded
1052      2     CARD16             sequence number
1053      4     2n                 reply length
1054      4     CARD32             nrects
1055      20                       unused
1056      8n    LISTofRECTANGLE    rectangles
1057 </literallayout>
1058 </sect2>
1059
1060 <sect2 id="Events_2">
1061 <title>Events</title>
1062 <literallayout class="monospaced">
1063 <function>ShapeNotify</function>
1064      1     CARD8               type (0 + extension event base)
1065      1     SHAPE_KIND          shape kind
1066      2     CARD16              sequence number
1067      4     WINDOW              affected window
1068      2     INT16               x value of extents
1069      2     INT16               y value of extents
1070      2     CARD16              width of extents
1071      2     CARD16              height of extents
1072      4     TIMESTAMP           server time
1073      1     BOOL                shaped
1074      11                        unused
1075 </literallayout>
1076 </sect2>
1077 </sect1>
1078 </chapter>
1079
1080 <glossary id="glossary">
1081 <title>Glossary</title>
1082 <glossentry>
1083   <glossterm>bounding region</glossterm>
1084   <glossdef>
1085 <para>
1086 The area of the parent window that this window will occupy.  This area is
1087 divided into two parts:  the border and the interior.
1088 <!-- .KE -->
1089     </para>
1090   </glossdef>
1091 </glossentry>
1092 <glossentry>
1093   <glossterm>clip region</glossterm>
1094   <glossdef>
1095 <para>
1096 The interior of the window, as a subset of the bounding region.  This
1097 region describes the area that will be painted with the window background
1098 when the window is cleared, will contain all graphics output to the window,
1099 and will clip any subwindows.
1100 <!-- .KE -->
1101     </para>
1102   </glossdef>
1103 </glossentry>
1104 <glossentry>
1105   <glossterm>input region</glossterm>
1106   <glossdef>
1107 <para>
1108 The subset of the bounding region which can ``contain'' the
1109 pointer.
1110 <!-- .KE -->
1111     </para>
1112   </glossdef>
1113 </glossentry>
1114 <glossentry>
1115   <glossterm>default bounding region</glossterm>
1116   <glossdef>
1117 <para>
1118 The rectangular area, as described by the core protocol window size, that
1119 covers the interior of the window and its border.
1120 <!-- .KE -->
1121     </para>
1122   </glossdef>
1123 </glossentry>
1124 <glossentry>
1125   <glossterm>default clip region</glossterm>
1126   <glossdef>
1127 <para>
1128 The rectangular area, as described by the core protocol window size, that
1129 covers the interior of the window and excludes the border.
1130 <!-- .KE -->
1131     </para>
1132   </glossdef>
1133 </glossentry>
1134 <glossentry>
1135   <glossterm>default input region</glossterm>
1136   <glossdef>
1137 <para>
1138 The rectangular area, as described by the core protocol window size, that
1139 covers the interior of the window and its border.
1140 <!-- .KE -->
1141     </para>
1142   </glossdef>
1143 </glossentry>
1144 <glossentry>
1145   <glossterm>client bounding region</glossterm>
1146   <glossdef>
1147 <para>
1148 The region associated with a window that is directly modified via this
1149 extension when specified by
1150 <function> ShapeBounding .</function>
1151 This region is used in conjunction with the default bounding region
1152 to produce the effective bounding region.
1153 <!-- .KE -->
1154     </para>
1155   </glossdef>
1156 </glossentry>
1157 <glossentry>
1158   <glossterm>client clip region</glossterm>
1159   <glossdef>
1160 <para>
1161 The region associated with a window that is directly modified via this
1162 extension when specified by
1163 <function> ShapeClip . </function>
1164 This region is used in conjunction with the default clip region
1165 and the client bounding region to produce the effective clip region.
1166 <!-- .KE -->
1167     </para>
1168   </glossdef>
1169 </glossentry>
1170 <glossentry>
1171   <glossterm>client input region</glossterm>
1172   <glossdef>
1173 <para>
1174 The region associated with a window that is directly modified via this
1175 extension when specified by
1176 <function> ShapeInput . </function>
1177 This region is used in conjunction with the default input region
1178 and the client bounding region to produce the effective input region.
1179 <!-- .KE -->
1180     </para>
1181   </glossdef>
1182 </glossentry>
1183 <glossentry>
1184   <glossterm>effective bounding region</glossterm>
1185   <glossdef>
1186 <para>
1187 The actual shape of the window on the screen, including border and interior
1188 (but excluding the effects of overlapping windows).  When a window has a client
1189 bounding region, the effective bounding region is the intersection of the
1190 default bounding region and the client bounding region.  Otherwise, the
1191 effective bounding region is the same as the default bounding region.
1192 <!-- .KE -->
1193     </para>
1194   </glossdef>
1195 </glossentry>
1196 <glossentry>
1197   <glossterm>effective clip region</glossterm>
1198   <glossdef>
1199 <para>
1200 The actual shape of the interior of the window on the screen (excluding the
1201 effects of overlapping windows).  When a window has a client clip region or
1202 a client bounding region, the effective clip region is the intersection of
1203 the default clip region, the client clip region (if any) and the client
1204 bounding region (if any).  Otherwise, the effective clip region is the
1205 same as the default clip region.
1206 <!-- .KE -->
1207     </para>
1208   </glossdef>
1209 </glossentry>
1210 <glossentry>
1211   <glossterm>effective input region</glossterm>
1212   <glossdef>
1213 <para>
1214 The actual shape of the window on the screen (excluding the
1215 effects of overlapping windows) which can ``contain'' the pointer.
1216 When a window has a client input region or
1217 a client bounding region, the effective input region is the intersection of
1218 the default input region, the client input region (if any) and the client
1219 bounding region (if any).  Otherwise, the effective input region is the
1220 same as the default input region.
1221 <!-- .KE -->
1222     </para>
1223   </glossdef>
1224 </glossentry>
1225 <!--
1226 Revision History
1227 .LP
1228 1.0 - 1989 - Original Revision
1229 .LP
1230 1.0.1 - March 2004 - Corrected misnumbering of \fIShapeInputSelected
1231 and \fIShapeGetRectangles requests in encoding section.
1232 .LP
1233 1.1 - February 2006 - Added Input regions.
1234 -->
1235 </glossary>
1236 </book>