XtDisplayInitialize()XtDisplayInitialize()NameXtDisplayInitialize - initialize a display and add it to an application
context.
Synopsis
void XtDisplayInitialize(app_context, display, application_name, appli‐
cation_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 applica‐
tion.
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 Cardi‐
nal *. 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 applica‐
tion name and any arguments that were not recognized as stan‐
dard 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 procedure
(if any was registered) with that language string. In all releases,
XtDisplayInitialize() parses the command line using the Xlib XrmParseC‐
ommand() function, builds the resource database, and performs other
per-display initialization. See XtAppInitialize() for information 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 data‐
base 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.
UsageXtDisplayInitialize() 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 signifi‐
cantly 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 highest prece‐
dence:
· Application command line (argv).
· Per-host user environment resource file on the local host.
· Per-screen resource specifications from the server.
· Per-display resource specifications from the server or from
the user preference file on the local host.
· Application-specific user resource file on the local host.
· 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:
· A temporary database, the "server resource database", is created
from the string returned by XResourceManagerString() or, if XRe‐
sourceManagerString() 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.
· 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 refer‐
ences in the Intrinsics that require the per-display language
string.
· The screen resource database is initialized by parsing the command
line. (See XtAppInitialize() for information on how the command
line is parsed.)
· 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 lan‐
guage string is saved for all future references in the Intrinsics
that require the per-display language string.
· 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
specified 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.
· 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.
· Next, the server resource database created earlier is merged into
the screen resource database. The server property, and correspond‐
ing user preference file, are owned and constructed entirely by the
user.
· 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 preserv‐
ing 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-
specific 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 following 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
following 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.
· 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 speci‐
fied 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 XtResolvePathname() for details on how this variable is used.
This file, the application class "app-defaults" file, should be pro‐
vided 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 dynami‐
cally 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 AlsoXtAppCreateShell(1), XtAppInitialize(1), XtCreateApplicationContext(1),
XtDatabase(1), XtOpenDisplay(1), XtResolvePathname(1).
Xt - Application Contexts XtDisplayInitialize()
