home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-08-27 | 49.5 KB | 1,577 lines |
- \&
- .sp 1
- .ce 3
- \s+1\fBChapter 15\fP\s-1
-
- \s+1\fBResource Manager Functions\fP\s-1
- .sp 2
- .nr H1 15
- .nr H2 0
- .nr H3 0
- .nr H4 0
- .nr H5 0
- .na
- .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 setting.
- The resource manager is provided for this purpose.
- Resource specifications are usually stored in human-readable files
- and in server properties.
- .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.
- .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.
- .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.
- .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.
- .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.
- .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''.
- .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 lookup routine.
- The resource manager compares this complete specification
- against the incomplete specifications of entries in the resource
- database, find the best match, and returns the corresponding
- value for that entry.
- .LP
- The definitions for the resource manager are contained in
- .Pn < X11/Xresource.h >.
- .NH 2
- Resource File Syntax
- .XS
- \*(SN Resource File Syntax
- .XE
- .LP
- The syntax of a resource file is a sequence of resource lines
- terminated by newline characters or end of file.
- The syntax of an individual resource line is:
- .LP
- .\" Start marker code here
- .Ds 0
- .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>}
- .De
- .\" End marker code here
- .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.
- .LP
- IncludeFile lines are interpreted by replacing the line with the
- contents of the specified file. The word "include" must be in lowercase.
- The filename is interpreted relative to the directory of the file in
- which the line occurs (for example, if the filename contains no
- directory or contains a relative directory specification).
- .LP
- If a ResourceName contains a contiguous sequence of two or more Binding
- characters, the sequence will be replaced with single "\&." character
- if the sequence contains only "\&." characters,
- otherwise the sequence will be replaced with a single "*" character.
- .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.
- .LP
- Any whitespace character before or after the name or colon in a ResourceSpec
- are ignored.
- To allow a Value to begin with whitespace,
- the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space)
- is recognized and replaced by a space character,
- and the two-character sequence ``\\\^\fItab\fP''
- (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 ``\\\^\fInewline\fP''
- (backslash followed by newline) is
- recognized and removed from the value.
- To allow a Value to contain arbitrary character codes,
- the four-character sequence ``\\\^\fInnn\fP'',
- where each \fIn\fP 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 ``\\\\'' is recognized
- and replaced with a single backslash.
- .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:
- .Ds
- magic.values: \\\\\\\^000\^\\
- z\\\^n
- .De
- .NH 2
- Resource Manager Matching Rules
- .XS
- \*(SN Resource Manager Matching Rules
- .XE
- .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 "*" and "?" are 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 "?") 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.
- .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:
- .IP 1. 5
- An entry that contains a matching component (whether name, class, or "?")
- takes precedence over entries that elide the level (that is, entries
- that match the level in a loose binding).
- .IP 2. 5
- An entry with a matching name takes precedence over both
- entries with a matching class and entries that match using "?".
- An entry with a matching class takes precedence over
- entries that match using "?".
- .IP 3. 5
- An entry preceded by a tight binding takes precedence over entries
- preceded by a loose binding.
- .LP
- To illustrate these rules, consider following the resource database entries:
- .Ds
- .TA 2.5i 3.5i
- .ta 2.5i 3.5i
- xmh*Paned*activeForeground: red \fI(entry A)\fP
- *incorporate.Foreground: blue \fI(entry B)\fP
- xmh.toc*Command*activeForeground: green \fI(entry C)\fP
- xmh.toc*?.Foreground: white \fI(entry D)\fP
- xmh.toc*Command.activeForeground: black \fI(entry E)\fP
- .De
- .LP
- Consider a query for the resource:
- .LP
- .Ds
- .TA 3.5i
- .ta 3.5i
- xmh.toc.messagefunctions.incorporate.activeForeground \fI(name)\fP
- Xmh.Paned.Box.Command.Foreground \fI(class)\fP
- .De
- .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.
- .NH 2
- Quarks
- .XS
- \*(SN Quarks
- .XE
- .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
- .PN XrmQuark .
- On some occasions,
- you may want to allocate a quark that has no string equivalent.
- .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.
- .LP
- .sp
- To allocate a new quark, use
- .PN XrmUniqueQuark .
- .IN "XrmUniqueQuark" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XrmQuark XrmUniqueQuark\^(\|)
- .FN
- .\" End marker code here
- .LP
- The
- .PN XrmUniqueQuark
- function allocates a quark that is guaranteed not to represent any string that
- is known to the resource manager.
- .LP
- .sp
- Each name, class, and representation type is typedef'd as an
- .PN XrmQuark .
- .LP
- .\" Start marker code here
- .Ds 0
- typedef int XrmQuark, *XrmQuarkList;
- typedef XrmQuark XrmName;
- typedef XrmQuark XrmClass;
- typedef XrmQuark XrmRepresentation;
- #define NULLQUARK ((XrmQuark) 0)
- .De
- .\" End marker code here
- .LP
- Lists are represented as null-terminated arrays of quarks.
- The size of the array must be large enough for the number of components used.
- .LP
- .\" Start marker code here
- .Ds 0
- typedef XrmQuarkList XrmNameList;
- typedef XrmQuarkList XrmClassList;
- .De
- .\" End marker code here
- .LP
- .sp
- To convert a string to a quark, use
- .PN XrmStringToQuark
- or
- .PN XrmPermStringToQuark .
- .IN "XrmStringToQuark" "" "@DEF@"
- .IN "XrmPermStringToQuark" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- #define XrmStringToName(string) XrmStringToQuark(string)
- #define XrmStringToClass(string) XrmStringToQuark(string)
- #define XrmStringToRepresentation(string) XrmStringToQuark(string)
- .sp
- XrmQuark XrmStringToQuark\^(\^\fIstring\fP\^)
- .br
- char *\fIstring\fP\^;
- .sp
- XrmQuark XrmPermStringToQuark\^(\^\fIstring\fP\^)
- .br
- char *\fIstring\fP\^;
- .FN
- .ds Ql
- .IP \fIstring\fP 1i
- Specifies the string for which a quark\*(Ql is to be allocated.
- .\" End marker code here
- .LP
- 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
- .PN XrmStringToQuark
- need not be permanently allocated storage.
- .PN XrmPermStringToQuark
- is just like
- .PN XrmStringToQuark ,
- 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
- .PN XrmQuarkToString .
- .LP
- .sp
- To convert a quark to a string, use
- .PN XrmQuarkToString .
- .IN "XrmQuarkToString" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- #define XrmNameToString(name) XrmQuarkToString(name)
- #define XrmClassToString(class) XrmQuarkToString(class)
- #define XrmRepresentationToString(type) XrmQuarkToString(type)
- .sp
- char *XrmQuarkToString\^(\^\fIquark\fP\^)
- .br
- XrmQuark \fIquark\fP\^;
- .FN
- .IP \fIquark\fP 1i
- Specifies the quark for which the equivalent string is desired.
- .\" End marker code here
- .LP
- This function 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,
- .PN XrmQuarkToString
- returns NULL.
- For any given quark, if
- .PN XrmQuarkToString
- returns a non-NULL value,
- all future calls will return the same value (identical address).
- .LP
- .sp
- To convert a string with one or more components to a quark list, use
- .PN XrmStringToQuarkList .
- .IN "XrmStringToQuarkList" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- #define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name))
- #define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
- .sp
- void XrmStringToQuarkList\^(\^\fIstring\fP, \fIquarks_return\fP\^)
- .br
- char *\fIstring\fP\^;
- .br
- XrmQuarkList \fIquarks_return\fP\^;
- .FN
- .ds Ql \ list
- .IP \fIstring\fP 1i
- Specifies the string for which a quark\*(Ql is to be allocated.
- .IP \fIquarks_return\fP 1i
- Returns the list of quarks.
- .\" End marker code here
- .LP
- The
- .PN XrmStringToQuarkList
- 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.
- .LP
- A binding list is a list of type
- .PN XrmBindingList
- and indicates if components of name or class lists are bound tightly or loosely
- (that is, if wildcarding of intermediate components is specified).
- .LP
- .Ds 0
- typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
- .De
- .LP
- .PN XrmBindTightly
- indicates that a period separates the components, and
- .PN XrmBindLoosely
- indicates that an asterisk separates the components.
- .LP
- .sp
- To convert a string with one or more components to a binding list
- and a quark list, use
- .PN XrmStringToBindingQuarkList .
- .IN "XrmStringToBindingQuarkList" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XrmStringToBindingQuarkList\^(\^\fIstring\fP, \fIbindings_return\fP, \
- \fIquarks_return\fP\^)
- .br
- char *\fIstring\fP\^;
- .br
- XrmBindingList \fIbindings_return\fP\^;
- .br
- XrmQuarkList \fIquarks_return\fP\^;
- .FN
- .ds Ql \ list
- .IP \fIstring\fP 1i
- Specifies the string for which a quark\*(Ql is to be allocated.
- .IP \fIbindings_return\fP 1i
- Returns the binding list.
- The caller must allocate sufficient space for the binding list before calling
- .PN XrmStringToBindingQuarkList .
- .IP \fIquarks_return\fP 1i
- Returns the list of quarks.
- The caller must allocate sufficient space for the quarks list before calling
- .PN XrmStringToBindingQuarkList .
- .\" End marker code here
- .LP
- 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, ``*a.b*c'' becomes:
- .LP
- .Ds 0
- .TA .75i 1.5i 2.25i
- .ta .75i 1.5i 2.25i
- quarks: a b c
- bindings: loose tight loose
- .De
- .NH 2
- Creating and Storing Databases
- .XS
- \*(SN Creating and Storing Databases
- .XE
- .LP
- .IN "XrmDatabase" "" "@DEF@"
- A resource database is an opaque type,
- .PN XrmDatabase .
- Each database value is stored in an
- .PN XrmValue
- 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, ``font'' or ``color'').
- It has nothing to do with the C data type or with its class.
- The
- .PN XrmValue
- structure is defined as:
- .LP
- .IN "XrmValue" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- unsigned int size;
- XPointer addr;
- } XrmValue, *XrmValuePtr;
- .De
- .\" End marker code here
- .LP
- .sp
- To initialize the resource manager, use
- .PN XrmInitialize .
- .IN "XrmInitialize" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmInitialize\^(\|);
- .FN
- .\" End marker code here
- .LP
- To retrieve a database from disk, use
- .PN XrmGetFileDatabase .
- .IN "XrmGetFileDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^)
- .br
- char *\fIfilename\fP\^;
- .FN
- .IP \fIfilename\fP 1i
- Specifies the resource database file name.
- .\" End marker code here
- .LP
- The
- .PN XrmGetFileDatabase
- 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 must contain a sequence of entries in valid ResourceLine
- format (see section 15.1).
- The file is parsed in the current locale,
- and the database is created in the current locale.
- If it cannot open the specified file,
- .PN XrmGetFileDatabase
- returns NULL.
- .LP
- .sp
- To store a copy of a database to disk, use
- .PN XrmPutFileDatabase .
- .IN "XrmPutFileDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmPutFileDatabase\^(\^\fIdatabase\fP, \fIstored_db\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .br
- char *\fIstored_db\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the database that is to be used.
- .IP \fIstored_db\fP 1i
- Specifies the file name for the stored database.
- .\" End marker code here
- .LP
- The
- .PN XrmPutFileDatabase
- 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.
- .LP
- .sp
- To obtain a pointer to the screen-independent resources of a display, use
- .PN XResourceManagerString .
- .IN "XResourceManagerString" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- char *XResourceManagerString\^(\^\fIdisplay\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" End marker code here
- .LP
- The
- .PN XResourceManagerString
- returns the RESOURCE_MANAGER property from the server's root window of screen
- zero, which was returned when the connection was opened using
- .PN XOpenDisplay .
- The property is converted from type STRING to the current locale.
- The conversion is identical to that produced by
- .PN XmbTextPropertyToTextList
- for a singleton STRING property.
- The returned string is owned by Xlib, and should not be freed by the client.
- Note that the property value must be in a format that is acceptable to
- .PN XrmGetStringDatabase .
- If no property exists, NULL is returned.
- .LP
- .sp
- To obtain a pointer to the screen-specific resources of a screen, use
- .PN XScreenResourceString .
- .IN "XScreenResourceString" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- char *XScreenResourceString\^(\^\fIscreen\fP\^)
- .br
- Screen *\fIscreen\fP\^;
- .FN
- .IP \fIscreen\fP 1i
- Specifies the screen.
- .\" End marker code here
- .LP
- The
- .PN XStringResourceString
- 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
- .PN XmbTextPropertyToTextList
- for a singleton STRING property.
- Note that the property value must be in a format that is acceptable to
- .PN XrmGetStringDatabase .
- If no property exists, NULL is returned.
- The caller is responsible for freeing the returned string, using
- .PN XFree .
- .LP
- .sp
- To create a database from a string, use
- .PN XrmGetStringDatabase .
- .IN "XrmGetStringDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^)
- .br
- char *\fIdata\fP\^;
- .FN
- .IP \fIdata\fP 1i
- Specifies the database contents using a string.
- .\" End marker code here
- .LP
- The
- .PN XrmGetStringDatabase
- function creates a new database and stores the resources specified
- in the specified null-terminated string.
- .PN XrmGetStringDatabase
- is similar to
- .PN XrmGetFileDatabase
- except that it reads the information out of a string instead of out of a file.
- The string must contain a sequence of entries in valid ResourceLine
- format (see section 15.1).
- The string is parsed in the current locale,
- and the database is created in the current locale.
- .LP
- .sp
- To obtain locale name of a database, use
- .PN XrmLocaleOfDatabase .
- .IN "XrmLocaleOfDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .\" End marker code here
- .LP
- The
- .PN XrmLocaleOfDatabase
- 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.
- .LP
- .sp
- To destroy a resource database and free its allocated memory, use
- .PN XrmDestroyDatabase .
- .IN "XrmDestroyDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmDestroyDatabase\^(\^\fIdatabase\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .\" End marker code here
- .LP
- If database is NULL,
- .PN XrmDestroyDatabase
- returns immediately.
- .LP
- .sp
- To associate a resource database with a display, use
- .PN XrmSetDatabase .
- .IN "XrmSetDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .br
- XrmDatabase \fIdatabase\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .\" End marker code here
- .LP
- The
- .PN XrmSetDatabase
- 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.
- .LP
- .sp
- To get the resource database associated with a display, use
- .PN XrmGetDatabase .
- .IN "XrmGetDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^)
- .br
- Display *\fIdisplay\fP\^;
- .FN
- .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
- .IP \fIdisplay\fP 1i
- Specifies the connection to the X server.
- .\" End marker code here
- .LP
- The
- .PN XrmGetDatabase
- function returns the database associated with the specified display.
- It returns NULL if a database has not yet been set.
- .NH 2
- Merging Resource Databases
- .XS
- \*(SN Merging Resource Databases
- .XE
- .LP
- To merge the contents of a resource file into a database, us
- .PN XrmCombineFileDatabase .
- .IN "XrmCombineFileDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmCombineFileDatabase(\^\fIfilename\fP, \fItarget_db\fP, \fIoverride\fP\^)
- .br
- char *\fIfilename\fP;
- .br
- XrmDatabase *\fItarget_db\fP\^;
- .br
- Bool \fIoverride\fP;
- .FN
- .IP \fIfilename\fP 1i
- Specifies the resource database file name.
- .IP \fItarget_db\fP 1i
- Specifies the resource database into which the source
- database is to be merged.
- .\" End marker code here
- .LP
- .\" $Header: XrmCFDBase.d,v 1.2 88/06/11 07:54:46 mento Exp $
- The
- .PN XrmCombineFileDatabase
- 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
- .PN True ;
- otherwise, the entry in 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,
- .PN XrmCombineFileDatabase
- 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.
- .LP
- .sp
- To merge the contents of one database into another database, use
- .PN XrmCombineDatabase .
- .IN "XrmCombineDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmCombineDatabase(\^\fIsource_db\fP, \fItarget_db\fP, \fIoverride\fP\^)
- .br
- XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
- .br
- Bool \fIoverride\fP;
- .FN
- .IP \fIsource_db\fP 1i
- Specifies the resource database that is to be merged into the target database.
- .IP \fItarget_db\fP 1i
- Specifies the resource database into which the source
- database is to be merged.
- .IP \fIoverride\fP 1i
- Specifies whether source entries override target ones.
- .\" End marker code here
- .LP
- .\" $Header: XrmCDBase.d,v 1.2 88/06/11 07:54:46 mento Exp $
- The
- .PN XrmCombineDatabase
- 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
- .PN True ;
- otherwise, the entry in source_db is discarded.
- If target_db contains NULL,
- .PN XrmCombineDatabase
- 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.
- .LP
- .sp
- To merge the contents of one database into another database with override
- semantics, use
- .PN XrmMergeDatabases .
- .IN "XrmMergeDatabases" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmMergeDatabases(\^\fIsource_db\fP, \fItarget_db\fP\^)
- .br
- XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
- .FN
- .IP \fIsource_db\fP 1i
- Specifies the resource database that is to be merged into the target database.
- .IP \fItarget_db\fP 1i
- Specifies the resource database into which the source
- database is to be merged.
- .\" End marker code here
- .LP
- .\" $Header: XrmMDBase.d,v 1.2 88/06/11 07:54:46 mento Exp $
- The
- .PN XrmMergeDatabases
- 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
- (that is, it overrides target_db).
- If target_db contains NULL,
- .PN XrmMergeDatabases
- 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.
- .NH 2
- Looking Up Resources
- .XS
- \*(SN Looking Up Resources
- .XE
- .LP
- To retrieve a resource from a resource database, use
- .PN XrmGetResource ,
- .PN XrmQGetResource ,
- or
- .PN XrmQGetSearchResource .
- .LP
- .sp
- .IN "XrmGetResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- Bool XrmGetResource\^(\^\fIdatabase\fP, \fIstr_name\fP, \fIstr_class\fP, \
- \fIstr_type_return\fP, \fIvalue_return\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .br
- char *\fIstr_name\fP\^;
- .br
- char *\fIstr_class\fP\^;
- .br
- char **\fIstr_type_return\fP\^;
- .br
- XrmValue *\fIvalue_return\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the database that is to be used.
- .IP \fIstr_name\fP 1i
- Specifies the fully qualified name of the value being retrieved (as a string).
- .IP \fIstr_class\fP 1i
- Specifies the fully qualified class of the value being retrieved (as a string).
- .IP \fIstr_type_return\fP 1i
- Returns the representation type of the destination (as a string).
- .IP \fIvalue_return\fP 1i
- Returns the value in the database.
- .\" End marker code here
- .LP
- .sp
- .IN "XrmQGetResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- Bool XrmQGetResource\^(\^\fIdatabase\fP, \fIquark_name\fP, \fIquark_class\fP, \
- \fIquark_type_return\fP, \fIvalue_return\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .br
- XrmNameList \fIquark_name\fP\^;
- .br
- XrmClassList \fIquark_class\fP\^;
- .br
- XrmRepresentation *\fIquark_type_return\fP\^;
- .br
- XrmValue *\fIvalue_return\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the database that is to be used.
- .IP \fIquark_name\fP 1i
- Specifies the fully qualified name of the value being retrieved (as a quark).
- .IP \fIquark_class\fP 1i
- Specifies the fully qualified class of the value being retrieved (as a quark).
- .IP \fIquark_type_return\fP 1i
- Returns the representation type of the destination (as a quark).
- .IP \fIvalue_return\fP 1i
- Returns the value in the database.
- .\" End marker code here
- .LP
- The
- .PN XrmGetResource
- and
- .PN XrmQGetResource
- 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.
- .LP
- The database only frees or overwrites entries on
- .PN XrmPutResource ,
- .PN XrmQPutResource ,
- or
- .PN XrmMergeDatabases .
- 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
- .PN XrmGetResource
- and
- .PN XrmQGetResource
- return
- .PN True ;
- otherwise, they return
- .PN False .
- .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 are made with only the
- last name/class differing in each probe.
- The
- .PN XrmGetResource
- function is at worst a %2 sup n% algorithm,
- where \fIn\fP 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.
- .LP
- .sp
- To obtain a list of database levels, use
- .PN XrmQGetSearchList .
- .IN "XrmQGetSearchList" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- typedef XrmHashTable *XrmSearchList;
- .sp
- Bool XrmQGetSearchList\^(\^\fIdatabase\fP, \fInames\fP, \fIclasses\fP, \
- \fIlist_return\fP, \fIlist_length\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .br
- XrmNameList \fInames\fP\^;
- .br
- XrmClassList \fIclasses\fP\^;
- .br
- XrmSearchList \fIlist_return\fP\^;
- .br
- int \fIlist_length\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the database that is to be used.
- .IP \fInames\fP 1i
- Specifies a list of resource names.
- .IP \fIclasses\fP 1i
- Specifies a list of resource classes.
- .IP \fIlist_return\fP 1i
- Returns a search list for further use.
- The caller must allocate sufficient space for the list before calling
- .PN XrmQGetSearchList .
- .IP \fIlist_length\fP 1i
- Specifies the number of entries (not the byte size) allocated for list_return.
- .\" End marker code here
- .LP
- .EQ
- delim %%
- .EN
- The
- .PN XrmQGetSearchList
- 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
- .PN XrmGetResource
- for determining precedence.
- If list_return was large enough for the search list,
- .PN XrmQGetSearchList
- returns
- .PN True ;
- otherwise, it returns
- .PN False .
- .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 sup n%,
- where \fIn\fP is the number of name or class components in names or classes.
- .LP
- When using
- .PN XrmQGetSearchList
- 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
- .PN XrmQGetSearchList .
- .LP
- .sp
- To search resource database levels for a given resource, use
- .PN XrmQGetSearchResource .
- .IN "XrmQGetSearchResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- Bool XrmQGetSearchResource\^(\^\fIlist\fP, \fIname\fP, \fIclass\fP, \
- \fItype_return\fP, \fIvalue_return\fP\^)
- .br
- XrmSearchList \fIlist\fP\^;
- .br
- XrmName \fIname\fP\^;
- .br
- XrmClass \fIclass\fP\^;
- .br
- XrmRepresentation *\fItype_return\fP\^;
- .br
- XrmValue *\fIvalue_return\fP\^;
- .FN
- .IP \fIlist\fP 1i
- Specifies the search list returned by
- .PN XrmQGetSearchList .
- .IP \fIname\fP 1i
- Specifies the resource name.
- .IP \fIclass\fP 1i
- Specifies the resource class.
- .IP \fItype_return\fP 1i
- Returns data representation type.
- .IP \fIvalue_return\fP 1i
- Returns the value in the database.
- .\" End marker code here
- .LP
- The
- .PN XrmQGetSearchResource
- 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.
- .PN XrmQGetSearchResource
- returns
- .PN True
- if the resource was found;
- otherwise, it returns
- .PN False .
- .LP
- A call to
- .PN XrmQGetSearchList
- with a name and class list containing all but the last component
- of a resource name followed by a call to
- .PN XrmQGetSearchResource
- with the last component name and class returns the same database entry as
- .PN XrmGetResource
- and
- .PN XrmQGetResource
- with the fully qualified name and class.
- .NH 2
- Storing Into a Resource Database
- .XS
- \*(SN Storing Into a Resource Database
- .XE
- .LP
- To store resources into the database, use
- .PN XrmPutResource
- or
- .PN XrmQPutResource .
- Both functions take a partial resource specification, a
- representation type, and a value.
- This value is copied into the specified database.
- .LP
- .sp
- .IN "XrmPutResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmPutResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fItype\fP, \fIvalue\fP\^)
- .br
- XrmDatabase *\fIdatabase\fP\^;
- .br
- char *\fIspecifier\fP\^;
- .br
- char *\fItype\fP\^;
- .br
- XrmValue *\fIvalue\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fIspecifier\fP 1i
- Specifies a complete or partial specification of the resource.
- .IP \fItype\fP 1i
- Specifies the type of the resource.
- .IP \fIvalue\fP 1i
- Specifies the value of the resource, which is specified as a string.
- .\" End marker code here
- .LP
- If database contains NULL,
- .PN XrmPutResource
- creates a new database and returns a pointer to it.
- .PN XrmPutResource
- is a convenience function that calls
- .PN XrmStringToBindingQuarkList
- followed by:
- .LP
- .Ds
- XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
- .De
- 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.
- .LP
- .sp
- .IN "XrmQPutResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmQPutResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
- \fItype\fP, \fIvalue\fP\^)
- .br
- XrmDatabase *\fIdatabase\fP\^;
- .br
- XrmBindingList \fIbindings\fP\^;
- .br
- XrmQuarkList \fIquarks\fP\^;
- .br
- XrmRepresentation \fItype\fP\^;
- .br
- XrmValue *\fIvalue\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fIbindings\fP 1i
- Specifies a list of bindings.
- .IP \fIquarks\fP 1i
- Specifies the complete or partial name or the class list of the resource.
- .IP \fItype\fP 1i
- Specifies the type of the resource.
- .IP \fIvalue\fP 1i
- Specifies the value of the resource, which is specified as a string.
- .\" End marker code here
- .LP
- If database contains NULL,
- .PN XrmQPutResource
- 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 value is replaced by the new
- specified value.
- The value is stored in the database without modification.
- .LP
- .sp
- To add a resource that is specified as a string, use
- .PN XrmPutStringResource .
- .IN "XrmPutStringResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmPutStringResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fIvalue\fP\^)
- .br
- XrmDatabase *\fIdatabase\fP\^;
- .br
- char *\fIspecifier\fP\^;
- .br
- char *\fIvalue\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fIspecifier\fP 1i
- Specifies a complete or partial specification of the resource.
- .IP \fIvalue\fP 1i
- Specifies the value of the resource, which is specified as a string.
- .\" End marker code here
- .LP
- If database contains NULL,
- .PN XrmPutStringResource
- creates a new database and returns a pointer to it.
- .PN XrmPutStringResource
- adds a resource with the specified value to the specified database.
- .PN XrmPutStringResource
- is a convenience function that first calls
- .PN XrmStringToBindingQuarkList
- on the specifier and then calls
- .PN XrmQPutResource ,
- 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.
- .LP
- .sp
- To add a string resource using quarks as a specification, use
- .PN XrmQPutStringResource .
- .IN "XrmQPutStringResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmQPutStringResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
- \fIvalue\fP\^)
- .br
- XrmDatabase *\fIdatabase\fP\^;
- .br
- XrmBindingList \fIbindings\fP\^;
- .br
- XrmQuarkList \fIquarks\fP\^;
- .br
- char *\fIvalue\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fIbindings\fP 1i
- Specifies a list of bindings.
- .IP \fIquarks\fP 1i
- Specifies the complete or partial name or the class list of the resource.
- .IP \fIvalue\fP 1i
- Specifies the value of the resource, which is specified as a string.
- .\" End marker code here
- .LP
- If database contains NULL,
- .PN XrmQPutStringResource
- creates a new database and returns a pointer to it.
- .PN XrmQPutStringResource
- is a convenience routine that constructs an
- .PN XrmValue
- for the value string (by calling
- .PN strlen
- to compute the size) and
- then calls
- .PN XrmQPutResource ,
- using a ``String'' representation type.
- The value is stored in the database without modification.
- .LP
- .sp
- To add a single resource entry that is specified as a string that contains
- both a name and a value, use
- .PN XrmPutLineResource .
- .IN "XrmPutLineResource" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmPutLineResource\^(\^\fIdatabase\fP, \fIline\fP\^)
- .br
- XrmDatabase *\fIdatabase\fP\^;
- .br
- char *\fIline\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fIline\fP 1i
- Specifies the resource name and value pair as a single string.
- .\" End marker code here
- .LP
- If database contains NULL,
- .PN XrmPutLineResource
- creates a new database and returns a pointer to it.
- .PN XrmPutLineResource
- adds a single resource entry to the specified database.
- The line must be in valid ResourceLine format (see section 15.1).
- The string is parsed in the locale of the database.
- If the
- .PN ResourceName
- is not in the Host Portable Character Encoding
- the result is implementation dependent.
- Note that comment lines are not stored.
- .NH 2
- Enumerating Database Entries
- .XS
- \*(SN Enumerating Database Entries
- .XE
- .LP
- To enumerate the entries of a database, use
- .PN XrmEnumerateDatabase .
- .IN "XrmEnumerateDatabase" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- .TS
- lw(.5i) lw(2i) lw(2.5i).
- T{
- #define
- T} T{
- .PN XrmEnumAllLevels
- T} T{
- 0
- T}
- T{
- #define
- T} T{
- .PN XrmEnumOneLevel
- T} T{
- 1
- T}
- .TE
- .sp
- Bool XrmEnumerateDatabase\^(\^\fIdatabase\fP, \fIname_prefix\fP, \fIclass_prefix\fP, \fImode\fP, \fIproc\fP, \fIarg\fP\^)
- .br
- XrmDatabase \fIdatabase\fP\^;
- .br
- XrmNameList \fIname_prefix\fP\^;
- .br
- XrmClassList \fIclass_prefix\fP\^;
- .br
- int \fImode\fP\^;
- .br
- Bool (\^*\fIproc\fP\^)\^(\^)\^;
- .br
- XPointer \fIarg\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fIname_prefix\fP 1i
- Specifies the resource name prefix.
- .IP \fIclass_prefix\fP 1i
- Specifies the resource class prefix.
- .IP \fImode\fP 1i
- Specifies the number of levels to enumerate.
- .IP \fIproc\fP 1i
- Specifies the procedure that is to be called for each matching entry.
- .IP \fIarg\fP 1i
- Specifies the user-supplied argument that will be passed to the procedure.
- .\" End marker code here
- .LP
- The
- .PN XrmEnumerateDatabase
- 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
- .PN XrmEnumOneLevel ,
- then a resource must match the given name/class prefix with
- just a single name and class appended. If mode is
- .PN XrmEnumAllLevels ,
- the resource must match the given name/class prefix with one or more names and
- classes appended.
- If the procedure returns
- .PN True ,
- the enumeration terminates and the function returns
- .PN True .
- If the procedure always returns
- .PN False ,
- all matching resources are enumerated and the function returns
- .PN False .
- .LP
- The procedure is called with the following arguments:
- .LP
- .\" Start marker code here
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- (*\fIproc\fP\^)(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \fItype\fP, \fIvalue\fP, \fIarg\fP\^)
- XrmDatabase *\fIdatabase\fP\^;
- XrmBindingList \fIbindings\fP\^;
- XrmQuarkList \fIquarks\fP\^;
- XrmRepresentation *\fItype\fP\^;
- XrmValue *\fIvalue\fP\^;
- XPointer \fIclosure\fP\^;
- .De
- .\" End marker code here
- .LP
- The bindings and quarks lists are terminated by
- .PN NULLQUARK .
- Note that pointers
- to the database and type are passed, but these values should not be modified.
- .NH 2
- Parsing Command Line Options
- .XS
- \*(SN Parsing Command Line Options
- .XE
- .LP
- The
- .PN XrmParseCommand
- 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.
- .LP
- .IN "XrmOptionKind" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .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;
- .De
- .\" End marker code here
- .LP
- Note that
- .PN XrmoptionSkipArg
- is equivalent to
- .PN XrmoptionSkipNArgs
- with the
- .PN XrmOptionDescRec.value
- field containing the value one.
- Note also that the value zero for
- .PN XrmoptionSkipNArgs
- indicates that only the option itself is to be skipped.
- .LP
- .IN "XrmOptionDescRec" "" "@DEF@"
- .\" Start marker code here
- .Ds 0
- .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;
- .De
- .\" End marker code here
- .LP
- .sp
- To load a resource database from a C command line, use
- .PN XrmParseCommand .
- .IN "XrmParseCommand" "" "@DEF@"
- .\" Start marker code here
- .FD 0
- void XrmParseCommand\^(\^\fIdatabase\fP\^, \^\fItable\fP\^, \^\fItable_count\fP\^, \
- \^\fIname\fP\^, \^\fIargc_in_out\fP\^, \^\fIargv_in_out\fP\^)
- .br
- XrmDatabase *\fIdatabase\fP\^;
- .br
- XrmOptionDescList \fItable\fP\^;
- .br
- int \fItable_count\fP\^;
- .br
- char *\fIname\fP\^;
- .br
- int *\fIargc_in_out\fP\^;
- .br
- char **\fIargv_in_out\fP\^;
- .FN
- .IP \fIdatabase\fP 1i
- Specifies the resource database.
- .IP \fItable\fP 1i
- Specifies the table of command line arguments to be parsed.
- .IP \fItable_count\fP 1i
- Specifies the number of entries in the table.
- .\" $Header: parname.a,v 1.1 88/02/26 10:30:16 mento Exp $
- .IP \fIname\fP 1i
- Specifies the application name.
- .IP \fIargc_in_out\fP 1i
- Specifies the number of arguments and returns the number of remaining arguments.
- .IP \fIargv_in_out\fP 1i
- Specifies the command line arguments
- and returns the remaining arguments.
- .\" End marker code here
- .LP
- .\" $Header: XrmParse.d,v 1.7 88/08/20 10:49:05 mento Exp $
- The
- .PN XrmParseCommand
- 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,
- .PN XrmParseCommand
- 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.
- .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.
- 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
- .PN XrmoptionNoArg .
- 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.
- 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.
- .LP
- The following provides a sample option table:
- .LP
- .Ds 0
- .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},
- };
- .De
- .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.
- .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
-