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

  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 15\fP\s-1
  5.  
  6. \s+1\fBResource Manager Functions\fP\s-1
  7. .sp 2
  8. .nr H1 15
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 15: Resource Manager Functions
  17. .XE
  18. A program often needs a variety of options in the X environment
  19. (for example, fonts, colors, icons, and cursors).
  20. Specifying all of these options on the command line is awkward
  21. because users may want to customize many aspects of the program
  22. and need a convenient way to establish these customizations as
  23. the default setting.
  24. The resource manager is provided for this purpose.
  25. Resource specifications are usually stored in human-readable files
  26. and in server properties.
  27. .LP
  28. The resource manager is a database manager with a twist.
  29. In most database systems, 
  30. you perform a query using an imprecise specification,
  31. and you get back a set of records.
  32. The resource manager, however, allows you to specify a large
  33. set of values with an imprecise specification, to query the database 
  34. with a precise specification, and to get back only a single value.
  35. This should be used by applications that need to know what the
  36. user prefers for colors, fonts, and other resources.
  37. It is this use as a database for dealing with X resources that
  38. inspired the name ``Resource Manager,''
  39. although the resource manager can be and is used in other ways.
  40. .LP
  41. For example, 
  42. a user of your application may want to specify 
  43. that all windows should have a blue background 
  44. but that all mail-reading windows should have a red background.
  45. With well-engineered and coordinated applications,
  46. a user can define this information using only two lines of specifications.
  47. .LP
  48. As an example of how the resource manager works,
  49. consider a mail-reading application called xmh.
  50. Assume that it is designed so that it uses a
  51. complex window hierarchy all the way down to individual command buttons,
  52. which may be actual small subwindows in some toolkits.
  53. These are often called objects or widgets.
  54. In such toolkit systems,
  55. each user interface object can be composed of other objects
  56. and can be assigned a name and a class.
  57. Fully qualified names or classes can have arbitrary numbers of component names,
  58. but a fully qualified name always has the same number of component names as a
  59. fully qualified class.
  60. This generally reflects the structure of the application as composed
  61. of these objects, starting with the application itself.
  62. .LP
  63. For example, the xmh mail program has a name ``xmh'' and is one
  64. of a class of ``Mail'' programs.
  65. By convention, the first character of class components is capitalized,
  66. and the first letter of name components is in lowercase.
  67. Each name and class finally has an attribute
  68. (for example ``foreground'' or ``font'').
  69. If each window is properly assigned a name and class,
  70. it is easy for the user to specify attributes of any portion 
  71. of the application.
  72. .LP
  73. At the top level, 
  74. the application might consist of a paned window (that is, a window divided
  75. into several sections) named ``toc''.
  76. One pane of the paned window is a button box window named ``buttons''
  77. and is filled with command buttons. 
  78. One of these command buttons is used to incorporate
  79. new mail and has the name ``incorporate''.
  80. This window has a fully qualified name, ``xmh.toc.buttons.incorporate'',
  81. and a fully qualified class, ``Xmh.Paned.Box.Command''.
  82. Its fully qualified name is the name of its parent, ``xmh.toc.buttons'', 
  83. followed by its name, ``incorporate''.
  84. Its class is the class of its parent, ``Xmh.Paned.Box'', 
  85. followed by its particular class, ``Command''.  
  86. The fully qualified name of a resource is
  87. the attribute's name appended to the object's fully qualified
  88. name, and the fully qualified class is its class appended to the object's
  89. class.
  90. .LP
  91. The incorporate button might need the following resources: 
  92. Title string,
  93. Font,
  94. Foreground color for its inactive state,
  95. Background color for its inactive state,
  96. Foreground color for its active state, and
  97. Background color for its active state.
  98. Each resource is considered
  99. to be an attribute of the button and, as such, has a name and a class.
  100. For example, the foreground color for the button in
  101. its active state might be named ``activeForeground'',
  102. and its class might be ``Foreground''.
  103. .LP
  104. When an application looks up a resource (for example, a color),
  105. it passes the complete name and complete class of the resource
  106. to a lookup routine.
  107. The resource manager compares this complete specification
  108. against the incomplete specifications of entries in the resource
  109. database, find the best match, and returns the corresponding
  110. value for that entry.
  111. .LP
  112. The definitions for the resource manager are contained in
  113. .Pn < X11/Xresource.h >.
  114. .NH 2
  115. Resource File Syntax
  116. .XS
  117. \*(SN Resource File Syntax
  118. .XE
  119. .LP
  120. The syntax of a resource file is a sequence of resource lines
  121. terminated by newline characters or end of file.
  122. The syntax of an individual resource line is:
  123. .LP
  124. .\" Start marker code here
  125. .Ds 0
  126. .TA 1.5i 1.75i
  127. .ta 1.5i 1.75i
  128. ResourceLine    =    Comment | IncludeFile | ResourceSpec | <empty line>
  129. Comment    =    "!" {<any character except null or newline>}
  130. IncludeFile    =    "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
  131. FileName    =    <valid filename for operating system>
  132. ResourceSpec    =    WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
  133. ResourceName    =    [Binding] {Component Binding} ComponentName
  134. Binding    =    "\&." | "*"
  135. WhiteSpace    =    {<space> | <horizontal tab>}
  136. Component    =    "?" | ComponentName
  137. ComponentName    =    NameChar {NameChar}
  138. NameChar    =    "a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-"
  139. Value    =    {<any character except null or unescaped newline>}
  140. .De
  141. .\" End marker code here
  142. .LP
  143. Elements separated by vertical bar (|) are alternatives.
  144. Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
  145. of the enclosed elements.
  146. Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional.
  147. Quotes ("\&.\&.\&.") are used around literal characters.
  148. .LP
  149. IncludeFile lines are interpreted by replacing the line with the
  150. contents of the specified file.  The word "include" must be in lowercase.
  151. The filename is interpreted relative to the directory of the file in
  152. which the line occurs (for example, if the filename contains no
  153. directory or contains a relative directory specification).
  154. .LP
  155. If a ResourceName contains a contiguous sequence of two or more Binding
  156. characters, the sequence will be replaced with single "\&." character
  157. if the sequence contains only "\&." characters,
  158. otherwise the sequence will be replaced with a single "*" character.
  159. .LP
  160. A resource database never contains more than one entry for a given
  161. ResourceName.  If a resource file contains multiple lines with the
  162. same ResourceName, the last line in the file is used.
  163. .LP
  164. Any whitespace character before or after the name or colon in a ResourceSpec
  165. are ignored.
  166. To allow a Value to begin with whitespace,
  167. the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space)
  168. is recognized and replaced by a space character,
  169. and the two-character sequence ``\\\^\fItab\fP''
  170. (backslash followed by horizontal tab)
  171. is recognized and replaced by a horizontal tab character.
  172. To allow a Value to contain embedded newline characters,
  173. the two-character sequence ``\\\^n'' is recognized and replaced by a
  174. newline character.
  175. To allow a Value to be broken across multiple lines in a text file,
  176. the two-character sequence ``\\\^\fInewline\fP''
  177. (backslash followed by newline) is
  178. recognized and removed from the value.
  179. To allow a Value to contain arbitrary character codes,
  180. the four-character sequence ``\\\^\fInnn\fP'',
  181. where each \fIn\fP is a digit character in the range of ``0''\-``7'',
  182. is recognized and replaced with a single byte that contains
  183. the octal value specified by the sequence.
  184. Finally, the two-character sequence ``\\\\'' is recognized
  185. and replaced with a single backslash.
  186. .LP
  187. As an example of these sequences,
  188. the following resource line contains a value consisting of four
  189. characters: a backslash, a null, a ``z'', and a newline:
  190. .Ds 
  191. magic.values: \\\\\\\^000\^\\
  192. z\\\^n
  193. .De
  194. .NH 2
  195. Resource Manager Matching Rules
  196. .XS
  197. \*(SN Resource Manager Matching Rules
  198. .XE
  199. .LP
  200. The algorithm for determining which resource database entry
  201. matches a given query is the heart of the resource manager.
  202. All queries must fully specify the name and class of the desired resource
  203. (use of "*" and "?" are not permitted).
  204. The library supports up to 100 components in a full name or class.
  205. Resources are stored in the database with only partially specified
  206. names and classes, using pattern matching constructs.
  207. An asterisk (*) is a loose binding and is used to represent any number
  208. of intervening components, including none.
  209. A period (.) is a tight binding and is used to separate immediately
  210. adjacent components.
  211. A question mark (?) is used to match any single component name or class.
  212. A database entry cannot end in a loose binding;
  213. the final component (which cannot be "?") must be specified.
  214. The lookup algorithm searches the database for the entry that most
  215. closely matches (is most specific for) the full name and class being queried.
  216. When more than one database entry matches the full name and class,
  217. precedence rules are used to select just one.
  218. .LP
  219. The full name and class are scanned from left to right (from highest
  220. level in the hierarchy to lowest), one component at a time.
  221. At each level, the corresponding component and/or binding of each
  222. matching entry is determined, and these matching components and
  223. bindings are compared according to precedence rules.
  224. Each of the rules is applied at each level,
  225. before moving to the next level,
  226. until a rule selects a single entry over all others.
  227. The rules (in order of precedence) are:
  228. .IP 1. 5
  229. An entry that contains a matching component (whether name, class, or "?")
  230. takes precedence over entries that elide the level (that is, entries
  231. that match the level in a loose binding).
  232. .IP 2. 5
  233. An entry with a matching name takes precedence over both
  234. entries with a matching class and entries that match using "?".
  235. An entry with a matching class takes precedence over
  236. entries that match using "?".
  237. .IP 3. 5
  238. An entry preceded by a tight binding takes precedence over entries
  239. preceded by a loose binding.
  240. .LP
  241. To illustrate these rules, consider following the resource database entries:
  242. .Ds 
  243. .TA 2.5i 3.5i
  244. .ta 2.5i 3.5i
  245. xmh*Paned*activeForeground:    red    \fI(entry A)\fP
  246. *incorporate.Foreground:    blue    \fI(entry B)\fP
  247. xmh.toc*Command*activeForeground:    green    \fI(entry C)\fP
  248. xmh.toc*?.Foreground:    white    \fI(entry D)\fP
  249. xmh.toc*Command.activeForeground:    black    \fI(entry E)\fP
  250. .De
  251. .LP
  252. Consider a query for the resource:
  253. .LP
  254. .Ds 
  255. .TA 3.5i
  256. .ta 3.5i
  257. xmh.toc.messagefunctions.incorporate.activeForeground    \fI(name)\fP
  258. Xmh.Paned.Box.Command.Foreground    \fI(class)\fP
  259. .De
  260. .LP
  261. At the first level (xmh, Xmh) rule 1 eliminates entry B.
  262. At the second level (toc, Paned) rule 2 eliminates entry A.
  263. At the third level (messagefunctions, Box) no entries are eliminated.
  264. At the fourth level (incorporate, Command) rule 2 eliminates entry D.
  265. At the fifth level (activeForeground, Foreground) rule 3 eliminates entry C.
  266. .NH 2
  267. Quarks
  268. .XS
  269. \*(SN Quarks
  270. .XE
  271. .LP
  272. Most uses of the resource manager involve defining names,
  273. classes, and representation types as string constants.
  274. However, always referring to strings in the resource manager can be slow,
  275. because it is so heavily used in some toolkits.
  276. To solve this problem, 
  277. a shorthand for a string is used in place of the string
  278. in many of the resource manager functions.
  279. Simple comparisons can be performed rather than string comparisons.
  280. The shorthand name for a string is called a quark and is the
  281. type 
  282. .PN XrmQuark .
  283. On some occasions,
  284. you may want to allocate a quark that has no string equivalent.
  285. .LP
  286. A quark is to a string what an atom is to a string in the server,
  287. but its use is entirely local to your application.
  288. .LP
  289. .sp
  290. To allocate a new quark, use
  291. .PN XrmUniqueQuark .
  292. .IN "XrmUniqueQuark" "" "@DEF@"
  293. .\" Start marker code here
  294. .FD 0
  295. XrmQuark XrmUniqueQuark\^(\|)
  296. .FN
  297. .\" End marker code here
  298. .LP
  299. The
  300. .PN XrmUniqueQuark
  301. function allocates a quark that is guaranteed not to represent any string that
  302. is known to the resource manager.
  303. .LP
  304. .sp
  305. Each name, class, and representation type is typedef'd as an
  306. .PN XrmQuark .
  307. .LP
  308. .\" Start marker code here
  309. .Ds 0
  310. typedef int XrmQuark, *XrmQuarkList;
  311. typedef XrmQuark XrmName;
  312. typedef XrmQuark XrmClass;
  313. typedef XrmQuark XrmRepresentation;
  314. #define NULLQUARK ((XrmQuark) 0)
  315. .De
  316. .\" End marker code here
  317. .LP
  318. Lists are represented as null-terminated arrays of quarks.
  319. The size of the array must be large enough for the number of components used.
  320. .LP
  321. .\" Start marker code here
  322. .Ds 0
  323. typedef XrmQuarkList XrmNameList;
  324. typedef XrmQuarkList XrmClassList;
  325. .De
  326. .\" End marker code here
  327. .LP
  328. .sp
  329. To convert a string to a quark, use
  330. .PN XrmStringToQuark
  331. or
  332. .PN XrmPermStringToQuark .
  333. .IN "XrmStringToQuark" "" "@DEF@"
  334. .IN "XrmPermStringToQuark" "" "@DEF@"
  335. .\" Start marker code here
  336. .FD 0
  337. #define XrmStringToName(string) XrmStringToQuark(string)
  338. #define XrmStringToClass(string) XrmStringToQuark(string)
  339. #define XrmStringToRepresentation(string) XrmStringToQuark(string)
  340. .sp
  341. XrmQuark XrmStringToQuark\^(\^\fIstring\fP\^)
  342. .br
  343.      char *\fIstring\fP\^;
  344. .sp
  345. XrmQuark XrmPermStringToQuark\^(\^\fIstring\fP\^)
  346. .br
  347.      char *\fIstring\fP\^;
  348. .FN
  349. .ds Ql
  350. .IP \fIstring\fP 1i
  351. Specifies the string for which a quark\*(Ql is to be allocated.
  352. .\" End marker code here
  353. .LP
  354. These functions can be used to convert from string to quark representation.
  355. If the string is not in the Host Portable Character Encoding
  356. the conversion is implementation dependent.
  357. The string argument to
  358. .PN XrmStringToQuark
  359. need not be permanently allocated storage.
  360. .PN XrmPermStringToQuark
  361. is just like
  362. .PN XrmStringToQuark ,
  363. except that Xlib is permitted to assume the string argument is permanently
  364. allocated,
  365. and hence that it can be used as the value to be returned by
  366. .PN XrmQuarkToString .
  367. .LP
  368. .sp
  369. To convert a quark to a string, use 
  370. .PN XrmQuarkToString .
  371. .IN "XrmQuarkToString" "" "@DEF@"
  372. .\" Start marker code here
  373. .FD 0
  374. #define XrmNameToString(name) XrmQuarkToString(name)
  375. #define XrmClassToString(class) XrmQuarkToString(class)
  376. #define XrmRepresentationToString(type) XrmQuarkToString(type)
  377. .sp
  378. char *XrmQuarkToString\^(\^\fIquark\fP\^)
  379. .br
  380.      XrmQuark \fIquark\fP\^;
  381. .FN
  382. .IP \fIquark\fP 1i
  383. Specifies the quark for which the equivalent string is desired.
  384. .\" End marker code here
  385. .LP
  386. This function can be used to convert from quark representation to string.
  387. The string pointed to by the return value must not be modified or freed.
  388. The returned string is byte-for-byte equal to the original
  389. string passed to one of the string-to-quark routines.
  390. If no string exists for that quark,
  391. .PN XrmQuarkToString
  392. returns NULL.
  393. For any given quark, if
  394. .PN XrmQuarkToString
  395. returns a non-NULL value,
  396. all future calls will return the same value (identical address).
  397. .LP
  398. .sp
  399. To convert a string with one or more components to a quark list, use
  400. .PN XrmStringToQuarkList .
  401. .IN "XrmStringToQuarkList" "" "@DEF@"
  402. .\" Start marker code here
  403. .FD 0
  404. #define XrmStringToNameList(str, name)  XrmStringToQuarkList((str), (name))
  405. #define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
  406. .sp
  407. void XrmStringToQuarkList\^(\^\fIstring\fP, \fIquarks_return\fP\^)
  408. .br
  409.      char *\fIstring\fP\^;
  410. .br
  411.      XrmQuarkList \fIquarks_return\fP\^;
  412. .FN
  413. .ds Ql \ list
  414. .IP \fIstring\fP 1i
  415. Specifies the string for which a quark\*(Ql is to be allocated.
  416. .IP \fIquarks_return\fP 1i
  417. Returns the list of quarks.
  418. .\" End marker code here
  419. .LP
  420. The
  421. .PN XrmStringToQuarkList
  422. function converts the null-terminated string (generally a fully qualified name)
  423. to a list of quarks.
  424. Note that the string must be in the valid ResourceName format 
  425. (see section 15.1).
  426. If the string is not in the Host Portable Character Encoding
  427. the conversion is implementation dependent.
  428. .LP
  429. A binding list is a list of type
  430. .PN XrmBindingList
  431. and indicates if components of name or class lists are bound tightly or loosely
  432. (that is, if wildcarding of intermediate components is specified).
  433. .LP
  434. .Ds 0
  435. typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
  436. .De
  437. .LP
  438. .PN XrmBindTightly
  439. indicates that a period separates the components, and
  440. .PN XrmBindLoosely
  441. indicates that an asterisk separates the components.
  442. .LP
  443. .sp
  444. To convert a string with one or more components to a binding list
  445. and a quark list, use
  446. .PN XrmStringToBindingQuarkList .
  447. .IN "XrmStringToBindingQuarkList" "" "@DEF@"
  448. .\" Start marker code here
  449. .FD 0
  450. XrmStringToBindingQuarkList\^(\^\fIstring\fP, \fIbindings_return\fP, \
  451. \fIquarks_return\fP\^)
  452. .br
  453.      char *\fIstring\fP\^;
  454. .br
  455.      XrmBindingList \fIbindings_return\fP\^;
  456. .br
  457.      XrmQuarkList \fIquarks_return\fP\^;
  458. .FN
  459. .ds Ql \ list
  460. .IP \fIstring\fP 1i
  461. Specifies the string for which a quark\*(Ql is to be allocated.
  462. .IP \fIbindings_return\fP 1i
  463. Returns the binding list.
  464. The caller must allocate sufficient space for the binding list before calling 
  465. .PN XrmStringToBindingQuarkList .
  466. .IP \fIquarks_return\fP 1i
  467. Returns the list of quarks.
  468. The caller must allocate sufficient space for the quarks list before calling 
  469. .PN XrmStringToBindingQuarkList .
  470. .\" End marker code here
  471. .LP
  472. Component names in the list are separated by a period or 
  473. an asterisk character.
  474. The string must be in the format of a valid ResourceName (see section 15.1).
  475. If the string does not start with a period or an asterisk, 
  476. a tight binding is assumed.
  477. For example, ``*a.b*c'' becomes:
  478. .LP
  479. .Ds 0
  480. .TA .75i 1.5i 2.25i
  481. .ta .75i 1.5i 2.25i
  482. quarks:    a    b    c
  483. bindings:    loose    tight    loose
  484. .De
  485. .NH 2
  486. Creating and Storing Databases
  487. .XS
  488. \*(SN Creating and Storing Databases
  489. .XE
  490. .LP
  491. .IN "XrmDatabase" "" "@DEF@"
  492. A resource database is an opaque type,
  493. .PN XrmDatabase .
  494. Each database value is stored in an
  495. .PN XrmValue 
  496. structure.
  497. This structure consists of a size, an address, and a representation type.
  498. The size is specified in bytes.
  499. The representation type is a way for you to store data tagged by some 
  500. application-defined type (for example, ``font'' or ``color'').
  501. It has nothing to do with the C data type or with its class. 
  502. The
  503. .PN XrmValue 
  504. structure is defined as:
  505. .LP
  506. .IN "XrmValue" "" "@DEF@"
  507. .\" Start marker code here
  508. .Ds 0
  509. .TA .5i 3i
  510. .ta .5i 3i
  511. typedef struct {
  512.     unsigned int size;
  513.     XPointer addr;
  514. } XrmValue, *XrmValuePtr;
  515. .De
  516. .\" End marker code here
  517. .LP
  518. .sp
  519. To initialize the resource manager, use
  520. .PN XrmInitialize .
  521. .IN "XrmInitialize" "" "@DEF@"
  522. .\" Start marker code here
  523. .FD 0
  524. void XrmInitialize\^(\|);
  525. .FN
  526. .\" End marker code here
  527. .LP
  528. To retrieve a database from disk, use
  529. .PN XrmGetFileDatabase .
  530. .IN "XrmGetFileDatabase" "" "@DEF@"
  531. .\" Start marker code here
  532. .FD 0
  533. XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^)
  534. .br
  535.      char *\fIfilename\fP\^;
  536. .FN
  537. .IP \fIfilename\fP 1i
  538. Specifies the resource database file name.
  539. .\" End marker code here
  540. .LP
  541. The
  542. .PN XrmGetFileDatabase
  543. function opens the specified file,
  544. creates a new resource database, and loads it with the specifications
  545. read in from the specified file.
  546. The specified file must contain a sequence of entries in valid ResourceLine
  547. format (see section 15.1).
  548. The file is parsed in the current locale, 
  549. and the database is created in the current locale.
  550. If it cannot open the specified file,
  551. .PN XrmGetFileDatabase
  552. returns NULL.
  553. .LP
  554. .sp
  555. To store a copy of a database to disk, use
  556. .PN XrmPutFileDatabase .
  557. .IN "XrmPutFileDatabase" "" "@DEF@"
  558. .\" Start marker code here
  559. .FD 0
  560. void XrmPutFileDatabase\^(\^\fIdatabase\fP, \fIstored_db\fP\^)
  561. .br
  562.      XrmDatabase \fIdatabase\fP\^;
  563. .br
  564.      char *\fIstored_db\fP\^;
  565. .FN
  566. .IP \fIdatabase\fP 1i
  567. Specifies the database that is to be used.
  568. .IP \fIstored_db\fP 1i
  569. Specifies the file name for the stored database.
  570. .\" End marker code here
  571. .LP
  572. The
  573. .PN XrmPutFileDatabase
  574. function stores a copy of the specified database in the specified file.
  575. Text is written to the file as a sequence of entries in valid
  576. ResourceLine format (see section 15.1).
  577. The file is written in the locale of the database.
  578. Entries containing resource names that are not in the Host Portable Character
  579. Encoding, or containing values that are not in the encoding of the database
  580. locale, are written in an implementation-dependent manner.
  581. The order in which entries are written is implementation dependent.
  582. Entries with representation types other than ``String'' are ignored.
  583. .LP
  584. .sp
  585. To obtain a pointer to the screen-independent resources of a display, use
  586. .PN XResourceManagerString .
  587. .IN "XResourceManagerString" "" "@DEF@"
  588. .\" Start marker code here
  589. .FD 0
  590. char *XResourceManagerString\^(\^\fIdisplay\fP\^)
  591. .br
  592.       Display *\fIdisplay\fP\^;
  593. .FN
  594. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  595. .IP \fIdisplay\fP 1i
  596. Specifies the connection to the X server.
  597. .\" End marker code here
  598. .LP
  599. The
  600. .PN XResourceManagerString
  601. returns the RESOURCE_MANAGER property from the server's root window of screen
  602. zero, which was returned when the connection was opened using
  603. .PN XOpenDisplay .
  604. The property is converted from type STRING to the current locale.
  605. The conversion is identical to that produced by 
  606. .PN XmbTextPropertyToTextList
  607. for a singleton STRING property.
  608. The returned string is owned by Xlib, and should not be freed by the client.
  609. Note that the property value must be in a format that is acceptable to
  610. .PN XrmGetStringDatabase .
  611. If no property exists, NULL is returned.
  612. .LP
  613. .sp
  614. To obtain a pointer to the screen-specific resources of a screen, use
  615. .PN XScreenResourceString .
  616. .IN "XScreenResourceString" "" "@DEF@"
  617. .\" Start marker code here
  618. .FD 0
  619. char *XScreenResourceString\^(\^\fIscreen\fP\^)
  620. .br
  621.       Screen *\fIscreen\fP\^;
  622. .FN
  623. .IP \fIscreen\fP 1i
  624. Specifies the screen.
  625. .\" End marker code here
  626. .LP
  627. The
  628. .PN XStringResourceString
  629. returns the SCREEN_RESOURCES property from the root window of the
  630. specified screen.
  631. The property is converted from type STRING to the current locale.
  632. The conversion is identical to that produced by 
  633. .PN XmbTextPropertyToTextList
  634. for a singleton STRING property.
  635. Note that the property value must be in a format that is acceptable to
  636. .PN XrmGetStringDatabase .
  637. If no property exists, NULL is returned.
  638. The caller is responsible for freeing the returned string, using
  639. .PN XFree .
  640. .LP
  641. .sp
  642. To create a database from a string, use
  643. .PN XrmGetStringDatabase .
  644. .IN "XrmGetStringDatabase" "" "@DEF@"
  645. .\" Start marker code here
  646. .FD 0
  647. XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^)
  648. .br
  649.      char *\fIdata\fP\^;
  650. .FN
  651. .IP \fIdata\fP 1i
  652. Specifies the database contents using a string.
  653. .\" End marker code here
  654. .LP
  655. The
  656. .PN XrmGetStringDatabase
  657. function creates a new database and stores the resources specified
  658. in the specified null-terminated string.
  659. .PN XrmGetStringDatabase
  660. is similar to
  661. .PN XrmGetFileDatabase
  662. except that it reads the information out of a string instead of out of a file.
  663. The string must contain a sequence of entries in valid ResourceLine
  664. format (see section 15.1).
  665. The string is parsed in the current locale, 
  666. and the database is created in the current locale.
  667. .LP
  668. .sp
  669. To obtain locale name of a database, use
  670. .PN XrmLocaleOfDatabase .
  671. .IN "XrmLocaleOfDatabase" "" "@DEF@"
  672. .\" Start marker code here
  673. .FD 0
  674. char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^)
  675. .br
  676.       XrmDatabase \fIdatabase\fP\^;
  677. .FN
  678. .IP \fIdatabase\fP 1i
  679. Specifies the resource database.
  680. .\" End marker code here
  681. .LP
  682. The
  683. .PN XrmLocaleOfDatabase
  684. function returns the name of the locale bound to the specified
  685. database, as a null-terminated string.
  686. The returned locale name string is owned by Xlib and should not be
  687. modified or freed by the client.
  688. Xlib is not permitted to free the string until the database is destroyed.
  689. Until the string is freed,
  690. it will not be modified by Xlib.
  691. .LP
  692. .sp
  693. To destroy a resource database and free its allocated memory, use
  694. .PN XrmDestroyDatabase .
  695. .IN "XrmDestroyDatabase" "" "@DEF@"
  696. .\" Start marker code here
  697. .FD 0
  698. void XrmDestroyDatabase\^(\^\fIdatabase\fP\^)
  699. .br
  700.       XrmDatabase \fIdatabase\fP\^;
  701. .FN
  702. .IP \fIdatabase\fP 1i
  703. Specifies the resource database.
  704. .\" End marker code here
  705. .LP
  706. If database is NULL,
  707. .PN XrmDestroyDatabase
  708. returns immediately.
  709. .LP
  710. .sp
  711. To associate a resource database with a display, use
  712. .PN XrmSetDatabase .
  713. .IN "XrmSetDatabase" "" "@DEF@"
  714. .\" Start marker code here
  715. .FD 0
  716. void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^)
  717. .br
  718.       Display *\fIdisplay\fP\^;
  719. .br
  720.       XrmDatabase \fIdatabase\fP\^;
  721. .FN
  722. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  723. .IP \fIdisplay\fP 1i
  724. Specifies the connection to the X server.
  725. .IP \fIdatabase\fP 1i
  726. Specifies the resource database.
  727. .\" End marker code here
  728. .LP
  729. The
  730. .PN XrmSetDatabase
  731. function associates the specified resource database (or NULL)
  732. with the specified display.
  733. The database previously associated with the display (if any) is not destroyed.
  734. A client or toolkit may find this function convenient for retaining a database
  735. once it is constructed.
  736. .LP
  737. .sp
  738. To get the resource database associated with a display, use
  739. .PN XrmGetDatabase .
  740. .IN "XrmGetDatabase" "" "@DEF@"
  741. .\" Start marker code here
  742. .FD 0
  743. XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^)
  744. .br
  745.       Display *\fIdisplay\fP\^;
  746. .FN
  747. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  748. .IP \fIdisplay\fP 1i
  749. Specifies the connection to the X server.
  750. .\" End marker code here
  751. .LP
  752. The
  753. .PN XrmGetDatabase
  754. function returns the database associated with the specified display.
  755. It returns NULL if a database has not yet been set.
  756. .NH 2
  757. Merging Resource Databases
  758. .XS
  759. \*(SN Merging Resource Databases
  760. .XE
  761. .LP
  762. To merge the contents of a resource file into a database, us
  763. .PN XrmCombineFileDatabase .
  764. .IN "XrmCombineFileDatabase" "" "@DEF@"
  765. .\" Start marker code here
  766. .FD 0
  767. void XrmCombineFileDatabase(\^\fIfilename\fP, \fItarget_db\fP, \fIoverride\fP\^)
  768. .br
  769.       char *\fIfilename\fP;
  770. .br
  771.       XrmDatabase *\fItarget_db\fP\^;
  772. .br
  773.       Bool \fIoverride\fP;
  774. .FN
  775. .IP \fIfilename\fP 1i
  776. Specifies the resource database file name.
  777. .IP \fItarget_db\fP 1i
  778. Specifies the resource database into which the source 
  779. database is to be merged.
  780. .\" End marker code here
  781. .LP 
  782. .\" $Header: XrmCFDBase.d,v 1.2 88/06/11 07:54:46 mento Exp $
  783. The
  784. .PN XrmCombineFileDatabase
  785. function merges the contents of a resource file into a database.
  786. If the same specifier is used for an entry in both the file and
  787. the database,
  788. the entry in the file will replace the entry in the database
  789. if override is
  790. .PN True ;
  791. otherwise, the entry in file is discarded.
  792. The file is parsed in the current locale.
  793. If the file cannot be read a zero status is returned;
  794. otherwise a nonzero status is returned.
  795. If target_db contains NULL,
  796. .PN XrmCombineFileDatabase
  797. creates and returns a new database to it.
  798. Otherwise, the database pointed to by target_db is not destroyed by the merge.
  799. The database entries are merged without changing values or types,
  800. regardless of the locale of the database.
  801. The locale of the target database is not modified.
  802. .LP
  803. .sp
  804. To merge the contents of one database into another database, use
  805. .PN XrmCombineDatabase .
  806. .IN "XrmCombineDatabase" "" "@DEF@"
  807. .\" Start marker code here
  808. .FD 0
  809. void XrmCombineDatabase(\^\fIsource_db\fP, \fItarget_db\fP, \fIoverride\fP\^)
  810. .br
  811.       XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
  812. .br
  813.       Bool \fIoverride\fP;
  814. .FN
  815. .IP \fIsource_db\fP 1i
  816. Specifies the resource database that is to be merged into the target database.
  817. .IP \fItarget_db\fP 1i
  818. Specifies the resource database into which the source 
  819. database is to be merged.
  820. .IP \fIoverride\fP 1i
  821. Specifies whether source entries override target ones.
  822. .\" End marker code here
  823. .LP 
  824. .\" $Header: XrmCDBase.d,v 1.2 88/06/11 07:54:46 mento Exp $
  825. The
  826. .PN XrmCombineDatabase
  827. function merges the contents of one database into another.
  828. If the same specifier is used for an entry in both databases,
  829. the entry in the source_db will replace the entry in the target_db
  830. if override is
  831. .PN True ;
  832. otherwise, the entry in source_db is discarded.
  833. If target_db contains NULL,
  834. .PN XrmCombineDatabase
  835. simply stores source_db in it.
  836. Otherwise, source_db is destroyed by the merge, but the database pointed
  837. to by target_db is not destroyed.
  838. The database entries are merged without changing values or types,
  839. regardless of the locales of the databases.
  840. The locale of the target database is not modified.
  841. .LP
  842. .sp
  843. To merge the contents of one database into another database with override
  844. semantics, use
  845. .PN XrmMergeDatabases .
  846. .IN "XrmMergeDatabases" "" "@DEF@"
  847. .\" Start marker code here
  848. .FD 0
  849. void XrmMergeDatabases(\^\fIsource_db\fP, \fItarget_db\fP\^)
  850. .br
  851.       XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
  852. .FN
  853. .IP \fIsource_db\fP 1i
  854. Specifies the resource database that is to be merged into the target database.
  855. .IP \fItarget_db\fP 1i
  856. Specifies the resource database into which the source 
  857. database is to be merged.
  858. .\" End marker code here
  859. .LP 
  860. .\" $Header: XrmMDBase.d,v 1.2 88/06/11 07:54:46 mento Exp $
  861. The
  862. .PN XrmMergeDatabases
  863. function merges the contents of one database into another.
  864. If the same specifier is used for an entry in both databases,
  865. the entry in the source_db will replace the entry in the target_db
  866. (that is, it overrides target_db).
  867. If target_db contains NULL,
  868. .PN XrmMergeDatabases
  869. simply stores source_db in it.
  870. Otherwise, source_db is destroyed by the merge, but the database pointed
  871. to by target_db is not destroyed.
  872. The database entries are merged without changing values or types,
  873. regardless of the locales of the databases.
  874. The locale of the target database is not modified.
  875. .NH 2
  876. Looking Up Resources
  877. .XS
  878. \*(SN Looking Up Resources
  879. .XE
  880. .LP
  881. To retrieve a resource from a resource database, use
  882. .PN XrmGetResource ,
  883. .PN XrmQGetResource ,
  884. or
  885. .PN XrmQGetSearchResource .
  886. .LP
  887. .sp
  888. .IN "XrmGetResource" "" "@DEF@"
  889. .\" Start marker code here
  890. .FD 0
  891. Bool XrmGetResource\^(\^\fIdatabase\fP, \fIstr_name\fP, \fIstr_class\fP, \
  892. \fIstr_type_return\fP, \fIvalue_return\fP\^)
  893. .br
  894.      XrmDatabase \fIdatabase\fP\^;
  895. .br
  896.      char *\fIstr_name\fP\^;
  897. .br
  898.      char *\fIstr_class\fP\^;
  899. .br
  900.      char **\fIstr_type_return\fP\^;
  901. .br
  902.      XrmValue *\fIvalue_return\fP\^; 
  903. .FN
  904. .IP \fIdatabase\fP 1i
  905. Specifies the database that is to be used.
  906. .IP \fIstr_name\fP 1i
  907. Specifies the fully qualified name of the value being retrieved (as a string).
  908. .IP \fIstr_class\fP 1i
  909. Specifies the fully qualified class of the value being retrieved (as a string).
  910. .IP \fIstr_type_return\fP 1i
  911. Returns the representation type of the destination (as a string).
  912. .IP \fIvalue_return\fP 1i
  913. Returns the value in the database.
  914. .\" End marker code here
  915. .LP
  916. .sp
  917. .IN "XrmQGetResource" "" "@DEF@"
  918. .\" Start marker code here
  919. .FD 0
  920. Bool XrmQGetResource\^(\^\fIdatabase\fP, \fIquark_name\fP, \fIquark_class\fP, \
  921. \fIquark_type_return\fP, \fIvalue_return\fP\^)
  922. .br
  923.      XrmDatabase \fIdatabase\fP\^;
  924. .br
  925.      XrmNameList \fIquark_name\fP\^;
  926. .br
  927.      XrmClassList \fIquark_class\fP\^;
  928. .br
  929.      XrmRepresentation *\fIquark_type_return\fP\^;
  930. .br
  931.      XrmValue *\fIvalue_return\fP\^; 
  932. .FN
  933. .IP \fIdatabase\fP 1i
  934. Specifies the database that is to be used.
  935. .IP \fIquark_name\fP 1i
  936. Specifies the fully qualified name of the value being retrieved (as a quark).
  937. .IP \fIquark_class\fP 1i
  938. Specifies the fully qualified class of the value being retrieved (as a quark).
  939. .IP \fIquark_type_return\fP 1i
  940. Returns the representation type of the destination (as a quark).
  941. .IP \fIvalue_return\fP 1i
  942. Returns the value in the database.
  943. .\" End marker code here
  944. .LP
  945. The 
  946. .PN XrmGetResource 
  947. and 
  948. .PN XrmQGetResource 
  949. functions retrieve a resource from the specified database.
  950. Both take a fully qualified name/class pair, a destination
  951. resource representation, and the address of a value
  952. (size/address pair).  
  953. The value and returned type point into database memory;
  954. therefore, you must not modify the data.
  955. .LP
  956. The database only frees or overwrites entries on
  957. .PN XrmPutResource , 
  958. .PN XrmQPutResource ,
  959. or 
  960. .PN XrmMergeDatabases .
  961. A client that is not storing new values into the database or
  962. is not merging the database should be safe using the address passed 
  963. back at any time until it exits.
  964. If a resource was found, both
  965. .PN XrmGetResource 
  966. and
  967. .PN XrmQGetResource 
  968. return 
  969. .PN True ;
  970. otherwise, they return 
  971. .PN False .
  972. .LP
  973. .sp
  974. Most applications and toolkits do not make random probes
  975. into a resource database to fetch resources.
  976. The X toolkit access pattern for a resource database is quite stylized.
  977. A series of from 1 to 20 probes are made with only the 
  978. last name/class differing in each probe.
  979. The 
  980. .PN XrmGetResource 
  981. function is at worst a %2 sup n% algorithm,
  982. where \fIn\fP is the length of the name/class list.
  983. This can be improved upon by the application programmer by prefetching a list
  984. of database levels that might match the first part of a name/class list.
  985. .LP
  986. .sp
  987. To obtain a list of database levels, use
  988. .PN XrmQGetSearchList .
  989. .IN "XrmQGetSearchList" "" "@DEF@"
  990. .\" Start marker code here
  991. .FD 0
  992. typedef XrmHashTable *XrmSearchList;
  993. .sp
  994. Bool XrmQGetSearchList\^(\^\fIdatabase\fP, \fInames\fP, \fIclasses\fP, \
  995. \fIlist_return\fP, \fIlist_length\fP\^)
  996. .br
  997.      XrmDatabase \fIdatabase\fP\^;
  998. .br
  999.      XrmNameList \fInames\fP\^;
  1000. .br
  1001.      XrmClassList \fIclasses\fP\^;
  1002. .br
  1003.      XrmSearchList \fIlist_return\fP\^;
  1004. .br
  1005.      int \fIlist_length\fP\^;
  1006. .FN
  1007. .IP \fIdatabase\fP 1i
  1008. Specifies the database that is to be used.
  1009. .IP \fInames\fP 1i
  1010. Specifies a list of resource names.
  1011. .IP \fIclasses\fP 1i
  1012. Specifies a list of resource classes.
  1013. .IP \fIlist_return\fP 1i
  1014. Returns a search list for further use.
  1015. The caller must allocate sufficient space for the list before calling 
  1016. .PN XrmQGetSearchList .
  1017. .IP \fIlist_length\fP 1i
  1018. Specifies the number of entries (not the byte size) allocated for list_return.
  1019. .\" End marker code here
  1020. .LP
  1021. .EQ
  1022. delim %%
  1023. .EN
  1024. The
  1025. .PN XrmQGetSearchList
  1026. function takes a list of names and classes
  1027. and returns a list of database levels where a match might occur.
  1028. The returned list is in best-to-worst order and
  1029. uses the same algorithm as 
  1030. .PN XrmGetResource 
  1031. for determining precedence.
  1032. If list_return was large enough for the search list,
  1033. .PN XrmQGetSearchList
  1034. returns 
  1035. .PN True ;
  1036. otherwise, it returns
  1037. .PN False .
  1038. .LP
  1039. The size of the search list that the caller must allocate is
  1040. dependent upon the number of levels and wildcards in the resource specifiers 
  1041. that are stored in the database.
  1042. The worst case length is %3 sup n%,
  1043. where \fIn\fP is the number of name or class components in names or classes.
  1044. .LP
  1045. When using 
  1046. .PN XrmQGetSearchList 
  1047. followed by multiple probes for resources with a common name and class prefix,
  1048. only the common prefix should be specified in the name and class list to 
  1049. .PN XrmQGetSearchList .
  1050. .LP
  1051. .sp
  1052. To search resource database levels for a given resource, use
  1053. .PN XrmQGetSearchResource .
  1054. .IN "XrmQGetSearchResource" "" "@DEF@"
  1055. .\" Start marker code here
  1056. .FD 0
  1057. Bool XrmQGetSearchResource\^(\^\fIlist\fP, \fIname\fP, \fIclass\fP, \
  1058. \fItype_return\fP, \fIvalue_return\fP\^)
  1059. .br
  1060.      XrmSearchList \fIlist\fP\^;
  1061. .br
  1062.      XrmName \fIname\fP\^;
  1063. .br
  1064.      XrmClass \fIclass\fP\^;
  1065. .br
  1066.      XrmRepresentation *\fItype_return\fP\^;
  1067. .br
  1068.      XrmValue *\fIvalue_return\fP\^;
  1069. .FN
  1070. .IP \fIlist\fP 1i
  1071. Specifies the search list returned by
  1072. .PN XrmQGetSearchList .
  1073. .IP \fIname\fP 1i
  1074. Specifies the resource name.
  1075. .IP \fIclass\fP 1i
  1076. Specifies the resource class.
  1077. .IP \fItype_return\fP 1i
  1078. Returns data representation type.
  1079. .IP \fIvalue_return\fP 1i
  1080. Returns the value in the database.
  1081. .\" End marker code here
  1082. .LP
  1083. The
  1084. .PN XrmQGetSearchResource
  1085. function searches the specified database levels for the resource 
  1086. that is fully identified by the specified name and class.
  1087. The search stops with the first match.
  1088. .PN XrmQGetSearchResource
  1089. returns 
  1090. .PN True 
  1091. if the resource was found;
  1092. otherwise, it returns
  1093. .PN False .
  1094. .LP
  1095. A call to 
  1096. .PN XrmQGetSearchList 
  1097. with a name and class list containing all but the last component 
  1098. of a resource name followed by a call to 
  1099. .PN XrmQGetSearchResource 
  1100. with the last component name and class returns the same database entry as 
  1101. .PN XrmGetResource 
  1102. and 
  1103. .PN XrmQGetResource 
  1104. with the fully qualified name and class.
  1105. .NH 2
  1106. Storing Into a Resource Database
  1107. .XS
  1108. \*(SN Storing Into a Resource Database
  1109. .XE
  1110. .LP
  1111. To store resources into the database, use
  1112. .PN XrmPutResource 
  1113. or
  1114. .PN XrmQPutResource .
  1115. Both functions take a partial resource specification, a
  1116. representation type, and a value.
  1117. This value is copied into the specified database.
  1118. .LP
  1119. .sp
  1120. .IN "XrmPutResource" "" "@DEF@"
  1121. .\" Start marker code here
  1122. .FD 0
  1123. void XrmPutResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fItype\fP, \fIvalue\fP\^)
  1124. .br
  1125.      XrmDatabase *\fIdatabase\fP\^;
  1126. .br
  1127.      char *\fIspecifier\fP\^;
  1128. .br
  1129.      char *\fItype\fP\^;
  1130. .br
  1131.      XrmValue *\fIvalue\fP\^;
  1132. .FN
  1133. .IP \fIdatabase\fP 1i
  1134. Specifies the resource database.
  1135. .IP \fIspecifier\fP 1i
  1136. Specifies a complete or partial specification of the resource.
  1137. .IP \fItype\fP 1i
  1138. Specifies the type of the resource.
  1139. .IP \fIvalue\fP 1i
  1140. Specifies the value of the resource, which is specified as a string.
  1141. .\" End marker code here
  1142. .LP
  1143. If database contains NULL,
  1144. .PN XrmPutResource
  1145. creates a new database and returns a pointer to it.
  1146. .PN XrmPutResource
  1147. is a convenience function that calls
  1148. .PN XrmStringToBindingQuarkList
  1149. followed by:
  1150. .LP
  1151. .Ds
  1152. XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
  1153. .De
  1154. If the specifier and type are not in the Host Portable Character Encoding
  1155. the result is implementation dependent.
  1156. The value is stored in the database without modification.
  1157. .LP
  1158. .sp
  1159. .IN "XrmQPutResource" "" "@DEF@"
  1160. .\" Start marker code here
  1161. .FD 0
  1162. void XrmQPutResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
  1163. \fItype\fP, \fIvalue\fP\^)
  1164. .br
  1165.      XrmDatabase *\fIdatabase\fP\^;
  1166. .br
  1167.      XrmBindingList \fIbindings\fP\^;
  1168. .br
  1169.      XrmQuarkList \fIquarks\fP\^;
  1170. .br
  1171.      XrmRepresentation \fItype\fP\^;
  1172. .br
  1173.      XrmValue *\fIvalue\fP\^;
  1174. .FN
  1175. .IP \fIdatabase\fP 1i
  1176. Specifies the resource database.
  1177. .IP \fIbindings\fP 1i
  1178. Specifies a list of bindings.
  1179. .IP \fIquarks\fP 1i
  1180. Specifies the complete or partial name or the class list of the resource.
  1181. .IP \fItype\fP 1i
  1182. Specifies the type of the resource.
  1183. .IP \fIvalue\fP 1i
  1184. Specifies the value of the resource, which is specified as a string.
  1185. .\" End marker code here
  1186. .LP
  1187. If database contains NULL,
  1188. .PN XrmQPutResource
  1189. creates a new database and returns a pointer to it.
  1190. If a resource entry with the identical bindings and quarks already
  1191. exists in the database, the previous value is replaced by the new
  1192. specified value.
  1193. The value is stored in the database without modification.
  1194. .LP
  1195. .sp
  1196. To add a resource that is specified as a string, use
  1197. .PN XrmPutStringResource .
  1198. .IN "XrmPutStringResource" "" "@DEF@"
  1199. .\" Start marker code here
  1200. .FD 0
  1201. void XrmPutStringResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fIvalue\fP\^)
  1202. .br
  1203.      XrmDatabase *\fIdatabase\fP\^;
  1204. .br
  1205.      char *\fIspecifier\fP\^;
  1206. .br
  1207.      char *\fIvalue\fP\^;
  1208. .FN
  1209. .IP \fIdatabase\fP 1i
  1210. Specifies the resource database.
  1211. .IP \fIspecifier\fP 1i
  1212. Specifies a complete or partial specification of the resource.
  1213. .IP \fIvalue\fP 1i
  1214. Specifies the value of the resource, which is specified as a string.
  1215. .\" End marker code here
  1216. .LP
  1217. If database contains NULL,
  1218. .PN XrmPutStringResource
  1219. creates a new database and returns a pointer to it.
  1220. .PN XrmPutStringResource
  1221. adds a resource with the specified value to the specified database.
  1222. .PN XrmPutStringResource
  1223. is a convenience function that first calls
  1224. .PN XrmStringToBindingQuarkList
  1225. on the specifier and then calls
  1226. .PN XrmQPutResource ,
  1227. using a ``String'' representation type.
  1228. If the specifier is not in the Host Portable Character Encoding
  1229. the result is implementation dependent.
  1230. The value is stored in the database without modification.
  1231. .LP
  1232. .sp
  1233. To add a string resource using quarks as a specification, use
  1234. .PN XrmQPutStringResource .
  1235. .IN "XrmQPutStringResource" "" "@DEF@"
  1236. .\" Start marker code here
  1237. .FD 0
  1238. void XrmQPutStringResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
  1239. \fIvalue\fP\^)
  1240. .br
  1241.      XrmDatabase *\fIdatabase\fP\^;
  1242. .br
  1243.      XrmBindingList \fIbindings\fP\^;
  1244. .br
  1245.      XrmQuarkList \fIquarks\fP\^;
  1246. .br
  1247.      char *\fIvalue\fP\^;
  1248. .FN
  1249. .IP \fIdatabase\fP 1i
  1250. Specifies the resource database.
  1251. .IP \fIbindings\fP 1i
  1252. Specifies a list of bindings.
  1253. .IP \fIquarks\fP 1i
  1254. Specifies the complete or partial name or the class list of the resource.
  1255. .IP \fIvalue\fP 1i
  1256. Specifies the value of the resource, which is specified as a string.
  1257. .\" End marker code here
  1258. .LP
  1259. If database contains NULL,
  1260. .PN XrmQPutStringResource
  1261. creates a new database and returns a pointer to it.
  1262. .PN XrmQPutStringResource
  1263. is a convenience routine that constructs an
  1264. .PN XrmValue
  1265. for the value string (by calling
  1266. .PN strlen
  1267. to compute the size) and
  1268. then calls
  1269. .PN XrmQPutResource ,
  1270. using a ``String'' representation type.
  1271. The value is stored in the database without modification.
  1272. .LP
  1273. .sp
  1274. To add a single resource entry that is specified as a string that contains
  1275. both a name and a value, use
  1276. .PN XrmPutLineResource .
  1277. .IN "XrmPutLineResource" "" "@DEF@"
  1278. .\" Start marker code here
  1279. .FD 0
  1280. void XrmPutLineResource\^(\^\fIdatabase\fP, \fIline\fP\^)
  1281. .br
  1282.      XrmDatabase *\fIdatabase\fP\^;
  1283. .br
  1284.      char *\fIline\fP\^;
  1285. .FN
  1286. .IP \fIdatabase\fP 1i
  1287. Specifies the resource database.
  1288. .IP \fIline\fP 1i
  1289. Specifies the resource name and value pair as a single string.
  1290. .\" End marker code here
  1291. .LP
  1292. If database contains NULL,
  1293. .PN XrmPutLineResource
  1294. creates a new database and returns a pointer to it.
  1295. .PN XrmPutLineResource
  1296. adds a single resource entry to the specified database.
  1297. The line must be in valid ResourceLine format (see section 15.1).
  1298. The string is parsed in the locale of the database.
  1299. If the
  1300. .PN ResourceName
  1301. is not in the Host Portable Character Encoding
  1302. the result is implementation dependent.
  1303. Note that comment lines are not stored.
  1304. .NH 2
  1305. Enumerating Database Entries
  1306. .XS
  1307. \*(SN Enumerating Database Entries
  1308. .XE
  1309. .LP
  1310. To enumerate the entries of a database, use
  1311. .PN XrmEnumerateDatabase .
  1312. .IN "XrmEnumerateDatabase" "" "@DEF@"
  1313. .\" Start marker code here
  1314. .FD 0
  1315. .TS
  1316. lw(.5i) lw(2i) lw(2.5i).
  1317. T{
  1318. #define
  1319. T}    T{
  1320. .PN XrmEnumAllLevels
  1321. T}    T{
  1322. 0
  1323. T}
  1324. T{
  1325. #define
  1326. T}    T{
  1327. .PN XrmEnumOneLevel
  1328. T}    T{
  1329. 1
  1330. T}
  1331. .TE
  1332. .sp
  1333. Bool XrmEnumerateDatabase\^(\^\fIdatabase\fP, \fIname_prefix\fP, \fIclass_prefix\fP, \fImode\fP, \fIproc\fP, \fIarg\fP\^)
  1334. .br
  1335.       XrmDatabase \fIdatabase\fP\^;
  1336. .br
  1337.       XrmNameList \fIname_prefix\fP\^;
  1338. .br
  1339.       XrmClassList \fIclass_prefix\fP\^;
  1340. .br
  1341.       int \fImode\fP\^;
  1342. .br
  1343.       Bool (\^*\fIproc\fP\^)\^(\^)\^;
  1344. .br
  1345.       XPointer \fIarg\fP\^;
  1346. .FN
  1347. .IP \fIdatabase\fP 1i
  1348. Specifies the resource database.
  1349. .IP \fIname_prefix\fP 1i
  1350. Specifies the resource name prefix.
  1351. .IP \fIclass_prefix\fP 1i
  1352. Specifies the resource class prefix.
  1353. .IP \fImode\fP 1i
  1354. Specifies the number of levels to enumerate.
  1355. .IP \fIproc\fP 1i
  1356. Specifies the procedure that is to be called for each matching entry.
  1357. .IP \fIarg\fP 1i
  1358. Specifies the user-supplied argument that will be passed to the procedure.
  1359. .\" End marker code here
  1360. .LP
  1361. The
  1362. .PN XrmEnumerateDatabase
  1363. function calls the specified procedure for each resource in the database
  1364. that would match some completion of the given name/class resource prefix.
  1365. The order in which resources are found is implementation-dependent.
  1366. If mode is
  1367. .PN XrmEnumOneLevel ,
  1368. then a resource must match the given name/class prefix with
  1369. just a single name and class appended.  If mode is
  1370. .PN XrmEnumAllLevels ,
  1371. the resource must match the given name/class prefix with one or more names and
  1372. classes appended.
  1373. If the procedure returns
  1374. .PN True ,
  1375. the enumeration terminates and the function returns
  1376. .PN True . 
  1377. If the procedure always returns
  1378. .PN False ,
  1379. all matching resources are enumerated and the function returns
  1380. .PN False .
  1381. .LP
  1382. The procedure is called with the following arguments:
  1383. .LP
  1384. .\" Start marker code here
  1385. .Ds 0
  1386. .TA .5i 3i
  1387. .ta .5i 3i
  1388. (*\fIproc\fP\^)(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \fItype\fP, \fIvalue\fP, \fIarg\fP\^)
  1389.     XrmDatabase *\fIdatabase\fP\^;
  1390.     XrmBindingList \fIbindings\fP\^;
  1391.     XrmQuarkList \fIquarks\fP\^;
  1392.     XrmRepresentation *\fItype\fP\^;
  1393.     XrmValue *\fIvalue\fP\^;
  1394.     XPointer \fIclosure\fP\^;
  1395. .De
  1396. .\" End marker code here
  1397. .LP
  1398. The bindings and quarks lists are terminated by
  1399. .PN NULLQUARK .
  1400. Note that pointers
  1401. to the database and type are passed, but these values should not be modified.
  1402. .NH 2
  1403. Parsing Command Line Options
  1404. .XS
  1405. \*(SN Parsing Command Line Options 
  1406. .XE
  1407. .LP
  1408. The
  1409. .PN XrmParseCommand
  1410. function can be used to parse the command line arguments to a program
  1411. and modify a resource database with selected entries from the command line.
  1412. .LP
  1413. .IN "XrmOptionKind" "" "@DEF@"
  1414. .\" Start marker code here
  1415. .Ds 0
  1416. .TA .5i 2.5i
  1417. .ta .5i 2.5i
  1418. typedef enum {
  1419.     XrmoptionNoArg,    /* Value is specified in XrmOptionDescRec.value */
  1420.     XrmoptionIsArg,    /* Value is the option string itself */
  1421.     XrmoptionStickyArg,    /* Value is characters immediately following option */
  1422.     XrmoptionSepArg,    /* Value is next argument in argv */
  1423.     XrmoptionResArg,    /* Resource and value in next argument in argv */
  1424.     XrmoptionSkipArg,    /* Ignore this option and the next argument in argv */
  1425.     XrmoptionSkipLine,    /* Ignore this option and the rest of argv */
  1426.     XrmoptionSkipNArgs    /* Ignore this option and the next
  1427.         \ \ \ XrmOptionDescRec.value arguments in argv */
  1428. } XrmOptionKind;
  1429. .De
  1430. .\" End marker code here
  1431. .LP
  1432. Note that
  1433. .PN XrmoptionSkipArg
  1434. is equivalent to 
  1435. .PN XrmoptionSkipNArgs
  1436. with the
  1437. .PN XrmOptionDescRec.value
  1438. field containing the value one.
  1439. Note also that the value zero for
  1440. .PN XrmoptionSkipNArgs
  1441. indicates that only the option itself is to be skipped.
  1442. .LP
  1443. .IN "XrmOptionDescRec" "" "@DEF@"
  1444. .\" Start marker code here
  1445. .Ds 0
  1446. .TA .5i 2.5i
  1447. .ta .5i 2.5i
  1448. typedef struct {
  1449.     char *option;    /* Option specification string in argv            */
  1450.     char *specifier;    /* Binding and resource name (sans application name)    */
  1451.     XrmOptionKind argKind;    /* Which style of option it is        */
  1452.     XPointer value;    /* Value to provide if XrmoptionNoArg or 
  1453.         \ \ \ XrmoptionSkipNArgs   */
  1454. } XrmOptionDescRec, *XrmOptionDescList;
  1455. .De
  1456. .\" End marker code here
  1457. .LP
  1458. .sp
  1459. To load a resource database from a C command line, use
  1460. .PN XrmParseCommand .
  1461. .IN "XrmParseCommand" "" "@DEF@"
  1462. .\" Start marker code here
  1463. .FD 0
  1464. void XrmParseCommand\^(\^\fIdatabase\fP\^, \^\fItable\fP\^, \^\fItable_count\fP\^, \
  1465. \^\fIname\fP\^, \^\fIargc_in_out\fP\^, \^\fIargv_in_out\fP\^)
  1466. .br
  1467.       XrmDatabase *\fIdatabase\fP\^;
  1468. .br
  1469.       XrmOptionDescList \fItable\fP\^;
  1470. .br
  1471.       int \fItable_count\fP\^;
  1472. .br
  1473.       char *\fIname\fP\^;
  1474. .br
  1475.       int *\fIargc_in_out\fP\^;
  1476. .br
  1477.       char **\fIargv_in_out\fP\^;
  1478. .FN
  1479. .IP \fIdatabase\fP 1i
  1480. Specifies the resource database.
  1481. .IP \fItable\fP 1i
  1482. Specifies the table of command line arguments to be parsed.
  1483. .IP \fItable_count\fP 1i
  1484. Specifies the number of entries in the table.
  1485. .\" $Header: parname.a,v 1.1 88/02/26 10:30:16 mento Exp $
  1486. .IP \fIname\fP 1i
  1487. Specifies the application name.
  1488. .IP \fIargc_in_out\fP 1i
  1489. Specifies the number of arguments and returns the number of remaining arguments.
  1490. .IP \fIargv_in_out\fP 1i
  1491. Specifies the command line arguments
  1492. and returns the remaining arguments.
  1493. .\" End marker code here
  1494. .LP
  1495. .\" $Header: XrmParse.d,v 1.7 88/08/20 10:49:05 mento Exp $
  1496. The
  1497. .PN XrmParseCommand
  1498. function parses an (argc, argv) pair according to the specified option table,
  1499. loads recognized options into the specified database with type ``String,''
  1500. and modifies the (argc, argv) pair to remove all recognized options.
  1501. If database contains NULL,
  1502. .PN XrmParseCommand
  1503. creates a new database and returns a pointer to it.
  1504. Otherwise, entries are added to the database specified.
  1505. If a database is created, it is created in the current locale.
  1506. .LP
  1507. The specified table is used to parse the command line.
  1508. Recognized options in the table are removed from argv,
  1509. and entries are added to the specified resource database.
  1510. The table entries contain information on the option string,
  1511. the option name, the style of option, 
  1512. and a value to provide if the option kind is 
  1513. .PN XrmoptionNoArg .
  1514. The option names are compared byte-for-byte to arguments in argv,
  1515. independent of any locale.
  1516. The resource values given in the table are stored in the resource database
  1517. without modification.
  1518. All resource database entries are created
  1519. using a ``String'' representation type.
  1520. The argc argument specifies the number of arguments in argv
  1521. and is set on return to the remaining number of arguments that were not parsed.
  1522. The name argument should be the name of your application
  1523. for use in building the database entry.
  1524. The name argument is prefixed to the resourceName in the option table
  1525. before storing a database entry.
  1526. No separating (binding) character is inserted,
  1527. so the table must contain either a period (.) or an asterisk (*)
  1528. as the first character in each resourceName entry.
  1529. To specify a more completely qualified resource name,
  1530. the resourceName entry can contain multiple components.
  1531. If the name argument and the resourceNames are not in the
  1532. Host Portable Character Encoding the result is implementation dependent.
  1533. .LP
  1534. The following provides a sample option table:
  1535. .LP
  1536. .Ds 0
  1537. .TA 1.25i 3.25i 4.75i
  1538. .ta 1.25i 3.25i 4.75i
  1539. static XrmOptionDescRec opTable[] = {
  1540. {"\-background",    "*background",    XrmoptionSepArg,    (XPointer) NULL},
  1541. {"\-bd",    "*borderColor",    XrmoptionSepArg,    (XPointer) NULL},
  1542. {"\-bg",    "*background",    XrmoptionSepArg,    (XPointer) NULL},
  1543. {"\-borderwidth",    "*TopLevelShell.borderWidth",    XrmoptionSepArg,    (XPointer) NULL},
  1544. {"\-bordercolor",    "*borderColor",    XrmoptionSepArg,    (XPointer) NULL},
  1545. {"\-bw",    "*TopLevelShell.borderWidth",    XrmoptionSepArg,    (XPointer) NULL},
  1546. {"\-display",    ".display",    XrmoptionSepArg,    (XPointer) NULL},
  1547. {"\-fg",    "*foreground",    XrmoptionSepArg,    (XPointer) NULL},
  1548. {"\-fn",    "*font",    XrmoptionSepArg,    (XPointer) NULL},
  1549. {"\-font",    "*font",    XrmoptionSepArg,    (XPointer) NULL},
  1550. {"\-foreground",    "*foreground",    XrmoptionSepArg,    (XPointer) NULL},
  1551. {"\-geometry",    ".TopLevelShell.geometry",    XrmoptionSepArg,    (XPointer) NULL},
  1552. {"\-iconic",    ".TopLevelShell.iconic",    XrmoptionNoArg,    (XPointer) "on"},
  1553. {"\-name",    ".name",    XrmoptionSepArg,    (XPointer) NULL},
  1554. {"\-reverse",    "*reverseVideo",    XrmoptionNoArg,    (XPointer) "on"},
  1555. {"\-rv",    "*reverseVideo",    XrmoptionNoArg,    (XPointer) "on"},
  1556. {"\-synchronous",    "*synchronous",    XrmoptionNoArg,    (XPointer) "on"},
  1557. {"\-title",    ".TopLevelShell.title",    XrmoptionSepArg,    (XPointer) NULL},
  1558. {"\-xrm",    NULL,    XrmoptionResArg,    (XPointer) NULL},
  1559. };
  1560. .De
  1561. .LP
  1562. In this table, if the \-background (or \-bg) option is used to set
  1563. background colors, the stored resource specifier matches all
  1564. resources of attribute background.  
  1565. If the \-borderwidth option is used, 
  1566. the stored resource specifier applies only to border width
  1567. attributes of class TopLevelShell (that is, outer-most windows, including
  1568. pop-up windows).  
  1569. If the \-title option is used to set a window name,
  1570. only the topmost application windows receive the resource.
  1571. .LP
  1572. When parsing the command line,
  1573. any unique unambiguous abbreviation for an option name in the table is 
  1574. considered a match for the option.
  1575. Note that uppercase and lowercase matter.
  1576. .bp
  1577.