XrmQGetSearchList()XrmQGetSearchList()Name
XrmQGetSearchList – return a list of database levels.
Synopsis
Bool XrmQGetSearchList(database, names, classes,
list_return, list_length)
XrmDatabase database;
XrmNameList names;
XrmClassList classes;
XrmSearchList list_return;
int list_length;
Arguments
database Specifies the database to be searched.
names Specifies a list of resource names.
classes Specifies a list of resource classes.
list_return
Returns a search list for further use. The caller must allo‐
cate sufficient space for the list before calling XrmQGet‐
SearchList().
list_length
Specifies the number of entries (not the byte size) allocated
for list_return.
Returns
True if list_return was large enough for the search list, else False.
DescriptionXrmQGetSearchList() is a tool for searching the database more effi‐
ciently. It is used in combination with XrmQGetSearchResource().
Often, one searches the database for many similar resources which dif‐
fer only in their final component (e.g., xmh.toc.foreground,
xmh.toc.background, etc). Rather than looking for each resource in its
entirety, XrmGetSearchList searches the database for the common part of
the resource name, returning a whole list of items in the database that
match it. This list is called the search list. This search list is
then used by XrmQGetSearchList(), which searches for the last compo‐
nents one at a time. In this way, the common work of searching for
similar resources is done only once, and the specific part of the
search is done on the much shorter search list.
XrmQGetSearchList() 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 XrmGetRe‐
source() for determining precedence. If list_return was large enough
for the search list, XrmQGetSearchList() returns True. Otherwise, it
returns False.
The size of the search list that must be allocated by the caller is
dependent upon the number of levels and wildcards in the resource spec‐
ifiers that are stored in the database. The worst case length is 3n ,
where n is the number of name or class components in names or classes.
Only the common prefix of a resource name should be specified in the
name and class list to XrmQGetSearchList(). In the example above, the
common prefix would be xmh.toc. However, note that XrmQGetSearchRe‐
source() requires that name represent a single component only. There‐
fore, the common prefix must be all but the last component of the name
and class.
For more information, see Volume One, Chapter 13, Managing User Prefer‐
ences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
typedef XrmQuark XrmRepresentation;
XrmSearchList is a pointer to an opaque data type.
See AlsoXrmDestroyDatabase(), XrmGetFileDatabase(), XrmGetResource(), XrmGet‐
StringDatabase(), XrmInitialize(), XrmMergeDatabases(), XrmParseCom‐
mand(), XrmPutFileDatabase(), XrmPutLineResource(), XrmPutResource(),
XrmPutStringResource(), XrmQGetResource(), XrmQGetSearchResource(),
XrmQPutResource(), XrmQPutStringResource(), XrmQuarkToString(), Xrm‐
StringToBindingQuarkList(), XrmStringToQuarkList(), XrmStringToQuark(),
XrmUniqueQuark().
Xlib - Resource Manager XrmQGetSearchList()
