Motif Programmer's Guide Migration Version

Motif 2.1 Programmer's Guide

Initializing the Intrinsics

The first task of a Motif application is to initialize the Intrinsics. Most applications can perform the initialization by calling the routine XtAppInitialize. This is a convenience routine that combines several initialization steps, each of which the application can take separately by calling a specialized Xt routine:

Initialize the state of the Intrinsics. An application can also do this by calling XtToolkitInitialize.

Create an application context. Xt uses this construct to contain the information it associates with each instance of an application. Its purpose is to allow multiple instances of an application to run in a single address space. Most applications need only create an application context and pass it to Intrinsics routines that take an application context as an argument. The data type is XtAppContext. An application can create an application context explicitly by calling XtCreateApplicationContext.

Open a connection to a display and attach it to an application context. When an application uses XtAppInitialize, the display specification comes from the command line invoking the application or from the user's environment. After opening the display, Xt builds a resource database by processing resource defaults and command-line options. The construction of this database is described in the next section. An application can perform these steps explicitly by calling XtOpenDisplay. If an application already has an open display as a result of calling XOpenDisplay, it can attach the display to an application context and build the initial resource database by calling XtDisplayInitialize.

Create a top-level shell widget for the application. XtAppInitialize creates an ApplicationShell and returns it as the function's return value. An application can create a top-level shell by calling XtAppCreateShell.

Following is an example of a simple call to XtAppInitialize:

int main(int argc, char **argv)
{
    Widget         app_shell;
    XtAppContext   app;
    app_shell = XtAppInitialize(&app, "Example",
        (XrmOptionDescList) NULL, 0, &argc, argv,
        (String *) NULL, (ArgList) NULL, 0);
}

The Initial Resource Database

The XtDisplayInitialize routine builds the initial resource database for the application. An application rarely needs to call this routine directly; it is called by XtOpenDisplay, which in turn is called by XtAppInitialize.

XtDisplayInitialize builds a separate resource database for each display connection. The initial database combines resource settings from the command line, the display, an application class defaults file, and user defaults files that may be specialized according to the application or the host on which the application is running. The application class defaults and the user's per-application defaults may be further specialized according to the language environment and possibly according to a general-purpose customization resource. The resources in the initial database may pertain to particular widgets or widget classes or to the application as a whole. When the application creates widgets, the resource settings from the database are often the source for the initial values of widget resources.

The remainder of this section describes the order in which XtDisplayInitialize loads each component of the database and how it derives the location of that component.

File Search Paths

In loading the application class defaults and the user's per-application defaults, XtDisplayInitialize calls XtResolvePathname to determine which files to read. XtResolvePathname uses file search paths. Each path is a set of patterns that may contain special character sequences for which XtResolvePathname substitutes runtime values when it searches for a file. It uses the following substitutions in building the path:

%N is replaced by the class name of the application, as specified by the application_class argument to XtAppInitialize, XtOpenDisplay, or XtDisplayInitialize.

%C is replaced by the value of the customization resource.

%L is replaced by the display's language specification. This may come from the xnlLanguage resource, the locale of the application, or an application callback procedure. See Chapter 11 for more information. The format of the language specification is implementation dependent; it may have language, territory, and code set components.

%l is replaced by the language part of the language specification.

%t is replaced by the territory part of the language specification.

%c is replaced by the code set part of the language specification.

%% is replaced by %.

If the language specification is not defined, or if one of its parts is missing, a % element that references it is replaced by NULL.

The paths contain a series of elements separated by colons. Each element denotes a filename, and the filenames are looked up left-to-right until one of them succeeds. Before doing the lookup, substitutions are performed.

Note:

The Intrinsics use the X/Open convention of collapsing multiple adjoining slashes in a filename into one slash.

Initial Database Components

The XtDisplayInitialize function loads the resource database by merging in resources from these sources, in order of precedence (that is, each component takes precedence over the following components):

The application command line

Per-host user environment resource file on the local host

