home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH07 < prev    next >
Encoding:
Text File  |  1991-08-27  |  58.0 KB  |  2,436 lines

  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 7\fP\s-1
  5.  
  6. \s+1\fBGraphics Context Functions\fP\s-1
  7. .sp 2
  8. .nr H1 7
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 7: Graphics Context Functions 
  17. .XE
  18. A number of resources are used when performing graphics operations in X.
  19. Most information about performing graphics (for example, foreground
  20. color, background color, line style, and so on) are stored in
  21. resources called graphics contexts (GC).
  22. .IN "Graphics context"
  23. Most graphics operations (see chapter 8) take a 
  24. GC as an argument.
  25. Although in theory the X protocol permits sharing of GCs between applications, 
  26. it is expected that applications will use their own
  27. GCs when performing operations. 
  28. Sharing of GCs is highly discouraged because the library may cache GC state.
  29. .LP
  30. Graphics operations can be performed to either windows or pixmaps, 
  31. which collectively are called drawables.
  32. .IN "Root"
  33. Each drawable exists on a single screen.
  34. A GC is created for a specific screen and drawable depth,
  35. and can only be used with drawables of matching
  36. screen and depth.
  37. .NH 2
  38. Manipulating Graphics Context/State
  39. .XS
  40. \*(SN Manipulating Graphics Context/State 
  41. .XE
  42. .LP
  43. Most attributes of graphics operations are stored in Graphic Contexts (GCs).
  44. These include line width, line style, plane mask, foreground, background,
  45. tile, stipple, clipping region, end style, join style, and so on.
  46. Graphics operations (for example, drawing lines) use these values
  47. to determine the actual drawing operation.
  48. Extensions to X may add additional components to GCs.
  49. The contents of a GC are private to Xlib.
  50. .LP
  51. Xlib implements a write-back cache for all elements of a GC that are not
  52. resource IDs to allow Xlib to implement the transparent coalescing of changes 
  53. to GCs.
  54. For example,
  55. a call to
  56. .PN XSetForeground
  57. of a GC followed by a call to
  58. .PN XSetLineAttributes
  59. results in only a single-change GC protocol request to the server.
  60. GCs are neither expected nor encouraged to be shared between client 
  61. applications, so this write-back caching should present no problems.
  62. Applications cannot share GCs without external synchronization.
  63. Therefore,
  64. sharing GCs between applications is highly discouraged. 
  65. .LP
  66. To set an attribute of a GC,
  67. set the appropriate member of the
  68. .PN XGCValues
  69. structure and OR in the corresponding value bitmask in your subsequent calls to
  70. .PN XCreateGC .
  71. The symbols for the value mask bits and the
  72. .PN XGCValues
  73. structure are:
  74. .\" Start marker code here
  75. .LP
  76. /* GC attribute value mask bits */
  77. .TS
  78. lw(.5i) lw(2.5i) lw(.75i).
  79. #define\
  80.     T{
  81. .PN GCFunction
  82. T}    T{
  83. (1L<<0)
  84. T}
  85. #define\
  86.     T{
  87. .PN GCPlaneMask
  88. T}    T{
  89. (1L<<1)
  90. T}
  91. #define\
  92.     T{
  93. .PN GCForeground
  94. T}    T{
  95. (1L<<2)
  96. T}
  97. #define\
  98.     T{
  99. .PN GCBackground
  100. T}    T{
  101. (1L<<3)
  102. T}
  103. #define\
  104.     T{
  105. .PN GCLineWidth
  106. T}    T{
  107. (1L<<4)
  108. T}
  109. #define\
  110.     T{
  111. .PN GCLineStyle
  112. T}    T{
  113. (1L<<5)
  114. T}
  115. #define\
  116.     T{
  117. .PN GCCapStyle
  118. T}    T{
  119. (1L<<6)
  120. T}
  121. #define\
  122.     T{
  123. .PN GCJoinStyle
  124. T}    T{
  125. (1L<<7)
  126. T}
  127. #define\
  128.     T{
  129. .PN GCFillStyle
  130. T}    T{
  131. (1L<<8)
  132. T}
  133. #define\
  134.     T{
  135. .PN GCFillRule
  136. T}    T{
  137. (1L<<9)
  138. T}
  139. #define\
  140.     T{
  141. .PN GCTile
  142. T}    T{
  143. (1L<<10)
  144. T}
  145. #define\
  146.     T{
  147. .PN GCStipple
  148. T}    T{
  149. (1L<<11)
  150. T}
  151. #define\
  152.     T{
  153. .PN GCTileStipXOrigin
  154. T}    T{
  155. (1L<<12)
  156. T}
  157. #define\
  158.     T{
  159. .PN GCTileStipYOrigin
  160. T}    T{
  161. (1L<<13)
  162. T}
  163. #define\
  164.     T{
  165. .PN GCFont
  166. T}    T{
  167. (1L<<14)
  168. T}
  169. #define\
  170.     T{
  171. .PN GCSubwindowMode
  172. T}    T{
  173. (1L<<15)
  174. T}
  175. #define\
  176.     T{
  177. .PN GCGraphicsExposures
  178. T}    T{
  179. (1L<<16)
  180. T}
  181. #define\
  182.     T{
  183. .PN GCClipXOrigin
  184. T}    T{
  185. (1L<<17)
  186. T}
  187. #define\
  188.     T{
  189. .PN GCClipYOrigin
  190. T}    T{
  191. (1L<<18)
  192. T}
  193. #define\
  194.     T{
  195. .PN GCClipMask
  196. T}    T{
  197. (1L<<19)
  198. T}
  199. #define\
  200.     T{
  201. .PN GCDashOffset
  202. T}    T{
  203. (1L<<20)
  204. T}
  205. #define\
  206.     T{
  207. .PN GCDashList
  208. T}    T{
  209. (1L<<21)
  210. T}
  211. #define\
  212.     T{
  213. .PN GCArcMode
  214. T}    T{
  215. (1L<<22)
  216. T}
  217. .TE
  218. .IN "XGCValues" "" "@DEF@"
  219. .Ds 0
  220. .TA .5i 3i
  221. .ta .5i 3i
  222. /* Values */
  223.  
  224. typedef struct {
  225.     int function;    /* logical operation */
  226.     unsigned long plane_mask;    /* plane mask */
  227.     unsigned long foreground;    /* foreground pixel */
  228.     unsigned long background;    /* background pixel */
  229.     int line_width;    /* line width (in pixels) */
  230.     int line_style;    /* LineSolid, LineOnOffDash, LineDoubleDash */
  231.     int cap_style;    /* CapNotLast, CapButt, CapRound, CapProjecting */
  232.     int join_style;    /* JoinMiter, JoinRound, JoinBevel */
  233.     int fill_style;    /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
  234.     int fill_rule;    /* EvenOddRule, WindingRule */
  235.     int arc_mode;    /* ArcChord, ArcPieSlice */
  236.     Pixmap tile;    /* tile pixmap for tiling operations */
  237.     Pixmap stipple;    /* stipple 1 plane pixmap for stippling */
  238.     int ts_x_origin;    /* offset for tile or stipple operations */
  239.     int ts_y_origin;
  240.     Font font;    /* default text font for text operations */
  241.     int subwindow_mode;    /* ClipByChildren, IncludeInferiors */
  242.     Bool graphics_exposures;    /* boolean, should exposures be generated */
  243.     int clip_x_origin;    /* origin for clipping */
  244.     int clip_y_origin;
  245.     Pixmap clip_mask;    /* bitmap clipping; other calls for rects */
  246.     int dash_offset;    /* patterned/dashed line information */
  247.     char dashes;
  248. } XGCValues;
  249. .De
  250. .\" End marker code here
  251. .LP 
  252. The default GC values are:
  253. .TS H
  254. l l.
  255. _
  256. .sp 6p
  257. .B
  258. Component    Default
  259. .sp 6p
  260. _
  261. .sp 6p
  262. .TH
  263. .R
  264. T{
  265. function
  266. T}    T{
  267. .PN GXcopy
  268. T}
  269. plane_mask    All ones
  270. foreground    0
  271. background    1
  272. line_width    0
  273. T{
  274. line_style
  275. T}    T{
  276. .PN LineSolid
  277. T}
  278. T{
  279. cap_style
  280. T}    T{
  281. .PN CapButt
  282. T}
  283. T{
  284. join_style
  285. T}    T{
  286. .PN JoinMiter
  287. T}
  288. T{
  289. fill_style
  290. T}    T{
  291. .PN FillSolid
  292. T}
  293. T{
  294. fill_rule
  295. T}    T{
  296. .PN EvenOddRule
  297. T}
  298. T{
  299. arc_mode
  300. T}    T{
  301. .PN ArcPieSlice
  302. T}
  303. tile    Pixmap of unspecified size filled with foreground pixel
  304.     (that is, client specified pixel if any, else 0)
  305.     (subsequent changes to foreground do not affect this pixmap)
  306. stipple    Pixmap of unspecified size filled with ones
  307. ts_x_origin    0
  308. ts_y_origin    0
  309. font    <implementation dependent>
  310. T{
  311. subwindow_mode
  312. T}    T{
  313. .PN ClipByChildren
  314. T}
  315. T{
  316. graphics_exposures
  317. T}    T{
  318. .PN True
  319. T}
  320. clip_x_origin    0
  321. clip_y_origin    0
  322. T{
  323. clip_mask
  324. T}    T{
  325. .PN None
  326. T}
  327. dash_offset    0
  328. dashes    4 (that is, the list [4, 4])
  329. .sp 6p
  330. _
  331. .TE
  332. .LP
  333. Note that foreground and background are not set to any values likely
  334. to be useful in a window.
  335. .LP
  336. .IN "Display Functions" "" "@DEF@"
  337. .IN "Source" "" "@DEF@"
  338. .IN "Destination" "" "@DEF@"
  339. The function attributes of a GC are used when you update a section of
  340. a drawable (the destination) with bits from somewhere else (the source).  
  341. The function in a GC defines how the new destination bits are to be
  342. computed from the source bits and the old destination bits.
  343. .PN GXcopy
  344. is typically the most useful because it will work on a color display,
  345. but special applications may use other functions,
  346. particularly in concert with particular planes of a color display.
  347. The 16 GC functions, defined in 
  348. .Pn < X11/X.h >,
  349. are:
  350. .\" are listed in Table 5-1 along with the 
  351. .\"the associated hexadecimal code
  352. .\" and operation.
  353. .\".CP T 1
  354. .\"Display Functions
  355. .TS H
  356. lw(1.5i) cw(.5i) lw(2i).
  357. _
  358. .sp 6p
  359. .B
  360. Function Name    Value    Operation
  361. .sp 6p
  362. _
  363. .sp 6p
  364. T{
  365. .PN GXclear
  366. T}    T{
  367. 0x0
  368. T}    T{
  369. 0
  370. T}
  371. T{
  372. .PN GXand
  373. T}    T{
  374. 0x1
  375. T}    T{
  376. src AND dst
  377. T}
  378. T{
  379. .PN GXandReverse
  380. T}    T{
  381. 0x2
  382. T}    T{
  383. src AND NOT dst
  384. T}
  385. T{
  386. .PN GXcopy
  387. T}    T{
  388. 0x3
  389. T}    T{
  390. src
  391. T}
  392. T{
  393. .PN GXandInverted
  394. T}    T{
  395. 0x4
  396. T}    T{
  397. (NOT src) AND dst
  398. T}
  399. T{
  400. .PN GXnoop
  401. T}    T{
  402. 0x5
  403. T}    T{
  404. dst
  405. T}
  406. T{
  407. .PN GXxor
  408. T}    T{
  409. 0x6
  410. T}    T{
  411. src XOR dst
  412. T}
  413. T{
  414. .PN GXor
  415. T}    T{
  416. 0x7
  417. T}    T{
  418. src OR dst
  419. T}
  420. T{
  421. .PN GXnor
  422. T}    T{
  423. 0x8
  424. T}    T{
  425. (NOT src) AND (NOT dst)
  426. T}
  427. T{
  428. .PN GXequiv
  429. T}    T{
  430. 0x9
  431. T}    T{
  432. (NOT src) XOR dst
  433. T}
  434. T{
  435. .PN GXinvert
  436. T}    T{
  437. 0xa
  438. T}    T{
  439. NOT dst
  440. T}
  441. T{
  442. .PN GXorReverse
  443. T}    T{
  444. 0xb
  445. T}    T{
  446. src OR (NOT dst)
  447. T}
  448. T{
  449. .PN GXcopyInverted
  450. T}    T{
  451. 0xc
  452. T}    T{
  453. NOT src
  454. T}
  455. T{
  456. .PN GXorInverted
  457. T}    T{
  458. 0xd
  459. T}    T{
  460. (NOT src) OR dst
  461. T}
  462. T{
  463. .PN GXnand
  464. T}    T{
  465. 0xe
  466. T}    T{
  467. (NOT src) OR (NOT dst)
  468. T}
  469. T{
  470. .PN GXset
  471. T}    T{
  472. 0xf
  473. T}    T{
  474. 1
  475. T}
  476. .sp 6p
  477. _
  478. .TE
  479. .LP
  480. Many graphics operations depend on either pixel values or planes in a GC.
  481. .IN "Pixel value"
  482. The planes attribute is of type long, and it specifies which planes of the
  483. destination are to be modified, one bit per plane.
  484. .IN "Plane" "mask"
  485. A monochrome display has only one plane and
  486. will be the least-significant bit of the word.
  487. As planes are added to the display hardware, they will occupy more
  488. significant bits in the plane mask.
  489. .LP
  490. In graphics operations, given a source and destination pixel, 
  491. the result is computed bitwise on corresponding bits of the pixels.
  492. That is, a Boolean operation is performed in each bit plane.  
  493. The plane_mask restricts the operation to a subset of planes.
  494. A macro constant
  495. .PN AllPlanes
  496. can be used to refer to all planes of the screen simultaneously.
  497. The result is computed by the following:
  498. .LP
  499. .Ds 
  500. ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
  501. .De
  502. .LP
  503. Range checking is not performed on the values for foreground,
  504. background, or plane_mask.
  505. They are simply truncated to the appropriate
  506. number of bits.
  507. The line-width is measured in pixels and either can be greater than or equal to
  508. one (wide line) or can be the special value zero (thin line).
  509. .LP
  510. Wide lines are drawn centered on the path described by the graphics request.
  511. Unless otherwise specified by the join-style or cap-style,
  512. the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
  513. width w is a rectangle with vertices at the following real coordinates:
  514. .LP
  515. .Ds
  516. .TA .5i 2.5i
  517. .ta .5i 2.5i
  518. [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
  519. [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
  520. .De
  521. .LP
  522. Here sn is the sine of the angle of the line,
  523. and cs is the cosine of the angle of the line.
  524. A pixel is part of the line and so is drawn
  525. if the center of the pixel is fully inside the bounding box
  526. (which is viewed as having infinitely thin edges).
  527. If the center of the pixel is exactly on the bounding box,
  528. it is part of the line if and only if the interior is immediately to its right
  529. (x increasing direction).
  530. Pixels with centers on a horizontal edge are a special case and are part of
  531. the line if and only if the interior or the boundary is immediately below 
  532. (y increasing direction) and the interior or the boundary is immediately
  533. to the right (x increasing direction).
  534. .LP
  535. Thin lines (zero line-width) are one-pixel-wide lines drawn using an
  536. unspecified, device-dependent algorithm.
  537. There are only two constraints on this algorithm. 
  538. .IP 1. 5
  539. If a line is drawn unclipped from [x1,y1] to [x2,y2] and
  540. if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
  541. a point [x,y] is touched by drawing the first line 
  542. if and only if the point [x+dx,y+dy] is touched by drawing the second line.
  543. .IP 2. 5
  544. The effective set of points comprising a line cannot be affected by clipping.
  545. That is, a point is touched in a clipped line if and only if the point 
  546. lies inside the clipping region and the point would be touched
  547. by the line when drawn unclipped.
  548. .LP
  549. A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 
  550. as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style 
  551. and join-style.
  552. It is recommended that this property be true for thin lines, 
  553. but this is not required.
  554. A line-width of zero may differ from a line-width of one in which pixels are
  555. drawn.
  556. This permits the use of many manufacturers' line drawing hardware,
  557. which may run many times faster than the more precisely specified
  558. wide lines.
  559. .LP
  560. In general, 
  561. drawing a thin line will be faster than drawing a wide line of width one.
  562. However, because of their different drawing algorithms,
  563. thin lines may not mix well aesthetically with wide lines.
  564. If it is desirable to obtain precise and uniform results across all displays,
  565. a client should always use a line-width of one rather than a line-width of zero.
  566. .LP
  567. The line-style defines which sections of a line are drawn:
  568. .TS
  569. lw(1.3i) lw(4.5i).
  570. T{
  571. .PN LineSolid
  572. T}    T{
  573. The full path of the line is drawn.
  574. T}
  575. .sp 6p
  576. T{
  577. .PN LineDoubleDash
  578. T}    T{
  579. The full path of the line is drawn, 
  580. but the even dashes are filled differently 
  581. than the odd dashes (see fill-style) with
  582. .PN CapButt 
  583. style used where even and odd dashes meet.
  584. T}
  585. .sp 6p
  586. T{
  587. .PN LineOnOffDash
  588. T}    T{
  589. Only the even dashes are drawn,
  590. and cap-style applies to 
  591. all internal ends of the individual dashes,
  592. except 
  593. .PN CapNotLast
  594. is treated as 
  595. .PN CapButt . 
  596. T}
  597. .TE
  598. .LP
  599. The cap-style defines how the endpoints of a path are drawn:
  600. .IN "Graphics context" "path"
  601. .TS
  602. lw(1.3i) lw(4.5i).
  603. T{
  604. .PN CapNotLast
  605. T}    T{
  606. This is equivalent to 
  607. .PN CapButt  
  608. except that for a line-width of zero the final endpoint is not drawn.
  609. T}
  610. .sp 6p
  611. T{
  612. .PN CapButt
  613. T}    T{
  614. The line is square at the endpoint (perpendicular to the slope of the line)
  615. with no projection beyond.
  616. T}
  617. .sp 6p
  618. T{
  619. .PN CapRound
  620. T}    T{
  621. The line has a circular arc with the diameter equal to the line-width,
  622. centered on the endpoint.
  623. (This is equivalent to 
  624. .PN CapButt 
  625. for line-width of zero).
  626. T}
  627. .sp 6p
  628. T{
  629. .PN CapProjecting
  630. T}    T{
  631. The line is square at the end, but the path continues beyond the endpoint 
  632. for a distance equal to half the line-width.
  633. (This is equivalent to 
  634. .PN CapButt 
  635. for line-width of zero).
  636. T}
  637. .TE
  638. .LP
  639. The join-style defines how corners are drawn for wide lines:
  640. .TS
  641. lw(1.3i) lw(4.5i).
  642. T{
  643. .PN JoinMiter
  644. T}    T{
  645. The outer edges of two lines extend to meet at an angle.
  646. However, if the angle is less than 11 degrees,
  647. then a
  648. .PN JoinBevel
  649. join-style is used instead.
  650. T}
  651. .sp 6p
  652. T{
  653. .PN JoinRound
  654. T}    T{
  655. The corner is a circular arc with the diameter equal to the line-width, 
  656. centered on the joinpoint.
  657. T}
  658. .sp 6p
  659. T{
  660. .PN JoinBevel
  661. T}    T{
  662. The corner has
  663. .PN CapButt 
  664. endpoint styles with the triangular notch filled.
  665. T}
  666. .TE
  667. .LP
  668. For a line with coincident endpoints (x1=x2, y1=y2), 
  669. when the cap-style is applied to both endpoints, 
  670. the semantics depends on the line-width and the cap-style:
  671. .TS
  672. lw(1.3i) lw(.5i) lw(4i).
  673. T{
  674. .PN CapNotLast
  675. T}    T{
  676. thin
  677. T}    T{
  678. The results are device-dependent, 
  679. but the desired effect is that nothing is drawn.
  680. T}
  681. .sp 6p
  682. T{
  683. .PN CapButt
  684. T}    T{
  685. thin
  686. T}    T{
  687. The results are device-dependent, 
  688. but the desired effect is that a single pixel is drawn.
  689. T}
  690. .sp 6p
  691. T{
  692. .PN CapRound
  693. T}    T{
  694. thin
  695. T}    T{
  696. The results are the same as for
  697. .PN CapButt /thin.
  698. T}
  699. .sp 6p
  700. T{
  701. .PN CapProjecting
  702. T}    T{
  703. thin
  704. T}    T{
  705. The results are the same as for
  706. .PN CapButt /thin.
  707. T}
  708. .sp 6p
  709. T{
  710. .PN CapButt
  711. T}    T{
  712. wide
  713. T}    T{
  714. Nothing is drawn.
  715. T}
  716. .sp 6p
  717. T{
  718. .PN CapRound
  719. T}    T{
  720. wide
  721. T}    T{
  722. The closed path is a circle, centered at the endpoint, and
  723. with the diameter equal to the line-width.
  724. T}
  725. .sp 6p
  726. T{
  727. .PN CapProjecting
  728. T}    T{
  729. wide
  730. T}    T{
  731. The closed path is a square, aligned with the coordinate axes, centered at the
  732. endpoint, and with the sides equal to the line-width.
  733. T}
  734. .TE
  735. .LP
  736. For a line with coincident endpoints (x1=x2, y1=y2), 
  737. when the join-style is applied at one or both endpoints, 
  738. the effect is as if the line was removed from the overall path.
  739. However, if the total path consists of or is reduced to a single point joined
  740. with itself, the effect is the same as when the cap-style is applied at both
  741. endpoints.
  742. .LP
  743. The tile/stipple represents an infinite 2D plane, with the tile/stipple
  744. replicated in all dimensions.  When that plane is superimposed on
  745. the drawable for use in a graphics operation, the upper left corner
  746. of some instance of the tile/stipple is at the coordinates within
  747. the drawable specified by the tile/stipple origin.
  748. The tile/stipple and clip origins are interpreted relative to the
  749. origin of whatever destination drawable is specified in a graphics
  750. request.
  751. The tile pixmap must have the same root and depth as the GC,
  752. or a
  753. .PN BadMatch 
  754. error results.
  755. The stipple pixmap must have depth one and must have the same root as the
  756. GC, or a 
  757. .PN BadMatch 
  758. error results.  
  759. For stipple operations where the fill-style is
  760. .PN FillStippled
  761. but not 
  762. .PN FillOpaqueStippled ,
  763. the stipple pattern is tiled in a
  764. single plane and acts as an additional clip mask to be ANDed with the clip-mask.
  765. Although some sizes may be faster to use than others,
  766. any size pixmap can be used for tiling or stippling.
  767. .LP
  768. The fill-style defines the contents of the source for line, text, and
  769. fill requests.  
  770. For all text and fill requests (for example,
  771. .PN XDrawText , 
  772. .PN XDrawText16 ,
  773. .PN XFillRectangle , 
  774. .PN XFillPolygon , 
  775. and
  776. .PN XFillArc );
  777. for line requests 
  778. with line-style 
  779. .PN LineSolid 
  780. (for example,
  781. .PN XDrawLine ,
  782. .PN XDrawSegments , 
  783. .PN XDrawRectangle ,
  784. .PN XDrawArc );
  785. and for the even dashes for line requests with line-style 
  786. .PN LineOnOffDash 
  787. or 
  788. .PN LineDoubleDash ,
  789. the following apply:
  790. .TS
  791. lw(1.8i) lw(4i).
  792. T{
  793. .PN FillSolid
  794. T}    T{
  795. Foreground
  796. T}
  797. .sp 6p
  798. T{
  799. .PN FillTiled
  800. T}    T{
  801. Tile
  802. T}
  803. .sp 6p
  804. T{
  805. .PN FillOpaqueStippled
  806. T}    T{
  807. A tile with the same width and height as stipple,
  808. but with background everywhere stipple has a zero
  809. and with foreground everywhere stipple has a one
  810. T}
  811. .sp 6p
  812. T{
  813. .PN FillStippled
  814. T}    T{
  815. Foreground masked by stipple
  816. T}
  817. .TE
  818. .LP
  819. When drawing lines with line-style
  820. .PN LineDoubleDash ,
  821. the odd dashes are controlled by the fill-style in the following manner:
  822. .TS
  823. lw(1.8i) lw(4i).
  824. T{
  825. .PN FillSolid
  826. T}    T{
  827. Background
  828. T}
  829. .sp 6p
  830. T{
  831. .PN FillTiled
  832. T}    T{
  833. Same as for even dashes
  834. T}
  835. .sp 6p
  836. T{
  837. .PN FillOpaqueStippled
  838. T}    T{
  839. Same as for even dashes
  840. T}
  841. .sp 6p
  842. T{
  843. .PN FillStippled
  844. T}    T{
  845. Background masked by stipple
  846. T}
  847. .TE
  848. .LP
  849. Storing a pixmap in a GC might or might not result in a copy
  850. being made.
  851. If the pixmap is later used as the destination for a graphics request,
  852. the change might or might not be reflected in the GC.
  853. If the pixmap is used simultaneously in a graphics request both as
  854. a destination and as a tile or stipple,
  855. the results are undefined.
  856. .LP
  857. For optimum performance,
  858. you should draw as much as possible with the same GC 
  859. (without changing its components).
  860. The costs of changing GC components relative to using different GCs
  861. depend upon the display hardware and the server implementation.
  862. It is quite likely that some amount of GC information will be
  863. cached in display hardware and that such hardware can only cache a small number
  864. of GCs.
  865. .LP
  866. The dashes value is actually a simplified form of the
  867. more general patterns that can be set with 
  868. .PN XSetDashes .  
  869. Specifying a
  870. value of N is equivalent to specifying the two-element list [N, N] in 
  871. .PN XSetDashes . 
  872. The value must be nonzero,
  873. or a
  874. .PN BadValue
  875. error results.
  876. .LP
  877. The clip-mask restricts writes to the destination drawable.  
  878. If the clip-mask is set to a pixmap,
  879. it must have depth one and have the same root as the GC,
  880. or a
  881. .PN BadMatch 
  882. error results.
  883. If clip-mask is set to
  884. .PN None ,
  885. the pixels are always drawn regardless of the clip origin.
  886. The clip-mask also can be set by calling the
  887. .PN XSetClipRectangles
  888. or
  889. .PN XSetRegion
  890. functions.
  891. Only pixels where the clip-mask has a bit set to 1 are drawn.  
  892. Pixels are not drawn outside the area covered by the clip-mask 
  893. or where the clip-mask has a bit set to 0.
  894. The clip-mask affects all graphics requests.
  895. The clip-mask does not clip sources.
  896. The clip-mask origin is interpreted relative to the origin of whatever
  897. destination drawable is specified in a graphics request.
  898. .LP
  899. You can set the subwindow-mode to
  900. .PN ClipByChildren
  901. or
  902. .PN IncludeInferiors .
  903. For 
  904. .PN ClipByChildren , 
  905. both source and destination windows are
  906. additionally clipped by all viewable 
  907. .PN InputOutput
  908. children.  
  909. For 
  910. .PN IncludeInferiors ,
  911. neither source nor destination window is clipped by inferiors. 
  912. This will result in including subwindow contents in the source
  913. and drawing through subwindow boundaries of the destination.
  914. The use of 
  915. .PN IncludeInferiors 
  916. on a window of one depth with mapped
  917. inferiors of differing depth is not illegal, but the semantics are
  918. undefined by the core protocol.
  919. .LP
  920. The fill-rule defines what pixels are inside (drawn) for
  921. paths given in 
  922. .PN XFillPolygon 
  923. requests and can be set to 
  924. .PN EvenOddRule 
  925. or
  926. .PN WindingRule .
  927. For
  928. .PN EvenOddRule ,
  929. a point is inside if
  930. an infinite ray with the point as origin crosses the path an odd number
  931. of times.  
  932. For 
  933. .PN WindingRule , 
  934. a point is inside if an infinite ray with the
  935. point as origin crosses an unequal number of clockwise and
  936. counterclockwise directed path segments.
  937. A clockwise directed path segment is one that crosses the ray from left to
  938. right as observed from the point.
  939. A counterclockwise segment is one that crosses the ray from right to left
  940. as observed from the point.
  941. The case where a directed line segment is coincident with the ray is
  942. uninteresting because you can simply choose a different ray that is not
  943. coincident with a segment.
  944. .LP
  945. For both 
  946. .PN EvenOddRule
  947. and
  948. .PN WindingRule ,
  949. a point is infinitely small, 
  950. and the path is an infinitely thin line.  
  951. A pixel is inside if the center point of the pixel is inside
  952. and the center point is not on the boundary.  
  953. If the center point is on the boundary,
  954. the pixel is inside if and only if the polygon interior is immediately to
  955. its right (x increasing direction).  
  956. Pixels with centers on a horizontal edge are a special case 
  957. and are inside if and only if the polygon interior is immediately below 
  958. (y increasing direction).
  959. .LP
  960. The arc-mode controls filling in the 
  961. .PN XFillArcs
  962. function and can be set to
  963. .PN ArcPieSlice
  964. or
  965. .PN ArcChord .
  966. For
  967. .PN ArcPieSlice ,
  968. the arcs are pie-slice filled.
  969. For
  970. .PN ArcChord ,
  971. the arcs are chord filled.
  972. .LP
  973. The graphics-exposure flag controls 
  974. .PN GraphicsExpose 
  975. event generation
  976. for 
  977. .PN XCopyArea 
  978. and 
  979. .PN XCopyPlane
  980. requests (and any similar requests defined by extensions).
  981. .LP
  982. .sp
  983. To create a new GC that is usable on a given screen with a 
  984. depth of drawable, use
  985. .PN XCreateGC .
  986. .IN "Graphics context" "initializing"
  987. .IN "XCreateGC" "" "@DEF@"
  988. .\" Start marker code here
  989. .FD 0
  990. .\" $Header: XCreateGC.f,v 1.2 88/05/09 11:06:37 mento Exp $
  991. GC XCreateGC\^(\^\fIdisplay\fP, \fId\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^)
  992. .br
  993.       Display *\fIdisplay\fP\^;
  994. .br
  995.       Drawable \fId\fP\^;
  996. .br
  997.       unsigned long \fIvaluemask\fP\^;
  998. .br
  999.       XGCValues *\^\fIvalues\fP\^;
  1000. .FN
  1001. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1002. .IP \fIdisplay\fP 1i
  1003. Specifies the connection to the X server.
  1004. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1005. .IP \fId\fP 1i
  1006. Specifies the drawable. 
  1007. .ds Vm set using the information in the specified values structure
  1008. .\" $Header: valuemask1.a,v 1.6 88/08/04 11:20:52 mento Exp $
  1009. .IP \fIvaluemask\fP 1i
  1010. Specifies which components in the GC are to be \*(Vm. 
  1011. This argument is the bitwise inclusive OR of zero or more of the valid
  1012. GC component mask bits.
  1013. .\" $Header: values1.a,v 1.2 88/05/09 10:50:42 mento Exp $
  1014. .IP \fIvalues\fP 1i
  1015. Specifies any values as specified by the valuemask.
  1016. .\" End marker code here
  1017. .LP
  1018. .\" $Header: XCreateGC.d,v 1.2 88/06/11 07:49:40 mento Exp $
  1019. The
  1020. .PN XCreateGC
  1021. function creates a graphics context and returns a GC.
  1022. The GC can be used with any destination drawable having the same root
  1023. and depth as the specified drawable.
  1024. Use with other drawables results in a
  1025. .PN BadMatch
  1026. error.
  1027. .LP
  1028. .PN XCreateGC
  1029. can generate
  1030. .PN BadAlloc ,
  1031. .PN BadDrawable ,
  1032. .PN BadFont ,
  1033. .PN BadMatch ,
  1034. .PN BadPixmap ,
  1035. and
  1036. .PN BadValue 
  1037. errors.
  1038. .LP
  1039. .sp
  1040. To copy components from a source GC to a destination GC, use
  1041. .PN XCopyGC .
  1042. .IN "XCopyGC" "" "@DEF@"
  1043. .\" Start marker code here
  1044. .FD 0
  1045. .\" $Header: XCopyGC.f,v 1.2 88/05/09 11:08:57 mento Exp $
  1046. XCopyGC\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIvaluemask\fP\^, \fIdest\fP\^)
  1047. .br
  1048.       Display *\fIdisplay\fP\^;
  1049. .br
  1050.       GC \fIsrc\fP\^, \fIdest\fP\^;
  1051. .br
  1052.       unsigned long \fIvaluemask\fP\^;
  1053. .FN
  1054. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1055. .IP \fIdisplay\fP 1i
  1056. Specifies the connection to the X server.
  1057. .\" $Header: src.a,v 1.2 88/05/09 11:11:06 mento Exp $
  1058. .IP \fIsrc\fP 1i
  1059. Specifies the components of the source GC.
  1060. .ds Vm copied to the destination GC
  1061. .\" $Header: valuemask1.a,v 1.6 88/08/04 11:20:52 mento Exp $
  1062. .IP \fIvaluemask\fP 1i
  1063. Specifies which components in the GC are to be \*(Vm. 
  1064. This argument is the bitwise inclusive OR of zero or more of the valid
  1065. GC component mask bits.
  1066. .\" $Header: dest.a,v 1.2 88/05/09 11:11:56 mento Exp $
  1067. .IP \fIdest\fP 1i
  1068. Specifies the destination GC.
  1069. .\" End marker code here
  1070. .LP 
  1071. .\" $Header: XCopyGC.d,v 1.3 88/06/11 07:49:27 mento Exp $
  1072. The
  1073. .PN XCopyGC
  1074. function copies the specified components from the source GC
  1075. to the destination GC.
  1076. The source and destination GCs must have the same root and depth,
  1077. or a
  1078. .PN BadMatch
  1079. error results.
  1080. The valuemask specifies which component to copy, as for
  1081. .PN XCreateGC .
  1082. .LP
  1083. .PN XCopyGC
  1084. can generate
  1085. .PN BadAlloc , 
  1086. .PN BadGC ,
  1087. and
  1088. .PN BadMatch
  1089. errors.
  1090. .LP
  1091. .sp
  1092. To change the components in a given GC, use
  1093. .PN XChangeGC .
  1094. .IN "XChangeGC" "" "@DEF@"
  1095. .\" Start marker code here
  1096. .FD 0
  1097. .\" $Header: XChGC.f,v 1.2 88/05/09 11:19:10 mento Exp $
  1098. XChangeGC\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^)
  1099. .br
  1100.       Display *\fIdisplay\fP\^;
  1101. .br
  1102.       GC \fIgc\fP\^;
  1103. .br
  1104.       unsigned long \fIvaluemask\fP\^;
  1105. .br
  1106.       XGCValues *\^\fIvalues\fP\^;
  1107. .FN
  1108. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1109. .IP \fIdisplay\fP 1i
  1110. Specifies the connection to the X server.
  1111. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1112. .IP \fIgc\fP 1i
  1113. Specifies the GC.
  1114. .ds Vm changed using information in the specified values structure
  1115. .\" $Header: valuemask1.a,v 1.6 88/08/04 11:20:52 mento Exp $
  1116. .IP \fIvaluemask\fP 1i
  1117. Specifies which components in the GC are to be \*(Vm. 
  1118. This argument is the bitwise inclusive OR of zero or more of the valid
  1119. GC component mask bits.
  1120. .\" $Header: values1.a,v 1.2 88/05/09 10:50:42 mento Exp $
  1121. .IP \fIvalues\fP 1i
  1122. Specifies any values as specified by the valuemask.
  1123. .\" End marker code here
  1124. .LP
  1125. .\" $Header: XChGC.d,v 1.3 88/06/11 07:49:02 mento Exp $
  1126. The
  1127. .PN XChangeGC
  1128. function changes the components specified by valuemask for
  1129. the specified GC.
  1130. The values argument contains the values to be set.
  1131. The values and restrictions are the same as for 
  1132. .PN XCreateGC .
  1133. Changing the clip-mask overrides any previous 
  1134. .PN XSetClipRectangles
  1135. request on the context. 
  1136. Changing the dash-offset or dash-list
  1137. overrides any previous 
  1138. .PN XSetDashes
  1139. request on the context.
  1140. The order in which components are verified and altered is server-dependent.
  1141. If an error is generated, a subset of the components may have been altered.
  1142. .LP
  1143. .PN XChangeGC
  1144. can generate
  1145. .PN BadAlloc ,
  1146. .PN BadFont ,
  1147. .PN BadGC ,
  1148. .PN BadMatch ,
  1149. .PN BadPixmap ,
  1150. and
  1151. .PN BadValue
  1152. errors.
  1153. .LP
  1154. .sp
  1155. To obtain components of a given GC, use
  1156. .PN XGetGCValues .
  1157. .IN "XGetGCValues" "" "@DEF@"
  1158. .\" Start marker code here
  1159. .FD 0
  1160. Status XGetGCValues\^(\^\fIdisplay\fP, \fIgc\fP, \fIvaluemask\fP, \
  1161. \fIvalues_return\fP\^)
  1162. .br
  1163.       Display *\fIdisplay\fP\^;
  1164. .br
  1165.       GC \fIgc\fP\^;
  1166. .br
  1167.       unsigned long \fIvaluemask\fP\^;
  1168. .br
  1169.       XGCValues *\fIvalues_return\fP\^;
  1170. .FN
  1171. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1172. .IP \fIdisplay\fP 1i
  1173. Specifies the connection to the X server.
  1174. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1175. .IP \fIgc\fP 1i
  1176. Specifies the GC.
  1177. .ds Vm returned in the values_return argument
  1178. .\" $Header: valuemask1.a,v 1.6 88/08/04 11:20:52 mento Exp $
  1179. .IP \fIvaluemask\fP 1i
  1180. Specifies which components in the GC are to be \*(Vm. 
  1181. This argument is the bitwise inclusive OR of zero or more of the valid
  1182. GC component mask bits.
  1183. .\" $Header: values3.a,v 1.2 88/04/06 17:19:04 mento Exp $
  1184. .IP \fIvalues_return\fP 1i
  1185. Returns the GC values in the specified
  1186. .PN XGCValues 
  1187. structure.
  1188. .\" End marker code here
  1189. .LP
  1190. The
  1191. .PN XGetGCValues
  1192. function returns the components specified by valuemask for the specified GC.
  1193. If the valuemask contains a valid set of GC mask bits
  1194. .Pn ( GCFunction ,
  1195. .PN GCPlaneMask ,
  1196. .PN GCForeground ,
  1197. .PN GCBackground ,
  1198. .PN GCLineWidth ,
  1199. .PN GCLineStyle ,
  1200. .PN GCCapStyle ,
  1201. .PN GCJoinStyle ,
  1202. .PN GCFillStyle ,
  1203. .PN GCFillRule ,
  1204. .PN GCTile ,
  1205. .PN GCStipple ,
  1206. .PN GCTileStipXOrigin ,
  1207. .PN GCTileStipYOrigin ,
  1208. .PN GCFont ,
  1209. .PN GCSubwindowMode ,
  1210. .PN GCGraphicsExposures ,
  1211. .PN GCClipXOrigin ,
  1212. .PN GCCLipYOrigin ,
  1213. .PN GCDashOffset ,
  1214. or
  1215. .PN GCArcMode )
  1216. and no error occur,
  1217. .PN XGetGCValues
  1218. sets the requested components in values_return and returns a nonzero status.
  1219. Otherwise, it returns a zero status.
  1220. Note that the clip-mask and dash-list (represented by the
  1221. .PN GCClipMask
  1222. and 
  1223. .PN GCDashList
  1224. bits, respectively, in the valuemask)
  1225. cannot be requested.
  1226. Also note that an invalid resource ID (with one or more of the three
  1227. most-significant bits set to one) will be returned for
  1228. .PN GCFont ,
  1229. .PN GCTile ,
  1230. and
  1231. .PN GCStipple
  1232. if the component has never been explicitly set by the client.
  1233. .LP
  1234. .sp
  1235. To free a given GC, use
  1236. .PN XFreeGC .
  1237. .IN "XFreeGC" "" "@DEF@"
  1238. .\" Start marker code here
  1239. .FD 0
  1240. .\" $Header: XFreeGC.f,v 1.1 88/02/26 10:00:18 mento Exp $
  1241. XFreeGC\^(\^\fIdisplay\fP, \fIgc\fP\^)
  1242. .br
  1243.       Display *\fIdisplay\fP\^;
  1244. .br
  1245.       GC \fIgc\fP\^;
  1246. .FN
  1247. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1248. .IP \fIdisplay\fP 1i
  1249. Specifies the connection to the X server.
  1250. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1251. .IP \fIgc\fP 1i
  1252. Specifies the GC.
  1253. .\" End marker code here
  1254. .LP
  1255. .\" $Header: XFreeGC.d,v 1.3 88/06/11 07:50:48 mento Exp $
  1256. The
  1257. .PN XFreeGC
  1258. function destroys the specified GC as well as all the associated storage.
  1259. .LP
  1260. .PN XFreeGC
  1261. can generate a
  1262. .PN BadGC 
  1263. error.
  1264. .LP
  1265. .sp
  1266. To obtain the 
  1267. .PN GContext 
  1268. resource ID for a given GC, use 
  1269. .PN XGContextFromGC .
  1270. .IN "XGContextFromGC" "" "@DEF@"
  1271. .\" Start marker code here
  1272. .FD 0
  1273. GContext XGContextFromGC\^(\^\fIgc\fP\^)
  1274. .br
  1275.       GC \fIgc\fP\^;
  1276. .FN
  1277. .ds Gc for which you want the resource ID
  1278. .\" $Header: gc_gen.a,v 1.2 88/08/04 11:14:11 mento Exp $
  1279. .IP \fIgc\fP 1i
  1280. Specifies the GC \*(Gc.
  1281. .\" End marker code here
  1282. .LP
  1283. .sp
  1284. Xlib normally defers sending changes to the components of a GC to the server
  1285. until a graphics function is actually called with that GC.
  1286. This permits batching of component changes into a single server request.
  1287. In some circumstances, however, it may be necessary for the client
  1288. to explicitly force sending of the changes to the server.
  1289. An example might be when a protocol extension uses the GC indirectly,
  1290. in such a way that the extension interface cannot know what GC will be used.
  1291. To force sending of GC component changes, use
  1292. .PN XFlushGC .
  1293. .IN "XFlushGC" "" "@DEF@"
  1294. .\" Start marker code here
  1295. .FD 0
  1296. void XFlushGC\^(\^\fIdisplay\fP, \fIgc\fP\^)
  1297. .br
  1298.       Display *\fIdisplay\fP\^;
  1299. .br
  1300.       GC \fIgc\fP\^;
  1301. .FN
  1302. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1303. .IP \fIdisplay\fP 1i
  1304. Specifies the connection to the X server.
  1305. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1306. .IP \fIgc\fP 1i
  1307. Specifies the GC.
  1308. .\" End marker code here
  1309. .NH 2
  1310. Using GC Convenience Routines
  1311. .XS
  1312. \*(SN Using GC Convenience Routines 
  1313. .XE
  1314. .LP
  1315. This section discusses how to set the:
  1316. .IP \(bu 5
  1317. Foreground, background, plane mask, or function components
  1318. .IP \(bu 5
  1319. Line attributes and dashes components
  1320. .IP \(bu 5
  1321. Fill style and fill rule components
  1322. .IP \(bu 5
  1323. Fill tile and stipple components
  1324. .IP \(bu 5
  1325. Font component
  1326. .IP \(bu 5
  1327. Clip region component
  1328. .IP \(bu 5
  1329. Arc mode, subwindow mode, and graphics exposure components
  1330. .LE
  1331. .NH 3
  1332. Setting the Foreground, Background, Function, or Plane Mask
  1333. .XS
  1334. \*(SN Setting the Foreground, Background, Function, or Plane Mask
  1335. .XE
  1336. .LP
  1337. To set the foreground, background, plane mask, and function components
  1338. for a given GC, use
  1339. .PN XSetState .
  1340. .IN "XSetState" "" "@DEF@"
  1341. .\" Start marker code here
  1342. .FD 0
  1343. .\" $Header: XSetState.f,v 1.1 88/02/26 10:03:39 mento Exp $
  1344. XSetState\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^, \fIbackground\fP\^, \fIfunction\fP\^, \fIplane_mask\fP\^)
  1345. .br
  1346.       Display *\fIdisplay\fP\^;
  1347. .br
  1348.       GC \fIgc\fP\^;
  1349. .br
  1350.       unsigned long \fIforeground\fP\^, \fIbackground\fP\^;
  1351. .br
  1352.       int \fIfunction\fP\^;
  1353. .br
  1354.       unsigned long \fIplane_mask\fP\^;
  1355. .FN
  1356. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1357. .IP \fIdisplay\fP 1i
  1358. Specifies the connection to the X server.
  1359. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1360. .IP \fIgc\fP 1i
  1361. Specifies the GC.
  1362. .\" $Header: foreground.a,v 1.2 88/05/09 11:35:55 mento Exp $
  1363. .IP \fIforeground\fP 1i
  1364. Specifies the foreground you want to set for the specified GC.
  1365. .\" $Header: background.a,v 1.2 88/05/09 11:36:36 mento Exp $
  1366. .IP \fIbackground\fP 1i
  1367. Specifies the background you want to set for the specified GC.
  1368. .\" $Header: function.a,v 1.2 88/05/09 11:37:19 mento Exp $
  1369. .IP \fIfunction\fP 1i
  1370. Specifies the function you want to set for the specified GC.
  1371. .\" $Header: plane_mask.a,v 1.1 88/02/26 10:30:28 mento Exp $
  1372. .IP \fIplane_mask\fP 1i
  1373. Specifies the plane mask.
  1374. .\" *** JIM: NEED MORE INFO FOR THIS. ***
  1375. .\" End marker code here
  1376. .LP
  1377. .PN XSetState
  1378. can generate
  1379. .PN BadAlloc ,
  1380. .PN BadGC ,
  1381. and
  1382. .PN BadValue 
  1383. errors.
  1384. .LP
  1385. .sp
  1386. To set the foreground of a given GC, use
  1387. .PN XSetForeground .
  1388. .IN "XSetForeground" "" "@DEF@"
  1389. .\" Start marker code here
  1390. .FD 0
  1391. .\" $Header: XSetFgrnd.f,v 1.1 88/02/26 10:03:08 mento Exp $
  1392. XSetForeground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^)
  1393. .br
  1394.       Display *\fIdisplay\fP\^;
  1395. .br
  1396.       GC \fIgc\fP\^;
  1397. .br
  1398.       unsigned long \fIforeground\fP\^;
  1399. .FN
  1400. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1401. .IP \fIdisplay\fP 1i
  1402. Specifies the connection to the X server.
  1403. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1404. .IP \fIgc\fP 1i
  1405. Specifies the GC.
  1406. .\" $Header: foreground.a,v 1.2 88/05/09 11:35:55 mento Exp $
  1407. .IP \fIforeground\fP 1i
  1408. Specifies the foreground you want to set for the specified GC.
  1409. .\" End marker code here
  1410. .LP
  1411. .PN XSetForeground
  1412. can generate
  1413. .PN BadAlloc
  1414. and
  1415. .PN BadGC 
  1416. errors.
  1417. .LP
  1418. .sp
  1419. To set the background of a given GC, use
  1420. .PN XSetBackground .
  1421. .IN "XSetBackground" "" "@DEF@"
  1422. .\" Start marker code here
  1423. .FD 0
  1424. .\" $Header: XSetBckgrnd.f,v 1.1 88/02/26 10:02:56 mento Exp $
  1425. XSetBackground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIbackground\fP\^)
  1426. .br
  1427.       Display *\fIdisplay\fP\^;
  1428. .br
  1429.       GC \fIgc\fP\^;
  1430. .br
  1431.       unsigned long \fIbackground\fP\^;
  1432. .FN
  1433. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1434. .IP \fIdisplay\fP 1i
  1435. Specifies the connection to the X server.
  1436. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1437. .IP \fIgc\fP 1i
  1438. Specifies the GC.
  1439. .\" $Header: background.a,v 1.2 88/05/09 11:36:36 mento Exp $
  1440. .IP \fIbackground\fP 1i
  1441. Specifies the background you want to set for the specified GC.
  1442. .\" End marker code here
  1443. .LP
  1444. .PN XSetBackground
  1445. can generate
  1446. .PN BadAlloc
  1447. and
  1448. .PN BadGC 
  1449. errors.
  1450. .LP
  1451. .sp
  1452. To set the display function in a given GC, use
  1453. .PN XSetFunction .
  1454. .IN "XSetFunction" "" "@DEF@"
  1455. .\" Start marker code here
  1456. .FD 0
  1457. .\" $Header: XSetFunc.f,v 1.1 88/02/26 10:03:14 mento Exp $
  1458. XSetFunction\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfunction\fP\^)
  1459. .br
  1460.       Display *\fIdisplay\fP\^;
  1461. .br
  1462.       GC \fIgc\fP\^;
  1463. .br
  1464.       int \fIfunction\fP\^;
  1465. .FN
  1466. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1467. .IP \fIdisplay\fP 1i
  1468. Specifies the connection to the X server.
  1469. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1470. .IP \fIgc\fP 1i
  1471. Specifies the GC.
  1472. .\" $Header: function.a,v 1.2 88/05/09 11:37:19 mento Exp $
  1473. .IP \fIfunction\fP 1i
  1474. Specifies the function you want to set for the specified GC.
  1475. .\" End marker code here
  1476. .LP
  1477. .PN XSetFunction
  1478. can generate
  1479. .PN BadAlloc ,
  1480. .PN BadGC ,
  1481. and
  1482. .PN BadValue 
  1483. errors.
  1484. .LP
  1485. .sp
  1486. To set the plane mask of a given GC, use
  1487. .PN XSetPlaneMask .
  1488. .IN "XSetPlaneMask" "" "@DEF@"
  1489. .\" Start marker code here
  1490. .FD 0
  1491. .\" $Header: XSetPlnMsk.f,v 1.1 88/02/26 10:03:26 mento Exp $
  1492. XSetPlaneMask\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIplane_mask\fP\^)
  1493. .br
  1494.       Display *\fIdisplay\fP\^;
  1495. .br
  1496.       GC \fIgc\fP\^;
  1497. .br
  1498.       unsigned long \fIplane_mask\fP\^;
  1499. .FN
  1500. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1501. .IP \fIdisplay\fP 1i
  1502. Specifies the connection to the X server.
  1503. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1504. .IP \fIgc\fP 1i
  1505. Specifies the GC.
  1506. .\" $Header: plane_mask.a,v 1.1 88/02/26 10:30:28 mento Exp $
  1507. .IP \fIplane_mask\fP 1i
  1508. Specifies the plane mask.
  1509. .\" *** JIM: NEED MORE INFO FOR THIS. ***
  1510. .\" End marker code here
  1511. .LP
  1512. .PN XSetPlaneMask
  1513. can generate
  1514. .PN BadAlloc
  1515. and
  1516. .PN BadGC 
  1517. errors.
  1518. .NH 3
  1519. Setting the Line Attributes and Dashes
  1520. .XS
  1521. \*(SN Setting the Line Attributes and Dashes 
  1522. .XE
  1523. .LP
  1524. To set the line drawing components of a given GC, use
  1525. .PN XSetLineAttributes .
  1526. .IN "XSetLineAttributes" "" "@DEF@"
  1527. .\" Start marker code here
  1528. .FD 0
  1529. .\" $Header: XSetLnStle.f,v 1.1 88/02/26 10:03:22 mento Exp $
  1530. XSetLineAttributes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIline_width\fP\^, \fIline_style\fP\^, \fIcap_style\fP\^, \fIjoin_style\fP\^)
  1531. .br
  1532.       Display *\fIdisplay\fP\^;
  1533. .br
  1534.       GC \fIgc\fP\^;
  1535. .br
  1536.       unsigned int \fIline_width\fP\^;
  1537. .br
  1538.       int \fIline_style\fP\^;
  1539. .br
  1540.       int \fIcap_style\fP\^;
  1541. .br
  1542.       int \fIjoin_style\fP\^;
  1543. .FN
  1544. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1545. .IP \fIdisplay\fP 1i
  1546. Specifies the connection to the X server.
  1547. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1548. .IP \fIgc\fP 1i
  1549. Specifies the GC.
  1550. .\" $Header: line_width.a,v 1.2 88/05/09 11:40:12 mento Exp $
  1551. .IP \fIline_width\fP 1i
  1552. Specifies the line-width you want to set for the specified GC.
  1553. .\" $Header: line_style.a,v 1.2 88/05/09 11:43:02 mento Exp $
  1554. .IP \fIline_style\fP 1i
  1555. Specifies the line-style you want to set for the specified GC.
  1556. You can pass
  1557. .PN LineSolid ,
  1558. .PN LineOnOffDash ,
  1559. or
  1560. .PN LineDoubleDash .
  1561. .\" $Header: cap_style.a,v 1.2 88/05/09 11:44:16 mento Exp $
  1562. .IP \fIcap_style\fP 1i
  1563. Specifies the line-style and cap-style you want to set for the specified GC.
  1564. You can pass
  1565. .PN CapNotLast ,
  1566. .PN CapButt ,
  1567. .PN CapRound ,
  1568. or
  1569. .PN CapProjecting .
  1570. .\" $Header: join_style.a,v 1.3 88/05/09 14:18:01 mento Exp $
  1571. .IP \fIjoin_style\fP 1i
  1572. Specifies the line join-style you want to set for the specified GC.
  1573. You can pass
  1574. .PN JoinMiter ,
  1575. .PN JoinRound ,
  1576. or
  1577. .PN JoinBevel .
  1578. .\" End marker code here
  1579. .LP
  1580. .PN XSetLineAttributes
  1581. can generate
  1582. .PN BadAlloc ,
  1583. .PN BadGC ,
  1584. and
  1585. .PN BadValue 
  1586. errors.
  1587. .LP
  1588. .sp
  1589. To set the dash-offset and dash-list for dashed line styles of a given GC, use
  1590. .PN XSetDashes .
  1591. .IN "XSetDashes" "" "@DEF@"
  1592. .\" Start marker code here
  1593. .FD 0
  1594. .\" $Header: XSetDashes.f,v 1.1 88/02/26 10:03:06 mento Exp $
  1595. XSetDashes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIdash_offset\fP\^, \fIdash_list\fP\^, \fIn\fP\^)
  1596. .br
  1597.         Display *\fIdisplay\fP\^;
  1598. .br
  1599.         GC \fIgc\fP\^;
  1600. .br
  1601.         int \fIdash_offset\fP\^;
  1602. .br
  1603.         char \fIdash_list\fP[]\^;
  1604. .br
  1605.         int \fIn\fP\^;
  1606. .FN
  1607. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1608. .IP \fIdisplay\fP 1i
  1609. Specifies the connection to the X server.
  1610. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1611. .IP \fIgc\fP 1i
  1612. Specifies the GC.
  1613. .\" $Header: dashoff.a,v 1.2 88/05/09 11:46:56 mento Exp $
  1614. .IP \fIdash_offset\fP 1i
  1615. Specifies the phase of the pattern for the dashed line-style you want to set
  1616. for the specified GC. 
  1617. .\" $Header: dashlist.a,v 1.2 88/05/09 11:47:52 mento Exp $
  1618. .IP \fIdash_list\fP 1i
  1619. Specifies the dash-list for the dashed line-style
  1620. you want to set for the specified GC. 
  1621. .\" $Header: n3.a,v 1.2 88/05/11 11:38:49 mento Exp $
  1622. .IP \fIn\fP 1i
  1623. Specifies the number of elements in dash_list. 
  1624. .\" End marker code here
  1625. .LP 
  1626. .\" $Header: XSetDashes.d,v 1.4 88/08/18 08:11:08 mento Exp $
  1627. The
  1628. .PN XSetDashes
  1629. function sets the dash-offset and dash-list attributes for dashed line styles
  1630. in the specified GC.
  1631. There must be at least one element in the specified dash_list,
  1632. or a
  1633. .PN BadValue
  1634. error results. 
  1635. The initial and alternating elements (second, fourth, and so on) 
  1636. of the dash_list are the even dashes, and
  1637. the others are the odd dashes.
  1638. Each element specifies a dash length in pixels.
  1639. All of the elements must be nonzero,
  1640. or a
  1641. .PN BadValue
  1642. error results.
  1643. Specifying an odd-length list is equivalent to specifying the same list
  1644. concatenated with itself to produce an even-length list.
  1645. .LP
  1646. The dash-offset defines the phase of the pattern,
  1647. specifying how many pixels into the dash-list the pattern
  1648. should actually begin in any single graphics request.
  1649. Dashing is continuous through path elements combined with a join-style
  1650. but is reset to the dash-offset between each sequence of joined lines.
  1651. .LP
  1652. The unit of measure for dashes is the same for the ordinary coordinate system.
  1653. Ideally, a dash length is measured along the slope of the line, but implementations
  1654. are only required to match this ideal for horizontal and vertical lines.
  1655. Failing the ideal semantics, it is suggested that the length be measured along the
  1656. major axis of the line.
  1657. The major axis is defined as the x axis for lines drawn at an angle of between
  1658. \-45 and +45 degrees or between 135 and 225 degrees from the x axis.
  1659. For all other lines, the major axis is the y axis.
  1660. .LP
  1661. .PN XSetDashes
  1662. can generate
  1663. .PN BadAlloc ,
  1664. .PN BadGC ,
  1665. and
  1666. .PN BadValue 
  1667. errors.
  1668. .NH 3
  1669. Setting the Fill Style and Fill Rule 
  1670. .XS
  1671. \*(SN Setting the Fill Style and Fill Rule 
  1672. .XE
  1673. .LP
  1674. To set the fill-style of a given GC, use
  1675. .PN XSetFillStyle .
  1676. .IN "XSetFillStyle" "" "@DEF@"
  1677. .\" Start marker code here
  1678. .FD 0
  1679. .\" $Header: XSetFStyle.f,v 1.1 88/02/26 10:03:07 mento Exp $
  1680. XSetFillStyle\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_style\fP\^)
  1681. .br
  1682.       Display *\fIdisplay\fP\^;
  1683. .br
  1684.       GC \fIgc\fP\^;
  1685. .br
  1686.       int \fIfill_style\fP\^;
  1687. .FN
  1688. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1689. .IP \fIdisplay\fP 1i
  1690. Specifies the connection to the X server.
  1691. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1692. .IP \fIgc\fP 1i
  1693. Specifies the GC.
  1694. .\" $Header: fill_style.a,v 1.3 88/05/09 11:54:36 mento Exp $
  1695. .IP \fIfill_style\fP 1i
  1696. Specifies the fill-style you want to set for the specified GC.
  1697. You can pass
  1698. .PN FillSolid ,
  1699. .PN FillTiled ,
  1700. .PN FillStippled ,
  1701. or
  1702. .PN FillOpaqueStippled .
  1703. .\" End marker code here
  1704. .LP
  1705. .PN XSetFillStyle
  1706. can generate
  1707. .PN BadAlloc ,
  1708. .PN BadGC ,
  1709. and
  1710. .PN BadValue 
  1711. errors.
  1712. .LP
  1713. .sp
  1714. To set the fill-rule of a given GC, use
  1715. .PN XSetFillRule .
  1716. .IN "XSetFillRule" "" "@DEF@"
  1717. .\" Start marker code here
  1718. .FD 0
  1719. .\" $Header: XSetFRule.f,v 1.1 88/02/26 10:03:07 mento Exp $
  1720. XSetFillRule\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_rule\fP\^)
  1721. .br
  1722.       Display *\fIdisplay\fP\^;
  1723. .br
  1724.       GC \fIgc\fP\^;
  1725. .br
  1726.       int \fIfill_rule\fP\^;
  1727. .FN
  1728. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1729. .IP \fIdisplay\fP 1i
  1730. Specifies the connection to the X server.
  1731. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1732. .IP \fIgc\fP 1i
  1733. Specifies the GC.
  1734. .\" $Header: fill_rule.a,v 1.3 88/05/09 11:57:36 mento Exp $
  1735. .IP \fIfill_rule\fP 1i
  1736. Specifies the fill-rule you want to set for the specified GC.
  1737. You can pass 
  1738. .PN EvenOddRule
  1739. or
  1740. .PN WindingRule .
  1741. .\" End marker code here
  1742. .LP
  1743. .PN XSetFillRule
  1744. can generate
  1745. .PN BadAlloc ,
  1746. .PN BadGC ,
  1747. and
  1748. .PN BadValue 
  1749. errors.
  1750. .NH 3
  1751. Setting the Fill Tile and Stipple 
  1752. .XS
  1753. \*(SN Setting the Fill Tile and Stipple 
  1754. .XE
  1755. .LP
  1756. Some displays have hardware support for tiling or
  1757. stippling with patterns of specific sizes.
  1758. Tiling and stippling operations that restrict themselves to those specific
  1759. sizes run much faster than such operations with arbitrary size patterns.
  1760. Xlib provides functions that you can use to determine the best size, 
  1761. tile, or stipple for the display
  1762. as well as to set the tile or stipple shape and the tile or stipple origin.
  1763. .LP
  1764. .sp
  1765. To obtain the best size of a tile, stipple, or cursor, use
  1766. .PN XQueryBestSize .
  1767. .IN "XQueryBestSize" "" "@DEF@"
  1768. .\" Start marker code here
  1769. .FD 0
  1770. Status XQueryBestSize\^(\^\fIdisplay\fP, \fIclass\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
  1771. .br
  1772.       Display *\fIdisplay\fP\^;
  1773. .br
  1774.       int \fIclass\fP\^;
  1775. .br
  1776.       Drawable \fIwhich_screen\fP\^;
  1777. .br
  1778.       unsigned int \fIwidth\fP, \fIheight\fP\^;
  1779. .br
  1780.       unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
  1781. .FN
  1782. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1783. .IP \fIdisplay\fP 1i
  1784. Specifies the connection to the X server.
  1785. .IP \fIclass\fP 1i
  1786. Specifies the class that you are interested in.
  1787. You can pass 
  1788. .PN TileShape , 
  1789. .PN CursorShape , 
  1790. or 
  1791. .PN StippleShape .
  1792. .IP \fIwhich_screen\fP 1i
  1793. Specifies any drawable on the screen.
  1794. .\" $Header: widtheight.a,v 1.1 88/02/26 10:32:27 mento Exp $
  1795. .IP \fIwidth\fP 1i
  1796. .br
  1797. .ns
  1798. .IP \fIheight\fP 1i
  1799. Specify the width and height.
  1800. .\" $Header: rwidtheight.a,v 1.2 88/05/09 11:58:59 mento Exp $
  1801. .IP \fIwidth_return\fP 1i
  1802. .br
  1803. .ns
  1804. .IP \fIheight_return\fP 1i
  1805. Return the width and height of the object best supported 
  1806. by the display hardware.
  1807. .\" End marker code here
  1808. .LP
  1809. .\" $Header: XQBestSize.d,v 1.2 88/06/11 07:52:31 mento Exp $
  1810. The
  1811. .PN XQueryBestSize
  1812. function returns the best or closest size to the specified size.
  1813. For 
  1814. .PN CursorShape ,
  1815. this is the largest size that can be fully displayed on the screen specified by
  1816. which_screen.
  1817. For 
  1818. .PN TileShape ,
  1819. this is the size that can be tiled fastest.
  1820. For 
  1821. .PN StippleShape ,
  1822. this is the size that can be stippled fastest.
  1823. For 
  1824. .PN CursorShape ,
  1825. the drawable indicates the desired screen.
  1826. For 
  1827. .PN TileShape 
  1828. and 
  1829. .PN StippleShape ,
  1830. the drawable indicates the screen and possibly the window class and depth.
  1831. An 
  1832. .PN InputOnly 
  1833. window cannot be used as the drawable for 
  1834. .PN TileShape
  1835. or 
  1836. .PN StippleShape ,
  1837. or a
  1838. .PN BadMatch 
  1839. error results.
  1840. .LP
  1841. .PN XQueryBestSize
  1842. can generate
  1843. .PN BadDrawable ,
  1844. .PN BadMatch ,
  1845. and 
  1846. .PN BadValue 
  1847. errors.
  1848. .LP
  1849. .sp
  1850. To obtain the best fill tile shape, use
  1851. .PN XQueryBestTile .
  1852. .IN "XQueryBestTile" "" "@DEF@"
  1853. .\" Start marker code here
  1854. .FD 0
  1855. Status XQueryBestTile\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
  1856. .br
  1857.       Display *\fIdisplay\fP\^;
  1858. .br
  1859.       Drawable \fIwhich_screen\fP\^;
  1860. .br
  1861.       unsigned int \fIwidth\fP, \fIheight\fP\^;
  1862. .br
  1863.       unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
  1864. .FN
  1865. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1866. .IP \fIdisplay\fP 1i
  1867. Specifies the connection to the X server.
  1868. .IP \fIwhich_screen\fP 1i
  1869. Specifies any drawable on the screen.
  1870. .\" $Header: widtheight.a,v 1.1 88/02/26 10:32:27 mento Exp $
  1871. .IP \fIwidth\fP 1i
  1872. .br
  1873. .ns
  1874. .IP \fIheight\fP 1i
  1875. Specify the width and height.
  1876. .\" $Header: rwidtheight.a,v 1.2 88/05/09 11:58:59 mento Exp $
  1877. .IP \fIwidth_return\fP 1i
  1878. .br
  1879. .ns
  1880. .IP \fIheight_return\fP 1i
  1881. Return the width and height of the object best supported 
  1882. by the display hardware.
  1883. .\" End marker code here
  1884. .LP
  1885. .\" $Header: XQTileShp.d,v 1.2 88/06/11 07:52:32 mento Exp $
  1886. The
  1887. .PN XQueryBestTile
  1888. function returns the best or closest size, that is, the size that can be
  1889. tiled fastest on the screen specified by which_screen.
  1890. The drawable indicates the screen and possibly the window class and depth.
  1891. If an 
  1892. .PN InputOnly 
  1893. window is used as the drawable, a 
  1894. .PN BadMatch 
  1895. error results.
  1896. .LP
  1897. .PN XQueryBestTile
  1898. can generate
  1899. .PN BadDrawable
  1900. and
  1901. .PN BadMatch 
  1902. errors.
  1903. .LP
  1904. .sp
  1905. To obtain the best stipple shape, use
  1906. .PN XQueryBestStipple .
  1907. .IN "XQueryBestStipple" "" "@DEF@"
  1908. .\" Start marker code here
  1909. .FD 0
  1910. Status XQueryBestStipple\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
  1911. .br
  1912.       Display *\fIdisplay\fP\^;
  1913. .br
  1914.       Drawable \fIwhich_screen\fP\^;
  1915. .br
  1916.       unsigned int \fIwidth\fP, \fIheight\fP\^;
  1917. .br
  1918.       unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
  1919. .FN
  1920. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1921. .IP \fIdisplay\fP 1i
  1922. Specifies the connection to the X server.
  1923. .IP \fIwhich_screen\fP 1i
  1924. Specifies any drawable on the screen.
  1925. .\" $Header: widtheight.a,v 1.1 88/02/26 10:32:27 mento Exp $
  1926. .IP \fIwidth\fP 1i
  1927. .br
  1928. .ns
  1929. .IP \fIheight\fP 1i
  1930. Specify the width and height.
  1931. .\" $Header: rwidtheight.a,v 1.2 88/05/09 11:58:59 mento Exp $
  1932. .IP \fIwidth_return\fP 1i
  1933. .br
  1934. .ns
  1935. .IP \fIheight_return\fP 1i
  1936. Return the width and height of the object best supported 
  1937. by the display hardware.
  1938. .\" End marker code here
  1939. .LP
  1940. .\" $Header: XQStipShp.d,v 1.2 88/06/11 07:52:31 mento Exp $
  1941. The
  1942. .PN XQueryBestStipple
  1943. function returns the best or closest size, that is, the size that can be
  1944. stippled fastest on the screen specified by which_screen.
  1945. The drawable indicates the screen and possibly the window class and depth.
  1946. If an
  1947. .PN InputOnly
  1948. window is used as the drawable, a
  1949. .PN BadMatch
  1950. error results.
  1951. .LP
  1952. .PN XQueryBestStipple
  1953. can generate
  1954. .PN BadDrawable
  1955. and
  1956. .PN BadMatch 
  1957. errors.
  1958. .LP
  1959. .sp
  1960. To set the fill tile of a given GC, use
  1961. .PN XSetTile .
  1962. .IN "XSetTile" "" "@DEF@"
  1963. .\" Start marker code here
  1964. .FD 0
  1965. .\" $Header: XSetTile.f,v 1.1 88/02/26 10:03:42 mento Exp $
  1966. XSetTile\^(\^\fIdisplay\fP, \fIgc\fP\^, \fItile\fP\^)
  1967. .br
  1968.       Display *\fIdisplay\fP\^;
  1969. .br
  1970.       GC \fIgc\fP\^;
  1971. .br
  1972.       Pixmap \fItile\fP\^;
  1973. .FN
  1974. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1975. .IP \fIdisplay\fP 1i
  1976. Specifies the connection to the X server.
  1977. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1978. .IP \fIgc\fP 1i
  1979. Specifies the GC.
  1980. .\" $Header: tile1.a,v 1.2 88/05/09 12:02:14 mento Exp $
  1981. .IP \fItile\fP 1i
  1982. Specifies the fill tile you want to set for the specified GC. 
  1983. .\" End marker code here
  1984. .LP
  1985. The tile and GC must have the same depth,
  1986. or a
  1987. .PN BadMatch
  1988. error results.
  1989. .LP
  1990. .PN XSetTile
  1991. can generate
  1992. .PN BadAlloc ,
  1993. .PN BadGC ,
  1994. .PN BadMatch ,
  1995. and
  1996. .PN BadPixmap 
  1997. errors.
  1998. .LP
  1999. .sp
  2000. To set the stipple of a given GC, use
  2001. .PN XSetStipple .
  2002. .IN "XSetStipple" "" "@DEF@"
  2003. .\" Start marker code here
  2004. .FD 0
  2005. .\" $Header: XSetStipple.f,v 1.1 88/02/26 10:03:40 mento Exp $
  2006. XSetStipple\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIstipple\fP\^)
  2007. .br
  2008.       Display *\fIdisplay\fP\^;
  2009. .br
  2010.       GC \fIgc\fP\^;
  2011. .br
  2012.       Pixmap \fIstipple\fP\^;
  2013. .FN
  2014. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2015. .IP \fIdisplay\fP 1i
  2016. Specifies the connection to the X server.
  2017. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2018. .IP \fIgc\fP 1i
  2019. Specifies the GC.
  2020. .\" $Header: stipple.a,v 1.2 88/05/09 12:03:58 mento Exp $
  2021. .IP \fIstipple\fP 1i
  2022. Specifies the stipple you want to set for the specified GC.
  2023. .\" End marker code here
  2024. .LP
  2025. The stipple must have a depth of one,
  2026. or a
  2027. .PN BadMatch
  2028. error results.
  2029. .LP
  2030. .PN XSetStipple
  2031. can generate
  2032. .PN BadAlloc ,
  2033. .PN BadGC ,
  2034. .PN BadMatch ,
  2035. and
  2036. .PN BadPixmap 
  2037. errors.
  2038. .LP
  2039. .sp
  2040. To set the tile or stipple origin of a given GC, use
  2041. .PN XSetTSOrigin .
  2042. .IN "XSetTSOrigin" "" "@DEF@"
  2043. .\" Start marker code here
  2044. .FD 0
  2045. .\" $Header: XSetTSOrig.f,v 1.1 88/02/26 10:03:41 mento Exp $
  2046. XSetTSOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIts_x_origin\fP\^, \fIts_y_origin\fP\^)
  2047. .br
  2048.       Display *\fIdisplay\fP\^;
  2049. .br
  2050.       GC \fIgc\fP\^;
  2051. .br
  2052.       int \fIts_x_origin\fP\^, \fIts_y_origin\fP\^;
  2053. .FN
  2054. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2055. .IP \fIdisplay\fP 1i
  2056. Specifies the connection to the X server.
  2057. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2058. .IP \fIgc\fP 1i
  2059. Specifies the GC.
  2060. .\" $Header: tsxy.a,v 1.2 88/04/06 09:57:10 mento Exp $
  2061. .IP \fIts_x_origin\fP 1i
  2062. .br
  2063. .ns
  2064. .IP \fIts_y_origin\fP 1i
  2065. Specify the x and y coordinates of the tile and stipple origin.
  2066. .\" End marker code here
  2067. .LP
  2068. When graphics requests call for tiling or stippling,
  2069. the parent's origin will be interpreted relative to whatever destination 
  2070. drawable is specified in the graphics request.
  2071. .LP
  2072. .PN XSetTSOrigin
  2073. can generate
  2074. .PN BadAlloc
  2075. and
  2076. .PN BadGC 
  2077. error.
  2078. .NH 3
  2079. Setting the Current Font 
  2080. .XS
  2081. \*(SN Setting the Current Font 
  2082. .XE
  2083. .LP
  2084. To set the current font of a given GC, use
  2085. .PN XSetFont .
  2086. .IN "XSetFont" "" "@DEF@"
  2087. .\" Start marker code here
  2088. .FD 0
  2089. .\" $Header: XSetFont.f,v 1.1 88/02/26 10:03:09 mento Exp $
  2090. XSetFont\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfont\fP\^)
  2091. .br
  2092.       Display *\fIdisplay\fP\^;
  2093. .br
  2094.       GC \fIgc\fP\^;
  2095. .br
  2096.       Font \fIfont\fP\^;
  2097. .FN
  2098. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2099. .IP \fIdisplay\fP 1i
  2100. Specifies the connection to the X server.
  2101. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2102. .IP \fIgc\fP 1i
  2103. Specifies the GC.
  2104. .\" $Header: font.a,v 1.2 88/05/09 14:28:06 mento Exp $
  2105. .IP \fIfont\fP 1i
  2106. Specifies the font.
  2107. .\" End marker code here
  2108. .LP
  2109. .PN XSetFont
  2110. can generate
  2111. .PN BadAlloc ,
  2112. .PN BadFont ,
  2113. and 
  2114. .PN BadGC 
  2115. errors.
  2116. .NH 3
  2117. Setting the Clip Region
  2118. .XS
  2119. \*(SN Setting the Clip Region 
  2120. .XE
  2121. .LP
  2122. Xlib provides functions that you can use to set the clip-origin 
  2123. and the clip-mask or set the clip-mask to a list of rectangles.
  2124. .LP
  2125. .sp
  2126. To set the clip-origin of a given GC, use
  2127. .PN XSetClipOrigin .
  2128. .IN "XSetClipOrigin" "" "@DEF@"
  2129. .\" Start marker code here
  2130. .FD 0
  2131. .\" $Header: XSetClipOrig.f,v 1.1 88/02/26 10:02:57 mento Exp $
  2132. XSetClipOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^)
  2133. .br
  2134.       Display *\fIdisplay\fP\^;
  2135. .br
  2136.       GC \fIgc\fP\^;
  2137. .br
  2138.       int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^;
  2139. .FN
  2140. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2141. .IP \fIdisplay\fP 1i
  2142. Specifies the connection to the X server.
  2143. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2144. .IP \fIgc\fP 1i
  2145. Specifies the GC.
  2146. .\" $Header: clipxy.a,v 1.3 88/05/09 12:10:59 mento Exp $
  2147. .IP \fIclip_x_origin\fP 1i
  2148. .br
  2149. .ns
  2150. .IP \fIclip_y_origin\fP 1i
  2151. Specify the x and y coordinates of the clip-mask origin.
  2152. .\" End marker code here
  2153. .LP
  2154. The clip-mask origin is interpreted relative to the origin of whatever 
  2155. destination drawable is specified in the graphics request.
  2156. .LP
  2157. .PN XSetClipOrigin
  2158. can generate
  2159. .PN BadAlloc
  2160. and
  2161. .PN BadGC 
  2162. errors.
  2163. .LP
  2164. .sp
  2165. To set the clip-mask of a given GC to the specified pixmap, use
  2166. .PN XSetClipMask .
  2167. .IN "XSetClipMask" "" "@DEF@"
  2168. .\" Start marker code here
  2169. .FD 0
  2170. XSetClipMask\^(\^\fIdisplay\fP, \fIgc\fP, \fIpixmap\fP\^)
  2171. .br
  2172.       Display *\fIdisplay\fP\^;
  2173. .br
  2174.       GC \fIgc\fP\^;
  2175. .br
  2176.       Pixmap \fIpixmap\fP\^;
  2177. .FN
  2178. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2179. .IP \fIdisplay\fP 1i
  2180. Specifies the connection to the X server.
  2181. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2182. .IP \fIgc\fP 1i
  2183. Specifies the GC.
  2184. .IP \fIpixmap\fP 1i
  2185. Specifies the pixmap or
  2186. .PN None .
  2187. .\" End marker code here
  2188. .LP
  2189. If the clip-mask is set to
  2190. .PN None ,
  2191. the pixels are are always drawn (regardless of the clip-origin).
  2192. .LP
  2193. .PN XSetClipMask
  2194. can generate
  2195. .PN BadAlloc ,
  2196. .PN BadGC ,
  2197. .PN BadMatch ,
  2198. and
  2199. .PN BadPixmap 
  2200. errors.
  2201. .LP
  2202. .sp
  2203. To set the clip-mask of a given GC to the specified list of rectangles, use
  2204. .PN XSetClipRectangles .
  2205. .IN "XSetClipRectangles" "" "@DEF@"
  2206. .\" Start marker code here
  2207. .FD 0
  2208. .\" $Header: XSetClpRects.f,v 1.1 88/02/26 10:02:59 mento Exp $
  2209. XSetClipRectangles\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^, \fIrectangles\fP\^, \fIn\fP\^, \fIordering\fP\^)
  2210. .br
  2211.       Display *\fIdisplay\fP\^;
  2212. .br
  2213.       GC \fIgc\fP\^;
  2214. .br
  2215.       int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^;
  2216. .br
  2217.       XRectangle \fIrectangles\fP[]\^;
  2218. .br
  2219.       int \fIn\fP\^;
  2220. .br
  2221.       int \fIordering\fP\^;
  2222. .FN
  2223. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2224. .IP \fIdisplay\fP 1i
  2225. Specifies the connection to the X server.
  2226. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2227. .IP \fIgc\fP 1i
  2228. Specifies the GC.
  2229. .\" $Header: clipxy.a,v 1.3 88/05/09 12:10:59 mento Exp $
  2230. .IP \fIclip_x_origin\fP 1i
  2231. .br
  2232. .ns
  2233. .IP \fIclip_y_origin\fP 1i
  2234. Specify the x and y coordinates of the clip-mask origin.
  2235. .\" $Header: rectangles1.a,v 1.2 88/05/09 12:16:32 mento Exp $
  2236. .IP \fIrectangles\fP 1i
  2237. Specifies an array of rectangles that define the clip-mask.
  2238. .\" $Header: n2.a,v 1.1 88/02/26 10:29:03 mento Exp $
  2239. .IP \fIn\fP 1i
  2240. Specifies the number of rectangles. 
  2241. .\" $Header: ordering.a,v 1.2 88/05/09 12:17:14 mento Exp $
  2242. .IP \fIordering\fP 1i
  2243. Specifies the ordering relations on the rectangles.
  2244. You can pass
  2245. .PN Unsorted ,
  2246. .PN YSorted ,
  2247. .PN YXSorted ,
  2248. or
  2249. .PN YXBanded .
  2250. .\" End marker code here
  2251. .LP
  2252. .\" $Header: XSetClpRects.d,v 1.3 88/06/11 07:53:03 mento Exp $
  2253. The
  2254. .PN XSetClipRectangles
  2255. function changes the clip-mask in the specified GC 
  2256. to the specified list of rectangles and sets the clip origin.
  2257. The output is clipped to remain contained within the
  2258. rectangles.
  2259. The clip-origin is interpreted relative to the origin of
  2260. whatever destination drawable is specified in a graphics request.  
  2261. The rectangle coordinates are interpreted relative to the clip-origin.  
  2262. The rectangles should be nonintersecting, or the graphics results will be
  2263. undefined.
  2264. Note that the list of rectangles can be empty, 
  2265. which effectively disables output.
  2266. This is the opposite of passing
  2267. .PN None
  2268. as the clip-mask in
  2269. .PN XCreateGC ,
  2270. .PN XChangeGC ,
  2271. and
  2272. .PN XSetClipMask .
  2273. .LP
  2274. If known by the client, ordering relations on the rectangles can be
  2275. specified with the ordering argument. 
  2276. This may provide faster operation
  2277. by the server. 
  2278. If an incorrect ordering is specified, the X server may generate a
  2279. .PN BadMatch
  2280. error, but it is not required to do so.
  2281. If no error is generated, the graphics
  2282. results are undefined.
  2283. .PN Unsorted 
  2284. means the rectangles are in arbitrary order.
  2285. .PN YSorted 
  2286. means that the rectangles are nondecreasing in their Y origin.
  2287. .PN YXSorted 
  2288. additionally constrains 
  2289. .PN YSorted 
  2290. order in that all
  2291. rectangles with an equal Y origin are nondecreasing in their X
  2292. origin.  
  2293. .PN YXBanded 
  2294. additionally constrains 
  2295. .PN YXSorted 
  2296. by requiring that,
  2297. for every possible Y scanline, all rectangles that include that
  2298. scanline have an identical Y origins and Y extents.
  2299. .LP
  2300. .PN XSetClipRectangles
  2301. can generate
  2302. .PN BadAlloc , 
  2303. .PN BadGC ,
  2304. .PN BadMatch ,
  2305. and
  2306. .PN BadValue 
  2307. errors.
  2308. .LP
  2309. Xlib provides a set of basic functions for performing
  2310. region arithmetic.
  2311. For information about these functions,
  2312. see section 16.5.
  2313. .NH 3
  2314. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure 
  2315. .XS
  2316. \*(SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure 
  2317. .XE
  2318. .LP
  2319. To set the arc mode of a given GC, use
  2320. .PN XSetArcMode .
  2321. .IN "XSetArcMode" "" "@DEF@"
  2322. .\" Start marker code here
  2323. .FD 0
  2324. .\" $Header: XSetArcMode.f,v 1.1 88/02/26 10:02:54 mento Exp $
  2325. XSetArcMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIarc_mode\fP\^)
  2326. .br
  2327.       Display *\fIdisplay\fP\^;
  2328. .br
  2329.       GC \fIgc\fP\^;
  2330. .br
  2331.       int \fIarc_mode\fP\^;
  2332. .FN
  2333. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2334. .IP \fIdisplay\fP 1i
  2335. Specifies the connection to the X server.
  2336. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2337. .IP \fIgc\fP 1i
  2338. Specifies the GC.
  2339. .\" $Header: arc_mode.a,v 1.2 88/05/09 12:21:20 mento Exp $
  2340. .IP \fIarc_mode\fP 1i
  2341. Specifies the arc mode.
  2342. You can pass
  2343. .PN ArcChord
  2344. or
  2345. .PN ArcPieSlice .
  2346. .\" End marker code here
  2347. .LP
  2348. .PN XSetArcMode
  2349. can generate
  2350. .PN BadAlloc ,
  2351. .PN BadGC ,
  2352. and
  2353. .PN BadValue 
  2354. errors.
  2355. .LP
  2356. .sp
  2357. To set the subwindow mode of a given GC, use
  2358. .PN XSetSubwindowMode .
  2359. .IN "XSetSubwindowMode" "" "@DEF@"
  2360. .\" Start marker code here
  2361. .FD 0
  2362. .\" $Header: XSetSubMode.f,v 1.1 88/02/26 10:03:40 mento Exp $
  2363. XSetSubwindowMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIsubwindow_mode\fP\^)
  2364. .br
  2365.       Display *\fIdisplay\fP\^;
  2366. .br
  2367.       GC \fIgc\fP\^;
  2368. .br
  2369.       int \fIsubwindow_mode\fP\^;
  2370. .FN
  2371. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2372. .IP \fIdisplay\fP 1i
  2373. Specifies the connection to the X server.
  2374. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2375. .IP \fIgc\fP 1i
  2376. Specifies the GC.
  2377. .\" $Header: sub_mode.a,v 1.2 88/05/09 12:23:45 mento Exp $
  2378. .IP \fIsubwindow_mode\fP 1i
  2379. Specifies the subwindow mode.
  2380. You can pass
  2381. .PN ClipByChildren
  2382. or
  2383. .PN IncludeInferiors .
  2384. .\" End marker code here
  2385. .LP
  2386. .PN XSetSubwindowMode
  2387. can generate
  2388. .PN BadAlloc ,
  2389. .PN BadGC ,
  2390. and
  2391. .PN BadValue 
  2392. errors.
  2393. .LP
  2394. .sp
  2395. To set the graphics-exposures flag of a given GC, use
  2396. .PN XSetGraphicsExposures .
  2397. .IN "XSetGraphicsExposures" "" "@DEF@"
  2398. .\" Start marker code here
  2399. .FD 0
  2400. .\" $Header: XSetGrExp.f,v 1.2 88/04/04 11:02:37 mento Exp $
  2401. XSetGraphicsExposures\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIgraphics_exposures\fP\^)
  2402. .br
  2403.       Display *\fIdisplay\fP\^;
  2404. .br
  2405.       GC \fIgc\fP\^;
  2406. .br
  2407.       Bool \fIgraphics_exposures\fP\^;
  2408. .FN
  2409. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2410. .IP \fIdisplay\fP 1i
  2411. Specifies the connection to the X server.
  2412. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2413. .IP \fIgc\fP 1i
  2414. Specifies the GC.
  2415. .\" $Header: graph_exp.a,v 1.4 88/08/18 08:13:37 mento Exp $
  2416. .IP \fIgraphics_exposures\fP 1i
  2417. Specifies a Boolean value that indicates whether you want
  2418. .PN GraphicsExpose
  2419. and
  2420. .PN NoExpose
  2421. events to be reported when calling
  2422. .PN XCopyArea
  2423. and
  2424. .PN XCopyPlane
  2425. with this GC.
  2426. .\" End marker code here
  2427. .LP
  2428. .PN XSetGraphicsExposures
  2429. can generate
  2430. .PN BadAlloc ,
  2431. .PN BadGC ,
  2432. and
  2433. .PN BadValue 
  2434. errors.
  2435. .bp
  2436.