home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / extensions / shape.ms < prev    next >
Encoding:
Text File  |  1991-07-28  |  27.0 KB  |  1,003 lines
  1. .\" Use -ms and macros.t
  2. .\" $XConsortium: shape.ms,v 1.13 91/07/28 15:49:51 rws Exp $
  3. .EH ''''
  4. .OH ''''
  5. .EF ''''
  6. .OF ''''
  7. .ps 10
  8. .nr PS 10
  9. \&
  10. .sp 8
  11. .ce 1
  12. \s+2\fBX11 NONRECTANGULAR WINDOW SHAPE EXTENSION\fP\s-2
  13. .sp 3
  14. .ce 3
  15. Version 1.0
  16. MIT X Consortium Standard
  17. X Version 11, Release 5
  18. .sp 6
  19. .ce 4
  20. \s-1Keith Packard
  21. .sp 6p
  22. X Consortium
  23. Laboratory for Computer Science
  24. Massachusetts Institute of Technology\s+1
  25. .ps 9
  26. .nr PS 9
  27. .sp 8
  28. .LP
  29. Copyright \(co 1989 by the Massachusetts Institute of Technology
  30. .LP
  31. Permission to use, copy, modify, and distribute this documentation for any
  32. purpose and without fee is hereby granted, provided that the above copyright
  33. notice and this permission notice appear in all copies.  MIT makes no
  34. representations about the suitability for any purpose of the information in
  35. this document.  This documentation is provided ``as is'' without express or
  36. implied warranty.
  37. .ps 10
  38. .nr PS 10
  39. .bp 1
  40. .EH ''X11 Nonrectangular Window Shape Extension''
  41. .OH ''X11 Nonrectangular Window Shape Extension''
  42. .EF ''\fB % \fP''
  43. .OF ''\fB % \fP''
  44. .NH 1
  45. Overview
  46. .LP
  47. This extension provides arbitrary window and border shapes within the X11
  48. protocol.
  49. .LP
  50. The restriction of rectangular windows within the X protocol is a significant
  51. limitation in the implementation of many styles of user interface.  For
  52. example, many transient windows would like to display a ``drop shadow'' to
  53. give the illusion of 3 dimensions.  As another example, some user interface
  54. style guides call for buttons with rounded corners; the full simulation of a
  55. nonrectangular shape, particularly with respect to event distribution and
  56. cursor shape, is not possible within the core X protocol.  As a final
  57. example, round clocks and nonrectangular icons are desirable visual addition
  58. to the desktop.
  59. .LP
  60. This extension provides mechanisms for changing the visible shape of a
  61. window to an arbitrary, possibly disjoint, nonrectangular form.  The intent
  62. of the extension is to supplement the existing semantics, not replace them.
  63. In particular, it is desirable for clients which are unaware of the
  64. extension to still be able to cope reasonably with shaped windows.  For
  65. example, window managers should still be able to negotiate screen
  66. real-estate in rectangular pieces.  Toward this end, any shape specified for
  67. a window is clipped by the bounding rectangle for the window as specified by
  68. the window's geometry in the core protocol.  An expected convention would be
  69. that client programs expand their shape to fill the area offered by the
  70. window manager.
  71. .NH 1
  72. Description
  73. .LP
  74. Each window (even with no shapes specified) is defined by two regions:  the
  75. \fBbounding region\fP and the \fBclip region\fP.  The bounding region is the area of the
  76. parent window which the window will occupy (including border). The clip region
  77. is the subset of the bounding region which is available for sub-windows and
  78. graphics.  The area between the bounding region and the clip region is defined
  79. to be the border of the window.
  80. .LP
  81. A non-shaped window will have a bounding region which is a rectangle
  82. spanning the window including its border; the clip region will be a rectangle
  83. filling the inside dimensions (not including the border).  In this document,
  84. these areas are referred to as the \fBdefault bounding region\fP and the
  85. \fBdefault clip region\fP.  For a window with inside size of \fIwidth\fP by
  86. \fIheight\fP and border width \fIbwidth\fP, the default bounding and clip
  87. regions are the rectangles (relative to the window origin):
  88. .IP
  89. bounding.x = -\fIbwidth\fP
  90. .br
  91. bounding.y = -\fIbwidth\fP
  92. .br
  93. bounding.width = \fIwidth\fP + 2 * \fIbwidth\fP
  94. .br
  95. bounding.height = \fIheight\fP + 2 * \fIbwidth\fP
  96. .sp
  97. clip.x = 0
  98. .br
  99. clip.y = 0
  100. .br
  101. clip.width = \fIwidth\fP
  102. .br
  103. clip.height = \fIheight\fP
  104. .LP
  105. This extension allows a client to modify either or both of the bounding or
  106. clip regions by specifying new regions which combine with the default
  107. regions.  These new regions are called the \fBclient bounding region\fP and
  108. the \fBclient clip region\fP.  They are specified relative to the origin of
  109. the window, and are always defined by offsets relative to the window origin
  110. (that is, region adjustments are not required when the window is moved).
  111. Three mechanisms for specifying regions are provided:  a list of rectangles,
  112. a bitmap, and an existing bounding or clip region from a window.  This is
  113. modeled on the specification of regions in graphics contexts in the core
  114. protocol, and allows a variety of different uses of the extension.
  115. .LP
  116. When using an existing window shape as an operand in specifying a new shape,
  117. the client region is used, unless none has been set in which case the
  118. default region is used instead.
  119. .LP
  120. The \fBeffective bounding region\fP of a window is defined to be the intersection of
  121. the client bounding region with the default bounding region.  Any portion of
  122. the client bounding region which is not included in the default bounding
  123. region will not be included in the effective bounding region on the screen.
  124. This means that window managers (or other geometry managers) used to dealing
  125. with rectangular client windows will be able to constrain the client to a
  126. rectangular area of the screen.
  127. .LP
  128. Construction of the effective bounding region is dynamic; the client bounding
  129. region is not mutated to obtain the effective bounding region.  If a client
  130. bounding region is specified which extends beyond the current default bounding
  131. region, and the window is later enlarged, the effective bounding region will
  132. be enlarged to include more of the client bounding region.
  133. .LP
  134. The \fBeffective clip region\fP of a window is defined to be the intersection of the
  135. client clip region with both the default clip region and the client bounding
  136. region.  Any portion of the client clip region which is not included in both
  137. the default clip region and the client bounding region will not be included in
  138. the effective clip region on the screen.
  139. .LP
  140. Construction of the effective clip region is dynamic; the client clip region is
  141. not mutated to obtain the effective clip region.  If a client clip region is
  142. specified which extends beyond the current default clip region, and the
  143. window or its bounding region is later enlarged, the effective clip region will
  144. be enlarged to include more of the client clip region if it is included in
  145. the effective bounding region.
  146. .LP
  147. The border of a window is defined to be the difference between the effective
  148. bounding region and the effective clip region.  If this region is empty, no
  149. border is displayed.  If this region is non-empty, the border is filled
  150. using the border-tile or border-pixel of the window as specified in the core
  151. protocol.  Note that a window with a nonzero border width will never be able
  152. to draw beyond the default clip region of the window.  Also note that a zero
  153. border width does not prevent a window from having a border, since the clip
  154. shape can still be made smaller than the bounding shape.
  155. .LP
  156. All output to the window, and visible regions of any subwindows, will be
  157. clipped to the effective clip region.  The server must not retain window
  158. contents beyond the effective bounding region with backing store.  The window's
  159. origin (for graphics operations, background tiling, and subwindow placement)
  160. is not affected by the existence of a bounding region or clip region.
  161. .LP 
  162. Areas which are inside the default bounding region but outside the effective
  163. bounding region are not part of the window; these areas of the screen will
  164. be occupied by other windows.  Input events which occur within the default
  165. bounding region but outside the effective bounding region will be delivered as
  166. if the window was not occluding the event position.  Events which occur in
  167. a nonrectangular border of a window will be delivered to that window, just
  168. as for events which occur in a normal rectangular border.
  169. .LP
  170. An InputOnly window can have its bounding region set, but it is a
  171. .PN Match
  172. error to attempt to set a clip region on an InputOnly window, or to
  173. specify its clip region as a source to a request in this extension.
  174. .LP
  175. The server must accept changes to the clip region of a root window, but
  176. the server is permitted to ignore requested changes to the bounding region
  177. of a root window.  If the server accepts bounding region changes, the contents
  178. of the screen outside the bounding region are implementation dependent.
  179. .NH 1
  180. Types
  181. .LP
  182. The following types are used in the request and event definitions in
  183. subsequent sections.
  184. .LP
  185. SHAPE_KIND:
  186. .Pn { Bounding ,
  187. .PN Clip }
  188. .LP
  189. SHAPE_OP:
  190. .Pn { Set ,
  191. .PN Union ,
  192. .PN Intersect ,
  193. .PN Subtract ,
  194. .PN Invert }
  195. .LP
  196. .PN Set
  197. means that the region specified as an explicit source in the request is stored
  198. unaltered as the new destination client region.
  199. .PN Union
  200. means that the source and destination regions are unioned together to produce
  201. the new destination client region.
  202. .PN Intersect
  203. means that the source and destination regions are intersected together to
  204. produce the new destination client region.
  205. .PN Subtract
  206. means that the source region is subtracted from the destination region to
  207. produce the new destination region.
  208. .PN Invert
  209. means that the destination region is subtracted from the source region to
  210. produce the new destination region.
  211. .NH 1
  212. Requests
  213. .LP
  214. .PN "ShapeQueryVersion"
  215. .LP
  216.    =>
  217. .IP
  218. \fImajorVersion\fP\^: CARD16
  219. .br
  220. \fIminorVersion\fP\^: CARD16
  221. .IP
  222. This request can be used to ensure that the server version of the SHAPE
  223. extension is usable by the client.  This document defines major version one
  224. (1), minor version zero (0).
  225. .LP
  226. .PN "ShapeRectangles"
  227. .IP
  228. \fIdest\fP\^: WINDOW
  229. .br
  230. \fIdestKind\fP\^: SHAPE_KIND
  231. .br
  232. \fIop\fP\^: SHAPE_OP
  233. .br
  234. \fIxOff, yOff\fP\^: INT16
  235. .br
  236. \fIrectangles\fP\^: LISTofRECTANGLES
  237. .br
  238. \fIordering\fP\^: {UnSorted, YSorted, YXSorted, YXBanded}
  239. .IP
  240. Errors:
  241. .PN Window ,
  242. .PN Length ,
  243. .PN Match ,
  244. .PN Value
  245. .IP
  246. This request specifies an array of rectangles, relative to the origin of the
  247. window plus the specified offset (\fIxOff\fP and \fIyOff\fP) which together
  248. define a region.  This region is combined (as specified by the operator
  249. \fIop\fP) with the existing client region (specified by \fIdestKind\fP) of the
  250. destination window, and the result is stored as the specified client region of
  251. the destination window.  Note that the list of rectangles can be empty,
  252. specifying an empty region; this is not the same as passing
  253. .PN None
  254. to
  255. .PN ShapeMask .
  256. .IP
  257. If known by the client, 
  258. ordering relations on the rectangles can be specified with the ordering 
  259. argument.
  260. This may provide faster operation by the server.
  261. The meanings of the ordering values are the same as in the core protocol
  262. .PN SetClipRectangles
  263. request.
  264. If an incorrect ordering is specified, 
  265. the server may generate a 
  266. .PN Match 
  267. error, but it is not required to do so.
  268. If no error is generated,
  269. the graphics results are undefined.
  270. Except for
  271. .PN UnSorted ,
  272. the rectangles should be nonintersecting, or the resulting region will
  273. be undefined.
  274. .PN UnSorted 
  275. means that the rectangles are in arbitrary order.
  276. .PN YSorted 
  277. means that the rectangles are nondecreasing in their Y origin.
  278. .PN YXSorted 
  279. additionally constrains 
  280. .PN YSorted 
  281. order in that all rectangles with an equal Y origin are
  282. nondecreasing in their X origin.
  283. .PN YXBanded 
  284. additionally constrains 
  285. .PN YXSorted 
  286. by requiring that, for every possible Y scanline,
  287. all rectangles that include that scanline have identical Y origins and Y
  288. extents.
  289. .LP
  290. .PN "ShapeMask"
  291. .IP
  292. \fIdest\fP\^: WINDOW
  293. .br
  294. \fIdestKind\fP\^: SHAPE_KIND
  295. .br
  296. \fIop\fP\^: SHAPE_OP
  297. .br
  298. \fIxOff, yOff\fP\^: INT16
  299. .br
  300. \fIsource\fP\^: PIXMAP or None
  301. .IP
  302. Errors:
  303. .PN Window ,
  304. .PN Pixmap ,
  305. .PN Match ,
  306. .PN Value
  307. .IP
  308. The source in this request is a 1-bit deep pixmap, or
  309. .PN None .
  310. If \fIsource\fP is 
  311. .PN None ,
  312. the specified client region is removed from the window causing the effective
  313. region to revert to the default region.  The ShapeNotify event generated by
  314. this request and subsequent ShapeQueryExtents will report that a client
  315. shape has not been specified.  If a valid pixmap is specified, it is converted
  316. to a region, with bits set to one included in the region and bits set to
  317. zero excluded, and an offset from the window origin as specified by
  318. \fIxOff\fP and \fIyOff\fP.  The resulting region is then combined (as
  319. specified by the operator \fIop\fP) with the existing client region
  320. (indicated by \fIdestKind\fP) of the destination window, and the result is
  321. stored as the specified client region of the destination window.  The source
  322. pixmap and destination window must have been created on the same screen or else
  323. a
  324. .PN Match
  325. error results.
  326. .LP
  327. .PN "ShapeCombine"
  328. .IP
  329. \fIdest\fP\^: WINDOW
  330. .br
  331. \fIdestKind\fP\^: SHAPE_KIND
  332. .br
  333. \fIop\fP\^: SHAPE_OP
  334. .br
  335. \fIxOff, yOff\fP\^: INT16
  336. .br
  337. \fIsource\fP\^: WINDOW
  338. .br
  339. \fIsourceKind\fP\^: SHAPE_KIND
  340. .IP
  341. Errors:
  342. .PN Window ,
  343. .PN Match ,
  344. .PN Value
  345. .IP
  346. The client region, indicated by \fIsourceKind\fP, of the source window is
  347. offset from the window origin by \fIxOff\fP and \fIyOff\fP and combined with
  348. the client region, indicated by \fIdestKind\fP, of the destination window.
  349. The result is stored as the specified client region of the destination
  350. window.
  351. The source and destination windows must be on the same screen or else a
  352. .PN Match
  353. error results.
  354. .LP
  355. .PN "ShapeOffset"
  356. .IP
  357. \fIdest\fP\^: WINDOW
  358. .br
  359. \fIdestKind\fP\^: SHAPE_KIND
  360. .br
  361. \fIxOff, yOff\fP\^: INT16
  362. .IP
  363. Errors:
  364. .PN Window ,
  365. .PN Match ,
  366. .PN Value
  367. .IP
  368. The client region, indicated by \fIdestKind\fP, is moved relative to its
  369. current position by the amounts \fIxOff\fP and \fIyOff\fP.
  370. .LP
  371. .PN "ShapeQueryExtents"
  372. .IP
  373. \fIdest\fP\^: WINDOW
  374. .LP
  375.    =>
  376. .IP
  377. \fIboundingShaped\fP\^: BOOL
  378. .br
  379. \fIclipShaped\fP\^: BOOL
  380. .br
  381. \fIxBoundingShape\fP\^: INT16
  382. .br
  383. \fIyBoundingShape\fP\^: INT16
  384. .br
  385. \fIwidthBoundingShape\fP\^: CARD16
  386. .br
  387. \fIheightBoundingShape\fP\^: CARD16
  388. .br
  389. \fIxClipShape\fP\^: INT16
  390. .br
  391. \fIyClipShape\fP\^: INT16
  392. .br
  393. \fIwidthClipShape\fP\^: CARD16
  394. .br
  395. \fIheightClipShape\fP\^: CARD16
  396. .IP
  397. Errors:
  398. .PN Window
  399. .IP
  400. The \fIboundingShaped\fP and \fIclipShaped\fP results are 
  401. .PN True
  402. if the corresponding client regions have been specified, else they are
  403. .PN False .
  404. The x, y, width, and height values define the extents of the client regions,
  405. when a client region has not been specified, the extents of the
  406. corresponding default region are reported.
  407. .LP
  408. .PN "ShapeSelectInput"
  409. .IP
  410. \fIwindow\fP\^: WINDOW
  411. .br
  412. \fIenable\fP\^: BOOL
  413. .IP
  414. Errors:
  415. .PN Window ,
  416. .PN Value
  417. .IP
  418. Specifying \fIenable\fP as
  419. .PN True
  420. causes the server to send the requesting client a
  421. .PN ShapeNotify
  422. event whenever the bounding or clip region of the specified window is
  423. altered by any client.
  424. Specifying \fIenable\fP as
  425. .PN False
  426. causes the server to stop sending such events.
  427. .LP
  428. .PN "ShapeInputSelected"
  429. .IP
  430. \fIwindow\fP\^: WINDOW
  431. .LP
  432.    =>
  433. .IP
  434. \fIenable\fP\^: BOOL
  435. .IP
  436. Errors:
  437. .PN Window
  438. .IP
  439. If \fIenable\fP is
  440. .PN True
  441. then
  442. .PN ShapeNotify
  443. events for the window are generated for this client.
  444. .LP
  445. .PN "ShapeGetRectangles"
  446. .IP
  447. \fIwindow\fP\^: WINDOW
  448. .br
  449. \fIkind\fP\^: SHAPE_KIND
  450. .LP
  451.    =>
  452. .IP
  453. \fIrectangles\fP: LISTofRECTANGLE
  454. .br
  455. \fIordering\fP\^: {UnSorted, YSorted, YXSorted, YXBanded}
  456. .IP
  457. Errors:
  458. .PN Window,
  459. .PN Match
  460. .IP
  461. A list of rectangles describing the region indicated by \fIkind\fP, and the
  462. ordering of those rectangles, is returned.  The meaning of the \fIordering\fP
  463. values is the same as in the
  464. .PN ShapeRectangles
  465. request.
  466. .NH 1
  467. Events
  468. .LP
  469. .PN "ShapeNotify"
  470. .IP
  471. \fIwindow\fP\^: WINDOW
  472. .br
  473. \fIkind\fP\^: SHAPE_KIND
  474. .br
  475. \fIshaped\fP\^: BOOL
  476. .br
  477. \fIx\fP, \fIy\fP\^: INT16
  478. .br
  479. \fIwidth\fP, \fIheight\fP\^: CARD16
  480. .br
  481. \fItime\fP\^: TIMESTAMP
  482. .IP
  483. Whenever the client bounding or clip shape of a window is modified, a
  484. .PN ShapeNotify
  485. event is sent to each client which has used
  486. .PN ShapeSelectInput
  487. to request it.
  488. .IP
  489. \fIkind\fP indicates which client region (bounding or clip) has been modified.
  490. \fIshaped\fP is
  491. .PN True
  492. when the window has a client shape of type \fIkind\fP, and is
  493. .PN False
  494. when the window no longer has a client shape of this type.
  495. \fIx\fP, \fIy\fP, \fIwidth\fP and \fIheight\fP indicate the extents of the
  496. current shape.  When \fIshaped\fP is
  497. .PN False
  498. these will indicate the extents of the default region.  The timestamp
  499. indicates the server time when the shape was changed.
  500. .NH 1
  501. Encoding
  502. .LP
  503. Please refer to the X11 Protocol Encoding document as this document uses
  504. conventions established there.
  505. .LP
  506. The name of this extension is ``SHAPE''.
  507. .LP
  508. .SH
  509. \s+2New types\s-2
  510. .LP
  511. .Ds 0
  512. .TA .75i 1.75i
  513. .ta .75i 1.75i
  514. .R
  515. SHAPE_KIND
  516.     0    Bounding
  517.     1    Clip
  518. .De
  519. .LP
  520. .Ds 0
  521. .TA .75i 1.75i
  522. .ta .75i 1.75i
  523. .R
  524. SHAPE_OP
  525.     0    Set
  526.     1    Union
  527.     2    Intersect
  528.     3    Subtract
  529.     4    Invert
  530. .De
  531. .SH
  532. \s+2Requests\s-2
  533. .LP
  534. .Ds 0
  535. .TA .2i .5i 1.5i 2.5i
  536. .ta .2i .5i 1.5i 2.5i
  537. .R
  538. .PN ShapeQueryVersion
  539.     1    CARD8        opcode
  540.     1    0        shape opcode
  541.     2    1        request length
  542. .De
  543. .Ds 0
  544. .TA .2i .5i 1.5i 2.5i
  545. .ta .2i .5i 1.5i 2.5i
  546. .R
  547.  =>
  548.      1    1        Reply
  549.     1            unused
  550.     2    CARD16        sequence number
  551.     4    0        length
  552.     2    CARD16        major version
  553.     2    CARD16        minor version
  554.     20            unused
  555. .De
  556. .LP
  557. .Ds 0
  558. .TA .2i .5i 1.5i 2.5i
  559. .ta .2i .5i 1.5i 2.5i
  560. .R
  561. .PN ShapeRectangles
  562.     1    CARD8        opcode
  563.     1    1        shape opcode
  564.     2    4+2n        request length
  565.     1    SHAPE_OP        operation
  566.     1    SHAPE_KIND        destination kind
  567.     1            ordering
  568.         0    UnSorted
  569.         1    YSorted
  570.         2    YXSorted
  571.         3    YXBanded
  572.     1            unused
  573.     4    WINDOW        destination window
  574.     2    INT16        x offset
  575.     2    INT16        y offset
  576.     8n    LISTofRECTANGLE        rectangles
  577. .De
  578. .LP
  579. .Ds 0
  580. .TA .2i .5i 1.5i 2.5i
  581. .ta .2i .5i 1.5i 2.5i
  582. .R
  583. .PN ShapeMask
  584.     1    CARD8        opcode
  585.     1    2        shape opcode
  586.     2    5        request length
  587.     1    SHAPE_OP        operation
  588.     1    SHAPE_KIND        destination kind
  589.     2            unused
  590.     4    WINDOW        destination window
  591.     2    INT16        x offset
  592.     2    INT16        y offset
  593.     4    PIXMAP        source bitmap
  594.         0    None
  595. .De
  596. .LP
  597. .Ds 0
  598. .TA .2i .5i 1.5i 2.5i
  599. .ta .2i .5i 1.5i 2.5i
  600. .R
  601. .PN ShapeCombine
  602.     1    CARD8        opcode
  603.     1    3        shape opcode
  604.     2    5        request length
  605.     1    SHAPE_OP        operation
  606.     1    SHAPE_KIND        destination kind
  607.     1    SHAPE_KIND        source kind
  608.     1            unused
  609.     4    WINDOW        destination window
  610.     2    INT16        x offset
  611.     2    INT16        y offset
  612.     4    WINDOW        source window
  613. .De
  614. .LP
  615. .Ds 0
  616. .TA .2i .5i 1.5i 2.5i
  617. .ta .2i .5i 1.5i 2.5i
  618. .R
  619. .PN ShapeOffset
  620.     1    CARD8        opcode
  621.     1    4        shape opcode
  622.     2    4        request length
  623.     1    SHAPE_KIND        destination kind
  624.     3            unused
  625.     4    WINDOW        destination window
  626.     2    INT16        x offset
  627.     2    INT16        y offset
  628. .De
  629. .LP
  630. .Ds 0
  631. .TA .2i .5i 1.5i 2.5i
  632. .ta .2i .5i 1.5i 2.5i
  633. .R
  634. .PN ShapeQueryExtents
  635.     1    CARD8        opcode
  636.     1    5        shape opcode
  637.     2    2        request length
  638.     4    WINDOW        destination window
  639. .De
  640. .Ds 0
  641. .TA .2i .5i 1.5i 2.5i
  642. .ta .2i .5i 1.5i 2.5i
  643. .R
  644.  =>
  645.     1    1        Reply
  646.     1            unused
  647.     2    CARD16        sequence number
  648.     4    0        reply length
  649.     1    BOOL        bounding shaped
  650.     1    BOOL        clip shaped
  651.     2            unused
  652.     2    INT16        bounding shape extents x
  653.     2    INT16        bounding shape extents y
  654.     2    CARD16        bounding shape extents width
  655.     2    CARD16        bounding shape extents height
  656.     2    INT16        clip shape extents x
  657.     2    INT16        clip shape extents y
  658.     2    CARD16        clip shape extents width
  659.     2    CARD16        clip shape extents height
  660.     4            unused
  661. .De
  662. .LP
  663. .Ds 0
  664. .TA .2i .5i 1.5i 2.5i
  665. .ta .2i .5i 1.5i 2.5i
  666. .R
  667. .PN ShapeSelectInput
  668.     1    CARD8        opcode
  669.     1    6        shape opcode
  670.     2    3        request length
  671.     4    WINDOW        destination window
  672.     1    BOOL        enable
  673.     3            unused
  674. .De
  675. .LP
  676. .Ds 0
  677. .TA .2i .5i 1.5i 2.5i
  678. .ta .2i .5i 1.5i 2.5i
  679. .R
  680. .PN ShapeInputSelected
  681.     1    CARD8        opcode
  682.     1    6        shape opcode
  683.     2    2        request length
  684.     4    WINDOW        destination window
  685. .De
  686. .Ds 0
  687. .TA .2i .5i 1.5i 2.5i
  688. .ta .2i .5i 1.5i 2.5i
  689. .R
  690.  =>
  691.     1    1        Reply
  692.     1    BOOL        enabled
  693.     2    CARD16        sequence number
  694.     4    0        reply length
  695.     24            unused
  696. .De
  697. .LP
  698. .Ds 0
  699. .TA .2i .5i 1.5i 2.5i
  700. .ta .2i .5i 1.5i 2.5i
  701. .R
  702. .PN ShapeGetRectangles
  703.     1    CARD8        opcode
  704.     1    7        shape opcode
  705.     2    3        request length
  706.     4    WINDOW        window
  707.     1    SHAPE_KIND        source kind
  708.     3            unused
  709. .De
  710. .Ds 0
  711. .TA .2i .5i 1.5i 2.5i
  712. .ta .2i .5i 1.5i 2.5i
  713. .R
  714.  =>
  715.     1    1        Reply
  716.     1            ordering
  717.         0    UnSorted
  718.         1    YSorted
  719.         2    YXSorted
  720.         3    YXBanded
  721.     2    CARD16        sequence number
  722.     4    2n        reply length
  723.     4    CARD32        nrects
  724.     20            unused
  725.     8n    LISTofRECTANGLE        rectangles
  726. .De
  727. .SH
  728. \s+2Events\s-2
  729. .LP
  730. .LP
  731. .Ds 0
  732. .TA .2i .5i 1.5i 2.5i
  733. .ta .2i .5i 1.5i 2.5i
  734. .R
  735. .PN ShapeNotify
  736.     1    CARD8        type (0 + extension event base)
  737.     1    SHAPE_KIND        shape kind
  738.     2    CARD16        sequence number
  739.     4    WINDOW        affected window
  740.     2    INT16        x value of extents
  741.     2    INT16        y value of extents
  742.     2    CARD16        width of extents
  743.     2    CARD16        height of extents
  744.     4    TIMESTAMP        server time
  745.     1    BOOL        shaped
  746.     11            unused
  747. .De
  748. .NH 1
  749. C language Binding
  750. .LP
  751. The C routines provide direct access to the protocol and add no additional
  752. semantics.
  753. .LP
  754. The include file for this extension is
  755. .Pn < X11/extensions/shape.h >.
  756. The defined shape kinds are
  757. .PN ShapeBounding
  758. and
  759. .PN ShapeClip .
  760. The defined region operations are
  761. .PN ShapeSet ,
  762. .PN ShapeUnion ,
  763. .PN ShapeIntersect ,
  764. .PN ShapeSubtract ,
  765. and
  766. .PN ShapeInvert .
  767. .LP
  768. Bool
  769. .br
  770. XShapeQueryExtension (display, event_base, error_base)
  771. .RS
  772. Display    *display;
  773. .br
  774. int *event_base; /* RETURN */
  775. .br
  776. int *error_base; /* RETURN */
  777. .RE
  778. .IP
  779. Returns
  780. .PN True
  781. if the specified display supports the SHAPE extension else
  782. .PN False .
  783. If the extension is supported, *event_base is set to the event number for
  784. .PN Shape Notify
  785. events and *error_base would be set to the error number for the first error for
  786. this extension.  As no errors are defined for this version of the extension,
  787. the value returned here is not defined (nor useful).
  788. .LP
  789. Status
  790. .br
  791. XShapeQueryVersion (display, major_version, minor_version)
  792. .RS
  793. Display *display;
  794. .br
  795. int *major_version, *minor_version;  /* RETURN */
  796. .RE
  797. .IP
  798. If the extension is supported, the major and minor version numbers of the
  799. extension supported by the display are set and a non-zero value is returned.
  800. Otherwise the arguments are not set and 0 is returned.
  801. .LP
  802. XShapeCombineRegion (display, dest, dest_kind, x_off, y_off, region, op)
  803. .RS
  804. Display *display;
  805. .br
  806. Window dest;
  807. .br
  808. int dest_kind, op, x_off, y_off;
  809. .br
  810. REGION *region;
  811. .RE
  812. .IP
  813. Converts the specified region into a list of rectangles and calls
  814. .PN XShapeRectangles .
  815. .LP
  816. XShapeCombineRectangles (display, dest, dest_kind, x_off, y_off, rectangles, n_rects, op, ordering)
  817. .RS
  818. Display *display;
  819. .br
  820. Window dest;
  821. .br
  822. int dest_kind, n_rects, op, x_off, y_off, ordering;
  823. .br
  824. XRectangle *rectangles;
  825. .RE
  826. .IP
  827. If the extension is supported, performs a CombineRectangles operation,
  828. otherwise the request is ignored.
  829. .LP
  830. XShapeCombineMask (display, dest, dest_kind, x_off, y_off, src, op)
  831. .RS
  832. Display *display;
  833. .br
  834. Window dest;
  835. .br
  836. int dest_kind, op, x_off, y_off;
  837. .br
  838. Pixmap    src;
  839. .RE
  840. .IP
  841. If the extension is supported, performs a CombineMask operation,
  842. otherwise the request is ignored.
  843. .LP
  844. XShapeCombineShape (display, dest, dest_kind, x_off, y_off, src, src_kind, op)
  845. .RS
  846. Display *display;
  847. .br
  848. Window dest, src;
  849. .br
  850. int dest_kind, src_kind, op, x_off, y_off;
  851. .RE
  852. .IP
  853. If the extension is supported, performs a CombineShape operation,
  854. otherwise the request is ignored.
  855. .LP
  856. XShapeOffsetShape (display, dest, dest_kind, x_off, y_off)
  857. .RS
  858. Display *display;
  859. .br
  860. Window dest;
  861. .br
  862. int dest_kind, x_off, y_off;
  863. .RE
  864. .IP
  865. If the extension is supported, performs an OffsetShape operation,
  866. otherwise the request is ignored.
  867. .LP
  868. Status XShapeQueryExtents
  869. 'in +1i
  870. (display, window, bounding_shaped, x_bounding, y_bounding, w_bounding, h_bounding, clip_shaped, x_clip, y_clip, w_clip, h_clip)
  871. 'in 0
  872. .RS
  873. Display *display;
  874. .br
  875. Window window;
  876. .br
  877. Bool *bounding_shaped, *clip_shaped; /* RETURN */
  878. .br
  879. int *x_bounding, *y_bounding, *x_clip, *y_clip; /* RETURN */
  880. .br
  881. unsigned int *w_bounding, *h_bounding, *w_clip, *h_clip; /* RETURN */
  882. .RE
  883. .IP
  884. If the extension is supported,
  885. x_bounding, y_bounding, w_bounding, h_bounding are set to the extents of the
  886. bounding shape, and x_clip, y_clip, w_clip, h_clip are set to the extents of
  887. the clip shape.  For unspecified client regions, the extents of the
  888. corresponding default region are used.
  889. .IP
  890. If the extension is supported a non-zero value is returned, otherwise 0
  891. is returned.
  892. .LP
  893. XShapeSelectInput (display, window, mask)
  894. .RS
  895. Display *display;
  896. .br
  897. Window window;
  898. .br
  899. unsigned long mask;
  900. .RE
  901. .IP
  902. To make this extension more compatible with other interfaces, although
  903. only one event type can be selected via the extension, this C interface
  904. provides a general mechanism similar to the standard Xlib binding for
  905. window events.  A mask value has been defined,
  906. .PN ShapeNotifyMask ,
  907. which is the only valid bit in \fImask\fP which may be specified.
  908. The structure for this event is defined as follows:
  909. .IP
  910. .TA 2.5i
  911. .ta 2.5i
  912. typedef struct {
  913.     int type;    /* of event */
  914.     unsigned long serial;    /* # of last request processed by server */
  915.     Bool send_event;    /* true if this came frome a SendEvent request */
  916.     Display *display;    /* Display the event was read from */
  917.     Window window;    /* window of event */
  918.     int kind;    /* ShapeBounding or ShapeClip */
  919.     int x, y;    /* extents of new region */
  920.     unsigned width, height;
  921.     Time time;    /* server timestamp when region changed */
  922.     Bool shaped;    /* true if the region exists */
  923. .br
  924. } XShapeEvent;
  925. .LP
  926. unsigned long
  927. .br
  928. XShapeInputSelected (display, window)
  929. .RS
  930. Display *display
  931. .br
  932. Window window;
  933. .RE
  934. .IP
  935. This returns the current input mask for extension events on the specified
  936. window; the value returned if
  937. .PN ShapeNotify
  938. is selected for is
  939. .PN ShapeNotifyMask ,
  940. otherwise it returns zero.
  941. .IP
  942. If the extension is not supported, 0 is returned.
  943. .LP
  944. XRectangle *
  945. .br
  946. XShapeGetRectangles (display, window, kind, count, ordering)
  947. .RS
  948. Display *display;
  949. .br
  950. Window window;
  951. .br
  952. int kind;
  953. .br
  954. int *count; /* RETURN */
  955. .br
  956. int *ordering; /* RETURN */
  957. .RE
  958. .LP
  959. .IP
  960. If the extension is not supported, NULL is returned.  Otherwise,
  961. a list of rectangles describing the region specified by \fIkind\fP
  962. is returned.
  963. .NH 1
  964. Glossary
  965. .LP
  966. .IP "\fBbounding region\fP"
  967. The area of the parent window which this window will occupy.  This area is
  968. divided into two parts:  the border and the interior.
  969. .IP "\fBclip region\fP"
  970. The interior of the window, as a subset of the \fBbounding region\fP.  This
  971. region describes the area which will be painted with the window background
  972. when the window is cleared, will contain all graphics output to the window,
  973. and will clip any subwindows.
  974. .IP "\fBdefault bounding region\fP"
  975. The rectangular area, as described by the core protocol window size, which
  976. covers the interior of the window and its border.
  977. .IP "\fBdefault clip region\fP
  978. The rectangular area as described by the core protocol window size which
  979. covers the interior of the window and excludes the border.
  980. .IP "\fBclient bounding region\fP"
  981. The region associated with a window which is directly modified via this
  982. extension when specified by \fIShapeBounding\fP.  This region is used in
  983. conjunction with the \fBdefault bounding region\fP to produce the
  984. \fBeffective bounding region\fP.
  985. .IP "\fBclient clip region\fP"
  986. The region associated with a window which is directly modified via this
  987. extension when specified by \fIShapeClip\fP.  This region is used in
  988. conjunction with the \fBdefault clip region\fP and the \fBclient bounding
  989. region\fP to produce the \fBeffective clip region\fP.
  990. .IP "\fBeffective bounding region\fP"
  991. The actual shape of the window on the screen, including border and interior
  992. (but excluding the effects of overlapping windows).  When a window has a client
  993. bounding region, the effective bounding region is the intersection of the
  994. default bounding region and the client bounding region.  Otherwise, the
  995. effective bounding region is the same as the default bounding region.
  996. .IP "\fBeffective clip region\fP"
  997. The actual shape of the interior of the window on the screen (excluding the
  998. effects of overlapping windows).  When a window has a client clip region or
  999. a client bounding region, the effective clip region is the intersection of
  1000. the default clip region, the client clip region (if any) and the client
  1001. bounding region (if any).  Otherwise, the effective clip region is the
  1002. same as the default clip region.
  1003.