diff options
Diffstat (limited to 'libX11/specs/libX11/CH15')
| -rw-r--r-- | libX11/specs/libX11/CH15 | 1628 |
1 files changed, 0 insertions, 1628 deletions
diff --git a/libX11/specs/libX11/CH15 b/libX11/specs/libX11/CH15 deleted file mode 100644 index a10df0a53..000000000 --- a/libX11/specs/libX11/CH15 +++ /dev/null @@ -1,1628 +0,0 @@ -.\" 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 |