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

  1. .\" $XConsortium: CH09,v 1.8 91/08/26 13:36:17 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 9\fP\s-1
  20.  
  21. \s+1\fBResource Management\fP\s-1
  22. .sp 2
  23. .nr H1 9
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 9 \- Resource Management
  31. .XE
  32. A resource is a field in the widget record with a corresponding
  33. resource entry in the \fIresources\fP list of the widget or any of its
  34. superclasses.
  35. This means that the field is
  36. settable by
  37. .PN XtCreateWidget
  38. (by naming the field in the argument list), by an
  39. entry in a resource file (by using either the name or class), and by
  40. .PN XtSetValues .
  41. In addition, it is readable by
  42. .PN XtGetValues .
  43. Not all fields in a widget record are resources.
  44. Some are for bookkeeping use by the
  45. generic routines (like \fImanaged\fP and \fIbeing_destroyed\fP).
  46. Others can be for local bookkeeping,
  47. and still others are derived from resources 
  48. (many graphics contexts and pixmaps).
  49. .LP
  50. Widgets typically need to obtain a large set of resources at widget
  51. creation time.
  52. Some of the resources come from the argument list supplied in the call to
  53. .PN XtCreateWidget ,
  54. some from the resource database,
  55. and some from the internal defaults specified by the widget.
  56. Resources are obtained first from the argument list,
  57. then from the resource database for all resources not specified
  58. in the argument list,
  59. and last, from the internal default, if needed.
  60.  
  61. .NH 2
  62. Resource Lists
  63. .XS
  64. \*(SN Resource Lists
  65. .XE
  66. .LP
  67. .IN "Resource Management"
  68. A resource entry specifies a field in the widget,
  69. the textual name and class of the field that argument lists
  70. and external resource files use to refer to the field,
  71. and a default value that the field should get if no value is specified.
  72. The declaration for the
  73. .PN XtResource
  74. structure is
  75. .LP
  76. .Ds 0
  77. .TA .5i 3i
  78. .ta .5i 3i
  79. typedef struct {
  80.     String resource_name;
  81.     String resource_class;
  82.     String resource_type;
  83.     Cardinal resource_size;
  84.     Cardinal resource_offset;
  85.     String default_type;
  86.     XtPointer default_addr;
  87. } XtResource, *XtResourceList;
  88. .De
  89. .IN "XtResourceList"
  90.  
  91. .LP
  92. When the resource list is specified as the
  93. .PN CoreClassPart ,
  94. .PN ObjectClassPart ,
  95. .PN RectObjClassPart ,
  96. or
  97. .PN ConstraintClassPart
  98. \fIresources\fP field the strings pointed to by \fIresource_name\fP,
  99. \fIresource_Iclass\fP, \fIresource_type\fP, and \fIdefault_type\fP must
  100. be permanently allocated prior to or during the execution of the class
  101. initialization procedure and must not be subsequently deallocated.
  102.  
  103. .LP
  104. The \fIresource_name\fP field contains the name used by clients to access the field
  105. in the widget.
  106. By convention, it starts with a lower-case letter
  107. and is spelled exactly like the field name,
  108. except all underscores (_) are deleted and the next letter is replaced by its 
  109. upper-case counterpart.
  110. For example, the resource name for background_pixel becomes backgroundPixel.
  111. Resource names beginning with the two-character
  112. sequence ``xt'' and resource classes beginning with the two-character
  113. sequence ``Xt'' are reserved to the \*(xI for future standard and
  114. implementation-dependent uses.
  115. Widget header files typically contain a symbolic name for each resource name.
  116. All resource names, classes, and types used by the \*(xI are named in
  117. .Pn < X11/StringDefs.h >.
  118. The \*(xI's symbolic resource names begin with
  119. ``XtN''
  120. and are followed by the string name (for example, XtNbackgroundPixel
  121. for backgroundPixel).
  122.  
  123. .LP
  124. The \fIresource_class\fP field contains the class string used in resource
  125. specification files to identify the field.
  126. A resource class provides two functions:
  127. .IP \(bu 5
  128. It isolates an application from different representations that widgets 
  129. can use for a similar resource.
  130. .IP \(bu 5
  131. It lets you specify values for several actual resources with a single name.
  132. A resource class should be chosen to span a group of closely related fields.
  133. .LP
  134. For example,
  135. a widget can have several pixel resources: background, foreground,
  136. border, block cursor, pointer cursor, and so on.
  137. Typically, the background defaults to white
  138. and everything else to black.
  139. The resource class for each of these resources in the resource list
  140. should be chosen so that it takes the minimal number of entries
  141. in the resource database to make the background offwhite
  142. and everything else darkblue.
  143. .LP
  144. In this case, the background pixel should have a resource class of
  145. ``Background''
  146. and all the other pixel entries a resource class of
  147. ``Foreground''.
  148. Then, the resource file needs only two lines to
  149. change all pixels to offwhite or darkblue:
  150. .LP
  151. .Ds 5
  152. .TA .5i 1.5i
  153. .ta .5i 1.5i
  154. *Background:    offwhite
  155. *Foreground:    darkblue
  156. .De
  157. .LP
  158. Similarly, a widget may have several font resources (such as normal and bold),
  159. but all fonts should have the class Font.
  160. Thus, changing all fonts simply requires only a single line in the 
  161. default resource file:
  162. .LP
  163. .Ds 5
  164. .TA .5i 3i
  165. .ta .5i 3i
  166. *Font:    6x13
  167. .De
  168. .LP
  169. By convention,
  170. resource classes are always spelled starting with a capital letter
  171. to distinguish them from resource names.
  172. Their symbolic names are preceded with
  173. ``XtC''
  174. (for example, XtCBackground).
  175. .LP
  176. The \fIresource_type\fP field gives the physical representation type of the resource
  177. and also encodes information about the specific usage of the field.
  178. By convention, it starts with an upper-case letter and is
  179. spelled identically to the type name of the field.
  180. The resource type is used when resources are fetched to
  181. convert from the resource database format (usually
  182. .PN String )
  183. or the format of the resource default value
  184. (almost anything, but often
  185. .PN String )
  186. to the desired
  187. physical representation (see Section 9.6).
  188. The \*(xI define the following resource types:
  189. .TS H
  190. lw(2.75i) lw(2.75i).
  191. _
  192. .sp 6p
  193. .TB
  194. Resource Type    Structure or Field Type
  195. .sp 6p
  196. _
  197. .sp 6p
  198. .TH
  199. .R
  200. T{
  201. .PN XtRAcceleratorTable
  202. T}    XtAccelerators
  203. T{
  204. .PN XtRAtom
  205. T}    Atom
  206. T{
  207. .PN XtRBitmap
  208. T}    Pixmap, depth=1
  209. T{
  210. .PN XtRBoolean
  211. T}    Boolean
  212. T{
  213. .PN XtRBool
  214. T}    Bool
  215. T{
  216. .PN XtRCallback
  217. T}    XtCallbackList
  218. T{
  219. .PN XtRCardinal
  220. T}    Cardinal
  221. T{
  222. .PN XtRColor
  223. T}    XColor
  224. T{
  225. .PN XtRColormap
  226. T}    Colormap
  227. T{
  228. .PN XtRCursor
  229. T}    Cursor
  230. T{
  231. .PN XtRDimension
  232. T}    Dimension
  233. T{
  234. .PN XtRDisplay
  235. T}    Display*
  236. T{
  237. .PN XtREnum
  238. T}    XtEnum
  239. T{
  240. .PN XtRFile
  241. T}    FILE*
  242. T{
  243. .PN XtRFloat
  244. T}    float
  245. T{
  246. .PN XtRFont
  247. T}    Font
  248. T{
  249. .PN XtRFontSet
  250. T}    XFontSet
  251. T{
  252. .PN XtRFontStruct
  253. T}    XFontStruct*
  254. T{
  255. .PN XtRFunction
  256. T}    (*)()
  257. T{
  258. .PN XtRGeometry
  259. T}    T{
  260. char*, format as defined by
  261. .PN XParseGeometry
  262. T}
  263. T{
  264. .PN XtRInitialState
  265. T}    int
  266. T{
  267. .PN XtRInt
  268. T}    int
  269. T{
  270. .PN XtRLongBoolean
  271. T}    long
  272. T{
  273. .PN XtRObject
  274. T}    Object
  275. T{
  276. .PN XtRPixel
  277. T}    Pixel
  278. T{
  279. .PN XtRPixmap
  280. T}    Pixmap
  281. T{
  282. .PN XtRPointer
  283. T}    XtPointer
  284. T{
  285. .PN XtRPosition
  286. T}    Position
  287. T{
  288. .PN XtRScreen
  289. T}    Screen*
  290. T{
  291. .PN XtRShort
  292. T}    short
  293. T{
  294. .PN XtRString
  295. T}    String
  296. T{
  297. .PN XtRStringArray
  298. T}    String*
  299. T{
  300. .PN XtRStringTable
  301. T}    String*
  302. T{
  303. .PN XtRTranslationTable
  304. T}    XtTranslations
  305. T{
  306. .PN XtRUnsignedChar
  307. T}    unsigned char
  308. T{
  309. .PN XtRVisual
  310. T}    Visual*
  311. T{
  312. .PN XtRWidget
  313. T}    Widget
  314. T{
  315. .PN XtRWidgetClass
  316. T}    WidgetClass
  317. T{
  318. .PN XtRWidgetList
  319. T}    WidgetList
  320. T{
  321. .PN XtRWindow
  322. T}    Window
  323. .sp 6p
  324. _
  325. .TE
  326. .sp
  327. .LP
  328. .Pn < X11/StringDefs.h >
  329. also defines the following resource types as a
  330. convenience for widgets, although they do not have any corresponding
  331. data type assigned:
  332. .PN XtREditMode ,
  333. .PN XtRJustify ,
  334. and
  335. .PN XtROrientation .
  336. .LP
  337. The \fIresource_size\fP field is the size of the physical representation in bytes;
  338. you should specify it as
  339. .PN sizeof (\fItype\fP)
  340. so that the
  341. compiler fills in the value.
  342. The \fIresource_offset\fP field is the offset in bytes of the field 
  343. within the widget.
  344. You should use the
  345. .PN XtOffsetOf
  346. macro to retrieve this value.
  347. The \fIdefault_type\fP field is the representation type of the default
  348. resource value.
  349. If \fIdefault_type\fP is different from \fIresource_type\fP and the default value
  350. is needed,
  351. the resource manager invokes a conversion procedure from \fIdefault_type\fP
  352. to \fIresource_type\fP.
  353. Whenever possible,
  354. the default type should be identical to the resource type in order
  355. to minimize widget creation time.
  356. However, there are sometimes no values of the type that the program 
  357. can easily specify.
  358. In this case,
  359. it should be a value for which the converter is guaranteed to work (for example, 
  360. .PN XtDefaultForeground
  361. for a pixel resource).
  362. The \fIdefault_addr\fP field specifies the address of the default resource value.
  363. As a special case, if \fIdefault_type\fP is
  364. .PN XtRString ,
  365. then the value in the \fIdefault_addr\fP field is the pointer to
  366. the string rather than a pointer to the pointer.
  367. The default is used if a resource is not specified in the argument list
  368. or in the resource database, or if the conversion from the representation
  369. type stored in the resource database fails,
  370. which can happen for various reasons (for example, a misspelled entry in a
  371. resource file).
  372. .LP
  373. Two special representation types 
  374. (XtRImmediate
  375. and
  376. XtRCallProc)
  377. are usable only as default resource types.
  378. XtRImmediate
  379. indicates that the value in the \fIdefault_addr\fP field is the actual value of
  380. the resource rather than the address of the value. 
  381. The value must be in the correct representation type for the resource,
  382. coerced to an
  383. .PN XtPointer .
  384. No conversion is possible, since there is no source representation type.
  385. XtRCallProc
  386. indicates that the value in the \fIdefault_addr\fP field is a procedure
  387. pointer.
  388. This procedure is automatically invoked with the widget,
  389. \fIresource_offset\fP, and a pointer to an
  390. .PN XrmValue
  391. in which to store the result.
  392. XtRCallProc
  393. procedure pointers are of type
  394. .PN XtResourceDefaultProc .
  395. .FD 0
  396. typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue*);
  397. .br
  398.       Widget \fIw\fP;
  399. .br
  400.       int \fIoffset\fP;
  401. .br
  402.       XrmValue *\fIvalue\fP;
  403. .FN
  404. .IP \fIw\fP 1i
  405. Specifies the widget whose resource value is to be obtained.
  406. .IP \fIoffset\fP 1i
  407. Specifies the offset of the field in the widget record.
  408. .IP \fIvalue\fP 1i
  409. Specifies the resource value descriptor to return.
  410. .LP
  411. The
  412. .PN XtResourceDefaultProc
  413. procedure should fill in the \fIvalue->addr\fP field with a pointer 
  414. to the resource value in its correct representation type.
  415. .sp
  416. .LP
  417. To get the resource list structure for a particular class, use
  418. .PN XtGetResourceList .
  419. .IN "XtGetResourceList" "" "@DEF@"
  420. .FD 0
  421. void XtGetResourceList(\fIclass\fP, \fIresources_return\fP, \fInum_resources_return\fP);
  422. .br
  423.       WidgetClass \fIclass\fP;
  424. .br
  425.       XtResourceList *\fIresources_return\fP;
  426. .br
  427.       Cardinal *\fInum_resources_return\fP;
  428. .FN
  429. .IP \fIclass\fP 1.5i
  430. Specifies the object class to be queried.  It must be
  431. .PN objectClass
  432. or any subclass thereof.
  433. .IP \fIresources_return\fP 1.5i
  434. Returns the resource list.
  435. .IP \fInum_resources_return\fP 1.5i
  436. Returns the number of entries in the resource list.
  437. .LP
  438. If
  439. .PN XtGetResourceList
  440. is called before the class is initialized,
  441. it returns the resource list as specified in the class record.
  442. If it is called after the class has been initialized,
  443. .PN XtGetResourceList
  444. returns a merged resource list that includes the resources 
  445. for all superclasses.
  446. The list returned by
  447. .PN XtGetResourceList
  448. should be freed using
  449. .PN XtFree
  450. when it is no longer needed.
  451. .sp
  452. .LP
  453. To get the constraint resource list structure for a particular widget
  454. class, use
  455. .PN XtGetConstraintResourceList .
  456. .IN "XtGetConstraintResourceList" "" "@DEF@"
  457. .FD 0
  458. void XtGetConstraintResourceList(\fIclass\fP, \fIresources_return\fP, \
  459. \fInum_resources_return\fP)
  460. .br
  461.       WidgetClass \fIclass\fP;
  462. .br
  463.       XtResourceList *\fIresources_return\fP;
  464. .br
  465.       Cardinal *\fInum_resources_return\fP;
  466. .FN
  467. .IP \fIclass\fP 1.5i
  468. Specifies the object class to be queried.  It must be
  469. .PN objectClass
  470. or any subclass thereof.
  471. .IP \fIresources_return\fP 1.5i
  472. Returns the constraint resource list.
  473. .IP \fInum_resources_return\fP 1.5i
  474. Returns the number of entries in the constraint resource list.
  475. .LP
  476. If
  477. .PN XtGetConstraintResourceList
  478. is called before the widget class is
  479. initialized, the resource list as specified in the widget
  480. class Constraint part is returned.  If
  481. .PN XtGetConstraintResourceList
  482. is called after the widget class has been initialized, the merged
  483. resource list for the class and all Constraint superclasses is
  484. returned.  If the
  485. specified class is not a subclass of
  486. .PN constraintWidgetClass ,
  487. *\fIresources_return\fP is set to NULL
  488. and *\fInum_resources_return\fP is set to zero.
  489. The list returned by
  490. .PN XtGetConstraintResourceList
  491. should be freed using
  492. .PN XtFree
  493. when it is no longer needed.
  494. .sp
  495. .LP
  496. The routines
  497. .PN XtSetValues
  498. and
  499. .PN XtGetValues
  500. also use the resource list to set and get widget state;
  501. see Sections 9.7.1 and 9.7.2.
  502. .LP
  503. Here is an abbreviated version of a possible resource list for a Label widget:
  504. .LP
  505. .Ds
  506. .TA .5i 1.5 3i
  507. .ta .5i 1.5 3i
  508. /* Resources specific to Label */
  509. static XtResource resources[] = {
  510. {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
  511.    XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground},
  512. {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
  513.    XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont},
  514. {XtNlabel, XtCLabel, XtRString, sizeof(String),
  515.    XtOffsetOf(LabelRec, label.label), XtRString, NULL},
  516.     .
  517.     .
  518.     .
  519. }
  520. .De
  521. .LP
  522. The complete resource name for a field of a widget instance is the
  523. concatenation of the application shell name (from 
  524. .PN XtAppCreateShell ),
  525. the instance names of all the widget's parents up to the 
  526. top of the widget tree,
  527. the instance name of the widget itself,
  528. and the resource name of the specified field of the widget.
  529. Similarly,
  530. the full resource class of a field of a widget instance is the
  531. concatenation of the application class (from
  532. .PN XtAppCreateShell ),
  533. the widget class names of all the widget's parents up to the 
  534. top of the widget tree,
  535. the widget class name of the widget itself,
  536. and the resource class of the specified field of the widget.
  537.  
  538. .NH 2
  539. Byte Offset Calculations
  540. .XS
  541. \*(SN Byte Offset Calculations
  542. .XE
  543. .LP
  544. To determine the byte offset of a field within a structure type, use
  545. .PN XtOffsetOf .
  546. .IN "XtOffsetOf" "" "@DEF@"
  547. .FD 0
  548. Cardinal XtOffsetOf(\fIstructure_type\fP, \fIfield_name\fP)
  549. .br
  550.       \fIType structure_type\fP;
  551. .br
  552.       \fIField field_name\fP;
  553. .FN
  554. .IP \fIstructure_type\fP 1i
  555. Specifies a type that is declared as a structure.
  556. .IP \fIfield_name\fP 1i
  557. Specifies the name of a member within the structure.
  558. .LP
  559. The
  560. .PN XtOffsetOf
  561. macro expands to a constant expression that gives the
  562. offset in bytes to the specified structure member from the beginning
  563. of the structure.  It is normally used to statically initialize
  564. resource lists and is more portable than
  565. .PN XtOffset ,
  566. which serves the same function.
  567.  
  568. .LP
  569. To determine the byte offset of a field within a structure pointer type, use
  570. .PN XtOffset .
  571. .IN "XtOffset" "" "@DEF@"
  572. .FD 0
  573. Cardinal XtOffset(\fIpointer_type\fP, \fIfield_name\fP)
  574. .br
  575.       \fIType pointer_type\fP;
  576. .br
  577.       \fIField field_name\fP;
  578. .FN
  579. .IP \fIpointer_type\fP 1i
  580. Specifies a type that is declared as a pointer to a structure.
  581. .IP \fIfield_name\fP 1i
  582. Specifies the name of a member within the structure.
  583. .LP
  584. The
  585. .PN XtOffset
  586. macro expands to a constant expression that gives the
  587. offset in bytes to the specified structure member from the beginning
  588. of the structure.  It may be used to statically initialize
  589. resource lists.
  590. .PN XtOffset
  591. is less portable than
  592. .PN XtOffsetOf .
  593.  
  594. .NH 2
  595. Superclass-to-Subclass Chaining of Resource Lists
  596. .XS
  597. \*(SN Superclass-to-Subclass Chaining of Resource Lists
  598. .XE
  599. .LP
  600. .IN "Inheritance"
  601. .IN "Superclass Chaining"
  602. .IN "Chaining"
  603. The 
  604. .PN XtCreateWidget
  605. function gets resources as a superclass-to-subclass chained operation.
  606. That is, the resources specified in the
  607. .PN objectClass
  608. resource list are fetched,
  609. then those in
  610. .PN rectObjClass ,
  611. and so on down to the resources specified
  612. for this widget's class. Within a class, resources are fetched in the order
  613. they are declared.
  614. .LP
  615. In general, if a widget resource field is declared in a superclass,
  616. that field is included in the superclass's resource list and need not be
  617. included in the subclass's resource list.
  618. For example, the
  619. Core 
  620. class contains a resource entry for \fIbackground_pixel\fP.
  621. Consequently,
  622. the implementation of Label need not also have a resource entry
  623. for \fIbackground_pixel\fP.
  624. However, a subclass,
  625. by specifying a resource entry for that field in its own resource list,
  626. can override the resource entry for any field declared in a superclass.
  627. This is most often done to override the defaults provided in the
  628. superclass with new ones.
  629. At class initialization time, 
  630. resource lists for that class are scanned from the superclass down 
  631. to the class to look for resources with the same offset.
  632. A matching resource in a subclass will be reordered to override
  633. the superclass entry.
  634. If reordering is necessary, a copy of the superclass resource list is made to
  635. avoid affecting other subclasses of the superclass.
  636. .LP
  637. .IN "class_initialize procedure"
  638. .IN "Widget" "class initialization"
  639. Also at class initialization time, the \*(xI produce an
  640. internal representation of the resource list to optimize access time
  641. when creating widgets.  In order to save memory, the \*(xI may
  642. overwrite the storage allocated for the resource list in the class
  643. record; therefore, widgets must allocate resource lists in writable
  644. storage and must not access the list contents directly after the
  645. class_initialize procedure has returned.
  646.  
  647. .NH 2
  648. Subresources
  649. .XS
  650. \*(SN Subresources
  651. .XE
  652. .LP
  653. A widget does not do anything to retrieve its own resources;
  654. instead,
  655. .PN XtCreateWidget
  656. does this automatically before calling the class initialize procedure.
  657. .LP
  658. Some widgets have subparts that are not widgets but for which the widget
  659. would like to fetch resources.
  660. Such widgets call
  661. .PN XtGetSubresources
  662. to accomplish this.
  663. .IN "XtGetSubresources" "" "@DEF@"
  664. .FD 0
  665. void XtGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
  666. \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
  667. .br
  668.       Widget \fIw\fP;
  669. .br
  670.       XtPointer \fIbase\fP;
  671. .br
  672.       String \fIname\fP;
  673. .br
  674.       String \fIclass\fP;
  675. .br
  676.       XtResourceList \fIresources\fP;
  677. .br
  678.       Cardinal \fInum_resources\fP;
  679. .br
  680.       ArgList \fIargs\fP;
  681. .br
  682.       Cardinal \fInum_args\fP;
  683. .FN
  684. .IP \fIw\fP 1i
  685. Specifies the object used to qualify the subpart resource name and
  686. class.  \*(oI
  687. .IP \fIbase\fP 1i
  688. Specifies the base address of the subpart data structure into which the
  689. resources will be written.
  690. .IP \fIname\fP 1i
  691. Specifies the name of the subpart.
  692. .IP \fIclass\fP 1i
  693. Specifies the class of the subpart.
  694. .IP \fIresources\fP 1i
  695. Specifies the resource list for the subpart.
  696. .IP \fInum_resources\fP 1i
  697. Specifies the number of entries in the resource list.
  698. .IP \fIargs\fP 1i
  699. Specifies the argument list to override any other resource specifications.
  700. .IP \fInum_args\fP 1i
  701. Specifies the number of entries in the argument list.
  702. .LP
  703. The
  704. .PN XtGetSubresources
  705. function constructs a name and class list from the application name and class,
  706. the names and classes of all the object's ancestors, and the object itself.
  707. Then it appends to this list the \fIname\fP and \fIclass\fP pair passed in.
  708. The resources are fetched from the argument list, the resource database,
  709. or the default values in the resource list.
  710. Then they are copied into the subpart record.
  711. If \fIargs\fP is NULL,
  712. \fInum_args\fP must be zero.
  713. However, if \fInum_args\fP is zero,
  714. the argument list is not referenced.
  715. .LP
  716. .PN XtGetSubresources
  717. may overwrite the specified resource list with an
  718. equivalent representation in an internal format, which optimizes access
  719. time if the list is used repeatedly.  The resource list must be
  720. allocated in writable storage, and the caller must not modify the list
  721. contents after the call if the same list is to be used again.
  722. Resources fetched by
  723. .PN XtGetSubresources
  724. are reference-counted as
  725. if they were referenced by the specified object.  Subresources might
  726. therefore be freed from the conversion cache and destroyed
  727. when the object is destroyed, but not before then.
  728. .sp
  729. .LP
  730. To fetch resources for widget subparts using varargs lists, use
  731. .PN XtVaGetSubresources .
  732. .IN "XtVaGetSubresources" "" "@DEF@"
  733. .FD 0
  734. void XtVaGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
  735. \fIresources\fP, \fInum_resources\fP, ...)
  736. .br
  737.     Widget \fIw\fP;
  738. .br
  739.     XtPointer \fIbase\fP;
  740. .br
  741.     String \fIname\fP;
  742. .br
  743.     String \fIclass\fP;
  744. .br
  745.     XtResourceList \fIresources\fP;
  746. .br
  747.     Cardinal \fInum_resources\fP;
  748. .FN
  749. .IP \fIw\fP 1i
  750. Specifies the object used to qualify the subpart resource name and
  751. class.  \*(oI
  752. .IP \fIbase\fP 1i
  753. Specifies the base address of the subpart data structure into which the
  754. resources will be written.
  755. .IP \fIname\fP 1i
  756. Specifies the name of the subpart.
  757. .IP \fIclass\fP 1i
  758. Specifies the class of the subpart.
  759. .IP \fIresources\fP 1i
  760. Specifies the resource list for the subpart.
  761. .IP \fInum_resources\fP 1i
  762. Specifies the number of entries in the resource list.
  763. .IP ... 1i
  764. Specifies the variable argument list to override any other
  765. resource specifications.
  766. .LP
  767. .PN XtVaGetSubresources
  768. is identical in function to
  769. .PN XtGetSubresources
  770. with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
  771. described in Section 2.5.1.
  772.  
  773. .NH 2
  774. Obtaining Application Resources
  775. .XS
  776. \fB\*(SN Obtaining Application Resources\fP
  777. .XE
  778. .LP
  779. To retrieve resources that are not specific to a widget
  780. but apply to the overall application, use
  781. .PN XtGetApplicationResources .
  782. .IN "XtGetApplicationResources" "" "@DEF@"
  783. .FD 0
  784. void XtGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \
  785. \fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
  786. .br
  787.       Widget \fIw\fP;
  788. .br
  789.       XtPointer \fIbase\fP;
  790. .br
  791.       XtResourceList \fIresources\fP;
  792. .br
  793.       Cardinal \fInum_resources\fP;
  794. .br
  795.       ArgList \fIargs\fP;
  796. .br
  797.       Cardinal \fInum_args\fP;
  798. .FN
  799. .IP \fIw\fP 1i
  800. Specifies the object that identifies the resource database to search
  801. (the database is that associated with the display for this object).  \*(oI
  802. .IP \fIbase\fP 1i
  803. Specifies the base address into which
  804. the resource values will be written.
  805. .IP \fIresources\fP 1i
  806. Specifies the resource list.
  807. .IP \fInum_resources\fP 1i
  808. Specifies the number of entries in the resource list.
  809. .IP \fIargs\fP 1i
  810. Specifies the argument list to override any other resource specifications.
  811. .IP \fInum_args\fP 1i
  812. Specifies the number of entries in the argument list.
  813. .LP
  814. The
  815. .PN XtGetApplicationResources
  816. function first uses the passed object,
  817. which is usually an application shell widget,
  818. to construct a resource name and class list.
  819. The full name and class of the specified object (that is, including its
  820. ancestors, if any) is logically added to the
  821. front of each resource name and class.
  822. Then it retrieves the resources from the argument list,
  823. the resource database, or the resource list default values.
  824. After adding base to each address,
  825. .PN XtGetApplicationResources
  826. copies the resources into the addresses
  827. obtained by adding \fIbase\fP to each \fIoffset\fP in the resource list.
  828. If \fIargs\fP is NULL,
  829. \fInum_args\fP must be zero.
  830. However, if \fInum_args\fP is zero,
  831. the argument list is not referenced.
  832. The portable way to specify application resources is to declare them
  833. as members of a structure and pass the address of the structure 
  834. as the \fIbase\fP argument.
  835. .LP
  836. .PN XtGetApplicationResources
  837. may overwrite the specified resource list
  838. with an equivalent representation in an internal format, which
  839. optimizes access time if the list is used repeatedly.  The resource
  840. list must be allocated in writable storage, and the caller must not
  841. modify the list contents after the call if the same list is to be
  842. used again.  Any per-display resources fetched by
  843. .PN XtGetApplicationResources
  844. will not be freed from the resource cache until the display is closed.
  845. .sp
  846. .LP
  847. To retrieve resources for the overall application using varargs lists, use
  848. .PN XtVaGetApplicationResources .
  849. .IN "XtVaGetApplicationResources" "" "@DEF@"
  850. .FD 0
  851. void XtVaGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \
  852. \fInum_resources\fP, ...)
  853. .br
  854.       Widget \fIw\fP;
  855. .br
  856.       XtPointer \fIbase\fP;
  857. .br
  858.       XtResourceList \fIresources\fP;
  859. .br
  860.       Cardinal \fInum_resources\fP;
  861. .FN
  862. .IP \fIw\fP 1i
  863. Specifies the object that identifies the resource database to search
  864. (the database is that associated with the display for this object).  \*(oI
  865. .IP \fIbase\fP 1i
  866. Specifies the base address into which
  867. the resource values will be written.
  868. .IP \fIresources\fP 1i
  869. Specifies the resource list for the subpart.
  870. .IP \fInum_resources\fP 1i
  871. Specifies the number of entries in the resource list.
  872. .IP ... 1i
  873. Specifies the variable argument list to override any other
  874. resource specifications.
  875. .LP
  876. .PN XtVaGetApplicationResources
  877. is identical in function to
  878. .PN XtGetApplicationResources
  879. with the \fIargs\fP and \fInum_args\fP parameters
  880. replaced by a varargs list, as described in Section 2.5.1.
  881.  
  882. .NH 2
  883. Resource Conversions
  884. .XS
  885. \*(SN Resource Conversions
  886. .XE
  887. .LP
  888. The \*(xI provide a mechanism for registering representation converters that
  889. are automatically invoked by the resource-fetching routines.
  890. The \*(xI additionally provide and register several commonly used converters.
  891. This resource conversion mechanism serves several purposes:
  892. .IP \(bu 5
  893. It permits user and application resource files to contain textual
  894. representations of nontextual values.
  895. .IP \(bu 5
  896. It allows textual or other representations of default resource values that
  897. are dependent on the display, screen, or colormap, and thus must be
  898. computed at runtime.
  899. .IP \(bu 5
  900. It caches conversion source and result data.
  901. Conversions that require much computation or space
  902. (for example, string-to-translation-table)
  903. or that require round-trips to the server
  904. (for example, string-to-font or string-to-color) are performed only once.
  905.  
  906. .NH 3
  907. Predefined Resource Converters
  908. .XS
  909. \*(SN Predefined Resource Converters
  910. .XE
  911. .LP
  912. The \*(xI define all the representations used in the 
  913. Object,
  914. RectObj,
  915. Core, 
  916. Composite, 
  917. Constraint, 
  918. and 
  919. Shell 
  920. widget classes.
  921. The \*(xI register the following resource converters that accept
  922. input values of representation type
  923. .PN XtRString .
  924. .LP
  925. .TS
  926. lw(1.5i) lw(2.25i) lw(1.5i) .
  927. _
  928. .sp 6p
  929. Target Representation    Converter Name    Additional Args
  930. .sp 6p
  931. _
  932. .sp 6p
  933. T{
  934. .PN XtRAcceleratorTable
  935. T}    T{
  936. .PN XtCvtStringToAcceleratorTable
  937. T}
  938. T{
  939. .PN XtRAtom
  940. T}    T{
  941. .PN XtCvtStringToAtom
  942. T}    Display*
  943. T{
  944. .PN XtRBoolean
  945. T}    T{
  946. .PN XtCvtStringToBoolean
  947. T}
  948. T{
  949. .PN XtRBool
  950. T}    T{
  951. .PN XtCvtStringToBool
  952. T}
  953. T{
  954. .PN XtRCursor
  955. T}    T{
  956. .PN XtCvtStringToCursor
  957. T}    Display*
  958. T{
  959. .PN XtRDimension
  960. T}    T{
  961. .PN XtCvtStringToDimension
  962. T}
  963. T{
  964. .PN XtRDisplay
  965. T}    T{
  966. .PN XtCvtStringToDisplay
  967. T}
  968. T{
  969. .PN XtRFile
  970. T}    T{
  971. .PN XtCvtStringToFile
  972. T}
  973. T{
  974. .PN XtRFloat
  975. T}    T{
  976. .PN XtCvtStringToFloat
  977. T}
  978. T{
  979. .PN XtRFont
  980. T}    T{
  981. .PN XtCvtStringToFont
  982. T}    Display*
  983. T{
  984. .PN XtRFontSet
  985. T}    T{
  986. .PN XtCvtStringToFontSet
  987. T}    Display*, String \fIlocale\fP
  988. T{
  989. .PN XtRFontStruct
  990. T}    T{
  991. .PN XtCvtStringToFontStruct
  992. T}    Display*
  993. T{
  994. .PN XtRInitialState
  995. T}    T{
  996. .PN XtCvtStringToInitialState
  997. T}
  998. T{
  999. .PN XtRInt
  1000. T}    T{
  1001. .PN XtCvtStringToInt
  1002. T}
  1003. T{
  1004. .PN XtRPixel
  1005. T}    T{
  1006. .PN XtCvtStringToPixel
  1007. T}    T{
  1008. .PN colorConvertArgs
  1009. T}
  1010. T{
  1011. .PN XtRPosition
  1012. T}    T{
  1013. .PN XtCvtStringToPosition
  1014. T}
  1015. T{
  1016. .PN XtRShort
  1017. T}    T{
  1018. .PN XtCvtStringToShort
  1019. T}
  1020. T{
  1021. .PN XtRTranslationTable
  1022. T}    T{
  1023. .PN XtCvtStringToTranslationTable
  1024. T}
  1025. T{
  1026. .PN XtRUnsignedChar
  1027. T}    T{
  1028. .PN XtCvtStringToUnsignedChar
  1029. T}
  1030. T{
  1031. .PN XtRVisual
  1032. T}    T{
  1033. .PN XtCvtStringToVisual
  1034. T}    Screen*, Cardinal \fIdepth\fP
  1035. .sp 6p
  1036. _
  1037. .TE
  1038.  
  1039. .LP
  1040. The String-to-Pixel conversion has two predefined constants that are
  1041. guaranteed to work and contrast with each other:
  1042. .PN XtDefaultForeground
  1043. and
  1044. .PN XtDefaultBackground .
  1045. .IN "XtDefaultBackground" "" "@DEF@"
  1046. .IN "XtDefaultForeground" "" "@DEF@"
  1047. They evaluate to the black and white pixel values of the widget's screen, 
  1048. respectively.
  1049. .IN "Resources" "reverseVideo"
  1050. If the application resource reverseVideo is
  1051. .PN True ,
  1052. they evaluate to the white and black pixel values of the widget's screen,
  1053. respectively.
  1054. Similarly, the String-to-Font and String-to-FontStruct converters recognize
  1055. the constant
  1056. .PN XtDefaultFont
  1057. .IN "XtDefaultFont" "" "@DEF@"
  1058. .IN "Resources" "xtDefaultFont"
  1059. and evaluate this in the following manner:
  1060. .IP \(bu 5
  1061. Query the resource database for the resource whose full name
  1062. is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget
  1063. name/class prefixes) and use a type
  1064. .PN XtRString
  1065. value returned as the font name, or a type
  1066. .PN XtRFont
  1067. or
  1068. .PN XtRFontStruct
  1069. value directly as the resource value.
  1070. .IP \(bu 5
  1071. If the resource database does not contain a value for xtDefaultFont,
  1072. class XtDefaultFont, or if the returned font name cannot be
  1073. successfully opened, an implementation-defined font in ISO8859-1
  1074. character set encoding is opened.  (One possible algorithm is to
  1075. perform an
  1076. .PN XListFonts
  1077. using a wildcard font name and use the first
  1078. font in the list.  This wildcard font name should be as broad as
  1079. possible to maximize the probability of locating a useable font;
  1080. for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".)
  1081. .IP \(bu 5
  1082. If no suitable ISO8859-1 font can be found, issue a warning message
  1083. and return
  1084. .PN False .
  1085. .LP
  1086. The String-to-FontSet converter recognizes the constant
  1087. .PN XtDefaultFontSet
  1088. .IN "XtDefaultFontSet" "" "@DEF@"
  1089. .IN "Resources" "xtDefaultFontSet"
  1090. and evaluate this in the following manner:
  1091. .IP \(bu 5
  1092. Query the resource database for the resource whose full name
  1093. is ``xtDefaultFontSet'', class ``XtDefaultFontSet'' (that is, no widget
  1094. name/class prefixes) and use a type
  1095. .PN XtRString
  1096. value returned as the base font name list, or a type
  1097. .PN XtRFontSet
  1098. value directly as the resource value.
  1099. .IP \(bu 5
  1100. If the resource database does not contain a value for xtDefaultFontSet,
  1101. class XtDefaultFontSet, or if a font set cannot be
  1102. successfully created from this resource,
  1103. an implementation-defined font set is created.
  1104. (One possible algorithm is to
  1105. perform an
  1106. .PN XCreateFontSet
  1107. using a wildcard base font name.
  1108. This wildcard base font name should be as broad as
  1109. possible to maximize the probability of locating a useable font;
  1110. for example, "-*-*-*-R-*-*-*-120-*-*-*-*".)
  1111. .IP \(bu 5
  1112. If no suitable font set can be created, issue a warning message
  1113. and return
  1114. .PN False .
  1115. .LP
  1116. If a font set is created but \fImissing_charset_list\fP is not
  1117. empty, a warning is issued and the partial font set is returned.
  1118. The \*(xI register the String-to-FontSet converter with
  1119. a conversion argument list that extracts the current process
  1120. locale at the time the converter is invoked.   This ensures
  1121. that the converter is invoked again if the same conversion
  1122. is required in a different locale.
  1123. .LP
  1124. The String-to-InitialState conversion accepts the values
  1125. .PN NormalState
  1126. or
  1127. .PN IconicState
  1128. as defined by the \fI\*(xC\fP.
  1129. .LP
  1130. The String-to-Visual conversion calls
  1131. .PN XMatchVisualInfo
  1132. using the
  1133. \fIscreen\fP and \fIdepth\fP fields from the core part and returns the first
  1134. matching Visual on the list.  The widget resource list must be certain
  1135. to specify any resource of type
  1136. .PN XtRVisual
  1137. after the depth resource.
  1138. The allowed string values are the visual class names defined in \fI\*(xP\fP,
  1139. Section 8;
  1140. .PN StaticGray ,
  1141. .PN StaticColor ,
  1142. .PN TrueColor ,
  1143. .PN GrayScale ,
  1144. .PN PseudoColor ,
  1145. and
  1146. .PN DirectColor .
  1147.  
  1148. .LP
  1149. The \*(xI register the following resource converter that accepts
  1150. an input value of representation type
  1151. .PN XtRColor .
  1152. .LP
  1153. .TS
  1154. lw(1.5i) lw(2.25i) lw(1.5i) .
  1155. _
  1156. .sp 6p
  1157. Target Representation    Converter Name    Additional Args
  1158. .sp 6p
  1159. _
  1160. .sp 6p
  1161. T{
  1162. .PN XtRPixel
  1163. T}    T{
  1164. .PN XtCvtColorToPixel
  1165. T}
  1166. .sp 6p
  1167. _
  1168. .TE
  1169.  
  1170. .LP
  1171. The \*(xI register the following resource converters that accept
  1172. input values of representation type
  1173. .PN XtRInt .
  1174. .LP
  1175. .TS
  1176. lw(1.5i) lw(2.25i) lw(1.5i) .
  1177. _
  1178. .sp 6p
  1179. Target Representation    Converter Name    Additional Args
  1180. .sp 6p
  1181. _
  1182. .sp 6p
  1183. T{
  1184. .PN XtRBoolean
  1185. T}    T{
  1186. .PN XtCvtIntToBoolean
  1187. T}
  1188. T{
  1189. .PN XtRBool
  1190. T}    T{
  1191. .PN XtCvtIntToBool
  1192. T}
  1193. T{
  1194. .PN XtRColor
  1195. T}    T{
  1196. .PN XtCvtIntToColor
  1197. T}    T{
  1198. .PN colorConvertArgs
  1199. T}
  1200. T{
  1201. .PN XtRDimension
  1202. T}    T{
  1203. .PN XtCvtIntToDimension
  1204. T}
  1205. T{
  1206. .PN XtRFloat
  1207. T}    T{
  1208. .PN XtCvtIntToFloat
  1209. T}
  1210. T{
  1211. .PN XtRFont
  1212. T}    T{
  1213. .PN XtCvtIntToFont
  1214. T}
  1215. T{
  1216. .PN XtRPixel
  1217. T}    T{
  1218. .PN XtCvtIntToPixel
  1219. T}
  1220. T{
  1221. .PN XtRPixmap
  1222. T}    T{
  1223. .PN XtCvtIntToPixmap
  1224. T}
  1225. T{
  1226. .PN XtRPosition
  1227. T}    T{
  1228. .PN XtCvtIntToPosition
  1229. T}
  1230. T{
  1231. .PN XtRShort
  1232. T}    T{
  1233. .PN XtCvtIntToShort
  1234. T}
  1235. T{
  1236. .PN XtRUnsignedChar
  1237. T}    T{
  1238. .PN XtCvtIntToUnsignedChar
  1239. T}
  1240. .sp 6p
  1241. _
  1242. .TE
  1243.  
  1244. .LP
  1245. The \*(xI register the following resource converter that accepts
  1246. an input value of representation type
  1247. .PN XtRPixel .
  1248. .LP
  1249. .TS
  1250. lw(1.5i) lw(2.25i) lw(1.5i) .
  1251. _
  1252. .sp 6p
  1253. Target Representation    Converter Name    Additional Args
  1254. .sp 6p
  1255. _
  1256. .sp 6p
  1257. T{
  1258. .PN XtRColor
  1259. T}    T{
  1260. .PN XtCvtPixelToColor
  1261. T}
  1262. .sp 6p
  1263. _
  1264. .TE
  1265.  
  1266. .NH 3
  1267. New Resource Converters
  1268. .XS
  1269. \*(SN New Resource Converters
  1270. .XE
  1271. .LP
  1272. Type converters use pointers to
  1273. .PN XrmValue
  1274. structures (defined in
  1275. .Pn < X11/Xresource.h >;
  1276. see Section 15.4 in \fI\*(xL\fP)
  1277. for input and output values.
  1278. .LP
  1279. .Ds 0
  1280. .TA .5i 3i
  1281. .ta .5i 3i
  1282. typedef struct {
  1283.     unsigned int size;
  1284.     XPointer addr;
  1285. } XrmValue, *XrmValuePtr;
  1286. .De
  1287. .LP
  1288. The \fIaddr\fP field specifies the address of the data and the \fIsize\fP field
  1289. gives the total number of significant bytes in the data.  For values
  1290. of type
  1291. .PN String ,
  1292. \fIaddr\fP is the address of the first character and \fIsize\fP
  1293. includes the NUL terminating byte. 
  1294. .LP
  1295. A resource converter procedure pointer is of type
  1296. .PN XtTypeConverter .
  1297. .IN "XtTypeConverter" "" "@DEF@"
  1298. .FD 0
  1299. typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*,
  1300.                               XrmValue*, XrmValue*, XtPointer*);
  1301. .br
  1302.       Display *\fIdisplay\fP;
  1303. .br
  1304.       XrmValue *\fIargs\fP;
  1305. .br
  1306.       Cardinal *\fInum_args\fP;
  1307. .br
  1308.       XrmValue *\fIfrom\fP;
  1309. .br
  1310.       XrmValue *\fIto\fP;
  1311. .br
  1312.       XtPointer *\fIconverter_data\fP;
  1313. .FN
  1314. .IP \fIdisplay\fP 1i
  1315. Specifies the display connection with which this conversion is associated.
  1316. .IP \fIargs\fP 1i
  1317. Specifies a list of additional
  1318. .PN XrmValue
  1319. arguments to the converter if additional context is needed
  1320. to perform the conversion, or NULL.
  1321. For example, the String-to-Font converter needs the widget's \fIscreen\fP,
  1322. and the String-to-Pixel converter needs the widget's \fIscreen\fP and \fIcolormap\fP.
  1323. .IP \fInum_args\fP 1i
  1324. Specifies the number of entries in \fIargs\fP.
  1325. .IP \fIfrom\fP 1i
  1326. Specifies the value to convert.
  1327. .IP \fIto\fP 1i
  1328. Specifies a descriptor for a location into which to store the converted value.
  1329. .IP \fIconverter_data\fP 1i
  1330. Specifies a location into which the converter may
  1331. store converter-specific data associated
  1332. with this conversion.
  1333. .LP
  1334. The \fIdisplay\fP argument is normally used only when generating error
  1335. messages, to identify the application context (with the function
  1336. .PN XtDisplayToApplicationContext ).
  1337. .LP
  1338. The \fIto\fP argument specifies the size and location into which the
  1339. converter should store the converted value.  If the \fIaddr\fP field is NULL,
  1340. the converter should allocate appropriate storage and store the size
  1341. and location into the \fIto\fP descriptor.  If the type converter allocates
  1342. the storage, it remains under the ownership of the converter and must
  1343. not be modified by the caller.  The type converter is permitted to use
  1344. static storage for this purpose, and therefore the caller must
  1345. immediately copy the data upon return from the converter.  If the
  1346. \fIaddr\fP field is not NULL, the converter must check the \fIsize\fP field to
  1347. ensure that sufficient space has been allocated before storing the
  1348. converted value.  If insufficient space is specified, the converter
  1349. should update the \fIsize\fP field with the number of bytes required and
  1350. return
  1351. .PN False
  1352. without modifying the data at the specified location.
  1353. If sufficient space was allocated by the caller, the converter should
  1354. update the \fIsize\fP field with the number of bytes actually occupied by the
  1355. converted value.  For converted values of type
  1356. .PN XtRString ,
  1357. the size should
  1358. include the NULL terminating byte, if any.
  1359. The converter may store any value in the location specified
  1360. in \fIconverter_data\fP; this data will be passed to the destructor, if any,
  1361. when the resource is freed by the \*(xI.
  1362. .LP
  1363. The converter must return
  1364. .PN True
  1365. if the conversion was successful and
  1366. .PN False
  1367. otherwise.  If the conversion cannot be performed because of an
  1368. improper source value, a warning message should also be issued with
  1369. .PN XtAppWarningMsg .
  1370.  
  1371. .LP
  1372. Most type converters just take the data described by the specified \fIfrom\fP
  1373. argument and return data by writing into the location specified in
  1374. the \fIto\fP argument.
  1375. A few need other information, which is available in \fIargs\fP.
  1376. A type converter can invoke another type converter,
  1377. which allows differing sources that may convert into a common intermediate
  1378. result to make maximum use of the type converter cache.
  1379. .LP
  1380. Note that if an address is written into \fIto->addr\fP, it cannot be that
  1381. of a local variable of the converter because the data will not be
  1382. valid after the converter returns.  Static variables may be used,
  1383. as in the following example.
  1384. If the converter modifies the resource database,
  1385. the changes affect any in-progress widget creation,
  1386. .PN XtGetApplicationResources ,
  1387. or
  1388. .PN XtGetSubresources
  1389. in an implementation-defined manner; however, insertion of new entries
  1390. or changes to existing entries is allowed and will not directly cause
  1391. an error.
  1392.  
  1393. .LP
  1394. The following is an example of a converter that takes a
  1395. .PN string
  1396. and converts it to a
  1397. .PN Pixel .
  1398. Note that the \fIdisplay\fP parameter is only
  1399. used to generate error messages; the
  1400. .PN Screen
  1401. conversion argument is
  1402. still required to inform the \*(xI that the converted value is
  1403. a function of the particular display (and colormap).
  1404. .LP
  1405. .Ds 0
  1406. .TA .3i .7i 1i 1.3i 1.7i 2i 4i
  1407. .ta .3i .7i 1i 1.3i 1.7i 2i 4i
  1408.  
  1409. #define done(type, value) \\
  1410.     {                        \\
  1411.         if (toVal->addr != NULL) {        \\
  1412.             if (toVal->size < sizeof(type)) {    \\
  1413.                 toVal->size = sizeof(type);    \\
  1414.                 return False;    \\
  1415.             }                \\
  1416.             *(type*)(toVal->addr) = (value);    \\
  1417.         }                    \\
  1418.         else {                \\
  1419.             static type static_val;    \\
  1420.             static_val = (value);    \\
  1421.             toVal->addr = (XPointer)&static_val;    \\
  1422.         }                    \\
  1423.         toVal->size = sizeof(type);    \\
  1424.         return True;            \\
  1425.     }
  1426.  
  1427. static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_data)
  1428.     Display    *dpy;
  1429.     XrmValue    *args;
  1430.     Cardinal    *num_args;
  1431.     XrmValue    *fromVal;
  1432.     XrmValue    *toVal;
  1433.     XtPointer    *converter_data;
  1434. {
  1435.     static XColor    screenColor;
  1436.     XColor        exactColor;
  1437.     Screen        *screen;
  1438.     Colormap        colormap;
  1439.     Status            status;
  1440.     char            message[1000];
  1441.  
  1442.     if (*num_args != 2)
  1443.         XtAppErrorMsg(XtDisplayToApplicationContext(dpy),
  1444.             "cvtStringToPixel", "wrongParameters", "XtToolkitError",
  1445.             "String to pixel conversion needs screen and colormap arguments",
  1446.             (String *)NULL, (Cardinal *)NULL);
  1447.  
  1448.     screen = *((Screen**) args[0].addr);
  1449.     colormap = *((Colormap *) args[1].addr);
  1450.  
  1451.     LowerCase((char *) fromVal->addr, message);
  1452.  
  1453.     if (strcmp(message, "xtdefaultbackground") == 0) done(&WhitePixelOfScreen(screen), Pixel);
  1454.     if (strcmp(message, "xtdefaultforeground") == 0) done(&BlackPixelOfScreen(screen), Pixel);
  1455.  
  1456.     status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, 
  1457.                 &screenColor, &exactColor);
  1458.  
  1459.     if (status == 0) {
  1460.         String params[1];
  1461.         Cardinal num_params = 1;
  1462.         params[0] = (String)fromVal->addr;
  1463.         XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
  1464.             "cvtStringToPixel", "noColormap", "XtToolkitError",
  1465.             "Cannot allocate colormap entry for \\"%s\\"", params, &num_params);
  1466.     } else {
  1467.         done( &screenColor.pixel, Pixel );
  1468.     }
  1469.  
  1470.     /* converter_data not used here */
  1471. };
  1472. .De
  1473. .LP
  1474. All type converters should define some set of conversion values for which they
  1475. are guaranteed to succeed so these can be used in the resource defaults.
  1476. This issue arises only with conversions, such as fonts and colors,
  1477. where there is no string representation that all server implementations
  1478. will necessarily recognize.
  1479. For resources like these,
  1480. the converter should define a symbolic constant
  1481. in the same manner as
  1482. .PN XtDefaultForeground ,
  1483. .PN XtDefaultBackground ,
  1484. and
  1485. .PN XtDefaultFont .
  1486. .sp
  1487. .LP
  1488. To allow the \*(xI to deallocate resources produced by type
  1489. converters, a resource destructor procedure may also be provided.
  1490. .LP
  1491. A resource destructor procedure pointer is of type
  1492. .PN XtDestructor .
  1493. .IN "XtDestructor" "" "@DEF@"
  1494. .FD 0
  1495. typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, \
  1496. Cardinal*);
  1497. .br
  1498.       XtAppContext \fIapp\fP;
  1499. .br
  1500.       XrmValue *\fIto\fP;
  1501. .br
  1502.       XtPointer \fIconverter_data\fP;
  1503. .br
  1504.       XrmValue *\fIargs\fP;
  1505. .br
  1506.       Cardinal *\fInum_args\fP;
  1507. .FN
  1508. .IP \fIapp\fP 1i
  1509. Specifies an application context in which the resource is being freed.
  1510. .IP \fIto\fP 1i
  1511. Specifies a descriptor for the resource produced by the type converter.
  1512. .IP \fIconverter_data\fP 1i
  1513. Specifies the converter-specific data returned by the type converter.
  1514. .IP \fIargs\fP 1i
  1515. Specifies the additional converter arguments as passed
  1516. to the type converter when the conversion was performed.
  1517. .IP \fInum_args\fP 1i
  1518. Specifies the number of entries in \fIargs\fP.
  1519. .LP
  1520. The destructor procedure is responsible for freeing the resource
  1521. specified by the \fIto\fP argument, including any auxiliary storage
  1522. associated with that resource, but not the memory directly addressed
  1523. by the size and location in the \fIto\fP argument nor the memory specified
  1524. by \fIargs\fP.
  1525.  
  1526. .NH 3
  1527. Issuing Conversion Warnings
  1528. .XS
  1529. \*(SN Issuing Conversion Warnings
  1530. .XE
  1531. .LP
  1532. The
  1533. .PN XtDisplayStringConversionWarning
  1534. procedure is a convenience routine for resource type converters
  1535. that convert from string values.
  1536. .IN "XtDisplayStringConversionWarning" "" "@DEF@"
  1537. .FD 0
  1538. void XtDisplayStringConversionWarning(\fIdisplay\fP, \fIfrom_value\fP, \
  1539. \fIto_type\fP)
  1540. .br
  1541.       Display *\fIdisplay\fP;
  1542. .br
  1543.       String \fIfrom_value\fP, \fIto_type\fP;
  1544. .FN
  1545. .IP \fIdisplay\fP 1i
  1546. Specifies the display connection with which the conversion is associated.
  1547. .IP \fIfrom_value\fP 1i
  1548. Specifies the string that could not be converted.
  1549. .IP \fIto_type\fP 1i
  1550. Specifies the target representation type requested.
  1551. .LP
  1552. The
  1553. .PN XtDisplayStringConversionWarning
  1554. procedure issues a warning message using
  1555. .PN XtAppWarningMsg
  1556. with \fIname\fP ``conversionError'',
  1557. \fItype\fP ``string'', \fIclass\fP ``XtToolkitError'', and the default message
  1558. ``Cannot convert "\fIfrom_value\fP" to type \fIto_type\fP''.
  1559. .LP
  1560. To issue other types of warning or error messages, the type converter
  1561. should use
  1562. .PN XtAppWarningMsg
  1563. or
  1564. .PN XtAppErrorMsg .
  1565. .sp
  1566. .LP
  1567. To retrieve the application context associated with a given
  1568. display connection, use
  1569. .PN XtDisplayToApplicationContext .
  1570. .IN "XtDisplayToApplicationContext" "" "@DEF@"
  1571. .FD 0
  1572. XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP )
  1573. .br
  1574.       Display *\fIdisplay\fP;
  1575. .FN
  1576. .IP \fIdisplay\fP 1i
  1577. Specifies an open and initialized display connection.
  1578. .LP
  1579. The
  1580. .PN XtDisplayToApplicationContext
  1581. function returns the application
  1582. context in which the specified \fIdisplay\fP was initialized.  If the
  1583. display is not known to the \*(xI, an error message is issued.
  1584.  
  1585. .NH 3
  1586. Registering a New Resource Converter
  1587. .XS
  1588. \fB\*(SN Registering a New Resource Converter\fP
  1589. .XE
  1590. .LP
  1591. When registering a resource converter, the client must specify the
  1592. manner in which the conversion cache is to be used when there are multiple
  1593. calls to the converter.  Conversion cache control is specified
  1594. via an
  1595. .PN XtCacheType
  1596. .IN "XtCacheType" "" "@DEF@"
  1597. argument.
  1598. .sp
  1599. .Ds 0
  1600. typedef int XtCacheType;
  1601. .De
  1602. .LP
  1603. An
  1604. .PN XtCacheType
  1605. field may contain one of the following values:
  1606. .br
  1607. .sp
  1608. .LP
  1609. .PN XtCacheNone
  1610. .IN "XtCacheNone" "" "@DEF@"
  1611. .IP
  1612. Specifies that the results of a previous conversion
  1613. may not be reused to satisfy any other resource
  1614. requests; the specified converter will be called
  1615. each time the converted value is required.
  1616. .br
  1617. .sp
  1618. .LP
  1619. .PN XtCacheAll
  1620. .IN "XtCacheAll" "" "@DEF@"
  1621. .IP
  1622. Specifies that the results of a previous conversion
  1623. should be reused for any resource request that depends
  1624. upon the same source value and conversion arguments.
  1625. .br
  1626. .sp
  1627. .LP
  1628. .PN XtCacheByDisplay
  1629. .IN "XtCacheByDisplay" "" "@DEF@"
  1630. .IP  
  1631. Specifies that the results of a previous conversion
  1632. should be used as for
  1633. .PN XtCacheAll
  1634. but the destructor will be called, if specified, if
  1635. .PN XtCloseDisplay
  1636. is called
  1637. for the display connection associated with the converted value, and
  1638. the value will be removed from the conversion cache.
  1639. .LP
  1640. The qualifier
  1641. .PN XtCacheRefCount
  1642. .IN "XtCacheRefCount" "" "@DEF@"
  1643. may be ORed with any of the above values.  If
  1644. .PN XtCacheRefCount
  1645. is specified, calls to
  1646. .PN XtCreateWidget ,
  1647. .PN XtCreateManagedWidget ,
  1648. .PN XtGetApplicationResources
  1649. and
  1650. .PN XtGetSubresources
  1651. that use the converted value will be counted.  When a widget using the
  1652. converted value is destroyed, the count is decremented, and if the
  1653. count reaches zero, the destructor procedure will be called and the
  1654. converted value will be removed from the conversion cache.
  1655.  
  1656. .LP
  1657. To register a type converter for all application contexts in a
  1658. process, use 
  1659. .PN XtSetTypeConverter
  1660. and to register a type converter in a single application context, use
  1661. .PN XtAppSetTypeConverter .
  1662. .IN "XtSetTypeConverter" "" "@DEF@"
  1663. .FD 0
  1664. void XtSetTypeConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
  1665. \fIconvert_args\fP, \fInum_args\fP,
  1666.                         \fIcache_type\fP, \fIdestructor\fP)
  1667. .br
  1668.       String \fIfrom_type\fP;
  1669. .br
  1670.       String \fIto_type\fP;
  1671. .br
  1672.       XtTypeConverter \fIconverter\fP;
  1673. .br
  1674.       XtConvertArgList \fIconvert_args\fP;
  1675. .br
  1676.       Cardinal \fInum_args\fP;
  1677. .br
  1678.       XtCacheType \fIcache_type\fP;
  1679. .br
  1680.       XtDestructor \fIdestructor\fP;
  1681. .FN
  1682. .IP \fIfrom_type\fP 1i
  1683. Specifies the source type.
  1684. .IP \fIto_type\fP 1i
  1685. Specifies the destination type.
  1686. .IP \fIconverter\fP 1i
  1687. Specifies the resource type converter procedure.
  1688. .IP \fIconvert_args\fP 1i
  1689. Specifies additional conversion arguments, or NULL.
  1690. .IP \fInum_args\fP 1i
  1691. Specifies the number of entries in \fIconvert_args\fP.
  1692. .IP \fIcache_type\fP 1i
  1693. Specifies whether or not resources produced by this
  1694. converter are sharable or display-specific and when
  1695. they should be freed.
  1696. .IP \fIdestructor\fP 1i
  1697. Specifies a destroy procedure for resources produced by
  1698. this conversion, or NULL if no additional action is
  1699. required to deallocate resources produced by the converter.
  1700.  
  1701. .sp
  1702. .LP
  1703. .IN "XtAppSetTypeConverter" "" "@DEF@"
  1704. .FD 0
  1705. void XtAppSetTypeConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
  1706. \fIconverter\fP, \fIconvert_args\fP,
  1707.                            \fInum_args\fP, \fIcache_type\fP, \fIdestructor\fP)
  1708. .br
  1709.       XtAppContext \fIapp_context\fP;
  1710. .br
  1711.       String \fIfrom_type\fP;
  1712. .br
  1713.       String \fIto_type\fP;
  1714. .br
  1715.       XtTypeConverter \fIconverter\fP;
  1716. .br
  1717.       XtConvertArgList \fIconvert_args\fP;
  1718. .br
  1719.       Cardinal \fInum_args\fP;
  1720. .br
  1721.       XtCacheType \fIcache_type\fP;
  1722. .br
  1723.       XtDestructor \fIdestructor\fP;
  1724. .FN
  1725. .IP \fIapp_context\fP 1i
  1726. Specifies the application context.
  1727. .IP \fIfrom_type\fP 1i
  1728. Specifies the source type.
  1729. .IP \fIto_type\fP 1i
  1730. Specifies the destination type.
  1731. .IP \fIconverter\fP 1i
  1732. Specifies the resource type converter procedure.
  1733. .IP \fIconvert_args\fP 1i
  1734. Specifies additional conversion arguments, or NULL.
  1735. .IP \fInum_args\fP 1i
  1736. Specifies the number of entries in \fIconvert_args\fP.
  1737. .IP \fIcache_type\fP 1i
  1738. Specifies whether or not resources produced by this
  1739. converter are sharable or display-specific and when
  1740. they should be freed.
  1741. .IP \fIdestructor\fP 1i
  1742. Specifies a destroy procedure for resources produced by
  1743. this conversion, or NULL if no additional action is
  1744. required to deallocate resources produced by the converter.
  1745. .LP
  1746. .PN XtSetTypeConverter
  1747. registers the specified type converter and
  1748. destructor in all application contexts created by the calling process,
  1749. including any future application contexts that may be created.
  1750. .PN XtAppSetTypeConverter
  1751. registers the specified type converter in the
  1752. single application context specified.  If the same \fIfrom_type\fP and
  1753. \fIto_type\fP are specified in multiple calls to either function, the most
  1754. recent overrides the previous ones.
  1755. .sp
  1756. .LP
  1757. For the few type converters that need additional arguments,
  1758. the \*(xI conversion mechanism provides a method of specifying
  1759. how these arguments should be computed.
  1760. The enumerated type
  1761. .PN XtAddressMode
  1762. and the structure
  1763. .PN XtConvertArgRec
  1764. specify how each argument is derived.
  1765. These are defined in
  1766. .Pn < X11/Intrinsic.h >.
  1767. .LP
  1768. .Ds 0
  1769. .TA .5i 2.5i
  1770. .ta .5i 2.5i
  1771. typedef enum {
  1772.     /* address mode    parameter representation */
  1773.        XtAddress,    /* address */
  1774.        XtBaseOffset,    /* offset */
  1775.        XtImmediate,    /* constant */
  1776.        XtResourceString,    /* resource name string */
  1777.        XtResourceQuark,    /* resource name quark */
  1778.        XtWidgetBaseOffset,    /* offset */
  1779.        XtProcedureArg    /* procedure to call */
  1780. } XtAddressMode;
  1781.  
  1782. typedef struct {
  1783.     XtAddressMode address_mode;
  1784.     XtPointer address_id;
  1785.     Cardinal size;
  1786. } XtConvertArgRec, *XtConvertArgList;
  1787. .De
  1788. .LP
  1789. The \fIsize\fP field specifies the length of the data in bytes.
  1790. The \fIaddress_mode\fP field specifies how the \fIaddress_id\fP field should be
  1791. interpreted.
  1792. .PN XtAddress
  1793. .IN "XtAddress" "" "@DEF@"
  1794. causes \fIaddress_id\fP to be interpreted as the address of the data.
  1795. .PN XtBaseOffset
  1796. .IN "XtBaseOffset" "" "@DEF@"
  1797. causes \fIaddress_id\fP to be interpreted as the offset from the widget base.
  1798. .PN XtImmediate
  1799. .IN "XtImmediate" "" "@DEF@"
  1800. causes \fIaddress_id\fP to be interpreted as a constant.
  1801. .PN XtResourceString
  1802. .IN "XtResourceString" "" "@DEF@"
  1803. causes \fIaddress_id\fP to be interpreted as the name of a resource
  1804. that is to be converted into an offset from the widget base.
  1805. .PN XtResourceQuark
  1806. .IN "XtResourceQuark" "" "@DEF@"
  1807. causes \fIaddress_id\fP to be interpreted as the result of an
  1808. .PN XrmStringToQuark
  1809. conversion on the name of a resource,
  1810. which is to be converted into an offset from the widget base.
  1811. .PN XtWidgetBaseOffset
  1812. .IN "XtWidgetBaseOffset" "" "@DEF@"
  1813. is similar to
  1814. .PN XtBaseOffset
  1815. except that it
  1816. searches for the closest windowed ancestor if the object is not
  1817. of a subclass of
  1818. Core
  1819. (See Chapter 12).
  1820. .PN XtProcedureArg
  1821. .IN "XtProcedureArg" "" "@DEF@"
  1822. specifies that \fIaddress_id\fP is a pointer to a procedure to
  1823. be invoked to return the conversion argument.  If
  1824. .PN XtProcedureArg
  1825. is specified, \fIaddress_id\fP must contain
  1826. the address of a function of type
  1827. .PN XtConvertArgProc .
  1828. .IN "XtConvertArgProc" "" "@DEF@"
  1829. .FD 0
  1830. typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*);
  1831. .br
  1832.       Widget \fIobject\fP;
  1833. .br
  1834.       Cardinal *\fIsize\fP;
  1835. .br
  1836.       XrmValue *\fIvalue\fP;
  1837. .FN
  1838. .IP \fIobject\fP 1i
  1839. Passes the object for which the resource is being
  1840. converted, or NULL if the converter was invoked by
  1841. .PN XtCallConverter
  1842. or
  1843. .PN XtDirectConvert .
  1844. .IP \fIsize\fP 1i
  1845. Passes a pointer to the \fIsize\fP field from the
  1846. .PN XtConvertArgRec .
  1847. .IP \fIvalue\fP 1i
  1848. Passes a pointer to a descriptor into which the procedure
  1849. must store the conversion argument.
  1850. .LP
  1851. When invoked, the
  1852. .PN XtConvertArgProc
  1853. procedure must derive a conversion
  1854. argument and store the address and size of the argument in the location
  1855. pointed to by \fIvalue\fP.
  1856. .LP
  1857. In order to permit reentrancy, the
  1858. .PN XtConvertArgProc
  1859. should return the address of storage whose lifetime is no shorter than the
  1860. lifetime of \fIobject\fP.  If \fIobject\fP is NULL, the lifetime of the conversion
  1861. argument must be no shorter than the lifetime of the resource with
  1862. which the conversion argument is associated.  The \*(xI do not
  1863. guarantee to copy this storage but do guarantee not to reference it if
  1864. the resource is removed from the conversion cache.
  1865. .LP
  1866. The following example illustrates how to register the CvtStringToPixel 
  1867. routine given earlier:
  1868. .LP
  1869. .Ds
  1870. .TA .2i 3i
  1871. .ta .2i 3i
  1872. static XtConvertArgRec colorConvertArgs[] = {
  1873.     {XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.screen),  sizeof(Screen*)},
  1874.     {XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.colormap),sizeof(Colormap)}
  1875. };
  1876.  
  1877. XtSetTypeConverter(XtRString, XtRPixel, CvtStringToPixel,
  1878.     colorConvertArgs, XtNumber(colorConvertArgs), XtCacheByDisplay, NULL);
  1879. .De
  1880. .LP
  1881. The conversion argument descriptors
  1882. .PN colorConvertArgs
  1883. and
  1884. .PN screenConvertArg
  1885. are predefined by the \*(xI.  Both take the
  1886. values from the closest windowed ancestor if the object is not of a
  1887. subclass of
  1888. Core.
  1889. The
  1890. .PN screenConvertArg
  1891. descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0].  The
  1892. .PN colorConvertArgs
  1893. descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0],
  1894. and the widget's \fIcolormap\fP field into \fIargs\fP[1].
  1895. .LP
  1896. Conversion routines should not just put a descriptor for the address of the
  1897. base of the widget into \fIargs\fP[0] and use that in the routine.
  1898. They should pass in the actual values on which the conversion depends on.
  1899. By keeping the dependencies of the conversion procedure specific,
  1900. it is more likely that subsequent conversions will find what they need
  1901. in the conversion cache.
  1902. This way the cache is smaller and has fewer and more widely applicable entries.
  1903. .LP
  1904. If any conversion arguments of type
  1905. .PN XtBaseOffset ,
  1906. .PN XtResourceString ,
  1907. .PN XtResourceQuark ,
  1908. and
  1909. .PN XtWidgetBaseOffset
  1910. are specified for conversions performed by
  1911. .PN XtGetApplicationResources ,
  1912. .PN XtGetSubresources ,
  1913. .PN XtVaGetApplicationResources
  1914. or
  1915. .PN XtVaGetSubresources ,
  1916. the arguments are
  1917. computed with respect to the specified widget, not the base address or
  1918. resource list specified in the call.
  1919. .LP
  1920. If the
  1921. .PN XtConvertArgProc
  1922. modifies the resource database,
  1923. the changes affect any in-progress widget creation,
  1924. .PN XtGetApplicationResources ,
  1925. or
  1926. .PN XtGetSubresources
  1927. in an implementation-defined manner; however, insertion of new entries
  1928. or changes to existing entries is allowed and will not directly cause
  1929. an error.
  1930.  
  1931. .NH 3
  1932. Resource Converter Invocation
  1933. .XS
  1934. \fB\*(SN Resource Converter Invocation\fP
  1935. .XE
  1936. .LP
  1937. All resource-fetching routines (for example,
  1938. .PN XtGetSubresources ,
  1939. .PN XtGetApplicationResources ,
  1940. and so on) call resource converters if the resource database or
  1941. varargs list specifies a value
  1942. that has a different representation from the desired representation or if the
  1943. widget's default resource value representation is different from the desired
  1944. representation.
  1945. .sp
  1946. .LP
  1947. To invoke explicit resource conversions, use
  1948. .PN XtConvertAndStore
  1949. or
  1950. .PN XtCallConverter .
  1951. .sp
  1952. .Ds 0
  1953. typedef XtPointer XtCacheRef;
  1954. .De
  1955. .IN "XtCallConverter" "" "@DEF@"
  1956. .FD 0
  1957. Boolean XtCallConverter( \fIdisplay\fP, \fIconverter\fP, \fIconversion_args\fP, \
  1958. \fInum_args\fP, \fIfrom\fP, \fIto_in_out\fP, \fIcache_ref_return\fP )
  1959. .br
  1960.       Display* \fIdisplay\fP;
  1961. .br
  1962.       XtTypeConverter \fIconverter\fP;
  1963. .br
  1964.       XrmValuePtr \fIconversion_args\fP;
  1965. .br
  1966.       Cardinal \fInum_args\fP;
  1967. .br
  1968.       XrmValuePtr \fIfrom\fP;
  1969. .br
  1970.       XrmValuePtr \fIto_in_out\fP;
  1971. .br
  1972.       XtCacheRef *\fIcache_ref_return\fP;
  1973. .FN
  1974. .IP \fIdisplay\fP 1i
  1975. Specifies the display with which the conversion is to be associated.
  1976. .IP \fIconverter\fP 1i
  1977. Specifies the conversion procedure to be called.
  1978. .IP \fIconversion_args\fP 1i
  1979. Specifies the additional conversion arguments needed
  1980. to perform the conversion, or NULL.
  1981. .IP \fInum_args\fP 1i
  1982. Specifies the number of entries in \fIconversion_args\fP.
  1983. .IP \fIfrom\fP 1i
  1984. Specifies a descriptor for the source value.
  1985. .IP \fIto_in_out\fP 1i
  1986. Returns the converted value.
  1987. .IP \fIcache_ref_return\fP 1i
  1988. Returns a conversion cache id.
  1989. .LP
  1990. The
  1991. .PN XtCallConverter
  1992. function looks up the
  1993. specified type converter in the application context associated with
  1994. the display and, if the converter was not registered or was registered
  1995. with cache type
  1996. .PN XtCacheAll
  1997. or
  1998. .PN XtCacheByDisplay
  1999. looks in the conversion cache to see if this conversion procedure
  2000. has been called with the specified conversion arguments.  If so, it
  2001. checks the success status of the prior call, and if
  2002. the conversion failed,
  2003. .PN XtCallConverter
  2004. returns
  2005. .PN False
  2006. immediately;
  2007. otherwise it checks the size specified in the \fIto\fP argument and, if it is
  2008. greater than or equal to the size stored in the cache, copies the
  2009. information stored in the cache into the location specified by
  2010. \fIto->addr\fP, stores the cache size into \fIto->size\fP, and returns
  2011. .PN True .
  2012. If the size specified in the \fIto\fP argument is smaller than the size stored
  2013. in the cache,
  2014. .PN XtCallConverter
  2015. copies the cache size into \fIto->size\fP and returns
  2016. .PN False .
  2017. If the converter was registered with cache type
  2018. .PN XtCacheNone
  2019. or no value was found in the conversion cache,
  2020. .PN XtCallConverter
  2021. calls the converter and, if it was not registered with cache type
  2022. .PN XtCacheNone ,
  2023. enters the result in the cache.  
  2024. .PN XtCallConverter
  2025. then returns what the converter returned.
  2026. .LP
  2027. The \fIcache_ref_return\fP field specifies storage allocated by the caller in which
  2028. an opaque value will be stored.  If the type converter has been
  2029. registered with the
  2030. .PN XtCacheRefCount
  2031. modifier and if the value returned
  2032. in \fIcache_ref_return\fP is non-NULL, then the caller should store the
  2033. \fIcache_ref_return\fP value in order to decrement the reference count when
  2034. the converted value is no longer required.  The \fIcache_ref_return\fP
  2035. argument should be
  2036. NULL if the caller is unwilling or unable to store the
  2037. value.
  2038. .sp
  2039. .LP
  2040. To explicitly decrement the reference counts for resources obtained
  2041. from
  2042. .PN XtCallConverter ,
  2043. use
  2044. .PN XtAppReleaseCacheRefs .
  2045. .IN "XtAppReleaseCacheRefs" "" "@DEF@"
  2046. .FD 0
  2047. void XtAppReleaseCacheRefs(\fIapp_context\fP, \fIrefs\fP)
  2048. .br
  2049.       XtAppContext \fIapp_context\fP;
  2050. .br
  2051.       XtCacheRef *\fIrefs\fP;
  2052. .FN
  2053. .IP \fIapp_context\fP 1i
  2054. Specifies the application context.
  2055. .IP \fIrefs\fP 1i
  2056. Specifies the list of cache references to be released.
  2057. .LP
  2058. .PN XtAppReleaseCacheRefs
  2059. decrements the reference count for the
  2060. conversion entries identified by the \fIrefs\fP argument.
  2061. This argument is a
  2062. pointer to a NULL-terminated list of
  2063. .PN XtCacheRef
  2064. values.  If any reference
  2065. count reaches zero, the destructor, if any, will be called and
  2066. the resource removed from the conversion cache.
  2067. .sp
  2068. .LP
  2069. As a convenience to clients needing to explicitly decrement reference
  2070. counts via a callback function, the \*(xI define two callback
  2071. procedures,
  2072. .PN XtCallbackReleaseCacheRef
  2073. and
  2074. .PN XtCallbackReleaseCacheRefList .
  2075. .IN "XtCallbackReleaseCacheRef" "" "@DEF@"
  2076. .FD 0
  2077. void XtCallbackReleaseCacheRef(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP)
  2078. .br
  2079.       Widget \fIobject\fP;
  2080. .br
  2081.       XtPointer \fIclient_data\fP;
  2082. .br
  2083.       XtPointer \fIcall_data\fP;
  2084. .FN
  2085. .IP \fIobject\fP 1i
  2086. Specifies the object with which the resource is associated.
  2087. .IP \fIclient_data\fP 1i
  2088. Specifies the conversion cache entry to be released.
  2089. .IP \fIcall_data\fP 1i
  2090. Is ignored.
  2091. .LP
  2092. This callback procedure may be added to a callback list to release a
  2093. previously returned
  2094. .PN XtCacheRef
  2095. value.  When adding the callback, the
  2096. callback \fIclient_data\fP argument must be specified as the value of the
  2097. .PN XtCacheRef
  2098. data cast to type
  2099. .PN XtPointer .
  2100. .sp
  2101. .IN "XtCallbackReleaseCacheRefList" "" "@DEF@"
  2102. .FD 0
  2103. void XtCallbackReleaseCacheRefList(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP)
  2104. .br
  2105.       Widget \fIobject\fP;
  2106. .br
  2107.       XtPointer \fIclient_data\fP;
  2108. .br
  2109.       XtPointer \fIcall_data\fP;
  2110. .FN
  2111. .IP \fIobject\fP 1i
  2112. Specifies the object with which the resources are associated.
  2113. .IP \fIclient_data\fP 1i
  2114. Specifies the conversion cache entries to be released.
  2115. .IP \fIcall_data\fP 1i
  2116. Is ignored.
  2117. .LP
  2118. This callback procedure may be added to a callback list to release a
  2119. list of previously returned
  2120. .PN XtCacheRef
  2121. values.  When adding the
  2122. callback, the callback \fIclient_data\fP argument must be specified as a
  2123. pointer to a NULL-terminated list of
  2124. .PN XtCacheRef
  2125. values.
  2126. .sp
  2127. .LP
  2128. To lookup and call a resource converter, copy the resulting value,
  2129. and free a cached resource when a widget is destroyed, use
  2130. .PN XtConvertAndStore .
  2131. .IN "XtConvertAndStore" "" "@DEF@"
  2132. .FD 0
  2133. Boolean XtConvertAndStore(\fIobject\fP, \fIfrom_type\fP, \fIfrom\fP, \
  2134. \fIto_type\fP, \fIto_in_out\fP)
  2135. .br
  2136.       Widget \fIobject\fP;
  2137. .br
  2138.       String \fIfrom_type\fP;
  2139. .br
  2140.       XrmValuePtr \fIfrom\fP;
  2141. .br
  2142.       String \fIto_type\fP;
  2143. .br
  2144.       XrmValuePtr \fIto_in_out\fP;
  2145. .FN
  2146. .IP \fIobject\fP 1i
  2147. Specifies the object to use for additional arguments, if any are needed,
  2148. and the destroy callback list.  \*(oI
  2149. .IP \fIfrom_type\fP 1i
  2150. Specifies the source type.
  2151. .IP \fIfrom\fP 1i
  2152. Specifies the value to be converted.
  2153. .IP \fIto_type\fP 1i
  2154. Specifies the destination type.
  2155. .IP \fIto_in_out\fP 1i
  2156. Specifies a descriptor for storage into which the converted value
  2157. will be returned.
  2158. .LP
  2159. The
  2160. .PN XtConvertAndStore
  2161. function looks up the type converter registered
  2162. to convert \fIfrom_type\fP to \fIto_type\fP, computes any additional arguments
  2163. needed, and then calls
  2164. .PN XtCallConverter
  2165. (or
  2166. .PN XtDirectConvert
  2167. if an old-style converter was registered with
  2168. .PN XtAddConverter
  2169. or
  2170. .PN XtAppAddConverter ;
  2171. see Appendix C) with the \fIfrom\fP and \fIto_in_out\fP arguments.  The
  2172. \fIto_in_out\fP argument specifies the size and location into which the
  2173. converted value will be stored and is passed directly to the
  2174. converter.  If the location is specified as NULL, it will be replaced
  2175. with a pointer to private storage and the size will be returned in the
  2176. descriptor.  The caller is expected to copy this private storage
  2177. immediately and must not modify it in any way.  If a non-NULL location
  2178. is specified, the caller must allocate sufficient storage to hold the
  2179. converted value and must also specify the size of that storage in the
  2180. descriptor.
  2181. The \fIsize\fP field will be modified on return to indicate the actual
  2182. size of the converted data.
  2183. If the conversion succeeds,
  2184. .PN XtConvertAndStore
  2185. returns
  2186. .PN True ;
  2187. otherwise, it returns
  2188. .PN False .
  2189. .LP
  2190. .PN XtConvertAndStore
  2191. adds
  2192. .PN XtCallbackReleaseCacheRef
  2193. .IN "destroyCallback"
  2194. to the destroyCallback list of the specified object if the conversion
  2195. returns an
  2196. .PN XtCacheRef
  2197. value.  The resulting resource should not be referenced
  2198. after the object has been destroyed.
  2199. .LP
  2200. .PN XtCreateWidget
  2201. performs processing equivalent to
  2202. .PN XtConvertAndStore
  2203. when initializing the object instance.  Because there is extra memory
  2204. overhead required to implement reference counting, clients may
  2205. distinguish those objects that are never destroyed before the
  2206. application exits from those that may be destroyed and whose
  2207. resources should be deallocated.
  2208. .LP
  2209. To specify whether reference counting is to be enabled for the
  2210. resources of a particular object when the object is created, the
  2211. client can specify a value for the
  2212. .PN Boolean
  2213. resource
  2214. XtNinitialResourcesPersistent,
  2215. .IN "XtNinitialResourcesPersistent" "" "@DEF@"
  2216. class
  2217. XtCInitialResourcesPersistent.
  2218. .LP
  2219. When
  2220. .PN XtCreateWidget
  2221. is called, if this resource is not specified as
  2222. .PN False
  2223. in either the arglist or the resource database, then the
  2224. resources referenced by this object are not reference-counted, regardless of
  2225. how the type converter may have been registered.  The effective
  2226. default value is
  2227. .PN True ;
  2228. thus clients that expect to destroy one or
  2229. more objects and want resources deallocated must explicitly specify
  2230. .PN False
  2231. for
  2232. .IN XtNinitialResourcesPersistent
  2233. XtNinitialResourcesPersistent.
  2234. .LP
  2235. The resources are still freed and destructors called when
  2236. .PN XtCloseDisplay
  2237. is called if the conversion was registered as
  2238. .PN XtCacheByDisplay .
  2239.  
  2240. .NH 2
  2241. Reading and Writing Widget State
  2242. .XS
  2243. \fB\*(SN Reading and Writing Widget State\fP
  2244. .XE
  2245. .LP
  2246. Any resource field in a widget can be read or written by a client.
  2247. On a write operation,
  2248. the widget decides what changes it will actually allow and updates all
  2249. derived fields appropriately.
  2250.  
  2251. .NH 3
  2252. Obtaining Widget State
  2253. .XS
  2254. \fB\*(SN Obtaining Widget State\fP
  2255. .XE
  2256. .LP
  2257. To retrieve the current values of resources associated with a
  2258. widget instance, use
  2259. .PN XtGetValues .
  2260. .IN "XtGetValues" "" "@DEF@"
  2261. .FD 0
  2262. void XtGetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP)
  2263. .br
  2264.       Widget \fIobject\fP;
  2265. .br
  2266.       ArgList \fIargs\fP;
  2267. .br
  2268.       Cardinal \fInum_args\fP;
  2269. .FN
  2270. .IP \fIobject\fP 1i
  2271. Specifies the object whose resource values are to be returned.  \*(oI
  2272. .IP \fIargs\fP 1i
  2273. Specifies the argument list of name/address pairs that contain the
  2274. resource names and the addresses into which the resource values are to
  2275. be stored.
  2276. The resource names are widget-dependent.
  2277. .IP \fInum_args\fP 1i
  2278. Specifies the number of entries in the argument list.
  2279. .LP
  2280. The
  2281. .PN XtGetValues
  2282. function starts with the resources specified for the Object class
  2283. and proceeds down the subclass chain to the class of the object.
  2284. The \fIvalue\fP field of a passed argument list must contain the
  2285. address into which to copy the contents of the corresponding
  2286. object instance field.  If the field is a pointer type, the lifetime
  2287. of the pointed-to data is defined by the object class.  For the
  2288. \*(xI-defined resources, the following lifetimes apply
  2289. .IP \(bu 3
  2290. Not valid following any operation that modifies the resource:
  2291. .RS
  2292. .IP \- 3
  2293. XtNchildren resource of composite widgets.
  2294. .IP \- 3
  2295. All resources of representation type XtRCallback.
  2296. .RE
  2297. .IP \(bu 3
  2298. Remain valid at least until the widget is destroyed:
  2299. .RS
  2300. .IP \- 3
  2301. XtNaccelerators, XtNtranslations.
  2302. .RE
  2303. .IP \(bu 3
  2304. Remain valid until the Display is closed:
  2305. .RS
  2306. .IP \- 3
  2307. XtNscreen.
  2308. .RE
  2309. .LP
  2310. It is the caller's responsibility
  2311. to allocate and deallocate storage for the copied data
  2312. according to the size of the
  2313. resource representation type used within the object.
  2314. .LP
  2315. If the class of the object's parent is a subclass of
  2316. .PN constraintWidgetClass ,
  2317. .PN XtGetValues
  2318. then fetches the values for any constraint resources requested.
  2319. It starts with the constraint resources specified for
  2320. .PN constraintWidgetClass
  2321. and proceeds down the subclass chain to the parent's constraint resources.
  2322. If the argument list contains a resource name that is not found in any of the
  2323. resource lists searched, 
  2324. the value at the corresponding address is not modified.
  2325. .IN "get_values_hook procedure"
  2326. If any get_values_hook procedures in the
  2327. object's class or superclass records are non-NULL, 
  2328. they are called in superclass-to-subclass order after
  2329. all the resource values have been fetched by
  2330. .PN XtGetValues .
  2331. Finally, if the object's parent is a
  2332. subclass of
  2333. .PN constraintWidgetClass ,
  2334. and if any of the parent's class or
  2335. superclass records have declared
  2336. .PN ConstraintClassExtension
  2337. records in
  2338. the Constraint class part \fIextension\fP field with a record type of
  2339. .PN \s-1NULLQUARK\s+1
  2340. and if the \fIget_values_hook\fP field in the extension record is non-NULL,
  2341. .PN XtGetValues
  2342. calls the get_values_hook procedures in superclass-to-subclass order.
  2343. This permits a Constraint parent to provide
  2344. nonresource data via
  2345. .PN XtGetValues .
  2346. .LP
  2347. Get_values_hook procedures may modify the data stored at the
  2348. location addressed by the \fIvalue\fP field, including (but not
  2349. limited to) making a copy of data whose resource representation is a
  2350. pointer.  None of the \*(xI-defined object classes copy
  2351. data in this manner.  Any operation that modifies the queried
  2352. object resource may invalidate the pointed-to data.
  2353.  
  2354. .sp
  2355. .LP
  2356. To retrieve the current values of resources associated with a widget
  2357. instance using varargs lists, use
  2358. .PN XtVaGetValues .
  2359. .IN "XtVaGetValues" "" "@DEF@"
  2360. .FD 0
  2361. void XtVaGetValues(\fIobject\fP, ...)
  2362. .br
  2363.       Widget \fIobject\fP;
  2364. .FN
  2365. .IP \fIobject\fP 1i
  2366. Specifies the object whose resource values are to be returned.  \*(oI
  2367. .IP ... 1i
  2368. Specifies the variable argument list for the resources to
  2369. be returned.
  2370. .LP
  2371. .PN XtVaGetValues
  2372. is identical in function to
  2373. .PN XtGetValues
  2374. with the \fIargs\fP
  2375. and \fInum_args\fP parameters replaced by a varargs list, as described in
  2376. Section 2.5.1.  All value entries in the list must specify pointers to
  2377. storage allocated by the caller to which the resource value will be
  2378. copied.  It is the caller's responsibility to ensure that sufficient
  2379. storage is allocated.  If
  2380. .PN XtVaTypedArg
  2381. is specified, the \fItype\fP argument
  2382. specifies the representation desired by the caller and \fIthe\fP size argument
  2383. specifies the number of bytes allocated to store the result of the
  2384. conversion.  If the size is insufficient, a warning message is issued
  2385. and the list entry is skipped.
  2386.  
  2387. .NH 4
  2388. Widget Subpart Resource Data: the get_values_hook Procedure
  2389. .XS
  2390. \*(SN Widget Subpart Resource Data: the get_values_hook Procedure
  2391. .XE
  2392. .LP
  2393. Widgets that have subparts can return resource values from them through
  2394. .PN XtGetValues
  2395. by supplying a get_values_hook procedure.
  2396. The get_values_hook procedure pointer is of type
  2397. .PN XtArgsProc .
  2398. .IN "get_values_hook procedure" "" "@DEF@"
  2399. .FD 0
  2400. typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*);
  2401. .br
  2402.       Widget \fIw\fP;
  2403. .br
  2404.       ArgList \fIargs\fP;
  2405. .br
  2406.       Cardinal *\fInum_args\fP;
  2407. .FN
  2408. .IP \fIw\fP 1i
  2409. Specifies the widget whose subpart resource values are to be retrieved.
  2410. .IP \fIargs\fP 1i
  2411. Specifies the argument list that was passed to
  2412. .PN XtGetValues
  2413. or the transformed varargs list passed to
  2414. .PN XtVaGetValues .
  2415. .IP \fInum_args\fP 1i
  2416. Specifies the number of entries in the argument list.
  2417. .LP
  2418. The widget with subpart resources should call
  2419. .PN XtGetSubvalues
  2420. in the get_values_hook procedure
  2421. and pass in its subresource list and the \fIargs\fP and \fInum_args\fP parameters.
  2422.  
  2423. .NH 4
  2424. Widget Subpart State
  2425. .XS
  2426. \*(SN Widget Subpart State
  2427. .XE
  2428. .LP
  2429. To retrieve the current values of subpart resource data associated with a
  2430. widget instance, use
  2431. .PN XtGetSubvalues .
  2432. For a discussion of subpart resources,
  2433. see Section 9.4.
  2434. .IN "XtGetSubvalues" "" "@DEF@"
  2435. .FD 0
  2436. void XtGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \
  2437. \fIargs\fP, \fInum_args\fP)
  2438. .br
  2439.       XtPointer \fIbase\fP;
  2440. .br
  2441.       XtResourceList \fIresources\fP;
  2442. .br
  2443.       Cardinal \fInum_resources\fP;
  2444. .br
  2445.       ArgList \fIargs\fP;
  2446. .br
  2447.       Cardinal \fInum_args\fP;
  2448. .FN
  2449. .IP \fIbase\fP 1i
  2450. Specifies the base address of the subpart data structure for which the
  2451. resources should be retrieved.
  2452. .IP \fIresources\fP 1i
  2453. Specifies the subpart resource list.
  2454. .IP \fInum_resources\fP 1i
  2455. Specifies the number of entries in the resource list.
  2456. .IP \fIargs\fP 1i
  2457. Specifies the argument list of name/address pairs that contain the
  2458. resource names and the addresses into which the resource values are to
  2459. be stored.
  2460. .IP \fInum_args\fP 1i
  2461. Specifies the number of entries in the argument list.
  2462. .LP
  2463. The
  2464. .PN XtGetSubvalues
  2465. function obtains resource values from the structure identified by \fIbase\fP.
  2466. The \fIvalue\fP field in each argument entry must contain the address into
  2467. which to store the corresponding resource value.  It is the caller's
  2468. responsibility to allocate and deallocate this storage according to
  2469. the size of the resource representation type used within the subpart.
  2470. If the argument list contains a resource name that is not found in the
  2471. resource list, the value at the corresponding address is not modified.
  2472.  
  2473. .sp
  2474. .LP
  2475. To retrieve the current values of subpart resources associated with
  2476. a widget instance using varargs lists, use
  2477. .PN XtVaGetSubvalues .
  2478. .IN "XtVaGetSubvalues" "" "@DEF@"
  2479. .FD 0
  2480. void XtVaGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...)
  2481. .br
  2482.       XtPointer \fIbase\fP;
  2483. .br
  2484.       XtResourceList \fIresources\fP;
  2485. .br
  2486.       Cardinal \fInum_resources\fP;
  2487. .FN
  2488. .IP \fIbase\fP 1i
  2489. Specifies the base address of the subpart data structure for which the
  2490. resources should be retrieved.
  2491. .IP \fIresources\fP 1i
  2492. Specifies the subpart resource list.
  2493. .IP \fInum_resources\fP 1i
  2494. Specifies the number of entries in the resource list.
  2495. .IP ... 1i
  2496. Specifies a variable argument list of name/address pairs that
  2497. contain the resource names and the addresses into which the resource
  2498. values are to be stored.
  2499. .LP
  2500. .PN XtVaGetSubvalues
  2501. is identical in function to
  2502. .PN XtGetSubvalues
  2503. with the
  2504. \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as described
  2505. in Section 2.5.1.
  2506. .PN XtVaTypedArg
  2507. is not supported for
  2508. .PN XtVaGetSubvalues .
  2509. If
  2510. .PN XtVaTypedArg
  2511. is specified in the list, a warning message is issued
  2512. and the entry is then ignored.
  2513.  
  2514. .NH 3
  2515. Setting Widget State
  2516. .XS
  2517. \fB\*(SN Setting Widget State\fP
  2518. .XE
  2519. .LP
  2520. To modify the current values of resources associated with a widget
  2521. instance, use
  2522. .PN XtSetValues .
  2523. .IN "XtSetValues" "" "@DEF@"
  2524. .FD 0
  2525. void XtSetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP)
  2526. .br
  2527.       Widget \fIobject\fP;
  2528. .br
  2529.       ArgList \fIargs\fP;
  2530. .br
  2531.       Cardinal \fInum_args\fP;
  2532. .FN
  2533. .IP \fIobject\fP 1i
  2534. Specifies the object whose resources are to be modified.  \*(oI
  2535. .IP \fIargs\fP 1i
  2536. Specifies the argument list of name/value pairs that contain the
  2537. resources to be modified and their new values.
  2538. .IP \fInum_args\fP 1i
  2539. Specifies the number of entries in the argument list.
  2540. .LP
  2541. The
  2542. .PN XtSetValues
  2543. function starts with the resources specified for the 
  2544. Object
  2545. class fields and proceeds down the subclass chain to the object.
  2546. At each stage, it replaces the \fIobject\fP resource fields with any values
  2547. specified in the argument list.
  2548. .PN XtSetValues
  2549. then calls the set_values procedures for the object in superclass-to-subclass 
  2550. order.
  2551. .IN "set_values_hook procedure"
  2552. If the object has any non-NULL \fIset_values_hook\fP fields,
  2553. these are called immediately after the
  2554. corresponding set_values procedure.
  2555. This procedure permits subclasses to set subpart data via
  2556. .PN XtSetValues .
  2557. .LP
  2558. If the class of the object's parent is a subclass of
  2559. .PN constraintWidgetClass ,
  2560. .PN XtSetValues
  2561. also updates the object's constraints.
  2562. It starts with the constraint resources specified for
  2563. .PN constraintWidgetClass
  2564. and proceeds down the subclass chain to the parent's class.
  2565. At each stage, it replaces the constraint resource fields with any
  2566. values specified in the argument list.
  2567. It then calls the constraint set_values procedures from
  2568. .PN constraintWidgetClass
  2569. down to the parent's class.
  2570. The constraint set_values procedures are called with widget arguments,
  2571. as for all set_values procedures, not just the constraint records,
  2572. so that they can make adjustments to the desired values based
  2573. on full information about the widget.  Any arguments specified that
  2574. do not match a resource list entry are silently ignored.
  2575. .LP
  2576. If the object is of a subclass of
  2577. RectObj,
  2578. .PN XtSetValues
  2579. determines if a geometry request is needed by comparing the old object to
  2580. the new object.
  2581. If any geometry changes are required,
  2582. .PN XtSetValues
  2583. restores the original geometry and makes the request on behalf of the widget.a
  2584. If the geometry manager returns
  2585. .PN XtGeometryYes ,
  2586. .PN XtSetValues
  2587. calls the object's resize procedure.
  2588. If the geometry manager returns
  2589. .PN XtGeometryDone ,
  2590. .PN XtSetValues
  2591. continues, as the object's resize procedure should have been called
  2592. by the geometry manager.
  2593. If the geometry manager returns
  2594. .PN XtGeometryNo ,
  2595. .PN XtSetValues
  2596. ignores the geometry request and continues.
  2597. If the geometry manager returns
  2598. .PN XtGeometryAlmost ,
  2599. .PN XtSetValues
  2600. calls the set_values_almost procedure,
  2601. which determines what should be done.
  2602. .PN XtSetValues
  2603. then repeats this process,
  2604. deciding once more whether the geometry manager should be called.
  2605. .LP
  2606. Finally, if any of the set_values procedures returned 
  2607. .PN True ,
  2608. and the widget is realized,
  2609. .PN XtSetValues
  2610. causes the widget's expose procedure to be invoked by calling
  2611. .PN XClearArea
  2612. on the widget's window.
  2613. .sp
  2614. .LP
  2615. To modify the current values of resources associated with a widget
  2616. instance using varargs lists, use
  2617. .PN XtVaSetValues .
  2618. .IN "XtVaSetValues" "" "@DEF@"
  2619. .FD 0
  2620. void XtVaSetValues(\fIobject\fP, ...)
  2621. .br
  2622.       Widget \fIobject\fP;
  2623. .FN
  2624. .IP \fIobject\fP 1i
  2625. Specifies the object whose resources are to be modified.  \*(oI
  2626. .IP ... 1i
  2627. Specifies the variable argument list of name/value pairs that
  2628. contain the resources to be modified and their new values.
  2629. .LP
  2630. .PN XtVaSetValues
  2631. is identical in function to
  2632. .PN XtSetValues
  2633. with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
  2634. described in Section 2.5.1.
  2635.  
  2636. .NH 4
  2637. Widget State: the set_values Procedure
  2638. .XS
  2639. \*(SN Widget State: the set_values Procedure
  2640. .XE
  2641. .LP
  2642. The set_values procedure pointer in a widget class is of type
  2643. .PN XtSetValuesFunc .
  2644. .IN "XtSetValuesFunc" "" "@DEF@"
  2645. .IN "set_values procedure" "" "@DEF@"
  2646. .FD 0
  2647. typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*);
  2648. .br
  2649.       Widget \fIcurrent\fP;
  2650. .br
  2651.       Widget \fIrequest\fP;
  2652. .br
  2653.       Widget \fInew\fP;
  2654. .br
  2655.       ArgList \fIargs\fP;
  2656. .br
  2657.       Cardinal *\fInum_args\fP;
  2658. .FN
  2659. .IP \fIcurrent\fP 1i
  2660. Specifies a copy of the widget as it was before the
  2661. .PN XtSetValues
  2662. call.
  2663. .IP \fIrequest\fP 1i
  2664. Specifies a copy of the widget with all values changed as asked for by the
  2665. .PN XtSetValues
  2666. call before any class set_values procedures have been called.
  2667. .IP \fInew\fP 1i
  2668. Specifies the widget with the new values that are actually allowed.
  2669. .IP \fIargs\fP 1i
  2670. Specifies the argument list passed to
  2671. .PN XtSetValues
  2672. or the transformed argument list passed to
  2673. .PN XtVaSetValues .
  2674. .IP \fInum_args\fP 1i
  2675. Specifies the number of entries in the argument list.
  2676. .LP
  2677. The set_values procedure should recompute any field
  2678. derived from resources that are changed
  2679. (for example, many GCs depend on foreground and background pixels).
  2680. If no recomputation is necessary and if none of the resources specific to a
  2681. subclass require the window to be redisplayed when their values are changed,
  2682. you can specify NULL for the \fIset_values\fP field in the class record.
  2683. .LP
  2684. Like the initialize procedure,
  2685. set_values mostly deals only with the fields defined in the subclass,
  2686. but it has to resolve conflicts with its superclass,
  2687. especially conflicts over width and height.
  2688. .LP
  2689. Sometimes a subclass may want to overwrite values filled in by its
  2690. superclass.
  2691. In particular, size calculations of a superclass are often
  2692. incorrect for a subclass and, in this case,
  2693. the subclass must modify or recalculate fields declared
  2694. and computed by its superclass.
  2695. .LP
  2696. As an example,
  2697. a subclass can visually surround its superclass display.
  2698. In this case, the width and height calculated by the superclass set_values
  2699. procedure are too small and need to be incremented by the size of the surround.
  2700. The subclass needs to know if its superclass's size was calculated by the
  2701. superclass or was specified explicitly.
  2702. All widgets must place themselves into whatever size is explicitly given,
  2703. but they should compute a reasonable size if no size is requested.
  2704. How does a subclass know the difference between a specified size
  2705. and a size computed by a superclass?
  2706. .LP
  2707. The \fIrequest\fP and \fInew\fP parameters provide the necessary information.
  2708. The \fIrequest\fP widget is a copy of the widget, updated as originally requested.
  2709. The \fInew\fP widget starts with the values in the request,
  2710. but it has additionally been updated by all superclass set_values
  2711. procedures called so far.
  2712. A subclass set_values procedure can compare these two to resolve
  2713. any potential conflicts.
  2714. The set_values procedure need not refer to the \fIrequest\fP widget
  2715. unless it must resolve conflicts between the \fIcurrent\fP and \fInew\fP widgets.
  2716. Any changes the widget needs to make, including geometry changes,
  2717. should be made in the \fInew\fP widget.
  2718. .LP
  2719. In the above example,
  2720. the subclass with the visual surround can see
  2721. if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero.
  2722. If so,
  2723. it adds its surround size to the \fIwidth\fP and
  2724. \fIheight\fP fields in the \fInew\fP widget.
  2725. If not, it must make do with the size originally specified.
  2726. In this case, zero is a special value defined by the class to permit
  2727. the application to invoke this behavior.
  2728. .LP
  2729. The \fInew\fP widget is the actual widget instance record.
  2730. Therefore,
  2731. the set_values procedure should do all its work on the \fInew\fP widget;
  2732. the \fIrequest\fP widget should never be modified.
  2733. If the set_values procedure needs to call any routines that operate on
  2734. a widget, it should specify \fInew\fP as the widget instance.
  2735. .LP
  2736. Before calling the set_values procedures, the \*(xI modify the
  2737. resources of the \fIrequest\fP widget according to the contents of the arglist;
  2738. if the widget names all its resources in the class resource list, it is
  2739. never necessary to examine the contents of \fIargs\fP.
  2740. .LP
  2741. Finally, the set_values procedure must return a Boolean that indicates whether
  2742. the widget needs to be redisplayed.
  2743. Note that a change in the geometry fields alone does not require
  2744. the set_values procedure to return 
  2745. .PN True ;
  2746. the X server will eventually generate an
  2747. .PN Expose
  2748. event, if necessary.
  2749. After calling all the set_values procedures,
  2750. .PN XtSetValues
  2751. forces a redisplay by calling
  2752. .PN XClearArea
  2753. if any of the set_values procedures returned 
  2754. .PN True .
  2755. Therefore, a set_values procedure should not try to do its own redisplaying.
  2756. .LP
  2757. Set_values procedures should not do any work in response to changes in
  2758. geometry because
  2759. .PN XtSetValues
  2760. eventually will perform a geometry request, and that request might be denied.
  2761. If the widget actually changes size in response to a
  2762. call to
  2763. .PN XtSetValues ,
  2764. its resize procedure is called.
  2765. Widgets should do any geometry-related work in their resize procedure.
  2766. .LP
  2767. Note that it is permissible to call
  2768. .PN XtSetValues
  2769. before a widget is realized.
  2770. Therefore, the set_values procedure must not assume that the widget is realized.
  2771.  
  2772. .NH 4
  2773. Widget State: the set_values_almost Procedure
  2774. .XS
  2775. \*(SN Widget State: the set_values_almost Procedure
  2776. .XE
  2777. .LP
  2778. The set_values_almost procedure pointer in the widget class record is of type
  2779. .PN XtAlmostProc .
  2780. .IN "set_values_almost procedure" "" "@DEF@"
  2781. .IN "XtAlmostProc" "" "@DEF@"
  2782. .FD 0
  2783. typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, \
  2784. XtWidgetGeometry*);
  2785. .br
  2786.       Widget \fIold\fP;
  2787. .br
  2788.       Widget \fInew\fP;
  2789. .br
  2790.       XtWidgetGeometry *\fIrequest\fP;
  2791. .br
  2792.       XtWidgetGeometry *\fIreply\fP;
  2793. .FN
  2794. .IP \fIold\fP 1i
  2795. Specifies a copy of the object as it was before the
  2796. .PN XtSetValues
  2797. call.
  2798. .IP \fInew\fP 1i
  2799. Specifies the object instance record.
  2800. .IP \fIrequest\fP 1i
  2801. Specifies the original geometry request that was sent to the geometry
  2802. manager that caused
  2803. .PN XtGeometryAlmost
  2804. to be returned.
  2805. .IP \fIreply\fP 1i
  2806. Specifies the compromise geometry that was returned by the geometry
  2807. manager with
  2808. .PN XtGeometryAlmost .
  2809. .LP
  2810. Most classes inherit the set_values_almost procedure from their superclass by
  2811. specifying 
  2812. .PN XtInheritSetValuesAlmost 
  2813. in the class initialization.
  2814. The
  2815. set_values_almost procedure in
  2816. .PN rectObjClass
  2817. accepts the compromise suggested.
  2818. .LP
  2819. The set_values_almost procedure is called when a client tries to set a widget's
  2820. geometry by means of a call to
  2821. .PN XtSetValues ,
  2822. and the geometry manager cannot
  2823. satisfy the request but instead returns
  2824. .PN XtGeometryNo
  2825. or
  2826. .PN XtGeometryAlmost
  2827. and a compromise geometry.
  2828. The \fInew\fP object is the actual instance record.  The \fIx\fP, \fIy\fP,
  2829. \fIwidth\fP, \fIheight\fP,
  2830. and \fIborder_width\fP fields contain the original values as they were
  2831. before the
  2832. .PN XtSetValues
  2833. call and all other fields contain the new
  2834. values.  The \fIrequest\fP parameter contains the new geometry request that
  2835. was made to the parent.  The \fIreply\fP parameter contains
  2836. \fIreply->request_mode\fP equal to zero if the parent returned
  2837. .PN XtGeometryNo
  2838. and contains the parent's compromise geometry otherwise.  The
  2839. set_values_almost procedure takes the original geometry and the 
  2840. compromise geometry and determines if the compromise is
  2841. acceptable or whether
  2842. to try a different compromise.
  2843. It returns its results in the \fIrequest\fP parameter,
  2844. which is then sent back to the geometry manager for another try.
  2845. To accept the compromise, the procedure must copy the contents
  2846. of the \fIreply\fP geometry into the \fIrequest\fP geometry; to attempt an
  2847. alternative geometry, the procedure may modify any part of the \fIrequest\fP
  2848. argument; to terminate the geometry negotiation and retain the
  2849. original geometry, the procedure must set \fIrequest->request_mode\fP to
  2850. zero.  The geometry fields of the \fIold\fP and \fInew\fP instances must not be modified
  2851. directly.
  2852.  
  2853. .NH 4
  2854. Widget State: the ConstraintClassPart set_values Procedure
  2855. .XS
  2856. \*(SN Widget State: the ConstraintClassPart set_values Procedure
  2857. .XE
  2858. .IN "set_values procedure"
  2859. .LP
  2860. The constraint set_values procedure pointer is of type
  2861. .PN XtSetValuesFunc .
  2862. The values passed to the parent's constraint set_values procedure
  2863. are the same as those passed to the child's class
  2864. set_values procedure.
  2865. A class can specify NULL for the \fIset_values\fP field of the
  2866. .PN ConstraintPart
  2867. if it need not compute anything.
  2868. .LP
  2869. The constraint set_values procedure should recompute any constraint fields
  2870. derived from constraint resources that are changed.
  2871. Further, it may modify other widget fields as appropriate.
  2872. For example, if a constraint for the maximum height of a widget is changed
  2873. to a value smaller than the widget's current height,
  2874. the constraint set_values procedure may reset the \fIheight\fP field in the
  2875. widget.
  2876.  
  2877. .NH 4
  2878. Widget Subpart State
  2879. .XS
  2880. \*(SN Widget Subpart State
  2881. .XE
  2882. .LP
  2883. To set the current values of subpart resources associated with a
  2884. widget instance, use
  2885. .PN XtSetSubvalues .
  2886. For a discussion of subpart resources,
  2887. see Section 9.4.
  2888. .IN "XtSetSubvalues" "" "@DEF@"
  2889. .FD 0
  2890. void XtSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \
  2891. \fIargs\fP, \fInum_args\fP)
  2892. .br
  2893.       XtPointer \fIbase\fP;
  2894. .br
  2895.       XtResourceList \fIresources\fP;
  2896. .br
  2897.       Cardinal \fInum_resources\fP;
  2898. .br
  2899.       ArgList \fIargs\fP;
  2900. .br
  2901.       Cardinal \fInum_args\fP;
  2902. .FN
  2903. .IP \fIbase\fP 1i
  2904. Specifies the base address of the subpart data structure into which the
  2905. resources should be written.
  2906. .IP \fIresources\fP 1i
  2907. Specifies the subpart resource list.
  2908. .IP \fInum_resources\fP 1i
  2909. Specifies the number of entries in the resource list.
  2910. .IP \fIargs\fP 1i
  2911. Specifies the argument list of name/value pairs that contain the
  2912. resources to be modified and their new values.
  2913. .IP \fInum_args\fP 1i
  2914. Specifies the number of entries in the argument list.
  2915. .LP
  2916. The
  2917. .PN XtSetSubvalues
  2918. function updates the resource fields of the structure identified by
  2919. \fIbase\fP.  Any specified arguments that do not match an entry in the
  2920. resource list are silently ignored.
  2921. .sp
  2922. .LP
  2923. To set the current values of subpart resources associated with
  2924. a widget instance using varargs lists, use
  2925. .PN XtVaSetSubvalues .
  2926. .IN "XtVaSetSubvalues" "" "@DEF@"
  2927. .FD 0 
  2928. void XtVaSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...)
  2929. .br
  2930.       XtPointer \fIbase\fP;
  2931. .br
  2932.       XtResourceList \fIresources\fP;
  2933. .br
  2934.       Cardinal \fInum_resources\fP;
  2935. .FN
  2936. .IP \fIbase\fP 1i
  2937. Specifies the base address of the subpart data structure into which the
  2938. resources should be written.
  2939. .IP \fIresources\fP 1i
  2940. Specifies the subpart resource list.
  2941. .IP \fInum_resources\fP 1i
  2942. Specifies the number of entries in the resource list.
  2943. .IP ... 1i
  2944. Specifies the variable argument list of name/value pairs that
  2945. contain the resources to be modified and their new values.
  2946. .LP
  2947. .PN XtVaSetSubvalues
  2948. is identical in function to
  2949. .PN XtSetSubvalues
  2950. with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
  2951. described in Section 2.5.1.
  2952. .PN XtVaTypedArg
  2953. is not supported for
  2954. .PN XtVaSetSubvalues .
  2955. If an entry containing
  2956. .PN XtVaTypedArg
  2957. is specified in the list, a warning message is issued
  2958. and the entry is ignored.
  2959.  
  2960. .NH 4
  2961. Widget Subpart Resource Data: the set_values_hook Procedure
  2962. .XS
  2963. \*(SN Widget Subpart Resource Data: the set_values_hook Procedure
  2964. .XE
  2965. .IN "set_values_hook procedure"
  2966. .NT
  2967. The set_values_hook procedure is obsolete, as the same information
  2968. is now available to the set_values procedure.  The procedure has been
  2969. retained for those widgets that used it in versions prior to Release 4.
  2970. .NE
  2971. .LP
  2972. Widgets that have a subpart can set the subpart resource values through
  2973. .PN XtSetValues
  2974. by supplying a set_values_hook procedure.
  2975. The set_values_hook procedure pointer in a widget class is of type
  2976. .PN XtArgsFunc .
  2977. .IN "set_values_hook procedure" "" "@DEF@"
  2978. .IN "XtArgsFunc" "" "@DEF@"
  2979. .FD 0
  2980. typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal*);
  2981. .br
  2982.       Widget \fIw\fP;
  2983. .br
  2984.       Arglist \fIargs\fP;
  2985. .br
  2986.       Cardinal *\fInum_args\fP;
  2987. .FN
  2988. .IP \fIw\fP 1i
  2989. Specifies the widget whose subpart resource values are to be changed.
  2990. .IP \fIargs\fP 1i
  2991. Specifies the argument list that was passed to
  2992. .PN XtSetValues
  2993. or the transformed varargs list passed to
  2994. .PN XtVaSetValues .
  2995. .IP \fInum_args\fP 1i
  2996. Specifies the number of entries in the argument list.
  2997. .LP
  2998. The widget with subpart resources may call
  2999. .PN XtSetValues
  3000. from the set_values_hook procedure
  3001. and pass in its subresource list and the
  3002. \fIargs\fP and \fInum_args\fP parameters.
  3003. .bp
  3004.