home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH16 < prev    next >
Encoding:
Text File  |  1991-08-27  |  61.3 KB  |  2,345 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 16\fP\s-1
  5.  
  6. \s+1\fBApplication Utility Functions\fP\s-1
  7. .sp 2
  8. .nr H1 16
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 16: Application Utility Functions 
  17. .XE
  18. Once you have initialized the X system,
  19. you can use the Xlib utility functions to:
  20. .IP \(bu 5
  21. Obtain and classify KeySyms
  22. .IP \(bu 5
  23. Allocate permanent storage
  24. .IP \(bu 5
  25. Parse window geometry strings
  26. .IP \(bu 5
  27. Manipulate regions
  28. .IP \(bu 5
  29. Use cut buffers
  30. .IP \(bu 5
  31. Determine the appropriate visual 
  32. .IP \(bu 5
  33. Manipulate images
  34. .IP \(bu 5
  35. Manipulate bitmaps
  36. .IP \(bu 5
  37. Use the context manager
  38. .RE
  39. As a group,
  40. the functions discussed in this chapter provide the functionality that 
  41. is frequently needed and that spans toolkits.
  42. Many of these functions do not generate actual protocol requests to the server.
  43. .NH 2
  44. Keyboard Utility Functions
  45. .XS
  46. \*(SN Keyboard Utility Functions 
  47. .XE
  48. .LP
  49. This section discusses mapping between KeyCodes and KeySyms,
  50. names for KeySyms, and KeySym classification macros.
  51. The functions in this section operate on an cached copy of the
  52. server keyboard mapping.  The first four KeySyms for each key code
  53. are modified according to the rules given in section 12.7.
  54. If you want the untransformed KeySyms defined for a key,
  55. you should only use the functions described in section 12.7.
  56. .LP
  57. .sp
  58. To obtain a KeySym for the key code of an event, use
  59. .PN XLookupKeysym .
  60. .IN "XLookupKeysym" "" "@DEF@"
  61. .\" Start marker code here
  62. .FD 0
  63. KeySym XLookupKeysym(\^\fIkey_event\fP, \fIindex\fP\^)
  64. .br
  65.       XKeyEvent *\fIkey_event\fP\^;
  66. .br
  67.       int \fIindex\fP\^;
  68. .FN
  69. .IP \fIkey_event\fP 1i
  70. Specifies the 
  71. .PN KeyPress
  72. or
  73. .PN KeyRelease
  74. event.
  75. .IP \fIindex\fP 1i
  76. Specifies the index into the KeySyms list for the event's KeyCode.
  77. .\" End marker code here
  78. .LP
  79. .\" $Header: XLKeysym.d,v 1.3 88/04/07 15:54:30 mento Exp $
  80. The
  81. .PN XLookupKeysym
  82. function uses a given keyboard event and the index you specified to return
  83. the KeySym from the list that corresponds to the KeyCode member in the
  84. .PN XKeyPressedEvent
  85. or
  86. .PN XKeyReleasedEvent
  87. structure.
  88. If no KeySym is defined for the KeyCode of the event,
  89. .PN XLookupKeysym
  90. returns
  91. .PN NoSymbol .
  92. .LP
  93. .sp
  94. To obtain a KeySym for a specific key code, use
  95. .PN XKeycodeToKeysym .
  96. .IN "XKeycodeToKeysym" "" "@DEF@"
  97. .\" Start marker code here
  98. .FD 0
  99. KeySym XKeycodeToKeysym\^(\^\fIdisplay\fP, \fIkeycode\fP, \fIindex\fP\^)
  100. .br
  101.       Display *\fIdisplay\fP\^;
  102. .br
  103.       KeyCode \fIkeycode\fP\^;
  104. .br
  105.       int \fIindex\fP\^;
  106. .FN
  107. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  108. .IP \fIdisplay\fP 1i
  109. Specifies the connection to the X server.
  110. .\" $Header: keycode.a,v 1.2 88/04/06 17:41:50 mento Exp $
  111. .IP \fIkeycode\fP 1i
  112. Specifies the KeyCode.
  113. .IP \fIindex\fP 1i
  114. Specifies the element of KeyCode vector.
  115. .\" End marker code here
  116. .LP
  117. .\" $Header: XKTKeysym.d,v 1.4 88/08/20 10:08:36 mento Exp $
  118. The
  119. .PN XKeycodeToKeysym
  120. function uses internal Xlib tables
  121. and returns the KeySym defined for the specified KeyCode and
  122. the element of the KeyCode vector.
  123. If no symbol is defined,
  124. .PN XKeycodeToKeysym
  125. returns
  126. .PN NoSymbol .
  127. .LP
  128. .sp
  129. To obtain a key code for a key having a specific KeySym, use
  130. .PN XKeysymToKeycode .
  131. .IN "XKeysymToKeycode" "" "@DEF@"
  132. .\" Start marker code here
  133. .FD 0
  134. KeyCode XKeysymToKeycode\^(\^\fIdisplay\fP, \fIkeysym\fP\^)
  135. .br
  136.       Display *\fIdisplay\fP\^;
  137. .br
  138.       KeySym \fIkeysym\fP\^;
  139. .FN
  140. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  141. .IP \fIdisplay\fP 1i
  142. Specifies the connection to the X server.
  143. .IP \fIkeysym\fP 1i
  144. Specifies the KeySym that is to be searched for.
  145. .\" End marker code here
  146. .LP
  147. .\" $Header: XKTKeycode.d,v 1.4 88/06/11 07:51:42 mento Exp $
  148. If the specified KeySym is not defined for any KeyCode,
  149. .PN XKeysymToKeycode
  150. returns zero.
  151. .LP
  152. .sp
  153. The mapping between key codes and KeySyms is cached internal to Xlib.
  154. When this information is changed at the server, an Xlib function must
  155. be called to refresh the cache.
  156. To refresh the stored modifier and keymap information, use
  157. .PN XRefreshKeyboardMapping .
  158. .IN "XRefreshKeyboardMapping" "" "@DEF@"
  159. .\" Start marker code here
  160. .FD 0
  161. XRefreshKeyboardMapping(\^\fIevent_map\fP\^)
  162. .br
  163.       XMappingEvent *\fIevent_map\fP\^;
  164. .FN
  165. .IP \fIevent_map\fP 1i
  166. Specifies the mapping event that is to be used.
  167. .\" End marker code here
  168. .LP
  169. .\" $Header: XRKMap.d,v 1.2 88/06/11 07:52:44 mento Exp $
  170. The
  171. .PN XRefreshKeyboardMapping
  172. function refreshes the stored modifier and keymap information.
  173. You usually call this function when a
  174. .PN MappingNotify
  175. event with a request member of
  176. .PN MappingKeyboard
  177. or
  178. .PN MappingModifier
  179. occurs.
  180. The result is to update Xlib's knowledge of the keyboard.
  181. .LP
  182. .sp
  183. KeySyms have string names as well as numeric codes.
  184. To convert the name of the KeySym to the KeySym code, use
  185. .PN XStringToKeysym .
  186. .IN "XStringToKeysym" "" "@DEF@"
  187. .\" Start marker code here
  188. .FD 0
  189. KeySym XStringToKeysym\^(\^\fIstring\fP\^)
  190. .br
  191.       char *\fIstring\fP\^;
  192. .FN
  193. .IP \fIstring\fP 1i
  194. Specifies the name of the KeySym that is to be converted.
  195. .\" End marker code here
  196. .LP
  197. .\" $Header: XSTKeysym.d,v 1.3 88/06/11 07:52:54 mento Exp $
  198. Standard KeySym names are obtained from
  199. .Pn < X11/keysymdef.h >
  200. by removing the XK_ prefix from each name.
  201. KeySyms that are not part of the Xlib standard also may be obtained
  202. with this function.
  203. Note that the set of KeySysms that are available in this manner 
  204. and the mechanisms by which Xlib obtains them is implementation dependent.
  205. .LP
  206. If the keysym name is not in the Host Portable Character Encoding
  207. the result is implementation dependent.
  208. If the specified string does not match a valid KeySym,
  209. .PN XStringToKeysym
  210. returns
  211. .PN NoSymbol .
  212. .LP
  213. .sp
  214. To convert a KeySym code to the name of the KeySym, use
  215. .PN XKeysymToString .
  216. .IN "XKeysymToString" "" "@DEF@"
  217. .\" Start marker code here
  218. .FD 0
  219. char *XKeysymToString\^(\^\fIkeysym\fP\^)
  220. .br
  221.       KeySym \fIkeysym\fP\^;
  222. .FN
  223. .ds Fn converted
  224. .IP \fIkeysym\fP 1i
  225. Specifies the KeySym that is to be \*(Fn.
  226. .\" End marker code here
  227. .LP
  228. .\" $Header: XKTString.d,v 1.3 88/06/11 07:51:44 mento Exp $
  229. The returned string is in a static area and must not be modified.
  230. The returned string is in the Host Portable Character Encoding.
  231. If the specified KeySym is not defined,
  232. .PN XKeysymToString
  233. returns a NULL.
  234. .NH 3
  235. Keysym Classification Macros
  236. .XS
  237. \*(SN Keysym Classification Macros 
  238. .XE
  239. .LP
  240. You may want to test if a KeySym is, for example, 
  241. on the keypad or on one of the function keys.
  242. You can use the KeySym macros to perform the following tests.
  243. .LP
  244. .sp
  245. .\" Start marker code here
  246. .FD 0
  247. IsCursorKey\^(\^\fIkeysym\fP\^)
  248. .FN
  249. .ds Fn tested
  250. .IP \fIkeysym\fP 1i
  251. Specifies the KeySym that is to be \*(Fn.
  252. .\" End marker code here
  253. .IN "IsCursorKey" "" "@DEF@"
  254. .LP
  255. Returns
  256. .PN True
  257. if the specified KeySym is a cursor key.
  258. .LP
  259. .sp
  260. .\" Start marker code here
  261. .FD 0
  262. IsFunctionKey\^(\^\fIkeysym\fP\^)
  263. .FN
  264. .ds Fn tested
  265. .IP \fIkeysym\fP 1i
  266. Specifies the KeySym that is to be \*(Fn.
  267. .\" End marker code here
  268. .IN "IsFunctionKey" "" "@DEF@"
  269. .LP
  270. Returns 
  271. .PN True
  272. if the specified KeySym is a function key.
  273. .LP
  274. .sp
  275. .\" Start marker code here
  276. .FD 0
  277. IsKeypadKey\^(\^\fIkeysym\fP\^)
  278. .FN
  279. .ds Fn tested
  280. .IP \fIkeysym\fP 1i
  281. Specifies the KeySym that is to be \*(Fn.
  282. .\" End marker code here
  283. .IN "IsKeypadKey" "" "@DEF@"
  284. .LP
  285. Returns
  286. .PN True
  287. if the specified KeySym is a keypad key.
  288. .LP
  289. .sp
  290. .\" Start marker code here
  291. .FD 0
  292. IsMiscFunctionKey\^(\^\fIkeysym\fP\^)
  293. .FN
  294. .ds Fn tested
  295. .IP \fIkeysym\fP 1i
  296. Specifies the KeySym that is to be \*(Fn.
  297. .\" End marker code here
  298. .IN "IsMiscFunctionKey" "" "@DEF@"
  299. .LP
  300. Returns 
  301. .PN True
  302. if the specified KeySym is a miscellaneous function key.
  303. .LP
  304. .sp
  305. .\" Start marker code here
  306. .FD 0
  307. IsModifierKey\^(\^\fIkeysym\fP\^)
  308. .FN
  309. .ds Fn tested
  310. .IP \fIkeysym\fP 1i
  311. Specifies the KeySym that is to be \*(Fn.
  312. .\" End marker code here
  313. .IN "IsModifierKey" "" "@DEF@"
  314. .LP
  315. Returns 
  316. .PN True
  317. if the specified KeySym is a modifier key.
  318. .LP
  319. .sp
  320. .\" Start marker code here
  321. .FD 0
  322. IsPFKey\^(\^\fIkeysym\fP\^)
  323. .FN
  324. .ds Fn tested
  325. .IP \fIkeysym\fP 1i
  326. Specifies the KeySym that is to be \*(Fn.
  327. .\" End marker code here
  328. .IN "IsPFKey" "" "@DEF@"
  329. .LP
  330. Returns 
  331. .PN True
  332. if the specified KeySym is a PF key.
  333. .NH 2
  334. Latin-1 Keyboard Event Functions
  335. .XS
  336. \*(SN Latin-1 Keyboard Event Functions 
  337. .XE
  338. .LP
  339. Chapter 13 describes internationalized text input facilities,
  340. but sometimes it is expedient to write an application that
  341. only deals with Latin-1 characters and ASCII controls,
  342. so Xlib provides a simple function for that purpose.
  343. .PN XLookupString
  344. handles the standard modifier semantics described in section 12.7.
  345. This function does not use any of the input method facilities
  346. described in chapter 13, and does not depend on the current locale.
  347. .LP
  348. .sp
  349. To map a key event to an ISO Latin-1 string, use
  350. .PN XLookupString .
  351. .IN "XLookupString" "" "@DEF@"
  352. .\" Start marker code here
  353. .FD 0
  354. int XLookupString(\^\fIevent_struct\fP, \fIbuffer_return\fP,\
  355.  \fIbytes_buffer\fP, \fIkeysym_return\fP, \fIstatus_in_out\fP\^)
  356. .br
  357.       XKeyEvent *\fIevent_struct\fP\^;
  358. .br
  359.       char *\fIbuffer_return\fP\^;
  360. .br
  361.       int \fIbytes_buffer\fP\^;
  362. .br
  363.       KeySym *\fIkeysym_return\fP\^;
  364. .br
  365.       XComposeStatus *\fIstatus_in_out\fP\^;
  366. .FN
  367. .IP \fIevent_struct\fP 1i
  368. Specifies the key event structure to be used.
  369. You can pass
  370. .PN XKeyPressedEvent
  371. or
  372. .PN XKeyReleasedEvent .
  373. .IP \fIbuffer_return\fP 1i
  374. Returns the translated characters.
  375. .IP \fIbytes_buffer\fP 1i
  376. Specifies the length of the buffer.
  377. No more than bytes_buffer of translation are returned.
  378. .IP \fIkeysym_return\fP 1i
  379. Returns the KeySym computed from the event if this argument is not NULL.
  380. .IP \fIstatus_in_out\fP 1i
  381. Specifies or returns the 
  382. .PN XComposeStatus 
  383. structure or NULL.
  384. .\" End marker code here
  385. .LP
  386. .\" $Header: XLookStr.d,v 1.4 88/08/20 10:08:02 mento Exp $
  387. The
  388. .PN XLookupString
  389. function translates a key event to a KeySym and a string.
  390. The KeySym is obtained by using the standard interpretation of the Shift,
  391. Lock, and group modifiers as defined in the X Protocol specification.
  392. If the KeySym has been rebound (see
  393. .PN XRebindKeysym ),
  394. the bound string will be stored in the buffer.
  395. Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
  396. or (if the Control modifier is on) to an ASCII control character,
  397. and that character is stored in the buffer.
  398. .PN XLookupString
  399. returns the number of characters that are stored in the buffer.
  400. .LP
  401. If present (non-NULL),
  402. the
  403. .PN XComposeStatus
  404. structure records the state,
  405. which is private to Xlib,
  406. that needs preservation across calls to
  407. .PN XLookupString
  408. to implement compose processing.
  409. The creation of
  410. .PN XComposeStatus
  411. structures is implementation dependent;
  412. a portable program must pass NULL for this argument.
  413. .LP
  414. .PN XLookupString
  415. depends on the cached keyboard information mentioned in the
  416. previous section, so it is necessary to use
  417. .PN XRefreshKeyboardMapping
  418. to keep this information up to date.
  419. .LP
  420. .sp
  421. To rebind the meaning of a KeySym for
  422. .PN XLookupString ,
  423. use
  424. .PN XRebindKeysym .
  425. .IN "XRebindKeysym" "" "@DEF@"
  426. .\" Start marker code here
  427. .FD 0
  428. XRebindKeysym(\^\fIdisplay\fP, \fIkeysym\fP, \fIlist\fP, \fImod_count\fP, \fIstring\fP, \fInum_bytes\fP\^)
  429. .br
  430.       Display *\fIdisplay\fP\^;
  431. .br
  432.       KeySym \fIkeysym\fP\^;
  433. .br
  434.       KeySym \fIlist\fP\^[\^]\^;
  435. .br
  436.       int \fImod_count\fP\^;
  437. .br
  438.       unsigned char *\fIstring\fP\^;
  439. .br
  440.       int \fInum_bytes\fP\^;
  441. .FN
  442. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  443. .IP \fIdisplay\fP 1i
  444. Specifies the connection to the X server.
  445. .ds Fn rebound
  446. .IP \fIkeysym\fP 1i
  447. Specifies the KeySym that is to be \*(Fn.
  448. .IP \fIlist\fP 1i
  449. Specifies the KeySyms to be used as modifiers.
  450. .IP \fImod_count\fP 1i
  451. Specifies the number of modifiers in the modifier list.
  452. .IP \fIstring\fP 1i
  453. Specifies the string that is copied and will be returned by 
  454. .PN XLookupString .
  455. .IP \fInum_bytes\fP 1i
  456. Specifies the number of bytes in the string argument.
  457. .\" End marker code here
  458. .LP
  459. .\" $Header: XRKeySym.d,v 1.3 88/06/11 07:52:44 mento Exp $
  460. The
  461. .PN XRebindKeysym
  462. function can be used to rebind the meaning of a KeySym for the client.
  463. It does not redefine any key in the X server but merely
  464. provides an easy way for long strings to be attached to keys.
  465. .PN XLookupString
  466. returns this string when the appropriate set of
  467. modifier keys are pressed and when the KeySym would have been used for
  468. the translation.
  469. No text conversions are performed;
  470. the client is responsible for supplying appropriately encoded strings.
  471. Note that you can rebind a KeySym that may not exist.
  472. .NH 2
  473. Allocating Permanent Storage
  474. .XS
  475. \*(SN Allocating Permanent Storage
  476. .XE
  477. .LP
  478. To allocate some memory you will never give back, use
  479. .PN Xpermalloc .
  480. .IN "Xpermalloc" "" "@DEF@"
  481. .\" Start marker code here
  482. .FD 0
  483. char *Xpermalloc\^(\^\fIsize\fP\^)
  484. .br
  485.      unsigned int \fIsize\fP\^;
  486. .FN
  487. .\" End marker code here
  488. .LP
  489. The
  490. .PN Xpermalloc
  491. function allocates storage that can never be freed for the life of the
  492. program.  The memory is allocated with alignment for the C type double.
  493. This function may provide some performance and space savings over
  494. the standard operating system memory allocator.
  495. .NH 2
  496. Parsing the Window Geometry
  497. .XS
  498. \*(SN Parsing the Window Geometry 
  499. .XE
  500. .LP
  501. To parse standard window geometry strings, use
  502. .PN XParseGeometry .
  503. .IN "Window" "determining location"
  504. .IN "XParseGeometry" "" "@DEF@"
  505. .LP
  506. .\" Start marker code here
  507. .FD 0
  508. .\" $Header: XParseGeom.f,v 1.1 88/02/26 10:01:42 mento Exp $
  509. int XParseGeometry\^(\^\fIparsestring\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
  510. .br
  511.       char *\fIparsestring\fP\^;
  512. .br
  513.       int *\fIx_return\fP\^, *\fIy_return\fP\^; 
  514. .br
  515.       unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
  516. .FN
  517. .\" $Header: parsestring.a,v 1.1 88/02/26 10:30:19 mento Exp $
  518. .IP \fIparsestring\fP 1i
  519. Specifies the string you want to parse.
  520. .\" $Header: xy_ret.a,v 1.3 88/05/20 05:05:44 mento Exp $
  521. .IP \fIx_return\fP 1i
  522. .br
  523. .ns
  524. .IP \fIy_return\fP 1i
  525. Return the x and y offsets.
  526. .\" $Header: widtheight2.a,v 1.1 88/02/26 10:32:28 mento Exp $
  527. .IP \fIwidth_return\fP 1i
  528. .br
  529. .ns
  530. .IP \fIheight_return\fP 1i
  531. Return the width and height determined.
  532. .\" End marker code here
  533. .LP
  534. .\" $Header: XParseGeom.d,v 1.3 88/08/20 10:15:39 mento Exp $
  535. By convention,
  536. X applications use a standard string to indicate window size and placement.
  537. .PN XParseGeometry
  538. makes it easier to conform to this standard because it allows you
  539. to parse the standard window geometry.
  540. Specifically, this function lets you parse strings of the form:
  541. .LP
  542. .Ds
  543. [=][<\fIwidth\fP>{xX}<\fIheight\fP>][{+-}<\fIxoffset\fP>{+-}<\fIyoffset\fP>] 
  544. .De
  545. .LP
  546. The fields map into the arguments associated with this function.
  547. (Items enclosed in <\^> are integers, items in [\^] are optional, and
  548. items enclosed in {\^} indicate ``choose one of.''
  549. Note that the brackets should not appear in the actual string.)
  550. If the string is not in the Host Portable Character Encoding
  551. the result is implementation dependent.
  552. .LP
  553. The
  554. .PN XParseGeometry
  555. function returns a bitmask that indicates which of the four values (width,
  556. height, xoffset, and yoffset) were actually found in the string 
  557. and whether the x and y values are negative. 
  558. By convention, \-0 is not equal to +0, because the user needs to
  559. be able to say ``position the window relative to the right or bottom edge.''
  560. For each value found, the corresponding argument is updated.
  561. For each value not found, the argument is left unchanged.
  562. The bits are represented by
  563. .PN XValue , 
  564. .PN YValue , 
  565. .PN WidthValue , 
  566. .PN HeightValue ,
  567. .PN XNegative , 
  568. or
  569. .PN YNegative
  570. and are defined in 
  571. .Pn < X11/Xutil.h >.
  572. They will be set whenever one of the values is defined 
  573. or one of the signs is set.
  574. .LP
  575. If the function returns either the 
  576. .PN XValue 
  577. or 
  578. .PN YValue 
  579. flag,
  580. you should place the window at the requested position.
  581. .sp
  582. .LP
  583. To construct a window's geometry information, use
  584. .PN XWMGeometry .
  585. .IN "XWMGeometry" "" "@DEF@"
  586. .\" Start marker code here
  587. .FD 0
  588. int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \
  589. \fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP,
  590. .br
  591.                 \fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^)
  592. .br
  593.       Display *\fIdisplay\fP\^;
  594. .br
  595.       int \fIscreen\fP\^;
  596. .br
  597.       char *\fIuser_geom\fP\^;
  598. .br
  599.       char *\fIdef_geom\fP\^;
  600. .br
  601.       unsigned int \fIbwidth\fP\^;
  602. .br
  603.       XSizeHints *\fIhints\fP\^;
  604. .br
  605.       int *\fIx_return\fP, *\fIy_return\fP\^; 
  606. .br
  607.       int *\fIwidth_return\fP\^;
  608. .br
  609.       int *\fIheight_return\fP\^;
  610. .br
  611.       int *\fIgravity_return\fP\^;
  612. .FN
  613. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  614. .IP \fIdisplay\fP 1i
  615. Specifies the connection to the X server.
  616. .IP \fIscreen\fP 1i
  617. Specifies the screen.
  618. .IP \fIuser_geom\fP 1i
  619. Specifies the user-specified geometry or NULL.
  620. .IP \fIdef_geom\fP 1i
  621. Specifies the application's default geometry or NULL.
  622. .\" $Header: bwidth.a,v 1.1 88/02/26 10:05:23 mento Exp $
  623. .IP \fIbwidth\fP 1i
  624. Specifies the border width.
  625. .IP \fIhints\fP 1i
  626. Specifies the size hints for the window in its normal state.
  627. .\" $Header: xy_ret.a,v 1.3 88/05/20 05:05:44 mento Exp $
  628. .IP \fIx_return\fP 1i
  629. .br
  630. .ns
  631. .IP \fIy_return\fP 1i
  632. Return the x and y offsets.
  633. .\" $Header: widtheight2.a,v 1.1 88/02/26 10:32:28 mento Exp $
  634. .IP \fIwidth_return\fP 1i
  635. .br
  636. .ns
  637. .IP \fIheight_return\fP 1i
  638. Return the width and height determined.
  639. .IP \fIgravity_return\fP 1i
  640. Returns the window gravity.
  641. .\" End marker code here
  642. .LP
  643. The 
  644. .PN XWMGeometry 
  645. function combines any geometry information (given in the format used by 
  646. .PN XParseGeometry )
  647. specified by the user and by the calling program with size hints 
  648. (usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, 
  649. size, and gravity
  650. .Pn ( NorthWestGravity , 
  651. .PN NorthEastGravity , 
  652. .PN SouthEastGravity ,
  653. or
  654. .PN SouthWestGravity ) 
  655. that describe the window.
  656. If the base size is not set in the 
  657. .PN XSizeHints
  658. structure, 
  659. the minimum size is used if set.
  660. Otherwise, a base size of zero is assumed.
  661. If no minimum size is set in the hints structure, 
  662. the base size is used.
  663. A mask (in the form returned by 
  664. .PN XParseGeometry ) 
  665. that describes which values came from the user specification 
  666. and whether or not the position coordinates are relative
  667. to the right and bottom edges is returned.
  668. Note that these coordinates will have already been accounted for 
  669. in the x_return and y_return values.
  670. .LP
  671. Note that invalid geometry specifications can cause a width or height 
  672. of zero to be returned.
  673. The caller may pass the address of the hints win_gravity field 
  674. as gravity_return to update the hints directly.
  675. .NH 2
  676. Manipulating Regions
  677. .XS
  678. \*(SN Manipulating Regions 
  679. .XE
  680. .LP
  681. Regions are arbitrary sets of pixel locations.
  682. Xlib provides functions for manipulating regions.
  683. The opaque type 
  684. .PN Region
  685. is defined in 
  686. .Pn < X11/Xutil.h >.
  687. Xlib provides functions that you can use to manipulate regions.
  688. This section discusses how to:
  689. .IP \(bu 5
  690. Create, copy, or destroy regions
  691. .IP \(bu 5
  692. Move or shrink regions
  693. .IP \(bu 5
  694. Compute with regions
  695. .IP \(bu 5
  696. Determine if regions are empty or equal
  697. .IP \(bu 5
  698. Locate a point or rectangle in a region
  699. .LE
  700. .NH 3
  701. Creating, Copying, or Destroying Regions
  702. .XS
  703. \*(SN Creating, Copying, or Destroying Regions 
  704. .XE
  705. .LP
  706. To create a new empty region, use
  707. .PN XCreateRegion .
  708. .IN "XCreateRegion" "" "@DEF@"
  709. .\" Start marker code here
  710. .FD 0
  711. .\" $Header: XCreRegion.f,v 1.1 88/02/26 09:59:13 mento Exp $
  712. Region XCreateRegion\^()
  713. .FN
  714. .\" End marker code here
  715. .LP
  716. .sp
  717. To generate a region from a polygon, use
  718. .PN XPolygonRegion .
  719. .IN "XPolygonRegion" "" "@DEF@"
  720. .\" Start marker code here
  721. .FD 0
  722. .\" $Header: XPolyRegion.f,v 1.1 88/02/26 10:01:56 mento Exp $
  723. Region XPolygonRegion\^(\^\fIpoints\fP\^, \fIn\fP\^, \fIfill_rule\fP\^)
  724. .br
  725.       XPoint \fIpoints[]\fP\^;
  726. .br
  727.       int \fIn\fP\^;
  728. .br
  729.       int \fIfill_rule\fP\^;    
  730. .FN
  731. .\" $Header: points1.a,v 1.1 88/02/26 10:30:33 mento Exp $
  732. .IP \fIpoints\fP 1i
  733. Specifies an array of points.
  734. .\" $Header: n1.a,v 1.1 88/02/26 10:29:03 mento Exp $
  735. .IP \fIn\fP 1i
  736. Specifies the number of points in the polygon. 
  737. .\" $Header: fill_rule.a,v 1.3 88/05/09 11:57:36 mento Exp $
  738. .IP \fIfill_rule\fP 1i
  739. Specifies the fill-rule you want to set for the specified GC.
  740. You can pass 
  741. .PN EvenOddRule
  742. or
  743. .PN WindingRule .
  744. .\" End marker code here
  745. .LP 
  746. .\" $Header: XPolyRegion.d,v 1.3 88/06/11 07:52:19 mento Exp $
  747. The
  748. .PN XPolygonRegion
  749. function returns a region for the polygon defined by the points array.
  750. For an explanation of fill_rule,
  751. see
  752. .PN XCreateGC .
  753. .LP
  754. .sp
  755. To set the clip-mask of a GC to a region, use
  756. .PN XSetRegion .
  757. .IN "XSetRegion" "" "@DEF@"
  758. .\" Start marker code here
  759. .FD 0
  760. .\" $Header: XSetRegion.f,v 1.1 88/02/26 10:03:27 mento Exp $
  761. XSetRegion\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIr\fP\^)
  762. .br
  763.       Display *\fIdisplay\fP\^;
  764. .br
  765.       GC \fIgc\fP\^;
  766. .br
  767.       Region \fIr\fP\^;
  768. .FN
  769. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  770. .IP \fIdisplay\fP 1i
  771. Specifies the connection to the X server.
  772. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  773. .IP \fIgc\fP 1i
  774. Specifies the GC.
  775. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  776. .IP \fIr\fP 1i
  777. Specifies the region.
  778. .\" End marker code here
  779. .LP
  780. .\" $Header: XSetRegion.d,v 1.3 88/05/20 05:32:45 mento Exp $
  781. The
  782. .PN XSetRegion
  783. function sets the clip-mask in the GC to the specified region.
  784. Once it is set in the GC,
  785. the region can be destroyed.
  786. .LP 
  787. .sp
  788. To deallocate the storage associated with a specified region, use
  789. .PN XDestroyRegion .
  790. .IN "XDestroyRegion" "" "@DEF@"
  791. .\" Start marker code here
  792. .FD 0
  793. .\" $Header: XDestroyReg.f,v 1.1 88/02/26 09:59:38 mento Exp $
  794. XDestroyRegion\^(\^\fIr\fP\^)
  795. .br
  796.       Region \fIr\fP\^;
  797. .FN
  798. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  799. .IP \fIr\fP 1i
  800. Specifies the region.
  801. .\" End marker code here
  802. .NH 3
  803. Moving or Shrinking Regions
  804. .XS
  805. \*(SN Moving or Shrinking Regions 
  806. .XE
  807. .LP
  808. To move a region by a specified amount, use 
  809. .PN XOffsetRegion .
  810. .IN "XOffsetRegion" "" "@DEF@"
  811. .\" Start marker code here
  812. .FD 0
  813. .\" $Header: XOffsetReg.f,v 1.1 88/02/26 10:01:40 mento Exp $
  814. XOffsetRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
  815. .br
  816.       Region \fIr\fP\^;
  817. .br
  818.       int \fIdx\fP\^, \fIdy\fP\^;
  819. .FN
  820. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  821. .IP \fIr\fP 1i
  822. Specifies the region.
  823. .ds Dy move
  824. .\" $Header: dxdy.a,v 1.3 88/08/04 11:11:24 mento Exp $
  825. .IP \fIdx\fP 1i
  826. .br
  827. .ns
  828. .IP \fIdy\fP 1i
  829. Specify the x and y coordinates,
  830. which define the amount you want to \*(Dy the specified region.
  831. .\" End marker code here
  832. .LP 
  833. .sp
  834. To reduce a region by a specified amount, use
  835. .PN XShrinkRegion .
  836. .IN "XShrinkRegion" "" "@DEF@"
  837. .\" Start marker code here
  838. .FD 0
  839. .\" $Header: XShrinkReg.f,v 1.1 88/02/26 10:03:47 mento Exp $
  840. XShrinkRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
  841. .br
  842.       Region \fIr\fP\^;
  843. .br
  844.       int \fIdx\fP\^, \fIdy\fP\^;
  845. .FN
  846. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  847. .IP \fIr\fP 1i
  848. Specifies the region.
  849. .ds Dy shrink
  850. .\" $Header: dxdy.a,v 1.3 88/08/04 11:11:24 mento Exp $
  851. .IP \fIdx\fP 1i
  852. .br
  853. .ns
  854. .IP \fIdy\fP 1i
  855. Specify the x and y coordinates,
  856. which define the amount you want to \*(Dy the specified region.
  857. .\" End marker code here
  858. .LP
  859. Positive values shrink the size of the region, 
  860. and negative values expand the region.
  861. .NH 3
  862. Computing with Regions
  863. .XS
  864. \*(SN Computing with Regions 
  865. .XE
  866. .LP
  867. .sp
  868. To generate the smallest rectangle enclosing a region, use
  869. .PN XClipBox .
  870. .IN "XClipBox" "" "@DEF@"
  871. .\" Start marker code here
  872. .FD 0
  873. .\" $Header: XClipBox.f,v 1.2 88/04/07 16:55:50 mento Exp $
  874. XClipBox\^(\^\fIr\fP\^, \fIrect_return\fP\^)
  875. .br
  876.       Region \fIr\fP\^;
  877. .br
  878.       XRectangle *\fIrect_return\fP\^;
  879. .FN
  880. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  881. .IP \fIr\fP 1i
  882. Specifies the region.
  883. .\" $Header: rect.a,v 1.2 88/04/07 16:56:54 mento Exp $
  884. .IP \fIrect_return\fP 1i
  885. Returns the smallest enclosing rectangle.
  886. .\" End marker code here
  887. .LP
  888. .\" $Header: XClipBox.d,v 1.3 88/04/23 12:41:53 mento Exp $
  889. The
  890. .PN XClipBox
  891. function returns the smallest rectangle enclosing the specified region.
  892. .LP
  893. .sp
  894. To compute the intersection of two regions, use
  895. .PN XIntersectRegion .
  896. .IN "XIntersectRegion" "" "@DEF@"
  897. .\" Start marker code here
  898. .FD 0
  899. .\" $Header: XInterReg.f,v 1.2 88/04/07 17:02:01 mento Exp $
  900. XIntersectRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
  901. .br
  902.       Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
  903. .FN
  904. .\" $Header: srasrb.a,v 1.1 88/02/26 10:31:19 mento Exp $
  905. .IP \fIsra\fP 1i
  906. .br
  907. .ns
  908. .IP \fIsrb\fP 1i
  909. Specify the two regions with which you want to perform the computation.
  910. .\" $Header: dr.a,v 1.2 88/04/07 17:02:49 mento Exp $
  911. .IP \fIdr_return\fP 1i
  912. Returns the result of the computation.
  913. .\" End marker code here
  914. .LP
  915. .sp
  916. To compute the union of two regions, use
  917. .PN XUnionRegion .
  918. .IN "XUnionRegion" "" "@DEF@"
  919. .\" Start marker code here
  920. .FD 0
  921. .\" $Header: XUnionRegion.f,v 1.2 88/04/07 17:03:24 mento Exp $
  922. XUnionRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
  923. .br
  924.       Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
  925. .FN
  926. .\" $Header: srasrb.a,v 1.1 88/02/26 10:31:19 mento Exp $
  927. .IP \fIsra\fP 1i
  928. .br
  929. .ns
  930. .IP \fIsrb\fP 1i
  931. Specify the two regions with which you want to perform the computation.
  932. .\" $Header: dr.a,v 1.2 88/04/07 17:02:49 mento Exp $
  933. .IP \fIdr_return\fP 1i
  934. Returns the result of the computation.
  935. .\" End marker code here
  936. .LP
  937. .sp
  938. To create a union of a source region and a rectangle, use
  939. .PN XUnionRectWithRegion .
  940. .IN "XUnionRectWithRegion" "" "@DEF@"
  941. .\" Start marker code here
  942. .FD 0
  943. XUnionRectWithRegion\^(\^\fIrectangle\fP, \fIsrc_region\fP, \
  944. \fIdest_region_return\fP\^)
  945. .br
  946.      XRectangle *\fIrectangle\fP\^;
  947. .br
  948.      Region \fIsrc_region\fP\^;
  949. .br
  950.      Region \fIdest_region_return\fP\^;
  951. .FN
  952. .IP \fIrectangle\fP 1i
  953. Specifies the rectangle.
  954. .IP \fIsrc_region\fP 1i
  955. Specifies the source region to be used.
  956. .IP \fIdest_region_return\fP 1i
  957. Returns the destination region.
  958. .\" End marker code here
  959. .LP
  960. The
  961. .PN XUnionRectWithRegion
  962. function updates the destination region from a union of the specified rectangle
  963. and the specified source region.
  964. .LP
  965. .sp
  966. To subtract two regions, use
  967. .PN XSubtractRegion .
  968. .IN "XSubtractRegion" "" "@DEF@"
  969. .\" Start marker code here
  970. .FD 0
  971. .\" $Header: XSubtractReg.f,v 1.2 88/04/07 17:07:58 mento Exp $
  972. XSubtractRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
  973. .br
  974.       Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
  975. .FN
  976. .\" $Header: srasrb.a,v 1.1 88/02/26 10:31:19 mento Exp $
  977. .IP \fIsra\fP 1i
  978. .br
  979. .ns
  980. .IP \fIsrb\fP 1i
  981. Specify the two regions with which you want to perform the computation.
  982. .\" $Header: dr.a,v 1.2 88/04/07 17:02:49 mento Exp $
  983. .IP \fIdr_return\fP 1i
  984. Returns the result of the computation.
  985. .\" End marker code here
  986. .LP
  987. .\" $Header: XSubtractReg.d,v 1.3 88/08/20 10:20:59 mento Exp $
  988. The
  989. .PN XSubtractRegion
  990. function subtracts srb from sra and stores the results in dr_return.
  991. .LP
  992. .sp
  993. To calculate the difference between the union and intersection 
  994. of two regions, use
  995. .PN XXorRegion .
  996. .IN "XXorRegion" "" "@DEF@"
  997. .\" Start marker code here
  998. .FD 0
  999. .\" $Header: XXorRegion.f,v 1.2 88/04/07 17:09:05 mento Exp $
  1000. XXorRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
  1001. .br
  1002.       Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
  1003. .FN
  1004. .\" $Header: srasrb.a,v 1.1 88/02/26 10:31:19 mento Exp $
  1005. .IP \fIsra\fP 1i
  1006. .br
  1007. .ns
  1008. .IP \fIsrb\fP 1i
  1009. Specify the two regions with which you want to perform the computation.
  1010. .\" $Header: dr.a,v 1.2 88/04/07 17:02:49 mento Exp $
  1011. .IP \fIdr_return\fP 1i
  1012. Returns the result of the computation.
  1013. .\" End marker code here
  1014. .NH 3
  1015. Determining if Regions Are Empty or Equal
  1016. .XS
  1017. \*(SN Determining if Regions Are Empty or Equal 
  1018. .XE
  1019. .LP
  1020. To determine if the specified region is empty, use
  1021. .PN XEmptyRegion .
  1022. .IN "XEmptyRegion" "" "@DEF@"
  1023. .\" Start marker code here
  1024. .FD 0
  1025. .\" $Header: XEmptyRegion.f,v 1.2 88/04/07 17:09:49 mento Exp $
  1026. Bool XEmptyRegion\^(\^\fIr\fP\^)
  1027. .br
  1028.       Region \fIr\fP\^;
  1029. .FN
  1030. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  1031. .IP \fIr\fP 1i
  1032. Specifies the region.
  1033. .\" End marker code here
  1034. .LP 
  1035. .\" $Header: XEmptyRegion.d,v 1.2 88/06/11 07:50:03 mento Exp $
  1036. The
  1037. .PN XEmptyRegion
  1038. function returns
  1039. .PN True
  1040. if the region is empty.
  1041. .LP
  1042. .sp
  1043. To determine if two regions have the same offset, size, and shape, use
  1044. .PN XEqualRegion .
  1045. .IN "XEqualRegion" "" "@DEF@"
  1046. .\" Start marker code here
  1047. .FD 0
  1048. .\" $Header: XEqualRegion.f,v 1.2 88/04/07 17:10:16 mento Exp $
  1049. Bool XEqualRegion\^(\^\fIr1\fP\^, \fIr2\fP\^)
  1050. .br
  1051.       Region \fIr1\fP\^, \fIr2\fP\^;
  1052. .FN
  1053. .\" $Header: r1r2.a,v 1.1 88/02/26 10:30:48 mento Exp $
  1054. .IP \fIr1\fP 1i
  1055. .br
  1056. .ns
  1057. .IP \fIr2\fP 1i
  1058. Specify the two regions.
  1059. .\" End marker code here
  1060. .LP
  1061. .\" $Header: XEqualRegion.d,v 1.2 88/06/11 07:50:04 mento Exp $
  1062. The
  1063. .PN XEqualRegion
  1064. function returns
  1065. .PN True
  1066. if the two regions have the same offset, size, and shape.
  1067. .NH 3
  1068. Locating a Point or a Rectangle in a Region
  1069. .XS
  1070. \*(SN Locating a Point or a Rectangle in a Region 
  1071. .XE
  1072. .LP
  1073. To determine if a specified point resides in a specified region, use
  1074. .PN XPointInRegion .
  1075. .IN "XPointInRegion" "" "@DEF@"
  1076. .\" Start marker code here
  1077. .FD 0
  1078. .\" $Header: XPointInReg.f,v 1.2 88/04/07 17:10:45 mento Exp $
  1079. Bool XPointInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^)
  1080. .br
  1081.       Region \fIr\fP\^;
  1082. .br
  1083.       int \fIx\fP\^, \fIy\fP\^;
  1084. .FN
  1085. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  1086. .IP \fIr\fP 1i
  1087. Specifies the region.
  1088. .ds Xy , which define the point
  1089. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1090. .IP \fIx\fP 1i
  1091. .br
  1092. .ns
  1093. .IP \fIy\fP 1i
  1094. Specify the x and y coordinates\*(Xy.
  1095. .\" Start marker code here
  1096. .LP
  1097. .\" $Header: XPointInReg.d,v 1.3 88/04/23 12:44:36 mento Exp $
  1098. The
  1099. .PN XPointInRegion
  1100. function returns 
  1101. .PN True
  1102. if the point (x, y) is contained in the region r.
  1103. .LP
  1104. .sp
  1105. To determine if a specified rectangle is inside a region, use
  1106. .PN XRectInRegion .
  1107. .IN "XRectInRegion" "" "@DEF@"
  1108. .\" Start marker code here
  1109. .FD 0
  1110. .\" $Header: XRectInReg.f,v 1.1 88/02/26 10:02:37 mento Exp $
  1111. int XRectInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
  1112. .br
  1113.       Region \fIr\fP\^;
  1114. .br
  1115.       int \fIx\fP\^, \fIy\fP\^; 
  1116. .br
  1117.       unsigned int \fIwidth\fP\^, \fIheight\fP\^;
  1118. .FN
  1119. .\" $Header: r.a,v 1.1 88/02/26 10:29:50 mento Exp $
  1120. .IP \fIr\fP 1i
  1121. Specifies the region.
  1122. .ds Xy , which define the coordinates of the upper-left corner of the rectangle
  1123. .\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
  1124. .IP \fIx\fP 1i
  1125. .br
  1126. .ns
  1127. .IP \fIy\fP 1i
  1128. Specify the x and y coordinates\*(Xy.
  1129. .ds Wh , which define the rectangle 
  1130. .\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
  1131. .IP \fIwidth\fP 1i
  1132. .br
  1133. .ns
  1134. .IP \fIheight\fP 1i
  1135. Specify the width and height\*(Wh.
  1136. .\" End marker code here
  1137. .LP 
  1138. .\" $Header: XRectInReg.d,v 1.1 88/02/26 10:50:04 mento Exp $
  1139. The
  1140. .PN XRectInRegion
  1141. function returns
  1142. .PN RectangleIn
  1143. if the rectangle is entirely in the specified region,
  1144. .PN RectangleOut
  1145. if the rectangle is entirely out of the specified region,
  1146. and
  1147. .PN RectanglePart
  1148. if the rectangle is partially in the specified region.
  1149. .NH 2
  1150. Using Cut Buffers
  1151. .XS
  1152. \*(SN Using Cut Buffers 
  1153. .XE
  1154. .LP
  1155. .IN "Cut Buffers"
  1156. Xlib provides functions to manipulate cut buffers,
  1157. a very simple form of ``cut and paste'' inter-client communication.
  1158. Selections are a much more powerful and useful mechanism for
  1159. interchanging data between clients (see section 4.5),
  1160. and generally should be used instead of cut buffers.
  1161. .LP
  1162. Cut buffers are implemented as properties on the first root window
  1163. of the display.
  1164. The buffers can only contain text, in the STRING encoding.
  1165. The text encoding is not changed by Xlib, when fetching or storing.
  1166. Eight buffers are provided
  1167. and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
  1168. .LP
  1169. .sp
  1170. To store data in cut buffer 0, use 
  1171. .PN XStoreBytes .
  1172. .IN "XStoreBytes" "" "@DEF@"
  1173. .\" Start marker code here
  1174. .FD 0
  1175. .\" $Header: XStoreBytes.f,v 1.2 88/04/07 17:21:31 mento Exp $
  1176. XStoreBytes\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^)
  1177. .br
  1178.       Display *\fIdisplay\fP\^;
  1179. .br
  1180.       char *\fIbytes\fP\^;
  1181. .br
  1182.       int \^\fInbytes\fP\^;
  1183. .br
  1184. .FN 
  1185. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1186. .IP \fIdisplay\fP 1i
  1187. Specifies the connection to the X server.
  1188. .\" $Header: bytes.a,v 1.2 88/05/20 05:55:18 mento Exp $
  1189. .IP \fIbytes\fP 1i
  1190. Specifies the bytes, which are not necessarily ASCII or null-terminated.
  1191. .IP \fInbytes\fP 1i
  1192. Specifies the number of bytes to be stored.
  1193. .\" End marker code here
  1194. .LP
  1195. .\" $Header: XStoreBytes.d,v 1.2 88/06/11 07:53:46 mento Exp $
  1196. Note that the data can have embedded null characters,
  1197. and need not be null terminated.
  1198. The cut buffer's contents can be retrieved later by
  1199. any client calling
  1200. .PN XFetchBytes .
  1201. .LP
  1202. .PN XStoreBytes
  1203. can generate a
  1204. .PN BadAlloc
  1205. error.
  1206. .LP
  1207. .sp
  1208. To store data in a specified cut buffer, use
  1209. .PN XStoreBuffer .
  1210. .IN "XStoreBuffer" "" "@DEF@"
  1211. .\" Start marker code here
  1212. .FD 0
  1213. .\" $Header: XStoreBuffer.f,v 1.2 88/04/07 17:22:43 mento Exp $
  1214. XStoreBuffer\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^, \fIbuffer\fP\^)
  1215. .br
  1216.       Display *\fIdisplay\fP\^;
  1217. .br
  1218.       char *\fIbytes\fP\^;
  1219. .br
  1220.       int \^\fInbytes\fP\^;
  1221. .br
  1222.       int \fIbuffer\fP\^;
  1223. .FN
  1224. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1225. .IP \fIdisplay\fP 1i
  1226. Specifies the connection to the X server.
  1227. .\" $Header: bytes.a,v 1.2 88/05/20 05:55:18 mento Exp $
  1228. .IP \fIbytes\fP 1i
  1229. Specifies the bytes, which are not necessarily ASCII or null-terminated.
  1230. .IP \fInbytes\fP 1i
  1231. Specifies the number of bytes to be stored.
  1232. .ds Fn in which you want to store the bytes
  1233. .\" $Header: buffer.a,v 1.4 88/08/04 11:02:57 mento Exp $
  1234. .IP \fIbuffer\fP 1i
  1235. Specifies the buffer \*(Fn.
  1236. .\" End marker code here
  1237. .LP
  1238. .\" $Header: XStoreBuffer.d,v 1.2 88/06/11 07:53:45 mento Exp $
  1239. If an invalid buffer is specified, the call has no effect.
  1240. Note that the data can have embedded null characters,
  1241. and need not be null terminated.
  1242. .LP
  1243. .PN XStoreBuffer
  1244. can generate a
  1245. .PN BadAlloc 
  1246. error.
  1247. .LP
  1248. .sp
  1249. To return data from cut buffer 0, use 
  1250. .PN XFetchBytes .
  1251. .IN "XFetchBytes" "" "@DEF@"
  1252. .\" Start marker code here
  1253. .FD 0
  1254. .\" $Header: XFetchBytes.f,v 1.1 88/02/26 10:00:00 mento Exp $
  1255. char *XFetchBytes\^(\^\fIdisplay\fP, \fInbytes_return\fP\^)
  1256. .br
  1257.       Display *\fIdisplay\fP\^;
  1258. .br
  1259.       int *\fInbytes_return\fP\^;
  1260. .FN
  1261. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1262. .IP \fIdisplay\fP 1i
  1263. Specifies the connection to the X server.
  1264. .\" $Header: nbytes.a,v 1.2 88/05/20 05:59:12 mento Exp $
  1265. .IP \fInbytes_return\fP 1i
  1266. Returns the number of bytes in the buffer.
  1267. .\" End marker code here
  1268. .LP
  1269. .\" $Header: XFetchBytes.d,v 1.3 88/08/20 10:22:26 mento Exp $
  1270. The
  1271. .PN XFetchBytes
  1272. function
  1273. returns the number of bytes in the nbytes_return argument,
  1274. if the buffer contains data.
  1275. Otherwise, the function
  1276. returns NULL and sets nbytes to 0.
  1277. The appropriate amount of storage is allocated and the pointer returned.
  1278. The client must free this storage when finished with it by calling
  1279. .PN XFree .
  1280. .LP
  1281. .sp
  1282. To return data from a specified cut buffer, use 
  1283. .PN XFetchBuffer .
  1284. .IN "XFetchBuffer" "" "@DEF@"
  1285. .\" Start marker code here
  1286. .FD 0
  1287. .\" $Header: XFetchBuffer.f,v 1.2 88/04/07 17:31:40 mento Exp $
  1288. char *XFetchBuffer\^(\^\fIdisplay\fP, \fInbytes_return\fP\^, \fIbuffer\fP\^)
  1289. .br
  1290.       Display *\fIdisplay\fP\^;
  1291. .br
  1292.       int *\fInbytes_return\fP\^;
  1293. .br
  1294.       int \fIbuffer\fP\^;
  1295. .FN
  1296. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1297. .IP \fIdisplay\fP 1i
  1298. Specifies the connection to the X server.
  1299. .\" $Header: nbytes.a,v 1.2 88/05/20 05:59:12 mento Exp $
  1300. .IP \fInbytes_return\fP 1i
  1301. Returns the number of bytes in the buffer.
  1302. .ds Fn from which you want the stored data returned
  1303. .\" $Header: buffer.a,v 1.4 88/08/04 11:02:57 mento Exp $
  1304. .IP \fIbuffer\fP 1i
  1305. Specifies the buffer \*(Fn.
  1306. .\" End marker code here
  1307. .LP
  1308. .\" $Header: XFetchBuffer.d,v 1.3 88/08/20 10:23:20 mento Exp $
  1309. The
  1310. .PN XFetchBuffer
  1311. function returns zero to the nbytes_return argument 
  1312. if there is no data in the buffer or if an invalid
  1313. buffer is specified.
  1314. .LP
  1315. .sp
  1316. To rotate the cut buffers, use 
  1317. .PN XRotateBuffers .
  1318. .IN "XRotateBuffers" "" "@DEF@"
  1319. .\" Start marker code here
  1320. .FD 0
  1321. .\" $Header: XRotateBufs.f,v 1.1 88/02/26 10:02:45 mento Exp $
  1322. XRotateBuffers\^(\^\fIdisplay\fP, \fIrotate\fP\^)
  1323. .br
  1324.       Display *\fIdisplay\fP\^;
  1325. .br
  1326.       int \fIrotate\fP\^;
  1327. .FN
  1328. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1329. .IP \fIdisplay\fP 1i
  1330. Specifies the connection to the X server.
  1331. .\" $Header: rotate.a,v 1.2 88/05/20 06:01:18 mento Exp $
  1332. .IP \fIrotate\fP 1i
  1333. Specifies how much to rotate the cut buffers.
  1334. .\" End marker code here
  1335. .LP 
  1336. .\" $Header: XRotateBufs.d,v 1.3 88/06/11 07:52:52 mento Exp $
  1337. The
  1338. .PN XRotateBuffers
  1339. function rotates the cut
  1340. buffers, such that buffer 0 becomes buffer n, 
  1341. buffer 1 becomes n + 1 mod 8, and so on.
  1342. This cut buffer numbering is global to the display.
  1343. Note that
  1344. .PN XRotateBuffers
  1345. generates
  1346. .PN BadMatch
  1347. errors if any of the eight buffers have not been created.
  1348. .NH 2
  1349. Determining the Appropriate Visual Type
  1350. .XS
  1351. \*(SN Determining the Appropriate Visual Type
  1352. .XE
  1353. .LP
  1354. A single display can support multiple screens.
  1355. Each screen can have several different visual types supported 
  1356. at different depths.
  1357. You can use the functions described in this section to determine
  1358. which visual to use for your application.
  1359. .LP
  1360. The functions in this section use the visual information masks and the
  1361. .PN XVisualInfo 
  1362. structure,
  1363. which is defined in
  1364. .Pn < X11/Xutil.h >
  1365. and contains:
  1366. .\" Start marker code here
  1367. .LP
  1368. /* Visual information mask bits */
  1369. .TS
  1370. lw(.5i) lw(2.5i) lw(.8i).
  1371. T{
  1372. #define
  1373. T}    T{
  1374. .PN VisualNoMask
  1375. T}    T{
  1376. 0x0
  1377. T}
  1378. T{
  1379. #define
  1380. T}    T{
  1381. .PN VisualIDMask
  1382. T}    T{
  1383. 0x1
  1384. T}
  1385. T{
  1386. #define
  1387. T}    T{
  1388. .PN VisualScreenMask
  1389. T}    T{
  1390. 0x2
  1391. T}
  1392. T{
  1393. #define
  1394. T}    T{
  1395. .PN VisualDepthMask
  1396. T}    T{
  1397. 0x4
  1398. T}
  1399. T{
  1400. #define
  1401. T}    T{
  1402. .PN VisualClassMask
  1403. T}    T{
  1404. 0x8
  1405. T}
  1406. T{
  1407. #define
  1408. T}    T{
  1409. .PN VisualRedMaskMask
  1410. T}    T{
  1411. 0x10
  1412. T}
  1413. T{
  1414. #define
  1415. T}    T{
  1416. .PN VisualGreenMaskMask
  1417. T}    T{
  1418. 0x20
  1419. T}
  1420. T{
  1421. #define
  1422. T}    T{
  1423. .PN VisualBlueMaskMask
  1424. T}    T{
  1425. 0x40
  1426. T}
  1427. T{
  1428. #define
  1429. T}    T{
  1430. .PN VisualColormapSizeMask
  1431. T}    T{
  1432. 0x80
  1433. T}
  1434. T{
  1435. #define
  1436. T}    T{
  1437. .PN VisualBitsPerRGBMask
  1438. T}    T{
  1439. 0x100
  1440. T}
  1441. T{
  1442. #define
  1443. T}    T{
  1444. .PN VisualAllMask
  1445. T}    T{
  1446. 0x1FF
  1447. T}
  1448. .TE
  1449. .IN "XVisualInfo" "" "@DEF@"
  1450. .Ds 0
  1451. .TA .5i 3i
  1452. .ta .5i 3i
  1453. /* Values */
  1454.  
  1455. typedef struct {
  1456.     Visual *visual;
  1457.     VisualID visualid;
  1458.     int screen;
  1459.     unsigned int depth;
  1460.     int class;
  1461.     unsigned long red_mask;
  1462.     unsigned long green_mask;
  1463.     unsigned long blue_mask;
  1464.     int colormap_size;
  1465.     int bits_per_rgb;
  1466. } XVisualInfo;
  1467. .De
  1468. .\" End marker code here
  1469. .LP
  1470. To obtain a list of visual information structures that match a specified
  1471. template, use
  1472. .PN XGetVisualInfo .
  1473. .IN "XGetVisualInfo" "" "@DEF@"
  1474. .\" Start marker code here
  1475. .FD 0
  1476. XVisualInfo *XGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP\^)
  1477. .br
  1478.       Display *\fIdisplay\fP\^;
  1479. .br
  1480.       long \fIvinfo_mask\fP\^;
  1481. .br
  1482.       XVisualInfo *\fIvinfo_template\fP\^;
  1483. .br
  1484.       int *\fInitems_return\fP\^;
  1485. .FN
  1486. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1487. .IP \fIdisplay\fP 1i
  1488. Specifies the connection to the X server.
  1489. .IP \fIvinfo_mask\fP 1i
  1490. Specifies the visual mask value.
  1491. .IP \fIvinfo_template\fP 1i
  1492. Specifies the visual attributes that are to be used in matching the visual
  1493. structures.
  1494. .IP \fInitems_return\fP 1i
  1495. Returns the number of matching visual structures.
  1496. .\" End marker code here
  1497. .LP
  1498. .\" $Header: XGetVInfo.d,v 1.3 88/06/11 07:51:29 mento Exp $
  1499. The
  1500. .PN XGetVisualInfo
  1501. function returns a list of visual structures that have attributes 
  1502. equal to the attributes specified by vinfo_template.
  1503. If no visual structures match the template using the specified vinfo_mask,
  1504. .PN XGetVisualInfo
  1505. returns a NULL.
  1506. To free the data returned by this function, use
  1507. .PN XFree .
  1508. .LP
  1509. .sp
  1510. To obtain the visual information that matches the specified depth and
  1511. class of the screen, use
  1512. .PN XMatchVisualInfo .
  1513. .IN "XMatchVisualInfo" "" "@DEF@"
  1514. .\" Start marker code here
  1515. .FD 0
  1516. Status XMatchVisualInfo\^(\^\fIdisplay\fP, \fIscreen\fP, \fIdepth\fP, \fIclass\fP, \fIvinfo_return\fP\^)
  1517. .br
  1518.       Display *\fIdisplay\fP\^;
  1519. .br
  1520.       int \fIscreen\fP\^;
  1521. .br
  1522.       int \fIdepth\fP\^;
  1523. .br
  1524.       int \fIclass\fP\^;
  1525. .br
  1526.       XVisualInfo *\fIvinfo_return\fP\^;
  1527. .FN
  1528. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1529. .IP \fIdisplay\fP 1i
  1530. Specifies the connection to the X server.
  1531. .IP \fIscreen\fP 1i
  1532. Specifies the screen.
  1533. .IP \fIdepth\fP 1i
  1534. Specifies the depth of the screen.
  1535. .IP \fIclass\fP 1i
  1536. Specifies the class of the screen.
  1537. .IP \fIvinfo_return\fP 1i
  1538. Returns the matched visual information.
  1539. .\" End marker code here
  1540. .LP
  1541. .\" $Header: XMatVInfo.d,v 1.2 88/06/11 07:51:59 mento Exp $
  1542. The
  1543. .PN XMatchVisualInfo
  1544. function returns the visual information for a visual that matches the specified
  1545. depth and class for a screen.
  1546. Because multiple visuals that match the specified depth and class can exist,
  1547. the exact visual chosen is undefined.
  1548. If a visual is found,
  1549. .PN XMatchVisualInfo
  1550. returns nonzero and the information on the visual to vinfo_return.
  1551. Otherwise, when a visual is not found,
  1552. .PN XMatchVisualInfo
  1553. returns zero.
  1554. .NH 2
  1555. Manipulating Images
  1556. .XS
  1557. \*(SN Manipulating Images 
  1558. .XE
  1559. .LP
  1560. Xlib provides several functions that perform basic operations on images.
  1561. All operations on images are defined using an 
  1562. .PN XImage 
  1563. structure, 
  1564. as defined in
  1565. .Pn < X11/Xlib.h >.
  1566. Because the number of different types of image formats can be very large,
  1567. this hides details of image storage properly from applications.
  1568. .LP
  1569. This section describes the functions for generic operations on images.
  1570. Manufacturers can provide very fast implementations of these for the
  1571. formats frequently encountered on their hardware.
  1572. These functions are neither sufficient nor desirable to use for general image
  1573. processing.
  1574. Rather, they are here to provide minimal functions on screen format
  1575. images.
  1576. The basic operations for getting and putting images are
  1577. .PN XGetImage
  1578. and 
  1579. .PN XPutImage .
  1580. .LP
  1581. Note that no functions have been defined, as yet, to read and write images 
  1582. to and from disk files.
  1583. .LP
  1584. The
  1585. .PN XImage 
  1586. structure describes an image as it exists in the client's memory.  
  1587. The user can request that some of the members such as height, width, 
  1588. and xoffset be changed when the image is sent to the server.
  1589. Note that bytes_per_line in concert with offset can be used to
  1590. extract a subset of the image.
  1591. Other members (for example, byte order, bitmap_unit, and so forth)
  1592. are characteristics of both the image and the server.  
  1593. If these members
  1594. differ between the image and the server, 
  1595. .PN XPutImage 
  1596. makes the appropriate conversions.
  1597. The first byte of the first line of
  1598. plane n must be located at the address (data + (n * height * bytes_per_line)).
  1599. For a description of the 
  1600. .PN XImage 
  1601. structure,
  1602. see section 8.7.
  1603. .LP
  1604. .sp
  1605. To allocate sufficient memory for an 
  1606. .PN XImage 
  1607. structure, use
  1608. .PN XCreateImage .
  1609. .IN "XCreateImage" "" "@DEF@"
  1610. .\" Start marker code here
  1611. .FD 0
  1612. XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP, 
  1613. .br
  1614.                         \fIbytes_per_line\fP\^)
  1615. .br
  1616.       Display *\fIdisplay\fP\^;
  1617. .br
  1618.       Visual *\fIvisual\fP\^;
  1619. .br
  1620.       unsigned int \fIdepth\fP\^;
  1621. .br
  1622.       int \fIformat\fP\^;
  1623. .br
  1624.       int \fIoffset\fP\^;
  1625. .br
  1626.       char *\fIdata\fP\^;
  1627. .br
  1628.       unsigned int \fIwidth\fP\^;
  1629. .br
  1630.       unsigned int \fIheight\fP\^;
  1631. .br
  1632.       int \fIbitmap_pad\fP\^;
  1633. .br
  1634.       int \fIbytes_per_line\fP\^;
  1635. .FN
  1636. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1637. .IP \fIdisplay\fP 1i
  1638. Specifies the connection to the X server.
  1639. .IP \fIvisual\fP 1i
  1640. Specifies the
  1641. .PN Visual
  1642. structure.
  1643. .IP \fIdepth\fP 1i
  1644. Specifies the depth of the image.
  1645. .IP \fIformat\fP 1i
  1646. Specifies the format for the image.
  1647. You can pass
  1648. .PN XYBitmap ,
  1649. .PN XYPixmap ,
  1650. or 
  1651. .PN ZPixmap .
  1652. .IP \fIoffset\fP 1i
  1653. Specifies the number of pixels to ignore at the beginning of the scanline.
  1654. .IP \fIdata\fP 1i
  1655. Specifies the image data.
  1656. .IP \fIwidth\fP 1i
  1657. Specifies the width of the image, in pixels.
  1658. .IP \fIheight\fP 1i
  1659. Specifies the height of the image, in pixels.
  1660. .IP \fIbitmap_pad\fP 1i
  1661. Specifies the quantum of a scanline (8, 16, or 32).
  1662. In other words, the start of one scanline is separated in client memory from 
  1663. the start of the next scanline by an integer multiple of this many bits.  
  1664. .IP \fIbytes_per_line\fP 1i
  1665. Specifies the number of bytes in the client image between
  1666. the start of one scanline and the start of the next.  
  1667. .\" End marker code here
  1668. .LP
  1669. .\" $Header: XCreImage.d,v 1.4 88/08/20 10:25:28 mento Exp $
  1670. The
  1671. .PN XCreateImage
  1672. function allocates the memory needed for an
  1673. .PN XImage
  1674. structure for the
  1675. specified display but does not allocate space for the image itself.
  1676. Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
  1677. values from the display and returns a pointer to the 
  1678. .PN XImage 
  1679. structure.
  1680. The red, green, and blue mask values are defined for Z format images only
  1681. and are derived from the 
  1682. .PN Visual 
  1683. structure passed in.
  1684. Other values also are passed in.
  1685. The offset permits the rapid displaying of the image without requiring each 
  1686. scanline to be shifted into position.
  1687. If you pass a zero value in bytes_per_line,
  1688. Xlib assumes that the scanlines are contiguous
  1689. in memory and calculates the value of bytes_per_line itself.
  1690. .LP
  1691. Note that when the image is created using
  1692. .PN XCreateImage ,
  1693. .PN XGetImage ,
  1694. or
  1695. .PN XSubImage ,
  1696. the destroy procedure that the 
  1697. .PN XDestroyImage
  1698. function calls frees both the image structure 
  1699. and the data pointed to by the image structure.
  1700. .LP
  1701. The basic functions used to get a pixel, set a pixel, create a subimage,
  1702. and add a constant value to an image are defined in the image object.
  1703. The functions in this section are really macro invocations of the functions
  1704. in the image object and are defined in
  1705. .Pn < X11/Xutil.h >.
  1706. .LP
  1707. .sp
  1708. To obtain a pixel value in an image, use
  1709. .PN XGetPixel .
  1710. .IN "XGetPixel" "" "@DEF@"
  1711. .\" Start marker code here
  1712. .FD 0
  1713. unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^)
  1714. .br
  1715.       XImage *\fIximage\fP\^;
  1716. .br
  1717.       int \fIx\fP\^;
  1718. .br
  1719.       int \fIy\fP\^;
  1720. .FN
  1721. .IP \fIximage\fP 1i
  1722. Specifies the image.
  1723. .\" $Header: xy.a,v 1.1 88/02/26 10:32:54 mento Exp $
  1724. .IP \fIx\fP 1i
  1725. .br
  1726. .ns
  1727. .IP \fIy\fP 1i
  1728. Specify the x and y coordinates.
  1729. .\" End marker code here
  1730. .LP
  1731. .\" $Header: XGetPixel.d,v 1.2 88/06/11 07:51:14 mento Exp $
  1732. The
  1733. .PN XGetPixel
  1734. function returns the specified pixel from the named image.
  1735. The pixel value is returned in normalized format (that is,
  1736. the least-significant byte of the long is the least-significant byte
  1737. of the pixel).
  1738. The image must contain the x and y coordinates.
  1739. .LP
  1740. .sp
  1741. To set a pixel value in an image, use
  1742. .PN XPutPixel .
  1743. .IN "XPutPixel" "" "@DEF@"
  1744. .\" Start marker code here
  1745. .FD 0
  1746. XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^)
  1747. .br
  1748.       XImage *\fIximage\fP\^;
  1749. .br
  1750.       int \fIx\fP\^;
  1751. .br
  1752.       int \fIy\fP\^;
  1753. .br
  1754.       unsigned long \fIpixel\fP\^;
  1755. .FN
  1756. .IP \fIximage\fP 1i
  1757. Specifies the image.
  1758. .\" $Header: xy.a,v 1.1 88/02/26 10:32:54 mento Exp $
  1759. .IP \fIx\fP 1i
  1760. .br
  1761. .ns
  1762. .IP \fIy\fP 1i
  1763. Specify the x and y coordinates.
  1764. .IP \fIpixel\fP 1i
  1765. Specifies the new pixel value.
  1766. .\" End marker code here
  1767. .LP
  1768. .\" $Header: XPutPixel.d,v 1.2 88/06/11 07:52:30 mento Exp $
  1769. The
  1770. .PN XPutPixel
  1771. function overwrites the pixel in the named image with the specified pixel value.
  1772. The input pixel value must be in normalized format
  1773. (that is, the least-significant byte of the long is the least-significant
  1774. byte of the pixel).
  1775. The image must contain the x and y coordinates.
  1776. .LP
  1777. .sp
  1778. To create a subimage, use
  1779. .PN XSubImage .
  1780. .IN "XSubImage" "" "@DEF@"
  1781. .\" Start marker code here
  1782. .FD 0
  1783. XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^)
  1784. .br
  1785.       XImage *\fIximage\fP\^;
  1786. .br
  1787.       int \fIx\fP\^;
  1788. .br
  1789.       int \fIy\fP\^;
  1790. .br
  1791.       unsigned int \fIsubimage_width\fP\^;
  1792. .br
  1793.       unsigned int \fIsubimage_height\fP\^;
  1794. .FN
  1795. .IP \fIximage\fP 1i
  1796. Specifies the image.
  1797. .\" $Header: xy.a,v 1.1 88/02/26 10:32:54 mento Exp $
  1798. .IP \fIx\fP 1i
  1799. .br
  1800. .ns
  1801. .IP \fIy\fP 1i
  1802. Specify the x and y coordinates.
  1803. .IP \fIsubimage_width\fP 1i
  1804. Specifies the width of the new subimage, in pixels.
  1805. .IP \fIsubimage_height\fP 1i
  1806. Specifies the height of the new subimage, in pixels.
  1807. .\" End marker code here
  1808. .LP
  1809. .\" $Header: XSubImage.d,v 1.3 88/08/20 10:26:23 mento Exp $
  1810. The
  1811. .PN XSubImage
  1812. function creates a new image that is a subsection of an existing one.
  1813. It allocates the memory necessary for the new
  1814. .PN XImage
  1815. structure
  1816. and returns a pointer to the new image.
  1817. The data is copied from the source image,
  1818. and the image must contain the rectangle defined by x, y, subimage_width,
  1819. and subimage_height.
  1820. .LP
  1821. .sp
  1822. To increment each pixel in an image by a constant value, use
  1823. .PN XAddPixel .
  1824. .IN "XAddPixel" "" "@DEF@"
  1825. .\" Start marker code here
  1826. .FD 0
  1827. XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^)
  1828. .br
  1829.       XImage *\fIximage\fP\^;
  1830. .br
  1831.       long \fIvalue\fP\^;
  1832. .FN
  1833. .IP \fIximage\fP 1i
  1834. Specifies the image.
  1835. .IP \fIvalue\fP 1i
  1836. Specifies the constant value that is to be added.
  1837. .\" End marker code here
  1838. .LP
  1839. .\" $Header: XAddPixel.d,v 1.2 88/06/11 07:48:34 mento Exp $
  1840. The
  1841. .PN XAddPixel
  1842. function adds a constant value to every pixel in an image.
  1843. It is useful when you have a base pixel value from allocating
  1844. color resources and need to manipulate the image to that form.
  1845. .LP
  1846. .sp
  1847. To deallocate the memory allocated in a previous call to
  1848. .PN XCreateImage ,
  1849. use
  1850. .PN XDestroyImage .
  1851. .IN "XDestroyImage" "" "@DEF@"
  1852. .\" Start marker code here
  1853. .FD 0
  1854. XDestroyImage\^(\^\fIximage\fP\^)
  1855. .br
  1856.         XImage *\^\fIximage\fP\^; 
  1857. .FN
  1858. .IP \fIximage\fP 1i
  1859. Specifies the image.
  1860. .\" End marker code here
  1861. .LP
  1862. .\" $Header: XDestImage.d,v 1.1 88/02/26 10:41:47 mento Exp $
  1863. The
  1864. .PN XDestroyImage
  1865. function deallocates the memory associated with the
  1866. .PN XImage
  1867. structure.
  1868. .LP
  1869. Note that when the image is created using
  1870. .PN XCreateImage ,
  1871. .PN XGetImage ,
  1872. or 
  1873. .PN XSubImage ,
  1874. the destroy procedure that this macro calls
  1875. frees both the image structure and the data pointed to by the image structure. 
  1876. .NH 2
  1877. Manipulating Bitmaps
  1878. .XS
  1879. \*(SN Manipulating Bitmaps 
  1880. .XE
  1881. .LP
  1882. Xlib provides functions that you can use to read a bitmap from a file,
  1883. save a bitmap to a file, or create a bitmap. 
  1884. This section describes those functions that transfer bitmaps to and
  1885. from the client's file system, thus allowing their reuse in a later
  1886. connection (for example, from an entirely different client or to a
  1887. different display or server).
  1888. .LP
  1889. The X version 11 bitmap file format is:
  1890. .LP
  1891. .\" Start marker code here
  1892. .Ds 0
  1893. #define \fIname\fP_width \fIwidth\fP
  1894. #define \fIname\fP_height \fIheight\fP
  1895. #define \fIname\fP_x_hot \fIx\fP
  1896. #define \fIname\fP_y_hot \fIy\fP
  1897. static unsigned char \fIname\fP_bits[] = { 0x\fINN\fP,... }
  1898. .De
  1899. .\" End marker code here
  1900. .LP
  1901. The lines for the variables ending with _x_hot and _y_hot suffixes are optional
  1902. because they are present only if a hotspot has been defined for this bitmap.
  1903. The lines for the other variables are required.
  1904. The word ``unsigned'' is optional; that is, the type of the _bits array
  1905. can be char or unsigned char.
  1906. The _bits array must be large enough to contain the size bitmap.
  1907. The bitmap unit is eight.
  1908. The name is derived from the name of the file that you specified
  1909. on the original command line by deleting the directory path and extension.
  1910. .LP
  1911. .sp
  1912. To read a bitmap from a file, use
  1913. .PN XReadBitmapFile .
  1914. .IN "XReadBitmapFile" "" "@DEF@"
  1915. .\" Start marker code here
  1916. .FD 0
  1917. int XReadBitmapFile(\^\fIdisplay\fP, \fId\fP, \fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIbitmap_return\fP, \fIx_hot_return\fP, 
  1918. .br
  1919.                        \fIy_hot_return\fP\^)
  1920. .br
  1921.       Display *\fIdisplay\fP\^;
  1922. .br
  1923.       Drawable \fId\fP\^;
  1924. .br
  1925.       char *\fIfilename\fP\^;
  1926. .br
  1927.       unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
  1928. .br
  1929.       Pixmap *\fIbitmap_return\fP\^;
  1930. .br
  1931.       int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;    
  1932. .FN
  1933. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1934. .IP \fIdisplay\fP 1i
  1935. Specifies the connection to the X server.
  1936. .ds Dr \ that indicates the screen
  1937. .\" $Header: d_gen.a,v 1.2 88/08/04 11:09:21 mento Exp $
  1938. .IP \fId\fP 1i
  1939. Specifies the drawable\*(Dr. 
  1940. .\" $Header: filename.a,v 1.2 88/05/20 07:30:24 mento Exp $
  1941. .IP \fIfilename\fP 1i
  1942. Specifies the file name to use.
  1943. The format of the file name is operating-system dependent.
  1944. .IP \fIwidth_return\fP 1i
  1945. .br
  1946. .ns
  1947. .IP \fIheight_return\fP 1i
  1948. Return the width and height values of the read in bitmap file.
  1949. .IP \fIbitmap_return\fP 1i
  1950. Returns the bitmap that is created.
  1951. .IP \fIx_hot_return\fP 1i
  1952. .br
  1953. .ns
  1954. .IP \fIy_hot_return\fP 1i
  1955. Return the hotspot coordinates.
  1956. .\" End marker code here
  1957. .LP
  1958. .\" $Header: XRBitFile.d,v 1.2 88/06/11 07:52:43 mento Exp $
  1959. The
  1960. .PN XReadBitmapFile
  1961. function reads in a file containing a bitmap.
  1962. The file is parsed in the encoding of the current locale.
  1963. The ability to read other than the standard format 
  1964. is implementation dependent.
  1965. If the file cannot be opened, 
  1966. .PN XReadBitmapFile 
  1967. returns 
  1968. .PN BitmapOpenFailed .  
  1969. If the file can be opened but does not contain valid bitmap data, 
  1970. it returns 
  1971. .PN BitmapFileInvalid .  
  1972. If insufficient working storage is allocated,
  1973. it returns
  1974. .PN BitmapNoMemory .  
  1975. If the file is readable and valid,
  1976. it returns 
  1977. .PN BitmapSuccess .
  1978. .LP
  1979. .PN XReadBitmapFile 
  1980. returns the bitmap's height and width, as read
  1981. from the file, to width_return and height_return.
  1982. It then creates a pixmap of the appropriate size, 
  1983. reads the bitmap data from the file into the pixmap,
  1984. and assigns the pixmap to the caller's variable bitmap.  
  1985. The caller must free the bitmap using 
  1986. .PN XFreePixmap 
  1987. when finished.
  1988. If \fIname\fP_x_hot and \fIname\fP_y_hot exist,
  1989. .PN XReadBitmapFile 
  1990. returns them to x_hot_return and y_hot_return;
  1991. otherwise, it returns \-1,\-1.
  1992. .LP
  1993. .PN XReadBitmapFile
  1994. can generate
  1995. .PN BadAlloc
  1996. and
  1997. .PN BadDrawable
  1998. errors.
  1999. .LP
  2000. .sp
  2001. To write out a bitmap to a file, use
  2002. .PN XWriteBitmapFile .
  2003. .IN "XWriteBitmapFile" "" "@DEF@"
  2004. .\" Start marker code here
  2005. .FD 0
  2006. int XWriteBitmapFile(\^\fIdisplay\fP, \fIfilename\fP, \fIbitmap\fP, \fIwidth\fP, \fIheight\fP, \fIx_hot\fP, \fIy_hot\fP\^)
  2007. .br
  2008.       Display *\fIdisplay\fP\^;
  2009. .br
  2010.       char *\fIfilename\fP\^;
  2011. .br
  2012.       Pixmap \fIbitmap\fP\^;
  2013. .br
  2014.       unsigned int \fIwidth\fP, \fIheight\fP\^;
  2015. .br
  2016.       int \fIx_hot\fP, \fIy_hot\fP\^;
  2017. .FN
  2018. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2019. .IP \fIdisplay\fP 1i
  2020. Specifies the connection to the X server.
  2021. .\" $Header: filename.a,v 1.2 88/05/20 07:30:24 mento Exp $
  2022. .IP \fIfilename\fP 1i
  2023. Specifies the file name to use.
  2024. The format of the file name is operating-system dependent.
  2025. .IP \fIbitmap\fP 1i
  2026. Specifies the bitmap.
  2027. .\" $Header: widtheight.a,v 1.1 88/02/26 10:32:27 mento Exp $
  2028. .IP \fIwidth\fP 1i
  2029. .br
  2030. .ns
  2031. .IP \fIheight\fP 1i
  2032. Specify the width and height.
  2033. .IP \fIx_hot\fP 1i
  2034. .br
  2035. .ns
  2036. .IP \fIy_hot\fP 1i
  2037. Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)
  2038. in the file.
  2039. .\" End marker code here
  2040. .LP
  2041. .\" $Header: XWBitFile.d,v 1.2 88/06/11 07:54:35 mento Exp $
  2042. The
  2043. .PN XWriteBitmapFile
  2044. function writes a bitmap out to a file in the X version 11 format.
  2045. The file is written in the encoding of the current locale.
  2046. If the file cannot be opened for writing, 
  2047. it returns 
  2048. .PN BitmapOpenFailed .  
  2049. If insufficient memory is allocated,
  2050. .PN XWriteBitmapFile
  2051. returns
  2052. .PN BitmapNoMemory ;
  2053. otherwise, on no error,
  2054. it returns
  2055. .PN BitmapSuccess .
  2056. If x_hot and y_hot are not \-1, \-1, 
  2057. .PN XWriteBitmapFile
  2058. writes them out as the hotspot coordinates for the bitmap.
  2059. .LP
  2060. .PN XWriteBitmapFile
  2061. can generate
  2062. .PN BadDrawable
  2063. and
  2064. .PN BadMatch
  2065. errors.
  2066. .LP
  2067. .sp
  2068. To create a pixmap and then store bitmap-format data into it, use
  2069. .PN XCreatePixmapFromBitmapData .
  2070. .IN "XCreatePixmapFromBitmapData" "" "@DEF@"
  2071. .\" Start marker code here
  2072. .FD 0
  2073. Pixmap XCreatePixmapFromBitmapData\^(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP, \fIfg\fP, \fIbg\fP, \fIdepth\fP\^)
  2074. .br
  2075.      Display *\fIdisplay\fP\^;
  2076. .br
  2077.      Drawable \fId\fP\^;
  2078. .br
  2079.      char *\fIdata\fP\^;
  2080. .br
  2081.      unsigned int \fIwidth\fP, \fIheight\fP\^;
  2082. .br
  2083.      unsigned long \fIfg\fP, \fIbg\fP\^;
  2084. .br
  2085.      unsigned int \fIdepth\fP\^;
  2086. .FN
  2087. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2088. .IP \fIdisplay\fP 1i
  2089. Specifies the connection to the X server.
  2090. .ds Dr \ that indicates the screen
  2091. .\" $Header: d_gen.a,v 1.2 88/08/04 11:09:21 mento Exp $
  2092. .IP \fId\fP 1i
  2093. Specifies the drawable\*(Dr. 
  2094. .IP \fIdata\fP 1i
  2095. Specifies the data in bitmap format.
  2096. .\" $Header: widtheight.a,v 1.1 88/02/26 10:32:27 mento Exp $
  2097. .IP \fIwidth\fP 1i
  2098. .br
  2099. .ns
  2100. .IP \fIheight\fP 1i
  2101. Specify the width and height.
  2102. .IP \fIfg\fP 1i
  2103. .br
  2104. .ns
  2105. .IP \fIbg\fP 1i
  2106. Specify the foreground and background pixel values to use.
  2107. .\" $Header: depth1.a,v 1.3 88/05/09 09:53:55 mento Exp $
  2108. .IP \fIdepth\fP 1i
  2109. Specifies the depth of the pixmap.
  2110. .\" End marker code here
  2111. .LP
  2112. The
  2113. .PN XCreatePixmapFromBitmapData
  2114. function creates a pixmap of the given depth and then does a bitmap-format
  2115. .PN XPutImage
  2116. of the data into it.
  2117. The depth must be supported by the screen of the specified drawable,
  2118. or a
  2119. .PN BadMatch
  2120. error results.
  2121. .LP
  2122. .PN XCreatePixmapFromBitmapData
  2123. can generate
  2124. .PN BadAlloc
  2125. and
  2126. .PN BadMatch
  2127. errors.
  2128. .LP
  2129. .sp
  2130. To include a bitmap written out by 
  2131. .PN XWriteBitmapFile 
  2132. .IN "XWriteBitmapFile"
  2133. in a program directly, as opposed to reading it in every time at run time, use
  2134. .PN XCreateBitmapFromData .
  2135. .IN "XCreateBitmapFromData" "" "@DEF@"
  2136. .\" Start marker code here
  2137. .FD 0
  2138. Pixmap XCreateBitmapFromData(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^)
  2139. .br
  2140.       Display *\fIdisplay\fP\^;
  2141. .br
  2142.       Drawable \fId\fP\^;
  2143. .br
  2144.       char *\fIdata\fP\^;
  2145. .br
  2146.       unsigned int \fIwidth\fP, \fIheight\fP\^;
  2147. .FN
  2148. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2149. .IP \fIdisplay\fP 1i
  2150. Specifies the connection to the X server.
  2151. .ds Dr \ that indicates the screen
  2152. .\" $Header: d_gen.a,v 1.2 88/08/04 11:09:21 mento Exp $
  2153. .IP \fId\fP 1i
  2154. Specifies the drawable\*(Dr. 
  2155. .IP \fIdata\fP 1i
  2156. Specifies the location of the bitmap data.
  2157. .\" $Header: widtheight.a,v 1.1 88/02/26 10:32:27 mento Exp $
  2158. .IP \fIwidth\fP 1i
  2159. .br
  2160. .ns
  2161. .IP \fIheight\fP 1i
  2162. Specify the width and height.
  2163. .\" End marker code here
  2164. .LP
  2165. .\" $Header: XCreBmap.d,v 1.6 88/08/24 09:09:07 mento Exp $
  2166. The
  2167. .PN XCreateBitmapFromData
  2168. function allows you to include in your C program (using #include) a bitmap file
  2169. that was written out by
  2170. .PN XWriteBitmapFile
  2171. (X version 11 format only) without reading in the bitmap file.
  2172. The following example creates a gray bitmap:
  2173. .LP
  2174. .Ds 0
  2175. #include "gray.bitmap"
  2176. .sp 6p
  2177. Pixmap bitmap;
  2178. bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
  2179. .De
  2180. .LP
  2181. If insufficient working storage was allocated,
  2182. .PN XCreateBitmapFromData
  2183. returns
  2184. .PN None .
  2185. It is your responsibility to free the
  2186. bitmap using
  2187. .PN XFreePixmap
  2188. when finished.
  2189. .LP
  2190. .PN XCreateBitmapFromData
  2191. can generate a
  2192. .PN BadAlloc
  2193. error.
  2194. .NH 2
  2195. Using the Context Manager
  2196. .XS
  2197. \*(SN Using the Context Manager 
  2198. .XE
  2199. .LP
  2200. The context manager provides a way of associating data with an X resource ID
  2201. (mostly typically a window) in your program.  
  2202. Note that this is local to your program;
  2203. the data is not stored in the server on a property list.
  2204. Any amount of data in any number of pieces can be associated with a
  2205. resource ID,
  2206. and each piece of data has a type associated with it.  
  2207. The context manager requires knowledge of the resource ID
  2208. and type to store or retrieve data.
  2209. .LP
  2210. Essentially, the context manager can be viewed as a two-dimensional, 
  2211. sparse array:  one dimension is subscripted by the X resource ID
  2212. and the other by a context type field.
  2213. Each entry in the array contains a pointer to the data.
  2214. Xlib provides context management functions with which you can
  2215. save data values, get data values, delete entries, and create a unique
  2216. context type.
  2217. The symbols used are in
  2218. .Pn < X11/Xutil.h >.
  2219. .LP
  2220. .sp
  2221. To save a data value that corresponds to a resource ID and context type, use
  2222. .PN XSaveContext .
  2223. .IN "XSaveContext" "" "@DEF@"
  2224. .\" Start marker code here
  2225. .FD 0
  2226. int XSaveContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata\fP\^)
  2227. .br
  2228.       Display *\fIdisplay\fP\^;    
  2229. .br
  2230.       XID \fIrid\fP\^;
  2231. .br
  2232.       XContext \fIcontext\fP\^;
  2233. .br
  2234.       XPointer \fIdata\fP\^;
  2235. .FN
  2236. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2237. .IP \fIdisplay\fP 1i
  2238. Specifies the connection to the X server.
  2239. .IP \fIrid\fP 1i
  2240. Specifies the resource ID with which the data is associated.
  2241. .IP \fIcontext\fP 1i
  2242. Specifies the context type to which the data belongs.
  2243. .IP \fIdata\fP 1i
  2244. Specifies the data to be associated with the window and type.
  2245. .\" End marker code here
  2246. .LP
  2247. .\" $Header: XSContext.d,v 1.2 88/06/11 07:52:54 mento Exp $
  2248. If an entry with the specified resource ID and type already exists,
  2249. .PN XSaveContext
  2250. overrides it with the specified context.
  2251. The
  2252. .PN XSaveContext
  2253. function returns a nonzero error code if an error has occurred
  2254. and zero otherwise.
  2255. Possible errors are
  2256. .PN XCNOMEM
  2257. (out of memory).
  2258. .LP
  2259. .sp
  2260. To get the data associated with a resource ID and type, use
  2261. .PN XFindContext .
  2262. .IN "XFindContext" "" "@DEF@"
  2263. .\" Start marker code here
  2264. .FD 0
  2265. int XFindContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata_return\fP\^)
  2266. .br
  2267.       Display *\fIdisplay\fP\^;
  2268. .br
  2269.       XID \fIrid\fP\^;
  2270. .br
  2271.       XContext \fIcontext\fP\^;
  2272. .br
  2273.       XPointer *\fIdata_return\fP\^;    
  2274. .FN
  2275. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2276. .IP \fIdisplay\fP 1i
  2277. Specifies the connection to the X server.
  2278. .IP \fIrid\fP 1i
  2279. Specifies the resource ID with which the data is associated.
  2280. .IP \fIcontext\fP 1i
  2281. Specifies the context type to which the data belongs.
  2282. .IP \fIdata_return\fP 1i
  2283. Returns the data.
  2284. .\" End marker code here
  2285. .LP
  2286. .\" $Header: XFContext.d,v 1.2 88/06/11 07:50:11 mento Exp $
  2287. Because it is a return value,
  2288. the data is a pointer.
  2289. The
  2290. .PN XFindContext
  2291. function returns a nonzero error code if an error has occurred
  2292. and zero otherwise.
  2293. Possible errors are
  2294. .PN XCNOENT
  2295. (context-not-found).
  2296. .LP
  2297. .sp
  2298. To delete an entry for a given resource ID and type, use
  2299. .PN XDeleteContext .
  2300. .IN "XDeleteContext" "" "@DEF@"
  2301. .\" Start marker code here
  2302. .FD 0
  2303. int XDeleteContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP\^)
  2304. .br
  2305.       Display *\fIdisplay\fP\^;
  2306. .br
  2307.       XID \fIrid\fP;
  2308. .br
  2309.       XContext \fIcontext\fP;
  2310. .FN
  2311. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2312. .IP \fIdisplay\fP 1i
  2313. Specifies the connection to the X server.
  2314. .IP \fIrid\fP 1i
  2315. Specifies the resource ID with which the data is associated.
  2316. .IP \fIcontext\fP 1i
  2317. Specifies the context type to which the data belongs.
  2318. .\" End marker code here
  2319. .LP
  2320. .\" $Header: XDContext.d,v 1.3 88/08/20 10:50:15 mento Exp $
  2321. The
  2322. .PN XDeleteContext
  2323. function deletes the entry for the given resource ID 
  2324. and type from the data structure.
  2325. This function returns the same error codes that
  2326. .PN XFindContext
  2327. returns if called with the same arguments.
  2328. .PN XDeleteContext
  2329. does not free the data whose address was saved.
  2330. .LP
  2331. .sp
  2332. To create a unique context type that may be used in subsequent calls to
  2333. .PN XSaveContext 
  2334. and
  2335. .PN XFindContext ,
  2336. use
  2337. .PN XUniqueContext .
  2338. .IN "XUniqueContext" "" "@DEF@"
  2339. .\" Start marker code here
  2340. .FD 0
  2341. XContext XUniqueContext(\^)
  2342. .FN
  2343. .\" End marker code here
  2344. .bp
  2345.