Query: xtdisplayinitialize
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtDisplayInitialize() XtDisplayInitialize()
Name
XtDisplayInitialize - initialize a display and add it to an application context.
Synopsis
void XtDisplayInitialize(app_context, display, application_name, application_class, options, num_options, argc, argv)
XtAppContext app_context;
Display *display;
String application_name;
String application_class;
XrmOptionDescRec *options;
Cardinal num_options;
int *argc; /* was Cardinal * in Release 4 */
String *argv;
Inputs
app_context
Specifies the application context.
display Specifies the display. Note that a display can be in at most one application context.
application_name
Specifies the name of the application instance.
application_class
Specifies the class name of this application. This name is usually the generic name for all instances of this application.
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 the options list.
argc Specifies a pointer to the number of command line arguments. In Release 4 and previously, this argument was of type Cardinal *.
In Release 5 it is an int *.
argv Specifies the command line arguments.
Outputs
argc Returns the number of command line arguments remaining after the command line is parsed.
argv Returns a modified command line containing only the application name and any arguments that were not recognized as standard Xt
options or options specified in options.
Description
In Release 5, XtDisplayInitialize() first retrieves the language string to be used for the specified display and calls the language proce-
dure (if any was registered) with that language string. In all releases, XtDisplayInitialize() parses the command line using the Xlib Xrm-
ParseCommand() function, builds the resource database, and performs other per-display initialization. See XtAppInitialize() for informa-
tion on how the language string is handled and how the command line is parsed. See the "Background" section below for detail on how the
resource database is built.
If the synchronize resource is True, XtDisplayInitialize() calls the Xlib XSynchronize() function to put Xlib into synchronous mode for
this display connection and any others currently open in the application context.
In Release 5, XtDisplayInitialize() calls XrmSetDatabase() to associate the resource database of the default screen with the display.
Usage
XtDisplayInitialize() does not actually open a display connection. XtOpenDisplay() opens a display and then calls XtDisplayInitialize().
Most applications need not use either of these functions; they can use XtAppInitialize() instead.
In Release 4, the argc argument is of type Cardinal *, and in Release 5, this argument is of type int *. This is a minor incompatibility
that may result warnings from ANSI-C compilers when porting from one release to another.
After XtDisplayInitialize() has been called, argc and argv contain only those arguments that were not in the standard option table or in
the table specified by the options argument. If the modified argc is not zero, most applications simply print out the modified argv along
with a message listing the allowable options.
Background
The algorithm for building the resource database has changed significantly between Release 4 and Release 5, with the introduction of per-
screen databases, internationalization and the customization resource. The process followed by XtDisplayInitialize() in Release 5 is
described below.
XtDisplayInitialize() first determines the language string to be used for the specified display and then creates resource databases as
needed for each screen of the display by combining the following sources in order, with the entries in the first named source having high-
est precedence:
o Application command line (argv).
o Per-host user environment resource file on the local host.
o Per-screen resource specifications from the server.
o Per-display resource specifications from the server or from
the user preference file on the local host.
o Application-specific user resource file on the local host.
o Application-specific class resource file on the local host.
When the resource database for a particular screen on the display is needed (either internally, or when XtScreenDatabase() is called),
XtDisplayInitialize() creates the resource database for the screen in the following manner:
o A temporary database, the "server resource database", is created from the string returned by XResourceManagerString() or, if XResourceM-
anagerString() returns NULL, the contents of a resource file in the user's home directory. On POSIX-based systems, the usual name for
this user preference resource file is $HOME/.Xdefaults.
o If a language procedure has been set, XtDisplayInitialize() first searches the command line for the option "-xnlLanguage", or for a -xrm
option that specifies the xnlLanguage/XnlLanguage resource. If such a resource is found, the value is assumed to be entirely in XPCS,
the X Portable Character Set. If neither option is specified on the command line, XtDisplayInitialize() queries the server resource
database (which is assumed to be entirely in XPCS) for the resource name.xnlLanguage, class Class.XnlLanguage where name and Class are
the application_name and application_class specified to XtDisplayInitialize(). The language procedure is then invoked with the resource
value if found, else the empty string. The string returned from the language procedure is saved for all future references in the
Intrinsics that require the per-display language string.
o The screen resource database is initialized by parsing the command line. (See XtAppInitialize() for information on how the command line
is parsed.)
o If a language procedure has not been set, The initial database is then queried for the resource name.xnlLanguage, class Class.XnlLan-
guage as specified above. If this database query fails, the server resource database is queried; if this query also fails, the language
is determined from the environment; on POSIX-based systems, this is done by retrieving the value of the LANG environment variable. If
no language string is found, the empty string is used. This language string is saved for all future references in the Intrinsics that
require the per-display language string.
o After determining the language string, the user's environment resource file is then merged into the initial resource database if the
file exists. This file is user-, host-, and process-specific and is expected to contain user preferences that are to override those
specifications in the per-display and per-screen resources. On POSIX-based systems, the user's environment resource file name is speci-
fied by the value of the XENVIRONMENT environment variable. If this environment variable does not exist, the user's home directory is
searched for a file named .Xdefaults-host , where host is the host 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 resource specifications are then merged into the screen resource database, if they exist. These specifications are the
string returned by XScreenResourceString() for the respective screen and are owned entirely by the user.
o Next, the server resource database created earlier is merged into the screen resource database. The server property, and corresponding
user preference file, are owned and constructed entirely by the user.
o The application-specific user resource file from the local host is then merged into the screen resource database. This file is owned by
the application and typically stores user customizations in a directory owned by the user. Its name is found by calling XrmSet-
Database() with the current screen resource database, after preserving the original display-associated database, then calling XtRe-
solvePathname() with the parameters (display, NULL, NULL, NULL, path, NULL, 0, NULL) where path is defined in an operating-system-spe-
cific way. On POSIX-based systems, path is defined to be the value of the environment variable XUSERFILESEARCHPATH if this is defined.
If XUSERFILESEARCHPATH is not defined, an implementation-dependent default value is used. This default value is constrained in the fol-
lowing manner:
- If the environment variable XAPPLRESDIR is not defined, the default XUSERFILESEARCHPATH must contain at least six entries. These
entries must contain $HOME as the directory prefix, plus the following substitutions:
1. %C, %N, %L or %C, %N, %l, %t, %c
2. %C, %N, %l
3. %C, %N
4. %N, %L or %N, %l, %t, %c
5. %N, %l
6. %N
The order of these six entries within the path must be as given above. The order and use of substitutions within a given entry is
implementation dependent.
- If XAPPLRESDIR is defined, the default XUSERFILESEARCHPATH must contain at least seven entries. These entries must contain the fol-
lowing directory prefixes and substitutions:
1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c
2. $XAPPLRESDIR with %C, %N, %l
3. $XAPPLRESDIR with %C, %N
4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c
5. $XAPPLRESDIR with %N, %l
6. $XAPPLRESDIR with %N
7. $HOME with %N
The order of these seven entries within the path must be as given above. The order and use of substitutions within a given entry is
implementation dependent.
o Lastly, the application-specific class resource file from the local host is merged into the screen resource database. This file is
owned by the application and is usually placed in a system directory (/usr/lib/X11/app-defaults in most implementations) when the appli-
cation is installed. It may contain site-wide customizations specified by the system manager. The name of the application class
resource file is found by calling XtResolvePathname() with the parameters (display, "app-defaults", NULL, NULL, NULL, NULL, 0, NULL).
This call will look in the default system directory, or in the directories specified by XFILESEARCHPATH environment variable. See XtRe-
solvePathname() for details on how this variable is used.
This file, the application class "app-defaults" file, should be provided by the developer of the application and may be required for the
application to function properly. A simple application that wants to be assured of having a minimal set of resources in the absence of its
class resource file can declare fallback resource specifications with XtAppSetFallbackResources().
Note that the customization substitution string is retrieved dynamically by XtResolvePathname() so that the resolved file name of the
application class resource file can be affected by any of the earlier sources for the screen resource database, even though the contents of
the class resource file have lowest precedence.
Structures
The XrmOptionDescRec structure is as follows. See XtAppInitialize() for information on how it is used.
typedef enum {
/* Value is ... */
XrmoptionNoArg,/* specified in OptionDescRec.value */
XrmoptionIsArg,/* the option string itself */
XrmoptionStickyArg,/* characters immediately following option */
XrmoptionSepArg,/* next argument in argv */
XrmoptionResArg,/* next argument is input to XrmPutLineResource */
/* Ignore this option and ... */
XrmoptionSkipArg,/* the next argument in argv */
XrmoptionSkipNArgs,/* Ignore this option and ... */
/* the next value arguments in argv */
XrmoptionSkipLine/* the rest of argv */
} XrmOptionKind;
typedef struct {
char *option; /* Option name in argv */
char *specifier;/* Resource name (without application name) */
XrmOptionKind argKind;/* Which style of option it is */
caddr_t value; /* Value to provide if XrmoptionNoArg */
} XrmOptionDescRec, *XrmOptionDescList;
See Also
XtAppCreateShell(1), XtAppInitialize(1), XtCreateApplicationContext(1), XtDatabase(1), XtOpenDisplay(1), XtResolvePathname(1).
Xt - Application Contexts XtDisplayInitialize()