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

  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 8\fP\s-1
  5.  
  6. \s+1\fBGraphics Functions\fP\s-1
  7. .sp 2
  8. .nr H1 8
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 8: Graphics Functions 
  17. .XE
  18. Once you have established a connection to a display,
  19. you can use the Xlib graphics functions to:
  20. .IP \(bu 5
  21. Clear and copy areas
  22. .IP \(bu 5
  23. Draw points, lines, rectangles, and arcs
  24. .IP \(bu 5
  25. Fill areas
  26. .IP \(bu 5
  27. Manipulate fonts
  28. .IP \(bu 5
  29. Draw text
  30. .IP \(bu 5
  31. Transfer images between clients and the server
  32. .RE
  33. .LP
  34. If the same drawable and GC is used for each call,
  35. Xlib batches back-to-back calls to
  36. .PN XDrawPoint ,
  37. .PN XDrawLine ,
  38. .PN XDrawRectangle ,
  39. .PN XFillArc ,
  40. and
  41. .PN XFillRectangle .
  42. Note that this reduces the total number of requests sent to the server.
  43. .NH 2
  44. Clearing Areas
  45. .XS
  46. \*(SN Clearing Areas 
  47. .XE
  48. .LP
  49. Xlib provides functions that you can use to clear an area or the entire window.
  50. Because pixmaps do not have defined backgrounds, 
  51. they cannot be filled by using the functions described in this section.
  52. Instead, to accomplish an analogous operation on a pixmap,
  53. you should use 
  54. .PN XFillRectangle ,
  55. which sets the pixmap to a known value.
  56. .LP
  57. .sp
  58. To clear a rectangular area of a given window, use
  59. .PN XClearArea .
  60. .IN "Areas" "clearing"
  61. .IN "Clearing" "areas"
  62. .IN "XClearArea" "" "@DEF@"
  63. .\" Start marker code here
  64. .FD 0
  65. .\" $Header: XClearArea.f,v 1.1 88/02/26 09:58:46 mento Exp $
  66. XClearArea\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIexposures\fP\^)
  67. .br
  68.       Display *\fIdisplay\fP\^;
  69. .br
  70.       Window \fIw\fP\^;
  71. .br
  72.       int \fIx\fP\^, \fIy\fP\^;
  73. .br
  74.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  75. .br
  76.       Bool \fIexposures\fP\^;
  77. .FN
  78. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  79. .IP \fIdisplay\fP 1i
  80. Specifies the connection to the X server.
  81. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  82. .IP \fIw\fP 1i
  83. Specifies the window.
  84. .ds Xy , which are relative to the origin of the window \
  85. and specify the upper-left corner of the rectangle
  86. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  87. .IP \fIx\fP 1i
  88. .br
  89. .ns
  90. .IP \fIy\fP 1i
  91. Specify the x and y coordinates\*(Xy.
  92. .ds Wh , which are the dimensions of the rectangle
  93. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  94. .IP \fIwidth\fP 1i
  95. .br
  96. .ns
  97. .IP \fIheight\fP 1i
  98. Specify the width and height\*(Wh.
  99. .\" $Header: exposures.a,v 1.2 88/05/13 07:34:33 mento Exp $
  100. .IP \fIexposures\fP 1i
  101. Specifies a Boolean value that indicates if
  102. .PN Expose
  103. events are to be generated.
  104. .\" End marker code here
  105. .LP
  106. .\" $Header: XClearArea.d,v 1.3 88/08/18 08:25:30 mento Exp $
  107. The
  108. .PN XClearArea
  109. function paints a rectangular area in the specified window according to the
  110. specified dimensions with the window's background pixel or pixmap.
  111. The subwindow-mode effectively is
  112. .PN ClipByChildren . 
  113. If width is zero, it
  114. is replaced with the current width of the window minus x.
  115. If height is
  116. zero, it is replaced with the current height of the window minus y.
  117. If the window has a defined background tile, 
  118. the rectangle clipped by any children is filled with this tile.
  119. If the window has
  120. background 
  121. .PN None , 
  122. the contents of the window are not changed.  
  123. In either
  124. case, if exposures is 
  125. .PN True , 
  126. one or more 
  127. .PN Expose 
  128. events are generated for regions of the rectangle that are either visible or are
  129. being retained in a backing store.
  130. If you specify a window whose class is
  131. .PN InputOnly ,
  132. a
  133. .PN BadMatch
  134. error results.
  135. .LP
  136. .PN XClearArea
  137. can generate
  138. .PN BadMatch ,
  139. .PN BadValue ,
  140. and
  141. .PN BadWindow 
  142. errors.
  143. .LP
  144. .sp
  145. To clear the entire area in a given window, use
  146. .PN XClearWindow .
  147. .IN "Window" "clearing"
  148. .IN "Clearing" "windows"
  149. .IN "XClearWindow" "" "@DEF@"
  150. .\" Start marker code here
  151. .FD 0
  152. .\" $Header: XClear.f,v 1.1 88/02/26 09:58:45 mento Exp $
  153. XClearWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
  154. .br
  155.       Display *\fIdisplay\fP\^;
  156. .br
  157.       Window \fIw\fP\^;
  158. .FN
  159. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  160. .IP \fIdisplay\fP 1i
  161. Specifies the connection to the X server.
  162. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  163. .IP \fIw\fP 1i
  164. Specifies the window.
  165. .\" End marker code here
  166. .LP
  167. .\" $Header: XClear.d,v 1.2 88/06/11 07:49:21 mento Exp $
  168. The
  169. .PN XClearWindow
  170. function clears the entire area in the specified window and is
  171. equivalent to
  172. .PN XClearArea
  173. (display, w, 0, 0, 0, 0, 
  174. .PN False ).
  175. If the window has a defined background tile, the rectangle is tiled with a
  176. plane-mask of all ones and 
  177. .PN GXcopy
  178. function.
  179. If the window has
  180. background 
  181. .PN None , 
  182. the contents of the window are not changed.  
  183. If you specify a window whose class is
  184. .PN InputOnly ,
  185. a
  186. .PN BadMatch
  187. error results. 
  188. .LP
  189. .PN XClearWindow
  190. can generate
  191. .PN BadMatch
  192. and
  193. .PN BadWindow 
  194. errors.
  195. .NH 2
  196. Copying Areas
  197. .XS
  198. \*(SN Copying Areas 
  199. .XE
  200. .LP
  201. Xlib provides functions that you can use to copy an area or a bit plane.
  202. .LP
  203. .sp
  204. To copy an area between drawables of the same
  205. root and depth, use
  206. .PN XCopyArea .
  207. .IN "Areas" "copying"
  208. .IN "Copying" "areas"
  209. .IN "XCopyArea" "" "@DEF@"
  210. .\" Start marker code here
  211. .FD 0
  212. .\" $Header: XCopyArea.f,v 1.1 88/02/26 09:58:59 mento Exp $
  213. XCopyArea\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^,  \fIdest_x\fP\^, \fIdest_y\fP\^)
  214. .br
  215.       Display *\fIdisplay\fP\^;
  216. .br
  217.       Drawable \fIsrc\fP\^, \fIdest\fP\^;
  218. .br
  219.       GC \fIgc\fP\^;
  220. .br
  221.       int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
  222. .br
  223.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  224. .br
  225.       int \fIdest_x\fP\^, \fIdest_y\fP\^;
  226. .FN
  227. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  228. .IP \fIdisplay\fP 1i
  229. Specifies the connection to the X server.
  230. .\" $Header: srcdest.a,v 1.1 88/02/26 10:31:20 mento Exp $
  231. .IP \fIsrc\fP 1i
  232. .br
  233. .ns
  234. .IP \fIdest\fP 1i
  235. Specify the source and destination rectangles to be combined. 
  236. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  237. .IP \fIgc\fP 1i
  238. Specifies the GC.
  239. .\" $Header: srcxy.a,v 1.3 88/05/13 07:40:32 mento Exp $
  240. .IP \fIsrc_x\fP 1i
  241. .br
  242. .ns
  243. .IP \fIsrc_y\fP 1i
  244. Specify the x and y coordinates, 
  245. which are relative to the origin of the source rectangle
  246. and specify its upper-left corner.
  247. .ds Wh , which are the dimensions of both the source \
  248. and destination rectangles
  249. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  250. .IP \fIwidth\fP 1i
  251. .br
  252. .ns
  253. .IP \fIheight\fP 1i
  254. Specify the width and height\*(Wh.
  255. .ds Dx , which are relative to the origin of the destination rectangle \
  256. and specify its upper-left corner
  257. .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
  258. .IP \fIdest_x\fP 1i
  259. .br
  260. .ns
  261. .IP \fIdest_y\fP 1i
  262. Specify the x and y coordinates\*(Dx. 
  263. .\" End marker code here
  264. .LP
  265. .\" $Header: XCopyArea.d,v 1.4 88/09/08 19:12:40 mento Exp $
  266. The
  267. .PN XCopyArea
  268. function combines the specified rectangle of src with the specified rectangle 
  269. of dest.
  270. The drawables must have the same root and depth,
  271. or a
  272. .PN BadMatch
  273. error results.
  274. .LP
  275. If regions of the source rectangle are obscured and have not been
  276. retained in backing store 
  277. or if regions outside the boundaries of the source drawable are specified, 
  278. those regions are not copied. 
  279. Instead, the 
  280. following occurs on all corresponding destination regions that are either
  281. visible or are retained in backing store.  
  282. If the destination is a window with a background other than 
  283. .PN None , 
  284. corresponding regions
  285. of the destination are tiled with that background
  286. (with plane-mask of all ones and
  287. .PN GXcopy 
  288. function).
  289. Regardless of tiling or whether the destination is a window or a pixmap,
  290. if graphics-exposures is 
  291. .PN True ,
  292. then
  293. .PN GraphicsExpose
  294. events for all corresponding destination regions are generated.
  295. If graphics-exposures is 
  296. .PN True 
  297. but no
  298. .PN GraphicsExpose
  299. events are generated, a
  300. .PN NoExpose 
  301. event is generated.
  302. Note that by default graphics-exposures is
  303. .PN True
  304. in new GCs.
  305. .LP
  306. This function uses these GC components: function, plane-mask, 
  307. subwindow-mode, graphics-exposures, clip-x-origin,
  308. clip-y-origin, and clip-mask.
  309. .LP
  310. .PN XCopyArea
  311. can generate
  312. .PN BadDrawable ,
  313. .PN BadGC ,
  314. and
  315. .PN BadMatch 
  316. errors.
  317. .sp
  318. .LP
  319. To copy a single bit plane of a given drawable, use
  320. .PN XCopyPlane .
  321. .IN "Plane" "copying"
  322. .IN "Copying" "planes"
  323. .IN "XCopyPlane" "" "@DEF@"
  324. .\" Start marker code here
  325. .FD 0
  326. .\" $Header: XCopyPlane.f,v 1.1 88/02/26 09:59:06 mento Exp $
  327. XCopyPlane\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIplane\fP\^)
  328. .br
  329.       Display *\fIdisplay\fP\^;
  330. .br
  331.       Drawable \fIsrc\fP\^, \fIdest\fP\^;
  332. .br
  333.       GC \fIgc\fP\^;
  334. .br
  335.       int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
  336. .br
  337.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  338. .br
  339.       int \fIdest_x\fP\^, \fIdest_y\fP\^;
  340. .br
  341.       unsigned long \fIplane\fP\^;
  342. .FN
  343. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  344. .IP \fIdisplay\fP 1i
  345. Specifies the connection to the X server.
  346. .\" $Header: srcdest.a,v 1.1 88/02/26 10:31:20 mento Exp $
  347. .IP \fIsrc\fP 1i
  348. .br
  349. .ns
  350. .IP \fIdest\fP 1i
  351. Specify the source and destination rectangles to be combined. 
  352. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  353. .IP \fIgc\fP 1i
  354. Specifies the GC.
  355. .\" $Header: srcxy.a,v 1.3 88/05/13 07:40:32 mento Exp $
  356. .IP \fIsrc_x\fP 1i
  357. .br
  358. .ns
  359. .IP \fIsrc_y\fP 1i
  360. Specify the x and y coordinates, 
  361. which are relative to the origin of the source rectangle
  362. and specify its upper-left corner.
  363. .ds Wh , which are the dimensions of both the source and destination rectangles
  364. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  365. .IP \fIwidth\fP 1i
  366. .br
  367. .ns
  368. .IP \fIheight\fP 1i
  369. Specify the width and height\*(Wh.
  370. .ds Dx , which are relative to the origin of the destination rectangle \
  371. and specify its upper-left corner
  372. .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
  373. .IP \fIdest_x\fP 1i
  374. .br
  375. .ns
  376. .IP \fIdest_y\fP 1i
  377. Specify the x and y coordinates\*(Dx. 
  378. .\" $Header: plane.a,v 1.3 88/05/13 13:48:24 mento Exp $
  379. .IP \fIplane\fP 1i
  380. Specifies the bit plane.
  381. You must set exactly one bit to 1.
  382. .\" End marker code here
  383. .LP
  384. .\" $Header: XCopyPlane.d,v 1.3 88/08/18 08:34:53 mento Exp $
  385. The
  386. .PN XCopyPlane
  387. function uses a single bit plane of the specified source rectangle
  388. combined with the specified GC to modify the specified rectangle of dest.
  389. The drawables must have the same root but need not have the same depth.
  390. If the drawables do not have the same root, a
  391. .PN BadMatch
  392. error results.
  393. If plane does not have exactly one bit set to 1 and the values of planes
  394. must be less than %2 sup n%, where \fIn\fP is the depth of src, a
  395. .PN BadValue
  396. error results.
  397. .LP
  398. Effectively, 
  399. .PN XCopyPlane
  400. forms a pixmap of the same depth as the rectangle of dest and with a
  401. size specified by the source region. 
  402. It uses the foreground/background pixels in the GC (foreground
  403. everywhere the bit plane in src contains a bit set to 1,
  404. background everywhere the bit plane in src contains a bit set to 0)
  405. and the equivalent of a 
  406. .PN CopyArea
  407. protocol request is performed with all the same exposure semantics.
  408. This can also be thought of as using the specified region of the source 
  409. bit plane as a stipple with a fill-style of
  410. .PN FillOpaqueStippled
  411. for filling a rectangular area of the destination.
  412. .LP
  413. This function uses these GC components: function, plane-mask, foreground,
  414. background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
  415. and clip-mask.
  416. .LP
  417. .PN XCopyPlane
  418. can generate
  419. .PN BadDrawable ,
  420. .PN BadGC ,
  421. .PN BadMatch ,
  422. and 
  423. .PN BadValue 
  424. errors.
  425. .NH 2
  426. Drawing Points, Lines, Rectangles, and Arcs
  427. .XS
  428. \*(SN Drawing Points, Lines, Rectangles, and Arcs 
  429. .XE
  430. .LP
  431. Xlib provides functions that you can use to draw:
  432. .IP \(bu 5
  433. A single point or multiple points
  434. .IP \(bu 5
  435. A single line or multiple lines
  436. .IP \(bu 5
  437. A single rectangle or multiple rectangles
  438. .IP \(bu 5
  439. A single arc or multiple arcs
  440. .LP
  441. Some of the functions described in the following sections
  442. use these structures:
  443. .LP
  444. .IN "XSegment" "" "@DEF@"
  445. .\" Start marker code here
  446. .Ds 0
  447. .TA .5i
  448. .ta .5i
  449. typedef struct {
  450.     short x1, y1, x2, y2;
  451. } XSegment;
  452. .De
  453. .\" End marker code here
  454. .LP
  455. .IN "XPoint" "" "@DEF@"
  456. .\" Start marker code here
  457. .Ds 0
  458. .TA .5i
  459. .ta .5i
  460. typedef struct {
  461.     short x, y;
  462. } XPoint;
  463. .De
  464. .\" End marker code here
  465. .LP
  466. .IN "XRectangle" "" "@DEF@"
  467. .\" Start marker code here
  468. .Ds 0
  469. .TA .5i
  470. .ta .5i
  471. typedef struct {
  472.     short x, y;
  473.     unsigned short width, height;
  474. } XRectangle;
  475. .De
  476. .\" End marker code here
  477. .LP
  478. .IN "XArc" "" "@DEF@"
  479. .\" Start marker code here
  480. .Ds 0
  481. .TA .5i 3i
  482. .ta .5i 3i
  483. typedef struct {
  484.     short x, y;
  485.     unsigned short width, height;
  486.     short angle1, angle2;             /* Degrees * 64 */
  487. } XArc;
  488. .De
  489. .\" End marker code here
  490. .LP
  491. All x and y members are signed integers.
  492. The width and height members are 16-bit unsigned integers.
  493. You should be careful not to generate coordinates and sizes
  494. out of the 16-bit ranges, because the protocol only has 16-bit fields
  495. for these values.
  496. .NH 3
  497. Drawing Single and Multiple Points
  498. .XS
  499. \*(SN Drawing Single and Multiple Points 
  500. .XE
  501. .LP
  502. .IN "Points" "drawing"
  503. .IN "Drawing" "points"
  504. .IN "XDrawPoints"
  505. .IN "XDrawPoint"
  506. .LP
  507. To draw a single point in a given drawable, use
  508. .PN XDrawPoint .
  509. .IN "XDrawPoint" "" "@DEF@"
  510. .\" Start marker code here
  511. .FD 0
  512. .\" $Header: XPoint.f,v 1.1 88/02/26 10:01:54 mento Exp $
  513. XDrawPoint\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^)
  514. .br
  515.       Display *\fIdisplay\fP\^;
  516. .br
  517.       Drawable \fId\fP\^;
  518. .br
  519.       GC \fIgc\fP\^;
  520. .br
  521.       int \fIx\fP\^, \fIy\fP\^;
  522. .FN
  523. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  524. .IP \fIdisplay\fP 1i
  525. Specifies the connection to the X server.
  526. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  527. .IP \fId\fP 1i
  528. Specifies the drawable. 
  529. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  530. .IP \fIgc\fP 1i
  531. Specifies the GC.
  532. .\" $Header: xy_point.a,v 1.1 88/02/26 10:32:57 mento Exp $
  533. .IP \fIx\fP 1i
  534. .br
  535. .ns
  536. .IP \fIy\fP 1i
  537. Specify the x and y coordinates where you want the point drawn.
  538. .\" End marker code here
  539. .LP
  540. .sp
  541. To draw multiple points in a given drawable, use
  542. .PN XDrawPoints .
  543. .IN "XDrawPoints" "" "@DEF@"
  544. .\" Start marker code here
  545. .FD 0
  546. .\" $Header: XPoints.f,v 1.1 88/02/26 10:01:55 mento Exp $
  547. XDrawPoints\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
  548. .br
  549.       Display *\fIdisplay\fP\^;
  550. .br
  551.       Drawable \fId\fP\^;
  552. .br
  553.       GC \fIgc\fP\^;
  554. .br
  555.       XPoint *\fIpoints\fP\^;
  556. .br
  557.       int \fInpoints\fP\^;
  558. .br
  559.       int \fImode\fP\^; 
  560. .FN
  561. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  562. .IP \fIdisplay\fP 1i
  563. Specifies the connection to the X server.
  564. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  565. .IP \fId\fP 1i
  566. Specifies the drawable. 
  567. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  568. .IP \fIgc\fP 1i
  569. Specifies the GC.
  570. .\" $Header: points.a,v 1.1 88/02/26 10:30:33 mento Exp $
  571. .IP \fIpoints\fP 1i
  572. Specifies an array of points.
  573. .\" $Header: npoints.a,v 1.1 88/02/26 10:29:46 mento Exp $
  574. .IP \fInpoints\fP 1i
  575. Specifies the number of points in the array.
  576. .\" $Header: mode.a,v 1.4 88/05/18 07:53:37 mento Exp $
  577. .IP \fImode\fP 1i
  578. Specifies the coordinate mode. 
  579. You can pass
  580. .PN CoordModeOrigin
  581. or
  582. .PN CoordModePrevious .
  583. .\" End marker code here
  584. .LP
  585. .\" $Header: XPoint.d,v 1.4 88/06/11 07:52:15 mento Exp $
  586. The
  587. .PN XDrawPoint
  588. function uses the foreground pixel and function components of the
  589. GC to draw a single point into the specified drawable; 
  590. .PN XDrawPoints
  591. draws multiple points this way.
  592. .PN CoordModeOrigin
  593. treats all coordinates as relative to the origin,
  594. and
  595. .PN CoordModePrevious
  596. treats all coordinates after the first as relative to the previous point.
  597. .PN XDrawPoints
  598. draws the points in the order listed in the array.
  599. .LP
  600. Both functions use these GC components: function, plane-mask,
  601. foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
  602. .LP
  603. .PN XDrawPoint
  604. can generate
  605. .PN BadDrawable ,
  606. .PN BadGC ,
  607. and 
  608. .PN BadMatch 
  609. errors.
  610. .PN XDrawPoints
  611. can generate
  612. .PN BadDrawable ,
  613. .PN BadGC ,
  614. .PN BadMatch ,
  615. and
  616. .PN BadValue 
  617. errors.
  618. .NH 3
  619. Drawing Single and Multiple Lines
  620. .XS
  621. \*(SN Drawing Single and Multiple Lines
  622. .XE
  623. .LP
  624. .IN "Lines" "drawing"
  625. .IN "Drawing" "lines"
  626. .IN "XDrawLine"
  627. .IN "XDrawLines"
  628. .IN "Polygons" "drawing"
  629. .IN "Drawing" "polygons"
  630. .IN "XDrawSegments"
  631. .LP
  632. To draw a single line between two points in a given drawable, use
  633. .PN XDrawLine .
  634. .IN "XDrawLine" "" "@DEF@"
  635. .\" Start marker code here
  636. .FD 0
  637. .\" $Header: XLine.f,v 1.1 88/02/26 09:58:43 mento Exp $
  638. XDrawLine\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^)
  639. .br
  640.       Display *\fIdisplay\fP\^;
  641. .br
  642.       Drawable \fId\fP\^;
  643. .br
  644.       GC \fIgc\fP\^;
  645. .br
  646.       int \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^;
  647. .FN
  648. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  649. .IP \fIdisplay\fP 1i
  650. Specifies the connection to the X server.
  651. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  652. .IP \fId\fP 1i
  653. Specifies the drawable. 
  654. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  655. .IP \fIgc\fP 1i
  656. Specifies the GC.
  657. .\" $Header: x1y1x2y2.a,v 1.3 88/05/13 08:17:23 mento Exp $
  658. .IP \fIx1\fP 1i
  659. .br
  660. .ns
  661. .IP \fIy1\fP 1i
  662. .br
  663. .ns
  664. .IP \fIx2\fP 1i
  665. .br
  666. .ns
  667. .IP \fIy2\fP 1i
  668. Specify the points (x1, y1) and (x2, y2) to be connected.
  669. .\" End marker code here
  670. .LP
  671. .sp
  672. To draw multiple lines in a given drawable, use
  673. .PN XDrawLines .
  674. .IN "XDrawLines" "" "@DEF@"
  675. .\" Start marker code here
  676. .FD 0
  677. .\" $Header: XLines.f,v 1.1 88/02/26 10:01:21 mento Exp $
  678. XDrawLines\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
  679. .br
  680.       Display *\fIdisplay\fP\^;
  681. .br
  682.       Drawable \fId\fP\^;
  683. .br
  684.       GC \fIgc\fP\^;
  685. .br
  686.       XPoint *\fIpoints\fP\^;
  687. .br
  688.       int \fInpoints\fP\^;
  689. .br
  690.       int \fImode\fP\^; 
  691. .FN
  692. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  693. .IP \fIdisplay\fP 1i
  694. Specifies the connection to the X server.
  695. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  696. .IP \fId\fP 1i
  697. Specifies the drawable. 
  698. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  699. .IP \fIgc\fP 1i
  700. Specifies the GC.
  701. .\" $Header: points.a,v 1.1 88/02/26 10:30:33 mento Exp $
  702. .IP \fIpoints\fP 1i
  703. Specifies an array of points.
  704. .\" $Header: npoints.a,v 1.1 88/02/26 10:29:46 mento Exp $
  705. .IP \fInpoints\fP 1i
  706. Specifies the number of points in the array.
  707. .\" $Header: mode.a,v 1.4 88/05/18 07:53:37 mento Exp $
  708. .IP \fImode\fP 1i
  709. Specifies the coordinate mode. 
  710. You can pass
  711. .PN CoordModeOrigin
  712. or
  713. .PN CoordModePrevious .
  714. .\" End marker code here
  715. .LP
  716. .sp
  717. To draw multiple, unconnected lines in a given drawable,
  718. use
  719. .PN XDrawSegments .
  720. .IN "XDrawSegments" "" "@DEF@"
  721. .\" Start marker code here
  722. .FD 0
  723. .\" $Header: XSegments.f,v 1.1 88/02/26 10:02:52 mento Exp $
  724. XDrawSegments\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIsegments\fP\^, \fInsegments\fP\^)
  725. .br
  726.       Display *\fIdisplay\fP\^;
  727. .br
  728.       Drawable \fId\fP\^;
  729. .br
  730.       GC \fIgc\fP\^;
  731. .br
  732.       XSegment *\fIsegments\fP\^;
  733. .br
  734.       int \fInsegments\fP\^;
  735. .FN
  736. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  737. .IP \fIdisplay\fP 1i
  738. Specifies the connection to the X server.
  739. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  740. .IP \fId\fP 1i
  741. Specifies the drawable. 
  742. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  743. .IP \fIgc\fP 1i
  744. Specifies the GC.
  745. .\" $Header: segments.a,v 1.1 88/02/26 10:31:10 mento Exp $
  746. .IP \fIsegments\fP 1i
  747. Specifies an array of segments.
  748. .\" $Header: nsegments.a,v 1.1 88/02/26 10:29:48 mento Exp $
  749. .IP \fInsegments\fP 1i
  750. Specifies the number of segments in the array.
  751. .\" End marker code here
  752. .LP
  753. The
  754. .PN XDrawLine
  755. function uses the components of the specified GC to
  756. draw a line between the specified set of points (x1, y1) and (x2, y2).
  757. It does not perform joining at coincident endpoints.
  758. For any given line, 
  759. .PN XDrawLine 
  760. does not draw a pixel more than once.
  761. If lines intersect, the intersecting pixels are drawn multiple times.  
  762. .LP
  763. The
  764. .PN XDrawLines
  765. function uses the components of the specified GC to draw 
  766. npoints\-1 lines between each pair of points (point[i], point[i+1]) 
  767. in the array of
  768. .PN XPoint
  769. structures.
  770. It draws the lines in the order listed in the array.
  771. The lines join correctly at all intermediate points, and if the first and last
  772. points coincide, the first and last lines also join correctly.
  773. For any given line, 
  774. .PN XDrawLines
  775. does not draw a pixel more than once.
  776. If thin (zero line-width) lines intersect, 
  777. the intersecting pixels are drawn multiple times.
  778. If wide lines intersect, the intersecting pixels are drawn only once, as though
  779. the entire 
  780. .PN PolyLine 
  781. protocol request were a single, filled shape.
  782. .PN CoordModeOrigin
  783. treats all coordinates as relative to the origin,
  784. and
  785. .PN CoordModePrevious
  786. treats all coordinates after the first as relative to the previous point.
  787. .LP
  788. The
  789. .PN XDrawSegments 
  790. function draws multiple, unconnected lines. 
  791. For each segment, 
  792. .PN XDrawSegments 
  793. draws a
  794. line between (x1, y1) and (x2, y2).
  795. It draws the lines in the order listed in the array of
  796. .PN XSegment
  797. structures and does not perform joining at coincident endpoints.
  798. For any given line, 
  799. .PN XDrawSegments
  800. does not draw a pixel more than once.  
  801. If lines intersect, the intersecting pixels are drawn multiple times.  
  802. .LP
  803. All three functions use these GC components:
  804. function, plane-mask, line-width,
  805. line-style, cap-style, fill-style, subwindow-mode,
  806. clip-x-origin, clip-y-origin, and clip-mask.
  807. The
  808. .PN XDrawLines
  809. function also uses the join-style GC component.
  810. All three functions also use these GC mode-dependent components:
  811. foreground, background, tile, stipple, tile-stipple-x-origin, 
  812. tile-stipple-y-origin, dash-offset, and dash-list.
  813. .LP
  814. .PN XDrawLine ,
  815. .PN XDrawLines ,
  816. and
  817. .PN XDrawSegments
  818. can generate
  819. .PN BadDrawable ,
  820. .PN BadGC ,
  821. and
  822. .PN BadMatch 
  823. errors.
  824. .PN XDrawLines
  825. also can generate
  826. .PN BadValue 
  827. errors.
  828. .NH 3
  829. Drawing Single and Multiple Rectangles 
  830. .XS
  831. \*(SN Drawing Single and Multiple Rectangles 
  832. .XE
  833. .LP
  834. .IN "Rectangles" "drawing"
  835. .IN "Drawing" "rectangles"
  836. .IN "XDrawRectangle"
  837. .IN "XDrawRectangles"
  838. .LP
  839. To draw the outline of a single rectangle in a given drawable, use
  840. .PN XDrawRectangle .
  841. .IN "XDrawRectangle" "" "@DEF@"
  842. .\" Start marker code here
  843. .FD 0
  844. .\" $Header: XRectangle.f,v 1.1 88/02/26 10:02:37 mento Exp $
  845. XDrawRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
  846. .br
  847.       Display *\fIdisplay\fP\^;
  848. .br
  849.       Drawable \fId\fP\^;
  850. .br
  851.       GC \fIgc\fP\^;
  852. .br
  853.       int \fIx\fP\^, \fIy\fP\^;
  854. .br
  855.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  856. .FN
  857. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  858. .IP \fIdisplay\fP 1i
  859. Specifies the connection to the X server.
  860. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  861. .IP \fId\fP 1i
  862. Specifies the drawable. 
  863. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  864. .IP \fIgc\fP 1i
  865. Specifies the GC.
  866. .ds Xy , which specify the upper-left corner of the rectangle
  867. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  868. .IP \fIx\fP 1i
  869. .br
  870. .ns
  871. .IP \fIy\fP 1i
  872. Specify the x and y coordinates\*(Xy.
  873. .ds Wh , which specify the dimensions of the rectangle
  874. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  875. .IP \fIwidth\fP 1i
  876. .br
  877. .ns
  878. .IP \fIheight\fP 1i
  879. Specify the width and height\*(Wh.
  880. .\" End marker code here
  881. .LP
  882. .sp
  883. To draw the outline of multiple rectangles
  884. in a given drawable, use
  885. .PN XDrawRectangles .
  886. .IN "XDrawRectangles" "" "@DEF@"
  887. .\" Start marker code here
  888. .FD 0
  889. .\" $Header: XRectangles.f,v 1.1 88/02/26 10:02:38 mento Exp $
  890. XDrawRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
  891. .br
  892.       Display *\fIdisplay\fP\^;
  893. .br
  894.       Drawable \fId\fP\^;
  895. .br
  896.       GC \fIgc\fP\^;
  897. .br
  898.       XRectangle \fIrectangles\fP\^[\^]\^;
  899. .br
  900.       int \fInrectangles\fP\^;
  901. .FN
  902. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  903. .IP \fIdisplay\fP 1i
  904. Specifies the connection to the X server.
  905. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  906. .IP \fId\fP 1i
  907. Specifies the drawable. 
  908. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  909. .IP \fIgc\fP 1i
  910. Specifies the GC.
  911. .\" $Header: rectangles.a,v 1.1 88/02/26 10:30:50 mento Exp $
  912. .IP \fIrectangles\fP 1i
  913. Specifies an array of rectangles.
  914. .\" $Header: nrectangles.a,v 1.1 88/02/26 10:29:47 mento Exp $
  915. .IP \fInrectangles\fP 1i
  916. Specifies the number of rectangles in the array.
  917. .\" End marker code here
  918. .LP
  919. .\" $Header: XRectangle.d,v 1.4 88/06/11 07:52:48 mento Exp $
  920. The
  921. .PN XDrawRectangle
  922. and
  923. .PN XDrawRectangles
  924. functions draw the outlines of the specified rectangle or rectangles as
  925. if a five-point 
  926. .PN PolyLine 
  927. protocol request were specified for each rectangle:
  928. .IP
  929. [x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
  930. .LP 
  931. For the specified rectangle or rectangles, 
  932. these functions do not draw a pixel more than once.
  933. .PN XDrawRectangles
  934. draws the rectangles in the order listed in the array.
  935. If rectangles intersect,
  936. the intersecting pixels are drawn multiple times.
  937. .LP
  938. Both functions use these GC components: 
  939. function, plane-mask, line-width,
  940. line-style, cap-style, join-style, fill-style, 
  941. subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
  942. They also use these GC mode-dependent components: 
  943. foreground, background, tile, stipple, tile-stipple-x-origin, 
  944. tile-stipple-y-origin, dash-offset, and dash-list.
  945. .LP
  946. .PN XDrawRectangle
  947. and
  948. .PN XDrawRectangles
  949. can generate
  950. .PN BadDrawable ,
  951. .PN BadGC ,
  952. and
  953. .PN BadMatch 
  954. errors.
  955. .NH 3
  956. Drawing Single and Multiple Arcs
  957. .XS
  958. \*(SN Drawing Single and Multiple Arcs 
  959. .XE
  960. .LP
  961. .IN "Drawing" "arcs"
  962. .IN "XDrawArc"
  963. .IN "Arcs" "drawing"
  964. .IN "XDrawArcs"
  965. .LP
  966. .sp
  967. To draw a single arc in a given drawable, use
  968. .PN XDrawArc .
  969. .IN "XDrawArc" "" "@DEF@"
  970. .\" Start marker code here
  971. .FD 0
  972. .\" $Header: XArc.f,v 1.1 88/02/26 09:58:12 mento Exp $
  973. XDrawArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
  974. .br
  975.       Display *\fIdisplay\fP\^;
  976. .br
  977.       Drawable \fId\fP\^;
  978. .br
  979.       GC \fIgc\fP\^;
  980. .br
  981.       int \fIx\fP\^, \fIy\fP\^;
  982. .br
  983.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  984. .br
  985.       int \fIangle1\fP\^, \fIangle2\fP\^;
  986. .FN
  987. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  988. .IP \fIdisplay\fP 1i
  989. Specifies the connection to the X server.
  990. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  991. .IP \fId\fP 1i
  992. Specifies the drawable. 
  993. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  994. .IP \fIgc\fP 1i
  995. Specifies the GC.
  996. .ds Xy , which are relative to the origin of the drawable \
  997. and specify the upper-left corner of the bounding rectangle
  998. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  999. .IP \fIx\fP 1i
  1000. .br
  1001. .ns
  1002. .IP \fIy\fP 1i
  1003. Specify the x and y coordinates\*(Xy.
  1004. .ds Wh , which are the major and minor axes of the arc
  1005. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  1006. .IP \fIwidth\fP 1i
  1007. .br
  1008. .ns
  1009. .IP \fIheight\fP 1i
  1010. Specify the width and height\*(Wh.
  1011. .\" $Header: angle1.a,v 1.2 88/05/13 09:05:46 mento Exp $
  1012. .IP \fIangle1\fP 1i
  1013. Specifies the start of the arc relative to the three-o'clock position
  1014. from the center, in units of degrees * 64.
  1015. .\" $Header: angle2.a,v 1.1 88/02/26 10:04:51 mento Exp $
  1016. .IP \fIangle2\fP 1i
  1017. Specifies the path and extent of the arc relative to the start of the
  1018. arc, in units of degrees * 64.
  1019. .\" End marker code here
  1020. .LP
  1021. .sp
  1022. To draw multiple arcs in a given drawable, use
  1023. .PN XDrawArcs .
  1024. .IN "XDrawArcs" "" "@DEF@"
  1025. .\" Start marker code here
  1026. .FD 0
  1027. .\" $Header: XArcs.f,v 1.1 88/02/26 09:58:12 mento Exp $
  1028. XDrawArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
  1029. .br
  1030.       Display *\fIdisplay\fP\^;
  1031. .br
  1032.       Drawable \fId\fP\^;
  1033. .br
  1034.       GC \fIgc\fP\^;
  1035. .br
  1036.       XArc *\fIarcs\fP\^;
  1037. .br
  1038.       int \fInarcs\fP\^;
  1039. .FN
  1040. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1041. .IP \fIdisplay\fP 1i
  1042. Specifies the connection to the X server.
  1043. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1044. .IP \fId\fP 1i
  1045. Specifies the drawable. 
  1046. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1047. .IP \fIgc\fP 1i
  1048. Specifies the GC.
  1049. .\" $Header: arcs.a,v 1.1 88/02/26 10:04:53 mento Exp $
  1050. .IP \fIarcs\fP 1i
  1051. Specifies an array of arcs.
  1052. .\" $Header: narcs.a,v 1.1 88/02/26 10:29:11 mento Exp $
  1053. .IP \fInarcs\fP 1i
  1054. Specifies the number of arcs in the array.
  1055. .\" End marker code here
  1056. .LP
  1057. .\" $Header: XArc.d,v 1.4 88/08/18 09:29:15 mento Exp $
  1058. .EQ
  1059. delim %%
  1060. .EN
  1061. .PN XDrawArc
  1062. draws a single circular or elliptical arc, and 
  1063. .PN XDrawArcs
  1064. draws multiple circular or elliptical arcs.
  1065. Each arc is specified by a rectangle and two angles.  
  1066. The center of the circle or ellipse is the center of the
  1067. rectangle, and the major and minor axes are specified by the width and height.
  1068. Positive angles indicate counterclockwise motion, 
  1069. and negative angles indicate clockwise motion.  
  1070. If the magnitude of angle2 is greater than 360 degrees, 
  1071. .PN XDrawArc
  1072. or 
  1073. .PN XDrawArcs
  1074. truncates it to 360 degrees.
  1075. .LP
  1076. For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, 
  1077. the origin of the major and minor axes is at 
  1078. % [ x +^ {width over 2} , ~y +^ {height over 2}  ]%, 
  1079. and the infinitely thin path describing the entire circle or ellipse 
  1080. intersects the horizontal axis at % [ x, ~y +^ {height over 2}  ]% and 
  1081. % [ x +^ width , ~y +^ { height over 2 }] %
  1082. and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and 
  1083. % [ x +^ { width over 2 }, ~y +^ height ]%.
  1084. These coordinates can be fractional
  1085. and so are not truncated to discrete coordinates.
  1086. The path should be defined by the ideal mathematical path.  
  1087. For a wide line with line-width lw, 
  1088. the bounding outlines for filling are given        
  1089. by the two infinitely thin paths consisting of all points whose perpendicular
  1090. distance from the path of the circle/ellipse is equal to lw/2
  1091. (which may be a fractional value).
  1092. The cap-style and join-style are applied the same as for a line
  1093. corresponding to the tangent of the circle/ellipse at the endpoint.
  1094. .LP
  1095. For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2  ]%,
  1096. the angles must be specified
  1097. in the effectively skewed coordinate system of the ellipse (for a
  1098. circle, the angles and coordinate systems are identical).  The
  1099. relationship between these angles and angles expressed in the normal
  1100. coordinate system of the screen (as measured with a protractor) is as
  1101. follows:
  1102. .LP
  1103. .Ds
  1104. % roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
  1105.  * width over height right ) +^ adjust%
  1106. .De
  1107. .LP
  1108. The skewed-angle and normal-angle are expressed in radians (rather
  1109. than in degrees scaled by 64) in the range % [ 0 , ~2 pi  ]% and where atan
  1110. returns a value in the range % [ - pi over 2 , ~pi over 2  ] %
  1111. and adjust is:
  1112. .LP
  1113. .Ds
  1114. .TA 1i 2i
  1115. .ta 1i 2i
  1116. %0%    for normal-angle in the range % [ 0 , ~pi over 2  ]%
  1117. %pi%    for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%
  1118. %2 pi%    for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%
  1119. .De
  1120. .LP
  1121. For any given arc, 
  1122. .PN XDrawArc
  1123. and
  1124. .PN XDrawArcs
  1125. do not draw a pixel more than once.  
  1126. If two arcs join correctly and if the line-width is greater than zero 
  1127. and the arcs intersect, 
  1128. .PN XDrawArc
  1129. and
  1130. .PN XDrawArcs
  1131. do not draw a pixel more than once.
  1132. Otherwise, 
  1133. the intersecting pixels of intersecting arcs are drawn multiple times.
  1134. Specifying an arc with one endpoint and a clockwise extent draws the same pixels
  1135. as specifying the other endpoint and an equivalent counterclockwise extent,
  1136. except as it affects joins.
  1137. .LP
  1138. If the last point in one arc coincides with the first point in the following 
  1139. arc, the two arcs will join correctly.  
  1140. If the first point in the first arc coincides with the last point in the last 
  1141. arc, the two arcs will join correctly.
  1142. By specifying one axis to be zero, a horizontal or vertical line can be
  1143. drawn.
  1144. Angles are computed based solely on the coordinate system and ignore the
  1145. aspect ratio.
  1146. .LP
  1147. Both functions use these GC components: 
  1148. function, plane-mask, line-width, line-style, cap-style, join-style, 
  1149. fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
  1150. They also use these GC mode-dependent components: 
  1151. foreground, background, tile, stipple, tile-stipple-x-origin, 
  1152. tile-stipple-y-origin, dash-offset, and dash-list.
  1153. .LP
  1154. .PN XDrawArc
  1155. and
  1156. .PN XDrawArcs
  1157. can generate
  1158. .PN BadDrawable ,
  1159. .PN BadGC ,
  1160. and
  1161. .PN BadMatch 
  1162. errors.
  1163. .NH 2
  1164. Filling Areas
  1165. .XS
  1166. \*(SN Filling Areas 
  1167. .XE
  1168. .LP
  1169. Xlib provides functions that you can use to fill:
  1170. .IP \(bu 5
  1171. A single rectangle or multiple rectangles
  1172. .IP \(bu 5
  1173. A single polygon
  1174. .IP \(bu 5
  1175. A single arc or multiple arcs
  1176. .NH 3
  1177. Filling Single and Multiple Rectangles
  1178. .XS
  1179. \*(SN Filling Single and Multiple Rectangles 
  1180. .XE
  1181. .LP
  1182. .IN "Filling" "rectangles"
  1183. .IN "XFillRectangle"
  1184. .IN "Rectangle" "filling"
  1185. .IN "XFillRectangles"
  1186. .LP
  1187. .sp
  1188. To fill a single rectangular area in a given drawable, use
  1189. .PN XFillRectangle .
  1190. .IN "XFillRectangle" "" "@DEF@"
  1191. .\" Start marker code here
  1192. .FD 0 
  1193. .\" $Header: XFillRect.f,v 1.1 88/02/26 10:00:09 mento Exp $
  1194. XFillRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
  1195. .br
  1196.       Display *\fIdisplay\fP\^;
  1197. .br
  1198.       Drawable \fId\fP\^;
  1199. .br
  1200.       GC \fIgc\fP\^;
  1201. .br
  1202.       int \fIx\fP\^, \fIy\fP\^;
  1203. .br
  1204.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  1205. .FN
  1206. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1207. .IP \fIdisplay\fP 1i
  1208. Specifies the connection to the X server.
  1209. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1210. .IP \fId\fP 1i
  1211. Specifies the drawable. 
  1212. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1213. .IP \fIgc\fP 1i
  1214. Specifies the GC.
  1215. .ds Xy , which are relative to the origin of the drawable \
  1216. and specify the upper-left corner of the rectangle
  1217. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1218. .IP \fIx\fP 1i
  1219. .br
  1220. .ns
  1221. .IP \fIy\fP 1i
  1222. Specify the x and y coordinates\*(Xy.
  1223. .ds Wh , which are the dimensions of the rectangle to be filled
  1224. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  1225. .IP \fIwidth\fP 1i
  1226. .br
  1227. .ns
  1228. .IP \fIheight\fP 1i
  1229. Specify the width and height\*(Wh.
  1230. .\" End marker code here
  1231. .LP
  1232. .sp
  1233. To fill multiple rectangular areas in a given drawable, use
  1234. .PN XFillRectangles .
  1235. .IN "XFillRectangles" "" "@DEF@"
  1236. .\" Start marker code here
  1237. .FD 0 
  1238. .\" $Header: XFillRects.f,v 1.1 88/02/26 10:00:10 mento Exp $
  1239. XFillRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
  1240. .br
  1241.       Display *\fIdisplay\fP\^;
  1242. .br
  1243.       Drawable \fId\fP\^;
  1244. .br
  1245.       GC \fIgc\fP\^;
  1246. .br
  1247.       XRectangle *\fIrectangles\fP\^;
  1248. .br
  1249.       int \fInrectangles\fP\^;
  1250. .FN
  1251. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1252. .IP \fIdisplay\fP 1i
  1253. Specifies the connection to the X server.
  1254. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1255. .IP \fId\fP 1i
  1256. Specifies the drawable. 
  1257. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1258. .IP \fIgc\fP 1i
  1259. Specifies the GC.
  1260. .\" $Header: rectangles.a,v 1.1 88/02/26 10:30:50 mento Exp $
  1261. .IP \fIrectangles\fP 1i
  1262. Specifies an array of rectangles.
  1263. .\" $Header: nrectangles.a,v 1.1 88/02/26 10:29:47 mento Exp $
  1264. .IP \fInrectangles\fP 1i
  1265. Specifies the number of rectangles in the array.
  1266. .\" End marker code here
  1267. .LP
  1268. .\" $Header: XFillRect.d,v 1.5 88/06/11 07:50:18 mento Exp $
  1269. The
  1270. .PN XFillRectangle
  1271. and
  1272. .PN XFillRectangles
  1273. functions fill the specified rectangle or rectangles
  1274. as if a four-point 
  1275. .PN FillPolygon
  1276. protocol request were specified for each rectangle:
  1277. .LP
  1278. .Ds
  1279. [x,y] [x+width,y] [x+width,y+height] [x,y+height]
  1280. .De
  1281. .LP
  1282. Each function uses the x and y coordinates,
  1283. width and height dimensions, and GC you specify.
  1284. .LP
  1285. .PN XFillRectangles
  1286. fills the rectangles in the order listed in the array.  
  1287. For any given rectangle,
  1288. .PN XFillRectangle
  1289. and
  1290. .PN XFillRectangles
  1291. do not draw a pixel more than once.  
  1292. If rectangles intersect, the intersecting pixels are
  1293. drawn multiple times.
  1294. .LP
  1295. Both functions use these GC components: 
  1296. function, plane-mask, fill-style, subwindow-mode, 
  1297. clip-x-origin, clip-y-origin, and clip-mask.
  1298. They also use these GC mode-dependent components: 
  1299. foreground, background, tile, stipple, tile-stipple-x-origin, 
  1300. and tile-stipple-y-origin.
  1301. .LP
  1302. .PN XFillRectangle
  1303. and
  1304. .PN XFillRectangles
  1305. can generate
  1306. .PN BadDrawable ,
  1307. .PN BadGC ,
  1308. and
  1309. .PN BadMatch 
  1310. errors.
  1311. .NH 3
  1312. Filling a Single Polygon
  1313. .XS
  1314. \*(SN Filling a Single Polygon 
  1315. .XE
  1316. .LP
  1317. .sp
  1318. To fill a polygon area in a given drawable, use
  1319. .PN XFillPolygon .
  1320. .IN "Polygons" "filling"
  1321. .IN "Filling" "polygon"
  1322. .IN "XFillPolygon" "" "@DEF@"
  1323. .\" Start marker code here
  1324. .FD 0 
  1325. .\" $Header: XFillPoly.f,v 1.1 88/02/26 10:00:08 mento Exp $
  1326. XFillPolygon\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fIshape\fP\^, \fImode\fP\^)
  1327. .br
  1328.       Display *\fIdisplay\fP\^;
  1329. .br
  1330.       Drawable \fId\fP\^;
  1331. .br
  1332.       GC \fIgc\fP\^;
  1333. .br
  1334.       XPoint *\fIpoints\fP\^;
  1335. .br
  1336.       int \fInpoints\fP\^;
  1337. .br
  1338.       int \fIshape\fP\^; 
  1339. .br
  1340.       int \fImode\fP\^; 
  1341. .FN
  1342. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1343. .IP \fIdisplay\fP 1i
  1344. Specifies the connection to the X server.
  1345. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1346. .IP \fId\fP 1i
  1347. Specifies the drawable. 
  1348. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1349. .IP \fIgc\fP 1i
  1350. Specifies the GC.
  1351. .\" $Header: points.a,v 1.1 88/02/26 10:30:33 mento Exp $
  1352. .IP \fIpoints\fP 1i
  1353. Specifies an array of points.
  1354. .\" $Header: npoints.a,v 1.1 88/02/26 10:29:46 mento Exp $
  1355. .IP \fInpoints\fP 1i
  1356. Specifies the number of points in the array.
  1357. .\" $Header: shape.a,v 1.4 88/04/23 09:30:27 mento Exp $
  1358. .IP \fIshape\fP 1i
  1359. Specifies a shape that helps the server to improve performance.
  1360. You can pass 
  1361. .PN Complex , 
  1362. .PN Convex , 
  1363. or 
  1364. .PN Nonconvex .
  1365. .\" $Header: mode.a,v 1.4 88/05/18 07:53:37 mento Exp $
  1366. .IP \fImode\fP 1i
  1367. Specifies the coordinate mode. 
  1368. You can pass
  1369. .PN CoordModeOrigin
  1370. or
  1371. .PN CoordModePrevious .
  1372. .\" End marker code here
  1373. .LP
  1374. .\" $Header: XFillPoly.d,v 1.2 88/06/11 07:50:18 mento Exp $
  1375. .PN XFillPolygon 
  1376. fills the region closed by the specified path.
  1377. The path is closed
  1378. automatically if the last point in the list does not coincide with the
  1379. first point.
  1380. .PN XFillPolygon
  1381. does not draw a pixel of the region more than once.
  1382. .PN CoordModeOrigin
  1383. treats all coordinates as relative to the origin,
  1384. and
  1385. .PN CoordModePrevious
  1386. treats all coordinates after the first as relative to the previous point.
  1387. .LP
  1388. Depending on the specified shape, the following occurs: 
  1389. .IP \(bu 5
  1390. If shape is
  1391. .PN Complex , 
  1392. the path may self-intersect. 
  1393. Note that contiguous coincident points in the path are not treated 
  1394. as self-intersection.
  1395. .IP \(bu 5
  1396. If shape is
  1397. .PN Convex , 
  1398. for every pair of points inside the polygon,
  1399. the line segment connecting them does not intersect the path.
  1400. If known by the client,
  1401. specifying 
  1402. .PN Convex 
  1403. can improve performance.  
  1404. If you specify
  1405. .PN Convex 
  1406. for a path that is not convex, 
  1407. the graphics results are undefined.
  1408. .IP \(bu 5
  1409. If shape is
  1410. .PN Nonconvex , 
  1411. the path does not self-intersect, but the shape is not
  1412. wholly convex. 
  1413. If known by the client, 
  1414. specifying 
  1415. .PN Nonconvex 
  1416. instead of
  1417. .PN Complex 
  1418. may improve performance.  
  1419. If you specify
  1420. .PN Nonconvex 
  1421. for a self-intersecting path, the graphics results are undefined.
  1422. .LP
  1423. The fill-rule of the GC controls the filling behavior of 
  1424. self-intersecting polygons.
  1425. .LP
  1426. This function uses these GC components: 
  1427. function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, 
  1428. clip-y-origin, and clip-mask.
  1429. It also uses these GC mode-dependent components: 
  1430. foreground, background, tile, stipple, tile-stipple-x-origin, 
  1431. and tile-stipple-y-origin.
  1432. .LP
  1433. .PN XFillPolygon
  1434. can generate
  1435. .PN BadDrawable ,
  1436. .PN BadGC ,
  1437. .PN BadMatch ,
  1438. and
  1439. .PN BadValue 
  1440. errors.
  1441. .NH 3
  1442. Filling Single and Multiple Arcs
  1443. .XS
  1444. \*(SN Filling Single and Multiple Arcs 
  1445. .XE
  1446. .LP
  1447. .IN "XFillArc"
  1448. .IN "Arcs" "filling"
  1449. .IN "Filling" "arcs"
  1450. To fill a single arc in a given drawable, use
  1451. .PN XFillArc .
  1452. .IN "XFillArc" "" "@DEF@"
  1453. .\" Start marker code here
  1454. .FD 0
  1455. .\" $Header: XFillArc.f,v 1.1 88/02/26 10:00:01 mento Exp $
  1456. XFillArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^,  \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
  1457. .br
  1458.       Display *\fIdisplay\fP\^;
  1459. .br
  1460.       Drawable \fId\fP\^;
  1461. .br
  1462.       GC \fIgc\fP\^;
  1463. .br
  1464.       int \fIx\fP\^, \fIy\fP\^;
  1465. .br
  1466.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  1467. .br
  1468.       int \fIangle1\fP\^, \fIangle2\fP\^;
  1469. .FN
  1470. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1471. .IP \fIdisplay\fP 1i
  1472. Specifies the connection to the X server.
  1473. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1474. .IP \fId\fP 1i
  1475. Specifies the drawable. 
  1476. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1477. .IP \fIgc\fP 1i
  1478. Specifies the GC.
  1479. .ds Xy , which are relative to the origin of the drawable \
  1480. and specify the upper-left corner of the bounding rectangle
  1481. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1482. .IP \fIx\fP 1i
  1483. .br
  1484. .ns
  1485. .IP \fIy\fP 1i
  1486. Specify the x and y coordinates\*(Xy.
  1487. .ds Wh , which are the major and minor axes of the arc
  1488. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  1489. .IP \fIwidth\fP 1i
  1490. .br
  1491. .ns
  1492. .IP \fIheight\fP 1i
  1493. Specify the width and height\*(Wh.
  1494. .\" $Header: angle1.a,v 1.2 88/05/13 09:05:46 mento Exp $
  1495. .IP \fIangle1\fP 1i
  1496. Specifies the start of the arc relative to the three-o'clock position
  1497. from the center, in units of degrees * 64.
  1498. .\" $Header: angle2.a,v 1.1 88/02/26 10:04:51 mento Exp $
  1499. .IP \fIangle2\fP 1i
  1500. Specifies the path and extent of the arc relative to the start of the
  1501. arc, in units of degrees * 64.
  1502. .\" End marker code here
  1503. .LP
  1504. .sp
  1505. To fill multiple arcs in a given drawable, use
  1506. .PN XFillArcs .
  1507. .IN "XFillArcs" "" "@DEF@"
  1508. .\" Start marker code here
  1509. .FD 0
  1510. .\" $Header: XFillArcs.f,v 1.1 88/02/26 10:00:02 mento Exp $
  1511. XFillArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
  1512. .br
  1513.       Display *\fIdisplay\fP\^;
  1514. .br
  1515.       Drawable \fId\fP\^;
  1516. .br
  1517.       GC \fIgc\fP\^;
  1518. .br
  1519.       XArc *\fIarcs\fP\^;
  1520. .br
  1521.       int \fInarcs\fP\^;
  1522. .FN
  1523. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1524. .IP \fIdisplay\fP 1i
  1525. Specifies the connection to the X server.
  1526. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  1527. .IP \fId\fP 1i
  1528. Specifies the drawable. 
  1529. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1530. .IP \fIgc\fP 1i
  1531. Specifies the GC.
  1532. .\" $Header: arcs.a,v 1.1 88/02/26 10:04:53 mento Exp $
  1533. .IP \fIarcs\fP 1i
  1534. Specifies an array of arcs.
  1535. .\" $Header: narcs.a,v 1.1 88/02/26 10:29:11 mento Exp $
  1536. .IP \fInarcs\fP 1i
  1537. Specifies the number of arcs in the array.
  1538. .\" End marker code here
  1539. .LP
  1540. .\" $Header: XFillArc.d,v 1.2 88/06/11 07:50:17 mento Exp $
  1541. For each arc, 
  1542. .PN XFillArc
  1543. or
  1544. .PN XFillArcs
  1545. fills the region closed by the infinitely thin path
  1546. described by the specified arc and, depending on the 
  1547. arc-mode specified in the GC, one or two line segments. 
  1548. For 
  1549. .PN ArcChord , 
  1550. the single line segment joining the endpoints of the arc is used.  
  1551. For 
  1552. .PN ArcPieSlice ,
  1553. the two line segments joining the endpoints of the arc with the center
  1554. point are used.  
  1555. .PN XFillArcs
  1556. fills the arcs in the order listed in the array.  
  1557. For any given arc,  
  1558. .PN XFillArc
  1559. and
  1560. .PN XFillArcs
  1561. do not draw a pixel more than once.  
  1562. If regions intersect, 
  1563. the intersecting pixels are drawn multiple times.
  1564. .LP
  1565. Both functions use these GC components: 
  1566. function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, 
  1567. clip-y-origin, and clip-mask.
  1568. They also use these GC mode-dependent components: 
  1569. foreground, background, tile, stipple, tile-stipple-x-origin, 
  1570. and tile-stipple-y-origin.
  1571. .LP
  1572. .PN XFillArc
  1573. and
  1574. .PN XFillArcs
  1575. can generate
  1576. .PN BadDrawable ,
  1577. .PN BadGC ,
  1578. and
  1579. .PN BadMatch 
  1580. errors.
  1581. .NH 2
  1582. Font Metrics
  1583. .XS
  1584. \*(SN Font Metrics 
  1585. .XE
  1586. .LP
  1587. .IN "Font"
  1588. A font is a graphical description of a set of characters that are used to 
  1589. increase efficiency whenever a set of small, similar sized patterns are 
  1590. repeatedly used.
  1591. .LP
  1592. This section discusses how to:
  1593. .IP \(bu 5
  1594. Load and free fonts
  1595. .IP \(bu 5
  1596. Obtain and free font names
  1597. .IP \(bu 5
  1598. Compute character string sizes
  1599. .IP \(bu 5
  1600. Return logical extents
  1601. .IP \(bu 5
  1602. Query character string sizes
  1603. .LE
  1604. .LP
  1605. The X server loads fonts whenever a program requests a new font.
  1606. The server can cache fonts for quick lookup.
  1607. Fonts are global across all screens in a server.
  1608. Several levels are possible when dealing with fonts.
  1609. Most applications simply use 
  1610. .PN XLoadQueryFont
  1611. to load a font and query the font metrics.
  1612. .LP
  1613. Characters in fonts are regarded as masks.
  1614. Except for image text requests,
  1615. the only pixels modified are those in which bits are set to 1 in the character.
  1616. This means that it makes sense to draw text using stipples or tiles
  1617. (for example, many menus gray-out unusable entries).
  1618. .LP
  1619. .\" Start marker code here
  1620. The
  1621. .PN XFontStruct
  1622. structure contains all of the information for the font
  1623. and consists of the font-specific information as well as
  1624. a pointer to an array of
  1625. .PN XCharStruct
  1626. structures for the
  1627. characters contained in the font.
  1628. The
  1629. .PN XFontStruct ,
  1630. .PN XFontProp ,
  1631. and
  1632. .PN XCharStruct
  1633. structures contain:
  1634. .LP
  1635. .IN "XCharStruct" "" "@DEF@"
  1636. .Ds 0
  1637. .TA .5i 3i
  1638. .ta .5i 3i
  1639. typedef struct {
  1640.     short lbearing;    /* origin to left edge of raster */
  1641.     short rbearing;    /* origin to right edge of raster */
  1642.     short width;    /* advance to next char's origin */
  1643.     short ascent;    /* baseline to top edge of raster */
  1644.     short descent;    /* baseline to bottom edge of raster */
  1645.     unsigned short attributes;    /* per char flags (not predefined) */
  1646. } XCharStruct;
  1647. .De
  1648. .LP
  1649. .IN "XFontProp" "" "@DEF@"
  1650. .Ds 0
  1651. .TA .5i 1i 3i
  1652. .ta .5i 1i 3i
  1653. typedef struct {
  1654.     Atom    name;
  1655.     unsigned long card32;
  1656. } XFontProp;
  1657. .De
  1658. .LP
  1659. .IN "XChar2b" "" "@DEF@"
  1660. .Ds 0
  1661. .TA .5i 3i
  1662. .ta .5i 3i
  1663. typedef struct {    /* normal 16 bit characters are two bytes */
  1664.     unsigned char byte1;
  1665.     unsigned char byte2;
  1666. } XChar2b;
  1667. .De
  1668. .LP
  1669. .IN "XFontStruct" "" "@DEF@"
  1670. .Ds 0
  1671. .TA .5i 3i
  1672. .ta .5i 3i
  1673. typedef struct {
  1674.     XExtData *ext_data;    /* hook for extension to hang data */
  1675.     Font fid;    /* Font id for this font */
  1676.     unsigned direction;    /* hint about the direction font is painted */
  1677.     unsigned min_char_or_byte2;    /* first character */
  1678.     unsigned max_char_or_byte2;    /* last character */
  1679.     unsigned min_byte1;    /* first row that exists */
  1680.     unsigned max_byte1;    /* last row that exists */
  1681.     Bool all_chars_exist;    /* flag if all characters have nonzero size */
  1682.     unsigned default_char;    /* char to print for undefined character */
  1683.     int n_properties;    /* how many properties there are */
  1684.     XFontProp *properties;    /* pointer to array of additional properties */
  1685.     XCharStruct min_bounds;    /* minimum bounds over all existing char */
  1686.     XCharStruct max_bounds;    /* maximum bounds over all existing char */
  1687.     XCharStruct *per_char;    /* first_char to last_char information */
  1688.     int ascent;    /* logical extent above baseline for spacing */
  1689.     int descent;    /* logical decent below baseline for spacing */
  1690. } XFontStruct;
  1691. .De
  1692. .\" End marker code here
  1693. .LP
  1694. X supports single byte/character, two bytes/character matrix,
  1695. and 16-bit character text operations.
  1696. Note that any of these forms can be used with a font, but a
  1697. single byte/character text request can only specify a single byte
  1698. (that is, the first row of a 2-byte font).
  1699. You should view 2-byte fonts as a two-dimensional matrix of defined
  1700. characters: byte1 specifies the range of defined rows and
  1701. byte2 defines the range of defined columns of the font.
  1702. Single byte/character fonts have one row defined, and the byte2 range
  1703. specified in the structure defines a range of characters.
  1704. .LP
  1705. The bounding box of a character is defined by the 
  1706. .PN XCharStruct 
  1707. of that character.
  1708. When characters are absent from a font,
  1709. the default_char is used.
  1710. When fonts have all characters of the same size,
  1711. only the information in the
  1712. .PN XFontStruct
  1713. min and max bounds are used.
  1714. .LP
  1715. The members of the 
  1716. .PN XFontStruct 
  1717. have the following semantics:
  1718. .IP \(bu 5
  1719. The direction member can be either 
  1720. .PN FontLeftToRight 
  1721. or 
  1722. .PN FontRightToLeft . 
  1723. It is just a hint as to whether most 
  1724. .PN XCharStruct 
  1725. elements 
  1726. have a positive 
  1727. .Pn ( FontLeftToRight ) 
  1728. or a negative 
  1729. .Pn ( FontRightToLeft )
  1730. character width 
  1731. metric.
  1732. The core protocol defines no support for vertical text.
  1733. .IP \(bu 5
  1734. If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
  1735. specifies the linear character index corresponding to the first element
  1736. of the per_char array, and max_char_or_byte2 specifies the linear character
  1737. index of the last element.
  1738. .IP
  1739. If either min_byte1 or max_byte1 are nonzero, both
  1740. min_char_or_byte2 and max_char_or_byte2 are less than 256, 
  1741. and the 2-byte character index values corresponding to the
  1742. per_char array element N (counting from 0) are:
  1743. .IP
  1744. .nf
  1745.     byte1 = N/D + min_byte1
  1746. .br
  1747.     byte2 = N\\D + min_char_or_byte2
  1748. .IP
  1749. .fi
  1750. where:
  1751. .IP
  1752. .nf
  1753.         D = max_char_or_byte2 \- min_char_or_byte2 + 1
  1754.         / = integer division
  1755.         \\ = integer modulus
  1756. .fi
  1757. .IP \(bu 5
  1758. If the per_char pointer is NULL, 
  1759. all glyphs between the first and last character indexes
  1760. inclusive have the same information,
  1761. as given by both min_bounds and max_bounds.
  1762. .IP \(bu 5
  1763. If all_chars_exist is 
  1764. .PN True ,
  1765. all characters in the per_char array have nonzero bounding boxes.
  1766. .IP \(bu 5
  1767. The default_char member specifies the character that will be used when an
  1768. undefined or nonexistent character is printed.  
  1769. The default_char is a 16-bit character (not a 2-byte character).
  1770. For a font using 2-byte matrix format, 
  1771. the default_char has byte1 in the most-significant byte
  1772. and byte2 in the least-significant byte.
  1773. If the default_char itself specifies an undefined or nonexistent character, 
  1774. no printing is performed for an undefined or nonexistent character.
  1775. .IP \(bu 5
  1776. The min_bounds and max_bounds members contain the most extreme values of
  1777. each individual 
  1778. .PN XCharStruct 
  1779. component over all elements of this array
  1780. (and ignore nonexistent characters).
  1781. The bounding box of the font (the smallest
  1782. rectangle enclosing the shape obtained by superimposing all of the
  1783. characters at the same origin [x,y]) has its upper-left coordinate at:
  1784. .Ds
  1785.     [x + min_bounds.lbearing, y \- max_bounds.ascent]
  1786. .De
  1787. .IP
  1788. Its width is:
  1789. .Ds
  1790.     max_bounds.rbearing \- min_bounds.lbearing
  1791. .De
  1792. .IP
  1793. Its height is:
  1794. .Ds
  1795.     max_bounds.ascent + max_bounds.descent
  1796. .De
  1797. .IP \(bu 5
  1798. The ascent member is the logical extent of the font above the baseline that is
  1799. used for determining line spacing.
  1800. Specific characters may extend beyond
  1801. this.
  1802. .IP \(bu 5
  1803. The descent member is the logical extent of the font at or below the
  1804. baseline that is used for determining line spacing.
  1805. Specific characters may extend beyond this.
  1806. .IP \(bu 5
  1807. If the baseline is at Y-coordinate y,
  1808. the logical extent of the font is inclusive between the Y-coordinate 
  1809. values (y \- font.ascent) and (y + font.descent \- 1).
  1810. Typically,
  1811. the minimum interline spacing between rows of text is given
  1812. by ascent + descent.
  1813. .LP
  1814. For a character origin at [x,y],
  1815. the bounding box of a character (that is, 
  1816. the smallest rectangle that encloses the character's shape)
  1817. described in terms of 
  1818. .PN XCharStruct 
  1819. components is a rectangle with its upper-left corner at:
  1820. .LP
  1821. .Ds
  1822. [x + lbearing, y \- ascent]
  1823. .De
  1824. .LP
  1825. Its width is:
  1826. .LP
  1827. .Ds
  1828. rbearing \- lbearing
  1829. .De
  1830. .LP
  1831. Its height is:
  1832. .LP
  1833. .Ds
  1834. ascent + descent
  1835. .De
  1836. .LP
  1837. The origin for the next character is defined to be:
  1838. .LP
  1839. .Ds
  1840. [x + width, y]
  1841. .De
  1842. .LP
  1843. The lbearing member defines the extent of the left edge of the character ink
  1844. from the origin.
  1845. The rbearing member defines the extent of the right edge of the character ink
  1846. from the origin.
  1847. The ascent member defines the extent of the top edge of the character ink
  1848. from the origin.
  1849. The descent member defines the extent of the bottom edge of the character ink
  1850. from the origin.
  1851. The width member defines the logical width of the character.
  1852. .LP
  1853. Note that the baseline (the y position of the character origin) 
  1854. is logically viewed as being the scanline just below nondescending characters. 
  1855. When descent is zero,
  1856. only pixels with Y-coordinates less than y are drawn,
  1857. and the origin is logically viewed as being coincident with the left edge of
  1858. a nonkerned character. 
  1859. When lbearing is zero,
  1860. no pixels with X-coordinate less than x are drawn.
  1861. Any of the
  1862. .PN XCharStruct
  1863. metric members could be negative.
  1864. If the width is negative,
  1865. the next character will be placed to the left of the current origin.
  1866. .LP
  1867. The X protocol does not define the interpretation of the attributes member 
  1868. in the
  1869. .PN XCharStruct
  1870. structure.
  1871. A nonexistent character is represented with all members of its
  1872. .PN XCharStruct
  1873. set to zero.
  1874. .LP
  1875. A font is not guaranteed to have any properties.
  1876. The interpretation of the property value (for example, long or unsigned long)
  1877. must be derived from \fIa priori\fP knowledge of the property. 
  1878. A basic set of font properties is specified in the X Consortium standard
  1879. \fIX Logical Font Description Conventions\fP.
  1880. .NH 3
  1881. Loading and Freeing Fonts
  1882. .XS
  1883. \*(SN Loading and Freeing Fonts 
  1884. .XE
  1885. .LP
  1886. Xlib provides functions that you can use to load fonts, get font information,
  1887. unload fonts, and free font information.
  1888. .IN "Fonts" "getting information"
  1889. .IN "Fonts" "unloading"
  1890. .IN "Fonts" "freeing font information"
  1891. A few font functions use a 
  1892. .PN GContext 
  1893. resource ID or a font ID interchangeably.
  1894. .LP
  1895. .sp
  1896. To load a given font, use
  1897. .PN XLoadFont .
  1898. .IN "XLoadFont" "" "@DEF@"
  1899. .\" Start marker code here
  1900. .FD 0
  1901. .\" $Header: XLoadFont.f,v 1.1 88/02/26 10:01:25 mento Exp $
  1902. Font XLoadFont\^(\^\fIdisplay\fP, \fIname\fP\^)
  1903. .br
  1904.       Display *\fIdisplay\fP\^;
  1905. .br
  1906.       char *\fIname\fP\^;
  1907. .FN
  1908. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1909. .IP \fIdisplay\fP 1i
  1910. Specifies the connection to the X server.
  1911. .\" $Header: name.a,v 1.2 88/05/13 10:40:29 mento Exp $
  1912. .IP \fIname\fP 1i
  1913. Specifies the name of the font,
  1914. which is a null-terminated string.
  1915. .\" End marker code here
  1916. .LP
  1917. .\" $Header: XLoadFont.d,v 1.2 88/06/11 07:51:54 mento Exp $
  1918. The
  1919. .PN XLoadFont
  1920. function loads the specified font and returns its associated font ID.
  1921. If the font name is not in the Host Portable Character Encoding
  1922. the result is implementation dependent.
  1923. Use of uppercase or lowercase does not matter.
  1924. The interpretation of characters ``?''
  1925. and ``*'' in the name is not defined by the core protocol
  1926. but is reserved for future definition.
  1927. A structured format for font names is specified in the X Consortium standard 
  1928. \fIX Logical Font Description Conventions\fP.
  1929. If 
  1930. .PN XLoadFont
  1931. was unsuccessful at loading the specified font, 
  1932. .PN BadName 
  1933. error results.
  1934. Fonts are not associated with a particular screen 
  1935. and can be stored as a component
  1936. of any GC.
  1937. When the font is no longer needed, call 
  1938. .PN XUnloadFont .
  1939. .LP
  1940. .PN XLoadFont
  1941. can generate
  1942. .PN BadAlloc
  1943. and
  1944. .PN BadName 
  1945. errors.
  1946. .LP
  1947. .sp
  1948. To return information about an available font, use
  1949. .PN XQueryFont .
  1950. .IN "XQueryFont" "" "@DEF@"
  1951. .\" Start marker code here
  1952. .FD 0
  1953. XFontStruct *XQueryFont\^(\^\fIdisplay\fP, \fIfont_ID\fP\^)
  1954. .br
  1955.       Display *\fIdisplay\fP\^;
  1956. .br
  1957.       XID \fIfont_ID\fP\^;
  1958. .FN
  1959. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1960. .IP \fIdisplay\fP 1i
  1961. Specifies the connection to the X server.
  1962. .IP \fIfont_ID\fP 1i
  1963. Specifies the font ID or the 
  1964. .PN GContext
  1965. ID.
  1966. .\" End marker code here
  1967. .LP
  1968. .\" $Header: XQueryFont.d,v 1.2 88/06/11 07:52:41 mento Exp $
  1969. The
  1970. .PN XQueryFont
  1971. function returns a pointer to the
  1972. .PN XFontStruct
  1973. structure, which contains information associated with the font.
  1974. You can query a font or the font stored in a GC.
  1975. The font ID stored in the 
  1976. .PN XFontStruct
  1977. structure will be the 
  1978. .PN GContext 
  1979. ID, and you need to be careful when using this ID in other functions
  1980. (see
  1981. .PN XGContextFromGC ).
  1982. If the font does not exist,
  1983. .PN XQueryFont
  1984. returns NULL.
  1985. To free this data, use
  1986. .PN XFreeFontInfo .
  1987. .LP
  1988. .sp
  1989. To perform a
  1990. .PN XLoadFont
  1991. and
  1992. .PN XQueryFont
  1993. in a single operation, use
  1994. .PN XLoadQueryFont .
  1995. .IN "XLoadQueryFont" "" "@DEF@"
  1996. .\" Start marker code here
  1997. .FD 0
  1998. .\" $Header: XFontStruct.f,v 1.1 88/02/26 10:00:12 mento Exp $
  1999. XFontStruct *XLoadQueryFont\^(\^\fIdisplay\fP, \fIname\fP\^)
  2000. .br
  2001.       Display *\fIdisplay\fP\^;
  2002. .br
  2003.       char *\fIname\fP\^;
  2004. .FN
  2005. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2006. .IP \fIdisplay\fP 1i
  2007. Specifies the connection to the X server.
  2008. .\" $Header: name.a,v 1.2 88/05/13 10:40:29 mento Exp $
  2009. .IP \fIname\fP 1i
  2010. Specifies the name of the font,
  2011. which is a null-terminated string.
  2012. .\" End marker code here
  2013. .LP
  2014. .\" $Header: XFontStruct.d,v 1.3 88/06/11 07:50:37 mento Exp $
  2015. The
  2016. .PN XLoadQueryFont
  2017. function provides the most common way for accessing a font.
  2018. .PN XLoadQueryFont
  2019. both opens (loads) the specified font and returns a pointer to the
  2020. appropriate
  2021. .PN XFontStruct
  2022. structure.
  2023. If the font name is not in the Host Portable Character Encoding
  2024. the result is implementation dependent.
  2025. If the font does not exist,
  2026. .PN XLoadQueryFont
  2027. returns NULL.
  2028. .LP
  2029. .PN XLoadQueryFont
  2030. can generate a
  2031. .PN BadAlloc 
  2032. error.
  2033. .LP
  2034. .sp
  2035. To unload the font and free the storage used by the font structure
  2036. that was allocated by
  2037. .PN XQueryFont
  2038. or
  2039. .PN XLoadQueryFont ,
  2040. use
  2041. .PN XFreeFont .
  2042. .IN "XFreeFont" "" "@DEF@"
  2043. .\" Start marker code here
  2044. .FD 0
  2045. .\" $Header: XFontFree.f,v 1.1 88/02/26 10:00:11 mento Exp $
  2046. XFreeFont\^(\^\fIdisplay\fP, \fIfont_struct\fP\^)
  2047. .br
  2048.       Display *\fIdisplay\fP\^;
  2049. .br
  2050.       XFontStruct *\fIfont_struct\fP\^;
  2051. .FN
  2052. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2053. .IP \fIdisplay\fP 1i
  2054. Specifies the connection to the X server.
  2055. .\" $Header: ptr.a,v 1.1 88/02/26 10:30:46 mento Exp $
  2056. .IP \fIfont_struct\fP 1i
  2057. Specifies the storage associated with the font.
  2058. .\" End marker code here
  2059. .LP 
  2060. .\" $Header: XFontFree.d,v 1.3 88/05/13 10:59:37 mento Exp $
  2061. The
  2062. .PN XFreeFont
  2063. function deletes the association between the font resource ID and the specified 
  2064. font and frees the
  2065. .PN XFontStruct
  2066. structure.
  2067. The font itself will be freed when no other resource references it.
  2068. The data and the font should not be referenced again.
  2069. .LP
  2070. .PN XFreeFont
  2071. can generate a
  2072. .PN BadFont 
  2073. error.
  2074. .LP
  2075. .sp
  2076. To return a given font property, use
  2077. .PN XGetFontProperty .
  2078. .IN "XGetFontProperty" "" "@DEF@"
  2079. .\" Start marker code here
  2080. .FD 0
  2081. .\" $Header: XGetFontProp.f,v 1.1 88/02/26 10:00:27 mento Exp $
  2082. Bool XGetFontProperty\^(\^\fIfont_struct\fP\^, \^\fIatom\fP\^, \^\fIvalue_return\fP\^)
  2083. .br
  2084.       XFontStruct *\fIfont_struct\fP\^;
  2085. .br
  2086.       Atom \fIatom\fP\^;
  2087. .br
  2088.       unsigned long *\fIvalue_return\fP\^;
  2089. .FN
  2090. .\" $Header: ptr.a,v 1.1 88/02/26 10:30:46 mento Exp $
  2091. .IP \fIfont_struct\fP 1i
  2092. Specifies the storage associated with the font.
  2093. .\" $Header: atom.a,v 1.2 88/04/06 12:06:45 mento Exp $
  2094. .IP \fIatom\fP 1i
  2095. Specifies the atom for the property name you want returned.
  2096. .\" $Header: value.a,v 1.2 88/04/06 15:17:04 mento Exp $
  2097. .IP \fIvalue_return\fP 1i
  2098. Returns the value of the font property.
  2099. .\" End marker code here
  2100. .LP
  2101. .\" $Header: XGetFontProp.d,v 1.6 88/08/18 09:39:18 mento Exp $
  2102. Given the atom for that property,
  2103. the
  2104. .PN XGetFontProperty
  2105. function returns the value of the specified font property. 
  2106. .PN XGetFontProperty
  2107. also returns 
  2108. .PN False
  2109. if the property was not defined or 
  2110. .PN True
  2111. if it was defined.
  2112. A set of predefined atoms exists for font properties,
  2113. which can be found in
  2114. .Pn < X11/Xatom.h >.
  2115. This set contains the standard properties associated with
  2116. a font.
  2117. Although it is not guaranteed,
  2118. it is likely that the predefined font properties will be present.
  2119. .LP
  2120. .sp
  2121. To unload a font that was loaded by
  2122. .PN XLoadFont , 
  2123. use
  2124. .PN XUnloadFont .
  2125. .IN "XUnloadFont" "" "@DEF@"
  2126. .\" Start marker code here
  2127. .FD 0
  2128. .\" $Header: XCloseFont.f,v 1.1 88/02/26 09:58:49 mento Exp $
  2129. XUnloadFont\^(\^\fIdisplay\fP, \fIfont\fP\^)
  2130. .br
  2131.       Display *\fIdisplay\fP\^;
  2132. .br
  2133.       Font \fIfont\fP\^;
  2134. .FN
  2135. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2136. .IP \fIdisplay\fP 1i
  2137. Specifies the connection to the X server.
  2138. .\" $Header: font.a,v 1.2 88/05/09 14:28:06 mento Exp $
  2139. .IP \fIfont\fP 1i
  2140. Specifies the font.
  2141. .\" End marker code here
  2142. .LP
  2143. .\" $Header: XCloseFont.d,v 1.2 88/06/11 07:49:24 mento Exp $
  2144. The
  2145. .PN XUnloadFont
  2146. function deletes the association between the font resource ID and the specified font.
  2147. The font itself will be freed when no other resource references it.
  2148. The font should not be referenced again.
  2149. .LP
  2150. .PN XUnloadFont
  2151. can generate a
  2152. .PN BadFont 
  2153. error.
  2154. .NH 3
  2155. Obtaining and Freeing Font Names and Information
  2156. .XS
  2157. \*(SN Obtaining and Freeing Font Names and Information
  2158. .XE
  2159. .LP
  2160. You obtain font names and information by matching a wildcard specification
  2161. when querying a font type for a list of available sizes and so on.
  2162. .LP
  2163. .sp
  2164. To return a list of the available font names, use
  2165. .PN XListFonts .
  2166. .IN "XListFonts" "" "@DEF@"
  2167. .\" Start marker code here
  2168. .FD 0
  2169. .\" $Header: XFontNames.f,v 1.1 88/02/26 10:00:12 mento Exp $
  2170. char **XListFonts\^(\^\fIdisplay\fP, \fIpattern\fP\^, \fImaxnames\fP, \fIactual_count_return\fP\^)
  2171. .br
  2172.       Display *\^\fIdisplay\fP\^;
  2173. .br
  2174.       char *\^\fIpattern\fP\^;
  2175. .br
  2176.       int \fImaxnames\fP\^;
  2177. .br
  2178.       int *\^\fIactual_count_return\fP\^;
  2179. .FN
  2180. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2181. .IP \fIdisplay\fP 1i
  2182. Specifies the connection to the X server.
  2183. .\" $Header: pattern.a,v 1.4 88/05/13 11:08:04 mento Exp $
  2184. .IP \fIpattern\fP 1i
  2185. Specifies the null-terminated pattern string that can contain wildcard 
  2186. characters.
  2187. .IP \fImaxnames\fP 1i
  2188. Specifies the maximum number of names to be returned.
  2189. .IP \fIactual_count_return\fP 1i
  2190. Returns the actual number of font names.
  2191. .\" End marker code here
  2192. .LP
  2193. .\" $Header: XFontNames.d,v 1.2 88/06/11 07:50:36 mento Exp $
  2194. The
  2195. .PN XListFonts
  2196. function returns an array of available font names 
  2197. (as controlled by the font search path; see
  2198. .PN XSetFontPath )
  2199. that match the string you passed to the pattern argument.
  2200. The pattern string can contain any characters,
  2201. but each asterisk (*) is a wildcard for any number of characters,
  2202. and each question mark (?) is a wildcard for a single character.
  2203. If the pattern string is not in the Host Portable Character Encoding
  2204. the result is implementation dependent.
  2205. Use of uppercase or lowercase does not matter.
  2206. Each returned string is null-terminated.
  2207. If the data returned by the server is in the Latin Portable Character Encoding,
  2208. then the returned strings are in the Host Portable Character Encoding.
  2209. Otherwise, the result is implementation dependent.
  2210. If there are no matching font names,
  2211. .PN XListFonts
  2212. returns NULL.
  2213. The client should call
  2214. .PN XFreeFontNames
  2215. when finished with the result to free the memory.
  2216. .LP
  2217. .sp
  2218. To free a font name array, use
  2219. .PN XFreeFontNames .
  2220. .IN "XFreeFontNames" "" "@DEF@"
  2221. .\" Start marker code here
  2222. .FD 0
  2223. .\" $Header: XFrFntNames.f,v 1.1 88/02/26 10:00:15 mento Exp $
  2224. XFreeFontNames\^(\^\fIlist\fP\^)
  2225. .br
  2226.       char *\fIlist\fP\^[\^]\^;
  2227. .FN
  2228. .\" $Header: list.a,v 1.1 88/02/26 10:28:40 mento Exp $
  2229. .IP \fIlist\fP 1i
  2230. Specifies the array of strings you want to free.
  2231. .\" End marker code here
  2232. .LP
  2233. .\" $Header: XFrFntNames.d,v 1.2 88/04/23 09:33:05 mento Exp $
  2234. The
  2235. .PN XFreeFontNames
  2236. function frees the array and strings returned by
  2237. .PN XListFonts 
  2238. or
  2239. .PN XListFontsWithInfo .
  2240. .LP
  2241. .sp
  2242. To obtain the names and information about available fonts, use
  2243. .PN XListFontsWithInfo .
  2244. .IN "XListFontsWithInfo" "" "@DEF@"
  2245. .\" Start marker code here
  2246. .FD 0
  2247. char **XListFontsWithInfo\^(\^\fIdisplay\fP, \fIpattern\fP, \fImaxnames\fP, \fIcount_return\fP, \fIinfo_return\fP\^)
  2248. .br
  2249.       Display *\fIdisplay\fP\^;
  2250. .br
  2251.       char *\fIpattern\fP\^;
  2252. .br
  2253.       int \fImaxnames\fP\^;
  2254. .br
  2255.       int *\fIcount_return\fP\^;
  2256. .br
  2257.       XFontStruct **\fIinfo_return\fP\^;
  2258. .FN
  2259. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2260. .IP \fIdisplay\fP 1i
  2261. Specifies the connection to the X server.
  2262. .\" $Header: pattern.a,v 1.4 88/05/13 11:08:04 mento Exp $
  2263. .IP \fIpattern\fP 1i
  2264. Specifies the null-terminated pattern string that can contain wildcard 
  2265. characters.
  2266. .IP \fImaxnames\fP 1i
  2267. Specifies the maximum number of names to be returned.
  2268. .IP \fIcount_return\fP 1i
  2269. Returns the actual number of matched font names.
  2270. .IP \fIinfo_return\fP 1i
  2271. Returns the font information.
  2272. .\" End marker code here
  2273. .LP
  2274. .\" $Header: XFNameInfo.d,v 1.3 88/06/11 07:50:14 mento Exp $
  2275. The
  2276. .PN XListFontsWithInfo
  2277. function returns a list of font names that match the specified pattern and their
  2278. associated font information.
  2279. The list of names is limited to size specified by maxnames.
  2280. The information returned for each font is identical to what
  2281. .PN XLoadQueryFont
  2282. would return except that the per-character metrics are not returned.
  2283. The pattern string can contain any characters,
  2284. but each asterisk (*) is a wildcard for any number of characters,
  2285. and each question mark (?) is a wildcard for a single character.
  2286. If the pattern string is not in the Host Portable Character Encoding
  2287. the result is implementation dependent.
  2288. Use of uppercase or lowercase does not matter.
  2289. Each returned string is null-terminated.
  2290. If the data returned by the server is in the Latin Portable Character Encoding,
  2291. then the returned strings are in the Host Portable Character Encoding.
  2292. Otherwise, the result is implementation dependent.
  2293. If there are no matching font names,
  2294. .PN XListFontsWithInfo
  2295. returns NULL.
  2296. .LP
  2297. To free only the allocated name array,
  2298. the client should call
  2299. .PN XFreeFontNames .
  2300. To free both the name array and the font information array,
  2301. or to free just the font information array,
  2302. the client should call
  2303. .PN XFreeFontInfo .
  2304. .LP
  2305. .sp
  2306. To free the the font information array, use
  2307. .PN XFreeFontInfo .
  2308. .IN "XFreeFontInfo" "" "@DEF@"
  2309. .\" Start marker code here
  2310. .FD 0
  2311. XFreeFontInfo(\^\fInames\fP, \fIfree_info\fP, \fIactual_count\fP\^)
  2312. .br
  2313.       char **\fInames\fP\^;
  2314. .br
  2315.       XFontStruct *\fIfree_info\fP;
  2316. .br
  2317.       int \fIactual_count\fP\^;
  2318. .FN
  2319. .IP \fInames\fP 1i
  2320. Specifies the list of font names returned by
  2321. .PN XListFontsWithInfo .
  2322. .IP \fIfree_info\fP 1i
  2323. Specifies the font information returned by
  2324. .PN XListFontsWithInfo .
  2325. .IP \fIactual_count\fP 1i
  2326. Specifies the actual number of matched font names returned by
  2327. .PN XListFontsWithInfo .
  2328. .\" End marker code here
  2329. .LP
  2330. .\" $Header: XFFontInfo.d,v 1.1 88/02/26 10:41:55 mento Exp $
  2331. The
  2332. .PN XFreeFontInfo
  2333. function frees the the font information array.
  2334. To free an
  2335. .PN XFontStruct
  2336. structure without closing the font,
  2337. call
  2338. .PN XFreeFontInfo
  2339. with the names argument specified as NULL.
  2340. .NH 3
  2341. Computing Character String Sizes
  2342. .XS
  2343. \*(SN Computing Character String Sizes 
  2344. .XE
  2345. .LP
  2346. Xlib provides functions that you can use to compute the width,
  2347. the logical extents, 
  2348. and the server information about 8-bit and 2-byte text strings.
  2349. .IN "XTextWidth"
  2350. .IN "XTextWidth16"
  2351. The width is computed by adding the character widths of all the characters.
  2352. It does not matter if the font is an 8-bit or 2-byte font.
  2353. These functions return the sum of the character metrics, in pixels.
  2354. .LP
  2355. .sp
  2356. To determine the width of an 8-bit character string, use
  2357. .PN XTextWidth .
  2358. .IN "XTextWidth" "" "@DEF@"
  2359. .\" Start marker code here
  2360. .FD 0
  2361. .\" $Header: XTextWidth.f,v 1.1 88/02/26 10:04:00 mento Exp $
  2362. int XTextWidth\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
  2363. .br
  2364.       XFontStruct *\fIfont_struct\fP\^;
  2365. .br
  2366.       char *\fIstring\fP\^;
  2367. .br
  2368.       int \fIcount\fP\^;
  2369. .FN
  2370. .\" $Header: ptr_width.a,v 1.1 88/02/26 10:30:47 mento Exp $
  2371. .IP \fIfont_struct\fP 1i
  2372. Specifies the font used for the width computation.
  2373. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2374. .IP \fIstring\fP 1i
  2375. Specifies the character string.
  2376. .IP \fIcount\fP 1i
  2377. Specifies the character count in the specified string.
  2378. .\" End marker code here
  2379. .LP
  2380. .sp
  2381. To determine the width of a 2-byte character string, use
  2382. .PN XTextWidth16 .
  2383. .IN "XTextWidth16" "" "@DEF@"
  2384. .\" Start marker code here
  2385. .FD 0
  2386. .\" $Header: XTextWidth16.f,v 1.1 88/02/26 10:04:01 mento Exp $
  2387. int XTextWidth16\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
  2388. .br
  2389.       XFontStruct *\fIfont_struct\fP\^;
  2390. .br
  2391.       XChar2b *\fIstring\fP\^;
  2392. .br
  2393.       int \fIcount\fP\^;
  2394. .FN
  2395. .\" $Header: ptr_width.a,v 1.1 88/02/26 10:30:47 mento Exp $
  2396. .IP \fIfont_struct\fP 1i
  2397. Specifies the font used for the width computation.
  2398. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2399. .IP \fIstring\fP 1i
  2400. Specifies the character string.
  2401. .IP \fIcount\fP 1i
  2402. Specifies the character count in the specified string.
  2403. .\" End marker code here
  2404. .NH 3
  2405. Computing Logical Extents
  2406. .XS
  2407. \*(SN Computing Logical Extents 
  2408. .XE
  2409. .LP
  2410. To compute the bounding box of an 8-bit character string in a given font, use
  2411. .PN XTextExtents .
  2412. .IN "XTextExtents" "" "@DEF@"
  2413. .\" Start marker code here
  2414. .FD 0
  2415. XTextExtents\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
  2416. \fIdirection_return\fP, \fIfont_ascent_return\fP,
  2417. .br
  2418.               \fIfont_descent_return\fP, \fIoverall_return\fP\^)
  2419. .br
  2420.       XFontStruct *\fIfont_struct\fP\^;
  2421. .br
  2422.       char *\fIstring\fP\^;
  2423. .br
  2424.       int \fInchars\fP\^;
  2425. .br
  2426.       int *\fIdirection_return\fP\^;
  2427. .br
  2428.       int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
  2429. .br
  2430.       XCharStruct *\fIoverall_return\fP\^;
  2431.  
  2432. .FN
  2433. .IP \fIfont_struct\fP 1i
  2434. Specifies the 
  2435. .PN XFontStruct 
  2436. structure.
  2437. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2438. .IP \fIstring\fP 1i
  2439. Specifies the character string.
  2440. .IP \fInchars\fP 1i
  2441. Specifies the number of characters in the character string.
  2442. .IP \fIdirection_return\fP 1i
  2443. Returns the value of the direction hint
  2444. .Pn ( FontLeftToRight
  2445. or
  2446. .PN FontRightToLeft ).
  2447. .IP \fIfont_ascent_return\fP 1i
  2448. Returns the font ascent.
  2449. .IP \fIfont_descent_return\fP 1i
  2450. Returns the font descent.
  2451. .IP \fIoverall_return\fP 1i
  2452. Returns the overall size in the specified
  2453. .PN XCharStruct 
  2454. structure.
  2455. .\" End marker code here
  2456. .LP
  2457. .sp
  2458. To compute the bounding box of a 2-byte character string in a given font, use
  2459. .PN XTextExtents16 .
  2460. .IN "XTextExtents16" "" "@DEF@"
  2461. .\" Start marker code here
  2462. .FD 0
  2463. XTextExtents16\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
  2464. \fIdirection_return\fP, \fIfont_ascent_return\fP, 
  2465. .br
  2466.                 \fIfont_descent_return\fP, \fIoverall_return\fP\^)
  2467. .br
  2468.       XFontStruct *\fIfont_struct\fP\^;
  2469. .br
  2470.       XChar2b *\fIstring\fP\^;
  2471. .br
  2472.       int \fInchars\fP\^;
  2473. .br
  2474.       int *\fIdirection_return\fP\^;
  2475. .br
  2476.       int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
  2477. .br
  2478.       XCharStruct *\fIoverall_return\fP\^;
  2479.  
  2480. .FN
  2481. .IP \fIfont_struct\fP 1i
  2482. Specifies the 
  2483. .PN XFontStruct 
  2484. structure.
  2485. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2486. .IP \fIstring\fP 1i
  2487. Specifies the character string.
  2488. .IP \fInchars\fP 1i
  2489. Specifies the number of characters in the character string.
  2490. .IP \fIdirection_return\fP 1i
  2491. Returns the value of the direction hint
  2492. .Pn ( FontLeftToRight
  2493. or
  2494. .PN FontRightToLeft ).
  2495. .IP \fIfont_ascent_return\fP 1i
  2496. Returns the font ascent.
  2497. .IP \fIfont_descent_return\fP 1i
  2498. Returns the font descent.
  2499. .IP \fIoverall_return\fP 1i
  2500. Returns the overall size in the specified
  2501. .PN XCharStruct 
  2502. structure.
  2503. .\" End marker code here
  2504. .LP
  2505. .\" $Header: XTextExt.d,v 1.2 88/06/11 07:54:02 mento Exp $
  2506. The
  2507. .PN XTextExtents
  2508. and
  2509. .PN XTextExtents16
  2510. functions 
  2511. perform the size computation locally and, thereby,
  2512. avoid the round-trip overhead of
  2513. .PN XQueryTextExtents 
  2514. and
  2515. .PN XQueryTextExtents16 .
  2516. Both functions return an
  2517. .PN XCharStruct
  2518. structure, whose members are set to the values as follows.
  2519. .LP
  2520. The ascent member is set to the maximum of the ascent metrics of all
  2521. characters in the string.
  2522. The descent member is set to the maximum of the descent metrics.
  2523. The width member is set to the sum of the character-width metrics of all
  2524. characters in the string.
  2525. For each character in the string,
  2526. let W be the sum of the character-width metrics of all characters preceding 
  2527. it in the string.
  2528. Let L be the left-side-bearing metric of the character plus W.
  2529. Let R be the right-side-bearing metric of the character plus W.
  2530. The lbearing member is set to the minimum L of all characters in the string.
  2531. The rbearing member is set to the maximum R.
  2532. .LP
  2533. For fonts defined with linear indexing rather than 2-byte matrix indexing,
  2534. each 
  2535. .PN XChar2b 
  2536. structure is interpreted as a 16-bit number with byte1 as the 
  2537. most-significant byte.
  2538. If the font has no defined default character,
  2539. undefined characters in the string are taken to have all zero metrics.
  2540. .NH 3
  2541. Querying Character String Sizes
  2542. .XS
  2543. \*(SN Querying Character String Sizes 
  2544. .XE
  2545. .LP
  2546. To query the server for the bounding box of an 8-bit character string in a 
  2547. given font, use 
  2548. .PN XQueryTextExtents .
  2549. .IN "XQueryTextExtents" "" "@DEF@"
  2550. .\" Start marker code here
  2551. .FD 0
  2552. XQueryTextExtents\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
  2553. \fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, 
  2554. .br
  2555.                     \fIfont_descent_return\fP, \fIoverall_return\fP\^)
  2556. .br
  2557.       Display *\fIdisplay\fP\^;
  2558. .br
  2559.       XID \fIfont_ID\fP\^;
  2560. .br
  2561.       char *\fIstring\fP\^;
  2562. .br
  2563.       int \fInchars\fP\^;
  2564. .br
  2565.       int *\fIdirection_return\fP\^;
  2566. .br
  2567.       int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
  2568. .br
  2569.       XCharStruct *\fIoverall_return\fP\^;
  2570. .FN
  2571. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2572. .IP \fIdisplay\fP 1i
  2573. Specifies the connection to the X server.
  2574. .IP \fIfont_ID\fP 1i
  2575. Specifies either the font ID or the 
  2576. .PN GContext
  2577. ID that contains the font.
  2578. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2579. .IP \fIstring\fP 1i
  2580. Specifies the character string.
  2581. .IP \fInchars\fP 1i
  2582. Specifies the number of characters in the character string.
  2583. .IP \fIdirection_return\fP 1i
  2584. Returns the value of the direction hint
  2585. .Pn ( FontLeftToRight
  2586. or
  2587. .PN FontRightToLeft ).
  2588. .IP \fIfont_ascent_return\fP 1i
  2589. Returns the font ascent.
  2590. .IP \fIfont_descent_return\fP 1i
  2591. Returns the font descent.
  2592. .IP \fIoverall_return\fP 1i
  2593. Returns the overall size in the specified
  2594. .PN XCharStruct 
  2595. structure.
  2596. .\" End marker code here
  2597. .LP
  2598. .sp
  2599. To query the server for the bounding box of a 2-byte character string
  2600. in a given font, use
  2601. .PN XQueryTextExtents16 .
  2602. .IN "XQueryTextExtents16" "" "@DEF@"
  2603. .\" Start marker code here
  2604. .FD 0
  2605. XQueryTextExtents16\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
  2606. \fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, 
  2607. .br
  2608.                         \fIfont_descent_return\fP, \fIoverall_return\fP\^)
  2609. .br
  2610.       Display *\fIdisplay\fP\^;
  2611. .br
  2612.       XID \fIfont_ID\fP\^;
  2613. .br
  2614.       XChar2b *\fIstring\fP\^;
  2615. .br
  2616.       int \fInchars\fP\^;
  2617. .br
  2618.       int *\fIdirection_return\fP\^;
  2619. .br
  2620.       int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
  2621. .br
  2622.       XCharStruct *\fIoverall_return\fP\^;
  2623. .FN
  2624. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2625. .IP \fIdisplay\fP 1i
  2626. Specifies the connection to the X server.
  2627. .IP \fIfont_ID\fP 1i
  2628. Specifies either the font ID or the 
  2629. .PN GContext
  2630. ID that contains the font.
  2631. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2632. .IP \fIstring\fP 1i
  2633. Specifies the character string.
  2634. .IP \fInchars\fP 1i
  2635. Specifies the number of characters in the character string.
  2636. .IP \fIdirection_return\fP 1i
  2637. Returns the value of the direction hint
  2638. .Pn ( FontLeftToRight
  2639. or
  2640. .PN FontRightToLeft ).
  2641. .IP \fIfont_ascent_return\fP 1i
  2642. Returns the font ascent.
  2643. .IP \fIfont_descent_return\fP 1i
  2644. Returns the font descent.
  2645. .IP \fIoverall_return\fP 1i
  2646. Returns the overall size in the specified
  2647. .PN XCharStruct 
  2648. structure.
  2649. .\" End marker code here
  2650. .LP
  2651. .\" $Header: XQryTExts.d,v 1.2 88/06/11 07:52:33 mento Exp $
  2652. The
  2653. .PN XQueryTextExtents
  2654. and
  2655. .PN XQueryTextExtents16
  2656. functions return the bounding box of the specified 8-bit and 16-bit
  2657. character string in the specified font or the font contained in the
  2658. specified GC.
  2659. These functions query the X server and, therefore, suffer the round-trip
  2660. overhead that is avoided by
  2661. .PN XTextExtents
  2662. and 
  2663. .PN XTextExtents16 .
  2664. Both functions return a
  2665. .PN XCharStruct 
  2666. structure, whose members are set to the values as follows.
  2667. .LP
  2668. The ascent member is set to the maximum of the ascent metrics 
  2669. of all characters in the string.
  2670. The descent member is set to the maximum of the descent metrics.
  2671. The width member is set to the sum of the character-width metrics 
  2672. of all characters in the string.
  2673. For each character in the string,
  2674. let W be the sum of the character-width metrics of all characters preceding
  2675. it in the string.
  2676. Let L be the left-side-bearing metric of the character plus W.
  2677. Let R be the right-side-bearing metric of the character plus W.
  2678. The lbearing member is set to the minimum L of all characters in the string.
  2679. The rbearing member is set to the maximum R.
  2680. .LP
  2681. For fonts defined with linear indexing rather than 2-byte matrix indexing,
  2682. each 
  2683. .PN XChar2b 
  2684. structure is interpreted as a 16-bit number with byte1 as the 
  2685. most-significant byte.
  2686. If the font has no defined default character,
  2687. undefined characters in the string are taken to have all zero metrics.
  2688. .LP
  2689. Characters with all zero metrics are ignored.
  2690. If the font has no defined default_char,
  2691. the undefined characters in the string are also ignored.
  2692. .LP
  2693. .PN XQueryTextExtents
  2694. and
  2695. .PN XQueryTextExtents16
  2696. can generate
  2697. .PN BadFont
  2698. and
  2699. .PN BadGC 
  2700. errors.
  2701. .NH 2
  2702. Drawing Text
  2703. .XS
  2704. \*(SN Drawing Text
  2705. .XE
  2706. .LP
  2707. This section discusses how to draw:
  2708. .IP \(bu 5
  2709. Complex text 
  2710. .IP \(bu 5
  2711. Text characters
  2712. .IP \(bu 5
  2713. Image text characters
  2714. .LE
  2715. .LP
  2716. The fundamental text functions
  2717. .PN XDrawText
  2718. and
  2719. .PN XDrawText16
  2720. use the following structures.
  2721. .LP
  2722. .IN "XTextItem" "" "@DEF@"
  2723. .\" Start marker code here
  2724. .Ds 0
  2725. .TA .5i 3i
  2726. .ta .5i 3i
  2727. typedef struct {
  2728.     char *chars;    /* pointer to string */
  2729.     int nchars;    /* number of characters */
  2730.     int delta;    /* delta between strings */
  2731.     Font font;    /* Font to print it in, None don't change */
  2732. } XTextItem;
  2733. .De
  2734. .LP
  2735. .IN "XTextItem16" "" "@DEF@"
  2736. .Ds 0
  2737. .TA .5i 3i
  2738. .ta .5i 3i
  2739. typedef struct {
  2740.     XChar2b *chars;    /* pointer to two-byte characters */
  2741.     int nchars;    /* number of characters */
  2742.     int delta;    /* delta between strings */
  2743.     Font font;    /* font to print it in, None don't change */
  2744. } XTextItem16;
  2745. .De
  2746. .\" End marker code here
  2747. .LP
  2748. If the font member is not
  2749. .PN None ,
  2750. the font is changed before printing and also is stored in the GC.
  2751. If an error was generated during text drawing,
  2752. the previous items may have been drawn.
  2753. The baseline of the characters are drawn starting at the x and y
  2754. coordinates that you pass in the text drawing functions.
  2755. .LP
  2756. For example, consider the background rectangle drawn by
  2757. .PN XDrawImageString .
  2758. If you want the upper-left corner of the background rectangle
  2759. to be at pixel coordinate (x,y), pass the (x,y + ascent)
  2760. as the baseline origin coordinates to the text functions.
  2761. The ascent is the font ascent, as given in the
  2762. .PN XFontStruct
  2763. structure.
  2764. If you want the lower-left corner of the background rectangle
  2765. to be at pixel coordinate (x,y), pass the (x,y \- descent + 1)
  2766. as the baseline origin coordinates to the text functions.
  2767. The descent is the font descent, as given in the
  2768. .PN XFontStruct
  2769. structure.
  2770. .NH 3
  2771. Drawing Complex Text
  2772. .XS
  2773. \*(SN Drawing Complex Text 
  2774. .XE
  2775. .LP
  2776. .IN "Text" "drawing"
  2777. .IN "Drawing" "text items"
  2778. .LP
  2779. To draw 8-bit characters in a given drawable, use
  2780. .PN XDrawText .
  2781. .IN "XDrawText" "" "@DEF@"
  2782. .\" Start marker code here
  2783. .FD 0
  2784. .\" $Header: XPolyText.f,v 1.1 88/02/26 10:01:57 mento Exp $
  2785. XDrawText\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
  2786. .br
  2787.       Display *\fIdisplay\fP\^;
  2788. .br
  2789.       Drawable \fId\fP\^;
  2790. .br
  2791.       GC \fIgc\fP\^;
  2792. .br
  2793.       int \fIx\fP\^, \fIy\fP\^;
  2794. .br
  2795.       XTextItem *\fIitems\fP\^;
  2796. .br
  2797.       int \fInitems\fP\^;
  2798. .FN
  2799. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2800. .IP \fIdisplay\fP 1i
  2801. Specifies the connection to the X server.
  2802. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  2803. .IP \fId\fP 1i
  2804. Specifies the drawable. 
  2805. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2806. .IP \fIgc\fP 1i
  2807. Specifies the GC.
  2808. .ds Xy , which are relative to the origin of the specified drawable \
  2809. and define the origin of the first character
  2810. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  2811. .IP \fIx\fP 1i
  2812. .br
  2813. .ns
  2814. .IP \fIy\fP 1i
  2815. Specify the x and y coordinates\*(Xy.
  2816. .\" $Header: items.a,v 1.1 88/02/26 10:28:21 mento Exp $
  2817. .IP \fIitems\fP 1i
  2818. Specifies an array of text items.
  2819. .\" $Header: nitems.a,v 1.1 88/02/26 10:29:33 mento Exp $
  2820. .IP \fInitems\fP 1i
  2821. Specifies the number of text items in the array.
  2822. .\" End marker code here
  2823. .LP
  2824. .sp
  2825. To draw 2-byte characters in a given drawable, use
  2826. .PN XDrawText16 .
  2827. .IN "XDrawText16" "" "@DEF@"
  2828. .\" Start marker code here
  2829. .FD 0
  2830. .\" $Header: XPolyText16.f,v 1.1 88/02/26 10:01:59 mento Exp $
  2831. XDrawText16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
  2832. .br
  2833.       Display *\fIdisplay\fP\^;
  2834. .br
  2835.       Drawable \fId\fP\^;
  2836. .br
  2837.       GC \fIgc\fP\^;
  2838. .br
  2839.       int \fIx\fP\^, \fIy\fP\^;
  2840. .br
  2841.       XTextItem16 *\fIitems\fP\^;
  2842. .br
  2843.       int \fInitems\fP\^;
  2844. .FN
  2845. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2846. .IP \fIdisplay\fP 1i
  2847. Specifies the connection to the X server.
  2848. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  2849. .IP \fId\fP 1i
  2850. Specifies the drawable. 
  2851. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2852. .IP \fIgc\fP 1i
  2853. Specifies the GC.
  2854. .ds Xy , which are relative to the origin of the specified drawable \
  2855. and define the origin of the first character
  2856. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  2857. .IP \fIx\fP 1i
  2858. .br
  2859. .ns
  2860. .IP \fIy\fP 1i
  2861. Specify the x and y coordinates\*(Xy.
  2862. .\" $Header: items.a,v 1.1 88/02/26 10:28:21 mento Exp $
  2863. .IP \fIitems\fP 1i
  2864. Specifies an array of text items.
  2865. .\" $Header: nitems.a,v 1.1 88/02/26 10:29:33 mento Exp $
  2866. .IP \fInitems\fP 1i
  2867. Specifies the number of text items in the array.
  2868. .\" End marker code here
  2869. .LP
  2870. .\" $Header: XPolyText.d,v 1.2 88/06/11 07:52:25 mento Exp $
  2871. The
  2872. .PN XDrawText16
  2873. function is similar to
  2874. .PN XDrawText 
  2875. except that it uses 2-byte or 16-bit characters.
  2876. Both functions allow complex spacing and font shifts between counted strings.
  2877. .LP
  2878. Each text item is processed in turn.
  2879. A font member other than 
  2880. .PN None
  2881. in an item causes the font to be stored in the GC
  2882. and used for subsequent text.  
  2883. A text element delta specifies an additional change
  2884. in the position along the x axis before the string is drawn. 
  2885. The delta is always added to the character origin
  2886. and is not dependent on any characteristics of the font.
  2887. Each character image, as defined by the font in the GC, is treated as an
  2888. additional mask for a fill operation on the drawable.
  2889. The drawable is modified only where the font character has a bit set to 1.
  2890. If a text item generates a
  2891. .PN BadFont
  2892. error, the previous text items may have been drawn.
  2893. .LP
  2894. For fonts defined with linear indexing rather than 2-byte matrix indexing,
  2895. each 
  2896. .PN XChar2b
  2897. structure is interpreted as a 16-bit number with byte1 as the 
  2898. most-significant byte.
  2899. .LP
  2900. Both functions use these GC components:
  2901. function, plane-mask, fill-style, font, subwindow-mode, 
  2902. clip-x-origin, clip-y-origin, and clip-mask.
  2903. They also use these GC mode-dependent components: 
  2904. foreground, background, tile, stipple, tile-stipple-x-origin, 
  2905. and tile-stipple-y-origin.
  2906. .LP
  2907. .PN XDrawText
  2908. and
  2909. .PN XDrawText16
  2910. can generate
  2911. .PN BadDrawable ,
  2912. .PN BadFont ,
  2913. .PN BadGC ,
  2914. and
  2915. .PN BadMatch 
  2916. errors.
  2917. .NH 3
  2918. Drawing Text Characters
  2919. .XS
  2920. \*(SN Drawing Text Characters 
  2921. .XE
  2922. .LP
  2923. .IN "Strings" "drawing"
  2924. .IN "Drawing" "strings"
  2925. To draw 8-bit characters in a given drawable, use
  2926. .PN XDrawString .
  2927. .IN "XDrawString" "" "@DEF@"
  2928. .\" Start marker code here
  2929. .FD 0
  2930. .\" $Header: XText.f,v 1.1 88/02/26 10:03:22 mento Exp $
  2931. XDrawString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
  2932. .br
  2933.       Display *\fIdisplay\fP\^;
  2934. .br
  2935.       Drawable \fId\fP\^;
  2936. .br
  2937.       GC \fIgc\fP\^;
  2938. .br
  2939.       int \fIx\fP\^, \fIy\fP\^;
  2940. .br
  2941.       char *\fIstring\fP\^;
  2942. .br
  2943.       int \fIlength\fP\^; 
  2944. .FN
  2945. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2946. .IP \fIdisplay\fP 1i
  2947. Specifies the connection to the X server.
  2948. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  2949. .IP \fId\fP 1i
  2950. Specifies the drawable. 
  2951. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2952. .IP \fIgc\fP 1i
  2953. Specifies the GC.
  2954. .ds Xy , which are relative to the origin of the specified drawable \
  2955. and define the origin of the first character
  2956. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  2957. .IP \fIx\fP 1i
  2958. .br
  2959. .ns
  2960. .IP \fIy\fP 1i
  2961. Specify the x and y coordinates\*(Xy.
  2962. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  2963. .IP \fIstring\fP 1i
  2964. Specifies the character string.
  2965. .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
  2966. .IP \fIlength\fP 1i
  2967. Specifies the number of characters in the string argument.
  2968. .\" End marker code here
  2969. .LP
  2970. .sp
  2971. To draw 2-byte characters in a given drawable, use
  2972. .PN XDrawString16 .
  2973. .IN "XDrawString16" "" "@DEF@"
  2974. .\" Start marker code here
  2975. .FD 0
  2976. .\" $Header: XText16.f,v 1.1 88/02/26 10:03:57 mento Exp $
  2977. XDrawString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
  2978. .br
  2979.       Display *\fIdisplay\fP\^;
  2980. .br
  2981.       Drawable \fId\fP\^;
  2982. .br
  2983.       GC \fIgc\fP\^;
  2984. .br
  2985.       int \fIx\fP\^, \fIy\fP\^;
  2986. .br
  2987.       XChar2b *\fIstring\fP\^;
  2988. .br
  2989.       int \fIlength\fP\^; 
  2990. .FN
  2991. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2992. .IP \fIdisplay\fP 1i
  2993. Specifies the connection to the X server.
  2994. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  2995. .IP \fId\fP 1i
  2996. Specifies the drawable. 
  2997. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  2998. .IP \fIgc\fP 1i
  2999. Specifies the GC.
  3000. .ds Xy , which are relative to the origin of the specified drawable \
  3001. and define the origin of the first character
  3002. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  3003. .IP \fIx\fP 1i
  3004. .br
  3005. .ns
  3006. .IP \fIy\fP 1i
  3007. Specify the x and y coordinates\*(Xy.
  3008. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  3009. .IP \fIstring\fP 1i
  3010. Specifies the character string.
  3011. .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
  3012. .IP \fIlength\fP 1i
  3013. Specifies the number of characters in the string argument.
  3014. .\" End marker code here
  3015. .LP
  3016. .\" $Header: XText.d,v 1.2 88/06/11 07:54:01 mento Exp $
  3017. Each character image, as defined by the font in the GC, is treated as an
  3018. additional mask for a fill operation on the drawable.
  3019. The drawable is modified only where the font character has a bit set to 1.
  3020. For fonts defined with 2-byte matrix indexing
  3021. and used with
  3022. .PN XDrawString16 ,
  3023. each byte is used as a byte2 with a byte1 of zero.
  3024. .LP
  3025. Both functions use these GC components: 
  3026. function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, 
  3027. clip-y-origin, and clip-mask.
  3028. They also use these GC mode-dependent components: 
  3029. foreground, background, tile, stipple, tile-stipple-x-origin, 
  3030. and tile-stipple-y-origin.
  3031. .LP
  3032. .PN XDrawString
  3033. and
  3034. .PN XDrawString16
  3035. can generate
  3036. .PN BadDrawable ,
  3037. .PN BadGC ,
  3038. and
  3039. .PN BadMatch 
  3040. errors.
  3041. .NH 3
  3042. Drawing Image Text Characters
  3043. .XS
  3044. \*(SN Drawing Image Text Characters 
  3045. .XE
  3046. .LP
  3047. .IN "Image text" "drawing"
  3048. .IN "Drawing" "image text"
  3049. Some applications, in particular terminal emulators, need to
  3050. print image text in which both the foreground and background bits of
  3051. each character are painted.
  3052. This prevents annoying flicker on many displays.
  3053. .IN "XDrawImageString"
  3054. .IN "XDrawImageString16"
  3055. .LP
  3056. .sp
  3057. To draw 8-bit image text characters in a given drawable, use
  3058. .PN XDrawImageString .
  3059. .IN "XDrawImageString" "" "@DEF@"
  3060. .\" Start marker code here
  3061. .FD 0
  3062. .\" $Header: XImageText.f,v 1.1 88/02/26 10:01:09 mento Exp $
  3063. XDrawImageString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
  3064. .br
  3065.       Display *\fIdisplay\fP\^;
  3066. .br
  3067.       Drawable \fId\fP\^;
  3068. .br
  3069.       GC \fIgc\fP\^;
  3070. .br
  3071.       int \fIx\fP\^, \fIy\fP\^;
  3072. .br
  3073.       char *\fIstring\fP\^;
  3074. .br
  3075.       int \fIlength\fP\^; 
  3076. .FN
  3077. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3078. .IP \fIdisplay\fP 1i
  3079. Specifies the connection to the X server.
  3080. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  3081. .IP \fId\fP 1i
  3082. Specifies the drawable. 
  3083. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  3084. .IP \fIgc\fP 1i
  3085. Specifies the GC.
  3086. .ds Xy , which are relative to the origin of the specified drawable \
  3087. and define the origin of the first character
  3088. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  3089. .IP \fIx\fP 1i
  3090. .br
  3091. .ns
  3092. .IP \fIy\fP 1i
  3093. Specify the x and y coordinates\*(Xy.
  3094. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  3095. .IP \fIstring\fP 1i
  3096. Specifies the character string.
  3097. .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
  3098. .IP \fIlength\fP 1i
  3099. Specifies the number of characters in the string argument.
  3100. .\" End marker code here
  3101. .LP
  3102. .sp
  3103. To draw 2-byte image text characters in a given drawable, use
  3104. .PN XDrawImageString16 .
  3105. .IN "XDrawImageString16" "" "@DEF@"
  3106. .\" Start marker code here
  3107. .FD 0
  3108. .\" $Header: XImageText16.f,v 1.1 88/02/26 10:01:10 mento Exp $
  3109. XDrawImageString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
  3110. .br
  3111.       Display *\fIdisplay\fP\^;
  3112. .br
  3113.       Drawable \fId\fP\^;
  3114. .br
  3115.       GC \fIgc\fP\^;
  3116. .br
  3117.       int \fIx\fP\^, \fIy\fP\^;
  3118. .br
  3119.       XChar2b *\fIstring\fP\^;
  3120. .br
  3121.       int \fIlength\fP\^; 
  3122. .FN
  3123. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3124. .IP \fIdisplay\fP 1i
  3125. Specifies the connection to the X server.
  3126. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  3127. .IP \fId\fP 1i
  3128. Specifies the drawable. 
  3129. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  3130. .IP \fIgc\fP 1i
  3131. Specifies the GC.
  3132. .ds Xy , which are relative to the origin of the specified drawable \
  3133. and define the origin of the first character
  3134. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  3135. .IP \fIx\fP 1i
  3136. .br
  3137. .ns
  3138. .IP \fIy\fP 1i
  3139. Specify the x and y coordinates\*(Xy.
  3140. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  3141. .IP \fIstring\fP 1i
  3142. Specifies the character string.
  3143. .\" $Header: length.a,v 1.1 88/02/26 10:28:36 mento Exp $
  3144. .IP \fIlength\fP 1i
  3145. Specifies the number of characters in the string argument.
  3146. .\" End marker code here
  3147. .LP
  3148. .\" $Header: XImageText.d,v 1.2 88/06/11 07:51:40 mento Exp $
  3149. The
  3150. .PN XDrawImageString16
  3151. function is similar to
  3152. .PN XDrawImageString 
  3153. except that it uses 2-byte or 16-bit characters.
  3154. Both functions also use both the foreground and background pixels 
  3155. of the GC in the destination.
  3156. .LP
  3157. The effect is first to fill a
  3158. destination rectangle with the background pixel defined in the GC and then
  3159. to paint the text with the foreground pixel.
  3160. The upper-left corner of the filled rectangle is at:
  3161. .LP
  3162. .Ds
  3163. [x, y \- font-ascent]
  3164. .De
  3165. .LP
  3166. The width is:
  3167. .LP
  3168. .Ds
  3169. overall-width
  3170. .De
  3171. .LP
  3172. The height is:
  3173. .LP
  3174. .Ds
  3175. font-ascent + font-descent
  3176. .De
  3177. .LP
  3178. The overall-width, font-ascent, and font-descent
  3179. are as would be returned by 
  3180. .PN XQueryTextExtents 
  3181. using gc and string.
  3182. The function and fill-style defined in the GC are ignored for these functions. 
  3183. The effective function is 
  3184. .PN GXcopy ,
  3185. and the effective fill-style is
  3186. .PN FillSolid .
  3187. .LP
  3188. For fonts defined with 2-byte matrix indexing
  3189. and used with
  3190. .PN XDrawImageString ,
  3191. each byte is used as a byte2 with a byte1 of zero.
  3192. .LP
  3193. Both functions use these GC components: 
  3194. plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, 
  3195. clip-y-origin, and clip-mask.
  3196. .LP
  3197. .PN XDrawImageString
  3198. and
  3199. .PN XDrawImageString16
  3200. can generate
  3201. .PN BadDrawable ,
  3202. .PN BadGC ,
  3203. and
  3204. .PN BadMatch 
  3205. errors.
  3206. .LP
  3207. .NH 2
  3208. Transferring Images between Client and Server
  3209. .XS
  3210. \*(SN Transferring Images between Client and Server 
  3211. .XE
  3212. .LP
  3213. Xlib provides functions that you can use to transfer images between a client 
  3214. and the server.
  3215. Because the server may require diverse data formats, 
  3216. Xlib provides an image object that fully describes the data in memory 
  3217. and that provides for basic operations on that data.  
  3218. You should reference the data 
  3219. through the image object rather than referencing the data directly.
  3220. However, some implementations of the Xlib library may efficiently deal with 
  3221. frequently used data formats by replacing
  3222. functions in the procedure vector with special case functions.
  3223. Supported operations include destroying the image, getting a pixel,
  3224. storing a pixel, extracting a subimage of an image, and adding a constant
  3225. to an image (see section 16.5).
  3226. .LP
  3227. All the image manipulation functions discussed in this section make use of 
  3228. the 
  3229. .PN XImage 
  3230. data structure,
  3231. which describes an image as it exists in the client's memory.
  3232. .LP
  3233. .IN "XImage" "" "@DEF@"
  3234. .\" Start marker code here
  3235. .Ds 0
  3236. .TA .5i 1i 3i
  3237. .ta .5i 1i 3i
  3238. typedef struct _XImage {
  3239.     int width, height;        /* size of image */
  3240.     int xoffset;        /* number of pixels offset in X direction */
  3241.     int format;        /* XYBitmap, XYPixmap, ZPixmap */
  3242.     char *data;        /* pointer to image data */
  3243.     int byte_order;        /* data byte order, LSBFirst, MSBFirst */
  3244.     int bitmap_unit;        /* quant. of scanline 8, 16, 32 */
  3245.     int bitmap_bit_order;        /* LSBFirst, MSBFirst */
  3246.     int bitmap_pad;        /* 8, 16, 32 either XY or ZPixmap */
  3247.     int depth;        /* depth of image */
  3248.     int bytes_per_line;        /* accelerator to next scanline */
  3249.     int bits_per_pixel;        /* bits per pixel (ZPixmap) */
  3250.     unsigned long red_mask;        /* bits in z arrangement */
  3251.     unsigned long green_mask;
  3252.     unsigned long blue_mask;
  3253.     XPointer obdata;    /* hook for the object routines to hang on */
  3254.     struct funcs {        /* image manipulation routines */
  3255.         struct _XImage *(*create_image)();
  3256.         int (*destroy_image)();
  3257.         unsigned long (*get_pixel)();
  3258.         int (*put_pixel)();
  3259.         struct _XImage *(*sub_image)();
  3260.         int (*add_pixel)();
  3261.     } f;
  3262. } XImage;
  3263. .De
  3264. .\" End marker code here
  3265. .LP
  3266. You may request that some of the members (for example,
  3267. height, width, and xoffset) be
  3268. changed when the image is sent to the server. 
  3269. That is, you may send a subset of the image.
  3270. Other members (for example, byte_order, bitmap_unit, and so forth)
  3271. are characteristics of both the image and the server.  
  3272. If these members
  3273. differ between the image and the server, 
  3274. .PN XPutImage 
  3275. makes the appropriate
  3276. conversions.
  3277. .\"If the image is formatted as an XYPixmap, 
  3278. .\"(that is, the format member is set to
  3279. .\".PN XYPixmap ), 
  3280. The first byte of the first scanline of
  3281. plane n is located at the address (data + (n * height * bytes_per_line)).
  3282. .LP
  3283. .sp
  3284. To combine an image in memory with a rectangle of a drawable on the display,
  3285. use
  3286. .PN XPutImage .
  3287. .IN "XPutImage" "" "@DEF@"
  3288. .\" Start marker code here
  3289. .FD 0
  3290. .\" $Header: XPutImage.f,v 1.2 88/08/23 15:07:57 mento Exp $
  3291. XPutImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIimage\fP\^, \fIsrc_x\fP, \fIsrc_y\fP, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
  3292. .br
  3293.         Display *\fIdisplay\fP\^;
  3294. .br
  3295.         Drawable \fId\fP\^;
  3296. .br
  3297.         GC \fIgc\fP\^;
  3298. .br
  3299.         XImage *\fIimage\fP\^;
  3300. .br
  3301.         int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
  3302. .br
  3303.         int \fIdest_x\fP\^, \fIdest_y\fP\^;
  3304. .br
  3305.         unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  3306. .FN
  3307. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3308. .IP \fIdisplay\fP 1i
  3309. Specifies the connection to the X server.
  3310. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  3311. .IP \fId\fP 1i
  3312. Specifies the drawable. 
  3313. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  3314. .IP \fIgc\fP 1i
  3315. Specifies the GC.
  3316. .\" $Header: image.a,v 1.1 88/02/26 10:28:13 mento Exp $
  3317. .IP \fIimage\fP 1i
  3318. Specifies the image you want combined with the rectangle. 
  3319. .IP \fIsrc_x\fP 1i
  3320. Specifies the offset in X from the left edge of the image defined
  3321. by the 
  3322. .PN XImage 
  3323. data structure.
  3324. .IP \fIsrc_y\fP 1i
  3325. Specifies the offset in Y from the top edge of the image defined
  3326. by the 
  3327. .PN XImage 
  3328. data structure.
  3329. .ds Dx , which are relative to the origin of the drawable \
  3330. and are the coordinates of the subimage
  3331. .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
  3332. .IP \fIdest_x\fP 1i
  3333. .br
  3334. .ns
  3335. .IP \fIdest_y\fP 1i
  3336. Specify the x and y coordinates\*(Dx. 
  3337. .ds Wh \ of the subimage, which define the dimensions of the rectangle
  3338. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  3339. .IP \fIwidth\fP 1i
  3340. .br
  3341. .ns
  3342. .IP \fIheight\fP 1i
  3343. Specify the width and height\*(Wh.
  3344. .\" End marker code here
  3345. .LP
  3346. .\" $Header: XPutImage.d,v 1.3 88/08/18 09:43:13 mento Exp $
  3347. The
  3348. .PN XPutImage
  3349. function
  3350. combines an image in memory with a rectangle of the specified drawable.
  3351. If 
  3352. .PN XYBitmap 
  3353. format is used, the depth of the image must be one,
  3354. or a
  3355. .PN BadMatch 
  3356. error results.
  3357. The foreground pixel in the GC defines the source for the one bits in the image,
  3358. and the background pixel defines the source for the zero bits.
  3359. For 
  3360. .PN XYPixmap 
  3361. and 
  3362. .PN ZPixmap , 
  3363. the depth of the image must match the depth of the drawable,
  3364. or a
  3365. .PN BadMatch
  3366. error results.
  3367. The section of the image defined by the src_x, src_y, width, and height 
  3368. arguments is drawn on the specified part of the drawable.
  3369. .LP
  3370. This function uses these GC components: 
  3371. function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, 
  3372. and clip-mask.
  3373. It also uses these GC mode-dependent components:
  3374. foreground and background.
  3375. .LP
  3376. .PN XPutImage
  3377. can generate
  3378. .PN BadDrawable ,
  3379. .PN BadGC ,
  3380. .PN BadMatch ,
  3381. and
  3382. .PN BadValue 
  3383. errors.
  3384. .LP
  3385. .sp
  3386. To return the contents of a rectangle in a given drawable on the display,
  3387. use
  3388. .PN XGetImage .
  3389. This function specifically supports rudimentary screen dumps.
  3390. .IN "XGetImage" "" "@DEF@"
  3391. .\" Start marker code here
  3392. .FD 0
  3393. .\" $Header: XGetImage.f,v 1.1 88/02/26 10:00:47 mento Exp $
  3394. XImage *XGetImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^)
  3395. .br
  3396.         Display *\fIdisplay\fP\^;
  3397. .br
  3398.         Drawable \fId\fP\^;
  3399. .br
  3400.         int \fIx\fP\^, \fIy\fP\^;
  3401. .br
  3402.         unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  3403. .br
  3404.         unsigned long \fIplane_mask\fP\^;
  3405. .br
  3406.         int \fIformat\fP\^;
  3407. .FN
  3408. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3409. .IP \fIdisplay\fP 1i
  3410. Specifies the connection to the X server.
  3411. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  3412. .IP \fId\fP 1i
  3413. Specifies the drawable. 
  3414. .ds Xy , which are relative to the origin of the drawable \
  3415. and define the upper-left corner of the rectangle
  3416. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  3417. .IP \fIx\fP 1i
  3418. .br
  3419. .ns
  3420. .IP \fIy\fP 1i
  3421. Specify the x and y coordinates\*(Xy.
  3422. .ds Wh \ of the subimage, which define the dimensions of the rectangle
  3423. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  3424. .IP \fIwidth\fP 1i
  3425. .br
  3426. .ns
  3427. .IP \fIheight\fP 1i
  3428. Specify the width and height\*(Wh.
  3429. .\" $Header: plane_mask.a,v 1.1 88/02/26 10:30:28 mento Exp $
  3430. .IP \fIplane_mask\fP 1i
  3431. Specifies the plane mask.
  3432. .\" *** JIM: NEED MORE INFO FOR THIS. ***
  3433. .IP \fIformat\fP 1i
  3434. Specifies the format for the image.
  3435. You can pass
  3436. .PN XYPixmap
  3437. or 
  3438. .PN ZPixmap .
  3439. .\" End marker code here
  3440. .LP
  3441. .\" $Header: XGetImage.d,v 1.3 88/08/18 09:45:47 mento Exp $
  3442. The
  3443. .PN XGetImage
  3444. function returns a pointer to an
  3445. .PN XImage
  3446. structure.
  3447. This structure provides you with the contents of the specified rectangle of
  3448. the drawable in the format you specify.
  3449. If the format argument is 
  3450. .PN XYPixmap ,
  3451. the image contains only the bit planes you passed to the plane_mask argument.
  3452. If the plane_mask argument only requests a subset of the planes of the
  3453. display, the depth of the returned image will be the number of planes
  3454. requested.
  3455. If the format argument is 
  3456. .PN ZPixmap ,
  3457. .PN XGetImage
  3458. returns as zero the bits in all planes not 
  3459. specified in the plane_mask argument.
  3460. The function performs no range checking on the values in plane_mask and ignores
  3461. extraneous bits.
  3462. .LP
  3463. .PN XGetImage
  3464. returns the depth of the image to the depth member of the
  3465. .PN XImage
  3466. structure.
  3467. The depth of the image is as specified when the drawable was created,
  3468. except when getting a subset of the planes in 
  3469. .PN XYPixmap
  3470. format, when the depth is given by the number of bits set to 1 in plane_mask.
  3471. .LP
  3472. If the drawable is a pixmap, 
  3473. the given rectangle must be wholly contained within the pixmap, 
  3474. or a
  3475. .PN BadMatch
  3476. error results.
  3477. If the drawable is a window, 
  3478. the window must be viewable, 
  3479. and it must be the case that if there were no inferiors or overlapping windows,
  3480. the specified rectangle of the window would be fully visible on the screen
  3481. and wholly contained within the outside edges of the window,
  3482. or a
  3483. .PN BadMatch
  3484. error results.
  3485. Note that the borders of the window can be included and read with
  3486. this request.
  3487. If the window has backing-store, the backing-store contents are
  3488. returned for regions of the window that are obscured by noninferior
  3489. windows. 
  3490. If the window does not have backing-store,
  3491. the returned contents of such obscured regions are undefined.
  3492. The returned contents of visible regions of inferiors
  3493. of a different depth than the specified window's depth are also undefined.
  3494. The pointer cursor image is not included in the returned contents.
  3495. If a problem occurs,
  3496. .PN XGetImage
  3497. returns NULL.
  3498. .LP
  3499. .PN XGetImage
  3500. can generate
  3501. .PN BadDrawable ,
  3502. .PN BadMatch ,
  3503. and
  3504. .PN BadValue 
  3505. errors.
  3506. .sp
  3507. To copy the contents of a rectangle on the display
  3508. to a location within a preexisting image structure, use
  3509. .PN XGetSubImage .
  3510. .IN "XGetSubImage" "" "@DEF@"
  3511. .\" Start marker code here
  3512. .FD 0
  3513. .\" $Header: XGetSImage.f,v 1.1 88/02/26 10:00:58 mento Exp $
  3514. XImage *XGetSubImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^, \fIdest_image\fP\^, \fIdest_x\fP\^, 
  3515. .br
  3516.                      \fIdest_y\fP\^)
  3517. .br
  3518.       Display *\fIdisplay\fP\^;
  3519. .br
  3520.       Drawable \fId\fP\^;
  3521. .br
  3522.       int \fIx\fP\^, \fIy\fP\^;
  3523. .br
  3524.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  3525. .br
  3526.       unsigned long \fIplane_mask\fP\^;
  3527. .br
  3528.       int \fIformat\fP\^;
  3529. .br
  3530.       XImage *\fIdest_image\fP\^;
  3531. .br
  3532.       int \fIdest_x\fP\^, \fIdest_y\fP\^;
  3533. .FN
  3534. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3535. .IP \fIdisplay\fP 1i
  3536. Specifies the connection to the X server.
  3537. .\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
  3538. .IP \fId\fP 1i
  3539. Specifies the drawable. 
  3540. .ds Xy , which are relative to the origin of the drawable \
  3541. and define the upper-left corner of the rectangle
  3542. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  3543. .IP \fIx\fP 1i
  3544. .br
  3545. .ns
  3546. .IP \fIy\fP 1i
  3547. Specify the x and y coordinates\*(Xy.
  3548. .ds Wh \ of the subimage, which define the dimensions of the rectangle
  3549. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  3550. .IP \fIwidth\fP 1i
  3551. .br
  3552. .ns
  3553. .IP \fIheight\fP 1i
  3554. Specify the width and height\*(Wh.
  3555. .\" $Header: plane_mask.a,v 1.1 88/02/26 10:30:28 mento Exp $
  3556. .IP \fIplane_mask\fP 1i
  3557. Specifies the plane mask.
  3558. .\" *** JIM: NEED MORE INFO FOR THIS. ***
  3559. .IP \fIformat\fP 1i
  3560. Specifies the format for the image.
  3561. You can pass
  3562. .PN XYPixmap
  3563. or 
  3564. .PN ZPixmap .
  3565. .IP \fIdest_image\fP 1i
  3566. Specify the destination image.
  3567. .ds Dx , which are relative to the origin of the destination rectangle, \
  3568. specify its upper-left corner, and determine where the subimage \
  3569. is placed in the destination image
  3570. .\" $Header: dstxy_gen.a,v 1.2 88/08/04 11:09:55 mento Exp $
  3571. .IP \fIdest_x\fP 1i
  3572. .br
  3573. .ns
  3574. .IP \fIdest_y\fP 1i
  3575. Specify the x and y coordinates\*(Dx. 
  3576. .\" End marker code here
  3577. .LP
  3578. .\" $Header: XGetSImage.d,v 1.6 88/08/21 06:57:22 mento Exp $
  3579. The 
  3580. .PN XGetSubImage 
  3581. function updates dest_image with the specified subimage in the same manner as 
  3582. .PN XGetImage . 
  3583. If the format argument is 
  3584. .PN XYPixmap ,
  3585. the image contains only the bit planes you passed to the plane_mask argument.
  3586. If the format argument is 
  3587. .PN ZPixmap ,
  3588. .PN XGetSubImage
  3589. returns as zero the bits in all planes not 
  3590. specified in the plane_mask argument.
  3591. The function performs no range checking on the values in plane_mask and ignores
  3592. extraneous bits.
  3593. As a convenience,
  3594. .PN XGetSubImage
  3595. returns a pointer to the same
  3596. .PN XImage
  3597. structure specified by dest_image.
  3598. .LP
  3599. The depth of the destination
  3600. .PN XImage
  3601. structure must be the same as that of the drawable.
  3602. If the specified subimage does not fit at the specified location
  3603. on the destination image, the right and bottom edges are clipped.
  3604. If the drawable is a pixmap,
  3605. the given rectangle must be wholly contained within the pixmap,
  3606. or a
  3607. .PN BadMatch
  3608. error results.
  3609. If the drawable is a window, 
  3610. the window must be viewable, 
  3611. and it must be the case that if there were no inferiors or overlapping windows,
  3612. the specified rectangle of the window would be fully visible on the screen
  3613. and wholly contained within the outside edges of the window,
  3614. or a
  3615. .PN BadMatch
  3616. error results.
  3617. If the window has backing-store, 
  3618. then the backing-store contents are returned for regions of the window 
  3619. that are obscured by noninferior windows. 
  3620. If the window does not have backing-store, 
  3621. the returned contents of such obscured regions are undefined.
  3622. The returned contents of visible regions of inferiors
  3623. of a different depth than the specified window's depth are also undefined.
  3624. If a problem occurs,
  3625. .PN XGetSubImage
  3626. returns NULL.
  3627. .LP
  3628. .PN XGetSubImage
  3629. can generate
  3630. .PN BadDrawable ,
  3631. .PN BadGC ,
  3632. .PN BadMatch ,
  3633. and
  3634. .PN BadValue 
  3635. errors.
  3636. .bp
  3637.