xref: /xsrc/external/mit/libXt/dist/specs/CH02.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter id='Widget_Instantiation'>
<title>Widget Instantiation</title>
<para>
A hierarchy of widget instances constitutes a widget tree.
The shell widget returned by
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
is the root of the widget tree instance.
The widgets with one or more children are the intermediate nodes of that tree,
and the widgets with no children of any kind are the leaves of the widget tree.
With the exception of pop-up children (see <xref linkend='Pop_Up_Widgets' />),
this widget tree instance defines the associated X Window tree.
</para>

<para>
Widgets can be either composite or primitive.
Both kinds of widgets can contain children,
but the Intrinsics provide a set of management mechanisms for constructing
and interfacing between composite widgets, their children, and
other clients.
</para>

<para>
Composite widgets, that is, members of the class
<function>compositeWidgetClass</function>,
are containers for an arbitrary,
but widget implementation-defined, collection of children,
which may be instantiated by the composite widget itself,
by other clients, or by a combination of the two.
Composite widgets also contain methods for managing the geometry (layout)
of any child widget.
Under unusual circumstances,
a composite widget may have zero children,
but it usually has at least one.
By contrast,
primitive widgets that contain children typically instantiate
specific children of known classes themselves and do not expect external
clients to do so.
Primitive widgets also do not have general geometry management methods.
</para>

<para>
In addition,
the Intrinsics recursively perform many operations
(for example, realization and destruction)
on composite widgets and all their children.
Primitive widgets that have children must be prepared
to perform the recursive operations themselves on behalf of their children.
</para>

<para>
A widget tree is manipulated by several Intrinsics functions.
For example,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
traverses the tree downward and recursively realizes all
pop-up widgets and children of composite widgets.
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
traverses the tree downward and destroys all pop-up widgets
and children of composite widgets.
The functions that fetch and modify resources traverse the tree upward
and determine the inheritance of resources from a widget's ancestors.
<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
traverses the tree up one level and calls the geometry manager
that is responsible for a widget child's geometry.
</para>

<para>
To facilitate upward traversal of the widget tree,
each widget has a pointer to its parent widget.
The
Shell
widget that
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
returns has a <emphasis remap='I'>parent</emphasis> pointer of NULL.
</para>

<para>
To facilitate downward traversal of the widget tree,
the <emphasis remap='I'>children</emphasis> field of
each composite widget is a pointer to an array of child widgets,
which includes all normal children created,
not just the subset of children that are managed by the composite widget's
geometry manager.
Primitive widgets
that instantiate children are entirely responsible for all operations
that require downward traversal below themselves.
In addition,
every widget has a pointer to an array of pop-up children.
</para>

<sect1 id="Initializing_the_tk">
<title>Initializing the X Toolkit</title>
<para>
Before an application can call any Intrinsics function
other than
<function>XtSetLanguageProc</function>
and
<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>,
it must initialize the Intrinsics by using
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
which initializes the Intrinsics internals
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
which initializes the per-application state
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
or
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
which initializes the per-display state
    </para>
  </listitem>
  <listitem>
    <para>
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
which creates the root of a widget tree
    </para>
  </listitem>
</itemizedlist>
<para>
Or an application can call the convenience procedure
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
which combines the functions of the preceding procedures.
An application wishing to use the ANSI C locale mechanism should call
<function>XtSetLanguageProc</function>
prior to calling
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
or
<xref linkend='XtAppInitialize' xrefstyle='select: title'/>.
</para>

<para>
Multiple instances of X Toolkit applications may be implemented
in a single address space.
Each instance needs to be able to read
input and dispatch events independently of any other instance.
Further, an application instance may need multiple display connections
to have widgets on multiple displays.
From the application's point of view, multiple display connections
usually are treated together as a single unit
for purposes of event dispatching.
To accommodate both requirements,
the Intrinsics define application contexts,
each of which provides the information needed to distinguish one application
instance from another.
The major component of an application context is a list of one or more X
<function>Display</function>
pointers for that application.
The Intrinsics handle all display connections within a single application
context simultaneously, handling input in a round-robin fashion.
The application context type
<function>XtAppContext</function>
is opaque to clients.
</para>

<para>
To initialize the Intrinsics internals, use
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtToolkitInitialize'>
<funcprototype>
  <funcdef>void <function>XtToolkitInitialize</function></funcdef>
  <paramdef><parameter>void</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<para>
If
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
was previously called, it returns immediately.
When
<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
is called before
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
the latter is protected against
simultaneous activation by multiple threads.
</para>

<para>
To create an application context, use
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCreateApplicationContext'>
<funcprototype>
  <funcdef>XtAppContext <function>XtCreateApplicationContext</function></funcdef>
  <paramdef><parameter>void</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<para>
The
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>
function returns an application context,
which is an opaque type.
Every application must have at least one application context.
</para>

<para>
To destroy an application context and close any
remaining display connections in it, use
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtDestroyApplicationContext'>
<funcprototype>
  <funcdef>void <function>XtDestroyApplicationContext</function></funcdef>
  <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
function destroys the specified application context.
If called from within an event dispatch (for example, in a callback procedure),
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
does not destroy the application context until the dispatch is complete.
</para>

<para>
To get the application context in which a given widget was created, use
<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtWidgetToApplicationContext'>
<funcprototype>
  <funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget for which you want the application context.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
function returns the application context for the specified widget.
</para>

<para>
To initialize a display and add it to an application context, use
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtDisplayInitialize'>
<funcprototype>
  <funcdef>void  <function>XtDisplayInitialize</function></funcdef>
      <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
      <paramdef>Display * <parameter>display</parameter></paramdef>
      <paramdef>const char * <parameter>application_name</parameter></paramdef>
      <paramdef>const char * <parameter>application_class</parameter></paramdef>
      <paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
      <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
      <paramdef>int * <parameter>argc</parameter></paramdef>
      <paramdef>char ** <parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies a previously opened display connection.  Note that a single
display connection can be in at most one application context.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the name of the application instance.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the class name of this application,
which is usually the generic name for all instances of this application.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>options</emphasis>
    </term>
    <listitem>
      <para>
Specifies how to parse the command line for any application-specific resources.
The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to
<function>XrmParseCommand</function>.
For further information,
see <olink targetdoc='libX11' targetptr='Parsing_Command_Line_Options'>Parsing Command Line Options</olink> in <olink targetdoc='libX11' targetptr='libX11'>Xlib &mdash; C Language X Interface</olink> and <xref linkend='Parsing_the_Command_Line' /> of this specification.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_options</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the options list.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argc</emphasis>
    </term>
    <listitem>
      <para>
Specifies a pointer to the number of command line parameters.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argv</emphasis>
    </term>
    <listitem>
      <para>
Specifies the list of command line parameters.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
function retrieves the language string to be
used for the specified display (see <xref linkend='Finding_File_Names' />),
calls the language procedure (if set) with that language string,
builds the resource database for the default screen, calls the Xlib
<function>XrmParseCommand</function>
function to parse the command line,
and performs other per-display initialization.
After
<function>XrmParseCommand</function>
has been called,
<emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> contain only those parameters that
were not in the standard option table or in the table specified by the
<emphasis remap='I'>options</emphasis> argument.
If the modified <emphasis remap='I'>argc</emphasis> is not zero,
most applications simply print out the modified <emphasis remap='I'>argv</emphasis> along with a message
listing the allowable options.
On POSIX-based systems,
the application name is usually the final component of <emphasis remap='I'>argv</emphasis>[0].
If the synchronous resource is
<function>True</function>,
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
calls the Xlib
<function>XSynchronize</function>
function to put Xlib into synchronous mode for this display connection
and any others currently open in the application context.
See <xref linkend='Loading_the_Resource_Database' />
and <xref linkend='Parsing_the_Command_Line' />
for details on the <emphasis remap='I'>application_name</emphasis>,
<emphasis remap='I'>application_class</emphasis>, <emphasis remap='I'>options</emphasis>, and <emphasis remap='I'>num_options</emphasis> arguments.
</para>

<para>
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
calls
<function>XrmSetDatabase</function>
to associate the resource database of the default screen with the
display before returning.
</para>

<para>
To open a display, initialize it, and then
add it to an application context, use
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtOpenDisplay'>
<funcprototype>
  <funcdef>Display *<function>XtOpenDisplay</function></funcdef>
       <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
       <paramdef>const char * <parameter>display_string</parameter></paramdef>
       <paramdef>const char * <parameter>application_name</parameter></paramdef>
       <paramdef>const char * <parameter>application_class</parameter></paramdef>
       <paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
       <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
       <paramdef>int * <parameter>argc</parameter></paramdef>
       <paramdef>char ** <parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>




<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>display_string</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display string, or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the name of the application instance, or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the class name of this application,
which is usually the generic name for all instances of this application.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>options</emphasis>
    </term>
    <listitem>
      <para>
Specifies how to parse the command line for any application-specific resources.
The options argument is passed as a parameter to
<function>XrmParseCommand</function>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_options</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the options list.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argc</emphasis>
    </term>
    <listitem>
      <para>
Specifies a pointer to the number of command line parameters.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argv</emphasis>
    </term>
    <listitem>
      <para>
Specifies the list of command line parameters.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
function calls
<function>XOpenDisplay</function>
with the specified <emphasis remap='I'>display_string</emphasis>.
If <emphasis remap='I'>display_string</emphasis> is NULL,
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
uses the current value of the -display option specified in <emphasis remap='I'>argv</emphasis>.
If no display is specified in <emphasis remap='I'>argv</emphasis>,
the user's default display is retrieved from the environment.
On POSIX-based systems,
this is the value of the
<emphasis role='strong'>DISPLAY</emphasis>
environment variable.
</para>

<para>
If this succeeds,
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
then calls
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
and passes it the opened display and
the value of the -name option specified in <emphasis remap='I'>argv</emphasis> as the application name.
If no -name option is specified
and <emphasis remap='I'>application_name</emphasis> is
non-NULL, <emphasis remap='I'>application_name</emphasis> is passed to
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
If <emphasis remap='I'>application_name</emphasis> is NULL and if the environment variable
<emphasis role='strong'>RESOURCE_NAME</emphasis>
is set, the value of
<emphasis role='strong'>RESOURCE_NAME</emphasis>
is used.  Otherwise, the application
name is the name used to invoke the program.  On implementations that
conform to ANSI C Hosted Environment support, the application name will
be <emphasis remap='I'>argv</emphasis>[0] less any directory and file type components, that is, the
final component of <emphasis remap='I'>argv</emphasis>[0], if specified.  If <emphasis remap='I'>argv</emphasis>[0] does not exist or
is the empty string, the application name is &ldquo;main&rdquo;.
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
returns the newly opened display or NULL if it failed.
</para>

<para>
See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
for information regarding the use of
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
in multiple threads.
</para>

<para>
To close a display and remove it from an application context, use
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCloseDisplay'>
<funcprototype>
  <funcdef>void <function>XtCloseDisplay</function></funcdef>
       <paramdef>Display * <parameter>display</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
