\&
.sp 1
.ce 3
\s+1\fBChapter 2\fP\s-1

\s+1\fBWidget Instantiation\fP\s-1
.sp 2
.nr H1 2
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.LP
.XS
Chapter 2 \- Widget Instantiation
.XE
A collection of widget instances constitutes a widget tree.
The shell widget returned by
.PN XtAppCreateShell
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 a widget tree.
With the exception of pop-up children (see Chapter 5),
this widget tree instance defines the associated X Window tree.
.LP
Widgets can be either composite or primitive.
Both kinds of widgets can contain children,
but the \*(xI provide a set of management mechanisms for constructing
and interfacing between composite widgets, their children, and
other clients.
.LP
Composite widgets, subclasses of 
.PN Composite ,
are containers for an arbitrary 
but 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 class themselves and do not expect external 
clients to do so.
Primitive widgets also do not have general geometry management methods.
.LP
In addition,
the \*(xI recursively perform many operations 
(for example, realization and destruction)
on composite widgets and all of their children.
Primitive widgets that have children must be prepared 
to perform the recursive operations themselves on behalf of their children. 
.LP
A widget tree is manipulated by several \*(xI functions.
For example,
.PN XtRealizeWidget
traverses the tree downward and recursively realizes all 
pop-up widgets and children of composite widgets.
.PN XtDestroyWidget
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.
.PN XtMakeGeometryRequest
traverses the tree up one level and calls the geometry manager 
that is responsible for a widget child's geometry.
.LP
To facilitate up-traversal of the widget tree,
each widget has a pointer to its parent widget.
The
.PN Shell 
widget that
.PN XtAppCreateShell 
returns, however, has a parent pointer of NULL.
.LP
To facilitate down-traversal of the widget tree,
each composite widget has a pointer to an array of children 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 widgets.
.NH 2
Initializing the \*(tk
.XS
\fB\*(SN Initializing the \*(tk\fP
.XE
.LP
Before an application can call any of the \*(xI functions,
it must initialize the \*(tk by using:
.IP \(bu 5
.PN XtToolkitInitialize ,
which initializes the \*(tk internals
.IP \(bu 5
.PN XtCreateApplicationContext ,
which initializes the per application state
.IP \(bu 5
.PN XtDisplayInitialize
or
.PN XtOpenDisplay ,
which initializes the per display state
.IP \(bu 5
.PN XtAppCreateShell ,
which creates the initial widget
.LP
Multiple instances of \*(tk applications may be implemented 
by a single program 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 may need multiple display connections 
or need to have widgets on multiple screens.
.IN "application context" "" "@DEF@"
To accommodate both requirements, 
the \*(xI 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 X
.PN Display
pointers for that application.
The application context type
.PN XtAppContext
.IN "XtAppContext" "" "@DEF@"
is opaque to clients.
.sp
.LP
To initialize the \*(tk internals, use
.PN XtToolkitInitialize .
.IN "XtToolkitInitialize" "" "@DEF@"
.FD 0
void XtToolkitInitialize()
.FN
.LP
The semantics of calling
.PN XtToolkitInitialize
more than once are undefined.
.sp
.LP
To create an application context, use
.PN XtCreateApplicationContext .
.IN "XtCreateApplicationContext" "" "@DEF@"
.FD 0
XtAppContext XtCreateApplicationContext()
.FN
The
.PN XtCreateApplicationContext
function returns an application context,
which is an opaque type.
Every application must have at least one application context.
.sp
.LP
To destroy an application context and close any displays in it, use
.PN XtDestroyApplicationContext .
.IN "XtDestroyApplicationContext" "" "@DEF@"
.FD 0
void XtDestroyApplicationContext(\fIapp_context\fP)
.br
      XtAppContext \fIapp_context\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.LP
The
.PN XtDestroyApplicationContext
function destroys the specified application context as soon as it is safe 
to do so.
If called from with an event dispatch (for example, a callback procedure),
.PN XtDestroyApplicationContext
does not destroy the application context until the dispatch is complete.
.sp
.LP
To get the application context for a given widget, use
.PN XtWidgetToApplicationContext .
.IN "XtWidgetToApplicationContext" "" "@DEF@"
.FD 0
XtAppContext XtWidgetToApplicationContext(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.ds Wi for which you want the application context 
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.LP
The
.PN XtWidgetToApplicationContext
function returns the application context for the specified widget.
.sp
.LP
To initialize a display and add it to an application context, use
.PN XtDisplayInitialize .
.IN "XtDisplayInitialize" "" "@DEF@"
.FD 0
void XtDisplayInitialize(\fIapp_context\fP, \fIdisplay\fP, \
\fIapplication_name\fP, \fIapplication_class\fP,
.br
                       \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
.br
      XtAppContext \fIapp_context\fP;
.br
      Display *\fIdisplay\fP;
.br
      String \fIapplication_name\fP;
.br
      String \fIapplication_class\fP;
.br
      XrmOptionDescRec *\fIoptions\fP;
.br
      Cardinal \fInum_options\fP;
.br
      Cardinal *\fIargc\fP;
.br
      String *\fIargv\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
Note that a display can be in at most one application context.
.IP \fIapplication_name\fP 1i
Specifies the name of the application instance.
.ds Ac , which is usually the generic name for all instances of this application
.IP \fIapplication_class\fP 1i
Specifies the class name of this application\*(Ac.
.IP \fIoptions\fP 1i
Specifies how to parse the command line for any application-specific resources.
The options argument is passed as a parameter to
.PN XrmParseCommand .
For further information,
see \fI\*(xL\fP.
.IP \fInum_options\fP 1i
Specifies the number of entries in the options list.
.IP \fIargc\fP 1i
Specifies a pointer to the number of command line parameters.
.IP \fIargv\fP 1i
Specifies the command line parameters.
.LP
The
.PN XtDisplayInitialize
function builds the resource database, calls the Xlib
.PN XrmParseCommand
function to parse the command line, 
and performs other per display initialization.
After 
.PN XrmParseCommand 
has been called,
argc and argv contain only those parameters that
were not in the standard option table or in the table specified by the
options argument.
If the modified argc is not zero,
most applications simply print out the modified argv along with a message
listing the allowable options.
On UNIX-based systems,
the application name is usually the final component of argv[0].
If the synchronize resource is
.PN True
for the specified application,
.PN XtDisplayInitialize
calls the Xlib
.PN XSynchronize
function to put Xlib into synchronous mode for this display connection.
If the reverseVideo resource is
.PN True ,
the \*(xI exchange
.PN XtDefaultForeground
and
.PN XtDefaultBackground
for widgets created on this display.
(See Section 9.6.1).
.sp
.LP
To open a display, initialize it, and add it to an application context, use 
.PN XtOpenDisplay .
.IN "XtOpenDisplay" "" "@DEF@"
.FD 0
Display *XtOpenDisplay(\fIapp_context\fP, \fIdisplay_string\fP, \
\fIapplication_name\fP, \fIapplication_class\fP, 
.br
                       \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
.br
       XtAppContext \fIapp_context\fP;
.br
       String \fIdisplay_string\fP;
.br
       String \fIapplication_name\fP;
.br
       String \fIapplication_class\fP;
.br
       XrmOptionDescRec *\fIoptions\fP;
.br
       Cardinal \fInum_options\fP;
.br
       Cardinal *\fIargc\fP;
.br
       String *\fIargv\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.IP \fIdisplay_string\fP 1i
Specifies the display string.
Note that a display can be in at most one application context.
.IP \fIapplication_name\fP 1i
Specifies the name of the application instance.
.ds Ac , which is usually the generic name for all instances of this application
.IP \fIapplication_class\fP 1i
Specifies the class name of this application\*(Ac.
.IP \fIoptions\fP 1i
Specifies how to parse the command line for any application-specific resources.
The options argument is passed as a parameter to
.PN XrmParseCommand .
For further information,
see \fI\*(xL\fP.
.IP \fInum_options\fP 1i
Specifies the number of entries in the options list.
.IP \fIargc\fP 1i
Specifies a pointer to the number of command line parameters.
.IP \fIargv\fP 1i
Specifies the command line parameters.
.LP
The
.PN XtOpenDisplay
function calls
.PN XOpenDisplay 
the specified display name.
If display_string is NULL,
.PN XtOpenDisplay
uses the current value of the \-display option specified in argv 
and if no display is specified in argv,
uses the user's default display (on UNIX-based systems, 
this is the value of the DISPLAY environment variable).
.LP
If this succeeds, it then calls
.PN XtDisplayInitialize
and pass it the opened display and
the value of the \-name option specified in argv as the application name.
If no name option is specified,
it uses the application name passed to
.PN XtOpenDisplay .
If the application name is NULL,
it uses the last component of argv[0].
.PN XtOpenDisplay
returns the newly opened display or NULL if it failed.
.LP
.PN XtOpenDisplay
is provided as a convenience to the application programmer.
.sp
.LP
To close a display and remove it from an application context, use
.PN XtCloseDisplay .
.IN "XtCloseDisplay" "" "@DEF@"
.FD 0
void XtCloseDisplay(\fIdisplay\fP)
.br
      Display *\fIdisplay\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.LP
The
.PN XtCloseDisplay
function closes the specified display as soon as it is safe to do so.
If called from within an event dispatch (for example, a callback procedure),
.PN XtCloseDisplay
does not close the display until the dispatch is complete.
Note that applications need only call
.PN XtCloseDisplay
if they are to continue executing after closing the display; 
otherwise, they should call
.PN XtDestroyApplicationContext
or just exit.
.NH 2
Loading the Resource Database
.XS
\fB\*(SN Loading the Resource Database\fP
.XE
.LP
The
.PN XtDisplayInitialize
function loads the application's resource database for this 
display/host/application combination from the following sources (in order):
.IP \(bu 5
Application-specific class resource file on the local host
.IP \(bu 5
Application-specific user resource file on the local host
.IP \(bu 5
Resource property on the server or user preference resource file on the local
host
.IP \(bu 5
Per-host user environment resource file on the local host
.IP \(bu 5
Application command line (argv)
.LP
Each resource database is kept on a per-display basis.
.LP
The application-specific class resource file name 
is constructed from the class name of the application. 
It points to a site-specific resource file that usually is installed 
by the site manager when the application is installed.
On UNIX-based systems,
this file usually is
.PN /usr/lib/X11/app-defaults/ \fIclass\fP,
where \fIclass\fP is the application class name.
This file is expected to be provided by the developer of the application
and may be required for the application to function properly.
.LP
The application-specific user resource file name is constructed from the
class name of the application and points to a user-specific resource
file.
This file is owned by the application and typically stores user customizations.
On UNIX-based systems,
this file name is constructed from the user's XAPPLRESDIR variable 
by appending \fIclass\fP to it,
where \fIclass\fP is the application class name.
If XAPPLRESDIR is not defined, 
it defaults to the user's home directory.
If the resulting resource file exists, 
it is merged into the resource database.
This file may be provided with the application or constructed by the user.
.LP
The server resource file is the contents of the X server's 
\s-1RESOURCE_MANAGER\s+1 property that was returned by
.PN XOpenDisplay .
If no such property exists for the display,
the contents of the resource
file in the user's home directory is used instead.
On UNIX-based systems,
the usual name for the user preference resource file is
.PN \&.Xdefaults .
If the resulting resource file exists, 
it is merged into the resource database.
The server resource file is constructed entirely by the user 
and contains both display-independent and display-specific user preferences.
.LP
If one exists, 
a user's environment resource file is then loaded and merged
into the resource database.
This file name is user and host specific.
On UNIX-based systems, 
the user's environment resource file name is constructed from
the value of the user's \s-1XENVIRONMENT\s+1 variable for the full path 
of the file.
If this environment variable does not exist,
.PN XtDisplayInitialize
searches the user's home directory for the
.PN \&.Xdefaults-\fIhost\fP
file, 
where \fIhost\fP is the name of the machine on which the application is running.
If the resulting resource file exists, it is merged into the resource database.
The environment resource file is expected to contain process-specific resource
specifications that are to supplement those user-preference specifications 
in the server resource file.
.sp
.LP
To obtain the resource database for a particular display, use
.PN XtDatabase .
.IN "XtDatabase" "" "@DEF@"
.FD 0
XrmDatabase XtDatabase(\fIdisplay\fP)
.br
      Display *\fIdisplay\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.LP
The
.PN XtDatabase
function returns the fully merged resource database that was built by
.PN XtDisplayInitialize
associated with the display that was passed in.
If this display has not been initialized by
.PN XtDisplayInitialize ,
the results are not defined.
.NH 2
Parsing the Command Line
.XS
\fB\*(SN Parsing the Command Line\fP
.XE
.LP
The
.PN XtOpenDisplay
function first parses the command line for the following options:
.IP \-display 1i
Specifies the display name for
.PN XOpenDisplay ,
which overrides the display name passed to
.PN XtDisplayInitialize .
.IP \-name 1i
Sets the resource name prefix, 
which overrides the application name passed to
.PN XtDisplayInitialize .
.LP
.PN XtDisplayInitialize
has a table of standard command line options that are passed to
.PN XrmParseCommand
for adding resources to the resource database, 
and it takes as a parameter additional
application-specific resource abbreviations.
.IN "XrmOptionDescRec" "" "@DEF@"
The format of this table is:
.LP
.Ds 0
.TA .5i 2.75i
.ta .5i 2.75i
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 */
	XrmoptionSkipArg,	/* Ignore this option and the next argument 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;	/* Which style of option it is */
	caddr_t value;	/* Value to provide if XrmoptionNoArg */
} XrmOptionDescRec, *XrmOptionDescList;

.De
.LP
The standard table contains the following entries:
.TS
l l l l .
_
.sp 6p
.TB
Option String	Resource Name	Argument Kind	Resource Value
.sp 6p
_
.sp 6p
\-background	background	SepArg	next argument
\-bd	borderColor	SepArg	next argument
\-bg	background	SepArg	next argument
\-borderwidth	borderWidth	SepArg	next argument
\-bordercolor	borderColor	SepArg	next argument
\-bw	borderWidth	SepArg	next argument
\-display	display	SepArg	next argument
\-fg	foreground	SepArg	next argument
\-fn	font	SepArg	next argument
\-font	font	SepArg	next argument
\-foreground	foreground	SepArg	next argument
\-geometry	geometry	SepArg	next argument
\-iconic	iconic	NoArg	true
\-name	name	SepArg	next argument
\-reverse	reverseVideo	NoArg	on
\-rv	reverseVideo	NoArg	on
+rv	reverseVideo	NoArg	off
\-selectionTimeout	selectionTimeout	SepArg	next argument
\-synchronous	synchronize	NoArg	on
+synchronous	synchronize	NoArg	off
\-title	title	SepArg	next argument
\-xrm	next argument	ResArg	next argument
.sp 6p
_
.TE
.LP
Note that any unique abbreviation for an option name in the standard table
or in the application table is accepted.
.NE
.LP
If reverseVideo is set,
the values of
.PN XtDefaultForeground
and
.PN XtDefaultBackground
are exchanged.
If synchronize is set,
the \*(xI put Xlib into synchronous mode for all connections.
.LP
The \-xrm option provides a method of setting any resource in an application.
The next argument should be a quoted string identical in format to a line in
the user resources file.
For example,
to give a red background to all command buttons in an application named
.PN xmh ,
you can start it up as:
.LP
.Ds
xmh \-xrm 'xmh*Command.background: red'
.DE
.LP
When it parses the command line,
.PN XtDisplayInitialize
merges the application option table with the standard option table
before calling the Xlib
.PN XrmParseCommand
function.
An entry in the application table with the same name as an entry
in the standard table overrides the standard table entry.
If an option name is a prefix of another option name,
both names are kept in the merged table.
.NH 2
Creating Widgets
.XS
\fB\*(SN Creating Widgets\fP
.XE
.LP
The creation of widget instances is a three-phase process:
.IP 1. 5
The widgets are allocated and initialized with resources
and are optionally added to the managed subset of their parent.
.IP 2. 5
All composite widgets are notified of their managed children
in a bottom-up traversal of the widget tree.
.IP 3. 5
The widgets create X windows that then get mapped.
.LP
.EQ
delim $$
.EN
To start the first phase, 
the application calls
.PN XtCreateWidget
for all its widgets and adds some (usually, most or all) of its widgets
to their respective parent's managed set by calling
.PN XtManageChild .
To avoid an $O( n sup 2 )$ 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.
.EQ
delim off
.EN
.LP
After all widgets have been created,
the application calls
.PN XtRealizeWidget
on the top-level widget to start the second and third phases.
.PN XtRealizeWidget
first recursively traverses the widget tree in a post-order (bottom-up)
traversal and then notifies each composite widget with one
or more managed children by means of its change_managed procedure.
.LP
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.
.LP
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.
.LP
Finally,
.PN XtRealizeWidget
starts the third phase by making a pre-order (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.
.NH 3
Creating and Merging Argument Lists
.XS
\fB\*(SN Creating and Merging Argument Lists\fP
.XE
.LP
Many \*(xI functions need to be passed pairs of resource names and
values.
These are passed as an
.PN ArgList ,
which contains:
.IN "ArgList" "" "@DEF@"
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef \fIsomething\fP XtArgVal;

typedef struct {
	String \fIname\fP;
	XtArgVal \fIvalue\fP;
} Arg, *ArgList;
.De
.LP
Where \fIsomething\fP is a type large enough to contain caddr_t, char *,
long, int *, or a pointer to a function.
.LP
If the size of the resource is less than or equal to the size of an
.PN XtArgVal ,
the resource value is stored directly in value;
otherwise, a pointer to it is stored into value.
.LP
To set values in an
.PN ArgList ,
use
.PN XtSetArg .
.IN "XtSetArg" "" "@DEF@"
.FD 0
XtSetArg(\fIarg\fP, \fIname\fP, \fIvalue\fP)
.br
      Arg \fIarg\fP;
.br
      String \fIname\fP;
.br
      XtArgVal \fIvalue\fP;
.FN
.IP \fIarg\fP 1i
Specifies the name-value pair to set.
.IP \fIname\fP 1i
Specifies the name of the resource.
.IP \fIvalue\fP 1i
Specifies the value of the resource if it will fit in an
.PN XtArgVal 
or the address.
.LP
The
.PN XtSetArg
function is usually used in a highly stylized manner to
minimize the probability of making a mistake; for example:
.LP
.Ds
.TA .5i 3i
.ta .5i 3i
Arg args[20];
int n;

n = 0;
XtSetArg(args[n], XtNheight, 100);	n++;
XtSetArg(args[n], XtNwidth, 200);	n++;
XtSetValues(widget, args, n);
.De
.LP
Alternatively, an application can statically declare the argument list
and use
.PN XtNumber :
.LP
.Ds
.TA .5i 3i
.ta .5i 3i
static Args args[] = {
	{XtNheight, (XtArgVal) 100},
	{XtNwidth, (XtArgVal) 200},
};
XtSetValues(Widget, args, XtNumber(args));
.De
.LP
Note that you should not use auto-increment or auto-decrement
within the first argument to
.PN XtSetArg .
.PN XtSetArg
can be implemented as a macro that dereferences the first argument twice.
.sp
.LP
To merge two
.PN ArgList
structures, use
.PN XtMergeArgLists .
.IN "XtMergeArgLists" "" "@DEF@"
.FD 0
ArgList XtMergeArgLists(\fIargs1\fP, \fInum_args1\fP, \fIargs2\fP, \
\fInum_args2\fP)
.br
     ArgList \fIargs1\fP;
.br
     Cardinal \fInum_args1\fP;
.br
     ArgList \fIargs2\fP;
.br
     Cardinal \fInum_args2\fP;
.FN
.IP \fIargs1\fP 1i
Specifies the first
.PN ArgList .
.IP \fInum_args1\fP 1i
Specifies the number of arguments in the first argument list.
.IP \fIargs2\fP 1i
Specifies the second 
.PN ArgList .
.IP \fInum_args2\fP 1i
Specifies the number of arguments in the second argument list.
.LP
The
.PN XtMergeArgLists
function allocates enough storage to hold the combined
.PN ArgList
structures and copies them into it.
Note that it does not check for duplicate entries.
When it is no longer needed,
free the returned storage by using
.PN XtFree .
.NH 3
Creating a Widget Instance
.XS
\fB\*(SN Creating a Widget Instance\fP
.XE
.LP
To create an instance of a widget, use
.PN XtCreateWidget .
.IN "XtCreateWidget" "" "@DEF@"
.FD 0
Widget XtCreateWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
\fIargs\fP, \fInum_args\fP)
.br
      String \fIname\fP;
.br
      WidgetClass \fIwidget_class\fP;
.br
      Widget \fIparent\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIname\fP 1i
Specifies the resource 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 same parent.
.ds Wc \ pointer for the created widget
.IP \fIwidget_class\fP 1i
Specifies the widget class\*(Wc.
.IP \fIparent\fP 1i
Specifies the parent widget.
.ds Al to override the resource defaults
.IP \fIargs\fP 1i
Specifies the argument list \*(Al.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtCreateWidget
function performs much of the boilerplate operations of widget creation:
.IP \(bu 5
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.
.IP \(bu 5
Allocates memory for the widget instance.
.IP \(bu 5
If the parent is a subclass of
.PN constraintWidgetClass ,
it allocates memory for the parent's constraints
and stores the address of this memory into the constraints field.
.IP \(bu 5
Initializes the core nonresource data fields
(for example, parent and visible).
.IP \(bu 5
Initializes the resource fields (for example, background_pixel)
by using the resource lists specified for this class and all superclasses.
.IP \(bu 5
If the parent is a subclass of
.PN constraintWidgetClass ,
it initializes the resource fields of the constraints record
by using the constraint resource list specified for the parent's class
and all superclasses up to
.PN constraintWidgetClass .
.IP \(bu 5
Calls the initialize procedures for the widget by starting at the 
.PN Core
initialize procedure on down to the widget's initialize procedure.
.IP \(bu 5
If the parent is a subclass of
.PN compositeWidgetClass ,
it puts the widget into its parent's children list by calling its parent's
insert_child procedure.
For further information,
see Section 3.5.
.IP \(bu 5
If the parent is a subclass of
.PN constraintWidgetClass ,
it calls the constraint initialize procedures,
starting at
.PN constraintWidgetClass
on down to the parent's constraint initialize procedure.
.LP
Note that you can determine the number of arguments in an argument list 
by using the
.PN  XtNumber
macro.
For further information, see Section 11.1.
(See also
.PN XtCreateManagedWidget .)
.NH 3
Creating an Application Shell Instance
.XS
\fB\*(SN Creating an Application Shell Instance\fP
.XE
.LP
An application can have multiple top-level widgets,
which can potentially be on many different screens.
An application uses 
.PN XtAppCreateShell
if it needs to have several independent windows.
The
.PN XtAppCreateShell
function creates a top-level widget that is the root of a widget tree.
.LP
.IN "XtAppCreateShell" "" "@DEF@"
.FD 0
Widget XtAppCreateShell(\fIapplication_name\fP, \
\fIapplication_class\fP, \fIwidget_class\fP, \fIdisplay\fP,
.br
                        \fIargs\fP, \fInum_args\fP)
.br
      String \fIapplication_name\fP;
.br
      String \fIapplication_class\fP;
.br
      WidgetClass \fIwidget_class\fP;
.br
      Display *\fIdisplay\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIapplication_name\fP 1i
Specifies the name of the application instance.
If application_name is NULL,
the application name passed to
.PN XtDisplayInitialize
is used.
.ds Ac
.IP \fIapplication_class\fP 1i
Specifies the class name of this application\*(Ac.
.ds Wc \ that the application top-level widget should be (normally, \
applicationShellWidgetClass) 
.IP \fIwidget_class\fP 1i
Specifies the widget class\*(Wc.
.ds Di \ from which to get the resources
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.IP \fIargs\fP 1i
Specifies the argument list in which to set in the \s-1WM_COMMAND\s+1 property.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
The
.PN XtAppCreateShell
function saves the specified application name and application class 
for qualifying all widget resource specifiers.
The application name and application class are used as the left-most components
in all widget resource names for this application.
.PN XtAppCreateShell
should be used to create a new logical application within a program
or to create a shell on another display.
In the first case, 
it allows the specification of a new root in the resource hierarchy.
In the second case,
it uses the resource database associated with the other display.
.LP
Note that the widget returned by
.PN XtAppCreateShell
has the \s-1WM_COMMAND\s+1
property set for session managers (see Chapter 4).
.LP
To create multiple top-level shells within a single (logical)
application, 
you can use one of two methods:
.IP \(bu 5
Designate one shell as the real top-level shell and
create the others as pop-up children of it by using 
.PN XtCreatePopupShell .
.IP \(bu 5
Have all shells as pop-up children of an unrealized top-level shell. 
.LP
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:
.LP
.Ds
.TA 2i
.ta 2i
xmail.geometry:...	(the main window)
xmail.read.geometry:...	(the read window)
xmail.compose.geometry:...	(the compose window)
.De
.LP
The second method, 
which is best if there is no main window,
leads to resource specifications like the following:
.LP
.Ds
.TA 2i
.ta 2i
xmail.headers.geometry:...	(the headers window)
xmail.read.geometry:...	(the read window)
xmail.compose.geometry:...	(the compose window)
.De
.NH 3
Widget Instance Initialization: the initialize Procedure
.XS
\*(SN Widget Instance Initialization: the initialize Procedure
.XE
.IN "Initialization"
.IN "Chaining"
.IN "Superclass Chaining"
.IN "Inheritance"
.LP
The initialize procedure pointer in a widget class is of type
.PN XtInitProc :
.IN "XtInitProc" "" "@DEF@"
.IN "initialize procedure" "" "@DEF@"
.FD 0
typedef void (*XtInitProc)(Widget, Widget);
.br
      Widget \fIrequest\fP; 
.br
      Widget \fInew\fP;
.FN
.IP \fIrequest\fP 1i
Specifies the widget with resource values as requested by the
argument list, the resource database, and the widget defaults.
.IP \fInew\fP 1i
Specifies a widget with the new values, both resource and nonresource,
that are actually allowed.
.LP
An initialization procedure performs the following:
.IP \(bu 5
Allocates space for and copies any resources that are referenced by address.
For example,
if a widget has a field that is a 
.PN String
it cannot depend on the characters at that address remaining constant 
but must dynamically allocate space for the string and copy it to the new space.
(Note that you should not allocate space for or copy callback lists.)
.IP \(bu 5
Computes values for unspecified resource fields.
For example, if width and height are zero,
the widget should compute an appropriate width and height 
based on other resources.
This is the only time that a widget should ever directly assign its own
width and height.
.IP \(bu 5
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.
.LP
An initialization procedure also can check certain fields for
internal consistency.
For example, it makes no sense to specify a color map for a depth
that does not support that color map.
.LP
Initialization procedures are called in superclass-to-subclass order.
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.
.LP
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 initialize field in the class record.
.LP
Sometimes a subclass may want to overwrite values filled in by its
superclass.
In particular, size calculations of a superclass are often
incorrect for a subclass and in this case,
the subclass must modify or recalculate fields declared
and computed by its superclass.
.LP
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.
.LP
The request and new arguments provide the necessary information for
how a subclass knows the difference between a specified size
and a size computed by a superclass.
The request widget is the widget as originally requested.
The new 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.
.LP
In the above example,
the subclass with the visual surround can see
if the width and height in the request widget are zero.
If so,
it adds its surround size to the width and height fields in the new widget.
If not, it must make do with the size originally specified.
.LP
The new widget will become the actual widget instance record.
Therefore,
the initialization procedure should do all its work on the new widget
(the request widget should never be modified),
and if it needs to call any routines that operate on a widget,
it should specify new as the widget instance.
.NH 3
Constraint Widget Instance Initialization: the constraint_initialize Procedure
.XS
\*(SN Constraint Widget Instance Initialization : the constraint_initialize Procedure
.XE
.IN "Initialization"
.IN "XtInitProc"
.IN "initialize procedure"
.IN "Chaining"
.IN "Superclass Chaining"
.IN "Inheritance"
.LP
The constraint_initialize procedure pointer is of type
.PN XtInitProc .
The values passed to the parent constraint initialization procedure
are the same as those passed to the child's class widget initialization
procedure.
.LP
The constraint initialization procedure should compute any constraint fields
derived from constraint resources.
It can make further changes to the widget to make the widget
conform to the specified constraints, for example, 
changing the widget's size or position.
.LP
If a constraint class does not need a constraint initialization procedure,
it can specify NULL for the initialize field of the
.PN ConstraintClassPart
in the class record.
.NH 3
Nonwidget Data Initialization: the initialize_hook Procedure
.XS
\*(SN Nonwidget Data Initialization: the initialize_hook Procedure
.XE
.IN "Initialization"
.LP
The initialize_hook procedure pointer is of type
.PN XtArgsProc :
.IN "initialize_hook procedure" "" "@DEF@"
.IN "XtArgsProc" "" "@DEF@"
.FD 0
typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *);
.br
     Widget \fIw\fP;
.br
     ArgList \fIargs\fP;
.br
     Cardinal *\fInum_args\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.IP \fIargs\fP 1i
Specifies the argument list to override the resource defaults.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
If this procedure is not NULL,
it is called immediately after the corresponding initialize
procedure or in its place if the initialize procedure is NULL.
.LP
The initialize_hook procedure allows a widget instance to initialize
nonwidget data using information from the specified argument list.
For example,
the Text widget has subparts that are not widgets,
yet these subparts have resources that can be specified by means of the
resource file or an argument list.
See also Section 9.4.
.NH 2
Realizing Widgets
.XS
\fB\*(SN Realizing Widgets\fP
.XE
.LP
To realize a widget instance, use
.PN XtRealizeWidget .
.IN "XtRealizeWidget" "" "@DEF@"
.FD 0
void XtRealizeWidget(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
If the widget is already realized,
.PN XtRealizeWidget
simply returns. 
Otherwise, it performs the following:
.IP \(bu 5
Binds all action names in the widget's
translation table to procedures (see Section 10.1.2).
.IP \(bu 5
Makes a post-order traversal of the widget tree rooted
at the specified widget and calls the change_managed procedure
of each composite widget that has one or more managed children.
.IP \(bu 5
Constructs an
.PN XSetWindowAttributes
structure filled in with information derived from the 
.PN Core 
widget fields and calls the realize procedure for the widget,
which adds any widget-specific attributes and creates the X window.
.IP \(bu 5
If the widget is
not a subclass of 
.PN compositeWidgetClass ,
.PN XtRealizeWidget
returns; otherwise, it continues and performs the following:
.RS
.IP \- 5
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.
.IP \- 5
Maps all of the managed children windows that have mapped_when_managed 
.PN True .
(If a widget is managed but mapped_when_managed is 
.PN False , 
the widget is allocated visual space but is not displayed.
Some people seem to like this to indicate certain states.)
.RE
.LP
If the widget is a top-level shell widget (that is, it has no parent), and
mapped_when_managed is 
.PN True , 
.PN XtRealizeWidget
maps the widget window.
.LP
.PN XtCreateWidget ,
.PN XtRealizeWidget ,
.PN XtManageChildren ,
.PN XtUnmanageChildren ,
and
.PN XtDestroyWidget
maintain the following invariants:
.IP \(bu 5
If a widget is realized, then all its managed children are realized.
.IP \(bu 5
If a widget is realized, then all its managed children that are also
mapped_when_managed are mapped.
.LP
All \*(xI functions and all widget routines should work
with either realized or unrealized widgets.
.sp
.LP
To check whether or not a widget has been realized, use
.PN XtIsRealized .
.IN "XtIsRealized" "" "@DEF@"
.FD 0
Boolean XtIsRealized(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
The
.PN XtIsRealized
function returns 
.PN True 
if the widget has been realized,
that is, if the widget has a nonzero X window ID.
.LP
Some widget procedures (for example, set_values) might wish to
operate differently
after the widget has been realized.
.NH 3
Widget Instance Window Creation: the realize Procedure
.XS
\*(SN Widget Instance Window Creation: the realize Procedure
.XE
.LP
The realize procedure pointer in a widget class is of type
.PN XtRealizeProc :
.IN "XtRealizeProc" "" "@DEF@"
.FD 0
typedef void (*XtRealizeProc)(Widget, XtValueMask *, XSetWindowAttributes *);
.br
      Widget \fIw\fP;
.br
      XtValueMask *\fIvalue_mask\fP;
.br
      XSetWindowAttributes *\fIattributes\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.IP \fIvalue_mask\fP 1i
Specifies which fields in the attributes structure to use.
.IP \fIattributes\fP 1i
Specifies the window attributes to use in the
.PN XCreateWindow
call.
.LP
The realize procedure must create the widget's window.
.LP
The generic
.PN XtRealizeWidget
function fills in a mask and a corresponding
.PN XSetWindowAttributes
structure.
It sets the following fields based on information in the widget
.PN Core
structure:
.IP \(bu 5
The background_pixmap (or background_pixel if background_pixmap is NULL)
is filled in from the corresponding field.
.IP \(bu 5
The border_pixmap (or border_pixel if border_pixmap is NULL)
is filled in from the corresponding field.
.IP \(bu 5
The event_mask is filled in based on the event handlers registered,
the event translations specified, whether expose is non-NULL,
and whether visible_interest is 
.PN True .
.IP \(bu 5
The bit_gravity is set to
.PN NorthWestGravity
if the expose field is NULL.
.IP \(bu 5
The do_not_propagate_mask is set to propagate all pointer and keyboard events
up the window tree.
A composite widget can implement functionality caused by
an event anywhere inside it (including on top of children widgets)
as long as children do not specify a translation for the event.
.LP
All other fields in attributes (and the corresponding bits in
value_mask) can be set by the realize procedure.
.LP
Note that because realize is not a chained operation,
the widget class realize procedure must update the
.PN XSetWindowAttributes
structure with all the appropriate fields from 
.Pn non- Core
superclasses.
.LP
.IN "Inheritance"
A widget class can inherit its realize procedure from its superclass
during class initialization.
The realize procedure defined for
.PN Core 
calls
.PN XtCreateWindow
with the passed value_mask and attributes
and with windowClass and visual set to
.PN CopyFromParent .
Both
.PN CompositeWidgetClass
and
.PN ConstraintWidgetClass
inherit this realize procedure, and most new widget subclasses
can do the same (see Section 1.4.9).
.LP
The most common noninherited realize procedures set bit_gravity in the mask
and attributes to the appropriate value and then create the window.
For example, depending on its justification, Label sets bit_gravity to
.PN WestGravity ,
.PN CenterGravity ,
or
.PN EastGravity .
Consequently, shrinking it just moves the bits appropriately,
and no
.PN Expose
event is needed for repainting.
.LP
If a composite widget's children should be realized in a particular
order (typically to control the stacking order),
it should call
.PN XtRealizeWidget
on its children itself in the appropriate order from within its own
realize procedure.
.LP
Widgets that have children and that are not a subclass of
.PN compositeWidgetClass
are responsible for calling
.PN XtRealizeWidget
on their children, usually from within the realize procedure.
.NH 3
Window Creation Convenience Routine
.XS
\*(SN Window Creation Convenience Routine
.XE
.LP
Rather than call the Xlib
.PN XCreateWindow
.IN "realize procedure"
function explicitly, a realize procedure should call the \*(xI analog
.PN XtCreateWindow ,
which simplifies the creation of windows for widgets.
.IN "XtCreateWindow" "" "@DEF@"
.FD 0
void XtCreateWindow(\fIw\fP, \fIwindow_class\fP, \fIvisual\fP, \
\fIvalue_mask\fP, \fIattributes\fP)
.br
      Widget \fIw\fP;
.br
      unsigned int \fIwindow_class\fP;
.br
      Visual *\fIvisual\fP;
.br
      XtValueMask \fIvalue_mask\fP;
.br
      XSetWindowAttributes *\fIattributes\fP;
.FN
.ds Wi that is used to set the x,y coordinates and so on
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fIwindow_class\fP 1i
Specifies the Xlib window class (for example,
.PN InputOutput ,
.PN InputOnly ,
or
.PN CopyFromParent ).
.IP \fIvisual\fP 1i
Specifies the visual type (usually
.PN CopyFromParent ).
.ds Vm attribute fields to use
.IP \fIvalue_mask\fP 1i
Specifies which \*(Vm.
.IP \fIattributes\fP 1i
Specifies the window attributes to use in the
.PN XCreateWindow
call.
.LP
The
.PN XtCreateWindow
function calls the Xlib
.PN XCreateWindow
function with values from the widget structure and the passed parameters.
Then, it assigns the created window to the widget's window field.
.LP
.PN XtCreateWindow
evaluates the following fields of the
.PN Core 
widget structure:
.IP \(bu 5
depth
.IP \(bu 5
screen
.IP \(bu 5
parent -> core.window
.IP \(bu 5
x
.IP \(bu 5
y
.IP \(bu 5
width
.IP \(bu 5
height
.IP \(bu 5
border_width
.NH 2
Obtaining Window Information from a Widget
.XS
\fB\*(SN Obtaining Window Information from a Widget\fP
.XE
.LP
The 
.PN Core
widget definition contains the screen and window IDs.
The window field may be NULL for a while
(see Sections 2.4 and 2.5).
.LP
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.
.sp
.IN "XtDisplay" "" "@DEF@"
.FD 0
Display *XtDisplay(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
.PN XtDisplay
returns the display pointer for the specified widget.
.sp
.LP
.IN "XtParent" "" "@DEF@"
.FD 0
Widget XtParent(\fIw\fP)
.br
     Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
.PN XtParent
returns the parent widget for the specified widget.
.sp
.LP
.IN "XtScreen" "" "@DEF@"
.FD 0
Screen *XtScreen(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
.PN XtScreen
returns the screen pointer for the specified widget.
.sp
.LP
.IN "XtWindow" "" "@DEF@"
.FD 0
Window XtWindow(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
.PN XtWindow
returns the window of the specified widget.
.LP
Several window attributes are locally cached in the widget.
Thus, they can be set by the resource manager and
.PN XtSetValues 
as well as used by routines that derive structures from these values
(for example, depth for deriving pixmaps,
background_pixel for deriving GCs, and so on) or in the
.PN XtCreateWindow
call.
.LP
The x, y, width, height, and border_width window attributes are available to
geometry managers.
These fields are maintained synchronously inside the \*(tk.
When an
.PN XConfigureWindow
is issued on the widget's window (on request of its parent),
these values are updated immediately rather than sometime later
when the server generates a
.PN ConfigureNotify
event.
(In fact, most widgets do not have
.PN SubstructureNotify
turned on.)
This ensures that all geometry calculations are based on the internally
consistent toolkit world, rather than on either
an inconsistent world updated by asynchronous
.PN ConfigureNotify
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 Chapter 6).
.NH 3
Unrealizing Widgets
.XS
\fB\*(SN Unrealizing Widgets\fP
.XE
.LP
To destroy the windows associated with a widget and its descendants, use
.PN XtUnrealizeWidget .
.IN "XtUnrealizeWidget" "" "@DEF@"
.FD 0
void XtUnrealizeWidget(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
The
.PN XtUnrealizeWidget
function destroys the windows of an existing widget and all of its
children (recursively down the widget tree).
To recreate the windows at a later time,
call
.PN XtRealizeWidget
again.
If the widget was managed, 
it will be unmanaged automatically before its window is freed.
.NH 2
Destroying Widgets
.XS
\fB\*(SN Destroying Widgets\fP
.XE
.LP
The \*(xI provide support to:
.IP \(bu 5
Destroy all the pop-up children of the widget being destroyed
and destroy all children of composite widgets
.IP \(bu 5
Remove (and unmap) the widget from its parent
.IP \(bu 5
Call the callback procedures that have been registered to trigger 
when the widget is destroyed
.IP \(bu 5
Minimize the number of things a widget has to deallocate when destroyed
.IP \(bu 5
Minimize the number of
.PN XDestroyWindow
calls
.sp
.LP
To destroy a widget instance, use
.PN XtDestroyWidget .
.IN "XtDestroyWidget" "" "@DEF@"
.FD 0
void XtDestroyWidget(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
The
.PN XtDestroyWidget
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.
.LP
In phase one,
.PN XtDestroyWidget
performs the following:
.IP \(bu 5
If the being_destroyed field of the widget is 
.PN True ,
it returns immediately.
.IP \(bu 5
Recursively descends the widget tree and
sets the being_destroyed field to 
.PN True 
for the widget and all children.
.IP \(bu 5
Adds the widget to a list of widgets (the destroy list) that should be
destroyed when it is safe to do so.
.LP
Entries on the destroy list satisfy the invariant that
if w2 occurs after w1 on the destroy list then w2 is not a descendent of w1.
(A descendant refers to both normal and pop-up children.)
.LP
Phase two 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
.PN XtDispatchEvent
is about to return or immediately if not in
.PN XtDispatchEvent .
.LP
In phase two,
.PN XtDestroyWidget
performs the following on each entry in the destroy list:
.IP \(bu 5
Calls the destroy callback procedures registered on the widget 
(and all descendants) in post-order (it calls children callbacks 
before parent callbacks).
.IP \(bu 5
If the widget's parent is a subclass of 
.PN compositeWidgetClass 
and if the parent is not being destroyed, 
it calls 
.PN XtUnmanageChild 
on the widget and then calls the widget's parent's delete_child procedure
(see Section 3.4).
.IP \(bu 5
If the widget's parent is a subclass of
.PN constraintWidgetClass ,
it calls the constraint destroy procedure for the parent,
then the parent's superclass,
until finally it calls the constraint destroy procedure for
.PN constraintWidgetClass .
.IP \(bu 5
Calls the destroy methods for the widget (and all descendants)
in post-order.
For each such widget,
it calls the 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 Core
class record.
.IP \(bu 5
Calls
.PN XDestroyWindow
if the widget is realized (that is, has an X window).
The server recursively destroys all descendant windows.
.IP \(bu 5
Recursively descends the tree and deallocates all pop-up widgets, constraint
records, callback lists and, if the widget is a subclass of 
.PN compositeWidgetClass , 
children.
.NH 3
Adding and Removing Destroy Callbacks
.XS
\fB\*(SN Adding and Removing Destroy Callbacks\fP
.XE
.LP
When a 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 Chapter 8.
.IN "Destroy Callbacks"
The destroy callback list is identified by the resource name
XtNdestroyCallback.
.LP
For example, the following adds an application-supplied destroy callback 
procedure \fIClientDestroy\fP with client data to a widget by calling
.PN XtAddCallback .
.IN "XtAddCallback"
.FD 0
XtAddCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
.FN
.LP
Similarly, the following removes the application-supplied destroy callback
procedure \fIClientDestroy\fP by calling
.PN XtRemoveCallback .
.IN "XtRemoveCallback"
.FD 0
XtRemoveCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
.FN
.LP
The \fIClientDestroy\fP argument is of type
.PN XtCallbackProc :
.LP
.Ds
typedef void (*XtCallbackProc)(Widget, caddr_t, caddr_t);
.De
.LP
For further information,
see Section 8.1.
.NH 3
Dynamic Data Deallocation: the destroy Procedure
.XS
\*(SN Dynamic Data Deallocation: the destroy Procedure
.XE
.LP
.IN "destroy procedure" "" "@DEF@"
The destroy procedure pointer in the
.PN CoreClassPart
structure is of type
.PN XtWidgetProc :
.IN "XtWidgetProc" "" "@DEF@"
.FD 0
typedef void (*XtWidgetProc)(Widget);
.FN
.LP
The destroy procedures are called in subclass-to-superclass order.
Therefore, a widget's destroy procedure only should deallocate storage
that is specific to the subclass and should not bother with the storage
allocated by any of its superclasses.
The destroy procedure should only deallocate resources that have been
explicitly created by the subclass.
Any resource that was obtained from the resource database 
or was passed in 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 widget class record can be NULL.
.LP
Deallocating storage includes but is not limited to:
.IP \(bu 5
Calling
.PN XtFree
on dynamic storage allocated with
.PN XtMalloc ,
.PN XtCalloc ,
and so on
.IP \(bu 5
Calling
.PN XFreePixmap
on pixmaps created with direct X calls
.IP \(bu 5
Calling
.PN XtDestroyGC
on GCs allocated with
.PN XtGetGC 
.IP \(bu 5
Calling
.PN XFreeGC
on GCs allocated with direct X calls
.IP \(bu 5
Calling
.PN XtRemoveEventHandler
on event handlers added with
.PN XtAddEventHandler 
.IP \(bu 5
Calling
.PN XtRemoveTimeOut
on timers created with
.PN XtAppAddTimeOut 
.IP \(bu 5
Calling
.PN XtDestroyWidget
for each child if the widget has children
and is not a subclass of 
.PN compositeWidgetClass
.NH 3
Dynamic Constraint Data Deallocation: the constraint destroy Procedure
.XS
\*(SN Dynamic Constraint Data Deallocation: the constraint destroy Procedure
.XE
.LP
The constraint destroy procedure identified in the
.PN ConstraintClassPart
structure is called for a widget whose parent is a subclass of
.PN constraintWidgetClass .
This constraint destroy procedure pointer is of type
.PN XtWidgetProc .
The constraint destroy procedures are called in subclass-to-superclass order,
starting at the widget's parent and ending at
.PN constraintWidgetClass .
Therefore, a parent's constraint destroy procedure only should deallocate
storage that is specific to the constraint subclass
and not the storage allocated by any of its superclasses.
.LP
If a parent does not need to deallocate any constraint storage,
the constraint destroy procedure entry
in its class record can be NULL.
.NH 2
Exiting from an Application
.XS
\fB\*(SN Exiting from an Application\fP
.XE
.LP
All \*(tk applications should terminate
by calling
.PN XtDestroyApplicationContext
and then exiting
using the
standard method for their operating system (typically, by calling
.PN exit
for UNIX-based systems).
The quickest way to make the windows disappear while exiting is to call
.PN XtUnmapWidget
on each top-level shell widget.
The \*(tk has no resources beyond those in the program image,
and the X server will free its resources when its connection
to the application is broken.
.bp
