Updated following packages:

bigreqsproto-1.1.2
fontsproto-2.1.2
recordproto-1.14.2
scrnsaverproto-1.2.2
xcmiscproto-1.2.2
libXt-1.1.3
xhost-1.0.5
kbproto-1.0.6
libXrender-0.9.7
libxkbfile-1.0.8
freetype-2.4.9
libXaw-1.0.10
libXpm-3.5.10
xproto-7.0.23

1 files changed, 0 insertions, 3165 deletions

diff --git a/libXt/specs/CH02 b/libXt/specs/CH02
deleted file mode 100644
index cbb4bb8a5..000000000
--- a/libXt/specs/CH02
+++ /dev/null
@@ -1,3165 +0,0 @@
-.\" $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