XtInitialize(Xt) UNIX System V
NAME
o XtInitialize - a function that initializes the toolkit and
returns a top-level shell.
SYNOPSIS
#include <Xm/Xm.h>
Widget XtInitialize (shell_name, application_class, options,
num_options, argc, argv)
String shell_name;
String application_class;
XrmOptionDescRecoptions;
Cardinal num_options;
Cardinal * argc;
String argv;
DESCRIPTION
The Xt Intrinsics must be initialized before making any
other calls to Xt Intrinsics functions. XtInitialize
establishes the connection to the display server, parses the
command line that invoked the application, loads the
resource database, and creates a shell widget to serve as
the parent of your application widgets.
By passing the command line that invoked your application to
XtInitialize, the function can parse the line to allow users
to specify certain resources (such as fonts and colors) for
your application at run time. XtInitialize scans the
command line and removes those options. The rest of your
application sees only the remaining options.
There is an alternate set of functions that you can use to
initialize the Xt Intrinsics that is not as convenient as
XtInitialize; however, it is more flexible because it lets
you decide the type of shell you want to use. The function
o XtToolkitInitialize just initializes the toolkit. It does
not open the display or create an application shell. You
must do this yourself using XtOpenDisplay and
XtAppCreateShell.
XtInitialize supports localization of defaults files based
on the value of the LANG environment variable. The user can
specify a language by using the LANG environment variable.
Elements of this variable are then used to establish a path
to the proper resource files. The following substitutions
are used in building the path:
⊕ %N is replaced by class_name of the application.
⊕ %L is replaced by the value of LANG environment variable.
⊕ %l is replaced by the language part of LANG environment
variable.
⊕ %t is replaced by the territory part of LANG environment
variable.
⊕ %c is replaced by the code set part of LANG environment
variable.
⊕ %% is replaced by %.
If the LANG environment variable is not defined, or if one
of its parts is missing, then a % element that references it
is replaced by NULL.
The paths contain a series of elements separated by colons.
Each element denotes a file name, and the file names are
looked up left to right till one of them succeeds. Before
doing the lookup, substitutions are performed.
NOTE: We are using the X/Open convention of collapsing
multiple adjoining slashes in a filename into one slash.
The XtInitalize function loads the resource database by
merging in resources from these sources:
⊕ Application-specific class resource file on the local
host.
⊕ Application-specific user resource file on the local
host.
⊕ Resource property on the server or user preference
resource file on the local host.
⊕ Per-host user environment resource file on the local
host.
⊕ The application command line (argv).
To load the application-specific class resource file,
XtInitialize performs the appropriate substitutions on this
path:
⊕ /usr/lib/X11/%L/app-defaults/%N:/usr/lib/X11/app-
defaults/%N
If LANG environment variable is not defined (or the first
path lookup using LANG fails), then the lookup will default
to the current non-language specific location
(/usr/lib/X11/app_defaults/%N).
To load the user's application resource file, XtInitialize
performs the following steps:
⊕ Use XAPPLRESLANGPATH environment variable to look up the
file. A possible value for XAPPLRESLANGDIR is:
./%N:$HOME/app-defaults/%L/%N:$HOME/app-defaults/%N:$HOME/%L/%N:$HOME/%N
⊕ If that fails, or if XAPPLPRESLANGPATH is not defined,
and if XAPPLRESDIR is defined, use the following as the
path:
XAPPLRESDIR%L/%N:XAPPLRESDIR%N
⊕ else use:
$HOME/%L/%N:$HOME/%N
Note that if the XAPPLRESLANGPATH lookup is not successful
and LANG is not defined the lookup is then equivalent to
that used by the R3 specification of XtInitialize (actually
described under XtDisplayInitialize).
The parameters for XtInitialize are defined below:
shell_name Specifies the name of the application shell
widget instance, which usually is something
generic like ``main.'' This name is used by the
Xt Intrinsics to search for resources that
belong specifically to this shell widget. The
application name is derived from the -name
command line argument or if that is not present
the trailing component of argv[0].
application_class
Specifies the class name of this application,
which usually is the generic name for all
instances of this application. By convention,
the class name is formed by reversing the case
of the application's first letter. The class
name is used to locate the files used to
initialize the resource database.
options Specifies how to parse the command line for any
application-specific resources. The options
argument is passed as a parameter to
XrmParseCommand.
num_options Specifies the number of entries in options list.
argc Specifies a pointer to the number of command
line parameters.
argv Specifies the command line parameters.
RETURN VALUE
Returns the widget ID of the top-level shell. The class of
the shell is ApplicationShellWidgetClass.
RELATED INFORMATION
XtDisplayInitialize(Xt).
(printed 2/19/90) XtInitialize(Xt)