git update until 25 Mar 2011

xserver 
fontconfig
glproto
libXau
libXft
libXmu
libfontenc
libxcb
mesa
mkfontscale
pixman
randrproto
xkeyboard-config
xtrans
xwininfo

updated following packages:

xproto-7.0.21
xineramaproto-1.2.1
libXt-1.1.1
libxkbfile-1.0.7
libXpm-3.5.9
libXfont-1.4.3
libXaw-1.0.9
bdftopcf-1.0.3
encodings-1.0.4
fixesproto-5.0
font-adobe-100dpi-1.0.3
font-adobe-75dpi-1.0.3
font-adobe-utopia-100dpi-1.0.4
font-adobe-utopia-75dpi-1.0.4
font-adobe-utopia-type1-1.0.4
font-alias-1.0.3
font-arabic-misc-1.0.3
font-bh-100dpi-1.0.3
font-bh-75dpi-1.0.3
font-bh-lucidatypewriter-100dpi-1.0.3
font-bh-lucidatypewriter-75dpi-1.0.3
font-bh-ttf-1.0.3
font-bh-type1-1.0.3
font-bitstream-100dpi-1.0.3
font-bitstream-75dpi-1.0.3
font-bitstream-speedo-1.0.2
font-bitstream-type1-1.0.3
font-cronyx-cyrillic-1.0.3
font-cursor-misc-1.0.3
font-daewoo-misc-1.0.3
font-dec-misc-1.0.3
font-ibm-type1-1.0.3
font-isas-misc-1.0.3
font-jis-misc-1.0.3
font-micro-misc-1.0.3
font-misc-cyrillic-1.0.3
font-misc-ethiopic-1.0.3
font-misc-meltho-1.0.3
font-misc-misc-1.1.2
font-mutt-misc-1.0.3
font-schumacher-misc-1.1.2
font-screen-cyrillic-1.0.4
font-sony-misc-1.0.3
font-sun-misc-1.0.3
font-util-1.2.0
font-winitzki-cyrillic-1.0.3
font-xfree86-type1-1.0.4

1 files changed, 3165 insertions, 0 deletions

