\&
.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
or by calling the convenience procedure
.PN XtAppInitialize
which combines the functions of the preceding procedures.
.LP
Multiple instances of \*(tk 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 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 retrieves the language string to be
used for the specified display (see Section 11.11),
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 POSIX-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
.IN "Resources" "reverseVideo"
.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, or NULL.
Note that a display can be in at most one application context.
.IP \fIapplication_name\fP 1i
Specifies the name of the application instance, or NULL.
.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 POSIX-based systems, 
this is the value of the DISPLAY environment variable).
.LP
If this succeeds, it then calls
.PN XtDisplayInitialize
and passes it the opened display and
the value of the \-name option specified in argv as the application name.
If no name option is specified
and application_name is
non-NULL, application_name is passed to
.PN XtDisplayInitialize .
If application_name is NULL and if the environment variable
.PN \s-1RESOURCE_NAME\s+1
is set, the value of
.PN \s-1RESOURCE_NAME\s+1
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 argv[0] less any directory and file type components; that is, the
final component of argv[0], if specified.  If argv[0] does not exist or
is the empty string, the application name is ``main''.
.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 first determines the language
string to be used for the specified display and then
loads the application's resource database for this 
display/host/application combination from the following sources in order
(i.e., the first named source has lowest precedence):
.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
.PN XtDisplayInitialize
creates a unique resource database for each
Display specified.  When creating the database, a language string is
determined for the Display in a manner equivalent to the following
sequence of actions:
.PN XtDisplayInitialize
initially creates two
temporary databases.  The first database is constructed by parsing the
command line according to section 2.3 and the second database from the
string returned by
.PN XResourceManagerString
or, if
.PN XResourceManagerString
returns NULL, the contents of a resource file
in the user's home directory.  On POSIX-based systems, the usual name
.IN ".Xdefaults" "" "@DEF@"
for this user preference resource file is $HOME/\fB.Xdefaults\fP.  The
database constructed from the command line is then queried for the
resource \fIname\fP\fB.xnlLanguage\fP, class
\fIClass\fP\fB.XnlLanguage\fP where name
.IN "xnlLanguage" "" "@DEF@"
.IN "Resources" "xnlLanguage"
and Class are the specified application_name and application_class.
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
.PN \s-1LANG\s+1
environment variable.  If no language string is
found, the empty string is used.
.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.
The file is found by calling
.PN XtResolvePathname
with the
parameters (display, "app-defaults", NULL, NULL, NULL, NULL, 0, NULL);
see Section 11.11.
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 which 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
.PN XtAppSetFallbackResources .
.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.
Its name is found by calling
.PN XtResolvePathname
with the parameters (display, NULL,
NULL, NULL, path, NULL, 0, NULL) where path is defined in an operating-system
specific way.  On POSIX-based systems path is defined to be the value
of the environment variable
.PN \s-1XUSERFILESEARCHPATH\s+1
if this is defined.  Otherwise, if
.PN \s-1XUSERFILESEARCHPATH\s+1
is not defined but the environment variable
.PN \s-1XAPPLRESDIR\s+1
is defined, path is
.IP
$XAPPLRESDIR/%L/%N:$XAPPLRESDIR/%l/%N:$XAPPLRESDIR/%N:$HOME/%N
.LP
where $XAPPLRESDIR is replaced by the value of that variable and $HOME
is replaced by the user's home directory.  If
.PN \s-1XAPPLRESDIR\s+1
is not defined, path is
.IP
$HOME/%L/%N:$HOME/%l/%N:$HOME/%N
.LP
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 temporary database constructed from the server resource property
or user resource file during language determination is then 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 POSIX-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.
.sp
.LP
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 first of the five sources listed above),
use
.PN XtAppSetFallbackResources .
.IN "XtAppSetFallbackResources" "" "@DEF@"
.FD 0
void XtAppSetFallbackResources(\fIapp_context\fP, \fIspecification_list\fP)
.br
      XtAppContext \fIapp_context\fP;
.br
      String *\fIspecification_list\fP;
