hpux man page for xtopendisplay

XtOpenDisplay() 														   XtOpenDisplay()

Name
  XtOpenDisplay - 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 initialized, or NULL.

  application_name
	    Specifies the name of the application instance, or NULL.

  application_class
	    Specifies the class name of this application, which is usually 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 Cardinal *.
	    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 application name and any arguments that were not recognized  as  standard  Xt
	    options or options specified in options.

Returns
  A pointer to the opened and initialized Display structure.

Description
  XtOpenDisplay()  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 command line, builds the resource database	and  does  other  per-display
  initialization  by  calling XtDisplayInitialize() and passing it the application 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  applica-
  tion_name  argument, if it is non-NULL, or the value of the RESOURCE_NAME environment 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  compo-
  nents;  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 XtDisplayInitialize() and XtAppInitialize() for more information on initializing the display.  In  particular,  see  XtAppIni-
  tialize() 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  XtOpenDis-
  play().   If	a  display is already open, it can be initialized and added to an application context, thereby making it known to the Intrin-
  sics, 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 Also
  XtAppInitialize(1), XtDisplayInitialize(1).

Xt - Application Contexts													   XtOpenDisplay()