function calls
<function>XCloseDisplay</function>
with the specified <emphasis remap='I'>display</emphasis> as soon as it is safe to do so.
If called from within an event dispatch (for example, a callback procedure),
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
does not close the display until the dispatch is complete.
Note that applications need only call
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
if they are to continue executing after closing the display;
otherwise, they should call
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
</para>

<para>
See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
for information regarding the use of
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
in multiple threads.
</para>
</sect1>

<sect1 id="Establishing_the_Locale">
<title>Establishing the Locale</title>
<para>
Resource databases are specified to be created in the current process
locale.  During display initialization prior to creating the
per-screen resource database, the Intrinsics will call out to a specified
application procedure to set the locale according to options found on
the command line or in the per-display resource specifications.
</para>

<para>
The callout procedure provided by the application is of type
<function>XtLanguageProc</function>.
</para>

<funcsynopsis>
<funcprototype>
  <funcdef>typedef String <function>(*XtLanguageProc)</function></funcdef>
  <paramdef>Display <parameter>display</parameter></paramdef>
  <paramdef>String <parameter>language</parameter></paramdef>
  <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Passes the display.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>language</emphasis>
    </term>
    <listitem>
      <para>
Passes the initial language value obtained from the command line
or server per-display resource specifications.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Passes the additional client data specified in the call to
<function>XtSetLanguageProc</function>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
<para>
The language procedure allows an application to set the locale to
the value of the language resource determined by
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
The function returns a new language string that
will be subsequently used by
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
to establish the path for loading resource files.  The returned
string  will be copied by the Intrinsics into new memory.
</para>

<para>
Initially, no language procedure is set by the Intrinsics.
To set the language procedure for use by
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
use
<function>XtSetLanguageProc</function>.
</para>

<funcsynopsis>
<funcprototype>
  <funcdef>XtLanguageProc <function>XtSetLanguageProc</function></funcdef>
  <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
  <paramdef>XtLanguageProc <parameter>proc</parameter></paramdef>
  <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context in which the language procedure is
to be used, or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the language procedure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies additional client data to be passed to the language
procedure when it is called.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XtSetLanguageProc</function>
sets the language procedure that will be called from
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
for all subsequent Displays initialized in the specified application
context.   If <emphasis remap='I'>app_context</emphasis> is NULL, the specified language
procedure is registered in all application contexts created by the
calling process, including any future application contexts that may
be created.   If <emphasis remap='I'>proc</emphasis> is NULL, a default language procedure is
registered.
<function>XtSetLanguageProc</function>
returns the previously registered language procedure.
If a language procedure has not yet been registered, the return value
is unspecified, but if this return value is used in a subsequent call to
<function>XtSetLanguageProc</function>,
it will cause the default language procedure to be registered.
</para>

<para>
The default language procedure does the following:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Sets the locale according to the environment.  On ANSI C-based
systems this is done by calling
<function>setlocale</function>(
<function>LC_ALL</function>,
<emphasis remap='I'>language</emphasis> ).
If an error is encountered, a warning message is issued with
<xref linkend='XtWarning' xrefstyle='select: title'/>.
    </para>
  </listitem>
  <listitem>
    <para>
Calls
<function>XSupportsLocale</function>
to verify that the current locale is supported.
If the locale is not supported, a warning message is issued with
<xref linkend='XtWarning' xrefstyle='select: title'/>
and the locale is set to &ldquo;C&rdquo;.
    </para>
  </listitem>
  <listitem>
    <para>
Calls
<function>XSetLocaleModifiers</function>
specifying the empty string.
    </para>
  </listitem>
  <listitem>
    <para>
Returns the value of the current locale.  On ANSI C-based systems this
is the return value from a final call to
<function>setlocale</function>(
<function>LC_ALL</function>,
NULL ).
    </para>
  </listitem>
</itemizedlist>
<para>
A client wishing to use this mechanism to establish locale can do so
by calling
<function>XtSetLanguageProc</function>
prior to
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
as in the following example.
</para>
<programlisting>
	Widget top;
	XtSetLanguageProc(NULL, NULL, NULL);
	top = XtOpenApplication(...);
	...
</programlisting>
</sect1>

<sect1 id="Loading_the_Resource_Database">
<title>Loading the Resource Database</title>
<para>
The
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
function first determines the language
string to be used for the specified display.  It then
creates a resource database for the default screen of the display by
combining the following sources in order, with the entries in the
first named source having highest precedence:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Application command line (<emphasis remap='I'>argc</emphasis>, <emphasis remap='I'>argv</emphasis>).
    </para>
  </listitem>
  <listitem>
    <para>
Per-host user environment resource file on the local host.
    </para>
  </listitem>
  <listitem>
    <para>
Per-screen resource specifications from the server.
    </para>
  </listitem>
  <listitem>
    <para>
Per-display resource specifications from the server or from
the user preference file on the local host.
    </para>
  </listitem>
  <listitem>
    <para>
Application-specific user resource file on the local host.
    </para>
  </listitem>
  <listitem>
    <para>
Application-specific class resource file on the local host.
    </para>
  </listitem>
</itemizedlist>
<para>
When the resource database for a particular screen on the display
is needed (either internally, or when
<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
is called),
it is created in the following manner using the sources listed
above in the same order:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
A temporary database, the &ldquo;server resource database&rdquo;, is
created from the string returned by
<function>XResourceManagerString</function>
or, if
<function>XResourceManagerString</function>
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/<function>.Xdefaults</function>.
    </para>
  </listitem>
  <listitem>
    <para>
If a language procedure has been set,
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
first searches the command line for the option &ldquo;-xnlLanguage&rdquo;, or
for a -xrm option that specifies the xnlLanguage/XnlLanguage resource,
as specified by Section 2.4.
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,
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
queries the server resource database (which is assumed to be entirely
in XPCS) for the resource
<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
where <emphasis remap='I'>name</emphasis>
and <emphasis remap='I'>Class</emphasis> are the <emphasis remap='I'>application_name</emphasis> and
<emphasis remap='I'>application_class</emphasis> specified to
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
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
references in the Intrinsics that require the per-display language string.
    </para>
  </listitem>
  <listitem>
    <para>
The screen resource database is initialized by parsing the command
line in the manner specified by Section 2.4.
    </para>
  </listitem>
  <listitem>
    <para>
If a language procedure has not been set,
the initial database is then queried for the resource
<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
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
<emphasis role='strong'>LANG</emphasis>
environment variable.  If no language string is
found, the empty string is used.
This language string is saved for all future references in the Intrinsics
that require the per-display language string.
    </para>
  </listitem>
  <listitem>
    <para>
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
<emphasis role='strong'>XENVIRONMENT</emphasis>
environment variable.
If this environment variable does not exist, the user's home directory
is searched for a file named
<function>.Xdefaults-</function><emphasis>host</emphasis>,
where <emphasis remap='I'>host</emphasis> is the host name of the machine on which the
application is running.
    </para>
  </listitem>
  <listitem>
    <para>
The per-screen resource specifications are then merged into the screen
resource database, if they exist.  These specifications are the string
returned by
<function>XScreenResourceString</function>
for the respective screen and are owned entirely by the user.
    </para>
  </listitem>
  <listitem>
    <para>
Next, the server resource database created earlier is merged into the
screen resource database.  The server property, and corresponding user
preference file, are owned and constructed entirely by the user.
    </para>
  </listitem>
  <listitem>
    <para>
The application-specific user resource file from the local host is
then merged into the screen resource database.
This file contains user customizations and is stored
in a directory owned by the user.
Either the user or the application or both can store resource specifications
in the file.  Each should be prepared to find and respect entries made
by the other.
The file name is found by calling
<function>XrmSetDatabase</function>
with the current screen resource database, after preserving the
original display-associated database, then calling
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
with the parameters
(<emphasis remap='I'>display</emphasis>, NULL, NULL, NULL, <emphasis remap='I'>path</emphasis>, NULL, 0, NULL),
where <emphasis remap='I'>path</emphasis> is defined in an operating-system-specific way.
On POSIX-based systems, <emphasis remap='I'>path</emphasis> is defined to be the value
of the environment variable
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
if this is defined.  If
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
is not defined, an implementation-dependent default value is used.
This default value is constrained in the following manner:
    </para>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>
If the environment variable
<emphasis role='strong'>XAPPLRESDIR</emphasis>
is not defined, the default
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
must contain at least six entries.  These entries must contain
$HOME as the directory prefix, plus the following substitutions:
        </para>
<programlisting>
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
</programlisting>
        <para>
The order of these six entries within the path must be as given above.
The order and use of substitutions within a given entry are
implementation-dependent.
        </para>
      </listitem>
      <listitem>
        <para> If
<emphasis role='strong'>XAPPLRESDIR</emphasis>
is defined, the default
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
must contain at least seven entries.  These entries must contain the
following directory prefixes and substitutions:
        </para>
<programlisting>
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
</programlisting>
        <para>
The order of these seven entries within the path must be as given above.
The order and use of substitutions within a given entry are
implementation-dependent.
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
  <listitem>
    <para>
Last, 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 installed in
a system directory when the application is installed.
It may contain sitewide customizations specified by the system manager.
The name of the application class resource file is found by calling
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
with the parameters
(<emphasis remap='I'>display</emphasis>, &ldquo;app-defaults&rdquo;, NULL, NULL, NULL, NULL, 0, NULL).
This file is expected to be provided 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
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
Note that the customization substitution string is retrieved
dynamically by
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
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.  After calling
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>,
the original display-associated database is restored.
    </para>
  </listitem>
</itemizedlist>

<para>
To obtain the resource database for a particular screen, use
<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtScreenDatabase'>
<funcprototype>
  <funcdef>XrmDatabase <function>XtScreenDatabase</function></funcdef>
      <paramdef>Screen * <parameter>screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>screen</emphasis>
    </term>
    <listitem>
      <para>
Specifies the screen whose resource database is to be returned.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
function returns the fully merged resource database as specified above,
associated with the specified screen.  If the specified <emphasis remap='I'>screen</emphasis>
does not belong to a
<function>Display</function>
initialized by
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
the results are undefined.
</para>

<para>
To obtain the default resource database associated with a particular display, use
<xref linkend='XtDatabase' xrefstyle='select: title'/>.
</para>


<funcsynopsis id='XtDatabase'>
<funcprototype>
  <funcdef>XrmDatabase <function>XtDatabase</function></funcdef>
      <paramdef>Display * <parameter>display</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtDatabase' xrefstyle='select: title'/>
function is equivalent to
<function>XrmGetDatabase</function>.
It returns the database associated with the specified display, or
NULL if a database has not been set.
</para>

<para>
To specify a default set of resource values that will be used to
initialize the resource database if no application-specific class
resource file is found (the last of the six sources listed above),
use
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAppSetFallbackResources'>
<funcprototype>
  <funcdef>void <function>XtAppSetFallbackResources</function></funcdef>
      <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
      <paramdef>String * <parameter>specification_list</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context in which
the fallback specifications will be used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>specification_list</emphasis>
    </term>
    <listitem>
      <para>
