svn merge ^/branches/released .

1 files changed, 0 insertions, 1103 deletions

diff --git a/libXaw/spec/CH2 b/libXaw/spec/CH2
deleted file mode 100644
index 9e6c17a8a..000000000
--- a/libXaw/spec/CH2
+++ /dev/null
@@ -1,1103 +0,0 @@
-.\" $Xorg: CH2,v 1.3 2000/08/17 19:42:26 cpqbld Exp $
-.bp
-\&
-.sp 1
-.ce 3
-\s+1\fBChapter 2\fP\s-1
-
-\s+1\fBUsing Widgets\fP\s-1
-.sp 2
-.nr H1 2
-.nr H2 0
-.nr H3 0
-.nr H4 0
-.nr H5 0
-.LP
-.XS
-Chapter 2 \- Using Widgets
-.XE
-.IN "using widgets" "" "@DEF@"
-Widgets serve as the primary tools for building a user interface or
-application environment.  The Athena widget set consists of primitive
-widgets that contain no children (for example, a command button) and
-composite widgets which may contain one or more widget children (for
-example, a Box widget).
-.LP
-The remaining chapters explain the widgets that are provided
-by the Athena widget set.
-These user-interface components serve as an interface for
-application programmers who do not want to implement their own widgets.
-In addition, they serve as a starting point
-for those widget programmers who, using the \*(xI mechanisms,
-want to implement alternative application programming interfaces.
-.LP
-This chapter is a brief introduction to widget programming.  The
-examples provided use the Athena widgets, though most of the concepts
-will apply to all widget sets.  Although there are several programming
-interfaces to the \*(tk, only one is described here.  A full
-description of the programming interface is provided in the document
-\fI\*(xT\fP.
-.NH 2
-Setting the Locale
-.LP
-.XS
-	Setting the Locale
-.XE
-If it is desirable that the application take advantage of
-internationalization (i18n), you must establish locale with
-.PN XtSetLanguageProc
-before \fBXtDisplayInitialize\fP or \fBXtAppInitialize\fP
-is called.  For full details, please refer to the document
-\fI\*(xT\fP, section 2.2. However, the following simplest-case
-call is sufficient in many or most applications.
-.LP
-.IN "internationalization" "" ""
-.IN "XtSetLanguageProc" "" "@DEF@"
-.IN "locale" "" ""
-.Ds
-.TA .5i 2i
-.ta .5i 2i
-	XtSetLanguageProc(NULL, NULL, NULL);
-.De
-.LP
-Most notably, this will affect the Standard C locale, determine which
-resource files will be loaded, and what fonts will be required of FontSet
-specifications.  In many cases, the addition of this line is the only source change
-required to internationalize Xaw programs, and will not disturb the function
-of programs in the default "C" locale.
-.NH 2
-Initializing the Toolkit
-.LP
-.XS
-	Initializing the Toolkit
-.XE
-You must call a toolkit initialization function before invoking any
-other toolkit routines (besides locale setting, above).
-.PN XtAppInitialize
-opens the X server connection, parses the command line,
-and creates an initial widget that will serve as the root of
-a tree of widgets created by this application.
-.IN "initialization" "" "@DEF@"
-.IN "toolkit initialization" "" "@DEF@"
-.IN "XtAppInitialize" "" "@DEF@"
-.IN "fallback resources" "" "@DEF@"
-.FD 0
-Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
-\fIoptions\fP, \fInum_options\fP,
-.ta 2i
-	\fIargc_in_out\fP, \fIargv_in_out\fP, \fIfallback_resources\fP, \
-\fIargs\fP, \fInum_args\fP)
-.br
-      XtAppContext *\fIapp_context_return\fP;
-.br
-      String \fIapplication_class\fP;
-.br
-      XrmOptionDescRec \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
-      ArgList \fIargs\fP;
-.br
-      Cardinal \fInum_args\fP;
-.FN
-.IP \fIapp_con_return\fP 1.5i
-Returns the application context of this application, if non-NULL.
-.IP \fIapplication_class\fP 1.5i
-Specifies the class name of this application,
-which is usually the generic name for all instances of this application.
-A useful convention is to form the class name by capitalizing the
-first letter of the application name. For example, the application named
-``xman'' has a class name of ``Xman''.
-.IP \fIoptions\fP 1.5i
-Specifies how to parse the command line for any application-specific
-resources.
-The options argument is passed as a parameter to
-.PN XrmParseCommand .
-For further information,
-see \fI\*(xL\fP.
-.IP \fInum_options\fP 1.5i
-Specifies the number of entries in the options list.
-.IP \fIargc_in_out\fP 1.5i
-Specifies a pointer to the number of command line parameters.
-.IP \fIargv_in_out\fP 1.5i
-Specifies the command line parameters.
-.IP \fIfallback_resources\fP 1.5i
-Specifies resource values to be used if the site-wide application class
-defaults file cannot be opened, or NULL.
-.IP \fIargs\fP 1.5i
-Specifies the argument list to use when creating the Application shell.
-.IP \fInum_args\fP 1.5i
-Specifies the number of arguments in \fIargs\fP.
-.LP
-This function will remove the command line arguments that the toolkit
-reads from \fIargc_in_out\fP, and \fIargv_in_out\fP.  It will then
-attempt to open the display.  If the display cannot be opened, an error
-message is issued and XtAppInitialize terminates the application.  Once
-the display is opened, all resources are read from the locations
-specified by the \*(xI.  This function returns an ApplicationShell
-widget to be used as the root of the application's widget tree.
-.NH 2
-Creating a Widget
-.LP
-.XS
-	Creating a Widget
-.XE
-.IN "widget creation" "" "@DEF@"
-.IN "creating widgets" "" "@DEF@"
-.IN "XtRealizeWidget" "" ""
-Creating a widget is a three-step process.  First, the widget instance
-is allocated, and various instance-specific attributes are set by
-using \fBXtCreateWidget\fP.  Second, the widget's parent is informed
-of the new child by using \fBXtManageChild\fP.  Finally, X windows are
-created for the parent and all its children by using \fBXtRealizeWidget\fP
-and specifying the top-most widget. The first two steps can be
-combined by using \fBXtCreateManagedWidget\fP.  In addition,
-\fBXtRealizeWidget\fP is automatically called when the child becomes
-managed if the parent is already realized.
-.LP
-To allocate, initialize, and manage a widget, use
-.PN XtCreateManagedWidget .
-.IN "XtCreateManagedWidget" "" "@DEF@"
-.FD 0
-Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
-\fIargs\fP, \fInum_args\fP)
-.br
-      String \fIname\fP;
-.br
-      WidgetClass \fIwidget_class\fP;
-.br
-      Widget \fIparent\fP;
-.br
-      ArgList \fIargs\fP;
-.br
-      Cardinal \fInum_args\fP;
-.FN
-.IP \fIname\fP 1i
-Specifies the instance name for the created widget that is used for retrieving
-widget resources.
-.IP \fIwidget_class\fP 1i
-Specifies the widget class pointer for the created widget.
-.IP \fIparent\fP 1i
-Specifies the parent widget ID.
-.IP \fIargs\fP 1i
-Specifies the argument list.  The argument list is a variable-length
-list composed of name and value pairs that contain information
-pertaining to the specific widget instance being created.  For further
-information, see Section 2.7.2.
-.IP \fInum_args\fP 1i
-Specifies the number of arguments in the argument list.
-If the num_args is zero, the argument list is never referenced.
-.LP
-When a widget instance is successfully created, the widget identifier
-is returned to the application.  If an error is encountered, the
-.PN XtError
-routine is invoked to inform the user of the error.
-.IN "XtError" "" ""
-.LP
-For further information, see \fI\*(xT\fP.
-.NH 2
-Common Resources
-.XS
-	Common Resources
-.XE
-.IN "resource" ""
-.LP
-Although a widget can have unique arguments that it understands, all
-widgets have common arguments that provide some regularity of operation.
-The common arguments allow arbitrary widgets to be managed by
-higher-level components without regard for the individual widget type.
-Widgets will ignore any argument that they do not understand.
-.LP
-The following resources are retrieved from the argument list
-or from the resource database by all of the Athena widgets:
-.TS H
-lw(1.5i) lw(1i) lw(1i) lw(2i).
-_
-.sp 3p
-.TB
-Name	Class	Type	Default Value
-.sp 3p
-_
-.TH
-.R
-.sp 3p
-accelerators	Accelerators	AcceleratorTable	NULL
-ancestorSensitive	AncestorSensitive	Boolean	True
-background	Background	Pixel	XtDefaultBackground
-backgroundPixmap	Pixmap	Pixmap	XtUnspecifiedPixmap
-borderColor	BorderColor	Pixel	XtDefaultForeground
-borderPixmap	Pixmap	Pixmap	XtUnspecifiedPixmap
-borderWidth	BorderWidth	Dimension	1
-colormap	Colormap	Colormap	Parent's Colormap
-depth	Depth	int	Parent's Depth
-destroyCallback	Callback	XtCallbackList	NULL
-height	Height	Dimension	\fIwidget dependent\fP
-mappedWhenManaged	MappedWhenManaged	Boolean	True
-screen	Screen	Screen	Parent's Screen
-sensitive	Sensitive	Boolean	True
-translations	Translations	TranslationTable	\fIwidget dependent\fP
-width	Width	Dimension	\fIwidget dependent\fP
-x	Position	Position	0
-y	Position	Position	0
-.sp 3p
-_
-.TE
-.IN "XtDefaultForeground" "" ""
-.IN "XtDefaultBackground" "" ""
-.LP
-The following additional resources are retrieved from the argument list
-or from the resource database by many of the Athena widgets:
-.TS H
-lw(1.5i) lw(1i) lw(1i) lw(2i).
-_
-.sp 3p
-.TB
-Name	Class	Type	Default Value
-.sp 3p
-_
-.TH
-.R
-.sp 3p
-callback	Callback	XtCallbackList	NULL
-cursor	Cursor	Cursor	\fIwidget dependent\fP
-foreground	Foreground	Pixel	XtDefaultForeground
-insensitiveBorder	Insensitive	Pixmap	GreyPixmap
-.sp 3p
-_
-.TE
-.IN "XtDefaultForeground" "" ""
-.NH 2
-Resource Conversions
-.XS
-	Resource Conversions
-.XE
-.IN "conversions" "" "@DEF@"
-.IN "string conversions" "" "@DEF@"
-.IN "type conversions" "" "@DEF@"
-.LP
-Most resources in the Athena widget set have a converter registered that
-will translate the string in a resource file to the correct internal
-representation.  While some are obvious (string to integer, for example),
-others need specific mention of the allowable values.  Three general
-converters are described here:
-.IP \(bu 5
-Cursor
-.IP \(bu 5
-Pixel
-.IP \(bu 5
-Bitmap
-.LP
-Many widgets have defined special converters that apply only to that
-widget.  When these occur, the documentation section for that widget
-will describe the converter.
-.NH 3
-Cursor Conversion
-.IN "conversions" "ColorCursor" "@DEF@"
-.IN "conversions" "Cursor" "@DEF@"
-.IN "cursor" "" ""
-.LP
-The value for the \fBcursorName\fP resource is specified in the resource
-database as a string, and is of the following forms:
-.IP \(bu 5
-A standard X cursor name from \fB< X11/cursorfont.h >\fP.
-The names in \fBcursorfont.h\fP each describe a specific cursor.  The
-resource names for these cursors are exactly like the names in this file
-except the \fBXC_\fP is not used.  The cursor definition \fBXC_gumby\fP
-has a resource name of \fBgumby\fP.
-.IP \(bu 5
-Glyphs, as in \fIFONT font-name glyph-index [[ font-name ] glyph-index ]\fP.
-The first font and glyph specify the cursor source pixmap.
-The second font and glyph specify the cursor mask pixmap.
-The mask font defaults to the source font,
-and the mask glyph index defaults to the source glyph index.
-.IP \(bu 5
-A relative or absolute file name.
-If a relative or absolute file name is specified, that file is used to
-create the source pixmap.  Then the string "Mask" is appended to
-locate the cursor mask pixmap.  If the "Mask" file does not exist, the
-suffix "msk" is tried.  If "msk" fails, no cursor mask will be used.
-If the filename does not start with '/' or './' the the bitmap
-file path is used (see section 2.4.3).
-.NH 3
-Pixel Conversion
-.LP
-.IN "conversions" "Pixel" "@DEF@"
-.IN "pixel" "" ""
-.IN "rgb.txt" "" ""
-.IN "XtDefaultForeground" "" ""
-.IN "XtDefaultBackground" "" ""
-The string-to-pixel converter takes any name that is acceptable to
-XParseColor (see \fI\*(xL\fP).  In addition this routine understands
-the special toolkit symbols `XtDefaultForeground' and
-`XtDefaultBackground', described in \fI\*(xT\fP.  In short the acceptable
-pixel names are:
-.IP \(bu 5
-Any color name for the rgb.txt file (typically in the directory
-/usr/lib/X11 on POSIX systems).
-.IP \(bu 5
-A numeric specification of the form #<red><green><blue> where these
-numeric values are hexadecimal digits (both upper and lower case).
-.IP \(bu 5
-The special strings `XtDefaultForeground' and `XtDefaultBackground'
-.NH 3
-Bitmap Conversion
-.IN "bitmap conversions" "" "@DEF@"
-.IN "conversions" "Bitmap" "@DEF@"
-.IN "bitmapFilePath" "" "@DEF@"
-.IN "BitmapFilePath" "" "@DEF@"
-.IN "/usr/include/X11/bitmaps" "" ""
-.LP
-The string-to-bitmap converter attempts to locate a file containing
-bitmap data whose name is specified by the input string.  If the file
-name is relative (i.e. does not begin with / or ./), the directories to
-be searched are specified in the \fBbitmapFilePath\fP resource--class
-\fBBitmapFilePath\fP.  This resource specifies a colon (:) separated
-list of directories that will be searched for the named bitmap or
-cursor glyph (see section 2.4.1).  The \fBbitmapFilePath\fP resource is
-global to the application, and may \fBnot\fP be specified differently
-for each widget that wishes to convert a cursor to bitmap.  In addition
-to the directories specified in the \fBbitmapFilePath\fP resource a
-default directory is searched.  When using POSIX the default
-directory is
-.PN /usr/include/X11/bitmaps .
-.NH 2
-Realizing a Widget
-.LP
-.XS
-	Realizing a Widget
-.XE
-.IN "realizing widgets" "" "@DEF@"
-The
-.PN XtRealizeWidget
-function performs two tasks:
-.IP \(bu 5
-Calculates the geometry constraints of all managed descendants
-of this widget.  The actual calculation is put off until realize time
-for performance reasons.
-.IP \(bu 5
-Creates an X window for the widget and, if it is a composite widget,
-realizes each of its managed children.
-.IN "XtRealizeWidget" "" "@DEF@"
-.FD 0
-void XtRealizeWidget(\fIw\fP)
-.br
-      Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget.
-.LP
-For further information about this function,
-see the \fI\*(xT\fP.
-.NH 2
-Processing Events
-.LP
-.XS
-	Processing Events
-.XE
-.IN "events" "" ""
-.IN "XtAppInitialize" "" ""
-Now that the application has created, managed and realized its
-widgets, it is ready to process the events that will be delivered by the
-X Server to this client.  A function call that will process the
-events is \fBXtAppMainLoop\fP.
-.IN "XtAppMainLoop" "" "@DEF@"
-.FD 0
-void XtAppMainLoop(\fIapp_context\fP)
-.br
-      XtAppContext \fIapp_context\fP;
-.FN
-.IP \fIapp_context\fP 1i
-Specifies the application context of this application.  The value is
-normally returned by \fBXtAppInitialize\fP.
-.LP
-This function never returns: it is an infinite loop that processes the
-X events.  User input can be handled through callback procedures and
-application defined action routines.  More details are provided in
-\fI\*(xT\fP.
-.NH 2
-Standard Widget Manipulation Functions
-.XS
-	Standard Widget Manipulation Functions
-.XE
-.LP
-After a widget has been created, a client can interact with that
-widget by calling one of the standard widget manipulation routines
-provided by the \*(xI, or a widget class-specific manipulation routine.
-.LP
-The \*(xI provide generic routines to give the application programmer
-access to a set of standard widget functions.  The common widget
-routines let an application or composite widget perform the following
-operations on widgets without requiring explicit knowledge of the widget
-type.
-.IP \(bu 5
-Control the mapping of widget windows
-.IP \(bu 5
-Destroy a widget instance
-.IP \(bu 5
-Obtain an argument value
-.IP \(bu 5
-Set an argument value
-.NH 3
-Mapping Widgets
-.LP
-By default,
-widget windows are mapped (made viewable) automatically by
-\fBXtRealizeWidget\fP.  This behavior can be disabled by using
-\fBXtSetMappedWhenManaged\fP, making the client responsible for calling
-\fBXtMapWidget\fP to make the widget viewable.
-.IN "XtSetMappedWhenManaged" "" "@DEF@"
-.IN "XtMapWidget" "" ""
-.IN "XtRealizeWidget" "" ""
-.FD 0
-void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP)
-.br
-      Widget \fIw\fP;
-.br
-      Boolean \fImap_when_managed\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget.
-.IP \fImap_when_managed\fP 1i
-Specifies the new value.
-If map_when_managed is \fBTrue\fP, the widget is mapped automatically
-when it is realized.  If map_when_managed is \fBFalse\fP, the client
-must call
-.PN XtMapWidget
-or make a second call to
-.PN XtSetMappedWhenManaged
-to cause the child window to be mapped.
-.LP
-.sp
-The definition for
-.PN XtMapWidget
-is:
-.IN "XtMapWidget" "" "@DEF@"
-.FD 0
-void XtMapWidget(\fIw\fP)
-.br
-     Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget.
-.LP
-When you are creating several children in sequence for a previously
-realized common parent it is generally more efficient to construct a
-list of children as they are created (using \fBXtCreateWidget\fP) and
-then use \fBXtManageChildren\fP to request that their parent managed
-them all at once.  By managing a list of children at one time, the
-parent can avoid wasteful duplication of geometry processing and the
-associated ``screen flash''.
-.IN "XtManageChildren" "" "@DEF@"
-.IN "XtCreateWidget" "" ""
-.FD 0
-void XtManageChildren(\fIchildren\fP, \fInum_children\fP)
-.br
-      WidgetList \fIchildren\fP;
-.br
-      Cardinal \fInum_children\fP;
-.FN
-.IP \fIchildren\fP 1i
-Specifies a list of children to add.
-.IP \fInum_children\fP 1i
-Specifies the number of children to add.
-.LP
-If the parent is already visible on the screen, it is especially
-important to batch updates so that the minimum amount of visible window
-reconfiguration is performed.
-.LP
-For further information about these functions,
-see the \fI\*(xT\fP.
-.NH 3
-Destroying Widgets
-.LP
-To destroy a widget instance of any type, use
-.PN XtDestroyWidget .
-.IN "XtDestroyWidget" "" "@DEF@"
-.FD 0
-void XtDestroyWidget(\fIw\fP)
-.br
-      Widget \fIw\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget.
-.LP
-.PN XtDestroyWidget
-destroys the widget and recursively destroys any children that it may have,
-including the windows created by its children.
-After calling
-.PN XtDestroyWidget ,
-no further references should be made to the widget or any children
-that the destroyed widget may have had.
-.NH 3
-Retrieving Widget Resource Values
-.LP
-To retrieve the current value of a resource attribute associated
-with a widget instance, use
-.PN XtGetValues .
-.IN "XtGetValues" "" "@DEF@"
-.FD 0
-void XtGetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP)
-.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 a variable-length argument list of name and \fBaddress\fP
-pairs that contain the resource name and the address into which the
-resource value is stored.
-.IP \fInum_args\fP 1i
-Specifies the number of arguments in the argument list.
-.LP
-The arguments and values passed in the argument list are dependent on
-the widget. Note that the caller is responsible for providing space
-into which the returned resource value is copied; the \fBArgList\fP
-contains a pointer to this storage (e.g. x and y must be
-allocated as Position).  For further information, see the \fI\*(xT\fP.
-.NH 3
-Modifying Widget Resource Values
-.LP
-To modify the current value of a resource attribute associated with a
-widget instance, use
-.PN XtSetValues .
-.IN "XtSetValues" "" "@DEF@"
-.FD 0
-void XtSetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP)
-.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 an array of name and \fBvalue\fP pairs that contain the
-arguments to be modified and their new values.
-.IP \fInum_args\fP 1i
-Specifies the number of arguments in the argument list.
-.LP
-The arguments and values that are passed will depend on the widget
-being modified.  Some widgets may not allow certain resources to be
-modified after the widget instance has been created or realized.
-No notification is given if any part of a \fBXtSetValues\fP request is
-ignored.
-.LP
-For further information about these functions, see the \fI\*(xT\fP.
-.IN "XtGetValues" "" ""
-.IN "XtSetValues" "" ""
-.NT
-The argument list entry for
-.PN XtGetValues
-specifies the address to which the caller wants the value copied.  The
-argument list entry for
-.PN XtSetValues ,
-however, contains the new value itself, if the size of value is less than
-sizeof(XtArgVal) (architecture dependent, but at least sizeof(long));
-otherwise, it is a pointer to the value.  String resources are always
-passed as pointers, regardless of the length of the string.
-.NE
-.NH 2
-Using the Client Callback Interface
-.LP
-.XS
-	Using the Client Callback Interface
-.XE
-.IN "callbacks" "" ""
-Widgets can communicate changes in their state to their clients
-by means of a callback facility.
-The format for a client's callback handler is:
-.IN "CallbackProc" "" "@DEF@"
-.FD 0
-void \fICallbackProc\fP(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
-.br
-      Widget \fIw\fP;
-.br
-      XtPointer \fIclient_data\fP;
-.br
-      XtPointer \fIcall_data\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies widget for which the callback is registered.
-.IP \fIclient_data\fP 1i
-Specifies arbitrary client-supplied data that the widget should pass
-back to the client when the widget executes the client's callback
-procedure.  This is a way for the client registering the callback to
-also register client-specific data: a pointer to additional information
-about the widget, a reason for invoking the callback, and so on. If no
-additional information is necessary, NULL may be passed as this argument.
-This field is also frequently known as the \fIclosure\fP.
-.IP \fIcall_data\fP 1i
-Specifies any callback-specific data the widget wants to pass to the client.
-For example, when Scrollbar executes its \fBjumpProc\fP callback list,
-it passes the current position of the thumb in \fIcall_data\fP.
-.LP
-Callbacks can be registered either by creating an argument containing
-the callback list described below or by using the special convenience
-routines \fBXtAddCallback\fP and \fBXtAddCallbacks\fP.  When the widget
-is created, a pointer to a list of callback procedure and data pairs can
-be passed in the argument list to
-.PN XtCreateWidget .
-The list is of type
-.PN XtCallbackList :
-.IN "XtCallbackProc"
-.IN "XtAddCallbacks"
-.IN "XtAddCallback"
-.IN "XtCallbackList" "" "@DEF@"
-.IN "XtCallbackRec" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 3i
-.ta .5i 3i
-typedef struct {
-	XtCallbackProc callback;
-	XtPointer closure;
-} XtCallbackRec, *XtCallbackList;
-.De
-.LP
-The callback list must be allocated and initialized before calling
-.PN XtCreateWidget .
-.IN "XtCreateWidget"
-The end of the list is identified by an entry containing NULL in
-callback and closure.  Once the widget is created, the client can change
-or de-allocate this list; the widget itself makes no further reference
-to it.  The closure field contains the client_data passed to the
-callback when the callback list is executed.
-.LP
-The second method for registering callbacks is to use
-.PN XtAddCallback
-after the widget has been created.
-.IN "XtAddCallback" "" "@DEF@"
-.FD 0
-void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \
-\fIclient_data\fP)
-.br
-      Widget \fIw\fP;
-.br
-      String \fIcallback_name\fP;
-.br
-      XtCallbackProc \fIcallback\fP;
-.br
-      XtPointer \fIclient_data\fP;
-.FN
-.IP \fIw\fP 1i
-Specifies the widget to add the callback to.
-.IP \fIcallback_name\fP 1i
-Specifies the callback list within the widget to append to.
-.IP \fIcallback\fP 1i
-Specifies the callback procedure to add.
-.IP \fIclient_data\fP 1i
-Specifies the data to be passed to the callback when it is invoked.
-.LP
-.PN XtAddCallback
-adds the specified callback to the list for the named widget.
-.LP
-All widgets provide a callback list named
-.PN destroyCallback
-.IN "destroyCallback" "" "@DEF@"
-where clients can register procedures that are to be executed when the
-widget is destroyed.  The destroy callbacks are executed when the widget
-or an ancestor is destroyed.  The \fIcall_data\fP argument is unused for
-destroy callbacks.
-.NH 2
-Programming Considerations
-.LP
-.XS
-	Programming Considerations
-.XE
-This section provides some guidelines on how to set up an application
-program that uses the \*(tk.
-.NH 3
-Writing Applications
-.LP
-.IN "writing applications"
-.IN "StringDefs.h"
-.IN "Intrinsic.h"
-When writing an application that uses the X Toolkit,
-you should make sure that your application performs the following:
-.IP 1. 5
-Include
-.Pn < X11/Intrinsic.h >
-in your application programs.
-This header file automatically includes
-.Pn < X11/Xlib.h >,
-so all Xlib functions also are defined.
-It may also be necessary to include \fB< X11/StringDefs.h >\fP when setting
-up argument lists, as many of the XtN\fIsomething\fP definitions are
-only defined in this file.
-.IP 2. 5
-Include the widget-specific header files for each widget type
-that you need to use.
-For example,
-.Pn < X11/Xaw/Label.h >
-and
-.Pn < X11/Xaw/Command.h >.
-.IP 3. 5
-Call the
-.PN XtAppInitialize
-.IN "XtAppInitialize"
-function before invoking any other toolkit or Xlib functions.
-For further information,
-see Section 2.1 and the \fI\*(xT\fP.
-.IP 4. 5
-To pass attributes to the widget creation routines that will override
-any site or user customizations, set up argument lists.  In this
-document, a list of valid argument names is provided in the discussion
-of each widget.  The names each have a global symbol defined that begins
-with \fBXtN\fP to help catch spelling errors.  For example,
-\fBXtNlabel\fP is defined for the \fBlabel\fP resource of many widgets.
-.IN "XtN" "" "@DEF@"
-.IP
-For further information, see Section 2.9.2.2.
-.IP 5. 5
-When the argument list is set up, create the widget with the
-\fBXtCreateManagedWidget\fP function.  For further information, see
-Section 2.2 and the \fI\*(xT\fP.
-.IN "XtCreateManagedWidget"
-.IP 6. 5
-If the widget has any callback routines, set by the
-.PN XtNcallback
-argument or the
-.PN XtAddCallback
-function, declare these routines within the application.
-.IN "XtAddCallback"
-.IP 7. 5
-After creating the initial widget hierarchy, windows must be created
-for each widget by calling
-.PN XtRealizeWidget
-on the top level widget.
-.IN "XtRealizeWidget"
-.IP 8. 5
-Most applications now sit in a loop processing events using
-.PN XtAppMainLoop ,
-for example:
-.IN "XtAppMainLoop"
-.IP
-.Ds 0
-XtCreateManagedWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP);
-XtRealizeWidget(\fIshell\fP);
-XtAppMainLoop(\fIapp_context\fP);
-.De
-.IP
-For information about this function, see the \fI\*(xT\fP.
-.IP 9. 5
-Link your application with
-.PN libXaw
-(the Athena widgets),
-.PN libXmu
-(miscellaneous utilities),
-.PN libXt
-(the \*(tk \*(xI),
-.PN libSM
-(Session Management),
-.PN libICE
-(Inter-Client Exchange),
-.PN libXext
-(the extension library needed for the shape extension code which allows
-rounded Command buttons), and
-.PN libX11
-(the core X library).
-The following provides a sample command line:
-.IN "libXaw"
-.IN "libXmu"
-.IN "libXt"
-.IN "libSM"
-.IN "libICE"
-.IN "libXext"
-.IN "libX11"
-.IN "linking applications"
-.IN "compiling applications"
-.IP
-.Ds 0
-cc -o \fIapplication\fP \fIapplication\fP.c \-lXaw \-lXmu \-lXt \
-\-lSM \-lICE \-lXext \-lX11
-.De
-.NH 3
-Changing Resource Values
-.IN "resource" ""
-.LP
-The \*(xI support two methods of changing the default resource
-values; the resource manager, and an argument list passed into
-XtCreateWidget.  While resources values will get updated no matter
-which method you use, the two methods provide slightly different
-functionality.
-.IP "Resource Manager" 1.5i
-This method picks up resource definitions described in \fI\*(xL\fP from
-many different locations at run time.  The locations most important to
-the application programmer are the \fIfallback resources\fP and the
-\fIapp-defaults\fP file, (see \fI\*(xT\fP for the complete list).
-Since these resource are loaded at run time, they can be overridden by
-the user, allowing an application to be customized to fit the
-particular needs of each individual user.  These values can also be
-modified without the need to rebuild the application, allowing rapid
-prototyping of user interfaces.  Application programmers should use
-resources in preference to hard-coded values whenever possible.
-.IP "Argument Lists" 1.5i
-The values passed into the widget at creation time via an argument list
-cannot be modified by the user, and allow no opportunity for
-customization.  It is used to set resources that cannot be specified as
-strings (e.g. callback lists) or resources that should not be
-overridden (e.g. window depth) by the user.
-.NH 4
-Specifying Resources
-.LP
-It is important for all X Toolkit application programmers to
-understand how to use the X Resource Manager to specify resources for
-widgets in an X application.  This section will describe the most common
-methods used to specify these resources, and how to use the X Resource
-manager.
-.IN "xrdb"
-.IP \fBXrdb\fP 1.5i
-The \fBxrdb\fP utility may be used to load a file containing
-resources into the X server.   Once the resources are loaded, the
-resources will affect any new applications started on the display that
-they were loaded onto.
-.IN "application defaults"
-.IN "app-defaults"
-.IN "/usr/lib/X11/app-defaults"
-.IP "\fBApplication Defaults\fP" 1.5i
-The application defaults (app-defaults) file (normally in
-/usr/lib/X11/app-defaults/\fIclassname\fP) for an application is loaded
-whenever the application is started.
-.LP
-The resource specification has two colon-separated parts, a name, and
-a value.  The \fIvalue\fP is a string whose format is dependent on the
-resource specified by \fIname\fP.  \fIName\fP is constructed by
-appending a resource name to a full widget name.
-.LP
-The full widget name is a list of the name of every ancestor of the
-desired widget separated by periods (.).  Each widget also has a class
-associated with it.  A class is a type of widget (e.g. Label or
-Scrollbar or Box).  Notice that class names, by convention, begin with
-capital letters and instance names begin with lower case letters.  The
-class of any widget may be used in place of its name in a resource
-specification.  Here are a few examples:
-.IP xman.form.button1 1.5i
-This is a fully specified resource name, and will affect only widgets
-called button1 that are children of widgets called form that are
-children of
-applications named xman.  (Note that while typically two widgets that
-are siblings will have different names, it is not prohibited.)
-
-.IP Xman.Form.Command 1.5i
-This will match any Command widget that is a child of a Form widget
-that is itself a child of an application of class \fIXman\fP.
-.IP Xman.Form.button1 1.5i
-This is a mixed resource name with both widget names and classes specified.
-.LP
-This syntax allows an application programmer to specify any widget
-in the widget tree.  To match more than one widget (for example a user
-may want to make all Command buttons blue), use an asterisk (*)
-instead of a period.  When an asterisk is used, any number of widgets
-(including zero) may exist between the two widget names. For example:
-.IP Xman*Command 1.5i
-This matches all Command widgets in the Xman application.
-.IP Foo*button1 1.5i
-This matches any widget in the Foo application that is named \fIbutton1\fP.
-.LP
-The root of all application widget trees is the widget returned by
-\fBXtAppInitialize\fP.  Even though this is actually an
-ApplicationShell widget, the toolkit replaces its widget class with the
-class name of the application.  The name of this widget is either
-the name used to invoke the application (\fBargv[0]\fP) or the name of
-the application specified using the standard \fI-name\fP command line
-option supported by the \*(xI.
-.LP
-The last step in constructing the resource name is to append the name of
-the resource with either a period or asterisk to the full or partial
-widget name already constructed.
-.IP *foreground:Blue 2.25i
-Specifies that all widgets in all applications will have a foreground
-color of blue.
-.IP Xman*borderWidth:10 2.25i
-Specifies that all widgets in an application whose class is Xman will
-have a border width of 10 (pixels).
-.IP xman.form.button1.label:Testing 2.25i
-Specifies that a particular widget in the xman application will have a
-label named \fITesting\fP.
-.LP
-An exclamation point (!) in the first column of a line indicates
-that the rest of the line should be treated as a comment.
-.LP
-\fBFinal Words\fP
-.LP
-The Resource manager is a powerful tool that can be used very
-effectively to customize \*(tk applications at run time by either the
-application programmer or the user.  Some final points to note:
-.IP \(bu 5
-An application programmer may add new resources to their
-application.  These resources are associated with the global
-application, and not any particular widget.  The \*(tk function used for
-adding the application resources is \fBXtGetApplicationResources\fP.
-.IN "XtGetApplicationResources"
-.IP \(bu 5
-Be careful when creating resource files.  Since widgets will
-ignore resources that they do not understand, any spelling
-errors will cause a resource to have no effect.
-.IP \(bu 5
-Only one resource line will match any given resource.  There is a set
-of precedence rules, which take the following general stance.
-.ta 10n
-.IP "" 5
-\(bu	More specific overrides less specific, thus period always overrides asterisk.
-.IP "" 5
-\(bu	Names on the left are more specific and override names on the right.
-.IP "" 5
-\(bu	When resource specifications are exactly the same, user defaults
-.br
-	will override program defaults.
-.LP
-For a complete explanation of the rules of precedence, and
-other specific topics see \fI\*(xT\fP and \fI\*(xL\fP.
-.NH 4
-Creating Argument Lists
-.IN "argument lists" "" "@DEF@"
-.LP
-To set up an argument list for the inline specification of widget attributes,
-you may use any of the four approaches discussed in this section.
-Each resource name has a global symbol associated with it.  This
-global symbol has the form XtN\fIresource name\fP.  For example, the
-symbol for ``foreground'' is \fBXtNforeground\fP. For further information,
-see the \fI\*(xT\fP.
-.LP
-Argument are specified by using the following structure:
-.IN "ArgList" "" "@DEF@"
-.IN "Arg" "" "@DEF@"
-.LP
-.Ds 0
-.TA .5i 1.5i
-.ta .5i 1.5i
-typedef struct {
-	String name;
-	XtArgVal value;
-} Arg, *ArgList;
-.De
-.LP
-The first approach is to statically initialize the argument list.
-For example:
-.LP
-.Ds 0
-.TA .5i
-.ta .5i
-static Arg arglist[] = {
-	{XtNwidth, (XtArgVal) 400},
-	{XtNheight, (XtArgVal) 300},
-};
-.De
-.LP
-This approach is convenient for lists that do not need to be computed
-at runtime and makes adding or deleting new elements easy.
-The
-.IN "XtNumber"
-.PN XtNumber
-macro is used to compute the number of elements in the argument list,
-preventing simple programming errors:
-.LP
-.Ds
-XtCreateWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIarglist\fP, XtNumber(\fIarglist\fP));
-.De
-.IN "XtSetArg" "" "@DEF@"
-.LP
-The second approach is to use the
-.PN XtSetArg
-macro.
-For example:
-.LP
-.Ds 0
-.TA .5i
-.ta .5i
-Arg arglist[10];
-XtSetArg(arglist[1], XtNwidth, 400);
-XtSetArg(arglist[2], XtNheight, 300);
-.De
-.LP
-To make it easier to insert and delete entries,
-you also can use a variable index:
-.LP
-.Ds 0
-.TA .5i
-.ta .5i
-Arg arglist[10];
-Cardinal i=0;
-XtSetArg(arglist[i], XtNwidth,  400);       i++;
-XtSetArg(arglist[i], XtNheight, 300);       i++;
-.De
-.LP
-The i variable can then be used as the argument list count in the widget
-create function.
-In this example,
-.IN "XtNumber"
-.PN XtNumber
-would return 10, not 2, and therefore is not useful.
-.NT
-You should not use auto-increment or auto-decrement
-within the first argument to
-.PN XtSetArg .
-As it is currently implemented,
-.PN XtSetArg
-is a macro that dereferences the first argument twice.
-.NE
-.LP
-The third approach is to individually set the elements of the
-argument list array:
-.LP
-.Ds 0
-.TA .5i
-.ta .5i
-Arg arglist[10];
-arglist[0].name  = XtNwidth;
-arglist[0].value = (XtArgVal) 400;
-arglist[1].name  = XtNheight;
-arglist[1].value = (XtArgVal) 300;
-.De
-.LP
-Note that in this example, as in the previous example,
-.IN "XtNumber"
-.PN XtNumber
-would return 10, not 2, and therefore would not be useful.
-.LP
-The fourth approach is to use a mixture of the first and third approaches:
-you can statically define the argument list but modify some entries at runtime.
-For example:
-.LP
-.Ds 0
-.TA .5i
-.ta .5i
-static Arg arglist[] = {
-	{XtNwidth, (XtArgVal) 400},
-	{XtNheight, (XtArgVal) NULL},
-};
-arglist[1].value = (XtArgVal) 300;
-.De
-.LP
-In this example,
-.IN "XtNumber"
-.PN XtNumber
-can be used, as in the first approach, for easier code maintenance.
-.NH 2
-Example Programs
-.XS
-	Example Programs
-.XE
-.IN "examples"
-.LP
-The best way to understand how to use any programming library is by
-trying some simple examples.  A collection of example programs that
-introduces each of the widgets in that Athena widget set, as well as many
-important toolkit programming concepts, is available in the X11R6
-release as distributed by the X Consortium.  It can be found in the
-distribution directory \fBcontrib/examples/mit/Xaw\fP, but see your
-site administrator for the exact location of these files on your system.
-See the README file from that directory for a guide to the examples.
-