Name
XtInitialize — initialize toolkit and display.
Synopsis
Widget XtInitialize(shell_name, application_class, options, num_options, argc, argv)
char ∗shell_name; /∗unused in R3∗/
char ∗application_class;
XrmOptionDescRec options[];
Cardinal num_options;
Cardinal ∗argc;
char ∗argv[];
Arguments
shell_name
Specifies the name of the application shell widget instance.
application_class
Specifies the class name of this application.
optionsSpecifies 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 options list.
argcSpecifies a pointer to the number of command line parameters.
argvSpecifies the command line parameters.
Description
XtInitialize has been superseded by XtAppInitialize. XtInitialize returns an application shell suitable for parenting the rest of the application, and consolidates other requisite Toolkit initialization. This is the initialization routine of choice for simple applications that use widgets.
XtInitialize calls XtToolkitInitialize to initialize the Toolkit internals, creates a default application context with XtCreateApplicationContext, XtOpenDisplay, and XtAppCreateShell, and returns the created shell. XtInitialize is generally more convenient than calling each of the routines individually.
The semantics of calling XtInitialize more than once are undefined.
Command Line Parsing
XtInitialize calls XtDisplayInitialize, which in turn calls the Xlib XrmParseCommand function to parse the command line.
The command line parser modifies argc and argv to contain only those parameters that were not in the standard option table or in the table specified by the options argument. If the resulting argc is not zero, then there were unexpected parameters declared on the user’s command line. Most applications handle this by simply printing out the remaining contents of argv along with a message listing the allowable options, with the application name. (On POSIX-based systems, the application name is usually the final component of argv[0].)
Note that the argc and argv arguments of XtInitialize are in the same order as in the call to main. This is the opposite order of arrays and array lengths throughout other Xt and Xlib routine calls. Also note that the address of argc, not argc itself, is passed to XtInitialize. This is so that XtInitialize can decrement the count to reflect recognized options. Watch out for these snags.
Loading the Resource Database
The XtDisplayInitialize function loads the application’s resource database for this display/host/application combination from the following sources (in order):
•Application-specific class resource file on the local host.
•Application-specific user resource file on the local host.
•Resource property on the server or user preference resource file on the local host.
•Per-host user environment resource file on the local host.
•Application command line (argv).
Each resource database is kept on a per-display basis.
The application-specific class resource file name is constructed from the class name of the application. It points to a site-specific resource file that usually is installed by the site manager when the application is installed. On POSIX-based systems, this file usually is /usr/lib/X11/app-defaults/class, where class is the application class name. This file is expected to be provided by the developer of the application and may be required for the application to function properly.
The application-specific user resource file name is constructed from the class name of the application and points to a user-specific resource file. This file is owned by the application and typically stores user customizations. On POSIX-based systems, this file name is constructed from the user’s XAPPLRESDIR variable by appending class to it, where class is the application class name. (That is, XAPPLRESDIR specifies the name of a directory, and class the name of a file contained in it.) If XAPPLRESDIR is not defined, it defaults to the user’s home directory. If the resulting resource file exists, it is merged into the resource database. This file may be provided with the application or constructed by the user.
The server resource file is the contents of the X server’s RESOURCE_MANAGER property that was returned by XOpenDisplay. If no such property exists for the display, the contents of the resource file in the user’s home directory is used instead. On POSIX-based systems, the usual name for the user preference resource file is .Xdefaults. If the resulting resource file exists, it is merged into the resource database. The server resource file is constructed entirely by the user and contains both display-independent and display-specific user preferences.
If one exists, a user’s environment resource file is then loaded and merged into the resource database. This file name is user and host specific. On POSIX-based systems, the user’s environment resource file name is constructed from the value of the user’s XENVIRONMENT variable for the full path of the file. If this environment variable does not exist, XtDisplayInitialize searches the user’s home directory for the .Xdefaults-host file, where host is the name of the machine on which the application is running. If the resulting resource file exists, it is merged into the resource database. The environment resource file is expected to contain system-specific resource specifications that are to supplement those user-preference specifications in the server resource file.
Parsing the Command Line
XtDisplayInitialize has a table of standard command line options for adding resources to the resource database, and it can accept application-specific resource abbreviations.
The format of this table is shown below in the Structures section of this reference page. The standard table contains the following entries:
| 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 |
Note that any unique abbreviation for an option name in the standard table or in the application table is accepted.
The table above lists the complete set of standard options. Options for which the resource name is shown starting with a dot rather than an asterisk set that resource only in the application’s top-level Shell.
If the user specifies synchronize True on the command line, XtDisplayInitialize calls the Xlib XSynchronize function to put the Xlib display connection into synchronous mode. If reverseVideo is True, the Intrinsics exchange XtDefaultForeground and XtDefaultBackground for widgets created on this display.
The -xrm option provides a method of setting any resource in an application. The next argument should be a quoted string identical in format to a line in the user resources file. For example, to give a red background to all command buttons in an application named xmh, you can start it up as:
xmh −xrm ’xmh∗Command.background: red’
When it fully parses the command line, XtDisplayInitialize merges the application option table with the standard option table and then calls the Xlib XrmParseCommand function. An entry in the application table with the same name as an entry in the standard table overrides the standard table entry. If an option name is a prefix of another option name, both names are kept in the merged table.
Structures
You make XtInitialize understand additional command-line options by initializing a XrmOptionDescRec structure (called the options table) and passing it as an argument to XtInitialize.
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;
Each options table entry consists of four fields:
•The option to be searched for on the command line. As with standard 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.
•The resource specification. This 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.
•The argument style. This field is one of seven enumerated constants describing how the option is to be interpreted. These constants are described below.
•The value. This field is the value to be used for the resource if the argument style is XrmOptionNoArg. This field is not used otherwise. Note that this value must already be converted to the value expected for the resource (often not a string). You may be able to use Xt’s type converter routines explicitly to convert this data to the right type.
The XrmOptionKind enum constants that specify the various command-line argument styles are as shown in the table below:
| Constant | Meaning | |
| XrmoptionNoArg | Take the value in the value field of the options table. For example, 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 options table is passed to XtInitialize as its third argument, and the number of options table entries as the fourth. The XtNumber macro is a convenient way to count the number of entries (this is only one of many contexts in which you’ll see this macro used).
Note that you cannot override the standard options by providing options with the same names in your own parsing table. If you try this, your options with the same names will simply not be set to the values specified on the command line. Instead, the standard options will be set to these values. This was a design decision in Xt, one of the few cases where a user-interface policy is enforced. Uniformity in this basic area was deemed more valuable than flexibility.
See Also
XtAppInitialize(1), XtOpenDisplay(1), XtToolkitInitialize(1).