Specifies a NULL-terminated list of
resource specifications to preload
the database, or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
Each entry in <emphasis remap='I'>specification_list</emphasis> points to a string in the format of
<function>XrmPutLineResource</function>.
Following a call to
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>,
when a resource database is being created for a particular screen and
the Intrinsics are not able
to find or read an application-specific class resource file according to the
rules given above and if <emphasis remap='I'>specification_list</emphasis> is not NULL, the
resource specifications in <emphasis remap='I'>specification_list</emphasis> will be merged
into the screen resource database in place of the application-specific
class resource file.
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
is not
required to copy <emphasis remap='I'>specification_list</emphasis>; the caller must ensure that the
contents of the list and of the strings addressed by the list remain
valid until all displays are initialized or until
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
is called again.  The value NULL for
<emphasis remap='I'>specification_list</emphasis> removes any previous fallback resource specification
for the application context.  The intended use for fallback resources
is to provide a minimal
number of resources that will make the application usable (or at
least terminate with helpful diagnostic messages) when some problem
exists in finding and loading the application defaults file.
</para>
</sect1>

<sect1 id="Parsing_the_Command_Line">
<title>Parsing the Command Line</title>
<para>
The
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
function first parses the command line for the following options:
<variablelist>
  <varlistentry>
    <term>-display</term>
    <listitem>
      <para>
Specifies the display name for
<function>XOpenDisplay</function>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>-name</term>
    <listitem>
      <para>
Sets the resource name prefix,
which overrides the application name passed to
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>-xnllanguage</term>
    <listitem>
      <para>
Specifies the initial language string for establishing locale
and for finding application class resource files.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>

<para>
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
has a table of standard command line options that are passed to
<function>XrmParseCommand</function>
for adding resources to the resource database,
and it takes as a parameter additional
application-specific resource abbreviations.
The format of this table is described in Section 15.9 in <emphasis remap='I'>Xlib &mdash; C Language X Interface</emphasis>.
</para>
<programlisting>
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,    /* Use the next argument as input to XrmPutLineResource*/
     XrmoptionSkipArg,   /* Ignore this option and the next argument in argv */
     XrmoptionSkipNArgs, /* Ignore this option and the next */
                         /* OptionDescRec.value arguments in argv */
     XrmoptionSkipLine   /* Ignore this option and the rest of argv */
} XrmOptionKind;

typedef struct {
     char *option;       /* Option name in argv */
     char *specifier;    /* Resource name (without application name) */
     XrmOptionKind argKind; /* Location of the resource value */
     XPointer value;     /* Value to provide if XrmoptionNoArg */
} XrmOptionDescRec, *XrmOptionDescList;
</programlisting>
<para>The standard table contains the following entries:</para>

<informaltable frame='topbot'>
  <?dbfo keep-together="always" ?>
  <tgroup cols='4' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='1.0*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <colspec colwidth='1.0*' colname='c3'/>
  <colspec colwidth='1.0*' colname='c4'/>
  <thead>
    <row rowsep='1'>
      <entry>Option String</entry>
      <entry>Resource Name</entry>
      <entry>Argument Kind</entry>
      <entry>Resource Value</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>-background</entry>
      <entry>*background</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-bd</entry>
      <entry>*borderColor</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-bg</entry>
      <entry>*background</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-borderwidth</entry>
      <entry>.borderWidth</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-bordercolor</entry>
      <entry>*borderColor</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-bw</entry>
      <entry>.borderWidth</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-display</entry>
      <entry>.display</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-fg</entry>
      <entry>*foreground</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-fn</entry>
      <entry>*font</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-font</entry>
      <entry>*font</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-foreground</entry>
      <entry>*foreground</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-geometry</entry>
      <entry>.geometry</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-iconic</entry>
      <entry>.iconic</entry>
      <entry>NoArg</entry>
      <entry>"true"</entry>
    </row>
    <row>
      <entry>-name</entry>
      <entry>.name</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-reverse</entry>
      <entry>.reverseVideo</entry>
      <entry>NoArg</entry>
      <entry>"on"</entry>
    </row>
    <row>
      <entry>-rv</entry>
      <entry>.reverseVideo</entry>
      <entry>NoArg</entry>
      <entry>"on"</entry>
    </row>
    <row>
      <entry>+rv</entry>
      <entry>.reverseVideo</entry>
      <entry>NoArg</entry>
      <entry>"off"</entry>
    </row>
    <row>
      <entry>-selectionTimeout</entry>
      <entry>.selectionTimeout</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-synchronous</entry>
      <entry>.synchronous</entry>
      <entry>NoArg</entry>
      <entry>"on"</entry>
    </row>
    <row>
      <entry>+synchronous</entry>
      <entry>.synchronous</entry>
      <entry>NoArg</entry>
      <entry>"off"</entry>
    </row>
    <row>
      <entry>-title</entry>
      <entry>.title</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-xnllanguage</entry>
      <entry>.xnlLanguage</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-xrm</entry>
      <entry>next argument</entry>
      <entry>ResArg</entry>
      <entry>next argument</entry>
    </row>
    <row>
      <entry>-xtsessionID</entry>
      <entry>.sessionID</entry>
      <entry>SepArg</entry>
      <entry>next argument</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>
Note that any unique abbreviation for an option name in the standard table
or in the application table is accepted.
</para>

<para>
If reverseVideo is
<function>True</function>,
the values of
<function>XtDefaultForeground</function>
and
<function>XtDefaultBackground</function>
are exchanged for all screens on the Display.
</para>

<para>
The value of the synchronous resource specifies whether or not
Xlib is put into synchronous mode.  If a value is found in the resource
database during display initialization,
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
makes a call to
<function>XSynchronize</function>
for all display
connections currently open in the application context.  Therefore,
when multiple displays are initialized in the same application
context, the most recent value specified for the synchronous resource
is used for all displays in the application context.
</para>

<para>
The value of the selectionTimeout resource applies to all displays
opened in the same application context.  When multiple displays are
initialized in the same application context, the most recent value
specified is used for all displays in the application context.
</para>

<para>
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 resource file.
For example,
to give a red background to all command buttons in an application named
<function>xmh</function>,
you can start it up as
</para>
<programlisting>
xmh -xrm 'xmh*Command.background: red'
</programlisting>
<para>
When it parses the command line,
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
merges the application option table with the standard option table
before calling the Xlib
<function>XrmParseCommand</function>
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.
The Intrinsics reserve all option names
beginning with the characters &ldquo;-xt&rdquo; for future standard uses.
</para>
</sect1>

<sect1 id="Creating_Widgets">
<title>Creating Widgets</title>
<para>
The creation of widget instances is a three-phase process:
</para>

<orderedlist>
  <listitem>
    <para>
The widgets are allocated and initialized with resources
and are optionally added to the managed subset of their parent.
    </para>
  </listitem>
  <listitem>
    <para>
All composite widgets are notified of their managed children
in a bottom-up traversal of the widget tree.
    </para>
  </listitem>
  <listitem>
    <para>
The widgets create X windows, which then are mapped.
    </para>
  </listitem>
</orderedlist>
<para>
To start the first phase,
the application calls
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
for all its widgets and adds some (usually, most or all) of its widgets
to their respective parents' managed set by calling
<xref linkend='XtManageChild' xrefstyle='select: title'/>.
To avoid an O(n<superscript>2</superscript>) creation process where each composite widget
lays itself out each time a widget is created and managed,
parent widgets are not notified of changes in their managed set
during this phase.
</para>

<para>
After all widgets have been created,
the application calls
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
with the top-level widget to execute the second and third phases.
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
first recursively traverses the widget tree in a postorder (bottom-up)
traversal and then notifies each composite widget with one
or more managed children by means of its change_managed procedure.
</para>

<para>
Notifying a parent about its managed set involves geometry layout and
possibly geometry negotiation.
A parent deals with constraints on its size imposed from above
(for example, when a user specifies the application window size)
and suggestions made from below (for example,
when a primitive child computes its preferred size).
One difference between the two can cause geometry changes to ripple
in both directions through the widget tree.
The parent may force some of its children to change size and position
and may issue geometry requests to its own parent in order to better
accommodate all its children.
You cannot predict where anything will go on the screen
until this process finishes.
</para>

<para>
Consequently, in the first and second phases,
no X windows are actually created, because it is likely
that they will get moved around after creation.
This avoids unnecessary requests to the X server.
</para>

<para>
Finally,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
starts the third phase by making a preorder (top-down) traversal
of the widget tree, allocates an X window to each widget by means of
its realize procedure, and finally maps the widgets that are managed.
</para>

<sect2 id="Creating_and_Merging_Argument_Lists">
<title>Creating and Merging Argument Lists</title>
<para>
Many Intrinsics functions may be passed pairs of resource names and
values.
These are passed as an arglist, a pointer to an array of
<function>Arg</function>
structures, which contains
</para>
<programlisting>
typedef struct {
	String name;
	XtArgVal value;
} Arg, *ArgList;
</programlisting>
<para>
where
<function>XtArgVal</function>
is as defined in Section 1.5.
</para>

<para>
If the size of the resource is less than or equal to the size of an
<function>XtArgVal</function>,
the resource value is stored directly in <emphasis remap='I'>value</emphasis>;
otherwise, a pointer to it is stored in <emphasis remap='I'>value</emphasis>.
</para>

<para>
To set values in an
<function>ArgList</function>,
use
<xref linkend='XtSetArg' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtSetArg'>
<funcprototype>
  <funcdef>void <function>XtSetArg</function></funcdef>
  <paramdef>Arg <parameter>arg</parameter></paramdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>XtArgVal <parameter>value</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>arg</emphasis>
    </term>
    <listitem>
      <para>
Specifies the <emphasis remap='I'>name/value</emphasis> pair to set.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the name of the resource.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>value</emphasis>
    </term>
    <listitem>
      <para>
Specifies the value of the resource if it will fit in an
<function>XtArgVal</function>,
else the address.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtSetArg' xrefstyle='select: title'/>
function is usually used in a highly stylized manner to
minimize the probability of making a mistake; for example:
</para>
<programlisting>
Arg args[20];
int n;
n = 0;
XtSetArg(args[n], XtNheight, 100);      n++;
XtSetArg(args[n], XtNwidth, 200);       n++;
XtSetValues(widget, args, n);
</programlisting>
<para>
Alternatively, an application can statically declare the argument list
and use
<xref linkend='XtNumber' xrefstyle='select: title'/>:
</para>
<programlisting>
static Args args[] = {
	{XtNheight, (XtArgVal) 100},
	{XtNwidth, (XtArgVal) 200},
};
XtSetValues(Widget, args, XtNumber(args));
</programlisting>
<para>
Note that you should not use expressions with side effects such as
auto-increment or auto-decrement
within the first argument to
<xref linkend='XtSetArg' xrefstyle='select: title'/>.
<xref linkend='XtSetArg' xrefstyle='select: title'/>
can be implemented as a macro that evaluates the first argument twice.
</para>

<para>
To merge two
arglist arrays, use
<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtMergeArgLists'>
<funcprototype>
  <funcdef>ArgList <function>XtMergeArgLists</function></funcdef>
     <paramdef>ArgList <parameter>args1</parameter></paramdef>
     <paramdef>Cardinal <parameter>num_args1</parameter></paramdef>
     <paramdef>ArgList <parameter>args2</parameter></paramdef>
     <paramdef>Cardinal <parameter>num_args2</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>args1</emphasis>
    </term>
    <listitem>
      <para>
