XtGetApplicationResources()XtGetApplicationResources()Name
XtGetApplicationResources - set application variables from the resource
database.
Synopsis
void XtGetApplicationResources(object, base, resources, num_resources,
args, num_args)
Widget object;
XtPointer base;
XtResourceList resources;
Cardinal num_resources;
ArgList args;
Cardinal num_args;
Inputs
object Specifies the object that identifies the resource database to
search; may be of class Object or any subclass.
base Specifies the base address of the structure into which the
resource values will be written.
resources Specifies the application's resource list.
num_resources
Specifies the number of resources in the resource list.
args Specifies the argument list to override other resource speci‐
fications, or NULL.
num_args Specifies the number of arguments in the argument list.
Outputs
base Returns the resource values from the argument list, the
resource database, or the resource list defaults.
DescriptionXtGetApplicationResources() retrieves resource settings that apply to
an overall application, rather than to a particular widget. For each
resource in resources, XtGetApplicationResource() sets a value in the
structure pointed to by base. This value comes from the argument list
args, or if no value for the resource is found in the argument list,
from the resource database associated with object, or if no value is
found in the database, from the default_addr field of the resource
itself. Once the value is determined, it is copied into the structure
at base using the resource_offset and resource_size fields of the
resource.
The search of the database is done using the resource_name and
resource_class fields of the resource. Resources are searched for at
the level in the resource name hierarchy at which object's resources
are found, i.e., application resources are set in a resource database
in the same way as the specified object's resources are set.
XtGetApplicationResources() may overwrite the specified resource list
with an equivalent representation in an internal format that optimizes
access time if the list is used repeatedly. The resource list must be
allocated in writable storage and the caller must not modify the list
contents after the call if the same list is to be used again. Any per-
display resources fetched by XtGetApplicationResources() will not be
freed from the resource cache until the display is closed.
The use of each of the fields in the XtResource structure is explained
in detail in the "Background" section below.
Usage
Any application that has any configurability should define application
resources as an alternative to command line options and configuration
files. To do this, you declare a structure that contains a field for
each of the resource values you want to look up in the database. Then
you statically initialize an array of XtResource structures which
describe the name, class, type and default of each resource, and also
specify the size of the resource value and the location within your
structure at which it should be stored. Next you call XtGetApplica‐
tionResources() with the address of your structure and your application
resource list, and possibly an argument list of values to override the
database. When XtGetApplicationResources() returns, your structure
will be initialized with values from the argument list, the resource
database, or from the resource list defaults. The "Example" section
below shows an example of this process, and the "Background" section
explains each of the fields of an XtResource structure in more detail.
Usually, you will pass a the shell widget returned by XtAppInitialize()
as object. This will make XtGetApplicationResources() look up
resources of the form application_name.resource_name. You may use any
other widget or object, but this will make XtGetApplicationResources()
look up resources that are deeper in the hierarchy, resources that
appear to be resources of the specified widget.
Example
Here is a short program that declares and initializes an application
resource list and uses it to get the value of some application
resources.
#include <X11/StringDefs.h>
#include <X11/Intrinsic.h>
/*
* fields to be filled in from resources
*/
typedef struct {
Pixel highlight_color;
XFontStruct *bold_font;
Boolean palette_on_left;
} application_variable_rec;
static XtResource resources[] = {
{"highlightColor", XtCForeground, XtRPixel, sizeof(Pixel),
XtOffsetOf(application_variable_rec, highlight_color),
XtRString, XtDefaultForeground
},
{"boldFont", XtCFont, XtRFontStruct, sizeof(XFontStruct *),
XtOffsetOf(application_variable_rec, bold_font),
XtRString, XtDefaultFont
},
{"paletteOnLeft", "PaletteOnLeft", XtRBoolean, sizeof(Boolean),
XtOffsetOf(application_variable_rec, palette_on_left),
XtRImmediate, True
}
};
main(argc, argv)
int argc;
char **argv;
{
XtAppContext app_context;
Widget toplevel;
application_variable_rec app_vars;
toplevel = XtAppInitialize(&app_context, "XDraw",
NULL, 0, &argc, argv,
NULL, NULL, 0);
XtGetApplicationResources(toplevel, /* widget */
&app_vars, /* base address */
resources, /* resource list */
XtNumber(resources), /* how many */
NULL, 0); /* ArgList */
.
.
.
}
If the application name is "xdraw", then the application resources can
be set with lines like the following in a resource file:
xdraw.highlightColor: blue
xdraw.boldFont: *-helvetica-bold-r-*-*-*-180-*
xdraw.paletteOnLeft: False
Background
To use XtGetApplicationResources(), you must initialize an array of
XtResource structures which describe the resources you want to obtain.
The XtResource structure is shown in the "Structures" section below.
The fields of this structure are used as follows:
resource_name
This field specifies the name of the resource, i.e., the name that
must appear in a resource file to set this resource. By convention,
the first letter of a resource name is lowercase, and any subsequent
words are capitalized and concatenated without a hyphen or under‐
score-"background" and "backgroundPixmap", for example. If you
define a symbolic constant for the resource name, it should be the
same as the resource name, with a prefix, which should end with an
`N'-XtNbackground or XmNbackgroundPixmap, for example. It is also
convention that the field in which this resource's value will be
stored has the same name as the resource, using all lowercase let‐
ters, and underscores to separate words--background and back‐
ground_pixmap, for example. Resource names beginning with "xt" are
reserved by the Intrinsics.
resource_class
This field specifies the class name of the resource. If a number of
resources have the same class, you can specify a value for all those
resources with a single line in a resource file. The "normalFont"
and "boldFont" resources might both be of class "Font", for example.
Class names conventionally begin with capital letters, and, as with
resource names, subsequent words are capitalized and underscores are
not used. Symbolic names for class names are conventionally spelled
the same way as the class name with a prefix which ends with
`C'--XtCFont, for example. If there is no general category to use
for a resource's class, the class should be the same as the resource
name, but capitalized. Class names beginning with "Xt" are reserved
by the Intrinsics.
resource_type
This field is a string that identifies the type of the resource. By
convention, it is spelled the same way as the type of the field that
this resource will set, but begins with a capital letter. Symbolic
names for resource types are spelled the same as the type name, but
begin with a prefix which end with `R'--XtRInt and XmRFontList, for
example. The Intrinsics predefine a number of types which are shown
in the table below. Type names are used to identify which resource
converter should be used to convert a string value from the resource
database into the appropriate type. If one of your fields is not of
one of the standard types listed below, use a type of your own, but
be aware that you will have to write and register a converter proce‐
dure if you want to get values for that field from the resource data‐
base.
resource_size
This field specifies the size in bytes of the field in your structure
that this resource will set. Use the sizeof() operator to compute
this value.
resource_offset
This field specifies the offset of this resource's field from the
beginning of the structure. This value is added to the base argument
passed to XtGetApplicationResources() in order to determine where the
resource value is to be stored. This field plus the resource_size
field provide enough information to correctly store the resource
value. Use the XtOffsetOf() macro to determine the offset of a field
in a structure.
default_type
This is a string which specifies the type of the default value in the
default_addr field. It is the same sort of type as the resource_type
field explained above. The type of the default does not have to be
the same as the type of resource. If they do not match, an appropri‐
ate resource converter will be invoked to convert the default value
when it is required. In addition to the types listed in the table
below, and any types of your own definition, there are two special
values that can be set in this field. If default_type is
XtRImmediate, then default_addr is interpreted as the resource value
itself, rather than a pointer to the value. This is useful for
resources that are integers, Booleans, or other scalar types. If
default_type is XtRCallProc, then default_addr is pointer to a proce‐
dure of type XtResourceDefaultProc which is responsible for storing
the default value in the correct location. See XtResourceDefault‐
Proc(2) for details on the responsibilities of such a procedure.
default_addr
This field specifies a pointer to the default value of the resource,
which must be of the type identified by default_type. This field is
interpreted differently for types
XtRImmediate and XtRCallProc, as explained above. Also, if
default_type is XtRString, then default_addr is the string itself,
not the address of the string (i.e., it is a char *, not a char **).
The Intrinsics define symbolic names for a number of strings which rep‐
resent commonly used types. These symbolic names and the types they
represent are shown in the table below.
Resource Type C Type Resource Type C Type
XtRAcceleratorTable XtAccelerators XtRInitialState int
XtRAtom Atom XtRInt int
XtRBitmap Pixmap, depth=1 XtRLongBoolean long
XtRBoolean Boolean XtRObject Object
XtRBool Bool XtRPixel Pixel
XtRCallback XtCallbackList XtRPixmap Pixmap
XtRCardinal Cardinal XtRPointer XtPointer
XtRColor XColor XtRPosition Position
XtRColormap Colormap XtRScreen Screen*
XtRCursor Cursor XtRShort short
XtRDimension Dimension XtRString String
XtRDisplay Display* XtRStringArray String*
XtREnum XtEnum XtRStringTable String*
XtRFile FILE* XtRTranslationTable XtTranslations
XtRFloat float XtRUnsignedChar unsigned char
XtRFont Font XtRVisual Visual*
XtRFontSet XFontSet XtRWidget Widget
XtRFontStruct XFontStruct* XtRWidgetClass WidgetClass
XtRFunction (*)() XtRWidgetList WidgetList
XtRGeometry char* XtRWindow Window
Structures
XtResource is defined as follows:
typedef struct _XtResource {
String resource_name; /* Resource name */
String resource_class; /* Resource class */
String resource_type; /* Representation type desired */
Cardinal resource_size; /* Size in bytes of representation */
Cardinal resource_offset;/* Offset from base to put resource value */
String default_type; /* Representation type of specified default */
XtPointer default_addr; /* Address of resource default value */
} XtResource, *XtResourceList;
The ArgList type is defined as follows:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
See AlsoXtGetSubresources(1), XtOffsetOf(1).
Xt - Resource Management XtGetApplicationResources()
