NAME

XtDisplayInitialize — a function that initializes the toolkit’s view of a display and adds it to an application context.

SYNOPSIS

#include <Xm/Xm.h> Widget XtDisplayInitialize (app_context, display, application_name, application_class, options, num_options, argc, argv)
XtAppContextapp_context;
Display∗ display;
Stringapplication_name;
Stringapplication_class;
XrmOptionDescRec options;
Cardinalnum_options;
Cardinal∗ argc;
Stringargv;

DESCRIPTION

XtDisplayInitialize parses the command line that invoked the application, and loads the resource database. XtDisplayInitialize is a back-end routine that is usually called be XtInitialize. It may be called directly if the application needs to open more than one display. XtDiplayInitialize is passed an open display.  XtOpenDisplay can be used in the case where an open display has not yet been generated. 

By passing the command line that invoked your application to XtDisplayInitialize, the function can parse the line to allow users to specify certain resources (such as fonts and colors) for your application at run time.  XtDisplayInitialize scans the command line and removes those options.  The rest of your application sees only the remaining options. 

XtDisplayInitialize 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, XtDisplayInitialize 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, XtDisplayInitialize 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 XtDisplayInitialize are defined below:

app_contextSpecifies the application context. 

displaySpecifies the display. Note that a display can be in at most one application context. 

application_name
Specifies the name of this application.

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. 

RELATED INFORMATION

XtInitialize(3Xm). 

7th Edition