XtAppInitialize man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

XtAppInitialize()					     XtAppInitialize()

Name
  XtAppInitialize  - initialize the X Toolkit internals, create an appli‐
  cation context, open and initialize a display, and create  the  initial
  application shell instance.

Synopsis
  Widget  XtAppInitialize(app_context_return, application_class, options,
  num_options,	argc_in_out,   argv_in_out,   fallback_resources,   args,
  num_args)
	   XtAppContext *app_context_return;
	   String application_class;
	   XrmOptionDescList options;
	   Cardinal num_options;
	   int *argc_in_out;	       /* was type Cardinal * in R4 */
	   String *argv_in_out;
	   String *fallback_resources;
	   ArgList args;
	   Cardinal num_args;

Inputs
  application_class
		 Specifies the class name of the application.

  options	 Specifies  an	array  of XrmOptionDescRec which describe
		 how to parse the command line.

  num_options	 Specifies the number of elements in options.

  argc_in_out	 Specifies the address of  the	number	of  command  line
		 arguments.   This argument is of type int * in Release 5
		 and of type Cardinal * in Release 4.

  argv_in_out	 Specifies the array of command line arguments.

  fallback_resources
		 Specifies a NULL-terminated array of resource specifica‐
		 tion  strings	to  be	used  if  the  application  class
		 resource file cannot be opened or read, or  NULL  if  no
		 fallback resources are desired.

  args		 Specifies   an	 argument  list	 to  override  any  other
		 resource specifications for the created shell widget.

  num_args	 Specifies the number of elements in args.

Outputs
  app_context_return
		 Returns the newly created application context,	 if  non-
		 NULL.

  argc_in_out	 Returns  the  number of command line arguments remaining
		 after the command line is  parsed  by	XtDisplayInitial‐
		 ize().

  argv_in_out	 Returns  the  command	line as modified by XtDisplayIni‐
		 tialize().

Returns
  A toplevel shell widget of class applicationShellWidgetClass.

Availability
  Release 4 and later.

Description
  XtAppInitialize() is a convenience  procedure	 that  most  applications
  will use to initialize themselves.  It does the following:

  ·  Calls  XtToolkitInitialize()  to  do Intrinsics internal initializa‐
     tion.

  ·  Calls XtCreateApplicationContext() to create an application  context
     for  the  application.  If app_context_return is non-NULL, the newly
     created application context is stored at the address it points to.

  ·  Calls XtAppSetFallbackResources() passing	the  application  context
     and fallback_resources, unless that argument is NULL.

  ·  Calls  XtOpenDisplay()  passing  the  application	context, applica‐
     tion_class,  options,  num_options,  argc_in_out,	and  argv_in_out.
     XtOpenDisplay() determines the display name and the application name
     from the command line or environment variables, opens  a  connection
     to the display, and calls XtDisplayInitialize() to parse the command
     line and build the resource database.  The command line as	 modified
     by XtDisplayInitialize() is returned in argc_in_out and argv_in_out.
     See the "Background" section below for more details on all of  these
     steps.

  ·  Calls  XtAppCreateShell()	to  create an applicationShellWidgetClass
     shell, passing args and num_args to override any resources found  in
     the database.

  If  the  display cannot be opened, an error message is issued and XtAp‐
  pInitialize() terminates the application.

Usage
  Most applications can XtAppInitialize() to initialize themselves.  Most
  programmers  will  not need to understand the details of initialization
  described in the "Background" section below.	 Applications  that  open
  multiple  displays or create multiple application contexts will have to
  use the lower-level initialization functions explicitly.

  Most applications can have all their command-line options automatically
  parsed  by  declaring	 an XrmOptionDescList and passing it to XtAppIni‐
  tialize() which will convert values on the command line into values  in
  the resource database which can then be retrieved into a structure with
  XtGetApplicationResources().	This is a  good	 idea,	because	 if  your
  application supports customization through application resources (which
  it should if there is anything to customize) then customization through
  the command line comes essentially for free.

  If  all  your	 command line options are parsed this way, then XtAppIni‐
  tialize() should remove everything except argv[0] from the command line
  and  should  set argc to 1.  If this is not the case when XtAppInitial‐
  ize() returns, then the user has requested an unrecognized option.   If
  you  parse  some  command  line options manually, you should parse them
  after calling XtAppInitialize().

  The "Background" section below explains how to declare an  XrmOptionDe‐
  scList and the example below shows the one used by viewres.

  The  fallback_resources  argument  is	 an array of strings, each string
  equivalent to a line in a resource file.  If your application relies on
  an  app-defaults file, you can use fallback resources as a backup to be
  used in case the app-defaults file is installed incorrectly  or  other‐
  wise cannot be found.	 If the application needs many resources to func‐
  tion properly, your fallback resources might simply set a label  widget
  to  display  an  error  message  which  informs  the user that the app-
  defaults file could not be found.  The example  below	 shows	a  simple
  fallback resource list.

  In  Release  4,  the argc_in_out argument is of type Cardinal *, and in
  Release 5, this argument is of type int *.  This is a minor  incompati‐
  bility that may result warnings from ANSI-C compilers when porting from
  one release to another.  The example below  shows  a	way  around  this
  problem.

  XtVaAppInitialize()  performs	 the  same function as XtAppInitialize(),
  but accepts a NULL-terminated variable-length argument list of resource
  name/resource value pairs instead of an ArgList.