diff --git a/libXt/specs/CH02 b/libXt/specs/CH02
new file mode 100644
index 000000000..cbb4bb8a5
--- /dev/null
+++ b/libXt/specs/CH02
@@ -0,0 +1,3165 @@
+.\" $Xorg: CH02,v 1.3 2000/08/17 19:42:42 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\" 
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\" 
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\" 
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.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 \(em Widget Instantiation
+.XE
+A hierarchy 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 the 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, that is, members of the class
+.PN compositeWidgetClass ,
+are containers for an arbitrary, 
+but widget implementation-defined, collection of children,
+which may be instantiated by the composite widget itself, 
+by other clients, or by a combination of the two.
+Composite widgets also contain methods for managing the geometry (layout) 
+of any child widget.
+Under unusual circumstances,
+a composite widget may have zero children, 
+but it usually has at least one.
+By contrast, 
+primitive widgets that contain children typically instantiate 
+specific children of known classes themselves and do not expect external 
+clients to do so.
+Primitive widgets also do not have general geometry management methods.
+.LP
+In addition,
+the \*(xI recursively perform many operations 
+(for example, realization and destruction)
+on composite widgets and all their children.
+Primitive widgets that have children must be prepared 
+to perform the recursive operations themselves on behalf of their children. 
+.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 upward traversal of the widget tree,
+each widget has a pointer to its parent widget.
+The
+Shell 
+widget that
+.PN XtAppCreateShell 
+returns has a \fIparent\fP pointer of NULL.
+.LP
+To facilitate downward traversal of the widget tree,
+the \fIchildren\fP field of
+each composite widget is a pointer to an array of child widgets,
+which includes all normal children created,
+not just the subset of children that are managed by the composite widget's
+geometry manager.
+Primitive widgets
+that instantiate children are entirely responsible for all operations
+that require downward traversal below themselves.
+In addition,
+every widget has a pointer to an array of pop-up children.
+
+.NH 2
+Initializing the \*(tk
+.XS
+\fB\*(SN Initializing the \*(tk\fP
+.XE
+.LP
+Before an application can call any \*(xI function
+other than
+.PN XtSetLanguageProc 
+and 
+.PN XtToolkitThreadInitialize ,
+it must initialize the \*(xI by using
+.IP \(bu 5
+.PN XtToolkitInitialize ,
+which initializes the \*(xI 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 root of a widget tree
+.LP
+Or an application can call the convenience procedure
+.PN XtOpenApplication ,
+which combines the functions of the preceding procedures.
+An application wishing to use the ANSI C locale mechanism should call
+.PN XtSetLanguageProc
+prior to calling
+.PN XtDisplayInitialize ,
+.PN XtOpenDisplay ,
+.PN XtOpenApplication ,
+or 
+.PN XtAppInitialize .
+.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 instance may need multiple display connections 
+to have widgets on multiple displays.
+From the application's point of view, multiple display connections
+usually are treated together as a single unit
+for purposes of event dispatching.
+.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 one or more X
+.PN Display
+pointers for that application.
+The \*(xI handle all display connections within a single application
+context simultaneously, handling input in a round-robin fashion.
+The application context type
+.PN XtAppContext
+.IN "XtAppContext" "" "@DEF@"
+is opaque to clients.
+.sp
+.LP
+To initialize the \*(xI internals, use
+.PN XtToolkitInitialize .
+.LP
+.IN "XtToolkitInitialize" "" "@DEF@"
+.sM
+.FD 0
+void XtToolkitInitialize()
+.FN
+.LP
+.eM
+If
+.PN XtToolkitInitialize
+was previously called, it returns immediately.
+When
+.PN XtToolkitThreadInitialize
+is called before
+.PN XtToolkitInitialize ,
+the latter is protected against
+simultaneous activation by multiple threads.
+.sp
+.LP
+To create an application context, use
+.PN XtCreateApplicationContext .
+.LP
+.IN "XtCreateApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+XtAppContext XtCreateApplicationContext()
+.FN
+.LP
+.eM
+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
+remaining display connections in it, use
+.PN XtDestroyApplicationContext .
+.LP
+.IN "XtDestroyApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+void XtDestroyApplicationContext(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+The
+.PN XtDestroyApplicationContext
+function destroys the specified application context.
+If called from within an event dispatch (for example, in a callback procedure),
+.PN XtDestroyApplicationContext
+does not destroy the application context until the dispatch is complete.
+.sp
+.LP
+To get the application context in which a given widget was created, use
+.PN XtWidgetToApplicationContext .
+.LP
+.IN "XtWidgetToApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+XtAppContext XtWidgetToApplicationContext(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which you want the application context.  \*(oI
+.LP
+.eM
+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 .
+.LP
+.IN "XtDisplayInitialize" "" "@DEF@"
+.sM
+.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
+      int *\fIargc\fP;
+.br
+      String *\fIargv\fP;
+.FN
+.IP \fIapp_context\fP 1.4i
+Specifies the application context.
+.IP \fIdisplay\fP 1.4i
+Specifies a previously opened display connection.  Note that a single
+display connection can be in at most one application context.
+.IP \fIapplication_name\fP 1.4i
+Specifies the name of the application instance.
+.IP \fIapplication_class\fP 1.4i
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+.IP \fIoptions\fP 1.4i
+Specifies how to parse the command line for any application-specific resources.
+The \fIoptions\fP argument is passed as a parameter to
+.PN XrmParseCommand .
+For further information,
+see Section 15.9 in \fI\*(xL\fP and Section 2.4 of this specification.
+.IP \fInum_options\fP 1.4i
+Specifies the number of entries in the options list.
+.IP \fIargc\fP 1.4i
+Specifies a pointer to the number of command line parameters.
+.IP \fIargv\fP 1.4i
+Specifies the list of command line parameters.
+.LP
+.eM
+The
+.PN XtDisplayInitialize
+function retrieves the language string to be
+used for the specified display (see Section 11.11),
+calls the language procedure (if set) with that language string,
+builds the resource database for the default screen, calls the Xlib
+.PN XrmParseCommand
+function to parse the command line, 
+and performs other per-display initialization.
+After 
+.PN XrmParseCommand 
+has been called,
+\fIargc\fP and \fIargv\fP contain only those parameters that
+were not in the standard option table or in the table specified by the
+\fIoptions\fP argument.
+If the modified \fIargc\fP is not zero,
+most applications simply print out the modified \fIargv\fP along with a message
+listing the allowable options.
+On POSIX-based systems,
+the application name is usually the final component of \fIargv\fP[0].
+If the synchronous resource is
+.PN True ,
+.PN XtDisplayInitialize
+calls the Xlib
+.PN XSynchronize
+function to put Xlib into synchronous mode for this display connection
+and any others currently open in the application context.
+See Sections 2.3 and 2.4 for details on the \fIapplication_name\fP,
+\fIapplication_class\fP, \fIoptions\fP, and \fInum_options\fP arguments.
+.LP
+.PN XtDisplayInitialize
+calls
+.PN XrmSetDatabase
+to associate the resource database of the default screen with the
+display before returning.
+
+.KS
+.LP
+To open a display, initialize it, and then
+add it to an application context, use 
+.PN XtOpenDisplay .
+.LP
+.IN "XtOpenDisplay" "" "@DEF@"
+.sM
+.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
+       int *\fIargc\fP;
+.br
+       String *\fIargv\fP;
+.FN
+.IP \fIapp_context\fP 1.4i
+Specifies the application context.
+.IP \fIdisplay_string\fP 1.4i
+Specifies the display string, or NULL.
+.IP \fIapplication_name\fP 1.4i
+Specifies the name of the application instance, or NULL.
+.IP \fIapplication_class\fP 1.4i
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+.IP \fIoptions\fP 1.4i
+Specifies how to parse the command line for any application-specific resources.
+The options argument is passed as a parameter to
+.PN XrmParseCommand .
+.IP \fInum_options\fP 1.4i
+Specifies the number of entries in the options list.
+.IP \fIargc\fP 1.4i
+Specifies a pointer to the number of command line parameters.
+.IP \fIargv\fP 1.4i
+Specifies the list of command line parameters.
+.KE
+.LP
+.eM
+The
+.PN XtOpenDisplay
+function calls
+.PN XOpenDisplay 
+with the specified \fIdisplay_string\fP.
+If \fIdisplay_string\fP is NULL,
+.PN XtOpenDisplay
+uses the current value of the \-display option specified in \fIargv\fP.
+If no display is specified in \fIargv\fP,
+the user's default display is retrieved from the environment.
+On POSIX-based systems, 
+this is the value of the
+.PN \s-1DISPLAY\s+1
+environment variable.
+.LP
+If this succeeds,
+.PN XtOpenDisplay
+then calls
+.PN XtDisplayInitialize
+and passes it the opened display and
+the value of the \-name option specified in \fIargv\fP as the application name.
+If no \-name option is specified
+and \fIapplication_name\fP is
+non-NULL, \fIapplication_name\fP is passed to
+.PN XtDisplayInitialize .
+If \fIapplication_name\fP 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 \fIargv\fP[0] less any directory and file type components, that is, the
+final component of \fIargv\fP[0], if specified.  If \fIargv\fP[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
+See Section 7.12 for information regarding the use of
+.PN XtOpenDisplay
+in multiple threads.
+.sp
+.LP
+To close a display and remove it from an application context, use
+.PN XtCloseDisplay .
+.LP
+.IN "XtCloseDisplay" "" "@DEF@"
+.sM
+.FD 0
+void XtCloseDisplay(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display.
+.LP
+.eM
+The
+.PN XtCloseDisplay
+function calls
+.PN XCloseDisplay
+with the specified \fIdisplay\fP 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 .
+.LP
+See Section 7.12 for information regarding the use of 
+.PN XtCloseDisplay
+in multiple threads.
+
+.NH 2
+Establishing the Locale
+.XS
+\fB\*(SN Establishing the Locale\fP
+.XE
+.LP
+Resource databases are specified to be created in the current process
+locale.  During display initialization prior to creating the
+per-screen resource database, the \*(xI will call out to a specified
+application procedure to set the locale according to options found on
+the command line or in the per-display resource specifications.
+.LP
+The callout procedure provided by the application is of type
+.PN XtLanguageProc .
+.LP
+.IN "XtLanguageProc" "" "@DEF@"
+.sM
+.FD 0
+typedef String (*XtLanguageProc)(Display*, String, XtPointer);
+.br
+      Display *\fIdisplay\fP;
+.br
+      String \fIlanguage\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Passes the display.
+.IP \fIlanguage\fP
+Passes the initial language value obtained from the command line
+or server per-display resource specifications.
+.IP \fIclient_data\fP
+Passes the additional client data specified in the call to
+.PN XtSetLanguageProc .
+.LP
+.eM
+The language procedure allows an application to set the locale to
+the value of the language resource determined by
+.PN XtDisplayInitialize .
+The function returns a new language string that
+will be subsequently used by
+.PN XtDisplayInitialize
+to establish the path for loading resource files.  The returned
+string  will be copied by the \*(xI into new memory.
+.LP
+Initially, no language procedure is set by the \*(xI.
+To set the language procedure for use by
+.PN XtDisplayInitialize ,
+use
+.PN XtSetLanguageProc .
+.LP
+.IN XtSetLanguageProc "" "@DEF@"
+.IN "language procedure" "" "@DEF@"
+.sM
+.FD 0
+XtLanguageProc XtSetLanguageProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtLanguageProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context in which the language procedure is
+to be used, or NULL.
+.IP \fIproc\fP 1i
+Specifies the language procedure.
+.IP \fIclient_data\fP 1i
+Specifies additional client data to be passed to the language
+procedure when it is called.
+.LP
+.eM
+.PN XtSetLanguageProc
+sets the language procedure that will be called from
+.PN XtDisplayInitialize
+for all subsequent Displays initialized in the specified application
+context.   If \fIapp_context\fP is NULL, the specified language
+procedure is registered in all application contexts created by the
+calling process, including any future application contexts that may
+be created.   If \fIproc\fP is NULL, a default language procedure is
+registered.
+.PN XtSetLanguageProc
+returns the previously registered language procedure.
+If a language procedure has not yet been registered, the return value
+is unspecified, but if this return value is used in a subsequent call to
+.PN XtSetLanguageProc ,
+it will cause the default language procedure to be registered.
+.LP
+The default language procedure does the following:
+.IP \(bu 5
+Sets the locale according to the environment.  On ANSI C-based
+systems this is done by calling
+.PN setlocale (
+.PN LC_ALL ,
+\fIlanguage\fP ).
+If an error is encountered, a warning message is issued with
+.PN XtWarning .
+.IP \(bu 5
+Calls
+.PN XSupportsLocale
+to verify that the current locale is supported.
+If the locale is not supported, a warning message is issued with
+.PN XtWarning
+and the locale is set to ``C''.
+.IP \(bu 5
+Calls
+.PN XSetLocaleModifiers
+specifying the empty string.
+.IP \(bu 5
+Returns the value of the current locale.  On ANSI C-based systems this
+is the return value from a final call to
+.PN setlocale (
+.PN LC_ALL ,
+NULL ).
+.LP
+A client wishing to use this mechanism to establish locale can do so
+by calling
+.PN XtSetLanguageProc
+prior to
+.PN XtDisplayInitialize ,
+as in the following example.
+.LP
+.Ds 0
+.TA .5i
+	Widget top;
+	XtSetLanguageProc(NULL, NULL, NULL);
+	top = XtOpenApplication(...);
+	...
+.De
+
+.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.  It then
+creates a resource database for the default screen of the display by
+combining the following sources in order, with the entries in the
+first named source having highest precedence:
+
+.IP \(bu 5
+Application command line (\fIargc\fP, \fIargv\fP).
+.IP \(bu 5
+Per-host user environment resource file on the local host.
+.IP \(bu 5
+Per-screen resource specifications from the server.
+.IP \(bu 5
+Per-display resource specifications from the server or from
+.br
+the user preference file on the local host.
+.IP \(bu 5
+Application-specific user resource file on the local host.
+.IP \(bu 5
+Application-specific class resource file on the local host.
+
+.LP
+When the resource database for a particular screen on the display
+is needed (either internally, or when
+.PN XtScreenDatabase
+is called),
+it is created in the following manner using the sources listed
+above in the same order:
+
+.IP \(bu 5
+A temporary database, the ``server resource database'', is
+created 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 for this user
+preference resource file is $HOME/\fB.Xdefaults\fP.
+.IN ".Xdefaults" "" "@DEF@"
+
+.IP \(bu 5
+If a language procedure has been set,
+.PN XtDisplayInitialize
+first searches the command line for the option ``-xnlLanguage'', or
+for a -xrm option that specifies the xnlLanguage/XnlLanguage resource,
+as specified by Section 2.4.
+If such a resource is found, the value is assumed to be
+entirely in XPCS, the X Portable Character Set.  If neither option is
+specified on the command line,
+.PN XtDisplayInitialize
+queries the server resource database (which is assumed to be entirely
+in XPCS) for the resource
+\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
+where \fIname\fP
+.IN "xnlLanguage" "" "@DEF@"
+.IN "Resources" "xnlLanguage"
+and \fIClass\fP are the \fIapplication_name\fP and
+\fIapplication_class\fP specified to
+.PN XtDisplayInitialize .
+The language procedure is then invoked with
+the resource value if found, else the empty string.  The
+string returned from the language procedure is saved for all future
+references in the \*(xI that require the per-display language string.
+
+.IP \(bu 5
+The screen resource database is initialized by parsing the command
+line in the manner specified by Section 2.4.
+
+.IP \(bu 5
+If a language procedure has not been set,
+the initial database is then queried for the resource
+\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
+as specified above.
+If this database query fails, the server resource database is
+queried; if this query also fails, the language is determined from
+the environment; on POSIX-based systems, this is done by retrieving the
+value of the
+.PN \s-1LANG\s+1
+environment variable.  If no language string is
+found, the empty string is used.
+This language string is saved for all future references in the \*(xI
+that require the per-display language string.
+
+.IP \(bu 5
+After determining the language string, the user's environment resource
+file is then merged into the initial resource database if the file exists.
+This file is user-, host-, and process-specific and is expected to
+contain user preferences that are to override those specifications in
+the per-display and per-screen resources.
+On POSIX-based systems, the user's environment resource file name is
+specified by the value of the
+.PN \s-1XENVIRONMENT\s+1
+environment variable.
+If this environment variable does not exist, the user's home directory
+is searched for a file named
+.PN \&.Xdefaults-\fIhost\fP ,
+where \fIhost\fP is the host name of the machine on which the
+application is running.
+
+.IP \(bu 5
+The per-screen resource specifications are then merged into the screen
+resource database, if they exist.  These specifications are the string
+returned by
+.PN XScreenResourceString
+for the respective screen and are owned entirely by the user.
+
+.IP \(bu 5
+Next, the server resource database created earlier is merged into the
+screen resource database.  The server property, and corresponding user
+preference file, are owned and constructed entirely by the user.
+
+.IP \(bu 5
+The application-specific user resource file from the local host is
+then merged into the screen resource database.
+This file contains user customizations and is stored
+in a directory owned by the user.
+Either the user or the application or both can store resource specifications
+in the file.  Each should be prepared to find and respect entries made
+by the other.
+The file name is found by calling
+.PN XrmSetDatabase
+with the current screen resource database, after preserving the
+original display-associated database, then calling
+.PN XtResolvePathname
+with the parameters
+(\fIdisplay\fP, NULL, NULL, NULL, \fIpath\fP, NULL, 0, NULL),
+where \fIpath\fP is defined in an operating-system-specific way.
+On POSIX-based systems, \fIpath\fP is defined to be the value
+of the environment variable
+.PN \s-1XUSERFILESEARCHPATH\s+1
+if this is defined.  If
+.PN \s-1XUSERFILESEARCHPATH\s+1
+is not defined, an implementation-dependent default value is used.
+This default value is constrained in the following manner:
+
+.RS
+.IP \- 3
+If the environment variable
+.PN \s-1XAPPLRESDIR\s+1
+is not defined, the default
+.PN \s-1XUSERFILESEARCHPATH\s+1
+must contain at least six entries.  These entries must contain
+.IN "XUSERFILESEARCHPATH" "" "@DEF@"
+.IN "XAPPLRESDIR" "" "@DEF@"
+.IN "$HOME"
+$HOME as the directory prefix, plus the following substitutions:
+
+.nf
+.ta .3i 1.5i 2i
+1.	%C, %N, %L	or	%C, %N, %l, %t, %c
+2.	%C, %N, %l
+3.	%C, %N
+4.	%N, %L	or	%N, %l, %t, %c
+5.	%N, %l
+6.	%N
+.fi
+
+The order of these six entries within the path must be as given above.
+The order and use of substitutions within a given entry are
+implementation-dependent.
+
+.IP \- 3
+If
+.PN \s-1XAPPLRESDIR\s+1
+is defined, the default
+.PN \s-1XUSERFILESEARCHPATH\s+1
+must contain at least seven entries.  These entries must contain the
+following directory prefixes and substitutions:
+
+.ne 1.1
+.nf
+.ta .3i 1.6i 2.2i 3.3i 3.7i
+1.	$XAPPLRESDIR	with	%C, %N, %L	or	%C, %N, %l, %t, %c
+2.	$XAPPLRESDIR	with	%C, %N, %l
+3.	$XAPPLRESDIR	with	%C, %N
+4.	$XAPPLRESDIR	with	%N, %L	or	%N, %l, %t, %c
+5.	$XAPPLRESDIR	with	%N, %l
+6.	$XAPPLRESDIR	with	%N
+7.	$HOME	with	%N
+.fi
+
+The order of these seven entries within the path must be as given above.
+The order and use of substitutions within a given entry are
+implementation-dependent.
+.RE
+
+.IP \(bu 5
+Last, the application-specific class resource file from the local
+host is merged into the screen resource database.
+This file is owned by the application and is usually installed in
+a system directory when the application is installed.
+It may contain sitewide customizations specified by the system manager.
+The name of the application class resource file is found by calling
+.PN XtResolvePathname
+with the parameters
+(\fIdisplay\fP, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL).
+This file is expected to be provided by the developer of the application
+and may be required for the application to function properly.
+A simple application that wants to be assured of having a minimal
+set of resources in the absence of its class resource file can declare
+fallback resource specifications with
+.PN XtAppSetFallbackResources .
+Note that the customization substitution string is retrieved
+dynamically by
+.PN XtResolvePathname
+so that the resolved file name of the application class resource file
+can be affected by any of the earlier sources for the screen resource
+database, even though the contents of the class resource file have
+lowest precedence.  After calling
+.PN XtResolvePathname ,
+the original display-associated database is restored.
+.sp
+.LP
+To obtain the resource database for a particular screen, use
+.PN XtScreenDatabase .
+.LP
+.IN "XtScreenDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XtScreenDatabase(\fIscreen\fP)
+.br
+      Screen *\fIscreen\fP;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the screen whose resource database is to be returned.
+.LP
+.eM
+The
+.PN XtScreenDatabase
+function returns the fully merged resource database as specified above,
+associated with the specified screen.  If the specified \fIscreen\fP
+does not belong to a
+.PN Display
+initialized by
+.PN XtDisplayInitialize ,
+the results are undefined.
+.sp
+.LP
+To obtain the default resource database associated with a particular display, use
+.PN XtDatabase .
+.LP
+.IN "XtDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XtDatabase(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display.
+.LP
+.eM
+The
+.PN XtDatabase
+function is equivalent to
+.PN XrmGetDatabase .
+It returns the database associated with the specified display, or
+NULL if a database has not been set.
+.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 last of the six sources listed above),
+use
+.PN XtAppSetFallbackResources .
+.LP
+.IN "XtAppSetFallbackResources" "" "@DEF@"
+.sM
+.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 preload
+the database, or NULL.
+.LP
+.eM
+Each entry in \fIspecification_list\fP points to a string in the format of
+.PN XrmPutLineResource .
+Following a call to
+.PN XtAppSetFallbackResources ,
+when a resource database is being created for a particular screen and
+the \*(xI are not able
+to find or read an application-specific class resource file according to the
+rules given above and if \fIspecification_list\fP is not NULL, the
+resource specifications in \fIspecification_list\fP will be merged
+into the screen resource database in place of the application-specific
+class resource file.
+.PN XtAppSetFallbackResources
+is not
+required to copy \fIspecification_list\fP; 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
+\fIspecification_list\fP removes any previous fallback resource specification
+for the application context.  The intended use for fallback resources
+is to provide a minimal
+number of resources that will make the application usable (or at
+least terminate with helpful diagnostic messages) when some problem
+exists in finding and loading the application defaults file.
+
+.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 .
+.IP \-name 1i
+Sets the resource name prefix, 
+which overrides the application name passed to
+.PN XtOpenDisplay .
+.IP \-xnllanguage 1i
+Specifies the initial language string for establishing locale
+and for finding application class resource files.
+.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 Section 15.9 in \fI\*(xL\fP.
+.LP
+.sM
+.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;	/* Location of the resource value */
+	XPointer value;	/* Value to provide if XrmoptionNoArg */
+} XrmOptionDescRec, *XrmOptionDescList;
+
+.De
+.LP
+.eM
+The standard table contains the following entries:
+.TS H
+l l l l .
+_
+.sp 6p
+.TH
+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
+\-xtsessionID	.sessionID	SepArg	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.
+.LP
+If reverseVideo is
+.PN True ,
+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 resource 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, which then are 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 parents' 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
+with the top-level widget to execute the second and third phases.
+.PN XtRealizeWidget
+first recursively traverses the widget tree in a postorder (bottom-up)
+traversal and then notifies each composite widget with one
+or more managed children by means of its change_managed procedure.
+.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 preorder (top-down) traversal 
+of the widget tree, allocates an X window to each widget by means of 
+its realize procedure, and finally maps the widgets that are managed.
+
+.NH 3
+Creating and Merging Argument Lists
+.XS
+\fB\*(SN Creating and Merging Argument Lists\fP
+.XE
+.LP
+Many \*(xI functions may be passed pairs of resource names and
+values.
+These are passed as an arglist, a pointer to an array of
+.PN Arg
+structures, which contains
+.IN "ArgList" "" "@DEF@"
+.IN "Arg" "" "@DEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String name;
+	XtArgVal value;
+} Arg, *ArgList;
+.De
+.LP
+.eM
+where
+.PN XtArgVal
+is as defined in Section 1.5.
+.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 \fIvalue\fP;
+otherwise, a pointer to it is stored in \fIvalue\fP.
+.LP
+To set values in an
+.PN ArgList ,
+use
+.PN XtSetArg .
+.LP
+.IN "XtSetArg" "" "@DEF@"
+.sM
+.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 \fIname/value\fP 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 ,
+else the address.
+.LP
+.eM
+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 expressions with side effects such as
+auto-increment or auto-decrement
+within the first argument to
+.PN XtSetArg .
+.PN XtSetArg
+can be implemented as a macro that evaluates the first argument twice.
+.sp
+.LP
+To merge two
+arglist arrays, use
+.PN XtMergeArgLists .
+.LP
+.IN "XtMergeArgLists" "" "@DEF@"
+.sM
+.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 argument list.
+.IP \fInum_args1\fP 1i
+Specifies the number of entries in the first argument list.
+.IP \fIargs2\fP 1i
+Specifies the second argument list.
+.IP \fInum_args2\fP 1i
+Specifies the number of entries in the second argument list.
+.LP
+.eM
+The
+.PN XtMergeArgLists
+function allocates enough storage to hold the combined
+arglist arrays and copies them into it.
+Note that it does not check for duplicate entries.
+The length of the returned list is the sum of the lengths of the
+specified lists.
+When it is no longer needed,
+free the returned storage by using
+.PN XtFree .
+.sp
+.LP
+.IN "varargs" "" "@DEF@"
+All \*(xI interfaces that require
+.PN ArgList
+arguments have analogs
+conforming to the ANSI C variable argument list
+(traditionally called ``varargs'')
+calling convention.  The name of the analog is formed by prefixing
+``Va'' to the name of the corresponding
+.PN ArgList
+procedure; e.g.,
+.PN XtVaCreateWidget .
+Each procedure named \fBXtVa\fP\fIsomething\fP takes as its
+last arguments, in place of the corresponding
+.PN ArgList /
+.PN Cardinal
+parameters, a variable 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 \fIname\fP 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
+.PN 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@"
+.sM
+.Ds 0
+#define XtVaTypedArg "XtVaTypedArg"
+.De
+.LP
+.eM
+If the name
+.PN XtVaTypedArg
+is specified in place of a resource
+name, then the following four arguments are interpreted as a
+\fIname/type/value/size\fP tuple \fIwhere\fP name is of type
+.PN String ,
+\fItype\fP is of type
+.PN String ,
+\fIvalue\fP is of type
+.PN XtArgVal ,
+and \fIsize\fP 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 \fItype\fP is
+XtRString, then \fIvalue\fP contains a pointer to the string and \fIsize\fP
+contains the number of bytes allocated, including the trailing null
+byte.  If \fItype\fP is not XtRString, then \fIif\fP size is
+less than or equal to
+\fBsizeof\fP(\fBXtArgVal\fP), the value should be the data cast to the type
+.PN XtArgVal ,
+otherwise \fIvalue\fP 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@"
+.sM
+.Ds 0
+#define XtVaNestedList  "XtVaNestedList"
+.De
+.LP
+.eM
+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
+.sM
+.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 parameter list of resource
+name and value pairs.
+.LP
+.eM
+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 \fIname\fP entry containing NULL.  Any entries
+of type
+.PN XtVaTypedArg
+are copied as specified without applying
+conversions.  Data passed by reference (including Strings) are not
+copied, only the pointers themselves; the caller must ensure that the
+data remain valid for the lifetime of the created varargs list.  The
+list should be freed using
+.PN XtFree
+when no longer needed.
+.LP
+Use of resource files and of the resource database is generally
+encouraged over lengthy arglist or varargs lists whenever possible in
+order to permit modification without recompilation.
+
+.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 .
+.LP
+.IN "XtCreateWidget" "" "@DEF@"
+.sM
+.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 instance name for the created widget,
+which is used for retrieving resources
+and, for that reason, should not be the same as any other widget
+that is a child of the same parent.
+.IP \fIobject_class\fP 1i
+Specifies the widget class pointer for the created object.  \*(oC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(oI
+.IP \fIargs\fP 1i
+Specifies the argument list to override any other resource specifications.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtCreateWidget
+function performs all the boilerplate operations of widget
+creation, doing the following in order:
+.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's class is a subclass of
+.PN compositeWidgetClass
+and either no extension record in
+the parent's composite class part extension field exists with the
+\fIrecord_type\fP
+.PN \s-1NULLQUARK\s+1
+or the \fIaccepts_objects\fP field in the extension
+record is
+.PN False ,
+.PN XtCreateWidget
+issues a fatal error; see Section 3.1 and Chapter 12.
+.IP \(bu 5
+If the specified class contains an extension record in the object class
+part \fIextension\fP field with \fIrecord_type\fP
+.PN \s-1NULLQUARK\s+1
+and the \fIallocate\fP field is not NULL,
+the procedure is invoked to allocate memory
+for the widget instance.  If the parent is a member of the class
+.PN constraintWidgetClass ,
+the procedure also allocates memory for the
+parent's constraints and stores the address of this memory into the
+\fIconstraints\fP field.  If no allocate procedure is found, the \*(xI
+allocate memory for the widget and, when applicable, the constraints,
+and initializes the \fIconstraints\fP field.
+.IP \(bu 5
+Initializes the Core nonresource data fields
+\fIself\fP, \fIparent\fP, \fIwidget_class\fP, \fIbeing_destroyed\fP,
+\fIname\fP, \fImanaged\fP, \fIwindow\fP, \fIvisible\fP,
+\fIpopup_list\fP, and \fInum_popups\fP. 
+.IP \(bu 5
+Initializes the resource fields (for example, \fIbackground_pixel\fP)
+by using the
+.PN CoreClassPart
+resource lists specified for this class and all superclasses.
+.IP \(bu 5
+If the parent is a member of the class
+.PN constraintWidgetClass ,
+initializes the resource fields of the constraints record
+by using the
+.PN ConstraintClassPart
+resource lists specified for the parent's class
+and all superclasses up to
+.PN constraintWidgetClass .
+.IP \(bu 5
+Calls the initialize procedures for the widget starting at the 
+Object
+initialize procedure on down to the widget's initialize procedure.
+.IP \(bu 5
+If the parent is a member of the class
+.PN constraintWidgetClass ,
+calls the
+.PN ConstraintClassPart
+initialize procedures,
+starting at
+.PN constraintWidgetClass
+on down to the parent's
+.PN ConstraintClassPart
+initialize procedure.
+.IP \(bu 5
+If the parent is a member of the class
+.PN compositeWidgetClass ,
+puts the widget into its parent's children list by calling its parent's
+insert_child procedure.
+For further information,
+see Section 3.1.
+.sp
+.LP
+To create an instance of a widget using varargs lists, use
+.PN XtVaCreateWidget .
+.LP
+.IN "XtVaCreateWidget" "" "@DEF@"
+.sM
+.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 \fIobject_class\fP 1i
+Specifies the widget class pointer for the created object.  \*(oC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(oI
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+The
+.PN XtVaCreateWidget
+procedure is identical in function to
+.PN XtCreateWidget
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
+as described
+in Section 2.5.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, each of which
+specifies a unique widget tree
+that can potentially be on different screens or displays.
+An application uses 
+.PN XtAppCreateShell
+to create independent widget trees.
+.LP
+.IN "XtAppCreateShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtAppCreateShell(\fIname\fP, \
+\fIapplication_class\fP, \fIwidget_class\fP, \fIdisplay\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      String \fIname\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 \fIname\fP 1.25i
+Specifies the instance name of the shell widget.
+If \fIname\fP is NULL,
+the application name passed to
+.PN XtDisplayInitialize
+is used.
+.IP \fIapplication_class\fP 1.25i
+Specifies the resource class string to be used in
+place of the widget \fIclass_name\fP string when
+\fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof.
+.IP \fIwidget_class\fP 1.25i
+Specifies the widget class for the top-level widget (e.g.,
+.PN applicationShellWidgetClass ).
+.IP \fIdisplay\fP 1.25i
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+.IP \fIargs\fP 1.25i
+Specifies the argument list to override any other resource specifications.
+.IP \fInum_args\fP 1.25i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtAppCreateShell
+function
+creates a new shell widget instance as the root of a widget tree.
+The screen resource for this widget is determined by first scanning
+\fIargs\fP for the XtNscreen argument.  If no XtNscreen argument is
+found, the resource database associated with the default screen of
+the specified display is queried for the resource \fIname\fP.screen,
+class \fIClass\fP.Screen where \fIClass\fP is the specified
+\fIapplication_class\fP if \fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof.  If \fIwidget_class\fP is not
+.PN application\%Shell\%Widget\%Class
+or a subclass, \fIClass\fP is the \fIclass_name\fP
+field from the
+.PN CoreClassPart
+of the specified \fIwidget_class\fP.
+If this query fails, the default
+screen of the specified display is used.  Once the screen is determined,
+the resource database associated with that screen is used to retrieve
+all remaining resources for the shell widget not specified in
+\fIargs\fP.  The widget name and \fIClass\fP as determined above are
+used as the leftmost (i.e., root) components in all fully qualified
+resource names for objects within this widget tree.
+
+.LP
+If the specified widget class is a subclass of WMShell, the name and
+\fIClass\fP as determined above will be stored into the
+.PN \s-1WM_CLASS\s+1
+property on the widget's window when it becomes realized.
+If the specified \fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof, the
+.PN \s-1WM_COMMAND\s+1
+property will also be set from the values of the XtNargv and
+XtNargc resources.
+
+.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 .
+.LP
+.IN "XtVaAppCreateShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaAppCreateShell(\fIname\fP, \fIapplication_class\fP, \
+\fIwidget_class\fP, \fIdisplay\fP, ...)
+.br
+    String \fIname\fP;
+.br
+    String \fIapplication_class\fP;
+.br
+    WidgetClass \fIwidget_class\fP;
+.br
+    Display *\fIdisplay\fP;
+.FN
+.IP \fIname\fP 1.5i
+Specifies the instance name of the shell widget.
+If \fIname\fP is NULL,
+the application name passed to
+.PN XtDisplayInitialize
+is used.
+.IP \fIapplication_class\fP 1.5i
+Specifies the resource class string to be used in
+place of the widget \fIclass_name\fP string when
+\fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof.
+.IP \fIwidget_class\fP 1.5i
+Specifies the widget class for the top-level widget.
+.IP \fIdisplay\fP 1.5i
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+.IP ... 1.5i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+The
+.PN XtVaAppCreateShell
+procedure is identical in function to
+.PN XtAppCreateShell
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
+described in Section 2.5.1.
+
+.NH 3
+Convenience Procedure to Initialize an Application
+.XS
+\fB\*(SN Convenience Procedure to Initialize an Application\fP
+.XE
+.LP
+To initialize the \*(xI internals, create an application context,
+open and initialize a display, and create the initial root shell
+instance, an application may use
+.PN XtOpenApplication
+or
+.PN XtVaOpenApplication .
+.LP
+.IN "XtOpenApplication" "" "@DEF@"
+.sM
+.FD 0
+Widget XtOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                       \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, \fIwidget_class\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
+      int *\fIargc_in_out\fP;
+.br
+      String *\fIargv_in_out\fP;
+.br
+      String *\fIfallback_resources\fP;
+.br
+      WidgetClass \fIwidget_class\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 \fIoptions\fP.
+.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 \fIwidget_class\fP 1.5i
+Specifies the class of the widget to be created.  Must be shellWidgetClass
+or a subclass.
+.br
+.IP \fIargs\fP 1.5i
+Specifies the argument list to override any
+other resource specifications for the created shell widget.
+.IP \fInum_args\fP 1.5i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtOpenApplication
+function calls
+.PN XtToolkitInitialize
+followed by
+.PN XtCreateApplicationContext ,
+then calls
+.PN XtOpenDisplay
+with \fIdisplay_string\fP NULL and
+\fIapplication_name\fP NULL, and finally calls
+.PN XtAppCreateShell
+with \fIname\fP NULL, the specified \fIwidget_class\fP,
+an argument list and count,
+and returns the created shell.
+The recommended \fIwidget_class\fP is 
+.PN sessionShellWidgetClass .
+The argument list and count are created by merging
+the specified \fIargs\fP and \fInum_args\fP with a list 
+containing the specified \fIargc\fP and \fIargv\fP.
+The modified \fIargc\fP and \fIargv\fP returned by
+.PN XtDisplayInitialize
+are returned in \fIargc_in_out\fP and \fIargv_in_out\fP.  If
+\fIapp_context_return\fP 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 XtOpenApplication
+terminates the application.  If \fIfallback_resources\fP is non-NULL,
+.PN XtAppSetFallbackResources
+is called with the value prior to calling
+.PN XtOpenDisplay .
+.sp
+.LP
+.IN "XtVaOpenApplication" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                         \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, \fIwidget_class\fP, ...)
+.br
+    XtAppContext *\fIapp_context_return\fP;
+.br
+    String \fIapplication_class\fP;
+.br
+    XrmOptionDescList \fIoptions\fP;
+.br
+    Cardinal \fInum_options\fP;
+.br
+    int *\fIargc_in_out\fP;
+.br
+    String *\fIargv_in_out\fP;
+.br
+    String *\fIfallback_resources\fP;
+.br
+    WidgetClass \fIwidget_class\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 \fIoptions\fP.
+.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 \fIwidget_class\fP 1.5i
+Specifies the class of the widget to be created.  Must be shellWidgetClass
+or a subclass.
+.IP ... 1.5i
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+.LP
+.eM
+The
+.PN XtVaOpenApplication
+procedure is identical in function to
+.PN XtOpenApplication
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+
+.NH 3
+Widget Instance Allocation: The allocate Procedure
+.XS
+\*(SN Widget Instance Allocation: The allocate Procedure
+.XE
+.IN "Widget Allocation"
+.LP
+A widget class may optionally provide an instance allocation procedure
+in the
+.PN ObjectClassExtension
+record.
+.LP
+When the call to create a widget includes a varargs list containing
+.PN XtVaTypedArg ,
+these arguments will be passed to the allocation procedure in an
+.PN XtTypedArgList .
+.LP
+.IN "XtTypedArgList" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String name;
+	String type;
+	XtArgVal value;
+	int size;
+} XtTypedArg, *XtTypedArgList;
+.De
+.LP
+.eM
+.IN "allocate procedure" "" "@DEF@"
+The allocate procedure pointer in the
+.PN ObjectClassExtension
+record is of type
+.PN XtAllocateProc .
+.LP
+.IN "XtAllocateProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, \
+Cardinal*,
+                                            XtTypedArgList, Cardinal*, \
+Widget*, XtPointer*);
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Cardinal* \fIconstraint_size\fP;
+.br
+      Cardinal* \fImore_bytes\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal* \fInum_args\fP;
+.br
+      XtTypedArgList \fItyped_args\fP,
+.br
+      Cardinal* \fInum_typed_args\fP;
+.br
+      Widget* \fInew_return\fP;
+.br
+      XtPointer* \fImore_bytes_return\fP;
+.FN
+.IP \fIwidget_class\fP 1.5i
+Specifies the widget class of the instance to allocate.
+.IP \fIconstraint_size\fP 1.5i
+Specifies the size of the constraint record to allocate, or 0.
+.IP \fImore_bytes\fP 1.5i
+Specifies the number of auxiliary bytes of memory to allocate.
+.IP \fIargs\fP 1.5i
+Specifies the argument list as given in the call to create the widget.
+.IP \fInum_args\fP 1.5i
+Specifies the number of arguments.
+.IP \fItyped_args\fP 1.5i
+Specifies the list of typed arguments given in the call to create the widget.
+.IP \fInum_typed_args\fP 1.5i
+Specifies the number of typed arguments.
+.IP \fInew_return\fP 1.5i
+Returns a pointer to the newly allocated instance, or NULL in case of error.
+.IP \fImore_bytes_return\fP 1.5i
+Returns the auxiliary memory if it was requested, or NULL
+if requested and an error occurred; otherwise, unchanged.
+.LP
+.eM
+At widget allocation time, if an extension record with \fIrecord_type\fP
+equal to 
+.PN \s-1NULLQUARK\s+1
+is located through the object class part \fIextension\fP field
+and the \fIallocate\fP field is not NULL, the 
+.PN XtAllocateProc
+will be invoked to allocate memory for the widget.  If no ObjectClassPart
+extension record is declared with \fIrecord_type equal\fP to
+.PN \s-1NULLQUARK\s+1 ,
+then
+.PN XtInheritAllocate
+and 
+.PN XtInheritDeallocate
+are assumed.
+If no
+.PN XtAllocateProc
+is found, the \*(xI will allocate memory for the widget.
+.LP
+An 
+.PN XtAllocateProc
+must perform the following:
+.IP \(bu 5
+Allocate memory for the widget instance and return it in \fInew_return\fP.
+The memory must be at least \fIwc->core_class.widget_size\fP bytes in length,
+double-word aligned.
+.IP \(bu 5
+Initialize the \fIcore.constraints\fP field in the instance record to NULL
+or to point to a constraint record.  If \fIconstraint_size\fP
+is not 0, the procedure must allocate memory for the constraint record.
+The memory must be double-word aligned.
+.IP \(bu 5
+If \fImore_bytes\fP is not 0, then the address of a block of memory
+at least \fImore_bytes\fP in size, double-word aligned, must be
+returned in the \fImore_bytes_return\fP parameter,
+or NULL to indicate an error.
+.LP
+A class allocation procedure that envelops the allocation procedure of a
+superclass must rely on the enveloped procedure to perform the instance
+and constraint allocation.
+Allocation procedures should refrain from initializing fields in the
+widget record except to store pointers to newly allocated additional memory.
+Under no circumstances should an allocation procedure that envelopes
+its superclass allocation procedure modify fields in the
+instance part of any superclass.
+
+.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 .
+.LP
+.IN "XtInitProc" "" "@DEF@"
+.IN "initialize procedure" "" "@DEF@"
+.sM
+.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 a copy of the widget with resource values as requested by the
+argument list, the resource database, and the widget defaults.
+.IP \fInew\fP 1i
+Specifies the 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.
+If the client created the widget using a varargs form, any resources
+specified via
+.PN XtVaTypedArg
+are converted to the widget representation and the list is transformed
+into the
+.PN ArgList
+format.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+An initialization procedure performs the following:
+.IP \(bu 5
+Allocates space for and copies any resources referenced by address
+that the client is allowed to free or modify
+after the widget has been created.
+For example,
+if a widget has a field that is a 
+.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 so state in their user documentation.
+.NT
+It is not necessary to allocate space for or to copy callback lists.
+.NE
+.IP \(bu 5
+Computes values for unspecified resource fields.
+For example, if \fIwidth\fP and \fIheight\fP are zero,
+the widget should compute an appropriate width and height 
+based on its other resources.
+.NT
+A widget may directly assign only
+its own \fIwidth\fP and \fIheight\fP within the initialize, initialize_hook,
+set_values, and
+set_values_hook procedures; see Chapter 6.
+.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 colormap for a depth
+that does not support that colormap.
+.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
+\fIargs\fP and \fInum_args\fP
+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 \fIinitialize\fP 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 often are
+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 \fIrequest\fP and \fInew\fP arguments provide the necessary information for
+a subclass to determine the difference between an explicitly specified field
+and a field computed by a superclass.
+The \fIrequest\fP widget is a copy of the widget as initialized by the
+arglist and resource database.
+The \fInew\fP 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 \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero.
+If so,
+it adds its surround size to the \fIwidth\fP and \fIheight\fP
+fields in the \fInew\fP widget.
+If not, it must make do with the size originally specified.
+.LP
+The \fInew\fP widget will become the actual widget instance record.
+Therefore,
+the initialization procedure should do all its work on the \fInew\fP widget;
+the \fIrequest\fP widget should never be modified.
+If the initialize procedure
+needs to call any routines that operate on a widget,
+it should specify \fInew\fP as the widget instance.
+
+.NH 3
+Constraint Instance Initialization: The ConstraintClassPart initialize Procedure
+.XS
+\*(SN Constraint Instance Initialization: The ConstraintClassPart initialize Procedure
+.XE
+.IN "Initialization"
+.IN "XtInitProc"
+.IN "initialize procedure"
+.IN "Chaining"
+.IN "Superclass Chaining"
+.IN "Inheritance"
+.LP
+The constraint initialization procedure pointer, found in the
+.PN ConstraintClassPart
+\fIinitialize\fP field of the widget class record, is of type
+.PN XtInitProc .
+The values passed to the parent constraint initialization procedures
+are the same as those passed to the child's class widget initialization
+procedures.
+.LP
+The \fIconstraints\fP field of the \fIrequest\fP widget points to a copy of the
+constraints record as initialized by the arglist and resource database.
+.LP
+The constraint initialization procedure should compute any constraint fields
+derived from constraint resources.
+It can make further changes to the \fInew\fP widget to make the widget
+and any other constraint fields
+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 \fIinitialize\fP 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 that used it in previous releases.
+.NE
+.LP
+The initialize_hook procedure pointer is of type
+.PN XtArgsProc :
+.LP
+.IN "initialize_hook procedure" "" "@DEF@"
+.IN "XtArgsProc" "" "@DEF@"
+.sM
+.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 passed by the client.
+If the client created the widget using a varargs form, any resources
+specified via
+.PN XtVaTypedArg
+are converted to the widget representation and the list is transformed
+into the
+.PN ArgList
+format.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+If this procedure is not NULL,
+it is called immediately after the corresponding initialize
+procedure or in its place if the \fIinitialize\fP field is NULL.
+.LP
+The initialize_hook procedure allows a widget instance to initialize
+nonresource data using information from the specified argument list
+as if it were a resource.
+
+.NH 2
+Realizing Widgets
+.XS
+\fB\*(SN Realizing Widgets\fP
+.XE
+.LP
+To realize a widget instance, use
+.PN XtRealizeWidget .
+.LP
+.IN "XtRealizeWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtRealizeWidget(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.eM
+.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 postorder traversal of the widget tree rooted
+at the specified widget and calls each non-NULL change_managed procedure
+of all composite widgets that have one or more managed children.
+.IP \(bu 5
+Constructs an
+.PN XSetWindowAttributes
+structure filled in with information derived from the 
+Core 
+widget fields and calls the realize procedure for the widget,
+which adds any widget-specific attributes and creates the X window.
+.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 \fImapped_when_managed\fP 
+.PN True .
+If a widget is managed but \fImapped_when_managed\fP is 
+.PN False , 
+the widget is allocated visual space but is not displayed.
+.RE
+.LP
+If the widget is a top-level shell widget (that is, it has no parent), and
+\fImapped_when_managed\fP is 
+.PN True , 
+.PN XtRealizeWidget
+maps the widget window.
+.LP
+.PN XtCreateWidget ,
+.PN XtVaCreateWidget ,
+.PN XtRealizeWidget ,
+.PN XtManageChildren ,
+.PN XtUnmanage\%Children ,
+.PN XtUnrealizeWidget ,
+.PN XtSetMappedWhenManaged ,
+and
+.PN XtDestroy\%Widget
+maintain the following invariants:
+.IP \(bu 5
+If a composite widget is realized, then all its managed children are realized.
+.IP \(bu 5
+If a composite widget is realized, then all its managed children that have
+\fImapped_when_managed\fP
+.PN True
+are mapped.
+.LP
+All \*(xI functions and all widget routines should accept
+either realized or unrealized widgets.
+When calling the realize or change_managed
+procedures for children of a composite
+widget,
+.PN XtRealizeWidget
+calls the procedures in reverse order of
+appearance in the
+.PN CompositePart
+\fIchildren\fP list.  By default, this
+ordering of the realize procedures will
+result in the stacking order of any newly created subwindows being
+top-to-bottom in the order of appearance on the list, and the most
+recently created child will be at the bottom.
+.sp
+.LP
+To check whether or not a widget has been realized, use
+.PN XtIsRealized .
+.LP
+.IN "XtIsRealized" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtIsRealized(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+The
+.PN XtIsRealized
+function returns 
+.PN True 
+if the widget has been realized,
+that is, if the widget has a nonzero window ID.
+If the specified object is not a widget, the state of the nearest
+widget ancestor is returned.
+.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 .
+.LP
+.IN "XtRealizeProc" "" "@DEF@"
+.sM
+.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 \fIattributes\fP structure are used.
+.IP \fIattributes\fP 1i
+Specifies the window attributes to use in the
+.PN XCreateWindow
+call.
+.LP
+.eM
+The realize procedure must create the widget's window.
+.LP
+Before calling the class realize procedure, the generic
+.PN XtRealizeWidget
+function fills in a mask and a corresponding
+.PN XSetWindowAttributes
+structure.
+It sets the following fields in \fIattributes\fP and
+corresponding bits in \fIvalue_mask\fP
+based on information in the widget
+core
+structure:
+.IP \(bu 5
+The \fIbackground_pixmap\fP (or \fIbackground_pixel\fP if \fIbackground_pixmap\fP is
+.PN XtUnspecifiedPixmap )
+is filled in from the corresponding field.
+.IP \(bu 5
+The \fIborder_pixmap\fP (or \fIborder_pixel\fP if \fIborder_pixmap\fP is
+.PN XtUnspecifiedPixmap )
+is filled in from the corresponding field.
+.IP \(bu 5
+The \fIcolormap\fP is filled in from the corresponding field.
+.IP \(bu 5
+The \fIevent_mask\fP is filled in based on the event handlers registered,
+the event translations specified, whether the \fIexpose\fP field is non-NULL,
+and whether \fIvisible_interest\fP is 
+.PN True .
+.IP \(bu 5
+The \fIbit_gravity\fP is set to
+.PN NorthWestGravity
+if the \fIexpose\fP field is NULL.
+.LP
+These or any other fields in attributes and the corresponding bits in
+\fIvalue_mask\fP 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 
+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 coreWidgetClass 
+calls
+.PN XtCreateWindow
+with the passed \fIvalue_mask\fP and \fIattributes\fP
+and with \fIwindow_class\fP and \fIvisual\fP 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.10).
+.LP
+The most common noninherited realize procedures set \fIbit_gravity\fP in the mask
+and attributes to the appropriate value and then create the window.
+For example, depending on its justification, Label might set \fIbit_gravity\fP to
+.PN WestGravity ,
+.PN CenterGravity ,
+or
+.PN EastGravity .
+Consequently, shrinking it would just move the bits appropriately,
+and no
+exposure
+event is needed for repainting.
+.LP
+If a composite widget's children should be realized in an order other
+than that specified
+(to control the stacking order, for example),
+it should call
+.PN XtRealizeWidget
+on its children itself in the appropriate order from within its own
+realize procedure.
+.LP
+Widgets that have children and whose class is not a subclass of
+.PN compositeWidgetClass
+are responsible for calling
+.PN XtRealizeWidget
+on their children, usually from within the realize procedure.
+.LP
+Realize procedures cannot manage or unmanage their descendants.
+
+.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 normally call the \*(xI analog
+.PN XtCreateWindow ,
+which simplifies the creation of windows for widgets.
+.LP
+.IN "XtCreateWindow" "" "@DEF@"
+.sM
+.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
+.IP \fIw\fP 1i
+Specifies the widget that defines the additional window attributed.  \*(cI
+.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 fields in the \fIattributes\fP structure are used.
+.IP \fIattributes\fP 1i
+Specifies the window attributes to use in the
+.PN XCreateWindow
+call.
+.LP
+.eM
+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 \fIwindow\fP field.
+.LP
+.PN XtCreateWindow
+evaluates the following fields of the widget core
+structure: \fIdepth\fP, \fIscreen\fP, \fIparent->core.window\fP, \fIx\fP,
+\fIy\fP, \fIwidth\fP, \fIheight\fP, and
+\fIborder_width\fP.
+
+.NH 2
+Obtaining Window Information from a Widget
+.XS
+\fB\*(SN Obtaining Window Information from a Widget\fP
+.XE
+.LP
+The 
+Core
+widget class definition contains the screen and window ids.
+The \fIwindow\fP field may be NULL for a while
+(see Sections 2.5 and 2.6).
+.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.
+.LP
+.IN "XtDisplay" "" "@DEF@"
+.sM
+.FD 0
+Display *XtDisplay(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+.PN XtDisplay
+returns the display pointer for the specified widget.
+.sp
+.LP
+.IN "XtParent" "" "@DEF@"
+.sM
+.FD 0
+Widget XtParent(\fIw\fP)
+.br
+     Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+.PN XtParent
+returns the parent object for the specified widget. The returned object
+will be of class Object or a subclass.
+.sp
+.LP
+.IN "XtScreen" "" "@DEF@"
+.sM
+.FD 0
+Screen *XtScreen(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+.PN XtScreen
+returns the screen pointer for the specified widget.
+.sp
+.LP
+.IN "XtWindow" "" "@DEF@"
+.sM
+.FD 0
+Window XtWindow(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+.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 nonwidget object are available
+by means of
+.PN XtDisplayOfObject ,
+.PN XtScreenOfObject ,
+and
+.PN XtWindowOfObject .
+.IN "XtDisplayOfObject" "" "@DEF@"
+.sp
+.LP
+.sM
+.FD 0
+Display *XtDisplayOfObject(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+.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 \fIobject\fP that is of class
+Widget or a subclass thereof.
+.LP
+.IN "XtScreenOfObject" "" "@DEF@"
+.sM
+.FD 0
+Screen *XtScreenOfObject(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+.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 \fIobject\fP that is of class
+Widget or a subclass thereof.
+.LP
+.IN "XtWindowOfObject" "" "@DEF@"
+.sM
+.FD 0
+Window XtWindowOfObject(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+.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 \fIobject\fP that is of class
+Widget or a subclass thereof.
+.sp
+.LP
+To retrieve the instance name of an object, use
+.PN XtName .
+.LP
+.IN "XtName" "" "@DEF@"
+.sM
+.FD 0
+String XtName(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object whose name is desired.  \*(oI
+.LP
+.eM
+.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 instance.
+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, \fIdepth\fP for deriving pixmaps,
+\fIbackground_pixel\fP for deriving GCs, and so on) or in the
+.PN XtCreateWindow
+call.
+.LP
+The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
+window attributes are available to
+geometry managers.
+These fields are maintained synchronously inside the \*(xI.
+When an
+.PN XConfigureWindow
+is issued by the \*(xI on the widget's window (on request of its parent),
+these values are updated immediately rather than some time later
+when the server generates a
+.PN ConfigureNotify
+event.
+(In fact, most widgets do not select
+.PN SubstructureNotify
+events.)
+This ensures that all geometry calculations are based on the internally
+consistent toolkit world rather than on either
+an inconsistent world updated by asynchronous
+.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
+non-pop-up descendants, use
+.PN XtUnrealizeWidget .
+.LP
+.IN "XtUnrealizeWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtUnrealizeWidget(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+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 postorder (child-to-parent) traversal of the widget tree
+rooted at the specified widget and, for each widget that has
+declared a callback list resource named ``unrealizeCallback'', executes the
+procedures on the
+.IN XtNunrealizeCallback
+XtNunrealizeCallback
+list.
+.IN "unrealizeCallback" "" "@DEF@"
+.IP \(bu 5
+Destroys the widget's window and any subwindows by calling
+.PN XDestroyWindow
+with the specified widget's \fIwindow\fP field.
+.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
+.IP \(bu 5
+To destroy all the pop-up children of the widget being destroyed
+and destroy all children of composite widgets.
+.IP \(bu 5
+To remove (and unmap) the widget from its parent.
+.IP \(bu 5
+To call the callback procedures that have been registered to trigger 
+when the widget is destroyed.
+.IP \(bu 5
+To minimize the number of things a widget has to deallocate when destroyed.
+.IP \(bu 5
+To minimize the number of
+.PN XDestroyWindow
+calls when destroying a widget tree.
+.sp
+.LP
+To destroy a widget instance, use
+.PN XtDestroyWidget .
+.LP
+.IN "XtDestroyWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtDestroyWidget(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+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 1,
+.PN XtDestroyWidget
+performs the following:
+.IP \(bu 5
+If the \fIbeing_destroyed\fP field of the widget is 
+.PN True ,
+it returns immediately.
+.IP \(bu 5
+Recursively descends the widget tree and
+sets the \fIbeing_destroyed\fP field to 
+.PN True 
+for the widget and all normal and pop-up 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,
+either normal or pop-up, of w1.
+.LP
+Phase 2 occurs when all procedures that should execute as a result of
+the current event have been called, including all procedures registered with
+the event and translation managers,
+that is, when the current invocation of
+.PN XtDispatchEvent
+is about to return, or immediately if not in
+.PN XtDispatchEvent .
+.LP
+In phase 2,
+.PN XtDestroyWidget
+performs the following on each entry in the destroy list in the order
+specified:
+.IP \(bu 5
+If the widget is not a pop-up child and the widget's parent is a subclass of 
+.PN composite\%WidgetClass ,
+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
+Calls the destroy callback procedures registered on the widget 
+and all normal and pop-up descendants in postorder (it calls child
+callbacks before parent callbacks).
+.LP
+The 
+.PN XtDestroyWidget
+function then makes second traversal of the widget and all normal
+and pop-up descendants to perform the following three items on each
+widget in postorder:
+.IP \(bu 5
+If the widget is not a pop-up child and the widget's parent is a subclass of
+.PN constraint\%WidgetClass ,
+it calls the
+.PN ConstraintClassPart
+destroy procedure for the parent,
+then for the parent's superclass,
+until finally it calls the
+.PN ConstraintClassPart
+destroy procedure for
+.PN constraintWidgetClass .
+.IP \(bu 5
+Calls the
+.PN CoreClassPart
+destroy procedure declared in the widget class,
+then the destroy procedure declared in its superclass,
+until finally it calls the destroy procedure declared in the Object
+class record.  Callback lists are deallocated.
+.IP \(bu 5
+If the widget class object class part contains an 
+.PN ObjectClassExtension
+record with the record_type
+.PN \s-1NULLQUARK\s+1
+and the \fIdeallocate\fP field is not NULL,
+calls the deallocate procedure to deallocate the instance and if one
+exists, the constraint record.  Otherwise, the \*(xI will deallocate
+the widget instance record and if one exists, the constraint record.
+.IP \(bu 5
+Calls
+.PN XDestroyWindow
+if the specified widget is realized (that is, has an X window).
+The server recursively destroys all normal descendant windows.
+(Windows of realized pop-up Shell children, and their
+descendants, are destroyed by a shell class destroy procedure.)
+
+.NH 3
+Adding and Removing Destroy Callbacks
+.XS
+\fB\*(SN Adding and Removing Destroy Callbacks\fP
+.XE
+.LP
+When an application needs to perform additional processing during the
+destruction of a widget,
+it should register a destroy callback procedure for the widget.
+The destroy callback procedures use the mechanism described in 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"
+.Ds
+XtAddCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
+.De
+.LP
+Similarly, the following removes the application-supplied destroy callback
+procedure \fIClientDestroy\fP by calling
+.PN XtRemoveCallback .
+.IN "XtRemoveCallback"
+.Ds
+XtRemoveCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
+.De
+.LP
+The \fIClientDestroy\fP argument is of type
+.PN XtCallbackProc ;
+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 pointers in the
+.PN ObjectClassPart ,
+.PN RectObjClassPart ,
+and
+.PN CoreClassPart
+structures are of type
+.PN XtWidgetProc .
+.LP
+.IN "XtWidgetProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtWidgetProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget being destroyed.
+.LP
+.eM
+The destroy procedures are called in subclass-to-superclass order.
+Therefore, a widget's destroy procedure should deallocate only storage
+that is specific to the subclass and should ignore the storage
+allocated by any of its superclasses.
+The destroy procedure should deallocate only resources that have been
+explicitly created by the subclass.
+Any resource that was obtained from the resource database 
+or passed in an argument list was not created by the widget
+and therefore should not be destroyed by it.
+If a widget does not need to deallocate any storage,
+the destroy procedure entry in its class record can be NULL.
+.LP
+Deallocating storage includes, but is not limited to,
+the following steps:
+.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 XtReleaseGC
+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 to other widgets.
+.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 .
+.LP
+During destroy phase 2 for each widget, the \*(xI remove the widget
+from the modal cascade, unregister all event handlers, remove all key,
+keyboard, button, and pointer grabs and remove all callback procedures
+registered on the widget.  Any outstanding selection transfers will time out.
+
+.NH 3
+Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure
+.XS
+\*(SN Dynamic Constraint Data Deallocation: The ConstraintClassPart 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 class of the widget's parent and ending at
+.PN constraint\%WidgetClass .
+Therefore, a parent's constraint destroy procedure should deallocate only
+storage that is specific to the constraint subclass
+and not storage allocated by any of its superclasses.
+.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 3
+Widget Instance Deallocation: The deallocate Procedure
+.XS
+\*(SN Widget Instance Deallocation: The deallocate Procedure
+.XE
+.LP
+.IN "deallocate procedure" "" "@DEF@"
+The deallocate procedure pointer in the
+.PN ObjectClassExtension
+record is of type
+.PN XtDeallocateProc .
+.LP
+.IN "XtDeallocateProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtDeallocateProc)(Widget, XtPointer);
+.br
+      Widget \fIwidget\fP;
+.br
+      XtPointer \fImore_bytes\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget being destroyed.
+.IP \fImore_bytes\fP 1i
+Specifies the auxiliary memory received from the corresponding allocator
+along with the widget, or NULL.
+.LP
+.eM
+When a widget is destroyed, if an
+.PN ObjectClassExtension
+record exists in the object class part \fIextension\fP field
+with \fIrecord_type\fP
+.PN \s-1NULLQUARK\s+1
+and the \fIdeallocate\fP field is not NULL, the
+.PN XtDeallocateProc
+will be called.
+If no ObjectClassPart extension record is declared with \fIrecord_type\fP
+equal to 
+.PN \s-1NULLQUARK\s+1 ,
+then 
+.PN XtInheritAllocate
+and 
+.PN XtInheritDeallocate
+are assumed.
+The responsibilities of the deallocate procedure are to deallocate the
+memory specified by \fImore_bytes\fP if it is not NULL,
+to deallocate the constraints record as specified by the
+widget's \fIcore.constraints\fP field if it is
+not NULL, and to deallocate the widget instance itself.
+.LP
+If no
+.PN XtDeallocateProc
+is found, it is assumed that the \*(xI
+originally allocated the memory and is responsible for freeing it.
+
+.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 \*(xI have no resources beyond those in the program image,
+and the X server will free its resources when its connection
+to the application is broken.
+.LP
+Depending upon the widget set in use, it may be necessary to explicitly
+destroy individual widgets or widget trees with
+.PN XtDestroyWidget
+before calling
+.PN XtDestroyApplicationContext
+in order to ensure that any
+required widget cleanup is properly executed.  The application developer
+must refer to the widget documentation to learn if a widget needs to
+perform cleanup beyond that performed automatically by the
+operating system.  If the client is a session participant
+(see Section 4.2), then the client may wish to resign from the session
+before exiting.  See Section 4.2.4 for details.
+.bp