XtAppInitialize()XtAppInitialize()NameXtAppInitialize - initialize the X Toolkit internals, create an appli‐
cation context, open and initialize a display, and create the initial
application shell instance.
Synopsis
Widget XtAppInitialize(app_context_return, application_class, options,
num_options, argc_in_out, argv_in_out, fallback_resources, args,
num_args)
XtAppContext *app_context_return;
String application_class;
XrmOptionDescList options;
Cardinal num_options;
int *argc_in_out; /* was type Cardinal * in R4 */
String *argv_in_out;
String *fallback_resources;
ArgList args;
Cardinal num_args;
Inputs
application_class
Specifies the class name of the application.
options Specifies an array of XrmOptionDescRec which describe
how to parse the command line.
num_options Specifies the number of elements in options.
argc_in_out Specifies the address of the number of command line
arguments. This argument is of type int * in Release 5
and of type Cardinal * in Release 4.
argv_in_out Specifies the array of command line arguments.
fallback_resources
Specifies a NULL-terminated array of resource specifica‐
tion strings to be used if the application class
resource file cannot be opened or read, or NULL if no
fallback resources are desired.
args Specifies an argument list to override any other
resource specifications for the created shell widget.
num_args Specifies the number of elements in args.
Outputs
app_context_return
Returns the newly created application context, if non-
NULL.
argc_in_out Returns the number of command line arguments remaining
after the command line is parsed by XtDisplayInitial‐
ize().
argv_in_out Returns the command line as modified by XtDisplayIni‐
tialize().
Returns
A toplevel shell widget of class applicationShellWidgetClass.
Availability
Release 4 and later.
DescriptionXtAppInitialize() is a convenience procedure that most applications
will use to initialize themselves. It does the following:
· Calls XtToolkitInitialize() to do Intrinsics internal initializa‐
tion.
· Calls XtCreateApplicationContext() to create an application context
for the application. If app_context_return is non-NULL, the newly
created application context is stored at the address it points to.
· Calls XtAppSetFallbackResources() passing the application context
and fallback_resources, unless that argument is NULL.
· Calls XtOpenDisplay() passing the application context, applica‐
tion_class, options, num_options, argc_in_out, and argv_in_out.
XtOpenDisplay() determines the display name and the application name
from the command line or environment variables, opens a connection
to the display, and calls XtDisplayInitialize() to parse the command
line and build the resource database. The command line as modified
by XtDisplayInitialize() is returned in argc_in_out and argv_in_out.
See the "Background" section below for more details on all of these
steps.
· Calls XtAppCreateShell() to create an applicationShellWidgetClass
shell, passing args and num_args to override any resources found in
the database.
If the display cannot be opened, an error message is issued and XtAp‐
pInitialize() terminates the application.
Usage
Most applications can XtAppInitialize() to initialize themselves. Most
programmers will not need to understand the details of initialization
described in the "Background" section below. Applications that open
multiple displays or create multiple application contexts will have to
use the lower-level initialization functions explicitly.
Most applications can have all their command-line options automatically
parsed by declaring an XrmOptionDescList and passing it to XtAppIni‐
tialize() which will convert values on the command line into values in
the resource database which can then be retrieved into a structure with
XtGetApplicationResources(). This is a good idea, because if your
application supports customization through application resources (which
it should if there is anything to customize) then customization through
the command line comes essentially for free.
If all your command line options are parsed this way, then XtAppIni‐
tialize() should remove everything except argv[0] from the command line
and should set argc to 1. If this is not the case when XtAppInitial‐
ize() returns, then the user has requested an unrecognized option. If
you parse some command line options manually, you should parse them
after calling XtAppInitialize().
The "Background" section below explains how to declare an XrmOptionDe‐
scList and the example below shows the one used by viewres.
The fallback_resources argument is an array of strings, each string
equivalent to a line in a resource file. If your application relies on
an app-defaults file, you can use fallback resources as a backup to be
used in case the app-defaults file is installed incorrectly or other‐
wise cannot be found. If the application needs many resources to func‐
tion properly, your fallback resources might simply set a label widget
to display an error message which informs the user that the app-
defaults file could not be found. The example below shows a simple
fallback resource list.
In Release 4, the argc_in_out argument is of type Cardinal *, and in
Release 5, this argument is of type int *. This is a minor incompati‐
bility that may result warnings from ANSI-C compilers when porting from
one release to another. The example below shows a way around this
problem.
XtVaAppInitialize() performs the same function as XtAppInitialize(),
but accepts a NULL-terminated variable-length argument list of resource
name/resource value pairs instead of an ArgList.
Example
The following initialization code is adapted from the X11R5 viewres
application.
static XrmOptionDescRec Options[] = {
{ "-top", "*topObject", XrmoptionSepArg, (XPointer) NULL },
{ "-variable", "*showVariable", XrmoptionNoArg, (XPointer) "on" },
{ "-vertical", "*Tree.Gravity", XrmoptionNoArg, (XPointer) "north" }
};
static char *fallback_resources[] = {
"*allowShellResize: true",
"*Porthole.top: ChainTop",
"*Porthole.left: ChainLeft",
"*Porthole.bottom: ChainBottom",
"*Porthole.right: ChainRight",
"*Porthole.resizable: on",
(char *) NULL
};
main (argc, argv)
int argc;
char **argv;
{
Widget toplevel;
XtAppContext app_con;
toplevel = XtAppInitialize(&app_con, "Viewres",
Options, XtNumber (Options),
#if XtSpecificationRelease > 4
&argc,
#else
(Cardinal *)&argc,
#endif
argv,
fallback_resources,
(ArgList) NULL, (Cardinal) 0);
if (argc != 1) display_usage_message();
.
.
.
}
Background
Initializing an application is a complex process. It involves deter‐
mining the display to be opened, determining the name of the applica‐
tion, setting the locale of the application, determining the screen on
which to create the shell widget, parsing the command line, and build‐
ing the resource database. Each of these tasks is described in detail
below. Some of the details have changed between Release 4 and Release
5. Release 5 is described below.
Determining Which Display to OpenXtAppInitialize() calls XtOpenDisplay() with NULL for its display_name
argument. XtOpenDisplay() determines which display to open by first
checking the command line (note that the command line has not been
parsed at this point) for a -display command line option, and if that
is not found, using the value of the DISPLAY environment variable (on
POSIX systems). The name is used in a call to XOpenDisplay().
Determining the Application NameXtOpenDisplay() also determines the name of the application. It checks
for the name in the following four locations and uses the first one it
finds:
· the value of the -name command line option.
· the value of its application_name argument. Note that XtAppInitial‐
ize() always passes NULL for this value.
· the value of the RESOURCE_NAME environment variable.
· the first word on the command line, argv[0], stripped of any leading
directories.
If the name is not found in any of these sources, "main" is used. This
name is passed to XtDisplayInitialize() to be used in building the
resource database, and will later be used by XtAppCreateShell() to name
the application's toplevel shell widget.
Establishing the Application's LocaleXtDisplayInitialize() determines an application's "language string" by
searching for the -xnlLanguage command line option, an -xrm command
line option that sets the xnlLanguage resource, or a value for the xnl‐
Language option in the user's personal resource database (i.e., the
resources set on the display with xrdb, or the resources in the .Xde‐
faults file.)
In Release 5, if a language procedure has been registered (see XtSet‐
LanguageProc()) then the language string is passed to this language
procedure. The language procedure localizes the application, usually
by calling setlocale(), and returns a string which becomes the new
value of the application's language string. If a language procedure
has not been set, and in Release 4, the LANG environment variable is
used for the language string if no command line argument or resource
value is found.
In either Release 4 and Release 5, the language string is associated
with the display and used in future calls to XtResolvePathname() so
that file customized for a particular language can be found. See
XtDisplayInitialize() and XtSetLanguageProc() for more detail on this
process.
Parsing the Command LineXtDisplayInitialize() parses the application command line by merging
options into the standard Xt command line options table and calling
XrmParseCommand(). Each element in options and the Xt options table is
a XrmOptionDescRec structure (shown in the "Structures" section below)
which describes how to parse a single command line argument. The
fields of this structure are as follows:
option
The string to be searched for on the command line. As with stan‐
dard command-line options, Xt will automatically accept any unique
abbreviation of the option specified here. For example, the
option -pixmapWidthInPixels will be recognized if typed on the
command line as -pixmapW. However, if you wanted the option -pw
to set the same resource, then you would need another entry, since
pw is not the leading string of pixmapWidthInPixels.
specifier
The resource specification. This string must identify a widget
resource or an application resource, but not provide a value.
Since it has the same form as allowed in the resource databases,
it may apply to a single widget or to many widgets. If it applies
to no widgets, no error message will be issued.
argKind
The argument style. This field is of type XrmOptionKind which
describes how the option is to be interpreted. These constants
are described below.
value
If argKind is XrmOptionNoArg, this field specifies the resource
value (a string) to be inserted into the database. If argKind is
XrmOptionSkipNArgs, this field specifies the number of arguments
to skip (you'll need to use a cast to set this field to an inte‐
ger). For other values of argKind, this field is not used.
The possible values for XrmOptionKind and their meanings are as fol‐
lows:
XrmoptionNoArg
Take the value in the value field of the options table. For exam‐
ple, this is used for Boolean fields, where the option might be
-debug and the default value False.
XrmoptionIsArg
The flag itself is the value without any additional information.
For example, if the option were -on, the value would be "on."
This constant is infrequently used, because the desired value such
as "on" is usually not descriptive enough when used as an option
(-on).
XrmoptionStickyArg
The value is the characters immediately following the option with
no white space intervening. This is the style of arguments for
some POSIX utilities such as uucico where -sventure means to call
system venture.
XrmoptionSepArg
The next item after the white space after this flag is the value.
For example, -fg blue would indicate that blue is the value for
the resource specified by -fg.
XrmoptionResArg
The resource name and its value are the next argument in argv
after the white space after this flag. For example, the flag
might be
-res basecalc*background:white;
then the resource name/value pair would be used as is. This form
is rarely used because it is equivalent to -xrm, and because the C
shell requires that special characters such as * be quoted.
XrmoptionSkipArg
Ignore this option and the next argument in argv.
XrmoptionSkipNArgs
Ignore this option and the next XrmOptionDescRec.value options
XrmoptionSkipLine
Ignore this option and the rest of argv.
The standard command line options parsed by XtDisplayInitialize() are
shown in the table below.
Option Resource Value Sets
-background *background Next argument Background color.
-bd *borderColor Next argument Border color.
-bg *background Next argument Background color.
-bordercolor *borderColor Next argument Color of border.
-borderwidth .borderWidth Next argument Width of border in pixels.
-bw .borderWidth Next argument Width of border in pixels.
-display .display Next argument Server to use.
-fg *foreground Next argument Foreground color.
-fn *font Next argument Font name.
-font *font Next argument Font name.
-foreground *foreground Next argument Foreground color.
-geometry .geometry Next argument Size and position.
-iconic .iconic on Start as an icon.
-name .name Next argument Name of application.
-reverse *reverseVideo on Reverse video.
-rv *reverseVideo on Reverse video.
+rv *reverseVideo off No reverse video.
-selectionTimeout .selectionTimeout Null Selection timeout.
-synchronous .synchronous on Synchronous debug mode.
+synchronous .synchronous off Synchronous debug mode.
-title .title Next argument Title of application.
-xnlLanguage .xnlLanguage Next argument Language.
-xrm Value of argument Next argument Depends on argument.
Building the Resource DatabaseXtDisplayInitialize() builds the application's resource database by
merging in resources from a number of sources. The merges are all done
to augment rather than override, so if a resource from one of these
sources conflicts with a resource in the database, the conflicting
value is ignored. The sources are:
· The application command line, parsed as described above.
· The file named by the XENVIRONMENT environment variable, or, if that
does not exist, the file .Xdefaults-<host> in the user's home direc‐
tory, where <host> is the name of the machine on which the applica‐
tion is running. If length of ".Xdefaults-<host>" is greater than
255, then ".Xdefaults-IP address" is looked for instead, where IP
address is the internet address of the host.
· The per-screen resources, stored in the SCREEN_RESOURCES property on
the root window of the screen, and returned by the function XScreen‐
ResourceString()
· The per-display resources stored in the RESOURCE_MANAGER property on
the root window of the default screen of the display, and obtained
with XResourceManagerString(). These resources are set by the user
with xrdb. If no RESOURCE_MANAGER property exists, the contents of
the .Xdefaults file in the user's home directory is used instead.
· The user's application-specific resource file, which is found with
XtResolvePathname() and the path specified in the XUSERFILESEARCH‐
PATH environment variable. If this environment variable is not
defined, an implementation-defined default path is used. This
default path will be relative to the directory specified in the XAP‐
PLRESDIR environment variable, if it exists, or the user's home
directory otherwise.
· The application class-specific resource file (the "app-defaults"
file), which is found with XtResolvePathname().
For more details on the precise algorithm used by the Intrinsics to
build the database, see XtDisplayInitialize().
Determining the Screen
In Release 5, XtAppCreateShell() checks its args argument for the
XtNscreen resource. If that is not found, it looks for the resource in
the database of the default screen of the display. If no screen is
found, the default screen of the display is used. If a value for the
screen resource is found, the shell widget is created on the specified
screen, and the database for that screen of the display is obtained
with XtScreenDatabase() and used for all the remaining resources of the
widget. Note that this database will have to be built using the steps
described above.
In Release 4, only the default screen of a display has a resource data‐
base, and widget resources come from that database regardless of the
which screen the shell widget is created on.
Structures
An XrmOptionDescList describes how to parse command line resources.
Prior to Release 5, the value field of the XrmOptionDescRec structure
was of type caddr_t. It was changed in Release 5 for portability rea‐
sons.
typedef enum {
XrmoptionNoArg, /* Value is specified in OptionDescRec.value */
XrmoptionIsArg, /* Value is the option string itself */
XrmoptionStickyArg, /* Value is characters immediately following option */
XrmoptionSepArg, /* Value is next argument in argv */
XrmoptionResArg, /* Resource and value in next argument in argv */
XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
XrmoptionSkipLine, /* Ignore this option and the rest of argv */
XrmoptionSkipNArgs /* Ignore this option and the next
OptionDescRes.value arguments in argv */
} XrmOptionKind;
typedef struct {
char *option; /* Option abbreviation in argv */
char *specifier; /* Resource specifier */
XrmOptionKind argKind; /* Which style of option it is */
XPointer value; /* Value to provide if XrmoptionNoArg */
} XrmOptionDescRec, *XrmOptionDescList;
An ArgList is an array of resource name/resource value pairs:
typedef struct {
String name;
XtArgVal value;
} Arg, *ArgList;
See AlsoXtAppCreateShell(1), XtAppSetFallbackResources(1), XtCreateApplication‐
Context(1), XtDisplayInitialize(1), XtOpenDisplay(1), XtResolvePath‐
name(1), XtScreenDatabase(1), XtSetLanguageProc(1), XtToolkitInitial‐
ize(1), XtVaAppInitialize(1).
Xt - Initialization XtAppInitialize()
