Added libXaw-1.0.7

1 files changed, 1103 insertions, 0 deletions

diff --git a/libXaw/spec/CH2 b/libXaw/spec/CH2
new file mode 100644
index 000000000..9e6c17a8a
--- /dev/null
+++ b/libXaw/spec/CH2
@@ -0,0 +1,1103 @@
+.\" $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.
+