Specifies the first argument list.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args1</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the first argument list.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args2</emphasis>
    </term>
    <listitem>
      <para>
Specifies the second argument list.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args2</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the second argument list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>
function allocates enough storage to hold the combined
arglist arrays and copies them into it.
Note that it does not check for duplicate entries.
The length of the returned list is the sum of the lengths of the
specified lists.
When it is no longer needed,
free the returned storage by using
<xref linkend='XtFree' xrefstyle='select: title'/>.
</para>

<para>
All Intrinsics interfaces that require
<function>ArgList</function>
arguments have analogs
conforming to the ANSI C variable argument list
(traditionally called &ldquo;varargs&rdquo;)
calling convention.  The name of the analog is formed by prefixing
&ldquo;Va&rdquo; to the name of the corresponding
<function>ArgList</function>
procedure; e.g.,
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
Each procedure named <function>XtVa</function><emphasis remap='I'>something</emphasis> takes as its
last arguments, in place of the corresponding
<function>ArgList</function>/
<function>Cardinal</function>
parameters, a variable parameter list of resource name and
value pairs where each name is of type
<function>String</function>
and each value is of type
<function>XtArgVal</function>.
The end of the list is identified by a <emphasis remap='I'>name</emphasis> entry
containing NULL.  Developers writing in the C language wishing to pass
resource name and value pairs to any of these interfaces may use the
<function>ArgList</function>
and varargs forms interchangeably.
</para>

<para>
Two special names are defined for use only in varargs lists:
<function>XtVaTypedArg</function>
and
<function>XtVaNestedList</function>.
</para>
<programlisting>
#define XtVaTypedArg "XtVaTypedArg"
</programlisting>
<para>
If the name
<function>XtVaTypedArg</function>
is specified in place of a resource
name, then the following four arguments are interpreted as a
<emphasis remap='I'>name/type/value/size</emphasis> tuple <emphasis remap='I'>where</emphasis> name is of type
<function>String</function>,
<emphasis remap='I'>type</emphasis> is of type
<function>String</function>,
<emphasis remap='I'>value</emphasis> is of type
<function>XtArgVal</function>,
and <emphasis remap='I'>size</emphasis> is of type int.  When a varargs list containing
<function>XtVaTypedArg</function>
is processed, a resource type
conversion (see <xref linkend='Resource_Conversions' />) is performed if necessary to convert the
value into the format required by the associated resource.  If <emphasis remap='I'>type</emphasis> is
XtRString, then <emphasis remap='I'>value</emphasis> contains a pointer to the string and <emphasis remap='I'>size</emphasis>
contains the number of bytes allocated, including the trailing null
byte.  If <emphasis remap='I'>type</emphasis> is not XtRString, then <emphasis remap='I'>if</emphasis> size is
less than or equal to
<function>sizeof</function>(<function>XtArgVal</function>), the value should be the data cast to the type
<function>XtArgVal</function>,
otherwise <emphasis remap='I'>value</emphasis> is a pointer to the data.  If the type
conversion fails for any reason, a warning message is issued and the
list entry is skipped.
</para>
<programlisting>
#define XtVaNestedList  "XtVaNestedList"
</programlisting>
<para>
If the name
<function>XtVaNestedList</function>
is specified in place of a resource name,
then the following argument is interpreted as an
<function>XtVarArgsList</function>
value, which specifies another
varargs list that is logically inserted into the original list at the
point of declaration.  The end of the nested list is identified with a
name entry containing NULL.  Varargs lists may nest to any depth.
</para>

<para>
To dynamically allocate a varargs list for use with
<function>XtVaNestedList</function>
in multiple calls, use
<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>.
</para>
<programlisting>
typedef XtPointer XtVarArgsList;
</programlisting>

<funcsynopsis id='XtVaCreateArgsList'>
<funcprototype>
  <funcdef>XtVarArgsList <function>XtVaCreateArgsList</function></funcdef>
     <paramdef>XtPointer <parameter>unused</parameter></paramdef>
     <paramdef> <parameter>...</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>unused</emphasis>
    </term>
    <listitem>
      <para>
This argument is not currently used and must be specified as NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      ...
    </term>
    <listitem>
      <para>
Specifies a variable parameter list of resource
name and value pairs.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>
function allocates memory and copies its arguments into a
single list pointer, which may be used with
<function>XtVaNestedList</function>.
The end of
both lists is identified by a <emphasis remap='I'>name</emphasis> entry containing NULL.  Any entries
of type
<function>XtVaTypedArg</function>
are copied as specified without applying
conversions.  Data passed by reference (including Strings) are not
copied, only the pointers themselves; the caller must ensure that the
data remain valid for the lifetime of the created varargs list.  The
list should be freed using
<xref linkend='XtFree' xrefstyle='select: title'/>
when no longer needed.
</para>

<para>
Use of resource files and of the resource database is generally
encouraged over lengthy arglist or varargs lists whenever possible in
order to permit modification without recompilation.
</para>
</sect2>

<sect2 id="Creating_a_Widget_Instance">
<title>Creating a Widget Instance</title>
<para>
To create an instance of a widget, use
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCreateWidget'>
<funcprototype>
  <funcdef>Widget <function>XtCreateWidget</function></funcdef>
      <paramdef>const char * <parameter>name</parameter></paramdef>
      <paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
      <paramdef>Widget <parameter>parent</parameter></paramdef>
      <paramdef>ArgList <parameter>args</parameter></paramdef>
      <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the resource instance name for the created widget,
which is used for retrieving resources
and, for that reason, should not be the same as any other widget
that is a child of the same parent.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>object_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget class pointer for the created object.  Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>parent</emphasis>
    </term>
    <listitem>
      <para>
Specifies the parent widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the argument list to override any other resource specifications.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the argument list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
function performs all the boilerplate operations of widget
creation, doing the following in order:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Checks to see if the class_initialize procedure has been called for this class
and for all superclasses and, if not, calls those necessary in a
superclass-to-subclass order.
    </para>
  </listitem>
  <listitem>
    <para>
If the specified class is not
<function>coreWidgetClass</function>
or a subclass thereof,
and the parent's class is a subclass of
<function>compositeWidgetClass</function>
and either no extension record in
the parent's composite class part extension field exists with the
<emphasis remap='I'>record_type</emphasis>
<emphasis role='strong'>NULLQUARK</emphasis>
or the <emphasis remap='I'>accepts_objects</emphasis> field in the extension
record is
<function>False</function>,
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
issues a fatal error; see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' /> and <xref linkend='Nonwidget_Objects' />.
    </para>
  </listitem>
  <listitem>
    <para>
If the specified class contains an extension record in the object class
part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>record_type</emphasis>
<emphasis role='strong'>NULLQUARK</emphasis>
and the <emphasis remap='I'>allocate</emphasis> field is not NULL,
the procedure is invoked to allocate memory
for the widget instance.  If the parent is a member of the class
<function>constraintWidgetClass</function>,
the procedure also allocates memory for the
parent's constraints and stores the address of this memory into the
<emphasis remap='I'>constraints</emphasis> field.  If no allocate procedure is found, the Intrinsics
allocate memory for the widget and, when applicable, the constraints,
and initializes the <emphasis remap='I'>constraints</emphasis> field.
    </para>
  </listitem>
  <listitem>
    <para>
Initializes the Core nonresource data fields
<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>being_destroyed</emphasis>,
<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>managed</emphasis>, <emphasis remap='I'>window</emphasis>, <emphasis remap='I'>visible</emphasis>,
<emphasis remap='I'>popup_list</emphasis>, and <emphasis remap='I'>num_popups</emphasis>.
    </para>
  </listitem>
  <listitem>
    <para>
Initializes the resource fields (for example, <emphasis remap='I'>background_pixel</emphasis>)
by using the
<function>CoreClassPart</function>
resource lists specified for this class and all superclasses.
    </para>
  </listitem>
  <listitem>
    <para>
If the parent is a member of the class
<function>constraintWidgetClass</function>,
initializes the resource fields of the constraints record
by using the
<function>ConstraintClassPart</function>
resource lists specified for the parent's class
and all superclasses up to
<function>constraintWidgetClass</function>.
    </para>
  </listitem>
  <listitem>
    <para>
Calls the initialize procedures for the widget starting at the
Object
initialize procedure on down to the widget's initialize procedure.
    </para>
  </listitem>
  <listitem>
    <para>
If the parent is a member of the class
<function>constraintWidgetClass</function>,
calls the
<function>ConstraintClassPart</function>
initialize procedures,
starting at
<function>constraintWidgetClass</function>
on down to the parent's
<function>ConstraintClassPart</function>
initialize procedure.
    </para>
  </listitem>
  <listitem>
    <para>
If the parent is a member of the class
<function>compositeWidgetClass</function>,
puts the widget into its parent's children list by calling its parent's
insert_child procedure.
For further information,
see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' />.
    </para>
  </listitem>
</itemizedlist>
<para>
To create an instance of a widget using varargs lists, use
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtVaCreateWidget'>
<funcprototype>
  <funcdef>Widget <function>XtVaCreateWidget</function></funcdef>
      <paramdef>const char * <parameter>name</parameter></paramdef>
      <paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
      <paramdef>Widget <parameter>parent</parameter></paramdef>
      <paramdef> <parameter>...</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the resource name for the created widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>object_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget class pointer for the created object.  Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>parent</emphasis>
    </term>
    <listitem>
      <para>
Specifies the parent widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      ...
    </term>
    <listitem>
      <para>
Specifies the variable argument list to override any other
resource specifications.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
procedure is identical in function to
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
as described
in Section 2.5.1.
</para>
</sect2>

<sect2 id="Creating_an_Application_Shell_Instance">
<title>Creating an Application Shell Instance</title>
<para>
An application can have multiple top-level widgets, each of which
specifies a unique widget tree
that can potentially be on different screens or displays.
An application uses
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
to create independent widget trees.
</para>

<funcsynopsis id='XtAppCreateShell'>
<funcprototype>
  <funcdef>Widget <function>XtAppCreateShell</function></funcdef>
      <paramdef>const char * <parameter>name</parameter></paramdef>
      <paramdef>const char * <parameter>application_class</parameter></paramdef>
      <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
      <paramdef>Display * <parameter>display</parameter></paramdef>
      <paramdef>ArgList <parameter>args</parameter></paramdef>
      <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the instance name of the shell widget.