Example
  The  following  initialization  code	is adapted from the X11R5 viewres
  application.

     static XrmOptionDescRec Options[] = {
	 { "-top", "*topObject", XrmoptionSepArg, (XPointer) NULL },
	 { "-variable", "*showVariable", XrmoptionNoArg, (XPointer) "on" },
	 { "-vertical", "*Tree.Gravity", XrmoptionNoArg, (XPointer) "north" }
     };

     static char *fallback_resources[] = {
	 "*allowShellResize: true",
	 "*Porthole.top: ChainTop",
	 "*Porthole.left: ChainLeft",
	 "*Porthole.bottom: ChainBottom",
	 "*Porthole.right:  ChainRight",
	 "*Porthole.resizable: on",
	 (char *) NULL
     };

     main (argc, argv)
	 int argc;
	 char **argv;
     {
	 Widget toplevel;
	 XtAppContext app_con;

	 toplevel = XtAppInitialize(&app_con, "Viewres",
				    Options, XtNumber (Options),
     #if XtSpecificationRelease > 4
				    &argc,
     #else
				    (Cardinal *)&argc,
     #endif
				    argv,
				    fallback_resources,
				    (ArgList) NULL, (Cardinal) 0);

	 if (argc != 1) display_usage_message();
	     .
	     .
	     .
     }

Background
  Initializing an application is a complex process.  It	 involves  deter‐
  mining  the  display to be opened, determining the name of the applica‐
  tion, setting the locale of the application, determining the screen  on
  which	 to create the shell widget, parsing the command line, and build‐
  ing the resource database.  Each of these tasks is described in  detail
  below.   Some of the details have changed between Release 4 and Release
  5.  Release 5 is described below.

Determining Which Display to Open
  XtAppInitialize() calls XtOpenDisplay() with NULL for its  display_name
  argument.   XtOpenDisplay()  determines  which display to open by first
  checking the command line (note that the  command  line  has	not  been
  parsed  at  this point) for a -display command line option, and if that
  is not found, using the value of the DISPLAY environment  variable  (on
  POSIX systems).  The name is used in a call to XOpenDisplay().

Determining the Application Name
  XtOpenDisplay() also determines the name of the application.	It checks
  for the name in the following four locations and uses the first one  it
  finds:

  ·  the value of the -name command line option.

  ·  the value of its application_name argument.  Note that XtAppInitial‐
     ize() always passes NULL for this value.

  ·  the value of the RESOURCE_NAME environment variable.

  ·  the first word on the command line, argv[0], stripped of any leading
     directories.

  If the name is not found in any of these sources, "main" is used.  This
  name is passed to XtDisplayInitialize() to  be  used	in  building  the
  resource database, and will later be used by XtAppCreateShell() to name
  the application's toplevel shell widget.

Establishing the Application's Locale
  XtDisplayInitialize() determines an application's "language string"  by
  searching  for  the  -xnlLanguage  command line option, an -xrm command
  line option that sets the xnlLanguage resource, or a value for the xnl‐
  Language  option  in	the  user's personal resource database (i.e., the
  resources set on the display with xrdb, or the resources in  the  .Xde‐
  faults file.)

  In  Release  5, if a language procedure has been registered (see XtSet‐
  LanguageProc()) then the language string is  passed  to  this	 language
  procedure.   The  language procedure localizes the application, usually
  by calling setlocale(), and returns a	 string	 which	becomes	 the  new
  value	 of  the  application's language string.  If a language procedure
  has not been set, and in Release 4, the LANG	environment  variable  is
  used	for  the  language string if no command line argument or resource
  value is found.

  In either Release 4 and Release 5, the language  string  is  associated
  with	the  display  and  used in future calls to XtResolvePathname() so
  that file customized for a  particular  language  can	 be  found.   See
  XtDisplayInitialize()	 and  XtSetLanguageProc() for more detail on this
  process.

