home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / AppD < prev    next >
Encoding:
Text File  |  1991-07-30  |  28.5 KB  |  1,137 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBAppendix D\fP\s-1
  5.  
  6. \s+1\fBCompatibility Functions\fP\s-1
  7. .sp 2
  8. .na
  9. .LP
  10. .XS
  11. Appendix D: Compatibility Functions
  12. .XE
  13. .LP
  14. The X Version 11 and X Version 10 functions discussed in this appendix 
  15. are obsolete, have been superseded by newer X Version 11 functions,
  16. and are maintained for compatibility reasons only.
  17. .SH
  18. X Version 11 Compatibility Functions
  19. .LP
  20. You can use the X Version 11 compatibility functions to:
  21. .IP \(bu 5
  22. Set standard properties 
  23. .IP \(bu 5
  24. Set and get window sizing hints 
  25. .IP \(bu 5
  26. Set and get an XStandardColormap structure 
  27. .IP \(bu 5
  28. Parse window geometry
  29. .IP \(bu 5
  30. Get X environment defaults
  31. .SH
  32. Setting Standard Properties
  33. .LP
  34. To specify a minimum set of properties describing the ``quickie'' application,
  35. use
  36. .PN XSetStandardProperties .
  37. This function has been superseded by
  38. .PN XSetWMProperties
  39. and sets all or portions of the 
  40. WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, 
  41. and WM_NORMAL_HINTS properties.
  42. .IN "XSetStandardProperties" "" "@DEF@"
  43. .\" Start marker code here
  44. .FD 0
  45. XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^)
  46. .br
  47.       Display *\fIdisplay\fP\^;
  48. .br
  49.       Window \fIw\fP\^;
  50. .br
  51.       char *\fIwindow_name\fP\^;
  52. .br
  53.       char *\fIicon_name\fP\^;
  54. .br
  55.       Pixmap \fIicon_pixmap\fP\^;
  56. .br
  57.       char **\fIargv\fP\^;
  58. .br
  59.       int \fIargc\fP\^;
  60. .br
  61.       XSizeHints *\fIhints\fP\^;
  62. .FN
  63. .IP \fIdisplay\fP 1i
  64. Specifies the connection to the X server.
  65. .IP \fIw\fP 1i
  66. Specifies the window.
  67. .IP \fIwindow_name\fP 1i
  68. Specifies the window name,
  69. which should be a null-terminated string.
  70. .IP \fIicon_name\fP 1i
  71. Specifies the icon name,
  72. which should be a null-terminated string.
  73. .IP \fIicon_pixmap\fP 1i
  74. Specifies the bitmap that is to be used for the icon or
  75. .PN None .
  76. .IP \fIargv\fP 1i
  77. Specifies the application's argument list.
  78. .IP \fIargc\fP 1i
  79. Specifies the number of arguments.
  80. .IP \fIhints\fP 1i
  81. Specifies a pointer to the size hints for the window in its normal state.
  82. .\" End marker code here
  83. .LP
  84. The
  85. .PN XSetStandardProperties
  86. function provides a means by which simple applications set the
  87. most essential properties with a single call.
  88. .PN XSetStandardProperties
  89. should be used to give a window manager some information about 
  90. your program's preferences. 
  91. It should not be used by applications that need
  92. to communicate more information than is possible with
  93. .PN XSetStandardProperties .
  94. (Typically, argv is the argv array of your main program.)
  95. If the strings are not in the Host Portable Character Encoding
  96. the result is implementation dependent.
  97. .LP
  98. .PN XSetStandardProperties
  99. can generate
  100. .PN BadAlloc
  101. and
  102. .PN BadWindow 
  103. errors.
  104. .SH
  105. Setting and Getting Window Sizing Hints
  106. .LP
  107. Xlib provides functions that you can use to set or get window sizing hints.
  108. The functions discussed in this section use the flags and the
  109. .PN XSizeHints 
  110. structure, as defined in the
  111. .Pn < X11/Xutil.h >
  112. header file, and use the WM_NORMAL_HINTS property.
  113. .LP
  114. .sp
  115. To set the size hints for a given window in its normal state, use
  116. .PN XSetNormalHints .
  117. This function has been superseded by
  118. .PN XSetWMNormalHints .
  119. .IN "XSetNormalHints" "" "@DEF@"
  120. .\" Start marker code here
  121. .FD 0
  122. XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
  123. .br
  124.       Display *\fIdisplay\fP\^;
  125. .br
  126.       Window \fIw\fP\^;
  127. .br
  128.       XSizeHints *\fIhints\fP\^;
  129. .FN
  130. .IP \fIdisplay\fP 1i
  131. Specifies the connection to the X server.
  132. .IP \fIw\fP 1i
  133. Specifies the window.
  134. .IP \fIhints\fP 1i
  135. Specifies a pointer to the size hints for the window in its normal state.
  136. .\" End marker code here
  137. .LP
  138. The
  139. .PN XSetNormalHints
  140. function sets the size hints structure for the specified window.
  141. Applications use
  142. .PN XSetNormalHints
  143. to inform the window manager of the size
  144. or position desirable for that window.
  145. In addition, 
  146. an application that wants to move or resize itself should call
  147. .PN XSetNormalHints
  148. and specify its new desired location and size
  149. as well as making direct Xlib calls to move or resize.  
  150. This is because window managers may ignore redirected
  151. configure requests, but they pay attention to property changes.
  152. .LP
  153. To set size hints, 
  154. an application not only must assign values to the appropriate members
  155. in the hints structure but also must set the flags member of the structure 
  156. to indicate which information is present and where it came from.  
  157. A call to
  158. .PN XSetNormalHints
  159. is meaningless, unless the flags member is set to indicate which members of
  160. the structure have been assigned values.
  161. .LP
  162. .PN XSetNormalHints
  163. can generate
  164. .PN BadAlloc
  165. and
  166. .PN BadWindow 
  167. errors.
  168. .LP
  169. .sp
  170. To return the size hints for a window in its normal state, use
  171. .PN XGetNormalHints .
  172. This function has been superseded by
  173. .PN XGetWMNormalHints .
  174. .IN "XGetNormalHints" "" "@DEF@"
  175. .\" Start marker code here
  176. .FD 0
  177. Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^)
  178. .br
  179.       Display *\fIdisplay\fP\^;
  180. .br
  181.       Window \fIw\fP\^;
  182. .br
  183.       XSizeHints *\fIhints_return\fP\^;
  184. .FN
  185. .IP \fIdisplay\fP 1i
  186. Specifies the connection to the X server.
  187. .IP \fIw\fP 1i
  188. Specifies the window.
  189. .IP \fIhints_return\fP 1i
  190. Returns the size hints for the window in its normal state.
  191. .\" End marker code here
  192. .LP
  193. The
  194. .PN XGetNormalHints
  195. function returns the size hints for a window in its normal state.
  196. It returns a nonzero status if it succeeds or zero if
  197. the application specified no normal size hints for this window.
  198. .LP
  199. .PN XGetNormalHints
  200. can generate a
  201. .PN BadWindow 
  202. error.
  203. .LP
  204. .sp
  205. The next two functions set and read the WM_ZOOM_HINTS property.
  206. .LP
  207. To set the zoom hints for a window, use
  208. .PN XSetZoomHints .
  209. This function is no longer supported by the
  210. \fIInter-Client Communication Conventions Manual\fP.
  211. .IN "XSetZoomHints" "" "@DEF@"
  212. .\" Start marker code here
  213. .FD 0
  214. XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^)
  215. .br
  216.       Display *\fIdisplay\fP\^;
  217. .br
  218.       Window \fIw\fP\^;
  219. .br
  220.       XSizeHints *\fIzhints\fP\^;
  221. .FN
  222. .IP \fIdisplay\fP 1i
  223. Specifies the connection to the X server.
  224. .IP \fIw\fP 1i
  225. Specifies the window.
  226. .IP \fIzhints\fP 1i
  227. Specifies a pointer to the zoom hints.
  228. .\" End marker code here
  229. .LP
  230. Many window managers think of windows in one of three states:
  231. iconic, normal, or zoomed.
  232. The
  233. .PN XSetZoomHints
  234. function provides the window manager with information for the window in the
  235. zoomed state.
  236. .LP
  237. .PN XSetZoomHints
  238. can generate
  239. .PN BadAlloc
  240. and
  241. .PN BadWindow 
  242. errors.
  243. .LP
  244. .sp
  245. To read the zoom hints for a window, use
  246. .PN XGetZoomHints .
  247. This function is no longer supported by the
  248. \fIInter-Client Communication Conventions Manual\fP.
  249. .IN "XGetZoomHints" "" "@DEF@"
  250. .\" Start marker code here
  251. .FD 0
  252. Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^)
  253. .br
  254.       Display *\fIdisplay\fP\^;
  255. .br
  256.       Window \fIw\fP\^;
  257. .br
  258.       XSizeHints *\fIzhints_return\fP\^;
  259. .FN
  260. .IP \fIdisplay\fP 1i
  261. Specifies the connection to the X server.
  262. .IP \fIw\fP 1i
  263. Specifies the window.
  264. .IP \fIzhints_return\fP 1i
  265. Returns the zoom hints.
  266. .\" End marker code here
  267. .LP
  268. The
  269. .PN XGetZoomHints
  270. function returns the size hints for a window in its zoomed state.
  271. It returns a nonzero status if it succeeds or zero if
  272. the application specified no zoom size hints for this window.
  273. .LP
  274. .PN XGetZoomHints
  275. can generate a
  276. .PN BadWindow 
  277. error.
  278. .LP
  279. .sp
  280. To set the value of any property of type WM_SIZE_HINTS, use
  281. .PN XSetSizeHints .
  282. This function has been superseded by
  283. .PN XSetWMSizeHints .
  284. .IN "XSetSizeHints" "" "@DEF@"
  285. .\" Start marker code here
  286. .FD 0
  287. XSetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
  288. .br
  289.       Display *\fIdisplay\fP\^;
  290. .br
  291.       Window \fIw\fP\^;
  292. .br
  293.       XSizeHints *\fIhints\fP\^;
  294. .br
  295.       Atom \fIproperty\fP\^;
  296. .FN
  297. .IP \fIdisplay\fP 1i
  298. Specifies the connection to the X server.
  299. .IP \fIw\fP 1i
  300. Specifies the window.
  301. .IP \fIhints\fP 1i
  302. Specifies a pointer to the size hints.
  303. .IP \fIproperty\fP 1i
  304. Specifies the property name.
  305. .\" End marker code here
  306. .LP
  307. The
  308. .PN XSetSizeHints
  309. function sets the
  310. .PN XSizeHints
  311. structure for the named property and the specified window.
  312. This is used by
  313. .PN XSetNormalHints
  314. and
  315. .PN XSetZoomHints ,
  316. and can be used to set the value of any property of type WM_SIZE_HINTS.
  317. Thus, it may be useful if other properties of that type get defined.
  318. .LP
  319. .PN XSetSizeHints
  320. can generate
  321. .PN BadAlloc ,
  322. .PN BadAtom ,
  323. and
  324. .PN BadWindow 
  325. errors.
  326. .LP
  327. .sp
  328. To read the value of any property of type WM_SIZE_HINTS, use
  329. .PN XGetSizeHints .
  330. This function has been superseded by
  331. .PN XGetWMSizeHints .
  332. .IN "XGetSizeHints" "" "@DEF@"
  333. .\" Start marker code here
  334. .FD 0
  335. Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^)
  336. .br
  337.       Display *\fIdisplay\fP\^;
  338. .br
  339.       Window \fIw\fP\^;
  340. .br
  341.       XSizeHints *\fIhints_return\fP\^;
  342. .br
  343.       Atom \fIproperty\fP\^;
  344. .FN
  345. .IP \fIdisplay\fP 1i
  346. Specifies the connection to the X server.
  347. .IP \fIw\fP 1i
  348. Specifies the window.
  349. .IP \fIhints_return\fP 1i
  350. Returns the size hints.
  351. .IP \fIproperty\fP 1i
  352. Specifies the property name.
  353. .\" End marker code here
  354. .LP
  355. .PN XGetSizeHints
  356. returns the
  357. .PN XSizeHints
  358. structure for the named property and the specified window.
  359. This is used by
  360. .PN XGetNormalHints
  361. and
  362. .PN XGetZoomHints .
  363. It also can be used to retrieve the value of any property of type
  364. WM_SIZE_HINTS.
  365. Thus, it may be useful if other properties of that type get defined.
  366. .PN XGetSizeHints
  367. returns a nonzero status if a size hint was defined
  368. or zero otherwise.
  369. .LP
  370. .PN XGetSizeHints
  371. can generate
  372. .PN BadAtom
  373. and 
  374. .PN BadWindow 
  375. errors.
  376. .SH
  377. Getting and Setting an XStandardColormap Structure
  378. .LP
  379. To get the 
  380. .PN XStandardColormap 
  381. structure associated with one of the described atoms, use
  382. .PN XGetStandardColormap .
  383. This function has been superseded by
  384. .PN XGetRGBColormap .
  385. .IN "XGetStandardColormap" "" "@DEF@"
  386. .\" Start marker code here
  387. .FD 0
  388. Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^)
  389. .br
  390.       Display *\fIdisplay\fP\^;
  391. .br
  392.       Window \fIw\fP\^;
  393. .br
  394.       XStandardColormap *\fIcolormap_return\fP\^;
  395. .br
  396.       Atom \fIproperty\fP\^;    /* RGB_BEST_MAP, etc. */
  397. .FN
  398. .IP \fIdisplay\fP 1i
  399. Specifies the connection to the X server.
  400. .IP \fIw\fP 1i
  401. Specifies the window.
  402. .IP \fIcolormap_return\fP 1i
  403. Returns the colormap associated with the specified atom.
  404. .IP \fIproperty\fP 1i
  405. Specifies the property name.
  406. .\" End marker code here
  407. .LP
  408. The
  409. .PN XGetStandardColormap
  410. function returns the colormap definition associated with the atom supplied
  411. as the property argument.
  412. .PN XGetStandardColormap
  413. returns a nonzero status if successful, and zero otherwise.
  414. For example,
  415. to fetch the standard
  416. .PN GrayScale
  417. colormap for a display,
  418. you use
  419. .PN XGetStandardColormap
  420. with the following syntax:
  421. .LP
  422. .\" Start marker code here
  423. .Ds 0
  424. .TA .5i 1.5i
  425. .ta .5i 1.5i
  426. XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
  427. .De
  428. .\" End marker code here
  429. .LP
  430. See section 14.3 for the semantics of standard colormaps.
  431. .LP
  432. .PN XGetStandardColormap
  433. can generate
  434. .PN BadAtom
  435. and
  436. .PN BadWindow 
  437. errors.
  438. .LP
  439. .sp
  440. To set a standard colormap, use
  441. .PN XSetStandardColormap .
  442. This function has been superseded by
  443. .PN XSetRGBColormap .
  444. .IN "XSetStandardColormap" "" "@DEF@"
  445. .\" Start marker code here
  446. .FD 0
  447. XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^)
  448. .br
  449.       Display *\fIdisplay\fP\^;
  450. .br
  451.       Window \fIw\fP\^;
  452. .br
  453.       XStandardColormap *\fIcolormap\fP\^;
  454. .br
  455.       Atom \fIproperty\fP\^;    /* RGB_BEST_MAP, etc. */
  456. .FN
  457. .IP \fIdisplay\fP 1i
  458. Specifies the connection to the X server.
  459. .IP \fIw\fP 1i
  460. Specifies the window.
  461. .IP \fIcolormap\fP 1i
  462. Specifies the colormap.
  463. .IP \fIproperty\fP 1i
  464. Specifies the property name.
  465. .\" End marker code here
  466. .LP
  467. The
  468. .PN XSetStandardColormap
  469. function usually is only used by window or session managers.
  470. .LP
  471. .PN XSetStandardColormap
  472. can generate
  473. .PN BadAlloc ,
  474. .PN BadAtom ,
  475. .PN BadDrawable ,
  476. and
  477. .PN BadWindow 
  478. errors.
  479. .SH
  480. Parsing Window Geometry
  481. .LP
  482. To parse window geometry given a user-specified position 
  483. and a default position, use
  484. .PN XGeometry .
  485. This function has been superseded by
  486. .PN XWMGeometry .
  487. .IN "Window" "determining location"
  488. .IN "XGeometry" "" "@DEF@"
  489. .\" Start marker code here
  490. .FD 0
  491. int XGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIposition\fP\^, \fIdefault_position\fP\^, \fIbwidth\fP\^, \fIfwidth\fP\^, \fIfheight\fP\^, \fIxadder\fP\^, 
  492. .br
  493.                   \fIyadder\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
  494. .br
  495.       Display *\fIdisplay\fP\^;
  496. .br
  497.       int \fIscreen\fP\^;
  498. .br
  499.       char *\fIposition\fP\^, *\fIdefault_position\fP\^;    
  500. .br
  501.       unsigned int \fIbwidth\fP\^;
  502. .br
  503.       unsigned int \fIfwidth\fP\^, \fIfheight\fP\^;    
  504. .br
  505.       int \fIxadder\fP\^, \fIyadder\fP\^;    
  506. .br
  507.       int *\fIx_return\fP\^, *\fIy_return\fP\^;
  508. .br
  509.       int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
  510. .FN
  511. .IP \fIdisplay\fP 1i
  512. Specifies the connection to the X server.
  513. .IP \fIscreen\fP 1i
  514. Specifies the screen.
  515. .IP \fIposition\fP 1i
  516. .br
  517. .ns
  518. .IP \fIdefault_position\fP 1i
  519. Specify the geometry specifications.
  520. .IP \fIbwidth\fP 1i
  521. Specifies the border width.
  522. .IP \fIfheight\fP 1i
  523. .br
  524. .ns
  525. .IP \fIfwidth\fP 1i
  526. Specify the font height and width in pixels (increment size).
  527. .IP \fIxadder\fP 1i
  528. .br
  529. .ns
  530. .IP \fIyadder\fP 1i
  531. Specify additional interior padding needed in the window.
  532. .IP \fIx_return\fP 1i
  533. .br
  534. .ns
  535. .IP \fIy_return\fP 1i
  536. Return the x and y offsets.
  537. .IP \fIwidth_return\fP 1i
  538. .br
  539. .ns
  540. .IP \fIheight_return\fP 1i
  541. Return the width and height determined.
  542. .\" End marker code here
  543. .LP
  544. You pass in the border width (bwidth),
  545. size of the increments fwidth and fheight
  546. (typically font width and height),
  547. and any additional interior space (xadder and yadder)
  548. to make it easy to compute the resulting size.
  549. The
  550. .PN XGeometry 
  551. function returns the position the window should be placed given a position and
  552. a default position.
  553. .PN XGeometry
  554. determines the placement of
  555. a window using a geometry specification as specified by
  556. .PN XParseGeometry 
  557. and the additional information about the window.
  558. Given a fully qualified default geometry specification and
  559. an incomplete geometry specification, 
  560. .PN XParseGeometry
  561. returns a bitmask value as defined above in the 
  562. .PN XParseGeometry
  563. call,
  564. by using the position argument.
  565. .LP
  566. The returned width and height will be the width and height specified
  567. by default_position as overridden by any user-specified position.
  568. They are not affected by fwidth, fheight, xadder, or yadder.
  569. The x and y coordinates are computed by using the border width,
  570. the screen width and height, padding as specified by xadder and yadder,
  571. and the fheight and fwidth times the width and height from the
  572. geometry specifications.
  573. .SH
  574. Obtaining the X Environment Defaults
  575. .LP
  576. The
  577. .PN XGetDefault
  578. function provides a primitive interface to the resource manager facilities 
  579. discussed in chapter 15.
  580. It is only useful in very simple applications.
  581. .LP
  582. .sp
  583. .IN "XGetDefault" "" "@DEF@"
  584. .\" Start marker code here
  585. .FD 0
  586. .\" $Header: XGetDefault.f,v 1.1 88/02/26 10:00:26 mento Exp $
  587. char *XGetDefault\^(\^\fIdisplay\fP, \fIprogram\fP\^, \fIoption\fP\^)
  588. .br
  589.       Display *\fIdisplay\fP\^;
  590. .br
  591.       char *\fIprogram\fP\^;
  592. .br
  593.       char *\fIoption\fP\^;
  594. .FN
  595. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  596. .IP \fIdisplay\fP 1i
  597. Specifies the connection to the X server.
  598. .\" $Header: program.a,v 1.3 88/05/20 05:05:05 mento Exp $
  599. .IP \fIprogram\fP 1i
  600. Specifies the program name for the Xlib defaults (usually argv[0] 
  601. of the main program).
  602. .\" $Header: option.a,v 1.1 88/02/26 10:30:09 mento Exp $
  603. .IP \fIoption\fP 1i
  604. Specifies the option name.
  605. .\" End marker code here
  606. .LP
  607. .\" $Header: XGetDefault.d,v 1.3 88/08/20 10:10:09 mento Exp $
  608. The
  609. .PN XGetDefault
  610. function returns the value of the resource \fIprog\fP.\fIoption\fP,
  611. where \fIprog\fP is the program argument with the directory prefix removed
  612. and \fIoption\fP must be a single component.
  613. Note that multi-level resources cannot be used with
  614. .PN XGetDefault .
  615. The class "Program.Name" is always used for the resource lookup.
  616. If the specified option name does not exist for this program,
  617. .PN XGetDefault
  618. returns NULL.
  619. The strings returned by
  620. .PN XGetDefault
  621. are owned by Xlib and should not be modified or freed by the client.
  622. .LP
  623. If a database has been set with 
  624. .PN XrmSetDatabase , 
  625. that database is used for the lookup.
  626. Otherwise, a database is created as described below,
  627. and this is set in the display (as if by calling 
  628. .PN XrmSetDatabase ).
  629. The database is created in the current locale.
  630. To create a database,
  631. .PN XGetDefault
  632. uses resources from the RESOURCE_MANAGER property on the root
  633. window of screen zero.
  634. If no such property exists,
  635. a resource file in the user's home directory is used.
  636. On a POSIX-conformant system, 
  637. this file is
  638. .PN "$HOME/.Xdefaults" .
  639. .IN "Files" "$HOME/.Xdefaults"
  640. After loading these defaults,
  641. .PN XGetDefault
  642. merges additional defaults specified by the XENVIRONMENT
  643. environment variable.
  644. If XENVIRONMENT is defined,
  645. it contains a full path name for the additional resource file.
  646. If XENVIRONMENT is not defined,
  647. .PN XGetDefault
  648. looks for
  649. .PN "$HOME/.Xdefaults-\fIname\fP" ,
  650. where \fIname\fP specifies the name of the machine on which the application
  651. is running.
  652. .SH
  653. X Version 10 Compatibility Functions
  654. .LP
  655. You can use the X Version 10 compatibility functions to:
  656. .IP \(bu 5
  657. Draw and fill polygons and curves
  658. .IP \(bu 5
  659. Associate user data with a value
  660. .SH
  661. Drawing and Filling Polygons and Curves
  662. .LP
  663. Xlib provides functions that you can use to draw or fill
  664. arbitrary polygons or curves.  
  665. These functions are provided mainly for compatibility with X Version 10 
  666. and have no server support.  
  667. That is, they call other Xlib functions, not the server directly.  
  668. Thus, if you just have straight lines to draw, using 
  669. .PN XDrawLines 
  670. .IN "XDrawLines"
  671. or
  672. .PN XDrawSegments 
  673. .IN "XDrawSegments" 
  674. is much faster.
  675. .LP
  676. The functions discussed here provide all the functionality of the 
  677. X Version 10 functions 
  678. .PN XDraw , 
  679. .IN "X10 compatibility" "XDraw" 
  680. .PN XDrawFilled , 
  681. .IN "X10 compatibility" "XDrawFilled"
  682. .PN XDrawPatterned , 
  683. .IN "X10 compatibility" "XDrawPatterned" 
  684. .PN XDrawDashed , 
  685. .IN "X10 compatibility" "XDrawDashed"
  686. and
  687. .PN XDrawTiled .  
  688. .IN "X10 compatibility" "XDrawTiled"
  689. They are as compatible as possible given X Version 11's new line drawing 
  690. functions.  
  691. One thing to note, however, is that
  692. .PN VertexDrawLastPoint 
  693. is no longer supported. 
  694. Also, the error status returned is the opposite of what it was under 
  695. X Version 10 (this is the X Version 11 standard error status).  
  696. .PN XAppendVertex 
  697. and 
  698. .PN XClearVertexFlag 
  699. from X Version 10 also are not supported.
  700. .LP
  701. Just how the graphics context you use is set up actually
  702. determines whether you get dashes or not, and so on.  
  703. Lines are properly joined if they connect and include
  704. the closing of a closed figure  (see 
  705. .PN XDrawLines ).
  706. The functions discussed here fail (return zero) only if they run out of memory
  707. or are passed a 
  708. .PN Vertex 
  709. list that has a 
  710. .PN Vertex 
  711. with 
  712. .PN VertexStartClosed
  713. set that is not followed by a 
  714. .PN Vertex 
  715. with 
  716. .PN VertexEndClosed 
  717. set.
  718. .LP
  719. .sp
  720. To achieve the effects of the X Version 10
  721. .PN XDraw , 
  722. .IN "X10 compatibility" "XDraw" 
  723. .PN XDrawDashed , 
  724. .IN "X10 compatibility" "XDrawDashed"
  725. and 
  726. .PN XDrawPatterned , 
  727. .IN "X10 compatibility" "XDrawPatterned" 
  728. use
  729. .PN XDraw .  
  730. .IN "XDraw" "" "@DEF@" 
  731. .\" Start marker code here
  732. .FD 0
  733. #include <X11/X10.h>
  734.  
  735. Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
  736. .br
  737.     Display *\fIdisplay\fP\^;
  738. .br
  739.     Drawable \fId\fP\^;
  740. .br
  741.     GC \fIgc\fP\^;
  742. .br
  743.     Vertex *\fIvlist\fP\^;
  744. .br
  745.     int \fIvcount\fP\^;
  746. .FN
  747. .IP \fIdisplay\fP 1i
  748. Specifies the connection to the X server.
  749. .IP \fId\fP 1i
  750. Specifies the drawable. 
  751. .IP \fIgc\fP 1i
  752. Specifies the GC.
  753. .IP \fIvlist\fP 1i
  754. Specifies a pointer to the list of vertices that indicate what to draw.
  755. .IP \fIvcount\fP 1i
  756. Specifies how many vertices are in vlist.
  757. .\" End marker code here
  758. .LP
  759. .PN XDraw 
  760. draws an arbitrary polygon or curve.  
  761. The figure drawn is defined by the specified list of vertices (vlist).
  762. The points are connected by lines as specified in the flags in the
  763. vertex structure.
  764. .LP
  765. Each Vertex, as defined in
  766. .Pn < X11/X10.h >,
  767. is a structure with the following members:
  768. .LP
  769. .IN "Vertex" "" "@DEF@"
  770. .\" Start marker code here
  771. .Ds 0
  772. .TA .5i 1.5i
  773. .ta .5i 1.5i
  774. typedef struct _Vertex {
  775.     short x,y;
  776.     unsigned short flags;
  777. } Vertex;
  778. .De
  779. .\" End marker code here
  780. .LP
  781. The x and y members are the coordinates of the vertex 
  782. that are relative to either the upper-left inside corner of the drawable 
  783. (if 
  784. .PN VertexRelative 
  785. is zero) or the previous vertex (if 
  786. .PN VertexRelative 
  787. is one).
  788. .LP
  789. The flags, as defined in 
  790. .Pn < X11/X10.h >, 
  791. are as follows:
  792. .IN "VertexRelative" "" "@DEF@"
  793. .IN "VertexDontDraw" "" "@DEF@"
  794. .IN "VertexCurved" "" "@DEF@"
  795. .IN "VertexStartClosed" "" "@DEF@"
  796. .IN "VertexEndClosed" "" "@DEF@"
  797. .\" Start marker code here
  798. .TS
  799. l l l.
  800. T{
  801. .PN VertexRelative
  802. T}    T{
  803. 0x0001
  804. T}    T{
  805. /* else absolute */
  806. T}
  807. T{
  808. .PN VertexDontDraw
  809. T}    T{
  810. 0x0002
  811. T}    T{
  812. /* else draw */
  813. T}
  814. T{
  815. .PN VertexCurved
  816. T}    T{
  817. 0x0004
  818. T}    T{
  819. /* else straight */
  820. T}
  821. T{
  822. .PN VertexStartClosed
  823. T}    T{
  824. 0x0008
  825. T}    T{
  826. /* else not */
  827. T}
  828. T{
  829. .PN VertexEndClosed
  830. T}    T{
  831. 0x0010
  832. T}    T{
  833. /* else not */
  834. T}
  835. .TE
  836. .\" End marker code here
  837. .IP \(bu 5
  838. If 
  839. .PN VertexRelative 
  840. is not set,  
  841. the coordinates are absolute (that is, relative to the drawable's origin).  
  842. The first vertex must be an absolute vertex.
  843. .IP \(bu 5
  844. If
  845. .PN VertexDontDraw 
  846. is one, 
  847. no line or curve is drawn from the previous vertex to this one.  
  848. This is analogous to picking up the pen and moving to another place 
  849. before drawing another line.
  850. .IP \(bu 5
  851. If 
  852. .PN VertexCurved 
  853. is one, 
  854. a spline algorithm is used to draw a smooth curve from the previous vertex
  855. through this one to the next vertex.  
  856. Otherwise, a straight line is drawn from the previous vertex to this one.  
  857. It makes sense to set 
  858. .PN VertexCurved 
  859. to one only if a previous and next vertex are both defined
  860. (either explicitly in the array or through the definition of a closed 
  861. curve).
  862. .IP \(bu 5
  863. It is permissible for 
  864. .PN VertexDontDraw 
  865. bits and 
  866. .PN VertexCurved
  867. bits both to be one. 
  868. This is useful if you want to define the previous point for the smooth curve
  869. but do not want an actual curve drawing to start until this point.
  870. .IP \(bu 5
  871. If 
  872. .PN VertexStartClosed 
  873. is one, 
  874. then this point marks the beginning of a closed curve.  
  875. This vertex must be followed later in the array by another vertex 
  876. whose effective coordinates are identical
  877. and that has a
  878. .PN VertexEndClosed 
  879. bit of one.
  880. The points in between form a cycle to determine predecessor 
  881. and successor vertices for the spline algorithm.
  882. .LP
  883. This function uses these GC components:
  884. function, plane-mask, line-width, line-style, cap-style, join-style,
  885. fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
  886. clip-mask.
  887. It also uses these GC mode-dependent components: 
  888. foreground, background, tile, stipple,
  889. tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
  890. .LP
  891. .sp
  892. To achieve the effects of the X Version 10
  893. .PN XDrawTiled 
  894. .IN "X10 compatibility" "XDrawTiled"
  895. and 
  896. .PN XDrawFilled , 
  897. .IN "X10 compatibility" "XDrawFilled"
  898. use
  899. .PN XDrawFilled .
  900. .IN "XDrawFilled" "" "@DEF@"
  901. .\" Start marker code here
  902. .FD 0
  903. #include <X11/X10.h>
  904.  
  905. Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
  906. .br
  907.     Display *\fIdisplay\fP\^;
  908. .br
  909.     Drawable \fId\fP\^;
  910. .br
  911.     GC \fIgc\fP\^;
  912. .br
  913.     Vertex *\fIvlist\fP\^;
  914. .br
  915.     int \fIvcount\fP\^;
  916. .FN
  917. .IP \fIdisplay\fP 1i
  918. Specifies the connection to the X server.
  919. .IP \fId\fP 1i
  920. Specifies the drawable. 
  921. .IP \fIgc\fP 1i
  922. Specifies the GC.
  923. .IP \fIvlist\fP 1i
  924. Specifies a pointer to the list of vertices that indicate what to draw.
  925. .IP \fIvcount\fP 1i
  926. Specifies how many vertices are in vlist.
  927. .\" End marker code here
  928. .LP
  929. .PN XDrawFilled 
  930. draws arbitrary polygons or curves and then fills them.
  931. .LP
  932. This function uses these GC components:
  933. function, plane-mask, line-width, line-style, cap-style, join-style,
  934. fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
  935. clip-mask.
  936. It also uses these GC mode-dependent components: 
  937. foreground, background, tile, stipple,
  938. tile-stipple-x-origin, tile-stipple-y-origin, 
  939. dash-offset, dash-list, fill-style, and fill-rule.
  940. .SH
  941. Associating User Data with a Value
  942. .LP
  943. These functions have been superseded by the context management functions
  944. (see section 16.10). 
  945. It is often necessary to associate arbitrary information with resource IDs.
  946. Xlib provides the 
  947. .PN XAssocTable 
  948. functions that you can use to make such an association.
  949. .IN "Hash Lookup"
  950. .IN "Window" "IDs"
  951. .IN "Resource IDs"
  952. Application programs often need to be able to easily refer to
  953. their own data structures when an event arrives.
  954. The 
  955. .PN XAssocTable
  956. system provides users of the X library with a method
  957. for associating their own data structures with X resources
  958. .Pn ( Pixmaps , 
  959. .PN Fonts , 
  960. .PN Windows , 
  961. and so on).
  962. .LP
  963. An 
  964. .PN XAssocTable
  965. can be used to type X resources.  
  966. For example, the user
  967. may want to have three or four types of windows,
  968. each with different properties. 
  969. This can be accomplished by associating each X window ID
  970. with a pointer to a window property data structure  defined  by  the
  971. user.
  972. A generic type has been defined in the X library for resource IDs.
  973. It is called an XID.
  974. .LP
  975. There are a few  guidelines  that  should be observed when using an
  976. .PN XAssocTable :
  977. .IP \(bu 5
  978. All  XIDs  are  relative  to  the  specified display.
  979. .IP \(bu 5
  980. Because  of  the  hashing  scheme  used  by  the  association mechanism,
  981. the following rules for determining the size of a
  982. .PN XAssocTable
  983. should be followed.  
  984. Associations will be  made  and  looked  up  more
  985. efficiently  if  the  table  size  (number  of  buckets in the hashing
  986. system) is a power of two and if there are not more than 8 XIDs  per
  987. bucket.
  988. .LP
  989. .sp
  990. To return a pointer to a new
  991. .PN XAssocTable , 
  992. use 
  993. .PN XCreateAssocTable .
  994. .IN "XCreateAssocTable" "" "@DEF@"
  995. .\" Start marker code here
  996. .FD 0
  997. XAssocTable *XCreateAssocTable\^(\^\fIsize\fP\^)
  998. .br
  999.       int \fIsize\fP\^;    
  1000. .FN
  1001. .IP \fIsize\fP 1i
  1002. Specifies the number of buckets in the hash system of
  1003. .PN XAssocTable .
  1004. .\" End marker code here
  1005. .LP
  1006. The size argument specifies the number of buckets in the 
  1007. hash system of
  1008. .PN XAssocTable .
  1009. For  reasons  of  efficiency  the number of buckets
  1010. should be a power of two.
  1011. Some size  suggestions  might  be:  use  32 buckets  per  100  objects,
  1012. and a reasonable maximum number of objects per buckets is 8.
  1013. If  an  error  allocating  memory  for  the
  1014. .PN XAssocTable 
  1015. occurs, 
  1016. a NULL pointer is returned. 
  1017. .LP
  1018. .sp
  1019. To create an entry in a given 
  1020. .PN XAssocTable ,
  1021. use 
  1022. .PN XMakeAssoc .
  1023. .IN "XMakeAssoc" "" "@DEF@"
  1024. .\" Start marker code here
  1025. .FD 0
  1026. XMakeAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^, \fIdata\fP\^)
  1027. .br
  1028.       Display *\fIdisplay\fP\^;
  1029. .br
  1030.       XAssocTable *\fItable\fP\^;    
  1031. .br
  1032.       XID \fIx_id\fP\^;
  1033. .br
  1034.       char *\fIdata\fP\^;
  1035. .FN
  1036. .IP \fIdisplay\fP 1i
  1037. Specifies the connection to the X server.
  1038. .IP \fItable\fP 1i
  1039. Specifies the assoc table. 
  1040. .IP \fIx_id\fP 1i
  1041. Specifies the X resource ID.
  1042. .IP \fIdata\fP 1i
  1043. Specifies the data to be associated with the X resource ID.
  1044. .\" End marker code here
  1045. .LP
  1046. .PN XMakeAssoc
  1047. inserts data into an 
  1048. .PN XAssocTable
  1049. keyed  on  an  XID.
  1050. Data  is inserted  into the table only once.
  1051. Redundant inserts are ignored.
  1052. The queue in each association bucket is sorted from the lowest XID to 
  1053. the highest XID.
  1054. .LP
  1055. .sp
  1056. To obtain data from a given 
  1057. .PN XAssocTable ,
  1058. use 
  1059. .PN XLookUpAssoc .
  1060. .IN "XLookUpAssoc" "" "@DEF@"
  1061. .\" Start marker code here
  1062. .FD 0
  1063. char *XLookUpAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
  1064. .br
  1065.       Display *\fIdisplay\fP\^;
  1066. .br
  1067.       XAssocTable *\fItable\fP\^;
  1068. .br
  1069.       XID \fIx_id\fP\^;
  1070. .FN
  1071. .IP \fIdisplay\fP 1i
  1072. Specifies the connection to the X server.
  1073. .IP \fItable\fP 1i
  1074. Specifies the assoc table. 
  1075. .IP \fIx_id\fP 1i
  1076. Specifies the X resource ID.
  1077. .\" End marker code here
  1078. .LP
  1079. .PN XLookUpAssoc
  1080. retrieves the data stored in an 
  1081. .PN XAssocTable
  1082. by its XID.  
  1083. If  an appropriately  matching XID can be found in the table,
  1084. .PN XLookUpAssoc
  1085. returns the data associated with it.
  1086. If the x_id cannot be found in the table,
  1087. it returns NULL.
  1088. .LP
  1089. .sp
  1090. To delete an entry from a given 
  1091. .PN XAssocTable ,
  1092. use 
  1093. .PN XDeleteAssoc .
  1094. .IN "XDeleteAssoc" "" "@DEF@"
  1095. .\" Start marker code here
  1096. .FD 0
  1097. XDeleteAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
  1098. .br
  1099.       Display *\fIdisplay\fP\^;
  1100. .br
  1101.       XAssocTable *\fItable\fP\^;
  1102. .br
  1103.       XID \fIx_id\fP\^;
  1104. .FN
  1105. .IP \fIdisplay\fP 1i
  1106. Specifies the connection to the X server.
  1107. .IP \fItable\fP 1i
  1108. Specifies the assoc table. 
  1109. .IP \fIx_id\fP 1i
  1110. Specifies the X resource ID.
  1111. .\" End marker code here
  1112. .LP
  1113. .PN XDeleteAssoc
  1114. deletes an association in an 
  1115. .PN XAssocTable
  1116. keyed on its XID.
  1117. Redundant deletes (and deletes of nonexistent XIDs) are ignored.
  1118. Deleting associations in no way impairs the performance of an 
  1119. .PN XAssocTable .
  1120. .LP
  1121. .sp
  1122. To free the memory associated with a given 
  1123. .PN XAssocTable ,
  1124. use 
  1125. .PN XDestroyAssocTable .
  1126. .IN "XDestroyAssocTable" "" "@DEF@"
  1127. .\" Start marker code here
  1128. .FD 0
  1129. XDestroyAssocTable\^(\^\fItable\fP\^)
  1130. .br
  1131.       XAssocTable *\fItable\fP\^;
  1132. .FN
  1133. .IP \fItable\fP 1i
  1134. Specifies the assoc table. 
  1135. .\" End marker code here
  1136. .bp
  1137.