If <emphasis remap='I'>name</emphasis> is NULL,
the application name passed to
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
is used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the resource class string to be used in
place of the widget <emphasis remap='I'>class_name</emphasis> string when
<emphasis remap='I'>widget_class</emphasis> is
<function>applicationShellWidgetClass</function>
or a subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget class for the top-level widget (e.g.,
<function>applicationShellWidgetClass ).</function>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display for the default screen
and for the resource database used to retrieve
the shell widget resources.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the argument list to override any other resource specifications.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the argument list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
function
creates a new shell widget instance as the root of a widget tree.
The screen resource for this widget is determined by first scanning
<emphasis remap='I'>args</emphasis> for the XtNscreen argument.  If no XtNscreen argument is
found, the resource database associated with the default screen of
the specified display is queried for the resource <emphasis remap='I'>name</emphasis>.screen,
class <emphasis remap='I'>Class</emphasis>.Screen where <emphasis remap='I'>Class</emphasis> is the specified
<emphasis remap='I'>application_class</emphasis> if <emphasis remap='I'>widget_class</emphasis> is
<function>applicationShellWidgetClass</function>
or a subclass thereof.  If <emphasis remap='I'>widget_class</emphasis> is not
<function>applicationShellWidgetClass</function>
or a subclass, <emphasis remap='I'>Class</emphasis> is the <emphasis remap='I'>class_name</emphasis>
field from the
<function>CoreClassPart</function>
of the specified <emphasis remap='I'>widget_class</emphasis>.
If this query fails, the default
screen of the specified display is used.  Once the screen is determined,
the resource database associated with that screen is used to retrieve
all remaining resources for the shell widget not specified in
<emphasis remap='I'>args</emphasis>.  The widget name and <emphasis remap='I'>Class</emphasis> as determined above are
used as the leftmost (i.e., root) components in all fully qualified
resource names for objects within this widget tree.
</para>

<para>
If the specified widget class is a subclass of WMShell, the name and
<emphasis remap='I'>Class</emphasis> as determined above will be stored into the
<emphasis role='strong'>WM_CLASS</emphasis>
property on the widget's window when it becomes realized.
If the specified <emphasis remap='I'>widget_class</emphasis> is
<function>applicationShellWidgetClass</function>
or a subclass thereof, the
<emphasis role='strong'>WM_COMMAND</emphasis>
property will also be set from the values of the XtNargv and
XtNargc resources.
</para>

<para>
To create multiple top-level shells within a single (logical)
application,
you can use one of two methods:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Designate one shell as the real top-level shell and
create the others as pop-up children of it by using
<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>.
    </para>
  </listitem>
  <listitem>
    <para>
Have all shells as pop-up children of an unrealized top-level shell.
    </para>
  </listitem>
</itemizedlist>
<para>
The first method,
which is best used when there is a clear choice for what is the main window,
leads to resource specifications like the following:
</para>
<programlisting>
xmail.geometry:...              (the main window)
xmail.read.geometry:...         (the read window)
xmail.compose.geometry:...      (the compose window)
</programlisting>
<para>
The second method,
which is best if there is no main window,
leads to resource specifications like the following:
</para>
<programlisting>
xmail.headers.geometry:...      (the headers window)
xmail.read.geometry:...         (the read window)
xmail.compose.geometry:...      (the compose window)
</programlisting>
<para>
To create a top-level widget that is the root of a widget tree using
varargs lists, use
<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtVaAppCreateShell'>
<funcprototype>
  <funcdef>Widget <function>XtVaAppCreateShell</function></funcdef>
      <paramdef>const char * <parameter>name</parameter></paramdef>
      <paramdef>const char * <parameter>application_class</parameter></paramdef>
      <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
      <paramdef>Display * <parameter>display</parameter></paramdef>
      <paramdef>...</paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the instance name of the shell widget.
If <emphasis remap='I'>name</emphasis> is NULL,
the application name passed to
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
is used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the resource class string to be used in
place of the widget <emphasis remap='I'>class_name</emphasis> string when
<emphasis remap='I'>widget_class</emphasis> is
<function>applicationShellWidgetClass</function>
or a subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget class for the top-level widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display for the default screen
and for the resource database used to retrieve
the shell widget resources.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      ...
    </term>
    <listitem>
      <para>
Specifies the variable argument list to override any other
resource specifications.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>
procedure is identical in function to
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
described in Section 2.5.1.
</para>
</sect2>

<sect2 id="Convenience_Procedure_to_Initialize_an_Application">
<title>Convenience Procedure to Initialize an Application</title>
<para>
To initialize the Intrinsics internals, create an application context,
open and initialize a display, and create the initial root shell
instance, an application may use
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
or
<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtOpenApplication'>
<funcprototype>
  <funcdef>Widget <function>XtOpenApplication</function></funcdef>
      <paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
      <paramdef>const char * <parameter>application_class</parameter></paramdef>
      <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
      <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
      <paramdef>int * <parameter>argc_in_out</parameter></paramdef>
      <paramdef>char ** <parameter>argv_in_out</parameter></paramdef>
      <paramdef>String * <parameter>fallback_resources</parameter></paramdef>
      <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
      <paramdef>ArgList <parameter>args</parameter></paramdef>
      <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the application context, if non-NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the class name of the application.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>options</emphasis>
    </term>
    <listitem>
      <para>
Specifies the command line options table.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_options</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argc_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies a pointer to the number of command line arguments.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argv_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies a pointer to the command line arguments.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>fallback_resources</emphasis>
    </term>
    <listitem>
      <para>
Specifies resource values to be used if the application class resource
file cannot be opened or read, or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the class of the widget to be created.  Must be shellWidgetClass
or a subclass.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the argument list to override any
other resource specifications for the created shell widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the argument list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
function calls
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
followed by
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
then calls
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
with <emphasis remap='I'>display_string</emphasis> NULL and
<emphasis remap='I'>application_name</emphasis> NULL, and finally calls
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
with <emphasis remap='I'>name</emphasis> NULL, the specified <emphasis remap='I'>widget_class</emphasis>,
an argument list and count,
and returns the created shell.
The recommended <emphasis remap='I'>widget_class</emphasis> is
<function>sessionShellWidgetClass</function>.
The argument list and count are created by merging
the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> with a list
containing the specified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis>.
The modified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> returned by
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
are returned in <emphasis remap='I'>argc_in_out</emphasis> and <emphasis remap='I'>argv_in_out</emphasis>.  If
<emphasis remap='I'>app_context_return</emphasis> is not NULL, the created application context is
also returned.  If the display specified by the command line cannot be
opened, an error message is issued and
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
terminates the application.  If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL,
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
is called with the value prior to calling
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtVaOpenApplication'>
<funcprototype>
  <funcdef>Widget <function>XtVaOpenApplication</function></funcdef>
      <paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
      <paramdef>const char * <parameter>application_class</parameter></paramdef>
      <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
      <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
      <paramdef>int * <parameter>argc_in_out</parameter></paramdef>
      <paramdef>char ** <parameter>argv_in_out</parameter></paramdef>
      <paramdef>String * <parameter>fallback_resources</parameter></paramdef>
      <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
      <paramdef>...</paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the application context, if non-NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>application_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the class name of the application.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>options</emphasis>
    </term>
    <listitem>
      <para>
Specifies the command line options table.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_options</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argc_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies a pointer to the number of command line arguments.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>argv_in_out</emphasis>
    </term>
    <listitem>
      <para>
Specifies the command line arguments array.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>fallback_resources</emphasis>
    </term>
    <listitem>
      <para>
Specifies resource values to be used if the application class
resource file cannot be opened, or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the class of the widget to be created.  Must be shellWidgetClass
or a subclass.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      ...
    </term>
    <listitem>
      <para>
Specifies the variable argument list to override any other
resource specifications for the created shell.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>
procedure is identical in function to
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
as described
in Section 2.5.1.
</para>
</sect2>

<sect2 id="Widget_Instance_Allocation_The_allocate_Procedure">
<title>Widget Instance Allocation: The allocate Procedure</title>
<para>
A widget class may optionally provide an instance allocation procedure
in the
<function>ObjectClassExtension</function>
record.
</para>

<para>
When the call to create a widget includes a varargs list containing
<function>XtVaTypedArg</function>,
these arguments will be passed to the allocation procedure in an
<function>XtTypedArgList</function>.
</para>
<programlisting>
typedef struct {
	String name;
	String type;
	XtArgVal value;
	int size;
} XtTypedArg, *XtTypedArgList;
</programlisting>
<para>
The allocate procedure pointer in the
<function>ObjectClassExtension</function>
record is of type
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAllocateProc'>
<funcprototype>
  <funcdef>typedef void <function>(*XtAllocateProc)</function></funcdef>
      <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
      <paramdef>Cardinal* <parameter>constraint_size</parameter></paramdef>
      <paramdef>Cardinal* <parameter>more_bytes</parameter></paramdef>
      <paramdef>ArgList <parameter>args</parameter></paramdef>
      <paramdef>Cardinal* <parameter>num_args</parameter></paramdef>
      <paramdef>XtTypedArgList <parameter>typed_args</parameter></paramdef>
      <paramdef>Cardinal* <parameter>num_typed_args</parameter></paramdef>
      <paramdef>Widget* <parameter>new_return</parameter></paramdef>
      <paramdef>XtPointer* <parameter>more_bytes_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget class of the instance to allocate.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>constraint_size</emphasis>
    </term>
    <listitem>
      <para>
Specifies the size of the constraint record to allocate, or 0.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>more_bytes</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of auxiliary bytes of memory to allocate.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the argument list as given in the call to create the widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of arguments.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>typed_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the list of typed arguments given in the call to create the widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_typed_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of typed arguments.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>new_return</emphasis>
    </term>
    <listitem>
      <para>
Returns a pointer to the newly allocated instance, or NULL in case of error.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>more_bytes_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the auxiliary memory if it was requested, or NULL
if requested and an error occurred; otherwise, unchanged.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
At widget allocation time, if an extension record with <emphasis remap='I'>record_type</emphasis>
equal to
<emphasis role='strong'>NULLQUARK</emphasis>
is located through the object class part <emphasis remap='I'>extension</emphasis> field
and the <emphasis remap='I'>allocate</emphasis> field is not NULL, the
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
will be invoked to allocate memory for the widget.  If no ObjectClassPart
extension record is declared with <emphasis remap='I'>record_type equal</emphasis> to
<emphasis role='strong'>NULLQUARK</emphasis>,
then
<function>XtInheritAllocate</function>
and
<function>XtInheritDeallocate</function>
are assumed.
If no
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
is found, the Intrinsics will allocate memory for the widget.
</para>

<para>
An
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
must perform the following:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Allocate memory for the widget instance and return it in <emphasis remap='I'>new_return</emphasis>.
The memory must be at least <emphasis remap='I'>wc-&gt;core_class.widget_size</emphasis> bytes in length,
double-word aligned.
    </para>
  </listitem>
  <listitem>
    <para>
Initialize the <emphasis remap='I'>core.constraints</emphasis> field in the instance record to NULL
or to point to a constraint record.  If <emphasis remap='I'>constraint_size</emphasis>
is not 0, the procedure must allocate memory for the constraint record.
The memory must be double-word aligned.
    </para>
  </listitem>
  <listitem>
    <para>
If <emphasis remap='I'>more_bytes</emphasis> is not 0, then the address of a block of memory
at least <emphasis remap='I'>more_bytes</emphasis> in size, double-word aligned, must be
returned in the <emphasis remap='I'>more_bytes_return</emphasis> parameter,
or NULL to indicate an error.
    </para>
  </listitem>