Screen-specific resources for the default screen of the display

Resource property on the server or user preference resource file on the local host

Application-specific user resource file on the local host

Application-specific class resource file on the local host

Command-Line Specifications

XtDisplayInitialize calls the X Resource Manager function XrmParseCommand to extract resource settings from the command line by which the user invoked the application. The arguments and number of arguments on the command line come from the argv and argc arguments to XtAppInitialize, XtOpenDisplay, or XtDisplayInitialize. Xt maintains a standard set of command-line options, such as -background and -geometry, for specifying resource settings. An application can specify additional options in arguments to XtAppInitialize, XtOpenDisplay, or XtDisplayInitialize. The user can supply the -xrm option to set any resource in the database.

Per-Host User Resources

To load the per-host user environment resources, XtDisplayInitialize uses the filename specified by the XENVIRONMENT environment variable. If XENVIRONMENT is not defined, XtDisplayInitialize looks for the file $HOME/.Xdefaults- host, where host is the name of the host on which the application is running (that is, the name of the client host, not the server host).

Screen-Specific Resources

To load screen-specific resources, XtDisplayInitialize looks for a SCREEN_RESOURCES property on the root window of the default screen of the display. The SCREEN_RESOURCES property typically results from invoking the xrdb command when some resources are not defined for all screens.

Note:

When Xt needs to fetch resources for a screen other than the default screen of the display--for example, when the application creates a widget on another screen--it uses the SCREEN_RESOURCES property of that screen instead of the SCREEN_RESOURCES property of the default screen.

Server or User-Preference Resources

To load the server resource property or user preference file, XtDisplayInitialize first looks for a RESOURCE_MANAGER property on the root window of the display's screen 0. The RESOURCE_MANAGER property typically results from invoking the xrdb command when some resources are defined for all screens. If that property does not exist, XtDisplayInitialize looks for the file $HOME/.Xdefaults.

User Application File

To load the user's application resource file, XtDisplayInitialize performs the following steps:

Use XUSERFILESEARCHPATH to look up the file, performing appropriate substitutions.

If that fails, or if XUSERFILESEARCHPATH is not defined, and if XAPPLRESDIR is defined, use an implementation-dependent search path containing at least seven entries, in the following order and with the following directory prefixes and substitutions:

$XAPPLRESDIR with %C, %N, %L or with %C, %N, %l, %t, %c
 
$XAPPLRESDIR with %C, %N, %l
 
$XAPPLRESDIR with %C, %N
 
$XAPPLRESDIR with %N, %L or with %N, %l, %t, %c
 
$XAPPLRESDIR with %N, %l
 
$XAPPLRESDIR with %N
$HOME with %N

where $XAPPLRESDIR is the value of the XAPPLRESDIR environment variable and $HOME is the user's home directory.

If XAPPLRESDIR is not defined, use an implementation-dependent search path containing at least six entries, in the following order and with the following directory prefixes and substitutions:

$HOME with %C, %N, %L or with %C, %N, %l,
%t, %c
$HOME with %C, %N, %l
$HOME with %C, %N
$HOME with %N, %L or with %N, %l, %t, %c
$HOME with %N, %l
$HOME with %N

Application Class Resource File

To load the application-specific class resource file, XtDisplayInitialize performs the appropriate substitutions on the path specified by the XFILESEARCHPATH environment variable. If that fails, or if XFILESEARCHPATH is not defined, XtDisplayInitialize uses an implementation-dependent search path containing at least six entries, in the following order and with the following substitutions:

%C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c
%C, %N, %S, %T, %l
%C, %N, %S, %T
%N, %S, %T, %L or %N, %S, %T, %l, %t, %c
%N, %S, %T, %l
%N, %S, %T

where the substitution for %S is usually NULL and the substitution for %T is usually app-defaults.

If no application-specific class resource file is found, XtDisplayInitialize looks for any fallback resources that may have been defined by a call to XtAppInitialize or XtAppSetFallbackResources.