.FN
.IP \fIapp_context\fP 1.25i
Specifies the application context in which
the fallback specifications will be used.
.IP \fIspecification_list\fP 1.25i
Specifies a NULL-terminated list of
resource specifications to pre-load
the database, or NULL.
.LP
Each entry in specification_list points to a string in the format of
.PN XrmPutLineResource .
In the future, if
.PN XtDisplayInitialize
is not able
to find or read an application-specific class resource file according to the
rules given above and if specification_list is non-NULL, the
display-specific resource database will be initialized with the resource
specifications in specification_list.
.PN XtAppSetFallbackResources
is not
required to copy specification_list; 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
.PN XtAppSetFallbackResources
is called again.  The value NULL for
specification_list removes any previous fallback resource specification
for the application context.  The intended use is to provide a minimal
number of resources which 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.

.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 described in \fI\*(xL\fP:
.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 */
	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;	/* 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	.synchronous	NoArg	on
+synchronous	.synchronous	NoArg	off
\-title	.title	SepArg	next argument
\-xnllanguage	.xnlLanguage	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 for all screens on the Display.
.LP
.IN "synchronous" "" "@DEF@"
.IN "Resources" "synchronous"
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,
.PN XtDisplayInitialize
makes a call to
.PN XSynchronize
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.
.LP
.IN "selectionTimeout" "" "@DEF@"
.IN "Resources" "selectionTimeout"
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.
.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.
The \*(xI reserve all option names
beginning with the characters ``xt'' for future standard uses.
.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
void 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 .
.sp
.LP
.IN "varargs" "" "@DEF@"
All \*(xI interfaces that require ArgList arguments have analogs
which conform to the ANSI C variable-length argument list (``varargs'')
calling convention.  The name of the analog is formed by prefixing
``Va'' to the name of the corresponding ArgList procedure; e.g.,
.br
\fBXtVaCreateWidget\fP.
Each procedure named \fBXtVa\fP\fIsomething\fP takes as its
last arguments, in place of the corresponding ArgList,Cardinal
parameters, a variable-length parameter list of resource name and
value pairs where each name is of type
.PN String
and each value is of type
.PN XtArgVal .
The end of the list is identified by a name 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
ArgList and varargs forms interchangeably.
.LP
Two special names are defined for use only in varargs lists;
.PN XtVaTypedArg
and
.PN XtVaNestedList .
.sp
.LP
.IN "XtVaTypedArg" "" "@DEF@"
.Ds 0
#define XtVaTypedArg "XtVaTypedArg"
.De

If the name
.PN XtVaTypedArg
is specified in place of a resource
name then the following four arguments are interpreted as a
name,type,value,size tuple where name is of type
.PN String ,
type is of type
.PN String ,
value is of type
.PN XtArgVal ,
and size is of type int.  When a varargs list containing
.PN XtVaTypedArg
is processed, a resource type
conversion (see Section 9.6) is performed if necessary to convert the
value into the format required by the associated resource.  If type is
XtRString then value contains a pointer to the string and size
contains the number of bytes allocated, including the trailing null
byte.  If type is not XtRString, then if size is less than or equal to
sizeof(XtArgVal), the value should be the data cast to the type
XtArgVal, otherwise value 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.
.sp
.LP
.IN "XtVaNestedList" "" "@DEF@"
.Ds 0
#define XtVaNestedList  "XtVaNestedList"
.De
.LP
If the name
.PN XtVaNestedList
is specified in place of a resource name
then the following argument is interpreted as an
.PN XtVarArgsList
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.
.sp
.LP
To dynamically allocate a varargs list for use with
.PN XtVaNestedList
in multiple calls, use
.PN XtVaCreateArgsList .
.IN "XtVaCreateArgsList" "" "@DEF@"
.sp
.LP
.Ds 0
typedef XtPointer XtVarArgsList;
.De
.LP
.FD 0
XtVarArgsList XtVaCreateArgsList(\fIunused\fP, ...)
.br
      XtPointer \fIunused\fP;
.FN
.IP \fIunused\fP 1i
This argument is not currently used and must be specified as NULL.
.IP ... 1i
Specifies a variable-length parameter list of resource
name and value pairs.
.LP
The
.PN XtVaCreateArgsList
function allocates memory and copies its arguments into a
single list pointer which may be used with
.PN XtVaNestedList .
The end of
both lists is identified by a name entry containing NULL.  Any entries
of type
.PN XtVaTypedArg
are copied as specified without applying
conversions.  Data passed by reference (including Strings) is not
copied, only the pointers themselves; the caller must ensure that the
data remains valid for the lifetime of the created varargs list.  The
list should be freed using
.PN XtFree
when no longer needed.
.LP
Use of resource files and the resource database is generally
encouraged over lengthy ArgList or varargs lists whenever possible in
order to permit modification without recompilation.

.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, \fIobject_class\fP, \fIparent\fP, \
\fIargs\fP, \fInum_args\fP)
.br
      String \fIname\fP;
.br
      WidgetClass \fIobject_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.
.IP \fIobject_class\fP 1i
Specifies the widget class pointer for the created object.
.IP \fIparent\fP 1i
Specifies the parent widget.
.IP \fIargs\fP 1i
Specifies the argument list to override any other resource specifications.
.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
If the specified class is not
.PN coreWidgetClass
or a subclass thereof
and the parent is a subclass of
.PN compositeWidgetClass
and either no extension record in
the parent's composite class part extension field exists with the
record_type
.PN \s-1NULLQUARK\s+1
or the accepts_objects field in the extension
record is
.PN False ,
.PN XtCreateWidget
issues a fatal error.  See Section 3.1 and Chapter 12.
.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.4.
.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 .)
.sp
.LP
To create an instance of a widget using varargs lists, use
.PN XtVaCreateWidget .
.IN "XtVaCreateWidget" "" "@DEF@"
.FD 0
Widget XtVaCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, ...)
.br
      String \fIname\fP;
.br
      WidgetClass \fIobject_class\fP;
.br
      Widget \fIparent\fP;
.FN
.IP \fIname\fP 1i
Specifies the resource name for the created widget.
.IP \fIwidget_class\fP 1i
Specifies the widget class pointer for the created object.
.IP \fIparent\fP 1i
Specifies the parent widget.
.IP ... 1i
Specifies the variable-length argument list to override any other
resource specifications.
.LP
The
.PN XtVaCreateWidget
procedure is identical in function to
.PN XtCreateWidget
with the args and num_args parameters replaced by a varargs list as described
in Section 2.4.1.

.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.
.IP \fIapplication_class\fP 1i
Specifies the class name of this application.
.IP \fIwidget_class\fP 1i
Specifies the widget class for the top-level widget (normally
.PN applicationShellWidgetClass )
.IP \fIdisplay\fP 1i
Specifies the display.
.IP \fIargs\fP 1i
Specifies the argument list to override any other resource specifications.
.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
and to set the \s-1WM_CLASS\s+1 property on the shell's window.
.IN \s-1WM_CLASS\s+1
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
The widget returned by
.PN XtAppCreateShell
has the \s-1WM_COMMAND\s+1
and \s-1WM_CLASS\s+1
properties set for window and session managers
if the specified widget_class is a subclass of
.PN ApplicationShell
(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
.sp
.LP
To create a top-level widget that is the root of a widget tree using
varargs lists, use
.PN XtVaAppCreateShell .
.IN "XtVaAppCreateShell" "" "@DEF@"
.FD 0
Widget XtVaAppCreateShell(\fIapplication_name\fP, \fIapplication_class\fP, \
\fIwidget_class\fP, \fIdisplay\fP, ...)
.br
    String \fIapplication_name\fP;
.br
    String \fIapplication_class\fP;
.br
    WidgetClass \fIwidget_class\fP;
.br
    Display *\fIdisplay\fP;
.FN
.IP \fIapplication_name\fP 1i
Specifies the name of the application instance.
.IP \fIapplication_class\fP 1i
Specifies the class name of this application.
.IP \fIwidget_class\fP 1i
Specifies the widget class for the top-level widget.
.IP \fIdisplay\fP 1i
Specifies the display.
.IP ... 1i
Specifies the variable-length argument list to override any other
resource specifications.
.LP
The
.PN XtVaAppCreateShell
procedure is identical in function to
.PN XtAppCreateShell
with the args and num_args parameters replaced by a varargs list as
described in Section 2.4.1.

.NH 3
Convenience Procedure to Initialize an Application
.XS
\fB\*(SN Convenience Procedure to Initialize an Application\fP
.XE
.LP
To initialize the \*(tk internals, create an application context,
open and initialize a display and create the initial application shell
instance, an application may use
.PN XtAppInitialize
or
.PN XtVaAppInitialize .
.IN "XtVaAppInitialize" "" "@DEF@"
.FD 0
Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
\fIoptions\fP, \fInum_options\fP,
.br
                       \fIargc_in_out\fP, \fIargv_in_out\fP, \
\fIfallback_resources\fP, \fIargs\fP, \fInum_args\fP)
.br
      XtAppContext *\fIapp_context_return\fP;
.br
      String \fIapplication_class\fP;
.br
      XrmOptionDescList \fIoptions\fP;
.br
      Cardinal \fInum_options\fP;
.br
      Cardinal *\fIargc_in_out\fP;
.br
      String *\fIargv_in_out\fP;
.br
      String *\fIfallback_resources\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIapp_context_return\fP 1.5i
Returns the application context, if non-NULL.
.IP \fIapplication_class\fP 1.5i
Specifies the class name of the application.
.IP \fIoptions\fP 1.5i
Specifies the command line options table.
.IP \fInum_options\fP 1.5i
Specifies the number of entries in options.
.IP \fIargc_in_out\fP 1.5i
Specifies a pointer to the number of command line arguments.
.IP \fIargv_in_out\fP 1.5i
Specifies a pointer to the command line arguments.
.IP \fIfallback_resources\fP 1.5i
Specifies resource values to be used if the application class resource
file cannot be opened or read, or NULL.
.IP \fIargs\fP 1.5i
Specifies resource values to override any
other resource specifications for the created shell widget.
.IP \fInum_args\fP 1.5i
Specifies the count of args.
.LP
The
.PN XtAppInitialize
function calls
.PN XtToolkitInitialize
and
.PN XtCreateApplicationContext ,
then calls
.PN XtOpenDisplay
with a display_string of NULL and an
application_name of NULL, and finally calls
.PN XtAppCreateShell
with an application_name of NULL, a widget_class of
.PN applicationShellWidgetClass ,
and the specified args and num_args
and returns the created shell.  The modified argc and argv returned by
.PN XtDisplayInitialize
are returned in argc_in_out and argv_in_out.  If
app_context_return 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
.PN XtAppInitialize
terminates the application.  If fallback_resources is non-NULL,
.PN XtAppSetFallbackResources
is called with the value prior to calling
.PN XtOpenDisplay .
.sp
.LP
To initialize the \*(tk internals, create an application context,
open and initialize a display and create the initial application shell
instance using varargs lists, an application may use
.PN XtVaAppInitialize .
.IN "XtVaAppInitialize" "" "@DEF@"
.FD 0
Widget XtVaAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
\fIoptions\fP, \fInum_options\fP,
.br
                         \fIargc_in_out\fP, \fIargv_in_out\fP, \
\fIfallback_resources\fP, ...)
.br
    XtAppContext *\fIapp_context_return\fP;
.br
    String \fIapplication_class\fP;
.br
    XrmOptionDescList \fIoptions\fP;
.br
    Cardinal \fInum_options\fP;
.br
    Cardinal *\fIargc_in_out\fP;
.br
    String *\fIargv_in_out\fP;
.br
    String *\fIfallback_resources\fP;
.FN
.IP \fIapp_context_return\fP 1.5i
Returns the application context, if non-NULL.
.IP \fIapplication_class\fP 1.5i
Specifies the class name of the application.
.IP \fIoptions\fP 1.5i
Specifies the command line options table.
.IP \fInum_options\fP 1.5i
Specifies the number of entries in options.
.IP \fIargc_in_out\fP 1.5i
Specifies a pointer to the number of command line arguments.
.IP \fIargv_in_out\fP 1.5i
Specifies the command line arguments array.
.IP \fIfallback_resources\fP 1.5i
Specifies resource values to be used if the application class
resource file cannot be opened, or NULL.
.IP ... 1.5i
Specifies the variable-length argument list to override any other
resource specifications for the created shell.
.LP
The
.PN XtVaAppInitialize
procedure is identical in function to
.PN XtAppInitialize
with the args and num_args parameters replaced by a varargs list as described
in Section 2.4.1.

.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, ArgList, Cardinal*);
.br
      Widget \fIrequest\fP; 
.br
      Widget \fInew\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal *\fInum_args\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.
.IP \fIargs\fP 1i
Specifies the argument list passed by the client, for
computing derived resource values.
.IP \fInum_args\fP 1i
Specifies the number of arguments in the argument list.
.LP
An initialization procedure performs the following:
.IP \(bu 5
Allocates space for and copies any resources that are referenced by address
which the widget creator is allowed to free or modify
after the widget has been created.
For example,
if a widget has a field that is a 
.PN String
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 state so in their user documentation.
.NT
It is not necessary to allocate space for or copy callback lists.
.NE
.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.
.NT
A widget may only directly assign
its own width and height within the initialize, set_values and
set_values_hook procedures; see Chapter 6, Geometry Management.
.NE
.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
after all fields specified in the resource lists have been
initialized.  The initialize procedure does not need to examine
the args 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.
.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
.NT
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 which used it in previous releases.
.NE
.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 accept
either realized or unrealized widgets.
When calling the realize procedures for children of a composite
widget,
.PN XtRealizeWidget
calls the procedures in reverse order of
appearance in the composite.children list.  By default, this 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.
.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 and corresponding bits in value_mask
based on information in the widget
.PN Core
structure:
.IP \(bu 5
The background_pixmap (or background_pixel if background_pixmap is
.PN XtUnspecifiedPixmap )
is filled in from the corresponding field.
.IP \(bu 5
The border_pixmap (or border_pixel if border_pixmap is
.PN XtUnspecifiedPixmap )
is filled in from the corresponding field.
.IP \(bu 5
The colormap 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.
.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.6.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
.IP \(bu 5
depth
.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.
.sp
.LP
The display pointer, screen pointer and window of a widget or
of the closest widget ancestor of a non-widget object are available
by means of
.PN XtDisplayOfObject ,
.PN XtScreenOfObject
and
.PN XtWindowOfObject .
.IN "XtDisplayOfObject" "" "@DEF@"
.sp
.LP
.FD 0
Display *XtDisplayOfObject(\fIobject\fP)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object; it may be of class Object or any subclass thereof.
.LP
.PN XtDisplayOfObject
is identical in function to
.PN XtDisplay
if the object is a widget; otherwise
.PN XtDisplayOfObject
returns the display
pointer for the nearest ancestor of object that is of class
.PN Widget .
.sp
.IN "XtScreenOfObject" "" "@DEF@"
.FD 0
Screen *XtScreenOfObject(\fIobject\fP)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object; it may be of class Object or any subclass thereof.
.LP
.PN XtScreenOfObject
is identical in function to
.PN XtScreen
if the object is a widget; otherwise
.PN XtScreenOfObject
returns the screen pointer
for the nearest ancestor of object that is of class
.PN Widget .
.sp
.IN "XtWindowOfObject" "" "@DEF@"
.FD 0
Window XtWindowOfObject(\fIobject\fP)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object; it may be of class Object or any subclass thereof.
.LP
.PN XtWindowOfObject
is identical in function to
.PN XtWindow
if the object is a widget; otherwise
.PN XtWindowOfObject
returns the window for the nearest ancestor of object that is of class
.PN Widget .
.sp
.IN "XtName" "" "@DEF@"
.FD 0
String XtName(\fIobject\fP)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object whose name is desired; it may be of class Object
or any subclass thereof.
.LP
.PN XtName
returns a pointer to the instance name of the specified object.
The storage is owned by the \*(xI and must not be modified.  The
name is not qualified by the names of any of the object's ancestors.
.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
If the widget is currently unrealized,
.PN XtUnrealizeWidget
simply returns.  Otherwise it performs the following:
.IP \(bu 5
Unmanages the widget if the widget is managed.
.IP \(bu 5
Makes a post-order (child to parent) traversal of the widget tree
rooted at the specified widget and, for each widget that has
declared a callback list named ``unrealizeCallback'', executes the
procedures on the
.PN XtNunrealizeCallback
list.
.IN "unrealizeCallback" "" "@DEF@"
.IP \(bu 5
Destroys the widget's window and any subwindows by calling
.PN XDestroyWindow
on the specified widget's window.
.LP
Any events in the queue or which arrive following a call to
.PN XtUnrealizeWidget
will be dispatched as if the window(s) of the
unrealized widget(s) had never existed.

.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.3).
.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, XtPointer, XtPointer);
.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 POSIX-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