</itemizedlist>
<para>
A class allocation procedure that envelops the allocation procedure of a
superclass must rely on the enveloped procedure to perform the instance
and constraint allocation.
Allocation procedures should refrain from initializing fields in the
widget record except to store pointers to newly allocated additional memory.
Under no circumstances should an allocation procedure that envelopes
its superclass allocation procedure modify fields in the
instance part of any superclass.
</para>
</sect2>

<sect2 id="Widget_Instance_Initialization_The_initialize_Procedure">
<title>Widget Instance Initialization: The initialize Procedure</title>
<para>
The initialize procedure pointer in a widget class is of type
<xref linkend='XtInitProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtInitProc'>
<funcprototype>
  <funcdef>typedef void <function>(*XtInitProc)</function></funcdef>
  <paramdef>Widget <parameter>request</parameter></paramdef>
  <paramdef>Widget <parameter>new</parameter></paramdef>
  <paramdef>ArgList <parameter>args</parameter></paramdef>
  <paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>request</emphasis>
    </term>
    <listitem>
      <para>
Specifies a copy of the widget with resource values as requested by the
argument list, the resource database, and the widget defaults.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>new</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget with the new values, both resource and nonresource,
that are actually allowed.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the argument list passed by the client, for
computing derived resource values.
If the client created the widget using a varargs form, any resources
specified via
<function>XtVaTypedArg</function>
are converted to the widget representation and the list is transformed
into the
<function>ArgList</function>
format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the argument list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
An initialization procedure performs the following:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Allocates space for and copies any resources referenced by address
that the client is allowed to free or modify
after the widget has been created.
For example,
if a widget has a field that is a
<function>String</function>,
it may choose not to
depend on the characters at that address remaining constant
but dynamically allocate space for the string and copy it to the new space.
Widgets that do not copy one or more resources referenced
by address should clearly so state in their user documentation.
<note><para>
It is not necessary to allocate space for or to copy callback lists.
</para></note>
    </para>
  </listitem>
  <listitem>
    <para>
Computes values for unspecified resource fields.
For example, if <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> are zero,
the widget should compute an appropriate width and height
based on its other resources.
<note><para>
A widget may directly assign only
its own <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> within the initialize, initialize_hook,
set_values, and
set_values_hook procedures; see <xref linkend='Geometry_Management' />.
</para></note>
    </para>
  </listitem>
  <listitem>
    <para>
Computes values for uninitialized nonresource fields that are derived from
resource fields.
For example, graphics contexts (GCs) that the widget uses are derived from
resources like background, foreground, and font.
    </para>
  </listitem>
</itemizedlist>
<para>
An initialization procedure also can check certain fields for
internal consistency.
For example, it makes no sense to specify a colormap for a depth
that does not support that colormap.
</para>

<para>
Initialization procedures are called in superclass-to-subclass order
after all fields specified in the resource lists have been
initialized.  The initialize procedure does not need to examine
<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
if all public resources are declared in the resource list.
Most of the initialization code for a specific widget class deals with fields
defined in that class and not with fields defined in its superclasses.
</para>

<para>
If a subclass does not need an initialization procedure
because it does not need to perform any of the above operations,
it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field in the class record.
</para>

<para>
Sometimes a subclass may want to overwrite values filled in by its
superclass.
In particular, size calculations of a superclass often are
incorrect for a subclass, and in this case,
the subclass must modify or recalculate fields declared
and computed by its superclass.
</para>

<para>
As an example,
a subclass can visually surround its superclass display.
In this case, the width and height calculated by the superclass initialize
procedure are too small and need to be incremented by the size of the surround.
The subclass needs to know if its superclass's size was calculated by the
superclass or was specified explicitly.
All widgets must place themselves into whatever size is explicitly given,
but they should compute a reasonable size if no size is requested.
</para>

<para>
The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> arguments provide the necessary information for
a subclass to determine the difference between an explicitly specified field
and a field computed by a superclass.
The <emphasis remap='I'>request</emphasis> widget is a copy of the widget as initialized by the
arglist and resource database.
The <emphasis remap='I'>new</emphasis> widget starts with the values in the request,
but it has been updated by all superclass initialization procedures called
so far.
A subclass initialize procedure can compare these two to resolve
any potential conflicts.
</para>

<para>
In the above example,
the subclass with the visual surround can see
if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero.
If so,
it adds its surround size to the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis>
fields in the <emphasis remap='I'>new</emphasis> widget.
If not, it must make do with the size originally specified.
</para>

<para>
The <emphasis remap='I'>new</emphasis> widget will become the actual widget instance record.
Therefore,
the initialization procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget;
the <emphasis remap='I'>request</emphasis> widget should never be modified.
If the initialize procedure
needs to call any routines that operate on a widget,
it should specify <emphasis remap='I'>new</emphasis> as the widget instance.
</para>
</sect2>

<sect2 id="Constraint_Instance_Initialization_The_ConstraintClassPart_initialize_Procedure">
<title>Constraint Instance Initialization: The ConstraintClassPart initialize Procedure</title>
<para>
The constraint initialization procedure pointer, found in the
<function>ConstraintClassPart</function>
<emphasis remap='I'>initialize</emphasis> field of the widget class record, is of type
<xref linkend='XtInitProc' xrefstyle='select: title'/>.
The values passed to the parent constraint initialization procedures
are the same as those passed to the child's class widget initialization
procedures.
</para>

<para>
The <emphasis remap='I'>constraints</emphasis> field of the <emphasis remap='I'>request</emphasis> widget points to a copy of the
constraints record as initialized by the arglist and resource database.
</para>

<para>
The constraint initialization procedure should compute any constraint fields
derived from constraint resources.
It can make further changes to the <emphasis remap='I'>new</emphasis> widget to make the widget
and any other constraint fields
conform to the specified constraints, for example,
changing the widget's size or position.
</para>

<para>
If a constraint class does not need a constraint initialization procedure,
it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field of the
<function>ConstraintClassPart</function>
in the class record.
</para>
</sect2>

<sect2 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure">
<title>Nonwidget Data Initialization: The initialize_hook Procedure</title>
<note>
<para>
The initialize_hook procedure is obsolete, as the same information
is now available to the initialize procedure.  The procedure has been
retained for those widgets that used it in previous releases.
</para>
</note>

<para>
The initialize_hook procedure pointer is of type
<xref linkend='XtArgsProc' xrefstyle='select: title'/>:
</para>

<funcsynopsis id='XtArgsProc'>
<funcprototype>
  <funcdef>typedef void <function>(*XtArgsProc)</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
  <paramdef>ArgList <parameter>args</parameter></paramdef>
  <paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the argument list passed by the client.
If the client created the widget using a varargs form, any resources
specified via
<function>XtVaTypedArg</function>
are converted to the widget representation and the list is transformed
into the
<function>ArgList</function>
format.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_args</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in the argument list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
If this procedure is not NULL,
it is called immediately after the corresponding initialize
procedure or in its place if the <emphasis remap='I'>initialize</emphasis> field is NULL.
</para>

<para>
The initialize_hook procedure allows a widget instance to initialize
nonresource data using information from the specified argument list
as if it were a resource.
</para>
</sect2>
</sect1>

<sect1 id="Realizing_Widgets">
<title>Realizing Widgets</title>
<para>
To realize a widget instance, use
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRealizeWidget'>
<funcprototype>
  <funcdef>void <function>XtRealizeWidget</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
If the widget is already realized,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
simply returns.
Otherwise it performs the following:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Binds all action names in the widget's
translation table to procedures (see <xref linkend='Action_Names_to_Procedure_Translations' />).
    </para>
  </listitem>
  <listitem>
    <para>
Makes a postorder traversal of the widget tree rooted
at the specified widget and calls each non-NULL change_managed procedure
of all composite widgets that have one or more managed children.
    </para>
  </listitem>
  <listitem>
    <para>
Constructs an
<function>XSetWindowAttributes</function>
structure filled in with information derived from the
Core
widget fields and calls the realize procedure for the widget,
which adds any widget-specific attributes and creates the X window.
    </para>
  </listitem>
  <listitem>
    <para>
If the widget is
not a subclass of
<function>compositeWidgetClass</function>,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
returns; otherwise it continues and performs the following:
    </para>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>
Descends recursively to each of the widget's
managed children and calls the realize procedures.
Primitive widgets that instantiate children are responsible for realizing
those children themselves.
        </para>
      </listitem>
      <listitem>
        <para>
Maps all of the managed children windows that have <emphasis remap='I'>mapped_when_managed</emphasis>
<function>True</function>.
If a widget is managed but <emphasis remap='I'>mapped_when_managed</emphasis> is
<function>False</function>,
the widget is allocated visual space but is not displayed.
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>
<para>
If the widget is a top-level shell widget (that is, it has no parent), and
<emphasis remap='I'>mapped_when_managed</emphasis> is
<function>True</function>,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
maps the widget window.
</para>

<para>
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
<function>XtUnmanageChildren</function>,
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
and
<function>XtDestroyWidget</function>
maintain the following invariants:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
If a composite widget is realized, then all its managed children are realized.
    </para>
  </listitem>
  <listitem>
    <para>
If a composite widget is realized, then all its managed children that have
<emphasis remap='I'>mapped_when_managed</emphasis>
<function>True</function>
are mapped.
    </para>
  </listitem>
</itemizedlist>
<para>
All Intrinsics functions and all widget routines should accept
either realized or unrealized widgets.
When calling the realize or change_managed
procedures for children of a composite
widget,
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
calls the procedures in reverse order of
appearance in the
<function>CompositePart</function>
<emphasis remap='I'>children</emphasis> list.  By default, this
ordering of the realize procedures will
result in the stacking order of any newly created subwindows being
top-to-bottom in the order of appearance on the list, and the most
recently created child will be at the bottom.
</para>

<para>
To check whether or not a widget has been realized, use
<xref linkend='XtIsRealized' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtIsRealized'>
<funcprototype>
  <funcdef>Boolean <function>XtIsRealized</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtIsRealized' xrefstyle='select: title'/>
function returns
<function>True</function>
if the widget has been realized,
that is, if the widget has a nonzero window ID.
If the specified object is not a widget, the state of the nearest
widget ancestor is returned.
</para>

<para>
Some widget procedures (for example, set_values) might wish to
operate differently
after the widget has been realized.
</para>
<sect2 id="Widget_Instance_Window_Creation_The_realize_Procedure">
<title>Widget Instance Window Creation: The realize Procedure</title>
<para>
The realize procedure pointer in a widget class is of type
<xref linkend='XtRealizeProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRealizeProc'>
<funcprototype>
  <funcdef>typedef void <function>(*XtRealizeProc)</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
  <paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
  <paramdef>XSetWindowAttributes <parameter>attributes</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>value_mask</emphasis>
    </term>
    <listitem>
      <para>
Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>attributes</emphasis>
    </term>
    <listitem>
      <para>
Specifies the window attributes to use in the
<function>XCreateWindow</function>
call.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The realize procedure must create the widget's window.
</para>

