NAME

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)
Stringshell_name;
Stringapplication_class;
XrmOptionDescRec options;
Cardinalnum_options;
Cardinal∗ argc;
Stringargv;

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 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_nameSpecifies 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.

optionsSpecifies how to parse the command line for any application-specific resources.  The options argument is passed as a parameter to XrmParseCommand. 

num_optionsSpecifies the number of entries in options list. 

argcSpecifies a pointer to the number of command line parameters. 

argvSpecifies 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(3Xm). 

7th Edition