Query: xtappinitialize
OS: hpux
Section: 1
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtAppInitialize() XtAppInitialize()
Name
XtAppInitialize - initialize the X Toolkit internals, create an application 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 Car-
dinal * in Release 4.
argv_in_out Specifies the array of command line arguments.
fallback_resources
Specifies a NULL-terminated array of resource specification 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 XtDisplayInitialize().
argv_in_out Returns the command line as modified by XtDisplayInitialize().
Returns
A toplevel shell widget of class applicationShellWidgetClass.
Availability
Release 4 and later.
Description
XtAppInitialize() is a convenience procedure that most applications will use to initialize themselves. It does the following:
o Calls XtToolkitInitialize() to do Intrinsics internal initialization.
o 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.
o Calls XtAppSetFallbackResources() passing the application context and fallback_resources, unless that argument is NULL.
o Calls XtOpenDisplay() passing the application context, application_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.
o 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 XtAppInitialize() terminates the application.
Usage
Most applications can XtAppInitialize() to initialize themselves. Most programmers will not need to understand the details of initializa-
tion 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 XtAp-
pInitialize() which will convert values on the command line into values in the resource database which can then be retrieved into a struc-
ture 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 XtAppInitialize() should remove everything except argv[0] from the command line
and should set argc to 1. If this is not the case when XtAppInitialize() 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 XrmOptionDescList 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 oth-
erwise cannot be found. If the application needs many resources to function 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 determining 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
building 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 Open
XtAppInitialize() 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 Name
XtOpenDisplay() also determines the name of the application. It checks for the name in the following four locations and uses the first one
it finds:
o the value of the -name command line option.
o the value of its application_name argument. Note that XtAppInitialize() always passes NULL for this value.
o the value of the RESOURCE_NAME environment variable.
o 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 Locale
XtDisplayInitialize() 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 xnlLanguage option in the user's personal resource database (i.e., the
resources set on the display with xrdb, or the resources in the .Xdefaults file.)
In Release 5, if a language procedure has been registered (see XtSetLanguageProc()) 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 Line
XtDisplayInitialize() 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 standard 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 integer).
For other values of argKind, this field is not used.
The possible values for XrmOptionKind and their meanings are as follows:
XrmoptionNoArg
Take the value in the value field of the options table. For example, 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 Database
XtDisplayInitialize() 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:
o The application command line, parsed as described above.
o The file named by the XENVIRONMENT environment variable, or, if that does not exist, the file .Xdefaults-<host> in the user's home
directory, where <host> is the name of the machine on which the application 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.
o The per-screen resources, stored in the SCREEN_RESOURCES property on the root window of the screen, and returned by the function
XScreenResourceString()
o 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.
o The user's application-specific resource file, which is found with XtResolvePathname() and the path specified in the XUSERFILESEARCHPATH
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 XAPPLRESDIR environment variable, if it exists, or the user's home directory other-
wise.
o 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 database, 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 reasons.
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 Also
XtAppCreateShell(1), XtAppSetFallbackResources(1), XtCreateApplicationContext(1), XtDisplayInitialize(1), XtOpenDisplay(1), XtResolvePath-
name(1), XtScreenDatabase(1), XtSetLanguageProc(1), XtToolkitInitialize(1), XtVaAppInitialize(1).
Xt - Initialization XtAppInitialize()