<para>
Before calling the class realize procedure, the generic
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
function fills in a mask and a corresponding
<function>XSetWindowAttributes</function>
structure.
It sets the following fields in <emphasis remap='I'>attributes</emphasis> and
corresponding bits in <emphasis remap='I'>value_mask</emphasis>
based on information in the widget
core
structure:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
The <emphasis remap='I'>background_pixmap</emphasis> (or <emphasis remap='I'>background_pixel</emphasis> if <emphasis remap='I'>background_pixmap</emphasis> is
<function>XtUnspecifiedPixmap</function>)
is filled in from the corresponding field.
    </para>
  </listitem>
  <listitem>
    <para>
The <emphasis remap='I'>border_pixmap</emphasis> (or <emphasis remap='I'>border_pixel</emphasis> if <emphasis remap='I'>border_pixmap</emphasis> is
<function>XtUnspecifiedPixmap</function>)
is filled in from the corresponding field.
    </para>
  </listitem>
  <listitem>
    <para>
The <emphasis remap='I'>colormap</emphasis> is filled in from the corresponding field.
    </para>
  </listitem>
  <listitem>
    <para>
The <emphasis remap='I'>event_mask</emphasis> is filled in based on the event handlers registered,
the event translations specified, whether the <emphasis remap='I'>expose</emphasis> field is non-NULL,
and whether <emphasis remap='I'>visible_interest</emphasis> is
<function>True</function>.
    </para>
  </listitem>
  <listitem>
    <para>
The <emphasis remap='I'>bit_gravity</emphasis> is set to
<function>NorthWestGravity</function>
if the <emphasis remap='I'>expose</emphasis> field is NULL.
    </para>
  </listitem>
</itemizedlist>
<para>
These or any other fields in attributes and the corresponding bits in
<emphasis remap='I'>value_mask</emphasis> can be set by the realize procedure.
</para>

<para>
Note that because realize is not a chained operation,
the widget class realize procedure must update the
<function>XSetWindowAttributes</function>
structure with all the appropriate fields from
non-Core
superclasses.
</para>

<para>
A widget class can inherit its realize procedure from its superclass
during class initialization.
The realize procedure defined for
<function>coreWidgetClass</function>
calls
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
with the passed <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>attributes</emphasis>
and with <emphasis remap='I'>window_class</emphasis> and <emphasis remap='I'>visual</emphasis> set to
<function>CopyFromParent</function>.
Both
<function>compositeWidgetClass</function>
and
<function>constraintWidgetClass</function>
inherit this realize procedure, and most new widget subclasses
can do the same (see <xref linkend='Inheritance_of_Superclass_Operations' />).
</para>

<para>
The most common noninherited realize procedures set <emphasis remap='I'>bit_gravity</emphasis> in the mask
and attributes to the appropriate value and then create the window.
For example, depending on its justification, Label might set <emphasis remap='I'>bit_gravity</emphasis> to
<function>WestGravity</function>,
<function>CenterGravity</function>,
or
<function>EastGravity</function>.
Consequently, shrinking it would just move the bits appropriately,
and no
exposure
event is needed for repainting.
</para>

<para>
If a composite widget's children should be realized in an order other
than that specified
(to control the stacking order, for example),
it should call
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
on its children itself in the appropriate order from within its own
realize procedure.
</para>

<para>
Widgets that have children and whose class is not a subclass of
<function>compositeWidgetClass</function>
are responsible for calling
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
on their children, usually from within the realize procedure.
</para>

<para>
Realize procedures cannot manage or unmanage their descendants.
</para>
</sect2>

<sect2 id="Window_Creation_Convenience_Routine">
<title>Window Creation Convenience Routine</title>
<para>
Rather than call the Xlib
<function>XCreateWindow</function>
function explicitly, a realize procedure should normally call the Intrinsics analog
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>,
which simplifies the creation of windows for widgets.
</para>

<funcsynopsis id='XtCreateWindow'>
<funcprototype>
  <funcdef>void <function>XtCreateWindow</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
  <paramdef>unsigned int <parameter>window_class</parameter></paramdef>
  <paramdef>Visual * <parameter>visual</parameter></paramdef>
  <paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
  <paramdef>XSetWindowAttributes * <parameter>attributes</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget that defines the additional window attributed.  Must be of class Core or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>window_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Xlib window class (for example,
<function>InputOutput</function>,
<function>InputOnly</function>,
or
<function>CopyFromParent ).</function>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>visual</emphasis>
    </term>
    <listitem>
      <para>
Specifies the visual type (usually
<function>CopyFromParent ).</function>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>value_mask</emphasis>
    </term>
    <listitem>
      <para>
Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>attributes</emphasis>
    </term>
    <listitem>
      <para>
Specifies the window attributes to use in the
<function>XCreateWindow</function>
call.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
function calls the Xlib
<function>XCreateWindow</function>
function with values from the widget structure and the passed parameters.
Then, it assigns the created window to the widget's <emphasis remap='I'>window</emphasis> field.
</para>

<para>
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
evaluates the following fields of the widget core
structure: <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>screen</emphasis>, <emphasis remap='I'>parent-&gt;core.window</emphasis>, <emphasis remap='I'>x</emphasis>,
<emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and
<emphasis remap='I'>border_width</emphasis>.
</para>
</sect2>
</sect1>

<sect1 id="Obtaining_Window_Information_from_a_Widget">
<title>Obtaining Window Information from a Widget</title>
<para>
The
Core
widget class definition contains the screen and window ids.
The <emphasis remap='I'>window</emphasis> field may be NULL for a while
(see <xref linkend='Creating_Widgets' /> and <xref linkend='Realizing_Widgets' />).
</para>

<para>
The display pointer, the parent widget, screen pointer,
and window of a widget are available to the widget writer by means of macros
and to the application writer by means of functions.
</para>

<funcsynopsis>
<funcprototype>
  <funcdef>Display * <function>XtDisplay</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XtDisplay</function>
returns the display pointer for the specified widget.
</para>

<funcsynopsis>
<funcprototype>
  <funcdef>Widget <function>XtParent</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XtParent</function>
returns the parent object for the specified widget. The returned object
will be of class Object or a subclass.
</para>

<funcsynopsis id='XtScreen'>
<funcprototype>
  <funcdef>Screen *<function>XtScreen</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtScreen' xrefstyle='select: title'/>
returns the screen pointer for the specified widget.
</para>

<funcsynopsis id='XtWindow'>
<funcprototype>
  <funcdef>Window <function>XtWindow</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtWindow' xrefstyle='select: title'/>
returns the window of the specified widget.
</para>

<para>
The display pointer, screen pointer, and window of a widget or
of the closest widget ancestor of a nonwidget object are available
by means of
<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>,
and
<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtDisplayOfObject'>
<funcprototype>
  <funcdef>Display *<function>XtDisplayOfObject</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>object</emphasis>
    </term>
    <listitem>
      <para>
Specifies the object.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
is identical in function to
<function>XtDisplay</function>
if the object is a widget; otherwise
<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
returns the display
pointer for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
Widget or a subclass thereof.
</para>

<funcsynopsis id='XtScreenOfObject'>
<funcprototype>
  <funcdef>Screen *<function>XtScreenOfObject</function></funcdef>
  <paramdef>Widget <parameter>object</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>object</emphasis>
    </term>
    <listitem>
      <para>
Specifies the object.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
is identical in function to
<xref linkend='XtScreen' xrefstyle='select: title'/>
if the object is a widget; otherwise
<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
returns the screen pointer
for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
Widget or a subclass thereof.
</para>

<funcsynopsis id='XtWindowOfObject'>
<funcprototype>
  <funcdef>Window <function>XtWindowOfObject</function></funcdef>
  <paramdef>Widget <parameter>object</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>object</emphasis>
    </term>
    <listitem>
      <para>
Specifies the object.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
is identical in function to
<xref linkend='XtWindow' xrefstyle='select: title'/>
if the object is a widget; otherwise
<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
returns the window for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
Widget or a subclass thereof.
</para>

<para>
To retrieve the instance name of an object, use
<xref linkend='XtName' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtName'>
<funcprototype>
  <funcdef>String <function>XtName</function></funcdef>
  <paramdef>Widget <parameter>object</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>object</emphasis>
    </term>
    <listitem>
      <para>
Specifies the object whose name is desired.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtName' xrefstyle='select: title'/>
returns a pointer to the instance name of the specified object.
The storage is owned by the Intrinsics and must not be modified.  The
name is not qualified by the names of any of the object's ancestors.
</para>

<para>
Several window attributes are locally cached in the widget instance.
Thus, they can be set by the resource manager and
<xref linkend='XtSetValues' xrefstyle='select: title'/>
as well as used by routines that derive structures from these values
(for example, <emphasis remap='I'>depth</emphasis> for deriving pixmaps,
<emphasis remap='I'>background_pixel</emphasis> for deriving GCs, and so on) or in the
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
call.
</para>

<para>
The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>
window attributes are available to
geometry managers.
These fields are maintained synchronously inside the Intrinsics.
When an
<function>XConfigureWindow</function>
is issued by the Intrinsics on the widget's window (on request of its parent),
these values are updated immediately rather than some time later
when the server generates a
<function>ConfigureNotify</function>
event.
(In fact, most widgets do not select
<function>SubstructureNotify</function>
events.)
This ensures that all geometry calculations are based on the internally
consistent toolkit world rather than on either
an inconsistent world updated by asynchronous
<function>ConfigureNotify</function>
events or a consistent, but slow, world in which geometry managers
ask the server
for window sizes whenever they need to lay out their managed children
(see <xref linkend='Geometry_Management' />).
</para>
<sect2 id="Unrealizing_Widgets">
<title>Unrealizing Widgets</title>
<para>
To destroy the windows associated with a widget and its
non-pop-up descendants, use
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtUnrealizeWidget'>
<funcprototype>
  <funcdef>void <function>XtUnrealizeWidget</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
If the widget is currently unrealized,
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
simply returns.  Otherwise it performs the following:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Unmanages the widget if the widget is managed.
    </para>
  </listitem>
  <listitem>
    <para>
Makes a postorder (child-to-parent) traversal of the widget tree
rooted at the specified widget and, for each widget that has
declared a callback list resource named &ldquo;unrealizeCallback&rdquo;, executes the
procedures on the
XtNunrealizeCallback
list.
    </para>
  </listitem>
  <listitem>
    <para>
Destroys the widget's window and any subwindows by calling
<function>XDestroyWindow</function>
with the specified widget's <emphasis remap='I'>window</emphasis> field.
    </para>
  </listitem>
</itemizedlist>
<para>
Any events in the queue or which arrive following a call to
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
will be dispatched as if the window(s) of the
unrealized widget(s) had never existed.
</para>
</sect2>
</sect1>

<sect1 id="Destroying_Widgets">
<title>Destroying Widgets</title>
<para>
The Intrinsics provide support
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
To destroy all the pop-up children of the widget being destroyed
and destroy all children of composite widgets.
    </para>
  </listitem>
  <listitem>
    <para>
To remove (and unmap) the widget from its parent.
    </para>
  </listitem>
  <listitem>
    <para>
To call the callback procedures that have been registered to trigger
when the widget is destroyed.
    </para>
  </listitem>
  <listitem>
    <para>
