XtOpenDisplay()XtOpenDisplay()NameXtOpenDisplay - open, initialize, and add a display to an application
context.
Synopsis
Display *XtOpenDisplay(app_context, display_name, application_name,
application_class, options, num_options, argc, argv)
XtAppContext app_context;
String display_name;
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_name
Specifies the name of the display to be opened and initial‐
ized, or NULL.
application_name
Specifies the name of the application instance, or NULL.
application_class
Specifies the class name of this application, which is usu‐
ally the generic name for all instances of this application.
options Specifies how to parse the command line for any application-
specific resources.
num_options
Specifies the number of entries in the options array.
argc Specifies a pointer to the number of command line parameters.
In Release 4 and previously, this argument was of type Cardi‐
nal *. In Release 5 it is an int *.
argv Specifies the command line parameters.
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.
Returns
A pointer to the opened and initialized Display structure.
DescriptionXtOpenDisplay() opens and initializes a display, and adds it to the
specified application context. Note that a display can be in at most
one application context.
XtOpenDisplay() calls XOpenDisplay() with the name of the display to
open. If display_name is NULL, XtOpenDisplay() uses the current value
of the -display option specified in argv or if no display is specified
in argv, it uses the user's default display (on POSIX-based systems,
this is the value of the DISPLAY environment variable).
If the display is successfully opened, XtOpenDisplay() parses the com‐
mand line, builds the resource database and does other per-display ini‐
tialization by calling XtDisplayInitialize() and passing it the appli‐
cation context, the opened display, the application name, and the
remaining arguments. The application name is the value of the -name
option if it is specified in argv, or the value of the application_name
argument, if it is non-NULL, or the value of the RESOURCE_NAME environ‐
ment variable if it is set, or the name used to invoke the program. On
implementations that conform to ANSI-C Hosted Environment support, this
is argv[0] less any directory and file type components; that is, the
final component of argv[0], if specified. If argv[0] does not exist or
is the empty string, the application name is "main". See XtDisplayIni‐
tialize() and XtAppInitialize() for more information on initializing
the display. In particular, see XtAppInitialize() for an explanation
of how to initialize and array of XrmOptionDescRec in order to specify
command line options to be parsed.
XtOpenDisplay() returns the newly opened display or NULL if it failed.
Usage
Most applications open only one display. For these applications, it is
easiest to simply call XtAppInitialize() which will automatically open
and initialize a display. Applications that want to use additional
displays will usually open and initialize them with XtOpenDisplay().
If a display is already open, it can be initialized and added to an
application context, thereby making it known to the Intrinsics, by
calling XtDisplayInitialize().
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.
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 AlsoXtAppInitialize(1), XtDisplayInitialize(1).
Xt - Application Contexts XtOpenDisplay()
