Query: xtgetapplib
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
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 specifications, 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.
Description
XtGetApplicationResources() 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 struc-
ture 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 opti-
mizes 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 configura-
tion 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 XtGetAppli-
cationResources() with the address of your structure and your application resource list, and possibly an argument list of values to over-
ride 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 XtGetApplicationRe-
sources() 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 conven-
tion that the field in which this resource's value will be stored has the same name as the resource, using all lowercase letters, and
underscores to separate words--background and background_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 procedure 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 appropriate 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 represent 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 Also
XtGetSubresources(1), XtOffsetOf(1).
Xt - Resource Management XtGetApplicationResources()