To minimize the number of things a widget has to deallocate when destroyed.
    </para>
  </listitem>
  <listitem>
    <para>
To minimize the number of
<function>XDestroyWindow</function>
calls when destroying a widget tree.
    </para>
  </listitem>
</itemizedlist>
<para>
To destroy a widget instance, use
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>.
</para>


<funcsynopsis id='XtDestroyWidget'>
<funcprototype>
  <funcdef>void <function>XtDestroyWidget</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
function provides the only method of destroying a widget,
including widgets that need to destroy themselves.
It can be called at any time,
including from an application callback routine of the widget being destroyed.
This requires a two-phase destroy process in order to avoid dangling
references to destroyed widgets.
</para>

<para>
In phase 1,
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
performs the following:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
If the <emphasis remap='I'>being_destroyed</emphasis> field of the widget is
<function>True</function>,
it returns immediately.
    </para>
  </listitem>
  <listitem>
    <para>
Recursively descends the widget tree and
sets the <emphasis remap='I'>being_destroyed</emphasis> field to
<function>True</function>
for the widget and all normal and pop-up children.
    </para>
  </listitem>
  <listitem>
    <para>
Adds the widget to a list of widgets (the destroy list) that should be
destroyed when it is safe to do so.
    </para>
  </listitem>
</itemizedlist>
<para>
Entries on the destroy list satisfy the invariant that
if w2 occurs after w1 on the destroy list, then w2 is not a descendent,
either normal or pop-up, of w1.
</para>

<para>
Phase 2 occurs when all procedures that should execute as a result of
the current event have been called, including all procedures registered with
the event and translation managers,
that is, when the current invocation of
<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
is about to return, or immediately if not in
<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
</para>

<para>
In phase 2,
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
performs the following on each entry in the destroy list in the order
specified:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
If the widget is not a pop-up child and the widget's parent is a subclass of
<function>compositeWidgetClass</function>,
and if the parent is not being destroyed,
it calls
<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
on the widget and then calls the widget's parent's delete_child procedure
(see <xref linkend='Deletion_of_Children_The_delete_child_Procedure' />).
    </para>
  </listitem>
  <listitem>
    <para>
Calls the destroy callback procedures registered on the widget
and all normal and pop-up descendants in postorder (it calls child
callbacks before parent callbacks).
    </para>
  </listitem>
</itemizedlist>
<para>
The
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
function then makes second traversal of the widget and all normal
and pop-up descendants to perform the following three items on each
widget in postorder:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
If the widget is not a pop-up child and the widget's parent is a subclass of
<function>constraintWidgetClass</function>,
it calls the
<function>ConstraintClassPart</function>
destroy procedure for the parent,
then for the parent's superclass,
until finally it calls the
<function>ConstraintClassPart</function>
destroy procedure for
<function>constraintWidgetClass</function>.
    </para>
  </listitem>
  <listitem>
    <para>
Calls the
<function>CoreClassPart</function>
destroy procedure declared in the widget class,
then the destroy procedure declared in its superclass,
until finally it calls the destroy procedure declared in the Object
class record.  Callback lists are deallocated.
    </para>
  </listitem>
  <listitem>
    <para>
If the widget class object class part contains an
<function>ObjectClassExtension</function>
record with the record_type
<emphasis role='strong'>NULLQUARK</emphasis>
and the <emphasis remap='I'>deallocate</emphasis> field is not NULL,
calls the deallocate procedure to deallocate the instance and if one
exists, the constraint record.  Otherwise, the Intrinsics will deallocate
the widget instance record and if one exists, the constraint record.
    </para>
  </listitem>
  <listitem>
    <para>
Calls
<function>XDestroyWindow</function>
if the specified widget is realized (that is, has an X window).
The server recursively destroys all normal descendant windows.
(Windows of realized pop-up Shell children, and their
descendants, are destroyed by a shell class destroy procedure.)
    </para>
  </listitem>
</itemizedlist>
<sect2 id="Adding_and_Removing_Destroy_Callbacks">
<title>Adding and Removing Destroy Callbacks</title>
<para>
When an application needs to perform additional processing during the
destruction of a widget,
it should register a destroy callback procedure for the widget.
The destroy callback procedures use the mechanism described in
<xref linkend='Callbacks' />.
The destroy callback list is identified by the resource name
XtNdestroyCallback.
</para>

<para>
For example, the following adds an application-supplied destroy callback
procedure <emphasis remap='I'>ClientDestroy</emphasis> with client data to a widget by calling
<xref linkend='XtAddCallback' xrefstyle='select: title'/>.
</para>

<programlisting>
XtAddCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
</programlisting>

<para>
Similarly, the following removes the application-supplied destroy callback
procedure <emphasis remap='I'>ClientDestroy</emphasis> by calling
<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>.
</para>

<programlisting>
XtRemoveCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
</programlisting>
<para>
The <emphasis remap='I'>ClientDestroy</emphasis> argument is of type
<xref linkend='XtCallbackProc' xrefstyle='select: title'/>;
see <xref linkend='Using_Callback_Procedure_and_Callback_List_Definitions' />.
</para>
</sect2>

<sect2 id="Dynamic_Data_Deallocation_The_destroy_Procedure">
<title>Dynamic Data Deallocation: The destroy Procedure</title>
<para>
The destroy procedure pointers in the
<function>ObjectClassPart</function>,
<function>RectObjClassPart</function>,
and
<function>CoreClassPart</function>
structures are of type
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtWidgetProc'>
<funcprototype>
  <funcdef>typedef void <function>XtWidgetProc</function></funcdef>
  <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget being destroyed.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The destroy procedures are called in subclass-to-superclass order.
Therefore, a widget's destroy procedure should deallocate only storage
that is specific to the subclass and should ignore the storage
allocated by any of its superclasses.
The destroy procedure should deallocate only resources that have been
explicitly created by the subclass.
Any resource that was obtained from the resource database
or passed in an argument list was not created by the widget
and therefore should not be destroyed by it.
If a widget does not need to deallocate any storage,
the destroy procedure entry in its class record can be NULL.
</para>

<para>
Deallocating storage includes, but is not limited to,
the following steps:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Calling
<xref linkend='XtFree' xrefstyle='select: title'/>
on dynamic storage allocated with
<xref linkend='XtMalloc' xrefstyle='select: title'/>,
<xref linkend='XtCalloc' xrefstyle='select: title'/>,
and so on.
    </para>
  </listitem>
  <listitem>
    <para>
Calling
<function>XFreePixmap</function>
on pixmaps created with direct X calls.
    </para>
  </listitem>
  <listitem>
    <para>
Calling
<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
on GCs allocated with
<xref linkend='XtGetGC' xrefstyle='select: title'/>.
    </para>
  </listitem>
  <listitem>
    <para>
Calling
<function>XFreeGC</function>
on GCs allocated with direct X calls.
    </para>
  </listitem>
  <listitem>
    <para>
Calling
<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
on event handlers added to other widgets.
    </para>
  </listitem>
  <listitem>
    <para>
Calling
<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
on timers created with
<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
    </para>
  </listitem>
  <listitem>
    <para>
Calling
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
for each child if the widget has children
and is not a subclass of
<function>compositeWidgetClass</function>.
    </para>
  </listitem>
</itemizedlist>
<para>
During destroy phase 2 for each widget, the Intrinsics remove the widget
from the modal cascade, unregister all event handlers, remove all key,
keyboard, button, and pointer grabs and remove all callback procedures
registered on the widget.  Any outstanding selection transfers will time out.
</para>
</sect2>

<sect2 id="Dynamic_Constraint_Data_Deallocation_The_ConstraintClassPart_destroy_Procedure">
<title>Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure</title>
<para>
The constraint destroy procedure identified in the
<function>ConstraintClassPart</function>
<function>constraintWidgetClass</function>.
This constraint destroy procedure pointer is of type
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
The constraint destroy procedures are called in subclass-to-superclass order,
starting at the class of the widget's parent and ending at
<function>constraintWidgetClass</function>.
Therefore, a parent's constraint destroy procedure should deallocate only
storage that is specific to the constraint subclass
and not storage allocated by any of its superclasses.
</para>

<para>
If a parent does not need to deallocate any constraint storage,
the constraint destroy procedure entry
in its class record can be NULL.
</para>
</sect2>

<sect2 id="Widget_Instance_Deallocation_The_deallocate_Procedure">
<title>Widget Instance Deallocation: The deallocate Procedure</title>
<para>
The deallocate procedure pointer in the
<function>ObjectClassExtension</function>
record is of type
<function>XtDeallocateProc</function>.
</para>

<funcsynopsis>
<funcprototype>
  <funcdef>typedef void <function>(*XtDeallocateProc)</function></funcdef>
  <paramdef>Widget <parameter>widget</parameter></paramdef>
  <paramdef>XtPointer <parameter>more_bytes</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget being destroyed.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>more_bytes</emphasis>
    </term>
    <listitem>
      <para>
Specifies the auxiliary memory received from the corresponding allocator
along with the widget, or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
When a widget is destroyed, if an
<function>ObjectClassExtension</function>
record exists in the object class part <emphasis remap='I'>extension</emphasis> field
with <emphasis remap='I'>record_type</emphasis>
<emphasis role='strong'>NULLQUARK</emphasis>
and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, the
<function>XtDeallocateProc</function>
will be called.
If no ObjectClassPart extension record is declared with <emphasis remap='I'>record_type</emphasis>
equal to
<emphasis role='strong'>NULLQUARK</emphasis>,
then
<function>XtInheritAllocate</function>
and
<function>XtInheritDeallocate</function>
are assumed.
The responsibilities of the deallocate procedure are to deallocate the
memory specified by <emphasis remap='I'>more_bytes</emphasis> if it is not NULL,
to deallocate the constraints record as specified by the
widget's <emphasis remap='I'>core.constraints</emphasis> field if it is
not NULL, and to deallocate the widget instance itself.
</para>

<para>
If no
<function>XtDeallocateProc</function>
is found, it is assumed that the Intrinsics
originally allocated the memory and is responsible for freeing it.
</para>
</sect2>
</sect1>

<sect1 id="Exiting_from_an_Application">
<title>Exiting from an Application</title>
<para>
All X Toolkit applications should terminate
by calling
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
and then exiting
using the
standard method for their operating system (typically, by calling
<function>exit</function>
for POSIX-based systems).
The quickest way to make the windows disappear while exiting is to call
<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
on each top-level shell widget.
The Intrinsics have no resources beyond those in the program image,
and the X server will free its resources when its connection
to the application is broken.
</para>

<para>
Depending upon the widget set in use, it may be necessary to explicitly
destroy individual widgets or widget trees with
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
before calling
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
in order to ensure that any
required widget cleanup is properly executed.  The application developer
must refer to the widget documentation to learn if a widget needs to
perform cleanup beyond that performed automatically by the
operating system.  If the client is a session participant
(see <xref linkend='Session_Participation' />), then the client may wish to resign from the session
before exiting.  See <xref linkend='Resigning_from_a_Session' /> for details.
</para>
</sect1>
</chapter>