diff options
Diffstat (limited to 'libX11/specs/libX11/CH15')
| -rw-r--r-- | libX11/specs/libX11/CH15 | 1628 |
1 files changed, 1628 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH15 b/libX11/specs/libX11/CH15 new file mode 100644 index 000000000..a10df0a53 --- /dev/null +++ b/libX11/specs/libX11/CH15 @@ -0,0 +1,1628 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.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 settings. +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 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. +.LP +The definitions for the resource manager are contained in +.hN 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 the end of the 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 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). +.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. +.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 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 ``\^\\\^\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 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. +.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 the character ``?'') +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 the character ``?''. +An entry with a matching class takes precedence over +entries that match using the character ``?''. +.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 the following 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@" +.sM +.FD 0 +XrmQuark XrmUniqueQuark\^(\|) +.FN +.LP +.eM +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 +.sM +.Ds 0 +typedef int XrmQuark, *XrmQuarkList; +typedef XrmQuark XrmName; +typedef XrmQuark XrmClass; +typedef XrmQuark XrmRepresentation; +#define NULLQUARK ((XrmQuark) 0) +.De +.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. +.LP +.sM +.Ds 0 +typedef XrmQuarkList XrmNameList; +typedef XrmQuarkList XrmClassList; +.De +.LP +.eM +.sp +To convert a string to a quark, use +.PN XrmStringToQuark +or +.PN XrmPermStringToQuark . +.IN "XrmStringToQuark" "" "@DEF@" +.IN "XrmPermStringToQuark" "" "@DEF@" +.sM +.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. +.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 +.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 +For any given quark, if +.PN XrmStringToQuark +returns a non-NULL value, +all future calls will return the same value (identical address). +.LP +.sp +To convert a quark to a string, use +.PN XrmQuarkToString . +.IN "XrmQuarkToString" "" "@DEF@" +.sM +.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. +.LP +.eM +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, +.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@" +.sM +.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. +The caller must allocate sufficient space for the quarks list before calling +.PN XrmStringToQuarkList . +.LP +.eM +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@" +.sM +.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 . +.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: +.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, the strings ``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@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + unsigned int size; + XPointer addr; +} XrmValue, *XrmValuePtr; +.De +.LP +.eM +.sp +To initialize the resource manager, use +.PN XrmInitialize . +.IN "XrmInitialize" "" "@DEF@" +.sM +.FD 0 +void XrmInitialize\^(\|); +.FN +.LP +.eM +To retrieve a database from disk, use +.PN XrmGetFileDatabase . +.IN "XrmGetFileDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^) +.br + char *\fIfilename\fP\^; +.FN +.IP \fIfilename\fP 1i +Specifies the resource database file name. +.LP +.eM +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 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, +.PN XrmGetFileDatabase +returns NULL. +.LP +.sp +To store a copy of a database to disk, use +.PN XrmPutFileDatabase . +.IN "XrmPutFileDatabase" "" "@DEF@" +.sM +.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. +.LP +.eM +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@" +.sM +.FD 0 +char *XResourceManagerString\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XResourceManagerString +function 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 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 +.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@" +.sM +.FD 0 +char *XScreenResourceString\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the screen. +.LP +.eM +The +.PN XScreenResourceString +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 +.PN XmbTextPropertyToTextList +for a single element STRING property. +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 by using +.PN XFree . +.LP +.sp +To create a database from a string, use +.PN XrmGetStringDatabase . +.IN "XrmGetStringDatabase" "" "@DEF@" +.sM +.FD 0 +XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^) +.br + char *\fIdata\fP\^; +.FN +.IP \fIdata\fP 1i +Specifies the database contents using a string. +.LP +.eM +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 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. +.LP +.sp +To obtain the locale name of a database, use +.PN XrmLocaleOfDatabase . +.IN "XrmLocaleOfDatabase" "" "@DEF@" +.sM +.FD 0 +char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.LP +.eM +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@" +.sM +.FD 0 +void XrmDestroyDatabase\^(\^\fIdatabase\fP\^) +.br + XrmDatabase \fIdatabase\fP\^; +.FN +.IP \fIdatabase\fP 1i +Specifies the resource database. +.LP +.eM +If database is NULL, +.PN XrmDestroyDatabase +returns immediately. +.LP +.sp +To associate a resource database with a display, use +.PN XrmSetDatabase . +.IN "XrmSetDatabase" "" "@DEF@" +.sM +.FD 0 +void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdatabase\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdatabase\fP 1i +Specifies the resource database. +.LP +.eM +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@" +.sM +.FD 0 +XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +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, use +.PN XrmCombineFileDatabase . +.IN "XrmCombineFileDatabase" "" "@DEF@" +.sM +.FD 0 +Status 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. +.IP \fIoverride\fP 1i +Specifies whether source entries override target ones. +.LP +.eM +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 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, +.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@" +.sM +.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. +.LP +.eM +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@" +.sM +.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. +.LP +.eM +Calling the +.PN XrmMergeDatabases +function is equivalent to calling the +.PN XrmCombineDatabase +function with an override argument of +.PN True . +.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@" +.sM +.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. +.LP +.eM +.sp +.IN "XrmQGetResource" "" "@DEF@" +.sM +.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. +.LP +.eM +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 +.EQ +delim %% +.EN +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 +.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@" +.sM +.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. +.LP +.eM +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@" +.sM +.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. +.LP +.eM +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@" +.sM +.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. +.LP +.eM +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@" +.sM +.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. +.LP +.eM +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 type and value are replaced by the new +specified type and 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@" +.sM +.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. +.LP +.eM +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@" +.sM +.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. +.LP +.eM +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@" +.sM +.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. +.LP +.eM +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 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 +.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@" +.sM +.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 +.FD 0 +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. +.LP +.eM +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 , +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 \fIarg\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. +.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. +.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@" +.sM +.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 +.LP +.eM +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@" +.sM +.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 +.LP +.eM +.sp +To load a resource database from a C command line, use +.PN XrmParseCommand . +.IN "XrmParseCommand" "" "@DEF@" +.sM +.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. +.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. +.LP +.eM +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 +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 +.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. +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. +.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 |