<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="resource_manager_functions">
<title>Resource Manager Functions</title>
<!-- .sp 2 -->
<!-- .nr H1 15 -->
<!-- .nr H2 0 -->
<!-- .nr H3 0 -->
<!-- .nr H4 0 -->
<!-- .nr H5 0 -->
<!-- .na -->
<para>
<!-- .LP -->
<!-- .XS -->
<!-- Chapter 15: Resource Manager Functions -->
<!-- .XE -->
A program often needs a variety of options in the X environment
(for example, fonts, colors, icons, and cursors).
Specifying all of these options on the command line is awkward
because users may want to customize many aspects of the program
and need a convenient way to establish these customizations as
the default settings.
The resource manager is provided for this purpose.
Resource specifications are usually stored in human-readable files
and in server properties.
</para>
<para>
<!-- .LP -->
The resource manager is a database manager with a twist.
In most database systems,
you perform a query using an imprecise specification,
and you get back a set of records.
The resource manager, however, allows you to specify a large
set of values with an imprecise specification, to query the database
with a precise specification, and to get back only a single value.
This should be used by applications that need to know what the
user prefers for colors, fonts, and other resources.
It is this use as a database for dealing with X resources that
inspired the name "Resource Manager,"
although the resource manager can be and is used in other ways.
</para>
<para>
<!-- .LP -->
For example,
a user of your application may want to specify
that all windows should have a blue background
but that all mail-reading windows should have a red background.
With well-engineered and coordinated applications,
a user can define this information using only two lines of specifications.
</para>
<para>
<!-- .LP -->
As an example of how the resource manager works,
consider a mail-reading application called xmh.
Assume that it is designed so that it uses a
complex window hierarchy all the way down to individual command buttons,
which may be actual small subwindows in some toolkits.
These are often called objects or widgets.
In such toolkit systems,
each user interface object can be composed of other objects
and can be assigned a name and a class.
Fully qualified names or classes can have arbitrary numbers of component names,
but a fully qualified name always has the same number of component names as a
fully qualified class.
This generally reflects the structure of the application as composed
of these objects, starting with the application itself.
</para>
<para>
<!-- .LP -->
For example, the xmh mail program has a name "xmh" and is one
of a class of "Mail" programs.
By convention, the first character of class components is capitalized,
and the first letter of name components is in lowercase.
Each name and class finally has an attribute
(for example, "foreground" or "font").
If each window is properly assigned a name and class,
it is easy for the user to specify attributes of any portion
of the application.
</para>
<para>
<!-- .LP -->
At the top level,
the application might consist of a paned window (that is, a window divided
into several sections) named "toc".
One pane of the paned window is a button box window named "buttons"
and is filled with command buttons.
One of these command buttons is used to incorporate
new mail and has the name "incorporate".
This window has a fully qualified name, "xmh.toc.buttons.incorporate",
and a fully qualified class, "Xmh.Paned.Box.Command".
Its fully qualified name is the name of its parent, "xmh.toc.buttons",
followed by its name, "incorporate".
Its class is the class of its parent, "Xmh.Paned.Box",
followed by its particular class, "Command".
The fully qualified name of a resource is
the attribute's name appended to the object's fully qualified
name, and the fully qualified class is its class appended to the object's
class.
</para>
<para>
<!-- .LP -->
The incorporate button might need the following resources:
Title string,
Font,
Foreground color for its inactive state,
Background color for its inactive state,
Foreground color for its active state, and
Background color for its active state.
Each resource is considered
to be an attribute of the button and, as such, has a name and a class.
For example, the foreground color for the button in
its active state might be named "activeForeground",
and its class might be "Foreground".
</para>
<para>
<!-- .LP -->
When an application looks up a resource (for example, a color),
it passes the complete name and complete class of the resource
to a look-up routine.
The resource manager compares this complete specification
against the incomplete specifications of entries in the resource
database, finds the best match, and returns the corresponding
value for that entry.
</para>
<para>
<!-- .LP -->
The definitions for the resource manager are contained in
<filename class="headerfile"><X11/Xresource.h></filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xresource.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xresource.h></filename></secondary></indexterm>
</para>
<sect1 id="Resource_File_Syntax">
<title>Resource File Syntax</title>
<!-- .XS -->
<!-- (SN Resource File Syntax -->
<!-- .XE -->
<para>
<!-- .LP -->
The syntax of a resource file is a sequence of resource lines
terminated by newline characters or the end of the file.
The syntax of an individual resource line is:
</para>
<para>
<!-- .LP -->
<!-- .\" Start marker code here -->
<literallayout class="monospaced">
<!-- .TA 1.5i 1.75i -->
<!-- .ta 1.5i 1.75i -->
ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
Comment = "!" {<any character except null or newline>}
IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
FileName = <valid filename for operating system>
ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
ResourceName = [Binding] {Component Binding} ComponentName
Binding = "." | "*"
WhiteSpace = {<space> | <horizontal tab>}
Component = "?" | ComponentName
ComponentName = NameChar {NameChar}
NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
Value = {<any character except null or unescaped newline>}
</literallayout>
<!-- .\" End marker code here -->
</para>
<para>
<!-- .LP -->
Elements separated by vertical bar (|) are alternatives.
Curly braces ({......}) indicate zero or more repetitions
of the enclosed elements.
Square brackets ([......]) indicate that the enclosed element is optional.
Quotes ("......") are used around literal characters.
</para>
<para>
<!-- .LP -->
IncludeFile lines are interpreted by replacing the line with the
contents of the specified file.
The word "include" must be in lowercase.
The file name is interpreted relative to the directory of the file in
which the line occurs (for example, if the file name contains no
directory or contains a relative directory specification).
</para>
<para>
<!-- .LP -->
If a ResourceName contains a contiguous sequence of two or more Binding
characters, the sequence will be replaced with a single ".." character
if the sequence contains only ".." characters;
otherwise, the sequence will be replaced with a single "*" character.
</para>
<para>
<!-- .LP -->
A resource database never contains more than one entry for a given
ResourceName. If a resource file contains multiple lines with the
same ResourceName, the last line in the file is used.
</para>
<para>
<!-- .LP -->
Any white space characters before or after the name or colon in a ResourceSpec
are ignored.
To allow a Value to begin with white space,
the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)
is recognized and replaced by a space character,
and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"
(backslash followed by horizontal tab)
is recognized and replaced by a horizontal tab character.
To allow a Value to contain embedded newline characters,
the two-character sequence "\\n" is recognized and replaced by a
newline character.
To allow a Value to be broken across multiple lines in a text file,
the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"
(backslash followed by newline) is
recognized and removed from the value.
To allow a Value to contain arbitrary character codes,
the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",
where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",
is recognized and replaced with a single byte that contains
the octal value specified by the sequence.
Finally, the two-character sequence "\newline" is recognized
and replaced with a single backslash.
</para>
<para>
<!-- .LP -->
As an example of these sequences,
the following resource line contains a value consisting of four
characters: a backslash, a null, a "z", and a newline:
<literallayout class="monospaced">
magic.values: \\000\
z\n
</literallayout>
</para>
</sect1>
<sect1 id="Resource_Manager_Matching_Rules">
<title>Resource Manager Matching Rules</title>
<!-- .XS -->
<!-- (SN Resource Manager Matching Rules -->
<!-- .XE -->
<para>
<!-- .LP -->
The algorithm for determining which resource database entry
matches a given query is the heart of the resource manager.
All queries must fully specify the name and class of the desired resource
(use of the characters "*" and "?" is not permitted).
The library supports up to 100 components in a full name or class.
Resources are stored in the database with only partially specified
names and classes, using pattern matching constructs.
An asterisk (*) is a loose binding and is used to represent any number
of intervening components, including none.
A period (.) is a tight binding and is used to separate immediately
adjacent components.
A question mark (?) is used to match any single component name or class.
A database entry cannot end in a loose binding;
the final component (which cannot be the character "?") must be specified.
The lookup algorithm searches the database for the entry that most
closely matches (is most specific for) the full name and class being queried.
When more than one database entry matches the full name and class,
precedence rules are used to select just one.
</para>
<para>
<!-- .LP -->
The full name and class are scanned from left to right (from highest
level in the hierarchy to lowest), one component at a time.
At each level, the corresponding component and/or binding of each
matching entry is determined, and these matching components and
bindings are compared according to precedence rules.
Each of the rules is applied at each level before moving to the next level,
until a rule selects a single entry over all others.
The rules, in order of precedence, are:
</para>
<itemizedlist>
<listitem>
<para>
An entry that contains a matching component (whether name, class,
or the character "?")
takes precedence over entries that elide the level (that is, entries
that match the level in a loose binding).
</para>
</listitem>
<listitem>
<para>
An entry with a matching name takes precedence over both
entries with a matching class and entries that match using the character "?".
An entry with a matching class takes precedence over
entries that match using the character "?".
</para>
</listitem>
<listitem>
<para>
An entry preceded by a tight binding takes precedence over entries
preceded by a loose binding.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
To illustrate these rules,
consider the following resource database entries:
<literallayout class="monospaced">
<!-- .TA 2.5i 3.5i -->
<!-- .ta 2.5i 3.5i -->
xmh*Paned*activeForeground: red <emphasis remap='I'>(entry A)</emphasis>
*incorporate.Foreground: blue <emphasis remap='I'>(entry B)</emphasis>
xmh.toc*Command*activeForeground: green <emphasis remap='I'>(entry C)</emphasis>
xmh.toc*?.Foreground: white <emphasis remap='I'>(entry D)</emphasis>
xmh.toc*Command.activeForeground: black <emphasis remap='I'>(entry E)</emphasis>
</literallayout>
</para>
<para>
<!-- .LP -->
Consider a query for the resource:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA 3.5i -->
<!-- .ta 3.5i -->
xmh.toc.messagefunctions.incorporate.activeForeground <emphasis remap='I'>(name)</emphasis>
Xmh.Paned.Box.Command.Foreground <emphasis remap='I'>(class)</emphasis>
</literallayout>
</para>
<para>
<!-- .LP -->
At the first level (xmh, Xmh), rule 1 eliminates entry B.
At the second level (toc, Paned), rule 2 eliminates entry A.
At the third level (messagefunctions, Box), no entries are eliminated.
At the fourth level (incorporate, Command), rule 2 eliminates entry D.
At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
</para>
</sect1>
<sect1 id="Quarks">
<title>Quarks</title>
<!-- .XS -->
<!-- (SN Quarks -->
<!-- .XE -->
<para>
<!-- .LP -->
Most uses of the resource manager involve defining names,
classes, and representation types as string constants.
However, always referring to strings in the resource manager can be slow,
because it is so heavily used in some toolkits.
To solve this problem,
a shorthand for a string is used in place of the string
in many of the resource manager functions.
Simple comparisons can be performed rather than string comparisons.
The shorthand name for a string is called a quark and is the
type
<type>XrmQuark</type>.
On some occasions,
you may want to allocate a quark that has no string equivalent.
</para>
<para>
<!-- .LP -->
A quark is to a string what an atom is to a string in the server,
but its use is entirely local to your application.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate a new quark, use
<function>XrmUniqueQuark</function>.
</para>
<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>
<!-- .sM -->
<para>XrmQuark XrmUniqueQuark()</para>
<!-- .FN -->
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmUniqueQuark</function>
function allocates a quark that is guaranteed not to represent any string that
is known to the resource manager.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
Each name, class, and representation type is typedef'd as an
<type>XrmQuark</type>.
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
#define NULLQUARK ((XrmQuark) 0)
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
Lists are represented as null-terminated arrays of quarks.
The size of the array must be large enough for the number of components used.
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
To convert a string to a quark, use
<function>XrmStringToQuark</function>
or
<function>XrmPermStringToQuark</function>.
</para>
<literallayout class="monospaced">
#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)
</literallayout>
<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>
<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>
<paramdef>char<parameter> *string</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<!-- .ds Ql -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the string for which a quark(Ql is to be allocated.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
These functions can be used to convert from string to quark representation.
If the string is not in the Host Portable Character Encoding,
the conversion is implementation-dependent.
The string argument to
<function>XrmStringToQuark</function>
need not be permanently allocated storage.
<function>XrmPermStringToQuark</function>
is just like
<function>XrmStringToQuark</function>,
except that Xlib is permitted to assume the string argument is permanently
allocated,
and, hence, that it can be used as the value to be returned by
<function>XrmQuarkToString</function>.
</para>
<para>
<!-- .LP -->
For any given quark, if
<function>XrmStringToQuark</function>
returns a non-NULL value,
all future calls will return the same value (identical address).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To convert a quark to a string, use
<function>XrmQuarkToString</function>.
</para>
<literallayout class="monospaced">
#define XrmNameToString(name) XrmQuarkToString(name)
#define XrmClassToString(class) XrmQuarkToString(name)
#define XrmRepresentationToString(type) XrmQuarkToString(type)
</literallayout>
<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XrmQuarkToString</function></funcdef>
<paramdef>XrmQuark<parameter> quark</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>quark</emphasis>
</term>
<listitem>
<para>
Specifies the quark for which the equivalent string is desired.
</para>
</listitem>
</varlistentry>
</variablelist>
<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->
<para>
These functions can be used to convert from quark representation to string.
The string pointed to by the return value must not be modified or freed.
The returned string is byte-for-byte equal to the original
string passed to one of the string-to-quark routines.
If no string exists for that quark,
<function>XrmQuarkToString</function>
returns NULL.
For any given quark, if
<function>XrmQuarkToString</function>
returns a non-NULL value,
all future calls will return the same value (identical address).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To convert a string with one or more components to a quark list, use
<function>XrmStringToQuarkList</function>.
</para>
<literallayout class="monospaced">
#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name))
#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
</literallayout>
<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmStringToQuarkList</function></funcdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<!-- .ds Ql \ list -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the string for which a quark(Ql is to be allocated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quarks_return</emphasis>
</term>
<listitem>
<para>
Returns the list of quarks.
The caller must allocate sufficient space for the quarks list before calling
<function>XrmStringToQuarkList</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmStringToQuarkList</function>
function converts the null-terminated string (generally a fully qualified name)
to a list of quarks.
Note that the string must be in the valid ResourceName format
(see section 15.1).
If the string is not in the Host Portable Character Encoding,
the conversion is implementation-dependent.
</para>
<para>
<!-- .LP -->
A binding list is a list of type
<type>XrmBindingList</type>
and indicates if components of name or class lists are bound tightly or loosely
(that is, if wildcarding of intermediate components is specified).
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
</literallayout>
</para>
<para>
<!-- .LP -->
<constant>XrmBindTightly</constant>
indicates that a period separates the components, and
<constant>XrmBindLoosely</constant>
indicates that an asterisk separates the components.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To convert a string with one or more components to a binding list
and a quark list, use
<function>XrmStringToBindingQuarkList</function>.
<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef><function>XrmStringToBindingQuarkList</function></funcdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>
<paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<!-- .ds Ql \ list -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the string for which a quark(Ql is to be allocated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>bindings_return</emphasis>
</term>
<listitem>
<para>
Returns the binding list.
The caller must allocate sufficient space for the binding list before calling
<function>XrmStringToBindingQuarkList</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quarks_return</emphasis>
</term>
<listitem>
<para>
Returns the list of quarks.
The caller must allocate sufficient space for the quarks list before calling
<function>XrmStringToBindingQuarkList</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
Component names in the list are separated by a period or
an asterisk character.
The string must be in the format of a valid ResourceName (see section 15.1).
If the string does not start with a period or an asterisk,
a tight binding is assumed.
For example, the string ``*a.b*c'' becomes:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .75i 1.5i 2.25i -->
<!-- .ta .75i 1.5i 2.25i -->
quarks: a b c
bindings: loose tight loose
</literallayout>
</para>
</sect1>
<sect1 id="Creating_and_Storing_Databases">
<title>Creating and Storing Databases</title>
<!-- .XS -->
<!-- (SN Creating and Storing Databases -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>
A resource database is an opaque type,
<type>XrmDatabase</type>.
Each database value is stored in an
<type>XrmValue</type>
structure.
This structure consists of a size, an address, and a representation type.
The size is specified in bytes.
The representation type is a way for you to store data tagged by some
application-defined type (for example, the strings ``font'' or ``color'').
It has nothing to do with the C data type or with its class.
The
<type>XrmValue</type>
structure is defined as:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
To initialize the resource manager, use
<function>XrmInitialize</function>.
<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmInitialize</function></funcdef>
<paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
</para>
<para>
<!-- .LP -->
<!-- .eM -->
To retrieve a database from disk, use
<function>XrmGetFileDatabase</function>.
<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XrmDatabase <function>XrmGetFileDatabase</function></funcdef>
<paramdef>char<parameter> *filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>filename</emphasis>
</term>
<listitem>
<para>
Specifies the resource database file name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmGetFileDatabase</function>
function opens the specified file,
creates a new resource database, and loads it with the specifications
read in from the specified file.
The specified file should contain a sequence of entries in valid ResourceLine
format (see section 15.1); the database that results from reading a file
with incorrect syntax is implementation-dependent.
The file is parsed in the current locale,
and the database is created in the current locale.
If it cannot open the specified file,
<function>XrmGetFileDatabase</function>
returns NULL.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To store a copy of a database to disk, use
<function>XrmPutFileDatabase</function>.
<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmPutFileDatabase</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
<paramdef>char<parameter> *stored_db</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the database that is to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>stored_db</emphasis>
</term>
<listitem>
<para>
Specifies the file name for the stored database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmPutFileDatabase</function>
function stores a copy of the specified database in the specified file.
Text is written to the file as a sequence of entries in valid
ResourceLine format (see section 15.1).
The file is written in the locale of the database.
Entries containing resource names that are not in the Host Portable Character
Encoding or containing values that are not in the encoding of the database
locale, are written in an implementation-dependent manner.
The order in which entries are written is implementation-dependent.
Entries with representation types other than ``String'' are ignored.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain a pointer to the screen-independent resources of a display, use
<function>XResourceManagerString</function>.
<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XResourceManagerString</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XResourceManagerString</function>
function returns the RESOURCE_MANAGER property from the server's root
window of screen zero, which was returned when the connection was opened using
<function>XOpenDisplay</function>.
The property is converted from type STRING to the current locale.
The conversion is identical to that produced by
<function>XmbTextPropertyToTextList</function>
for a single element STRING property.
The returned string is owned by Xlib and should not be freed by the client.
The property value must be in a format that is acceptable to
<function>XrmGetStringDatabase</function>.
If no property exists, NULL is returned.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain a pointer to the screen-specific resources of a screen, use
<function>XScreenResourceString</function>.
<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XScreenResourceString</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the screen.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XScreenResourceString</function>
function returns the SCREEN_RESOURCES property from the root window of the
specified screen.
The property is converted from type STRING to the current locale.
The conversion is identical to that produced by
<function>XmbTextPropertyToTextList</function>
for a single element STRING property.
The property value must be in a format that is acceptable to
<function>XrmGetStringDatabase</function>.
If no property exists, NULL is returned.
The caller is responsible for freeing the returned string by using
<function>XFree</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To create a database from a string, use
<function>XrmGetStringDatabase</function>.
<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XrmDatabase <function>XrmGetStringDatabase</function></funcdef>
<paramdef>char<parameter> *data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>data</emphasis>
</term>
<listitem>
<para>
Specifies the database contents using a string.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmGetStringDatabase</function>
function creates a new database and stores the resources specified
in the specified null-terminated string.
<function>XrmGetStringDatabase</function>
is similar to
<function>XrmGetFileDatabase</function>
except that it reads the information out of a string instead of out of a file.
The string should contain a sequence of entries in valid ResourceLine
format (see section 15.1) terminated by a null character;
the database that results from using a string
with incorrect syntax is implementation-dependent.
The string is parsed in the current locale,
and the database is created in the current locale.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the locale name of a database, use
<function>XrmLocaleOfDatabase</function>.
<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XrmLocaleOfDatabase</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmLocaleOfDatabase</function>
function returns the name of the locale bound to the specified
database, as a null-terminated string.
The returned locale name string is owned by Xlib and should not be
modified or freed by the client.
Xlib is not permitted to free the string until the database is destroyed.
Until the string is freed,
it will not be modified by Xlib.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To destroy a resource database and free its allocated memory, use
<function>XrmDestroyDatabase</function>.
<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmDestroyDatabase</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If database is NULL,
<function>XrmDestroyDatabase</function>
returns immediately.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To associate a resource database with a display, use
<function>XrmSetDatabase</function>.
<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmSetDatabase</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmSetDatabase</function>
function associates the specified resource database (or NULL)
with the specified display.
The database previously associated with the display (if any) is not destroyed.
A client or toolkit may find this function convenient for retaining a database
once it is constructed.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To get the resource database associated with a display, use
<function>XrmGetDatabase</function>.
<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XrmDatabase <function>XrmGetDatabase</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmGetDatabase</function>
function returns the database associated with the specified display.
It returns NULL if a database has not yet been set.
</para>
</sect1>
<sect1 id="Merging_Resource_Databases">
<title>Merging Resource Databases</title>
<!-- .XS -->
<!-- (SN Merging Resource Databases -->
<!-- .XE -->
<para>
<!-- .LP -->
To merge the contents of a resource file into a database, use
<function>XrmCombineFileDatabase</function>.
<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XrmCombineFileDatabase</function></funcdef>
<paramdef>char<parameter> *filename</parameter></paramdef>
<paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>
<paramdef>Bool<parameter> override</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>filename</emphasis>
</term>
<listitem>
<para>
Specifies the resource database file name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>target_db</emphasis>
</term>
<listitem>
<para>
Specifies the resource database into which the source
database is to be merged.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>override</emphasis>
</term>
<listitem>
<para>
Specifies whether source entries override target ones.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmCombineFileDatabase</function>
function merges the contents of a resource file into a database.
If the same specifier is used for an entry in both the file and
the database,
the entry in the file will replace the entry in the database
if override is
<symbol>True</symbol>;
otherwise, the entry in the file is discarded.
The file is parsed in the current locale.
If the file cannot be read,
a zero status is returned;
otherwise, a nonzero status is returned.
If target_db contains NULL,
<function>XrmCombineFileDatabase</function>
creates and returns a new database to it.
Otherwise, the database pointed to by target_db is not destroyed by the merge.
The database entries are merged without changing values or types,
regardless of the locale of the database.
The locale of the target database is not modified.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To merge the contents of one database into another database, use
<function>XrmCombineDatabase</function>.
<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmCombineDatabase</function></funcdef>
<paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
<paramdef>Bool<parameter> override</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>source_db</emphasis>
</term>
<listitem>
<para>
Specifies the resource database that is to be merged into the target database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>target_db</emphasis>
</term>
<listitem>
<para>
Specifies the resource database into which the source
database is to be merged.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>override</emphasis>
</term>
<listitem>
<para>
Specifies whether source entries override target ones.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmCombineDatabase</function>
function merges the contents of one database into another.
If the same specifier is used for an entry in both databases,
the entry in the source_db will replace the entry in the target_db
if override is
<symbol>True</symbol>;
otherwise, the entry in source_db is discarded.
If target_db contains NULL,
<function>XrmCombineDatabase</function>
simply stores source_db in it.
Otherwise, source_db is destroyed by the merge, but the database pointed
to by target_db is not destroyed.
The database entries are merged without changing values or types,
regardless of the locales of the databases.
The locale of the target database is not modified.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To merge the contents of one database into another database with override
semantics, use
<function>XrmMergeDatabases</function>.
<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmMergeDatabases</function></funcdef>
<paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>source_db</emphasis>
</term>
<listitem>
<para>
Specifies the resource database that is to be merged into the target database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>target_db</emphasis>
</term>
<listitem>
<para>
Specifies the resource database into which the source
database is to be merged.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
Calling the
<function>XrmMergeDatabases</function>
function is equivalent to calling the
<function>XrmCombineDatabase</function>
function with an override argument of
<symbol>True</symbol>.
</para>
</sect1>
<sect1 id="Looking_Up_Resources">
<title>Looking Up Resources</title>
<!-- .XS -->
<!-- (SN Looking Up Resources -->
<!-- .XE -->
<para>
<!-- .LP -->
To retrieve a resource from a resource database, use
<function>XrmGetResource</function>,
<function>XrmQGetResource</function>,
or
<function>XrmQGetSearchResource</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XrmGetResource</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
<paramdef>char<parameter> *str_name</parameter></paramdef>
<paramdef>char<parameter> *str_class</parameter></paramdef>
<paramdef>char<parameter> **str_type_return</parameter></paramdef>
<paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the database that is to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>str_name</emphasis>
</term>
<listitem>
<para>
Specifies the fully qualified name of the value being retrieved (as a string).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>str_class</emphasis>
</term>
<listitem>
<para>
Specifies the fully qualified class of the value being retrieved (as a string).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>str_type_return</emphasis>
</term>
<listitem>
<para>
Returns the representation type of the destination (as a string).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value_return</emphasis>
</term>
<listitem>
<para>
Returns the value in the database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XrmQGetResource</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
<paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>
<paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>
<paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>
<paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the database that is to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quark_name</emphasis>
</term>
<listitem>
<para>
Specifies the fully qualified name of the value being retrieved (as a quark).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quark_class</emphasis>
</term>
<listitem>
<para>
Specifies the fully qualified class of the value being retrieved (as a quark).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quark_type_return</emphasis>
</term>
<listitem>
<para>
Returns the representation type of the destination (as a quark).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value_return</emphasis>
</term>
<listitem>
<para>
Returns the value in the database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmGetResource</function>
and
<function>XrmQGetResource</function>
functions retrieve a resource from the specified database.
Both take a fully qualified name/class pair, a destination
resource representation, and the address of a value
(size/address pair).
The value and returned type point into database memory;
therefore, you must not modify the data.
</para>
<para>
<!-- .LP -->
The database only frees or overwrites entries on
<function>XrmPutResource</function>,
<function>XrmQPutResource</function>,
or
<function>XrmMergeDatabases</function>.
A client that is not storing new values into the database or
is not merging the database should be safe using the address passed
back at any time until it exits.
If a resource was found, both
<function>XrmGetResource</function>
and
<function>XrmQGetResource</function>
return
<symbol>True</symbol>;
otherwise, they return
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
Most applications and toolkits do not make random probes
into a resource database to fetch resources.
The X toolkit access pattern for a resource database is quite stylized.
A series of from 1 to 20 probes is made with only the
last name/class differing in each probe.
The
<function>XrmGetResource</function>
function is at worst a
2<superscript><emphasis remap='I'>n</emphasis></superscript> algorithm,
where <emphasis remap='I'>n</emphasis> is the length of the name/class list.
This can be improved upon by the application programmer by prefetching a list
of database levels that might match the first part of a name/class list.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain a list of database levels, use
<function>XrmQGetSearchList</function>.
<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
<paramdef>XrmNameList<parameter> names</parameter></paramdef>
<paramdef>XrmClassList<parameter> classes</parameter></paramdef>
<paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>
<paramdef>int<parameter> list_length</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the database that is to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>names</emphasis>
</term>
<listitem>
<para>
Specifies a list of resource names.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>classes</emphasis>
</term>
<listitem>
<para>
Specifies a list of resource classes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>list_return</emphasis>
</term>
<listitem>
<para>
Returns a search list for further use.
The caller must allocate sufficient space for the list before calling
<function>XrmQGetSearchList</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>list_length</emphasis>
</term>
<listitem>
<para>
Specifies the number of entries (not the byte size) allocated for list_return.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmQGetSearchList</function>
function takes a list of names and classes
and returns a list of database levels where a match might occur.
The returned list is in best-to-worst order and
uses the same algorithm as
<function>XrmGetResource</function>
for determining precedence.
If list_return was large enough for the search list,
<function>XrmQGetSearchList</function>
returns
<symbol>True</symbol>;
otherwise, it returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
The size of the search list that the caller must allocate is
dependent upon the number of levels and wildcards in the resource specifiers
that are stored in the database.
The worst case length is
3<superscript><emphasis remap='I'>n</emphasis></superscript>,
where <emphasis remap='I'>n</emphasis> is the number of name or class
components in names or classes.
</para>
<para>
<!-- .LP -->
When using
<function>XrmQGetSearchList</function>
followed by multiple probes for resources with a common name and class prefix,
only the common prefix should be specified in the name and class list to
<function>XrmQGetSearchList</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To search resource database levels for a given resource, use
<function>XrmQGetSearchResource</function>.
<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
<paramdef>XrmSearchList<parameter> list</parameter></paramdef>
<paramdef>XrmName<parameter> name</parameter></paramdef>
<paramdef>XrmClass<parameter> class</parameter></paramdef>
<paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>
<paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>list</emphasis>
</term>
<listitem>
<para>
Specifies the search list returned by
<function>XrmQGetSearchList</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>name</emphasis>
</term>
<listitem>
<para>
Specifies the resource name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>class</emphasis>
</term>
<listitem>
<para>
Specifies the resource class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>type_return</emphasis>
</term>
<listitem>
<para>
Returns data representation type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value_return</emphasis>
</term>
<listitem>
<para>
Returns the value in the database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmQGetSearchResource</function>
function searches the specified database levels for the resource
that is fully identified by the specified name and class.
The search stops with the first match.
<function>XrmQGetSearchResource</function>
returns
<symbol>True</symbol>
if the resource was found;
otherwise, it returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
A call to
<function>XrmQGetSearchList</function>
with a name and class list containing all but the last component
of a resource name followed by a call to
<function>XrmQGetSearchResource</function>
with the last component name and class returns the same database entry as
<function>XrmGetResource</function>
and
<function>XrmQGetResource</function>
with the fully qualified name and class.
</para>
</sect1>
<sect1 id="Storing_into_a_Resource_Database">
<title>Storing into a Resource Database</title>
<!-- .XS -->
<!-- (SN Storing into a Resource Database -->
<!-- .XE -->
<para>
<!-- .LP -->
To store resources into the database, use
<function>XrmPutResource</function>
or
<function>XrmQPutResource</function>.
Both functions take a partial resource specification, a
representation type, and a value.
This value is copied into the specified database.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmPutResource</function></funcdef>
<paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
<paramdef>char<parameter> *specifier</parameter></paramdef>
<paramdef>char<parameter> *type</parameter></paramdef>
<paramdef>XrmValue<parameter> *value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>specifier</emphasis>
</term>
<listitem>
<para>
Specifies a complete or partial specification of the resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>type</emphasis>
</term>
<listitem>
<para>
Specifies the type of the resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value</emphasis>
</term>
<listitem>
<para>
Specifies the value of the resource, which is specified as a string.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If database contains NULL,
<function>XrmPutResource</function>
creates a new database and returns a pointer to it.
<function>XrmPutResource</function>
is a convenience function that calls
<function>XrmStringToBindingQuarkList</function>
followed by:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
</literallayout>
If the specifier and type are not in the Host Portable Character Encoding,
the result is implementation-dependent.
The value is stored in the database without modification.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmQPutResource</function></funcdef>
<paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
<paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
<paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
<paramdef>XrmRepresentation<parameter> type</parameter></paramdef>
<paramdef>XrmValue<parameter> *value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>bindings</emphasis>
</term>
<listitem>
<para>
Specifies a list of bindings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quarks</emphasis>
</term>
<listitem>
<para>
Specifies the complete or partial name or the class list of the resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>type</emphasis>
</term>
<listitem>
<para>
Specifies the type of the resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value</emphasis>
</term>
<listitem>
<para>
Specifies the value of the resource, which is specified as a string.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If database contains NULL,
<function>XrmQPutResource</function>
creates a new database and returns a pointer to it.
If a resource entry with the identical bindings and quarks already
exists in the database, the previous type and value are replaced by the new
specified type and value.
The value is stored in the database without modification.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To add a resource that is specified as a string, use
<function>XrmPutStringResource</function>.
<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmPutStringResource</function></funcdef>
<paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
<paramdef>char<parameter> *specifier</parameter></paramdef>
<paramdef>char<parameter> *value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>specifier</emphasis>
</term>
<listitem>
<para>
Specifies a complete or partial specification of the resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value</emphasis>
</term>
<listitem>
<para>
Specifies the value of the resource, which is specified as a string.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If database contains NULL,
<function>XrmPutStringResource</function>
creates a new database and returns a pointer to it.
<function>XrmPutStringResource</function>
adds a resource with the specified value to the specified database.
<function>XrmPutStringResource</function>
is a convenience function that first calls
<function>XrmStringToBindingQuarkList</function>
on the specifier and then calls
<function>XrmQPutResource</function>,
using a ``String'' representation type.
If the specifier is not in the Host Portable Character Encoding,
the result is implementation-dependent.
The value is stored in the database without modification.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To add a string resource using quarks as a specification, use
<function>XrmQPutStringResource</function>.
<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmQPutStringResource</function></funcdef>
<paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
<paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
<paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
<paramdef>char<parameter> *value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>bindings</emphasis>
</term>
<listitem>
<para>
Specifies a list of bindings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>quarks</emphasis>
</term>
<listitem>
<para>
Specifies the complete or partial name or the class list of the resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>value</emphasis>
</term>
<listitem>
<para>
Specifies the value of the resource, which is specified as a string.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If database contains NULL,
<function>XrmQPutStringResource</function>
creates a new database and returns a pointer to it.
<function>XrmQPutStringResource</function>
is a convenience routine that constructs an
<type>XrmValue</type>
for the value string (by calling
<function>strlen</function>
to compute the size) and
then calls
<function>XrmQPutResource</function>,
using a ``String'' representation type.
The value is stored in the database without modification.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To add a single resource entry that is specified as a string that contains
both a name and a value, use
<function>XrmPutLineResource</function>.
<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmPutLineResource</function></funcdef>
<paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
<paramdef>char<parameter> *line</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>line</emphasis>
</term>
<listitem>
<para>
Specifies the resource name and value pair as a single string.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If database contains NULL,
<function>XrmPutLineResource</function>
creates a new database and returns a pointer to it.
<function>XrmPutLineResource</function>
adds a single resource entry to the specified database.
The line should be in valid ResourceLine format (see section 15.1)
terminated by a newline or null character;
the database that results from using a string
with incorrect syntax is implementation-dependent.
The string is parsed in the locale of the database.
If the
<replaceable>ResourceName</replaceable>
is not in the Host Portable Character Encoding,
the result is implementation-dependent.
Note that comment lines are not stored.
</para>
</sect1>
<sect1 id="Enumerating_Database_Entries">
<title>Enumerating Database Entries</title>
<!-- .XS -->
<!-- (SN Enumerating Database Entries -->
<!-- .XE -->
<para>
<!-- .LP -->
To enumerate the entries of a database, use
<function>XrmEnumerateDatabase</function>.
<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>
<!-- .sM -->
</para>
<literallayout class="monospaced">
#define XrmEnumAllLevels 0
#define XrmEnumOneLevel 0
</literallayout>
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XrmEnumerateDatabase</function></funcdef>
<paramdef>XrmDatabase<parameter> database</parameter></paramdef>
<paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>
<paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>
<paramdef>int<parameter> mode</parameter></paramdef>
<paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
<paramdef>XPointer<parameter> arg</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>name_prefix</emphasis>
</term>
<listitem>
<para>
Specifies the resource name prefix.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>class_prefix</emphasis>
</term>
<listitem>
<para>
Specifies the resource class prefix.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>mode</emphasis>
</term>
<listitem>
<para>
Specifies the number of levels to enumerate.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>proc</emphasis>
</term>
<listitem>
<para>
Specifies the procedure that is to be called for each matching entry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>arg</emphasis>
</term>
<listitem>
<para>
Specifies the user-supplied argument that will be passed to the procedure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmEnumerateDatabase</function>
function calls the specified procedure for each resource in the database
that would match some completion of the given name/class resource prefix.
The order in which resources are found is implementation-dependent.
If mode is
<symbol>XrmEnumOneLevel</symbol>,
a resource must match the given name/class prefix with
just a single name and class appended. If mode is
<symbol>XrmEnumAllLevels</symbol>,
the resource must match the given name/class prefix with one or more names and
classes appended.
If the procedure returns
<symbol>True</symbol>,
the enumeration terminates and the function returns
<symbol>True</symbol>.
If the procedure always returns
<symbol>False</symbol>,
all matching resources are enumerated and the function returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
The procedure is called with the following arguments:
</para>
<para>
<!-- .LP -->
<!-- .\" Start marker code here -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)
XrmDatabase *<emphasis remap='I'>database</emphasis>;
XrmBindingList <emphasis remap='I'>bindings</emphasis>;
XrmQuarkList <emphasis remap='I'>quarks</emphasis>;
XrmRepresentation *<emphasis remap='I'>type</emphasis>;
XrmValue *<emphasis remap='I'>value</emphasis>;
XPointer <emphasis remap='I'>arg</emphasis>;
</literallayout>
<!-- .\" End marker code here -->
</para>
<para>
<!-- .LP -->
The bindings and quarks lists are terminated by
<symbol>NULLQUARK</symbol>.
Note that pointers
to the database and type are passed, but these values should not be modified.
</para>
<para>
<!-- .LP -->
The procedure must not modify the database.
If Xlib has been initialized for threads, the procedure is called with
the database locked and the result of a call by the procedure to any
Xlib function using the same database is not defined.
</para>
</sect1>
<sect1 id="Parsing_Command_Line_Options">
<title>Parsing Command Line Options</title>
<!-- .XS -->
<!-- (SN Parsing Command Line Options -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<function>XrmParseCommand</function>
function can be used to parse the command line arguments to a program
and modify a resource database with selected entries from the command line.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef enum {
XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value */
XrmoptionIsArg, /* Value is the option string itself */
XrmoptionStickyArg, /* Value is characters immediately following option */
XrmoptionSepArg, /* Value is next argument in argv */
XrmoptionResArg, /* Resource and value in next argument in argv */
XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
XrmoptionSkipLine, /* Ignore this option and the rest of argv */
XrmoptionSkipNArgs /* Ignore this option and the next
\ \ \ XrmOptionDescRec.value arguments in argv */
} XrmOptionKind;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
Note that
<constant>XrmoptionSkipArg</constant>
is equivalent to
<constant>XrmoptionSkipNArgs</constant>
with the
<structname>XrmOptionDescRec</structname>.<structfield>value</structfield>
field containing the value one.
Note also that the value zero for
<constant>XrmoptionSkipNArgs</constant>
indicates that only the option itself is to be skipped.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
char *option; /* Option specification string in argv */
char *specifier; /* Binding and resource name (sans application name) */
XrmOptionKind argKind; /* Which style of option it is */
XPointer value; /* Value to provide if XrmoptionNoArg or
\ \ \ XrmoptionSkipNArgs */
} XrmOptionDescRec, *XrmOptionDescList;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
To load a resource database from a C command line, use
<function>XrmParseCommand</function>.
<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XrmParseCommand</function></funcdef>
<paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
<paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>
<paramdef>int<parameter> table_count</parameter></paramdef>
<paramdef>char<parameter> *name</parameter></paramdef>
<paramdef>int<parameter> *argc_in_out</parameter></paramdef>
<paramdef>char<parameter> **argv_in_out</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>database</emphasis>
</term>
<listitem>
<para>
Specifies the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>table</emphasis>
</term>
<listitem>
<para>
Specifies the table of command line arguments to be parsed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>table_count</emphasis>
</term>
<listitem>
<para>
Specifies the number of entries in the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>name</emphasis>
</term>
<listitem>
<para>
Specifies the application name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>argc_in_out</emphasis>
</term>
<listitem>
<para>
Specifies the number of arguments and returns the number of remaining arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>argv_in_out</emphasis>
</term>
<listitem>
<para>
Specifies the command line arguments
and returns the remaining arguments.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XrmParseCommand</function>
function parses an (argc, argv) pair according to the specified option table,
loads recognized options into the specified database with type ``String,''
and modifies the (argc, argv) pair to remove all recognized options.
If database contains NULL,
<function>XrmParseCommand</function>
creates a new database and returns a pointer to it.
Otherwise, entries are added to the database specified.
If a database is created, it is created in the current locale.
</para>
<para>
<!-- .LP -->
The specified table is used to parse the command line.
Recognized options in the table are removed from argv,
and entries are added to the specified resource database
in the order they occur in argv.
The table entries contain information on the option string,
the option name, the style of option,
and a value to provide if the option kind is
<constant>XrmoptionNoArg</constant>.
The option names are compared byte-for-byte to arguments in argv,
independent of any locale.
The resource values given in the table are stored in the resource database
without modification.
All resource database entries are created
using a ``String'' representation type.
The argc argument specifies the number of arguments in argv
and is set on return to the remaining number of arguments that were not parsed.
The name argument should be the name of your application
for use in building the database entry.
The name argument is prefixed to the resourceName in the option table
before storing a database entry.
The name argument is treated as a single component, even if it
has embedded periods.
No separating (binding) character is inserted,
so the table must contain either a period (.) or an asterisk (*)
as the first character in each resourceName entry.
To specify a more completely qualified resource name,
the resourceName entry can contain multiple components.
If the name argument and the resourceNames are not in the
Host Portable Character Encoding,
the result is implementation-dependent.
</para>
<para>
<!-- .LP -->
The following provides a sample option table:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA 1.25i 3.25i 4.75i -->
<!-- .ta 1.25i 3.25i 4.75i -->
static XrmOptionDescRec opTable[] = {
{"-background", "*background", XrmoptionSepArg, (XPointer) NULL},
{"-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
{"-bg", "*background", XrmoptionSepArg, (XPointer) NULL},
{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
{"-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
{"-display", ".display", XrmoptionSepArg, (XPointer) NULL},
{"-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL},
{"-fn", "*font", XrmoptionSepArg, (XPointer) NULL},
{"-font", "*font", XrmoptionSepArg, (XPointer) NULL},
{"-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL},
{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL},
{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"},
{"-name", ".name", XrmoptionSepArg, (XPointer) NULL},
{"-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
{"-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
{"-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"},
{"-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL},
{"-xrm", NULL, XrmoptionResArg, (XPointer) NULL},
};
</literallayout>
</para>
<para>
<!-- .LP -->
In this table, if the -background (or -bg) option is used to set
background colors, the stored resource specifier matches all
resources of attribute background.
If the -borderwidth option is used,
the stored resource specifier applies only to border width
attributes of class TopLevelShell (that is, outer-most windows, including
pop-up windows).
If the -title option is used to set a window name,
only the topmost application windows receive the resource.
</para>
<para>
<!-- .LP -->
When parsing the command line,
any unique unambiguous abbreviation for an option name in the table is
considered a match for the option.
Note that uppercase and lowercase matter.
<!-- .bp -->
</para>
</sect1>
</chapter>