Parsing the Command Line
  XtDisplayInitialize() parses the application command	line  by  merging
  options  into	 the  standard	Xt command line options table and calling
  XrmParseCommand().  Each element in options and the Xt options table is
  a  XrmOptionDescRec structure (shown in the "Structures" section below)
  which describes how to parse	a  single  command  line  argument.   The
  fields of this structure are as follows:

  option
       The  string to be searched for on the command line.  As with stan‐
       dard command-line options, Xt will automatically accept any unique
       abbreviation  of	 the  option  specified	 here.	 For example, the
       option -pixmapWidthInPixels will be recognized  if  typed  on  the
       command	line  as -pixmapW.  However, if you wanted the option -pw
       to set the same resource, then you would need another entry, since
       pw is not the leading string of pixmapWidthInPixels.

  specifier
       The  resource  specification.   This string must identify a widget
       resource or an application resource,  but  not  provide	a  value.
       Since  it  has the same form as allowed in the resource databases,
       it may apply to a single widget or to many widgets.  If it applies
       to no widgets, no error message will be issued.

  argKind
       The  argument  style.   This  field is of type XrmOptionKind which
       describes how the option is to be  interpreted.	 These	constants
       are described below.

  value
       If  argKind  is	XrmOptionNoArg, this field specifies the resource
       value (a string) to be inserted into the database.  If argKind  is
       XrmOptionSkipNArgs,  this  field specifies the number of arguments
       to skip (you'll need to use a cast to set this field to	an  inte‐
       ger).  For other values of argKind, this field is not used.

  The  possible	 values	 for XrmOptionKind and their meanings are as fol‐
  lows:

  XrmoptionNoArg
       Take the value in the value field of the options table.	For exam‐
       ple,  this  is  used for Boolean fields, where the option might be
       -debug and the default value False.

  XrmoptionIsArg
       The flag itself is the value without any	 additional  information.
       For  example,  if  the  option  were -on, the value would be "on."
       This constant is infrequently used, because the desired value such
       as  "on"	 is usually not descriptive enough when used as an option
       (-on).

  XrmoptionStickyArg
       The value is the characters immediately following the option  with
       no  white  space	 intervening.  This is the style of arguments for
       some POSIX utilities such as uucico where -sventure means to  call
       system venture.

  XrmoptionSepArg
       The  next item after the white space after this flag is the value.
       For example, -fg blue would indicate that blue is  the  value  for
       the resource specified by -fg.

  XrmoptionResArg
       The  resource  name  and	 its  value are the next argument in argv
       after the white space after this	 flag.	 For  example,	the  flag
       might be
	    -res basecalc*background:white;
       then  the resource name/value pair would be used as is.	This form
       is rarely used because it is equivalent to -xrm, and because the C
       shell requires that special characters such as * be quoted.

  XrmoptionSkipArg
       Ignore this option and the next argument in argv.

  XrmoptionSkipNArgs
       Ignore this option and the next XrmOptionDescRec.value options

  XrmoptionSkipLine
       Ignore this option and the rest of argv.

  The  standard	 command line options parsed by XtDisplayInitialize() are
  shown in the table below.

Option		    Resource		Value		Sets
-background	    *background		Next argument	Background color.
-bd		    *borderColor	Next argument	Border color.

-bg		    *background		Next argument	Background color.
-bordercolor	    *borderColor	Next argument	Color of border.
-borderwidth	    .borderWidth	Next argument	Width of border in pixels.
-bw		    .borderWidth	Next argument	Width of border in pixels.
-display	    .display		Next argument	Server to use.
-fg		    *foreground		Next argument	Foreground color.
-fn		    *font		Next argument	Font name.
-font		    *font		Next argument	Font name.
-foreground	    *foreground		Next argument	Foreground color.
-geometry	    .geometry		Next argument	Size and position.
-iconic		    .iconic		on		Start as an icon.
-name		    .name		Next argument	Name of application.
-reverse	    *reverseVideo	on		Reverse video.
-rv		    *reverseVideo	on		Reverse video.
+rv		    *reverseVideo	off		No reverse video.
-selectionTimeout   .selectionTimeout	Null		Selection timeout.
-synchronous	    .synchronous	on		Synchronous debug mode.
+synchronous	    .synchronous	off		Synchronous debug mode.
-title		    .title		Next argument	Title of application.
-xnlLanguage	    .xnlLanguage	Next argument	Language.
-xrm		    Value of argument	Next argument	Depends on argument.

