home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH11 < prev    next >
Encoding:
Text File  |  1991-08-27  |  72.8 KB  |  2,469 lines
  1. .\" $XConsortium: CH11,v 1.8 91/08/27 10:03:30 swick Exp $
  2. .\"
  3. .\" Copyright 1985, 1986, 1987, 1988, 1991
  4. .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
  5. .\" and Digital Equipment Corporation, Maynard, Massachusetts.
  6. .\"
  7. .\" Permission to use, copy, modify and distribute this documentation for any
  8. .\" purpose and without fee is hereby granted, provided that the above copyright
  9. .\" notice appears in all copies and that both that copyright notice and this
  10. .\" permission notice appear in supporting documentation, and that the name of
  11. .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
  12. .\" to distribution of the software without specific, written prior permission.
  13. .\" M.I.T and Digital makes no representations about the suitability of the
  14. .\" software described herein for any purpose.
  15. .\" It is provided ``as is'' without express or implied warranty.
  16. \&
  17. .sp 1
  18. .ce 3
  19. \s+1\fBChapter 11\fP\s-1
  20.  
  21. \s+1\fBUtility Functions\fP\s-1
  22. .sp 2
  23. .nr H1 11
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 11 \- Utility Functions
  31. .XE
  32. The \*(xI provide a number of utility functions that you can use to
  33. .IP \(bu 5
  34. Determine the number of elements in an array.
  35. .IP \(bu 5
  36. Translate strings to widget instances.
  37. .IP \(bu 5
  38. Manage memory usage.
  39. .IP \(bu 5
  40. Share graphics contexts.
  41. .IP \(bu 5
  42. Manipulate selections.
  43. .IP \(bu 5
  44. Merge exposure events into a region.
  45. .IP \(bu 5
  46. Translate widget coordinates.
  47. .IP \(bu 5
  48. Locate a widget given a window id.
  49. .IP \(bu 5
  50. Handle errors.
  51. .IP \(bu 5
  52. Set the WM_COLORMAP_WINDOWS property.
  53. .IP \(bu 5
  54. Locate files by name with string substitutions.
  55.  
  56. .NH 2
  57. Determining the Number of Elements in an Array
  58. .XS
  59. \fB\*(SN Determining the Number of Elements in an Array\fP
  60. .XE
  61. .LP
  62. To determine the number of elements in a fixed-size array, use
  63. .PN XtNumber .
  64. .IN "XtNumber" "" "@DEF@"
  65. .FD 0
  66. Cardinal XtNumber(\fIarray\fP)
  67. .br
  68.       \fIArrayType array\fP;
  69. .FN
  70. .IP \fIarray\fP 1i
  71. Specifies a fixed-size array of arbitrary type.
  72. .LP
  73. The
  74. .PN XtNumber
  75. macro returns the number of elements allocated to the array.
  76.  
  77. .NH 2
  78. Translating Strings to Widget Instances
  79. .XS
  80. \fB\*(SN Translating Strings to Widget Instances\fP
  81. .XE
  82. .LP
  83. To translate a widget name to a widget instance, use
  84. .PN XtNameToWidget .
  85. .IN "XtNameToWidget" "" "@DEF@"
  86. .FD 0
  87. Widget XtNameToWidget(\fIreference\fP, \fInames\fP)
  88. .br
  89.       Widget \fIreference\fP;
  90. .br
  91.       String \fInames\fP;
  92. .FN
  93. .IP \fIreference\fP 1i
  94. Specifies the widget from which the search is to start.  \*(cI
  95. .IP \fInames\fP 1i
  96. Specifies the partially qualified name of the desired widget.
  97. .LP
  98. The
  99. .PN XtNameToWidget
  100. function searches for a descendant of the \fIreference\fP
  101. widget whose name matches the specified names.  The \fInames\fP parameter
  102. specifies a simple object name or a series of simple object name
  103. components separated by periods or asterisks.
  104. .PN XtNameToWidget
  105. returns the descendant with the shortest name matching the specification
  106. according to the following rules, where child is either a pop-up child
  107. or a normal child if the widget's class is a subclass of
  108. Composite :
  109. .IP \(bu 5
  110. Enumerate the object subtree rooted at the reference widget in
  111. breadth-first order, qualifying the name of each object with the
  112. names of all its ancestors up to but not including the reference
  113. widget.  The ordering between children of a common parent is
  114. not defined.
  115. .IP \(bu 5
  116. Return the first object in the enumeration that matches the
  117. specified name, where each component of \fInames\fP matches exactly the
  118. corresponding component of the qualified object name, and asterisk
  119. matches any series of components, including none.
  120. .IP \(bu 5
  121. If no match is found, return NULL.
  122. .LP
  123. Since breadth-first traversal is specified, the descendant with the
  124. shortest matching name (i.e., the fewest number of components), if any,
  125. will always be returned.  However, since the order of enumeration of
  126. children is undefined and since the \*(xI do not require that all
  127. children of a widget have unique names,
  128. .PN XtNameToWidget
  129. may return any
  130. child that matches if there are multiple objects in the subtree with
  131. the same name.  Consecutive separators (periods or asterisks)
  132. including at least one asterisk are treated as a single asterisk.
  133. Consecutive periods are treated as a single period.
  134.  
  135. .NH 2
  136. Managing Memory Usage
  137. .XS
  138. \fB\*(SN Managing Memory Usage\fP
  139. .XE
  140. .LP
  141. The \*(xI' memory management functions provide uniform checking for
  142. null pointers and error reporting on memory allocation errors.
  143. These functions are completely compatible with their standard C language 
  144. runtime counterparts
  145. .PN malloc ,
  146. .PN calloc ,
  147. .PN realloc ,
  148. and
  149. .PN free
  150. with the following added functionality:
  151. .IP \(bu 5
  152. .PN XtMalloc ,
  153. .PN XtCalloc ,
  154. and
  155. .PN XtRealloc
  156. give an error if there is not enough memory.
  157. .IP \(bu 5
  158. .PN XtFree
  159. simply returns if passed a NULL pointer.
  160. .IP \(bu 5
  161. .PN XtRealloc
  162. simply allocates new storage if passed a NULL pointer.
  163. .LP
  164. See the standard C library documentation on
  165. .PN malloc ,
  166. .PN calloc ,
  167. .PN realloc ,
  168. and
  169. .PN free
  170. for more information.
  171. .sp
  172. .LP
  173. To allocate storage, use
  174. .PN XtMalloc .
  175. .IN "XtMalloc" "" "@DEF@"
  176. .FD 0
  177. char *XtMalloc(\fIsize\fP)
  178. .br
  179.       Cardinal \fIsize\fP;
  180. .FN
  181. .IP \fIsize\fP 1i
  182. Specifies the number of bytes desired.
  183. .LP
  184. The
  185. .PN XtMalloc
  186. function returns a pointer to a block of storage of at least 
  187. the specified \fIsize\fP bytes.
  188. If there is insufficient memory to allocate the new block,
  189. .PN XtMalloc
  190. calls
  191. .PN XtErrorMsg .
  192. .sp
  193. .LP
  194. To allocate and initialize an array, use
  195. .PN XtCalloc .
  196. .IN "XtCalloc" "" "@DEF@"
  197. .FD 0
  198. char *XtCalloc(\fInum\fP, \fIsize\fP)
  199. .br
  200.       Cardinal \fInum\fP;
  201. .br
  202.       Cardinal \fIsize\fP;
  203. .FN
  204. .IP \fInum\fP 1i
  205. Specifies the number of array elements to allocate.
  206. .IP \fIsize\fP 1i
  207. Specifies the size of each array element in bytes.
  208. .LP
  209. The
  210. .PN XtCalloc
  211. function allocates space for the specified number of array elements 
  212. of the specified size and initializes the space to zero.
  213. If there is insufficient memory to allocate the new block,
  214. .PN XtCalloc
  215. calls
  216. .PN XtErrorMsg .
  217. .PN XtCalloc
  218. returns the address of the allocated storage.
  219. .sp
  220. .LP
  221. To change the size of an allocated block of storage, use
  222. .PN XtRealloc .
  223. .IN "XtRealloc" "" "@DEF@"
  224. .FD 0
  225. char *XtRealloc(\fIptr\fP, \fInum\fP)
  226. .br
  227.       char *\fIptr\fP;
  228. .br
  229.       Cardinal \fInum\fP;
  230. .FN
  231. .IP \fIptr\fP 1i
  232. Specifies a pointer to the old storage allocated with
  233. .PN XtMalloc ,
  234. .PN XtCalloc ,
  235. or
  236. .PN XtRealloc ,
  237. or NULL.
  238. .IP \fInum\fP 1i
  239. Specifies number of bytes desired in new storage.
  240. .LP
  241. The
  242. .PN XtRealloc
  243. function changes the size of a block of storage, possibly moving it.
  244. Then it copies the old contents (or as much as will fit) into the new block
  245. and frees the old block.
  246. If there is insufficient memory to allocate the new block,
  247. .PN XtRealloc
  248. calls
  249. .PN XtErrorMsg .
  250. If \fIptr\fP is NULL,
  251. .PN XtRealloc
  252. simply calls
  253. .PN XtMalloc .
  254. .PN XtRealloc
  255. then returns the address of the new block.
  256. .sp
  257. .LP
  258. To free an allocated block of storage, use
  259. .PN XtFree .
  260. .IN "XtFree" "" "@DEF@"
  261. .FD 0
  262. void XtFree(\fIptr\fP)
  263. .br
  264.       char *\fIptr\fP;
  265. .FN
  266. .IP \fIptr\fP 1i
  267. Specifies a pointer to a block of storage allocated with
  268. .PN XtMalloc ,
  269. .PN XtCalloc ,
  270. or
  271. .PN XtRealloc ,
  272. or NULL.
  273. .LP
  274. The
  275. .PN XtFree
  276. function returns storage, allowing it to be reused.
  277. If \fIptr\fP is NULL,
  278. .PN XtFree
  279. returns immediately.
  280. .sp
  281. .LP
  282. To allocate storage for a new instance of a type, use
  283. .PN XtNew .
  284. .IN "XtNew" "" "@DEF@"
  285. .FD 0
  286. \fItype\fP *XtNew(\fItype\fP)
  287. .br
  288.       \fItype t\fP;
  289. .FN
  290. .IP \fItype\fP 1i
  291. Specifies a previously declared type.
  292. .LP
  293. .PN XtNew
  294. returns a pointer to the allocated storage.
  295. If there is insufficient memory to allocate the new block,
  296. .PN XtNew
  297. calls
  298. .PN XtErrorMsg .
  299. .PN XtNew
  300. is a convenience macro that calls
  301. .PN XtMalloc
  302. with the following arguments specified:
  303. .LP
  304. .Ds
  305. .TA .5i
  306. .ta .5i
  307. ((type *) XtMalloc((unsigned) sizeof(type)))
  308. .De
  309. .LP
  310. The storage allocated by
  311. .PN XtNew
  312. should be freed using
  313. .PN XtFree .
  314. .sp
  315. .LP
  316. To copy an instance of a string, use
  317. .PN XtNewString .
  318. .IN "XtNewString" "" "@DEF@"
  319. .FD 0
  320. String XtNewString(\fIstring\fP)
  321. .br
  322.       String \fIstring\fP;
  323. .FN
  324. .IP \fIstring\fP 1i
  325. Specifies a previously declared string.
  326. .LP
  327. .PN XtNewString
  328. returns a pointer to the allocated storage.
  329. If there is insufficient memory to allocate the new block,
  330. .PN XtNewString
  331. calls
  332. .PN XtErrorMsg .
  333. .PN XtNewString
  334. is a convenience macro that calls
  335. .PN XtMalloc
  336. with the following arguments specified:
  337. .LP
  338. .Ds 
  339. .TA .5i
  340. .ta .5i
  341. (strcpy(XtMalloc((unsigned)strlen(str) + 1), str))
  342. .De
  343. .LP
  344. The storage allocated by
  345. .PN XtNewString
  346. should be freed using
  347. .PN XtFree .
  348.  
  349. .NH 2
  350. Sharing Graphics Contexts
  351. .XS
  352. \fB\*(SN Sharing Graphics Contexts\fP
  353. .XE
  354. .LP
  355. The \*(xI provide a mechanism whereby cooperating objects can share a
  356. graphics context (GC), thereby reducing both the number of GCs
  357. created and the total number of server calls in any given application.
  358. The mechanism is a simple caching scheme
  359. and allows for clients to declare both modifiable and nonmodifiable
  360. fields of the shared GCs.
  361. .LP
  362. To obtain a shareable GC with modifiable fields, use
  363. .PN XtAllocateGC .
  364. .IN "XtAllocateGC" "" "@DEF@"
  365. .FD 0
  366. GC XtAllocateGC(\fIwidget\fP, \fIdepth\fP, \fIvalue_mask\fP, \fIvalues\fP, \
  367. \fIdynamic_mask\fP, \fIunused_mask\fP)
  368. .br
  369.       Widget \fIobject\fP;
  370. .br
  371.       Cardinal \fIdepth\fP;
  372. .br
  373.       XtGCMask \fIvalue_mask\fP;
  374. .br
  375.       XGCValues *\fIvalues\fP;
  376. .br
  377.       XtGCMask \fIdynamic_mask\fP;
  378. .br
  379.       XtGCMask \fIunused_mask\fP;
  380. .FN
  381. .IP \fIobject\fP 1i
  382. Specifies an object, giving the screen for which the
  383. returned GC is valid.  \*(oI
  384. .IP \fIdepth\fP 1i
  385. Specifies the depth for which the returned GC is valid, or 0.
  386. .IP \fIvalue_mask\fP 1i
  387. Specifies fields of the GC that are initialized from \fIvalues\fP.
  388. .IP \fIvalues\fP 1i
  389. Specifies the values for the initialized fields.
  390. .IP \fIdynamic_mask\fP 1i
  391. Specifies fields of the GC that may be modified by the caller.
  392. .IP \fIunused_mask\fP 1i
  393. Specifies fields of the GC that will not be used by the caller.
  394.  
  395. .LP
  396. The
  397. .PN XtAllocateGC
  398. function returns a shareable GC that may be
  399. modified by the client.  The \fIscreen\fP field of the specified
  400. widget or of the nearest widget ancestor of the specified
  401. object and the specified \fIdepth\fP argument supply
  402. the root and drawable depths for which the GC is to be
  403. valid.  If \fIdepth\fP is zero the depth is taken from the
  404. \fIdepth\fP field of the specified widget or of the nearest
  405. widget ancestor of the specified object.
  406.  
  407. The \fIvalue_mask\fP argument specifies fields of the GC
  408. that will be initialized with the respective member of the
  409. \fIvalues\fP structure.  The \fIdynamic_mask\fP argument specifies fields
  410. that the caller intends to modify during program execution.
  411. The caller must insure that the corresponding GC field is set
  412. prior to each use of the GC.  The \fIunused_mask\fP argument
  413. specifies fields of the GC that are of no interest to the
  414. caller.  The caller may make no assumptions about the contents
  415. of any fields specified in \fIunused_mask\fP.  The caller may assume
  416. that at all times all fields not specified in either
  417. \fIdynamic_mask\fP or \fIunused_mask\fP have their default value if not
  418. specified in \fIvalue_mask\fP or the value specified by \fIvalues\fP.
  419. If a field is specified in both \fIvalue_mask\fP and \fIdynamic_mask\fP,
  420. the effect is as if it were specified only in \fIdynamic_mask\fP
  421. and then immediately set to the value in \fIvalues\fP.  If a field
  422. is set in \fIunused_mask\fP and also in either \fIvalue_mask\fP or
  423. \fIdynamic_mask\fP, the specification in \fIunused_mask\fP is ignored.
  424.  
  425. .PN XtAllocateGC
  426. tries to minimize the number of unique GCs
  427. created by comparing the arguments with those of previous
  428. calls and returning an existing GC when there are no
  429. conflicts.
  430. .PN XtAllocateGC
  431. may modify and return an existing GC if it was allocated with a
  432. nonzero \fIunused_mask\fP.
  433.  
  434. .sp
  435. .LP
  436. To obtain a shareable GC with no modifiable fields, use
  437. .PN XtGetGC .
  438.  
  439. .IN "XtGetGC" "" "@DEF@"
  440. .FD 0
  441. GC XtGetGC(\fIobject\fP, \fIvalue_mask\fP, \fIvalues\fP)
  442. .br
  443.       Widget \fIobject\fP;
  444. .br
  445.       XtGCMask \fIvalue_mask\fP;
  446. .br
  447.       XGCValues *\fIvalues\fP;
  448. .FN
  449. .IP \fIobject\fP 1i
  450. Specifies an object, giving the screen and depth for which the
  451. returned GC is valid.  \*(oI
  452. .IP \fIvalue_mask\fP 1i
  453. Specifies which fields of the \fIvalues\fP structure are specified.
  454. .IP \fIvalues\fP 1i
  455. Specifies the actual values for this GC.
  456. .LP
  457. The
  458. .PN XtGetGC
  459. function returns a shareable, read-only GC.
  460. The parameters to this function are the same as those for
  461. .PN XCreateGC 
  462. except that an Object is passed instead of a Display.
  463. .PN XtGetGC
  464. is equivalent to
  465. .PN XtAllocateGC
  466. with \fIdepth\fP, \fIdynamic_mask\fP, and \fIunused_mask\fP all zero.
  467. .LP
  468. .PN XtGetGC
  469. shares only GCs in which all values in the GC returned by
  470. .PN XCreateGC
  471. are the same.
  472. In particular, it does not use the \fIvalue_mask\fP provided to
  473. determine which fields of the GC a widget considers relevant.
  474. The \fIvalue_mask\fP is used only to tell the server which fields should be
  475. filled in from \fIvalues\fP and which it should fill in with default values.
  476.  
  477. .sp
  478. .LP
  479. To deallocate a shared GC when it is no longer needed, use
  480. .PN XtReleaseGC .
  481. .IN "XtReleaseGC" "" "@DEF@"
  482. .FD 0
  483. void XtReleaseGC(\fIobject\fP, \fIgc\fP)
  484. .br
  485.       Widget \fIobject\fP;
  486. .br
  487.       GC \fIgc\fP;
  488. .FN
  489. .IP \fIobject\fP 1i
  490. Specifies any object on the Display for which the GC was created.  \*(oI
  491. .IP \fIgc\fP 1i
  492. Specifies the shared GC obtained with either
  493. .PN XtAllocateGC
  494. or
  495. .PN XtGetGC .
  496. .LP
  497. References to shareable GCs are counted and a free request is generated to the
  498. server when the last user of a given GC releases it.
  499.  
  500. .NH 2
  501. Managing Selections
  502. .XS
  503. \*(SN Managing Selections
  504. .XE
  505. .LP
  506. Arbitrary widgets in multiple applications can communicate 
  507. with each other by means of the \*(xI global selection mechanism,
  508. which conforms to the specifications in the \fI\*(xC\fP.
  509. The \*(xI supply functions for providing and receiving selection data in
  510. one logical piece (atomic transfers)
  511. or in smaller logical segments (incremental transfers).
  512. .LP
  513. The incremental interface is provided for a selection owner or
  514. selection requestor that cannot or prefers not to pass the selection
  515. value to and from the \*(xI in a single call.  For instance,
  516. either an application that is running on a machine with limited memory
  517. may not be able to store the entire selection value in memory, or a
  518. selection owner may already have the selection value available in
  519. discrete chunks, and it would be more efficient not to have to
  520. allocate additional storage to copy the pieces contiguously.  Any
  521. owner or requestor that prefers to deal with the selection value in
  522. segments can use the incremental interfaces to do so.
  523. The transfer between the selection owner or requestor and the \*(xI is not
  524. required to match the underlying
  525. transport protocol between the application and the X server;
  526. the \*(xI will break a too large selection 
  527. into smaller pieces for transport if necessary
  528. and will coalesce a selection transmitted incrementally if the value
  529. was requested atomically.
  530.  
  531. .NH 3
  532. Setting and Getting the Selection Timeout Value
  533. .XS
  534. \fB\*(SN Setting and Getting the Selection Timeout Value\fP
  535. .XE
  536. .LP
  537. To set the \*(xI selection timeout, use
  538. .PN XtAppSetSelectionTimeout .
  539. .IN "XtAppSetSelectionTimeout" "" "@DEF@"
  540. .FD 0
  541. void XtAppSetSelectionTimeout(\fIapp_context\fP, \fItimeout\fP)
  542. .br
  543.     XtAppContext \fIapp_context\fP;
  544. .br
  545.     unsigned long \fItimeout\fP;
  546. .FN
  547. .IP \fIapp_context\fP 1i
  548. Specifies the application context.
  549. .IP \fItimeout\fP 1i
  550. Specifies the selection timeout in milliseconds.
  551. .sp
  552. .LP
  553. To get the current selection timeout value, use
  554. .PN XtAppGetSelectionTimeout .
  555. .IN "XtAppGetSelectionTimeout" "" "@DEF@"
  556. .FD 0
  557. unsigned long XtAppGetSelectionTimeout(\fIapp_context\fP)
  558. .br
  559.      XtAppContext \fIapp_context\fP;
  560. .FN
  561. .IP \fIapp_context\fP 1i
  562. Specifies the application context.
  563. .LP
  564. The
  565. .PN XtAppGetSelectionTimeout
  566. function returns the current selection timeout value, in milliseconds.
  567. The selection timeout is the time within which the two communicating 
  568. applications must respond to one another.
  569. The initial timeout value is set by the 
  570. selectionTimeout
  571. .IN "selectionTimeout"
  572. application resource as retrieved by
  573. .PN XtDisplayInitialize .
  574. If
  575. selectionTimeout
  576. is not specified,
  577. the default is five seconds.
  578.  
  579. .NH 3
  580. Using Atomic Transfers
  581. .XS
  582. \*(SN Using Atomic Transfers
  583. .XE
  584. .LP
  585. When using atomic transfers, the owner will completely
  586. process one selection request at a time.
  587. The owner may consider each request individually,
  588. since there is no possibility for overlap
  589. between evaluation of two requests.
  590.  
  591. .NH 4
  592. Atomic Transfer Procedures
  593. .XS
  594. \*(SN Atomic Transfer Procedures
  595. .XE
  596. .IN "Selections" "atomic"
  597. .LP
  598. The following procedures are used by the selection owner when
  599. providing selection data in a single unit.
  600. .LP
  601. The procedure pointer specified by the owner to supply the selection
  602. data to the \*(xI is of type
  603. .PN XtConvertSelectionProc .
  604. .LP
  605. .IN "XtConvertSelectionProc" "" "@DEF@"
  606. .FD 0
  607. typedef Boolean (*XtConvertSelectionProc)(Widget, Atom*, Atom*, Atom*,
  608. .br
  609.                       XtPointer*, unsigned long*, int*);
  610. .br
  611.     Widget \fIw\fP;
  612. .br
  613.     Atom *\fIselection\fP;
  614. .br
  615.     Atom *\fItarget\fP;
  616. .br
  617.     Atom *\fItype_return\fP;
  618. .br
  619.     XtPointer *\fIvalue_return\fP;
  620. .br
  621.     unsigned long *\fIlength_return\fP;
  622. .br
  623.     int *\fIformat_return\fP;
  624. .FN
  625. .IP \fIw\fP 1i
  626. Specifies the widget that currently owns this selection.
  627. .IP \fIselection\fP 1i
  628. Specifies the atom naming the selection requested
  629. (for example,
  630. .PN XA_PRIMARY
  631. or 
  632. .PN XA_SECONDARY ).
  633. .IP \fItarget\fP 1i
  634. Specifies the target type of the selection that has been requested,
  635. which indicates the desired information about the selection 
  636. (for example, File Name, Text, Window).
  637. .IP \fItype_return\fP 1i
  638. Specifies a pointer to an atom into which the property type of the 
  639. converted value of the selection is to be stored.
  640. For instance, either File Name or Text might have property type 
  641. .PN XA_STRING .
  642. .IP \fIvalue_return\fP 1i
  643. Specifies a pointer into which a pointer to the converted value of the 
  644. selection is to be stored.
  645. The selection owner is responsible for allocating this storage.
  646. If the selection owner has provided an
  647. .PN XtSelectionDoneProc
  648. for the selection, 
  649. this storage is owned by the selection owner; 
  650. otherwise, it is owned by the \*(xI selection mechanism, 
  651. which frees it by calling
  652. .PN XtFree
  653. when it is done with it.
  654. .IP \fIlength_return\fP 1i
  655. Specifies a pointer into which the number of elements in \fIvalue_return\fP,
  656. each of size indicated by \fIformat_return\fP, is to be stored.
  657. .IP \fIformat_return\fP 1i
  658. Specifies a pointer into which the size in bits of the data elements 
  659. of the selection value is to be stored.
  660. .LP
  661. This procedure is called by the \*(xI selection mechanism 
  662. to get the value of a selection as a given type 
  663. from the current selection owner.
  664. It returns 
  665. .PN True 
  666. if the owner successfully converted the selection to the target type or
  667. .PN False
  668. otherwise.
  669. If the procedure returns
  670. .PN False ,
  671. the values of the return arguments are undefined.
  672. Each
  673. .PN XtConvertSelectionProc
  674. should respond to target value
  675. .PN TARGETS 
  676. by returning a value containing the list of the targets
  677. into which it is
  678. prepared to convert the selection.
  679. The value returned in
  680. \fIformat_return\fP must be one of 8, 16, or 32 to allow the server to
  681. byte-swap the data if necessary.
  682. .LP
  683. .IN "Selections" "MULTIPLE"
  684. .IN "Selections" "TIMESTAMP"
  685. This procedure does not need to worry about responding to the
  686. MULTIPLE or the TIMESTAMP target values (see Section 2.6.2 in the \fI\*(xC\fP).
  687. A selection request with
  688. the MULTIPLE target type will be transparently transformed into a
  689. series of calls to this procedure, one for each target type, and a
  690. selection request with the TIMESTAMP target value will be answered
  691. automatically by the \*(xI using the time specified in the
  692. call to
  693. .PN XtOwnSelection
  694. or
  695. .PN XtOwnSelectionIncremental .
  696. .sp
  697. .LP
  698. To retrieve the
  699. .PN SelectionRequest
  700. event that triggered the
  701. .PN XtConvertSelectionProc
  702. procedure, use
  703. .PN XtGetSelectionRequest .
  704. .IN "XtGetSelectionRequest" "" "@DEF@"
  705. .FD 0
  706. XSelectionRequestEvent *XtGetSelectionRequest(\fIw\fP, \fIselection\fP, \
  707. \fIrequest_id\fP)
  708. .br
  709.       Widget \fIw\fP;
  710. .br
  711.       Atom \fIselection\fP;
  712. .br
  713.       XtRequestId \fIrequest_id\fP;
  714. .FN
  715. .IP \fIw\fP 1i
  716. Specifies the widget that currently owns this selection.  \*(cI
  717. .IP \fIselection\fP 1i
  718. Specifies the selection being processed.
  719. .IP \fIrequest_id\fP 1i
  720. Specifies the requestor id in the case of incremental
  721. selections, or NULL in the case of atomic transfers.
  722. .LP
  723. .PN XtGetSelectionRequest
  724. may only be called from within an
  725. .PN XtConvertSelectionProc
  726. procedure and returns a pointer to the
  727. .PN SelectionRequest
  728. event that caused the conversion procedure to be invoked.
  729. \fIRequest_id\fP specifies a unique id for the individual request in the
  730. case that multiple incremental transfers are outstanding.  For atomic
  731. transfers, \fIrequest_id\fP must be specified as NULL.  If no
  732. .PN SelectionRequest
  733. event is being processed for the specified
  734. \fIwidget\fP, \fIselection\fP, and \fIrequest_id\fP,
  735. .PN XtGetSelectionRequest
  736. returns NULL.
  737. .sp
  738. .LP
  739. The procedure pointer specified by the owner when it desires
  740. notification upon losing ownership is of type
  741. .PN XtLoseSelectionProc .
  742. .LP
  743. .IN "XtLoseSelectionProc" "" "@DEF@"
  744. .FD 0
  745. typedef void (*XtLoseSelectionProc)(Widget, Atom*);
  746. .br
  747.     Widget \fIw\fP;
  748. .br
  749.     Atom *\fIselection\fP;
  750. .FN
  751. .IP \fIw\fP 1i
  752. Specifies the widget that has lost selection ownership.
  753. .IP \fIselection\fP 1i
  754. Specifies the atom naming the selection.
  755. .LP
  756. This procedure is called by the \*(xI selection mechanism
  757. to inform the specified widget that it has lost the given selection.
  758. Note that this procedure does not ask the widget to relinquish the 
  759. selection ownership; it is merely informative.
  760. .sp
  761. .LP
  762. The procedure pointer specified by the owner when it desires
  763. notification of receipt of the data or when it manages the storage
  764. containing the data is of type
  765. .PN XtSelectionDoneProc .
  766. .LP
  767. .IN "XtSelectionDoneProc" "" "@DEF@"
  768. .FD 0
  769. typedef void (*XtSelectionDoneProc)(Widget, Atom*, Atom*);
  770. .br
  771.       Widget \fIw\fP;
  772. .br
  773.       Atom *\fIselection\fP;
  774. .br
  775.       Atom *\fItarget\fP;
  776. .FN
  777. .IP \fIw\fP 1i
  778. Specifies the widget that owns the converted selection.
  779. .IP \fIselection\fP 1i
  780. Specifies the atom naming the selection that was converted.
  781. .IP \fItarget\fP 1i
  782. Specifies the target type to which the conversion was done.
  783. .LP
  784. This procedure is called by the \*(xI selection mechanism
  785. to inform the selection owner that a selection requestor has successfully
  786. retrieved a selection value.
  787. If the selection owner has registered an
  788. .PN XtSelectionDoneProc ,
  789. it should expect it to be called once for each conversion that it performs,
  790. after the converted value has been successfully transferred
  791. to the requestor.
  792. If the selection owner has registered an
  793. .PN XtSelectionDoneProc ,
  794. it also owns the storage containing the converted
  795. selection value.
  796.  
  797. .NH 4
  798. Getting the Selection Value
  799. .XS
  800. \*(SN Getting the Selection Value
  801. .XE
  802. .LP
  803. The procedure pointer specified by the requestor to receive the
  804. selection data from the \*(xI is of type
  805. .PN XtSelectionCallbackProc .
  806. .LP
  807. .IN "XtSelectionCallbackProc" "" "@DEF@"
  808. .FD 0
  809. typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom*, Atom*, \
  810. XtPointer, unsigned long*, int*);
  811. .br
  812.       Widget \fIw\fP;
  813. .br
  814.       XtPointer \fIclient_data\fP;
  815. .br
  816.       Atom *\fIselection\fP;
  817. .br
  818.       Atom *\fItype\fP;
  819. .br
  820.       XtPointer \fIvalue\fP;
  821. .br
  822.       unsigned long *\fIlength\fP;
  823. .br
  824.       int *\fIformat\fP;
  825. .FN
  826. .IP \fIw\fP 1i
  827. Specifies the widget that requested the selection value.
  828. .IP \fIclient_data\fP 1i
  829. Specifies a value passed in by the widget when it requested the
  830. selection.
  831. .IP \fIselection\fP 1i
  832. Specifies the name of the selection that was requested.
  833. .IP \fItype\fP 1i
  834. Specifies the representation type of the selection value (for example,
  835. .PN XA_STRING ).
  836. Note that it is not the target that was requested (which the client
  837. must remember for itself) but the type that
  838. is used to represent the target.
  839. The special symbolic constant
  840. .PN XT_CONVERT_FAIL 
  841. is used to indicate that the selection conversion failed because the
  842. selection owner did not respond within the \*(xI selection timeout
  843. interval.
  844. .IP \fIvalue\fP 1i
  845. Specifies a pointer to the selection value.
  846. The requesting client owns this storage and is responsible for freeing it 
  847. by calling
  848. .PN XtFree
  849. when it is done with it.
  850. .IP \fIlength\fP 1i
  851. Specifies the number of elements in \fIvalue\fP.
  852. .IP \fIformat\fP 1i
  853. Specifies the size in bits of the data elements of value.
  854. .LP
  855. This procedure is called by the \*(xI selection mechanism to deliver the
  856. requested selection to the requestor.
  857. .LP
  858. If the
  859. .PN SelectionNotify
  860. event returns a property of
  861. .PN None ,
  862. meaning the conversion has been refused because there is no owner for the
  863. specified selection or the owner cannot convert the selection to the
  864. requested target for any reason, the procedure is called with a value
  865. of NULL and a length of zero.
  866. .sp
  867. .LP
  868. To obtain the selection value in a single logical unit, use
  869. .PN XtGetSelectionValue
  870. or
  871. .PN XtGetSelectionValues .
  872. .IN "XtGetSelectionValue" "" "@DEF@"
  873. .FD 0
  874. void XtGetSelectionValue(\fIw\fP, \fIselection\fP, \fItarget\fP, \
  875. \fIcallback\fP, \fIclient_data\fP, \fItime\fP)
  876. .br
  877.       Widget \fIw\fP;
  878. .br
  879.       Atom \fIselection\fP;
  880. .br
  881.       Atom \fItarget\fP;
  882. .br
  883.       XtSelectionCallbackProc \fIcallback\fP;
  884. .br
  885.       XtPointer \fIclient_data\fP;
  886. .br
  887.       Time \fItime\fP;
  888. .FN
  889. .IP \fIw\fP 1i
  890. Specifies the widget making the request.  \*(cI
  891. .IP \fIselection\fP 1i
  892. Specifies the particular selection desired; for example,
  893. .PN XA_PRIMARY .
  894. .IP \fItarget\fP 1i
  895. Specifies the type of information needed about the selection.
  896. .IP \fIcallback\fP 1i
  897. Specifies the procedure to be called when the selection value
  898. has been obtained.
  899. Note that this is how the selection value is communicated back to the client.
  900. .IP \fIclient_data\fP 1i
  901. Specifies additional data to be passed to the specified procedure
  902. when it is called.
  903. .IP \fItime\fP 1i
  904. Specifies the timestamp that indicates when the selection request was
  905. initiated.
  906. This should be the timestamp of the event that triggered this request;
  907. the value 
  908. .PN CurrentTime 
  909. is not acceptable.
  910. .LP
  911. The
  912. .PN XtGetSelectionValue
  913. function requests the value of the selection converted to 
  914. the target type. 
  915. The specified callback will be called at some time after 
  916. .PN XtGetSelectionValue 
  917. is called, when the selection data is received from the X server.
  918. It may be called before or after 
  919. .PN XtGetSelectionValue 
  920. returns.
  921. For more information about \fIselection\fP, \fItarget\fP, and
  922. \fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
  923. .sp
  924. .LP
  925. .IN "XtGetSelectionValues" "" "@DEF@"
  926. .FD 0
  927. void XtGetSelectionValues(\fIw\fP, \fIselection\fP, \fItargets\fP, \
  928. \fIcount\fP, \fIcallback\fP, \fIclient_data\fP, \fItime\fP)
  929. .br
  930.       Widget \fIw\fP;
  931. .br
  932.       Atom \fIselection\fP;
  933. .br
  934.       Atom *\fItargets\fP;
  935. .br
  936.       int \fIcount\fP;
  937. .br
  938.       XtSelectionCallbackProc \fIcallback\fP;
  939. .br
  940.       XtPointer *\fIclient_data\fP;
  941. .br
  942.       Time \fItime\fP;
  943. .FN
  944. .IP \fIw\fP 1i
  945. Specifies the widget making the request.  \*(cI
  946. .IP \fIselection\fP 1i
  947. Specifies the particular selection desired (that is, primary or secondary).
  948. .IP \fItargets\fP 1i
  949. Specifies the types of information needed about the selection.
  950. .IP \fIcount\fP 1i
  951. Specifies the length of \fIthe\fP targets and \fIclient_data\fP lists.
  952. .IP \fIcallback\fP 1i
  953. Specifies the callback procedure
  954. to be called with each selection value obtained.
  955. Note that this is how the selection values are communicated back to the
  956. client.
  957. .IP \fIclient_data\fP 1i
  958. Specifies a list of additional data values, one for each target type,
  959. that are passed to the callback procedure when it is called for that target.
  960. .IP \fItime\fP 1i
  961. Specifies the timestamp that indicates when the selection request was
  962. initiated.
  963. This should be the timestamp of the event that triggered this request;
  964. the value 
  965. .PN CurrentTime
  966. is not acceptable.
  967. .LP
  968. The
  969. .PN XtGetSelectionValues
  970. function is similar to multiple calls to
  971. .PN XtGetSelectionValue 
  972. except that it guarantees that no other client can assert ownership
  973. between requests and therefore that all the conversions will refer to
  974. the same selection value.  The callback is invoked once for each
  975. target value with the corresponding client data.
  976. For more information about \fIselection\fP, \fItarget\fP, and
  977. \fItime\fP see Section 2.6 in the \fI\*(xC\fP.
  978.  
  979. .NH 4
  980. Setting the Selection Owner
  981. .XS
  982. \*(SN Setting the Selection Owner
  983. .XE
  984. .LP
  985. To set the selection owner and indicate that the selection value will
  986. be provided in one piece, use
  987. .PN XtOwnSelection .
  988. .IN "XtOwnSelection" "" "@DEF@"
  989. .FD 0
  990. Boolean XtOwnSelection(\fIw\fP, \fIselection\fP, \fItime\fP, \
  991. \fIconvert_proc\fP, \fIlose_selection\fP, \fIdone_proc\fP)
  992. .br
  993.       Widget \fIw\fP;
  994. .br
  995.       Atom \fIselection\fP;
  996. .br
  997.       Time \fItime\fP;
  998. .br
  999.       XtConvertSelectionProc \fIconvert_proc\fP;
  1000. .br
  1001.       XtLoseSelectionProc \fIlose_selection\fP;
  1002. .br
  1003.       XtSelectionDoneProc \fIdone_proc\fP;
  1004. .FN
  1005. .IP \fIw\fP 1i
  1006. Specifies the widget that wishes to become the owner.  \*(cI
  1007. .IP \fIselection\fP 1i
  1008. Specifies the name of the selection (for example,
  1009. .PN XA_PRIMARY ).
  1010. .IP \fItime\fP 1i
  1011. Specifies the timestamp that indicates when the ownership request was
  1012. initiated.
  1013. This should be the timestamp of the event that triggered ownership;
  1014. the value
  1015. .PN CurrentTime 
  1016. is not acceptable.
  1017. .IP \fIconvert_proc\fP 1i
  1018. Specifies the procedure to be called whenever a client requests the 
  1019. current value of the selection.
  1020. .IP \fIlose_selection\fP 1i
  1021. Specifies the procedure to be called whenever the widget has 
  1022. lost selection ownership, or NULL if the owner is not interested in being 
  1023. called back.
  1024. .IP \fIdone_proc\fP 1i
  1025. Specifies the procedure called 
  1026. after the requestor has received the selection value, or NULL if the
  1027. owner is not
  1028. interested in being called back.
  1029. .LP
  1030. The
  1031. .PN XtOwnSelection
  1032. function informs the \*(xI selection mechanism that a
  1033. widget wishes to own a selection.
  1034. It returns 
  1035. .PN True 
  1036. if the widget successfully becomes the owner and 
  1037. .PN False
  1038. otherwise.
  1039. The widget may fail to become the owner if some other widget 
  1040. has asserted ownership at a time later than this widget.
  1041. The widget can lose selection ownership either 
  1042. because some other client asserted later ownership of the selection 
  1043. or because the widget voluntarily gave up ownership of the selection.
  1044. The lose_selection procedure is not called 
  1045. if the widget fails to obtain selection ownership in the first place.
  1046. .LP
  1047. If a done_proc is specified, the client owns the storage allocated
  1048. for passing the value to the \*(xI.  If \fIdone_proc\fP is NULL,
  1049. the convert_proc must allocate storage using
  1050. .PN XtMalloc ,
  1051. .PN XtRealloc ,
  1052. or
  1053. .PN XtCalloc ,
  1054. and the value specified will be freed by the
  1055. \*(xI when the transfer is complete.
  1056. .sp
  1057. .LP
  1058. Usually, a selection owner maintains ownership indefinitely until some
  1059. other client requests ownership, at which time
  1060. the \*(xI selection mechanism informs the previous owner that it
  1061. has lost ownership of the selection.
  1062. However, in response to some user actions 
  1063. (for example, when a user deletes the information selected),
  1064. the application may with to explicitly inform the \*(xI that it
  1065. no longer is to be the selection owner by using
  1066. .PN XtDisownSelection .
  1067. .IN "XtDisownSelection" "" "@DEF@"
  1068. .FD 0
  1069. void XtDisownSelection(\fIw\fP, \fIselection\fP, \fItime\fP)
  1070. .br
  1071.       Widget \fIw\fP;
  1072. .br
  1073.       Atom \fIselection\fP;
  1074. .br
  1075.       Time \fItime\fP;
  1076. .FN
  1077. .IP \fIw\fP 1i
  1078. Specifies the widget that wishes to relinquish ownership.
  1079. .IP \fIselection\fP 1i
  1080. Specifies the atom naming the selection being given up.
  1081. .IP \fItime\fP 1i
  1082. Specifies the timestamp that indicates when the request to
  1083. relinquish selection ownership was initiated.
  1084. .LP
  1085. The
  1086. .PN XtDisownSelection
  1087. function informs the \*(xI selection mechanism that
  1088. the specified widget is to lose ownership of the selection.
  1089. If the widget does not currently own the selection, either 
  1090. because it lost the selection 
  1091. or because it never had the selection to begin with,
  1092. .PN XtDisownSelection
  1093. does nothing.
  1094. .LP
  1095. After a widget has called
  1096. .PN XtDisownSelection ,
  1097. its convert procedure is not called even if a request arrives later 
  1098. with a timestamp during the period that this widget owned the selection.
  1099. However, its done procedure will be called if a conversion that started 
  1100. before the call to
  1101. .PN XtDisownSelection
  1102. finishes after the call to
  1103. .PN XtDisownSelection .
  1104.  
  1105. .NH 3
  1106. Using Incremental Transfers
  1107. .XS
  1108. \*(SN Using Incremental Transfers
  1109. .XE
  1110. .LP
  1111. When using the incremental interface, an owner may have to process
  1112. more than one selection request for the same selection, converted to
  1113. the same target, at the same time.  The incremental functions take a
  1114. \fIrequest_id\fP argument, which is an identifier that is guaranteed to be
  1115. unique among all incremental requests that are active concurrently.
  1116. .LP
  1117. For example, consider the following:
  1118. .IP \(bu 5
  1119. Upon receiving a request for the selection value, the owner sends
  1120. the first segment.
  1121. .IP \(bu 5
  1122. While waiting to be called to provide the next segment value but
  1123. before sending it, the owner receives another request from a
  1124. different requestor for the same selection value. 
  1125. .IP \(bu 5
  1126. To distinguish between the requests, the owner uses the request_id
  1127. value.  This allows the owner to distinguish between the first
  1128. requestor, which is asking for the second segment, and the second
  1129. requestor, which is asking for the first segment. 
  1130.  
  1131. .NH 4
  1132. Incremental Transfer Procedures
  1133. .XS
  1134. \*(SN Incremental Transfer Procedures
  1135. .XE
  1136. .IN "Selections" "incremental"
  1137. .LP
  1138. The following procedures are used by selection owners who wish to
  1139. provide the selection data in multiple segments.
  1140. .LP
  1141. The procedure pointer specified by the incremental owner to supply the
  1142. selection data to the \*(xI is of type
  1143. .PN XtConvertSelectionIncrProc .
  1144. .LP
  1145. .sp
  1146. .Ds 0
  1147. typedef XtPointer XtRequestId;
  1148. .De
  1149. .IN "XtRequestId" "" "@DEF@"
  1150. .IN "XtConvertSelectionIncrProc" "" "@DEF@"
  1151. .FD 0
  1152. typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*, \
  1153. Atom*, XtPointer*,
  1154.                                unsigned long*, int*, unsigned long*, \
  1155. XtPointer, XtRequestId*);
  1156. .br
  1157.       Widget \fIw\fP;
  1158. .br
  1159.       Atom *\fIselection\fP;
  1160. .br
  1161.       Atom *\fItarget\fP;
  1162. .br
  1163.       Atom *\fItype_return\fP;
  1164. .br
  1165.       XtPointer *\fIvalue_return\fP;
  1166. .br
  1167.       unsigned long *\fIlength_return\fP;
  1168. .br
  1169.       int *\fIformat_return\fP;
  1170. .br
  1171.       unsigned long *\fImax_length\fP;
  1172. .br
  1173.       XtPointer \fIclient_data\fP;
  1174. .br
  1175.       XtRequestId *\fIrequest_id\fP;
  1176. .FN
  1177. .IP \fIw\fP 1i
  1178. Specifies the widget that currently owns this selection.
  1179. .IP \fIselection\fP 1i
  1180. Specifies the atom that names the selection requested.
  1181. .IP \fItarget\fP 1i
  1182. Specifies the type of information required about the selection.
  1183. .IP \fItype_return\fP 1i
  1184. Specifies a pointer to an atom into which the property
  1185. type of the converted value of the selection is to be
  1186. stored.
  1187. .IP \fIvalue_return\fP 1i
  1188. Specifies a pointer into which a pointer to the
  1189. converted value of the selection is to be stored.
  1190. The selection owner is responsible for allocating this storage.
  1191. .IP \fIlength_return\fP 1i
  1192. Specifies a pointer into which the number of elements
  1193. in \fIvalue_return\fP, each of size indicated by
  1194. \fIformat_return\fP, is to be stored.
  1195. .IP \fIformat_return\fP 1i
  1196. Specifies a pointer into which the size in bits of the
  1197. data elements of the selection value is to be stored so that the
  1198. server may byte-swap the data if necessary.
  1199. .IP \fImax_length\fP 1i
  1200. Specifies the maximum number of bytes which may be
  1201. transferred at any one time.
  1202. .IP \fIclient_data\fP 1i
  1203. Specifies the value passed in by the widget when it
  1204. took ownership of the selection.
  1205. .IP \fIrequest_id\fP 1i
  1206. Specifies an opaque identification for a specific request.
  1207. .LP
  1208. This procedure is called repeatedly by the \*(xI selection mechanism to get
  1209. the next incremental chunk of data from a selection owner who has
  1210. called
  1211. .PN XtOwnSelectionIncremental .
  1212. It must return
  1213. .PN True
  1214. if the procedure has succeeded in converting the selection data or
  1215. .PN False
  1216. otherwise.
  1217. On the first call with a particular request id, the owner must begin
  1218. a new incremental transfer for the requested selection and target.  On
  1219. subsequent calls with the same request id, the owner may assume that
  1220. the previously supplied value is no longer needed by the \*(xI;
  1221. that is, a fixed transfer area may be allocated and returned in \fIvalue_return\fP
  1222. for each segment to be transferred.  This procedure should store a
  1223. non-NULL value in \fIvalue_return\fP and zero in \fIlength_return\fP to indicate that the
  1224. entire selection has been delivered.  After returning this final
  1225. segment, the request id may be reused by the \*(xI to begin a
  1226. new transfer.
  1227. .LP
  1228. To retrieve the
  1229. .PN SelectionRequest
  1230. event that triggered the selection conversion procedure, use
  1231. .PN XtGetSelectionRequest ,
  1232. described in Section 11.5.2.1.
  1233. .sp
  1234. .LP
  1235. The procedure pointer specified by the incremental selection owner
  1236. when it desires notification upon no longer having ownership is of
  1237. type
  1238. .PN XtLoseSelectionIncrProc .
  1239. .IN "XtLoseSelectionIncrProc" "" "@DEF@"
  1240. .FN 0
  1241. typedef void (*XtLoseSelectionIncrProc)(Widget, Atom*, XtPointer);
  1242. .br
  1243.       Widget \fIw\fP;
  1244. .br
  1245.       Atom *\fIselection\fP;
  1246. .br
  1247.       XtPointer \fIclient_data\fP;
  1248. .FN
  1249. .IP \fIw\fP 1i
  1250. Specifies the widget that has lost the selection ownership.
  1251. .IP \fIselection\fP 1i
  1252. Specifies the atom that names the selection.
  1253. .IP \fIclient_data\fP 1i
  1254. Specifies the value passed in by the widget when it
  1255. took ownership of the selection.
  1256. .LP
  1257. This procedure, which is optional, is called by the \*(xI to
  1258. inform the selection owner that it no longer owns the selection.
  1259. .sp
  1260. .LP
  1261. The procedure pointer specified by the incremental selection owner
  1262. when it desires notification of receipt of the data or when it manages
  1263. the storage containing the data is of type
  1264. .PN XtSelectionDoneIncrProc .
  1265. .IN "XtSelectionDoneIncrProc" "" "@DEF@"
  1266. .FD 0
  1267. typedef void (*XtSelectionDoneIncrProc)(Widget, Atom*, Atom*, \
  1268. XtRequestId*, XtPointer);
  1269. .br
  1270.       Widget \fIw\fP;
  1271. .br
  1272.       Atom *\fIselection\fP;
  1273. .br
  1274.       Atom *\fItarget\fP;
  1275. .br
  1276.       XtRequestId *\fIrequest_id\fP;
  1277. .br
  1278.       XtPointer \fIclient_data\fP;
  1279. .FN
  1280. .IP \fIw\fP 1i
  1281. Specifies the widget that owns the selection.
  1282. .IP \fIselection\fP 1i
  1283. Specifies the atom that names the selection being transferred.
  1284. .IP \fItarget\fP 1i
  1285. Specifies the target type to which the conversion was done.
  1286. .IP \fIrequest_id\fP 1i
  1287. Specifies an opaque identification for a specific request.
  1288. .IP \fIclient_data\fP 1i
  1289. Specified the value passed in by the widget when it
  1290. took ownership of the selection.
  1291. .LP
  1292. This procedure, which is optional, is called by the \*(xI after
  1293. the requestor has retrieved the final (zero-length) segment of the
  1294. incremental transfer to indicate that the entire transfer is complete.
  1295. If this procedure is not specified, the \*(xI will free only the
  1296. final value returned by the selection owner using
  1297. .PN XtFree .
  1298. .sp
  1299. .LP
  1300. The procedure pointer specified by the incremental selection owner to
  1301. notify it if a transfer should be terminated prematurely is of type
  1302. .PN XtCancelConvertSelectionProc .
  1303. .IN "XtCancelConvertSelectionProc" "" "@DEF@"
  1304. .FD 0
  1305. typedef void (*XtCancelConvertSelectionProc)(Widget, Atom*, Atom*, \
  1306. XtRequestId*, XtPointer);
  1307. .br
  1308.       Widget \fIw\fP;
  1309. .br
  1310.       Atom *\fIselection\fP;
  1311. .br
  1312.       Atom *\fItarget\fP;
  1313. .br
  1314.       XtRequestId *\fIrequest_id\fP;
  1315. .br
  1316.       XtPointer \fIclient_data\fP;
  1317. .FN
  1318. .IP \fIw\fP 1i
  1319. Specifies the widget that owns the selection.
  1320. .IP \fIselection\fP 1i
  1321. Specifies the atom that names the selection being transferred.
  1322. .IP \fItarget\fP 1i
  1323. Specifies the target type to which the conversion was done.
  1324. .IP \fIrequest_id\fP 1i
  1325. Specifies an opaque identification for a specific request.
  1326. .IP \fIclient_data\fP 1i
  1327. Specifies the value passed in by the widget when it took ownership of
  1328. the selection.
  1329. .LP
  1330. This procedure is called by the \*(xI when it has been determined
  1331. by means of a timeout or other mechanism that any remaining segments
  1332. of the selection no longer need to be transferred.  Upon receiving
  1333. this callback, the selection request is considered complete and the
  1334. owner can free the memory and any other resources that have been
  1335. allocated for the transfer.
  1336.  
  1337. .NH 4
  1338. Getting the Selection Value Incrementally
  1339. .XS
  1340. \*(SN Getting the Selection Value Incrementally
  1341. .XE
  1342. .LP
  1343. To obtain the value of the selection using incremental transfers, use
  1344. .PN XtGetSelectionValueIncremental
  1345. or
  1346. .PN XtGetSelectionValuesIncremental .
  1347. .IN "XtGetSelectionValueIncremental" "" "@DEF@"
  1348. .FD 0
  1349. void XtGetSelectionValueIncremental(\fIw\fP, \fIselection\fP, \fItarget\fP, \
  1350. \fIselection_callback\fP, \fIclient_data\fP, \fItime\fP)
  1351. .br
  1352.       Widget \fIw\fP;
  1353. .br
  1354.       Atom \fIselection\fP;
  1355. .br
  1356.       Atom \fItarget\fP;
  1357. .br
  1358.       XtSelectionCallbackProc \fIselection_callback\fP;
  1359. .br
  1360.       XtPointer \fIclient_data\fP;
  1361. .br
  1362.       Time \fItime\fP;
  1363. .FN
  1364. .IP \fIw\fP 1i
  1365. Specifies the widget making the request.  \*(cI
  1366. .IP \fIselection\fP 1i
  1367. Specifies the particular selection desired.
  1368. .IP \fItarget\fP 1i
  1369. Specifies the type of information needed
  1370. about the selection.
  1371. .IP \fIselection_callback\fP 1i
  1372. Specifies the callback procedure to be
  1373. called to receive each data segment.
  1374. .IP \fIclient_data\fP 1i
  1375. Specifies client-specific data to be passed to
  1376. the specified callback procedure when it is invoked.
  1377. .IP \fItime\fP 1i
  1378. Specifies the timestamp that indicates when the
  1379. selection request was initiated.  This should be the
  1380. timestamp of the event that triggered this request;
  1381. the value
  1382. .PN CurrentTime
  1383. is not acceptable.
  1384. .LP
  1385. The
  1386. .PN XtGetSelectionValueIncremental
  1387. function is similar to
  1388. .PN XtGetSelectionValue
  1389. except that the selection_callback procedure will
  1390. be called repeatedly upon delivery of multiple segments of the
  1391. selection value.  The end of the selection value is indicated when
  1392. \fIselection_callback\fP is called with a non-NULL value of length zero,
  1393. which must still be freed by the client.  If the
  1394. transfer of the selection is aborted in the middle of a transfer
  1395. (for example, because to timeout), the selection_callback procedure is
  1396. called with a type value equal to the symbolic constant
  1397. .PN XT_CONVERT_FAIL
  1398. so that the requestor can dispose
  1399. of the partial selection value it has collected up until that point.
  1400. Upon receiving
  1401. .PN XT_CONVERT_FAIL ,
  1402. the requesting client must determine
  1403. for itself whether or not a partially completed data transfer is meaningful.
  1404. For more information about \fIselection\fP, \fItarget\fP, and
  1405. \fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
  1406. .sp
  1407. .IN "XtGetSelectionValuesIncremental" "" "@DEF@"
  1408. .FD 0
  1409. void XtGetSelectionValuesIncremental(\fIw\fP, \fIselection\fP, \fItargets\fP, \
  1410. \fIcount\fP, \fIselection_callback\fP, \fIclient_data\fP, \fItime\fP)
  1411. .br
  1412.       Widget \fIw\fP;
  1413. .br
  1414.       Atom \fIselection\fP;
  1415. .br
  1416.       Atom *\fItargets\fP;
  1417. .br
  1418.       int \fIcount\fP;
  1419. .br
  1420.       XtSelectionCallbackProc \fIselection_callback\fP;
  1421. .br
  1422.       XtPointer *\fIclient_data\fP;
  1423. .br
  1424.       Time \fItime\fP;
  1425. .FN
  1426. .IP \fIw\fP 1i
  1427. Specifies the widget making the request.  \*(cI
  1428. .IP \fIselection\fP 1i
  1429. Specifies the particular selection desired.
  1430. .IP \fItargets\fP 1i
  1431. Specifies the types of information needed about
  1432. the selection.
  1433. .IP \fIcount\fP 1i
  1434. Specifies the length of the \fItargets\fP and \fIclient_data\fP lists.
  1435. .IP \fIselection_callback\fP 1i
  1436. Specifies the callback procedure to be called
  1437. to receive each selection value.
  1438. .IP \fIclient_data\fP 1i
  1439. Specifies a list of client data (one for each target
  1440. type) values that are passed to the callback procedure when
  1441. it is invoked for the corresponding target.
  1442. .IP \fItime\fP 1i
  1443. Specifies the timestamp that indicates when the
  1444. selection request was initiated.  This should be the
  1445. timestamp of the event that triggered this request;
  1446. the value
  1447. .PN CurrentTime
  1448. is not acceptable.
  1449. .LP
  1450. The
  1451. .PN XtGetSelectionValuesIncremental
  1452. function is similar to
  1453. .PN XtGetSelectionValueIncremental
  1454. except that it takes a list of targets and client data.
  1455. .PN XtGetSelectionValuesIncremental
  1456. is equivalent to calling
  1457. .PN XtGetSelectionValueIncremental
  1458. successively for each \fItarget/client_data\fP pair except that
  1459. .PN XtGetSelectionValuesIncremental
  1460. does guarantee that all the conversions will use the same selection
  1461. value because the ownership of the selection cannot change in the
  1462. middle of the list, as would be possible when calling
  1463. .PN XtGetSelectionValueIncremental
  1464. repeatedly.
  1465. For more information about \fIselection\fP, \fItarget\fP, and
  1466. \fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
  1467.  
  1468. .NH 4
  1469. Setting the Selection Owner for Incremental Transfers
  1470. .XS
  1471. \*(SN Setting the Selection Owner for Incremental Transfers
  1472. .XE
  1473. .LP
  1474. To set the selection owner when using incremental transfers, use
  1475. .PN XtOwnSelectionIncremental .
  1476. .IN "XtOwnSelectionIncremental" "" "@DEF@"
  1477. .FD 0
  1478. Boolean XtOwnSelectionIncremental(\fIw\fP, \fIselection\fP, \fItime\fP, \
  1479. \fIconvert_callback\fP, \fIlose_callback\fP,
  1480.                                   \fIdone_callback\fP, \
  1481. \fIcancel_callback\fP, \fIclient_data\fP)
  1482. .br
  1483.       Widget \fIw\fP;
  1484. .br
  1485.       Atom \fIselection\fP;
  1486. .br
  1487.       Time \fItime\fP;
  1488. .br
  1489.       XtConvertSelectionIncrProc \fIconvert_callback\fP;
  1490. .br
  1491.       XtLoseSelectionIncrProc \fIlose_callback\fP;
  1492. .br
  1493.       XtSelectionDoneIncrProc \fIdone_callback\fP;
  1494. .br
  1495.       XtCancelConvertSelectionProc \fIcancel_callback\fP;
  1496. .br
  1497.       XtPointer \fIclient_data\fP;
  1498. .FN
  1499. .IP \fIw\fP 1.25i
  1500. Specifies the widget that wishes to become the owner.  \*(cI
  1501. .IP \fIselection\fP 1.25i
  1502. Specifies the atom that names the selection.
  1503. .IP \fItime\fP 1.25i
  1504. Specifies the timestamp that indicates when the
  1505. selection ownership request was initiated.  This should be
  1506. the timestamp of the event that triggered ownership; the value
  1507. .PN CurrentTime
  1508. is not acceptable.
  1509. .IP \fIconvert_callback\fP 1.25i
  1510. Specifies the procedure to be called whenever
  1511. the current value of the selection is requested.
  1512. .IP \fIlose_callback\fP 1.25i
  1513. Specifies the procedure to be called whenever
  1514. the widget has lost selection ownership, or NULL if the
  1515. owner is not interested in being notified.
  1516. .IP \fIdone_callback\fP 1.25i
  1517. Specifies the procedure called after the
  1518. requestor has received the entire selection, or NULL if
  1519. the owner is not interested in being notified.
  1520. .IP \fIcancel_callback\fP 1.25i
  1521. Specifies the callback procedure to be called
  1522. when a selection request aborts because a timeout expires,
  1523. or NULL if the owner is not interested in being notified.
  1524. .IP \fIclient_data\fP 1.25i
  1525. Specifies the argument to be passed to each of
  1526. the callback procedures when they are called.
  1527. .LP
  1528. The
  1529. .PN XtOwnSelectionIncremental
  1530. procedure informs the \*(xI
  1531. incremental selection mechanism that the specified widget wishes to
  1532. own the selection.  It returns
  1533. .PN True
  1534. if the specified widget successfully becomes the selection owner or
  1535. .PN False
  1536. otherwise.
  1537. For more information about \fIselection\fP, \fItarget\fP, and
  1538. \fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
  1539. .LP
  1540. If a done_callback procedure is specified, the client owns the storage allocated
  1541. for passing the value to the \*(xI.  If \fIdone_callback\fP is NULL,
  1542. the convert_callback procedure must allocate storage using
  1543. .PN XtMalloc ,
  1544. .PN XtRealloc ,
  1545. or
  1546. .PN XtCalloc ,
  1547. and the final value specified will be freed by the
  1548. \*(xI when the transfer is complete.  After a selection transfer
  1549. has started, only one of the done_callback or cancel_callback
  1550. procedures will be invoked to indicate completion of the transfer.
  1551. .LP
  1552. The lose_callback procedure does not indicate completion of any in-progress
  1553. transfers; it will be invoked at the time a
  1554. .PN SelectionClear
  1555. event is dispatched regardless of any active transfers, which are still
  1556. expected to continue.
  1557. .LP
  1558. A widget that becomes the selection owner using
  1559. .PN XtOwnSelectionIncremental
  1560. may use
  1561. .PN XtDisownSelection
  1562. to relinquish selection ownership.
  1563.  
  1564. .NH 3
  1565. Retrieving the Most Recent Timestamp
  1566. .XS
  1567. \*(SN Retrieving the Most Recent Timestamp
  1568. .XE
  1569. .LP
  1570. To retrieve the timestamp from the most recent call to
  1571. .PN XtDispatchEvent
  1572. that contained a timestamp, use
  1573. .PN XtLastTimestampProcessed .
  1574. .IN "XtLastTimestampProcessed" "" "@DEF@"
  1575. .FD 0
  1576. Time XtLastTimestampProcessed(\fIdisplay\fP)
  1577. .br
  1578.       Display *\fIdisplay\fP;
  1579. .FN
  1580. .IP \fIdisplay\fP 1i
  1581. Specifies an open display connection.
  1582. .LP
  1583. If no
  1584. .PN KeyPress ,
  1585. .PN KeyRelease ,
  1586. .PN ButtonPress ,
  1587. .PN ButtonRelease ,
  1588. .PN MotionNotify ,
  1589. .PN EnterNotify ,
  1590. .PN LeaveNotify ,
  1591. .PN PropertyNotify ,
  1592. or
  1593. .PN SelectionClear
  1594. event has yet been passed to
  1595. .PN XtDispatchEvent
  1596. for the specified display,
  1597. .PN XtLastTimestampProcessed
  1598. returns zero.
  1599.  
  1600. .NH 2
  1601. Merging Exposure Events into a Region
  1602. .XS
  1603. \*(SN Merging Exposure Events into a Region
  1604. .XE
  1605. .LP
  1606. The \*(xI provide an
  1607. .PN XtAddExposureToRegion
  1608. utility function that merges
  1609. .PN Expose
  1610. and
  1611. .PN GraphicsExpose
  1612. events into a region for clients to process at once
  1613. rather than processing individual rectangles.
  1614. For further information about regions,
  1615. see Section 16.5 in \fI\*(xL\fP.
  1616. .sp
  1617. .LP
  1618. To merge
  1619. .PN Expose
  1620. and
  1621. .PN GraphicsExpose
  1622. events into a region, use
  1623. .PN XtAddExposureToRegion .
  1624. .IN "XtAddExposureToRegion" "" "@DEF@"
  1625. .FD 0
  1626. void XtAddExposureToRegion(\fIevent\fP, \fIregion\fP)
  1627. .br
  1628.      XEvent *\fIevent\fP;
  1629. .br
  1630.      Region \fIregion\fP;
  1631. .FN
  1632. .IP \fIevent\fP 1i
  1633. Specifies a pointer to the
  1634. .PN Expose
  1635. or
  1636. .PN GraphicsExpose
  1637. event.
  1638. .IP \fIregion\fP 1i
  1639. Specifies the region object (as defined in
  1640. .Pn < X11/Xutil.h >).
  1641. .LP
  1642. The
  1643. .PN XtAddExposureToRegion
  1644. function computes the union of the rectangle defined by the exposure
  1645. event and the specified region.
  1646. Then it stores the results back in \fIregion\fP.
  1647. If the event argument is not an
  1648. .PN Expose
  1649. or
  1650. .PN GraphicsExpose
  1651. event,
  1652. .PN XtAddExposureToRegion
  1653. returns without an error and without modifying \fIregion\fP.
  1654. .LP
  1655. This function is used by the exposure compression mechanism;
  1656. see Section 7.9.3.
  1657.  
  1658. .NH 2
  1659. Translating Widget Coordinates
  1660. .XS
  1661. \fB\*(SN Translating Widget Coordinates\fP
  1662. .XE
  1663. .LP
  1664. To translate an x-y coordinate pair from widget coordinates to root
  1665. window absolute coordinates, use
  1666. .PN XtTranslateCoords .
  1667. .IN "XtTranslateCoords" "" "@DEF@"
  1668. .FD 0
  1669. void XtTranslateCoords(\fIw\fP, \fIx\fP, \fIy\fP, \fIrootx_return\fP, \
  1670. \fIrooty_return\fP)
  1671. .br
  1672.       Widget \fIw\fP;
  1673. .br
  1674.       Position \fIx\fP, \fIy\fP;
  1675. .br
  1676.       Position *\fIrootx_return\fP, *\fIrooty_return\fP;
  1677. .FN
  1678. .IP \fIw\fP 1i
  1679. Specifies the widget.  \*(rI
  1680. .IP \fIx\fP 1i
  1681. .br
  1682. .ns
  1683. .IP \fIy\fP 1i
  1684. Specify the widget-relative x and y coordinates.
  1685. .IP \fIrootx_return\fP 1i
  1686. .br
  1687. .ns
  1688. .IP \fIrooty_return\fP 1i
  1689. Return the root-relative x and y coordinates.
  1690. .LP
  1691. While
  1692. .PN XtTranslateCoords
  1693. is similar to the Xlib
  1694. .PN XTranslateCoordinates 
  1695. function, it does not generate a server request because all the required
  1696. information already is in the widget's data structures.
  1697.  
  1698. .NH 2
  1699. Translating a Window to a Widget
  1700. .XS
  1701. \fB\*(SN Translating a Window to a Widget\fP
  1702. .XE
  1703. .LP
  1704. To translate a given window and display pointer into a widget instance, use
  1705. .PN XtWindowToWidget .
  1706. .IN "XtWindowToWidget" "" "@DEF@"
  1707. .FD 0
  1708. Widget XtWindowToWidget(\fIdisplay\fP, \fIwindow\fP)
  1709. .br
  1710.       Display *\fIdisplay\fP;
  1711. .br
  1712.       Window \fIwindow\fP;
  1713. .FN
  1714. .IP \fIdisplay\fP 1i
  1715. Specifies the display on which the window is defined.
  1716. .IP \fIwindow\fP 1i
  1717. Specifies the window for which you want the widget.
  1718. .LP
  1719. If there is a realized widget whose window is the specified \fIwindow\fP on
  1720. the specified \fIdisplay\fP,
  1721. .PN XtWindowToWidget
  1722. returns that widget; otherwise, it returns NULL.
  1723.  
  1724. .NH 2
  1725. Handling Errors
  1726. .XS
  1727. \fB\*(SN Handling Errors\fP
  1728. .XE
  1729. .LP
  1730. The \*(xI allow a client to register procedures that will be called
  1731. whenever a fatal or nonfatal error occurs.
  1732. These facilities are intended for both error reporting and logging
  1733. and for error correction or recovery.
  1734. .LP
  1735. Two levels of interface are provided: 
  1736. .IP \(bu 5
  1737. A high-level interface that takes an error
  1738. name and class and retrieves the error message text from
  1739. an error resource database.
  1740. .IP \(bu 5
  1741. A low-level interface that takes a simple string to display.
  1742. .LP
  1743. The high-level functions construct a string to pass to the lower-level
  1744. interface.
  1745. The strings may be specified in application code and will be
  1746. overridden by the contents of an external system-wide file,
  1747. the ``error database file''.  The location and name of this file is
  1748. implementation dependent.
  1749. .NT
  1750. The application-context-specific error handling is not
  1751. implemented on many systems, although the interfaces are
  1752. always present.
  1753. Most implementations will have just one set of error handlers
  1754. for all application contexts within a process.
  1755. If they are set for different application contexts,
  1756. the ones registered last will prevail.
  1757. .NE
  1758. .sp
  1759. .LP
  1760. To obtain the error database (for example, to merge with
  1761. an application- or widget-specific database), use
  1762. .PN XtAppGetErrorDatabase .
  1763. .IN "XtAppGetErrorDatabase" "" "@DEF@"
  1764. .FD 0
  1765. XrmDatabase *XtAppGetErrorDatabase(\^\fIapp_context\fP\^)
  1766. .br
  1767.      XtAppContext \fIapp_context\fP;
  1768. .FN
  1769. .IP \fIapp_context\fP 1i
  1770. Specifies the application context.
  1771. .LP
  1772. The
  1773. .PN XtAppGetErrorDatabase
  1774. function returns the address of the error database.
  1775. The \*(xI do a lazy binding of the error database and do not merge in the
  1776. database file until the first call to
  1777. .PN XtAppGetErrorDatabaseText .
  1778. .LP
  1779. For a complete listing of all errors and warnings 
  1780. that can be generated by the \*(xI, see Appendix D.
  1781. .sp
  1782. .LP
  1783. The high-level error and warning handler procedure pointers are of type
  1784. .PN XtErrorMsgHandler .
  1785. .LP
  1786. .IN "XtErrorMsgHandler" "" "@DEF@"
  1787. .FD 0
  1788. typedef void (*XtErrorMsgHandler)(String, String, String, String, \
  1789. String*, Cardinal*);
  1790. .br
  1791.     String \fIname\fP;
  1792. .br
  1793.     String \fItype\fP;
  1794. .br
  1795.     String \fIclass\fP;
  1796. .br
  1797.     String \fIdefaultp\fP;
  1798. .br
  1799.     String *\fIparams\fP;
  1800. .br
  1801.     Cardinal *\fInum_params\fP;
  1802. .FN
  1803. .IP \fIname\fP 1i
  1804. Specifies the name to be concatenated with the specified type to form 
  1805. the resource name of the error message.
  1806. .IP \fItype\fP 1i
  1807. Specifies the type to be concatenated with the name to form the 
  1808. resource name of the error message.
  1809. .IP \fIclass\fP 1i
  1810. Specifies the resource class of the error message.
  1811. .IP \fIdefaultp\fP 1i
  1812. Specifies the default message to use if no error database entry is found.
  1813. .IP \fIparams\fP 1i
  1814. Specifies a pointer to a list of parameters to be substituted in the message.
  1815. .IP \fInum_params\fP 1i
  1816. Specifies the number of entries in \fIparams\fP.
  1817. .LP
  1818. The specified name can be a general kind of error, 
  1819. like ``invalidParameters'' or ``invalidWindow'', 
  1820. and the specified type gives extra information
  1821. such as the name of the routine in which the error was detected.
  1822. Standard 
  1823. .PN printf 
  1824. notation is used to substitute the parameters into the message.
  1825. .sp
  1826. .LP
  1827. An error message handler can obtain the error database text for an
  1828. error or a warning by calling
  1829. .PN XtAppGetErrorDatabaseText .
  1830. .IN "XtAppGetErrorDatabaseText" "" "@DEF@"
  1831. .FD 0
  1832. void XtAppGetErrorDatabaseText(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP, \fIdatabase\fP)
  1833. .br
  1834.       XtAppContext \fIapp_context\fP;
  1835. .br
  1836.       String \fIname\fP, \fItype\fP, \fIclass\fP;
  1837. .br
  1838.       String \fIdefault\fP;
  1839. .br
  1840.       String \fIbuffer_return\fP;
  1841. .br
  1842.       int \fInbytes\fP;
  1843. .br
  1844.       XrmDatabase \fIdatabase\fP;
  1845. .FN
  1846. .IP \fIapp_context\fP 1i
  1847. Specifies the application context.
  1848. .IP \fIname\fP 1i
  1849. .br
  1850. .ns
  1851. .IP \fItype\fP 1i
  1852. Specify the name and type concatenated to form the resource name 
  1853. of the error message.
  1854. .IP \fIclass\fP 1i
  1855. Specifies the resource class of the error message.
  1856. .IP \fIdefault\fP 1i
  1857. Specifies the default message to use if an error database entry is not found.
  1858. .IP \fIbuffer_return\fP 1i
  1859. Specifies the buffer into which the error message is to be returned.
  1860. .IP \fInbytes\fP 1i
  1861. Specifies the size of the buffer in bytes.
  1862. .IP \fIdatabase\fP 1i
  1863. Specifies the name of the alternative database to be used,
  1864. or NULL if the application context's error database is to be used.
  1865. .LP
  1866. The
  1867. .PN XtAppGetErrorDatabaseText
  1868. returns the appropriate message from the error database
  1869. or returns the specified default message if one is not found in the
  1870. error database.
  1871. To form the full resource name and class when querying the database,
  1872. the \fIname\fP and \fItype\fP are concatenated with a single ``.''
  1873. between them and the \fIclass\fP is concatenated with itself with a
  1874. single ``.'' if it does not already contain a ``.''.
  1875.  
  1876. .sp
  1877. .LP
  1878. To return the application name and class as passed to
  1879. .PN XtDisplayInitialize
  1880. for a particular Display, use
  1881. .PN XtGetApplicationNameAndClass .
  1882. .IN "XtGetApplicationNameAndClass" "" "@DEF@"
  1883. .FD 0
  1884. void XtGetApplicationNameAndClass(\fIdisplay\fP, \fIname_return\fP, \
  1885. \fIclass_return\fP)
  1886. .br
  1887.       Display* \fIdisplay\fP;
  1888. .br
  1889.       String* \fIname_return\fP;
  1890. .br
  1891.       String* \fIclass_return\fP;
  1892. .FN
  1893. .IP \fIdisplay\fP 1i
  1894. Specifies an open display connection that has been initialized with
  1895. .PN XtDisplayInitialize .
  1896. .IP \fIname_return\fP 1i
  1897. Returns the application name.
  1898. .IP \fIclass_return\fP 1i
  1899. Returns the application class.
  1900. .LP
  1901. .PN XtGetApplicationNameAndClass
  1902. returns the application name and class passed to
  1903. .PN XtDisplayInitialize
  1904. for the specified display.  If the display was
  1905. never initialized or has been closed, the result is undefined.  The
  1906. returned strings are owned by the \*(xI and must not be modified
  1907. or freed by the caller.
  1908. .sp
  1909. .LP
  1910. To register a procedure to be called on fatal error conditions, use
  1911. .PN XtAppSetErrorMsgHandler .
  1912. .IN "XtAppSetErrorMsgHandler" "" "@DEF@"
  1913. .FD 0
  1914. XtErrorMsgHandler XtAppSetErrorMsgHandler(\fIapp_context\fP, \fImsg_handler\fP)
  1915. .br
  1916.       XtAppContext \fIapp_context\fP;
  1917. .br
  1918.       XtErrorMsgHandler \fImsg_handler\fP;
  1919. .FN
  1920. .IP \fIapp_context\fP 1i
  1921. Specifies the application context.
  1922. .IP \fImsg_handler\fP 1i
  1923. Specifies the new fatal error procedure, which should not return.
  1924. .LP
  1925. .PN XtAppSetErrorMsgHandler
  1926. returns a pointer to the previously
  1927. installed high-level fatal error handler.
  1928. The default high-level fatal error handler provided by the \*(xI is named
  1929. .PN _XtDefaultErrorMsg
  1930. .IN "_XtDefaultErrorMsg" "" "@DEF"
  1931. and constructs a string from the error resource database and calls
  1932. .PN XtError .
  1933. Fatal error message handlers should not return.
  1934. If one does,
  1935. subsequent \*(xI behavior is undefined.
  1936. .sp
  1937. .LP
  1938. To call the high-level error handler, use
  1939. .PN XtAppErrorMsg .
  1940. .IN "XtAppErrorMsg" "" "@DEF@"
  1941. .FD 0
  1942. void XtAppErrorMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \
  1943. \fIdefault\fP, \ \fIparams\fP, \fInum_params\fP)
  1944. .br
  1945.       XtAppContext \fIapp_context\fP;
  1946. .br
  1947.       String \fIname\fP;
  1948. .br
  1949.       String \fItype\fP;
  1950. .br
  1951.       String \fIclass\fP;
  1952. .br
  1953.       String \fIdefault\fP;
  1954. .br
  1955.       String *\fIparams\fP;
  1956. .br
  1957.       Cardinal *\fInum_params\fP;
  1958. .FN
  1959. .IP \fIapp_context\fP 1i
  1960. Specifies the application context.
  1961. .IP \fIname\fP 1i
  1962. Specifies the general kind of error.
  1963. .IP \fItype\fP 1i
  1964. Specifies the detailed name of the error.
  1965. .IP \fIclass\fP 1i
  1966. Specifies the resource class.
  1967. .IP \fIdefault\fP 1i
  1968. Specifies the default message to use if an error database entry is not found.
  1969. .IP \fIparams\fP 1i
  1970. Specifies a pointer to a list of values to be stored in the message.
  1971. .IP \fInum_params\fP 1i
  1972. Specifies the number of entries in \fIparams\fP.
  1973. .LP
  1974. The \*(xI internal errors all have class
  1975. ``XtToolkitError''.
  1976. .sp
  1977. .LP
  1978. To register a procedure to be called on nonfatal error conditions, use
  1979. .PN XtAppSetWarningMsgHandler .
  1980. .IN "XtAppSetWarningMsgHandler" "" "@DEF@"
  1981. .FD 0
  1982. XtErrorMsgHandler XtAppSetWarningMsgHandler(\fIapp_context\fP, \fImsg_handler\fP)
  1983. .br
  1984.       XtAppContext \fIapp_context\fP;
  1985. .br
  1986.       XtErrorMsgHandler \fImsg_handler\fP;
  1987. .FN
  1988. .IP \fIapp_context\fP 1i
  1989. Specifies the application context.
  1990. .IP \fImsg_handler\fP 1i
  1991. Specifies the new nonfatal error procedure, which usually returns.
  1992. .LP
  1993. .PN XtAppSetWarningMsgHandler
  1994. returns a pointer to the previously
  1995. installed high-level warning handler.
  1996. The default high-level warning handler provided by the \*(xI is named
  1997. .PN _XtDefaultWarningMsg
  1998. .IN "_XtDefaultWarningMsg" "" "@DEF@"
  1999. and constructs a string
  2000. from the error resource database and calls
  2001. .PN XtWarning .
  2002. .sp
  2003. .LP
  2004. To call the installed high-level warning handler, use
  2005. .PN XtAppWarningMsg .
  2006. .IN "XtAppWarningMsg" "" "@DEF@"
  2007. .FD 0
  2008. void XtAppWarningMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIparams\fP, \fInum_params\fP)
  2009. .br
  2010.       XtAppContext \fIapp_context\fP;
  2011. .br
  2012.       String \fIname\fP;
  2013. .br
  2014.       String \fItype\fP;
  2015. .br
  2016.       String \fIclass\fP;
  2017. .br
  2018.       String \fIdefault\fP;
  2019. .br
  2020.       String *\fIparams\fP;
  2021. .br
  2022.       Cardinal *\fInum_params\fP;
  2023. .FN
  2024. .IP \fIapp_context\fP 1i
  2025. Specifies the application context.
  2026. .IP \fIname\fP 1i
  2027. Specifies the general kind of error.
  2028. .IP \fItype\fP 1i
  2029. Specifies the detailed name of the error.
  2030. .IP \fIclass\fP 1i
  2031. Specifies the resource class.
  2032. .IP \fIdefault\fP 1i
  2033. Specifies the default message to use if an error database entry is not found.
  2034. .IP \fIparams\fP 1i
  2035. Specifies a pointer to a list of values to be stored in the message.
  2036. .IP \fInum_params\fP 1i
  2037. Specifies the number of entries in \fIparams\fP.
  2038. .LP
  2039. The \*(xI internal warnings all have class
  2040. ``XtToolkitError''.
  2041. .sp
  2042. .LP
  2043. The low-level error and warning handler procedure pointers are of type
  2044. .PN XtErrorHandler .
  2045. .IN "XtErrorHandler" "" "@DEF@"
  2046. .FD 0
  2047. typedef void (*XtErrorHandler)(String);
  2048. .br
  2049.       String \fImessage\fP;
  2050. .FN
  2051. .IP \fImessage\fP 1i
  2052. Specifies the error message.
  2053. .LP
  2054. The error handler should display the message string in some appropriate fashion.
  2055. .sp
  2056. .LP
  2057. To register a procedure to be called on fatal error conditions, use
  2058. .PN XtAppSetErrorHandler .
  2059. .IN "XtAppSetErrorHandler" "" "@DEF@"
  2060. .FD 0
  2061. XtErrorHandler XtAppSetErrorHandler(\fIapp_context\fP, \fIhandler\fP)
  2062. .br
  2063.       XtAppContext \fIapp_context\fP;
  2064. .br
  2065.       XtErrorHandler \fIhandler\fP;
  2066. .FN
  2067. .IP \fIapp_context\fP 1i
  2068. Specifies the application context.
  2069. .IP \fIhandler\fP 1i
  2070. Specifies the new fatal error procedure, which should not return.
  2071. .LP
  2072. .PN XtAppSetErrorHandler
  2073. returns a pointer to the previously installed
  2074. low-level fatal error handler.
  2075. The default low-level error handler provided by the \*(xI is
  2076. .PN _XtDefaultError .
  2077. .IN "_XtDefaultError" "" "@DEF@"
  2078. On POSIX-based systems,
  2079. it prints the message to standard error and terminates the application.
  2080. Fatal error message handlers should not return.
  2081. If one does,
  2082. subsequent \*(xI behavior is undefined.
  2083. .sp
  2084. .LP
  2085. To call the installed fatal error procedure, use
  2086. .PN XtAppError .
  2087. .IN "XtAppError" "" "@DEF@"
  2088. .FD 0
  2089. void XtAppError(\fIapp_context\fP, \fImessage\fP)
  2090. .br
  2091.       XtAppContext \fIapp_context\fP;
  2092. .br
  2093.       String \fImessage\fP;
  2094. .FN
  2095. .IP \fIapp_context\fP 1i
  2096. Specifies the application context.
  2097. .IP \fImessage\fP 1i
  2098. Specifies the message to be reported.
  2099. .LP
  2100. Most programs should use
  2101. .PN XtAppErrorMsg ,
  2102. not
  2103. .PN XtAppError ,
  2104. to provide for customization and internationalization of error messages.
  2105. .sp
  2106. .LP
  2107. To register a procedure to be called on nonfatal error conditions, use
  2108. .PN XtAppSetWarningHandler .
  2109. .IN "XtAppSetWarningHandler" "" "@DEF@"
  2110. .FD 0
  2111. XtErrorHandler XtAppSetWarningHandler(\fIapp_context\fP, \fIhandler\fP)
  2112. .br
  2113.       XtAppContext \fIapp_context\fP;
  2114. .br
  2115.       XtErrorHandler \fIhandler\fP;
  2116. .FN
  2117. .IP \fIapp_context\fP 1i
  2118. Specifies the application context.
  2119. .IP \fIhandler\fP 1i
  2120. Specifies the new nonfatal error procedure, which usually returns.
  2121. .LP
  2122. .PN XtAppSetWarningHandler
  2123. returns a pointer to the previously installed
  2124. low-level warning handler.
  2125. The default low-level warning handler provided by the \*(xI is
  2126. .PN _XtDefaultWarning .
  2127. .IN "_XtDefaultWarning" "" "@DEF@"
  2128. On POSIX-based systems,
  2129. it prints the message to standard error and returns to the caller.
  2130. .sp
  2131. .LP
  2132. To call the installed nonfatal error procedure, use
  2133. .PN XtAppWarning .
  2134. .IN "XtAppWarning" "" "@DEF@"
  2135. .FD 0
  2136. void XtAppWarning(\fIapp_context\fP, \fImessage\fP)
  2137. .br
  2138.       XtAppContext \fIapp_context\fP;
  2139. .br
  2140.       String \fImessage\fP;
  2141. .FN
  2142. .IP \fIapp_context\fP 1i
  2143. Specifies the application context.
  2144. .IP \fImessage\fP 1i
  2145. Specifies the nonfatal error message to be reported.
  2146. .LP
  2147. Most programs should use
  2148. .PN XtAppWarningMsg ,
  2149. not
  2150. .PN XtAppWarning ,
  2151. to provide for customization and internationalization of warning messages.
  2152.  
  2153. .NH 2
  2154. Setting WM_COLORMAP_WINDOWS
  2155. .XS
  2156. \fB\*(SN Setting WM_COLORMAP_WINDOWS\fP
  2157. .XE
  2158. .LP
  2159. A client may set the value of the \s-1WM_COLORMAP_WINDOWS\s+1
  2160. .IN "WM_COLORMAP_WINDOWS" "" "@DEF@"
  2161. property on a widget's window by calling
  2162. .PN XtSetWMColormapWindows .
  2163. .IN "XtSetWMColormapWindows" "" "@DEF@"
  2164. .FD 0
  2165. void XtSetWMColormapWindows(\fIwidget\fP, \fIlist\fP, \fIcount\fP)
  2166. .br
  2167.       Widget \fIwidget\fP;
  2168. .br
  2169.       Widget* \fIlist\fP;
  2170. .br
  2171.       Cardinal \fIcount\fP;
  2172. .FN
  2173. .IP \fIwidget\fP 1i
  2174. Specifies the widget on whose window the \s-1WM_COLORMAP_WINDOWS\s+1
  2175. property will be stored.  \*(cI
  2176. .IP \fIlist\fP 1i
  2177. Specifies a list of widgets whose windows are potentially to be
  2178. listed in the \s-1WM_COLORMAP_WINDOWS\s+1 property.
  2179. .IP \fIcount\fP 1i
  2180. Specifies the number of widgets in \fIlist\fP.
  2181. .LP
  2182. .PN XtSetWMColormapWindows
  2183. returns immediately if \fIwidget\fP is not realized or if \fIcount\fP is 0.
  2184. Otherwise,
  2185. .PN XtSetWMColormapWindows
  2186. constructs an ordered list of windows
  2187. by examining each widget in \fIlist\fP in turn and
  2188. ignoring the widget if it is not realized, or
  2189. adding the widget's window to the window list if the widget is realized
  2190. and if its colormap resource is different from the colormap
  2191. resources of all widgets whose windows are already on the window list.
  2192. .LP
  2193. Finally,
  2194. .PN XtSetWMColormapWindows
  2195. stores the resulting window list in the \s-1WM_COLORMAP_WINDOWS\s+1
  2196. property on the specified widget's window.
  2197. Refer to Section 4.1.8 in the \fI\*(xC\fP for details of
  2198. the semantics of the \s-1WM_COLORMAP_WINDOWS\s+1 property.
  2199.  
  2200. .NH 2
  2201. Finding File Names
  2202. .XS
  2203. \fB\*(SN Finding File Names\fP
  2204. .XE
  2205. .LP
  2206. The \*(xI provide procedures to look for a file by name, allowing
  2207. string substitutions in a list of file specifications.  Two
  2208. routines are provided for this:
  2209. .PN XtFindFile
  2210. and
  2211. .PN XtResolvePathname .
  2212. .PN XtFindFile
  2213. uses an arbitrary set of client-specified substitutions, and
  2214. .PN XtResolvePathname
  2215. uses a set of standard substitutions corresponding
  2216. to the \fIX/Open Portability Guide\fP language localization conventions.
  2217. Most applications should use
  2218. .PN XtResolvePathname .
  2219. .LP
  2220. A string substitution is defined by a list of
  2221. .PN Substitution
  2222. .IN "Substitution" "" "@DEF@"
  2223. entries.
  2224. .sp
  2225. .Ds 0
  2226. .TA .5i 3i
  2227. .ta .5i 3i
  2228. typedef struct {
  2229.     char match;
  2230.     String substitution;
  2231. } SubstitutionRec, *Substitution;
  2232. .De
  2233. .LP
  2234. File name evaluation is handled in an operating-system-dependent
  2235. fashion by an
  2236. .PN XtFilePredicate
  2237. .IN "XtFilePredicate" "" "@DEF@"
  2238. procedure.
  2239. .FD 0
  2240. typedef Boolean (*XtFilePredicate)(String);
  2241. .br
  2242.       String \fIfilename\fP;
  2243. .FN
  2244. .IP \fIfilename\fP 1i
  2245. Specifies a potential filename.
  2246. .LP
  2247. A file predicate procedure will be called with a string that is
  2248. potentially a file name.  It should return
  2249. .PN True 
  2250. if this string specifies a file that is appropriate for the intended use and 
  2251. .PN False
  2252. otherwise.
  2253. .sp
  2254. .LP
  2255. To search for a file using substitutions in a path list, use
  2256. .PN XtFindFile .
  2257. .IN "XtFindFile" "" "@DEF@"
  2258. .FD 0
  2259. String XtFindFile(\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \
  2260. \fIpredicate\fP)
  2261. .br
  2262.       String \fIpath\fP;
  2263. .br
  2264.       Substitution \fIsubstitutions\fP;
  2265. .br
  2266.       Cardinal \fInum_substitutions\fP;
  2267. .br
  2268.       XtFilePredicate \fIpredicate\fP;
  2269. .FN
  2270. .IP \fIpath\fP 1.2i
  2271. Specifies a path of file names, including substitution characters.
  2272. .IP \fIsubstitutions\fP 1.2i
  2273. Specifies a list of substitutions to make into the path.
  2274. .IP \fInum_substitutions\fP 1.2i
  2275. Specifies the number of substitutions passed in.
  2276. .IP \fIpredicate\fP 1.2i
  2277. Specifies a procedure called to judge each potential file name, or NULL.
  2278. .LP
  2279. The \fIpath\fP parameter specifies a string that consists of a series of
  2280. potential file names delimited by colons.  Within each name, the
  2281. percent character specifies a string substitution selected by the
  2282. following character.  The character sequence ``%:'' specifies an
  2283. embedded colon that is not a delimiter; the sequence is replaced by a
  2284. single colon.  The character sequence ``%%'' specifies a percent
  2285. character that does not introduce a substitution; the sequence is
  2286. replaced by a single percent character.  If a percent character is
  2287. followed by any other character,
  2288. .PN XtFindFile
  2289. looks through the
  2290. specified \fIsubstitutions\fP for that character in the \fImatch\fP field and if
  2291. found replaces the percent and match characters with the string in the
  2292. corresponding \fIsubstitution\fP field.  A \fIsubstitution\fP field entry of NULL
  2293. is equivalent to a pointer to an empty string.  If the operating
  2294. system does not interpret multiple embedded name separators in the
  2295. path (i.e., ``/'' in POSIX) the same way as a single separator,
  2296. .PN XtFindFile
  2297. will collapse multiple separators into a single one after performing
  2298. all string substitutions.  Except for collapsing embedded separators,
  2299. the contents of the string substitutions are not interpreted by
  2300. .PN XtFindFile
  2301. and may therefore contain any operating-system-dependent
  2302. characters, including additional name separators.  Each resulting
  2303. string is passed to the predicate procedure until a string is found for
  2304. which the procedure returns
  2305. .PN True ;
  2306. this string is the return value for
  2307. .PN XtFindFile .
  2308. If no string yields a
  2309. .PN True
  2310. return from the predicate,
  2311. .PN XtFindFile
  2312. returns NULL.
  2313. .LP
  2314. If the \fIpredicate\fP parameter is NULL, an internal procedure that checks
  2315. if the file exists, is readable, and is not a directory will be used.
  2316. .LP
  2317. It is the responsibility of the caller to free the returned string using
  2318. .PN XtFree
  2319. when it is no longer needed.
  2320. .sp
  2321. .LP
  2322. To search for a file using standard substitutions in a path list, use
  2323. .PN XtResolvePathname .
  2324. .IN "XtResolvePathname" "" "@DEF@"
  2325. .FD 0
  2326. String XtResolvePathname(\fIdisplay\fP, \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \
  2327. \fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \fIpredicate\fP)
  2328. .br
  2329.       Display *\fIdisplay\fP;
  2330. .br
  2331.       String \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \fIpath\fP;
  2332. .br
  2333.       Substitution \fIsubstitutions\fP;
  2334. .br
  2335.       Cardinal \fInum_substitutions\fP;
  2336. .br
  2337.       XtFilePredicate \fIpredicate\fP;
  2338. .FN
  2339. .IP \fIdisplay\fP 1.2i
  2340. Specifies the display to use to find the language for language substitutions.
  2341. .IP \fItype\fP
  2342. .br
  2343. .ns
  2344. .IP \fIfilename\fP
  2345. .br
  2346. .ns
  2347. .IP \fIsuffix\fP 1.2i
  2348. Specify values to substitute into the path.
  2349. .IP \fIpath\fP 1.2i
  2350. Specifies the list of file specifications, or NULL.
  2351. .IP \fIsubstitutions\fP 1.2i
  2352. Specifies a list of additional substitutions to make into the path, or NULL.
  2353. .IP \fInum_substitutions\fP 1.2i
  2354. Specifies the number of entries in \fIsubstitutions\fP.
  2355. .IP \fIpredicate\fP 1.2i
  2356. Specifies a procedure called to judge each potential file name, or NULL.
  2357. .LP
  2358. The substitutions specified by
  2359. .PN XtResolvePathname
  2360. are determined from the value of the language string retrieved by
  2361. .PN XtDisplayInitialize
  2362. for the specified display.
  2363. To set the
  2364. language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the
  2365. resource database. 
  2366. .IN "xnlLanguage"
  2367. The format and content of the language string are
  2368. implementation-defined.   One suggested syntax is to compose
  2369. the language string of three parts;  a  ``language  part'',  a
  2370. ``territory  part'' and a ``codeset part''.  The manner in which
  2371. this composition is accomplished is implementation-defined
  2372. and the \*(xI make no interpretation of the parts other
  2373. than to use them in substitutions as described below.
  2374. .LP
  2375. .PN XtResolvePathname
  2376. calls
  2377. .PN XtFindFile
  2378. with the following substitutions
  2379. in addition to any passed by the caller and returns the value returned by
  2380. .PN XtFindFile :
  2381. .IP %N 5
  2382. The value of the \fIfilename\fP parameter, or the application's
  2383. class name if \fIfilename\fP is NULL.
  2384. .IP %T 5
  2385. The value of the \fItype\fP parameter.
  2386. .IP %S 5
  2387. The value of the \fIsuffix\fP parameter.
  2388. .IP %L 5
  2389. The language string associated with the specified display.
  2390. .IP %l 5
  2391. The language part of the display's language string.
  2392. .IP %t 5
  2393. The territory part of the display's language string.
  2394. .IP %c 5
  2395. The codeset part of the display's language string.
  2396. .IP %C 5
  2397. The customization string retrieved from the resource
  2398. database associated with \fIdispay\fP.
  2399. .LP
  2400. If a path is passed to
  2401. .PN XtResolvePathname ,
  2402. it will be passed along to
  2403. .PN XtFindFile .
  2404. If the \fIpath\fP argument is NULL, the value of the
  2405. .PN \s-1XFILESEARCHPATH\s+1
  2406. .IN "XFILESEARCHPATH" "" "@DEF@"
  2407. environment variable will be passed to
  2408. .PN XtFindFile .
  2409. If
  2410. .PN \s-1XFILESEARCHPATH\s+1
  2411. is not defined, an implementation-specific default path will be used
  2412. which contains at least 6 entries.  These entries
  2413. must contain the following substitutions:
  2414.  
  2415. .nf
  2416. .ta .3i 2i 2.5i
  2417. 1.    %C, %N, %S, %T, %L    or    %C, %N, %S, %T, %l, %t, %c
  2418. 2.    %C, %N, %S, %T, %l
  2419. 3.    %C, %N, %S, %T
  2420. 4.    %N, %S, %T, %L    or    %N, %S, %T, %l, %t, %c
  2421. 5.    %N, %S, %T, %l
  2422. 6.    %N, %S, %T
  2423. .fi
  2424.  
  2425. The order of these six entries within the path must be as given above.
  2426. The order and use of substitutions within a given entry is implementation
  2427. dependent.
  2428. If the path begins
  2429. with a colon, it will be preceded by %N%S.  If the path includes two
  2430. adjacent colons, \fB%N%S\fP will be inserted between them.
  2431. .LP
  2432. The \fItype\fP parameter is intended to be a category of files, usually
  2433. being translated into a directory in the pathname.  Possible values
  2434. might include ``app-defaults'', ``help'', and ``bitmap''.
  2435. .LP
  2436. The \fIsuffix\fP parameter is intended to be appended to the file name.
  2437. Possible values might include ``.txt'', ``.dat'', and ``.bm''.
  2438. .LP
  2439. A suggested value for the default path on POSIX-based systems is
  2440. .IP
  2441. /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\\
  2442. .br
  2443. /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\\
  2444. .br
  2445. /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
  2446.  
  2447. .LP
  2448. Using this example, if the user has specified a language, it will be
  2449. used as a subdirectory of /usr/lib/X11 that will be searched for other
  2450. files.  If the desired file is not found there, the lookup will be
  2451. tried again using just the language part of the specification.  If the
  2452. file is not there, it will be looked for in /usr/lib/X11.  The \fItype\fP
  2453. parameter is used as a subdirectory of the language directory or of
  2454. /usr/lib/X11, and \fIsuffix\fP is appended to the file name.
  2455. .LP
  2456. The customization string is obtained by querying the resource database
  2457. currently associated with the display (the database returned by
  2458. .PN XrmGetDatabase )
  2459. for the resource \fIapplication_name\fP.customization, class
  2460. \fIapplication_class\fP.Customization where \fIapplication_name\fP
  2461. and \fIapplication_class\fP are the values returned by
  2462. .PN XtGetApplicationNameAndClass .
  2463. If no value is specified in the database, the empty string is used.
  2464. .LP
  2465. It is the responsibility of the caller to free the returned string using
  2466. .PN XtFree
  2467. when it is no longer needed.
  2468. .bp
  2469.