Building the Resource Database
  XtDisplayInitialize() builds the  application's  resource  database  by
  merging in resources from a number of sources.  The merges are all done
  to augment rather than override, so if a resource  from  one	of  these
  sources  conflicts  with  a  resource	 in the database, the conflicting
  value is ignored.  The sources are:

  ·  The application command line, parsed as described above.

  ·  The file named by the XENVIRONMENT environment variable, or, if that
     does not exist, the file .Xdefaults-<host> in the user's home direc‐
     tory, where <host> is the name of the machine on which the	 applica‐
     tion  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 resources, stored in the SCREEN_RESOURCES property on
     the root window of the screen, and returned by the function XScreen‐
     ResourceString()

  ·  The per-display resources stored in the RESOURCE_MANAGER property on
     the root window of the default screen of the display,  and	 obtained
     with  XResourceManagerString().  These resources are set by the user
     with xrdb.	 If no RESOURCE_MANAGER property exists, the contents  of
     the .Xdefaults file in the user's home directory is used instead.

  ·  The  user's  application-specific resource file, which is found with
     XtResolvePathname() and the path specified in  the	 XUSERFILESEARCH‐
     PATH  environment	variable.   If	this  environment variable is not
     defined, an  implementation-defined  default  path	 is  used.   This
     default path will be relative to the directory specified in the XAP‐
     PLRESDIR environment variable, if it  exists,  or	the  user's  home
     directory otherwise.

  ·  The  application  class-specific  resource	 file (the "app-defaults"
     file), which is found with XtResolvePathname().

  For more details on the precise algorithm used  by  the  Intrinsics  to
  build the database, see XtDisplayInitialize().

Determining the Screen
  In  Release  5,  XtAppCreateShell()  checks  its  args argument for the
  XtNscreen resource.  If that is not found, it looks for the resource in
  the  database	 of  the  default screen of the display.  If no screen is
  found, the default screen of the display is used.  If a value	 for  the
  screen  resource is found, the shell widget is created on the specified
  screen, and the database for that screen of  the  display  is	 obtained
  with XtScreenDatabase() and used for all the remaining resources of the
  widget.  Note that this database will have to be built using the  steps
  described above.

  In Release 4, only the default screen of a display has a resource data‐
  base, and widget resources come from that database  regardless  of  the
  which screen the shell widget is created on.

Structures
  An  XrmOptionDescList	 describes  how	 to parse command line resources.
  Prior to Release 5, the value field of the  XrmOptionDescRec	structure
  was  of type caddr_t.	 It was changed in Release 5 for portability rea‐
  sons.

     typedef enum {
	 XrmoptionNoArg,     /* Value is specified in OptionDescRec.value	 */
	 XrmoptionIsArg,     /* Value is the option string itself		 */
	 XrmoptionStickyArg, /* Value is characters immediately following option */
	 XrmoptionSepArg,    /* Value is next argument in argv			 */
	 XrmoptionResArg,    /* Resource and value in next argument in argv	 */
	 XrmoptionSkipArg,   /* Ignore this option and the next argument in argv */
	 XrmoptionSkipLine,  /* Ignore this option and the rest of argv		 */
	 XrmoptionSkipNArgs  /* Ignore this option and the next
				OptionDescRes.value arguments in argv */
     } XrmOptionKind;

     typedef struct {
	 char		 *option;	 /* Option abbreviation in argv		 */
	 char		 *specifier;	 /* Resource specifier			 */
	 XrmOptionKind	 argKind;	 /* Which style of option it is		 */
	 XPointer	 value;		 /* Value to provide if XrmoptionNoArg	 */
     } XrmOptionDescRec, *XrmOptionDescList;

  An ArgList is an array of resource name/resource value pairs:

     typedef struct {
	 String	     name;
	 XtArgVal    value;
     } Arg, *ArgList;

See Also
  XtAppCreateShell(1), XtAppSetFallbackResources(1), XtCreateApplication‐
  Context(1), XtDisplayInitialize(1), XtOpenDisplay(1), XtResolvePath‐
  name(1), XtScreenDatabase(1), XtSetLanguageProc(1), XtToolkitInitial‐
  ize(1), XtVaAppInitialize(1).

Xt - Initialization					     XtAppInitialize()
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net