svn merge ^/branches/released .

24 files changed, 28557 insertions, 0 deletions

diff --git a/libXt/specs/CH01 b/libXt/specs/CH01
new file mode 100644
index 000000000..78f128bd7
--- /dev/null
+++ b/libXt/specs/CH01
@@ -0,0 +1,2471 @@
+.\" $Xorg: CH01,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 1\fP\s-1
+
+\s+1\fBIntrinsics and Widgets\fP\s-1
+.sp 2
+.if \n(GS .nr nh*hl 1
+.nr H1 1
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+\fBChapter 1 \(em Intrinsics and Widgets\fP
+.XE
+The \*(xI are a programming library tailored to the special requirements
+of user interface construction within a network window system,
+specifically the X Window System.
+The \*(xI and a widget set make up an \*(tk.
+
+.NH 2
+Intrinsics
+.XS
+\fB\*(SN Intrinsics\fP
+.XE
+.LP
+The \*(xI provide the base mechanism necessary to build 
+a wide variety of interoperating widget sets and application environments.
+The Intrinsics are a layer on top of Xlib, the
+C Library X Interface.  They extend the
+fundamental abstractions provided by the X Window System while still
+remaining independent of any particular user interface policy or
+style.
+.LP
+The Intrinsics use object-oriented programming techniques to supply a
+consistent architecture for constructing and composing user interface
+components, known as widgets.  This
+allows programmers to extend a widget set in new ways, either by
+deriving new widgets from existing ones (subclassing) or by writing
+entirely new widgets following the established conventions.
+.LP
+When the \*(xI were first conceived, the root of the object
+hierarchy was a widget class named
+Core.
+.IN "Core"
+In Release 4 of the
+\*(xI, three nonwidget superclasses were added above Core.
+These superclasses are described in Chapter 12.  The name of the class
+now at the root of the Intrinsics class hierarchy is
+Object.
+.IN "Object"
+The remainder of this
+specification refers uniformly to \fIwidgets\fP and \fICore\fP
+as if they were the
+base class for all \*(xI operations.  The argument descriptions
+for each Intrinsics procedure and Chapter 12 describe which operations
+are defined for the nonwidget superclasses of Core.  The reader may
+determine by context whether a specific reference to \fIwidget\fP
+actually means ``widget'' or ``object.''
+
+.NH 2
+Languages
+.XS
+\fB\*(SN Languages\fP
+.XE
+.LP
+The Intrinsics are intended to be used for two programming purposes.
+Programmers writing widgets will be using most of the facilities
+provided by the
+Intrinsics to construct user interface components from the simple, such
+as buttons and scrollbars, to the complex, such as control panels and
+property sheets.  Application programmers will use a much smaller subset of
+the Intrinsics procedures in combination with one or more sets of widgets to
+construct and present complete user interfaces on an X display.  The
+Intrinsics
+programming interfaces primarily
+intended for application use are designed to be callable from most
+procedural programming languages.  Therefore, most arguments are passed by
+reference rather than by value.  The interfaces primarily
+intended for widget programmers are expected to be used principally
+from the C language.  In these cases, the usual C programming
+conventions apply.  In this specification, the term \fIclient\fP refers to
+any module, widget, or application that calls an Intrinsics procedure.
+.LP
+Applications that use the \*(xI mechanisms
+must include the header files
+.Pn < X11/Intrinsic.h >
+and
+.Pn < X11/StringDefs.h >,
+or their equivalent,
+and they may also include
+.Pn < X11/Xatoms.h >
+and
+.Pn < X11/Shell.h >.
+In addition, widget implementations should include
+.Pn < X11/IntrinsicP.h >
+instead of
+.Pn < X11/Intrinsic.h >.
+.LP
+The applications must also include the additional header files for
+each widget class that they are to use (for example,
+.Pn < X11/Xaw/Label.h >
+or
+.Pn < X11/Xaw/Scrollbar.h >).
+On a POSIX-based system, 
+the \*(xI object library file is named
+.PN libXt.a
+and is usually referenced as \-lXt when linking the application.
+
+.NH 2
+Procedures and Macros
+.LP
+.XS
+\fB\*(SN Procedures and Macros\fP
+.XE
+All functions defined in this specification except those specified below
+may be implemented as C macros with arguments.  C applications may use
+``#undef'' to remove a macro definition and ensure that the actual function
+is referenced.  Any such macro will expand to a single expression that
+has the same precedence as a function call and that evaluates each
+of its arguments exactly once, fully protected by parentheses, so that
+arbitrary expressions may be used as arguments.
+.LP
+The following symbols are macros that do not have function
+equivalents and that may expand their arguments in a manner other
+than that described above:
+.PN XtCheckSubclass ,
+.PN XtNew ,
+.PN XtNumber ,
+.PN XtOffsetOf ,
+.PN XtOffset ,
+and
+.PN XtSetArg .
+
+.NH 2
+Widgets
+.LP
+.XS
+\fB\*(SN Widgets\fP
+.XE
+.LP
+The fundamental abstraction and data type of the \*(tk is the widget,
+which is a combination of an X window and its associated
+input and display semantics
+and which is dynamically allocated and contains state information.
+Some widgets display information (for example, text or graphics),
+and others are merely containers for other widgets (for example, a menu box).
+Some widgets are output-only and do not react to pointer or keyboard input,
+and others change their display in response to input
+and can invoke functions that an application has attached to them.
+.LP
+Every widget belongs to exactly one widget class, which is statically
+allocated and initialized and which contains the operations allowable on
+widgets of that class.
+Logically, a widget class is the procedures and data associated
+with all widgets belonging to that class.
+These procedures and data can be inherited by
+subclasses.
+Physically, a widget class is a pointer to a structure.
+The contents of this structure are constant for all widgets of the widget
+class but will vary from class to class.
+(Here, ``constant'' means the class structure is initialized at compile time
+and never changed, except for a one-time class initialization
+and in-place compilation of resource lists,
+which takes place when the first widget of the class or subclass is created.)
+For further information,
+see Section 2.5.
+.LP
+The distribution of the declarations and code for a new widget class
+among a public .h file for application programmer use, a private .h file
+for widget programmer use,
+and the implementation .c file is described in Section 1.6.
+The predefined widget classes adhere to these conventions.
+.LP
+A widget instance is composed of two parts:
+.IP \(bu 5
+A data structure which contains instance-specific values.
+.IP \(bu 5
+A class structure which contains information that is applicable to
+all widgets of that class.
+.LP
+Much of the input/output of a widget (for example, fonts, colors, sizes, 
+or border widths) is customizable by users.
+.LP
+This chapter discusses the base widget classes,
+Core, Composite, and Constraint, and
+ends with a discussion of widget classing.
+
+.NH 3
+Core Widgets
+.XS
+\*(SN Core Widgets
+.XE
+.LP
+.IN "Core" "" "@DEF@"
+The 
+Core 
+widget class contains the definitions of fields common to all widgets.
+All widgets classes are subclasses of the
+Core class,
+which is defined by the 
+.PN CoreClassPart
+and 
+.PN CorePart 
+structures.
+
+.NH 4
+CoreClassPart Structure
+.XS
+\*(SN CoreClassPart Structure
+.XE
+.LP
+All widget classes contain the fields defined in the
+.PN CoreClassPart
+structure.
+.LP
+.IN "CoreClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3.5i
+.ta .5i 3.5i
+typedef struct {
+	WidgetClass superclass;	See Section 1.6
+	String class_name;	See Chapter 9
+	Cardinal widget_size;	See Section 1.6
+	XtProc class_initialize;	See Section 1.6
+	XtWidgetClassProc class_part_initialize;	See Section 1.6
+	XtEnum class_inited;	See Section 1.6
+	XtInitProc initialize;	See Section 2.5
+	XtArgsProc initialize_hook;	See Section 2.5
+	XtRealizeProc realize;	See Section 2.6
+	XtActionList actions;	See Chapter 10
+	Cardinal num_actions;	See Chapter 10
+	XtResourceList resources;	See Chapter 9
+	Cardinal num_resources;	See Chapter 9
+	XrmClass xrm_class;	Private to resource manager
+	Boolean compress_motion;	See Section 7.9
+	XtEnum compress_exposure;	See Section 7.9
+	Boolean compress_enterleave;	See Section 7.9
+	Boolean visible_interest;	See Section 7.10
+	XtWidgetProc destroy;	See Section 2.8
+	XtWidgetProc resize;	See Chapter 6
+	XtExposeProc expose;	See Section 7.10
+	XtSetValuesFunc set_values;	See Section 9.7
+	XtArgsFunc set_values_hook;	See Section 9.7
+	XtAlmostProc set_values_almost;	See Section 9.7
+	XtArgsProc get_values_hook;	See Section 9.7
+	XtAcceptFocusProc accept_focus;	See Section 7.3
+	XtVersionType version;	See Section 1.6
+	XtPointer callback_private;	Private to callbacks
+	String tm_table;		See Chapter 10
+	XtGeometryHandler query_geometry;	See Chapter 6
+	XtStringProc display_accelerator;	See Chapter 10
+	XtPointer extension;	See Section 1.6
+} CoreClassPart;
+.De
+.LP
+.eM
+All widget classes have the Core class fields as their first component.
+The prototypical
+.PN WidgetClass
+and
+.PN CoreWidgetClass
+are defined with only this set of fields.
+.LP
+.IN "Core"
+.IN "WidgetClass" "" "@DEF@"
+.IN "CoreWidgetClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	CoreClassPart core_class;
+} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
+.De
+.LP
+.eM
+Various routines can cast widget class pointers, as needed,
+to specific widget class types.
+.LP
+The single occurrences of the class record and pointer for
+creating instances of Core are
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClassRec widgetClassRec;
+#define coreClassRec widgetClassRec
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClass widgetClass, coreWidgetClass;
+.De
+.LP
+.eM
+The opaque types
+.PN Widget
+and
+.PN WidgetClass
+and the opaque variable
+.PN widgetClass
+are defined for generic actions on widgets.
+In order to make these types opaque and ensure that the compiler
+does not allow applications to access private data, the \*(xI use
+incomplete structure definitions in
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
+.De
+.eM
+
+.NH 4
+CorePart Structure
+.XS
+\*(SN CorePart Structure
+.XE
+.LP
+All widget instances contain the fields defined in the
+.PN CorePart
+structure.
+.LP
+.IN "CorePart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _CorePart {
+	Widget self;	Described below
+	WidgetClass widget_class;	See Section 1.6
+	Widget parent;	See Section 2.5
+	Boolean being_destroyed;	See Section 2.8
+	XtCallbackList destroy_callbacks;	See Section 2.8
+	XtPointer constraints;	See Section 3.6
+	Position x;	See Chapter 6
+	Position y;	See Chapter 6
+	Dimension width;	See Chapter 6
+	Dimension height;	See Chapter 6
+	Dimension border_width;	See Chapter 6
+	Boolean managed;	See Chapter 3
+	Boolean sensitive;	See Section 7.7
+	Boolean ancestor_sensitive;	See Section 7.7
+	XtTranslations accelerators;	See Chapter 10
+	Pixel border_pixel;	See Section 2.6
+	Pixmap border_pixmap;	See Section 2.6
+	WidgetList popup_list;	See Chapter 5
+	Cardinal num_popups;	See Chapter 5
+	String name;	See Chapter 9
+	Screen *screen;	See Section 2.6
+	Colormap colormap;	See Section 2.6
+	Window window;	See Section 2.6
+	Cardinal depth;	See Section 2.6
+	Pixel background_pixel;	See Section 2.6
+	Pixmap background_pixmap;	See Section 2.6
+	Boolean visible;	See Section 7.10
+	Boolean mapped_when_managed;	See Chapter 3
+} CorePart;
+.De
+.LP
+.eM
+All widget instances have the Core fields as their first component.
+The prototypical type
+.PN Widget
+is defined with only this set of fields.
+.LP
+.IN "Widget" "" "@DEF@"
+.IN "CoreWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	CorePart core;
+} WidgetRec, *Widget, CoreRec, *CoreWidget;
+.De
+.LP
+.eM
+Various routines can cast widget pointers, as needed,
+to specific widget types.
+.LP
+In order to make these types opaque and ensure that the compiler
+does not allow applications to access private data, the \*(xI use
+incomplete structure definitions in
+.PN Intrinsic.h .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _WidgetRec *Widget, *CoreWidget;
+.De
+.eM
+
+.NH 4
+Core Resources
+.LP
+.XS
+\fB\*(SN Core Resources\fP
+.XE
+.LP
+.IN "CoreWidget" "Resources"
+The resource names, classes, and representation types specified in the
+.PN coreClassRec
+resource list are
+.LP
+.TS
+lw(1.5i) lw(1.5i) lw(2.5i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNaccelerators	XtCAccelerators	XtRAcceleratorTable
+XtNbackground	XtCBackground	XtRPixel
+XtNbackgroundPixmap	XtCPixmap	XtRPixmap
+XtNborderColor	XtCBorderColor	XtRPixel
+XtNborderPixmap	XtCPixmap	XtRPixmap
+XtNcolormap	XtCColormap	XtRColormap
+XtNdepth	XtCDepth	XtRInt
+XtNmappedWhenManaged	XtCMappedWhenManaged	XtRBoolean
+XtNscreen	XtCScreen	XtRScreen
+XtNtranslations	XtCTranslations	XtRTranslationTable
+.sp 6p
+_
+.TE
+.LP
+Additional resources are defined for all widgets via the
+.PN objectClassRec
+and
+.PN rectObjClassRec
+resource lists; see Sections 12.2 and 12.3 for details.
+
+.NH 4
+CorePart Default Values
+.XS
+\*(SN CorePart Default Values
+.XE
+.LP
+The default values for the Core fields, which are filled in by the \*(xI,
+from the resource lists, and by the initialize procedures, are
+.LP
+.TS
+lw(1.5i) lw(4.25i) .
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+self	Address of the widget structure (may not be changed).
+T{
+widget_class
+T}	T{
+\fIwidget_class\fP argument to
+.PN XtCreateWidget
+(may not be changed).
+T}
+T{
+parent
+T}	T{
+\fIparent\fP argument to
+.PN XtCreateWidget
+(may not be changed).
+T}
+being_destroyed	Parent's \fIbeing_destroyed\fP value.
+destroy_callbacks	NULL
+constraints	NULL
+x	0
+y	0
+width	0
+height	0
+border_width	1
+T{
+managed
+T}	T{
+.PN False
+T}
+T{
+sensitive
+T}	T{
+.PN True
+T}
+ancestor_sensitive	T{
+logical AND of parent's \fIsensitive\fP and
+\fIancestor_sensitive\fP values.
+T}
+accelerators	NULL
+T{
+border_pixel	
+T}	T{
+.PN XtDefaultForeground
+T}
+border_pixmap	T{
+.PN XtUnspecifiedPixmap
+T}
+popup_list	NULL
+num_popups	0
+T{
+name
+T}	T{
+\fIname\fP argument to
+.PN XtCreateWidget
+(may not be changed).
+T}
+T{
+screen
+T}	T{
+Parent's \fIscreen\fP; top-level widget gets screen from display specifier
+.br
+(may not be changed).
+T}
+colormap	Parent's \fIcolormap\fP value.
+window	NULL
+depth	Parent's \fIdepth\fP; top-level widget gets root window depth.
+T{
+background_pixel
+T}	T{
+.PN XtDefaultBackground
+T}
+background_pixmap	T{
+.PN XtUnspecifiedPixmap
+T}
+T{
+visible
+T}	T{
+.PN True
+T}
+T{
+mapped_when_managed
+T}	T{
+.PN True
+T}
+.sp 6p
+_
+.TE
+.LP
+.IN XtUnspecifiedPixmap "" "@DEF@"
+.PN XtUnspecifiedPixmap
+is a symbolic constant guaranteed to be unequal to
+any valid Pixmap id,
+.PN None ,
+and
+.PN ParentRelative .
+
+.NH 3
+Composite Widgets
+.XS
+\*(SN Composite Widgets
+.XE
+.LP
+.IN "Composite" "" "@DEF@"
+The Composite 
+widget class is a subclass of the 
+Core 
+widget class (see Chapter 3).
+Composite widgets are intended to be containers for other widgets.
+The additional data used by composite widgets are defined by the
+.PN CompositeClassPart
+and 
+.PN CompositePart
+structures.
+
+.NH 4
+CompositeClassPart Structure
+.XS
+\*(SN CompositeClassPart Structure
+.XE
+.LP
+In addition to the 
+Core 
+class fields,
+widgets of the Composite class have the following class fields.
+.LP
+.IN "CompositeClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3.5i
+.ta .5i 3.5i
+typedef struct {
+	XtGeometryHandler geometry_manager;	See Chapter 6
+	XtWidgetProc change_managed;	See Chapter 3
+	XtWidgetProc insert_child;	See Chapter 3
+	XtWidgetProc delete_child;	See Chapter 3
+	XtPointer extension;	See Section 1.6
+} CompositeClassPart;
+.De
+.LP
+.eM
+The extension record defined for
+.PN CompositeClassPart
+with \fIrecord_type\fP
+equal to
+.PN \s-1NULLQUARK\s+1
+is
+.PN CompositeClassExtensionRec .
+.LP
+.IN "CompositeClassExtensionRec" "" "@DEF@"
+.IN "CompositeClassExtension" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3.5i
+.ta .5i 3.5i
+typedef struct {
+	XtPointer next_extension;	See Section 1.6.12
+	XrmQuark record_type;	See Section 1.6.12
+	long version;	See Section 1.6.12
+	Cardinal record_size;	See Section 1.6.12
+	Boolean accepts_objects;	See Section 2.5.2
+	Boolean allows_change_managed_set;	See Section 3.4.3
+} CompositeClassExtensionRec, *CompositeClassExtension;
+.De
+.LP
+.eM
+Composite 
+classes have the Composite class fields immediately following the
+Core class fields.
+.LP
+.IN "CompositeWidgetClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	CoreClassPart core_class;
+	CompositeClassPart composite_class;
+} CompositeClassRec, *CompositeWidgetClass;
+.De
+.LP
+.eM
+The single occurrences of the class record and pointer for creating
+instances of Composite are
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern CompositeClassRec compositeClassRec;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClass compositeWidgetClass;
+.De
+.LP
+.eM
+The opaque types
+.PN CompositeWidget
+and
+.PN CompositeWidgetClass
+and the opaque variable
+.PN compositeWidgetClass
+are defined for generic operations on widgets whose class
+is Composite or a subclass of Composite.
+The symbolic constant for the
+.PN CompositeClassExtension
+version identifier is
+.PN XtCompositeExtensionVersion
+(see Section 1.6.12).
+.PN Intrinsic.h
+uses an incomplete structure
+definition to ensure that the compiler catches attempts to access
+private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _CompositeClassRec *CompositeWidgetClass;
+.De
+.eM
+
+.NH 4
+CompositePart Structure
+.XS
+\*(SN CompositePart Structure
+.XE
+.LP
+In addition to the
+Core instance
+fields,
+widgets of the Composite class have the following
+instance fields defined in the
+.PN CompositePart
+structure.
+.LP
+.IN "CompositePart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	WidgetList children;	See Chapter 3
+	Cardinal num_children;	See Chapter 3
+	Cardinal num_slots;	See Chapter 3
+	XtOrderProc insert_position;	See Section 3.2
+} CompositePart;
+.De
+.LP
+.eM
+Composite 
+widgets have the Composite instance fields immediately following the Core
+instance fields.
+.LP
+.IN "CompositeWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	CorePart core;
+	CompositePart composite;
+} CompositeRec, *CompositeWidget;
+.De
+.LP
+.eM
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _CompositeRec *CompositeWidget;
+.De
+.eM
+
+.NH 4
+Composite Resources
+.XS
+\fB\*(SN Composite Resources\fP
+.XE
+.LP
+.IN "CompositeWidget" "Resources"
+The resource names, classes, and representation types
+that are specified in
+the
+.PN compositeClassRec
+resource list are
+.LP
+.TS
+lw(1.5i) lw(1.5i) lw(2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNchildren	XtCReadOnly	XtRWidgetList
+XtNinsertPosition	XtCInsertPosition	XtRFunction
+XtNnumChildren	XtCReadOnly	XtRCardinal
+.sp 6p
+_
+.TE
+
+.NH 4
+CompositePart Default Values
+.XS
+\*(SN CompositePart Default Values
+.XE
+.LP
+The default values for the Composite fields,
+which are filled in from the 
+Composite 
+resource list and by the
+Composite
+initialize procedure, are
+.LP
+.TS
+l l .
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+children	NULL
+num_children	0
+num_slots	0
+insert_position	Internal function to insert at end
+.sp 6p
+_
+.TE
+.LP
+The \fIchildren\fP, \fInum_children\fP,
+and \fIinsert_position\fP fields are declared
+as resources;
+.IN XtNinsertPosition
+XtNinsertPosition
+is a settable resource,
+.IN XtNchildren
+XtNchildren
+and
+.IN XtNnumChildren
+XtNnumChildren
+may be read by any client but should only be modified by the composite
+widget class procedures.
+
+.NH 3
+Constraint Widgets
+.XS
+\*(SN Constraint Widgets
+.XE
+.LP
+.IN "Constraint" "" "@DEF@"
+The Constraint 
+widget class is a subclass of the 
+Composite
+widget class (see Section 3.6).  Constraint
+widgets maintain additional state
+data for each child; for example, client-defined constraints on the child's
+geometry.
+The additional data used by constraint widgets are defined by the
+.PN ConstraintClassPart
+and
+.PN ConstraintPart
+structures.
+
+.NH 4
+ConstraintClassPart Structure
+.XS
+\*(SN ConstraintClassPart Structure
+.XE
+.LP
+In addition to the
+Core
+and
+Composite 
+class fields,
+widgets of the Constraint class
+have the following class fields.
+.LP
+.IN "ConstraintClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XtResourceList resources;	See Chapter 9
+	Cardinal num_resources;	See Chapter 9
+	Cardinal constraint_size;	See Section 3.6
+	XtInitProc initialize;	See Section 3.6
+	XtWidgetProc destroy;	See Section 3.6
+	XtSetValuesFunc set_values;	See Section 9.7.2
+	XtPointer extension;	See Section 1.6
+} ConstraintClassPart;
+.De
+.LP
+.eM
+The extension record defined for
+.PN ConstraintClassPart
+with \fIrecord_type\fP equal to
+.PN \s-1NULLQUARK\s+1
+is
+.PN ConstraintClassExtensionRec .
+.LP
+.IN "ConstraintClassExtensionRec" "" "@DEF@"
+.IN "ConstraintClassExtension" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XtPointer next_extension;	See Section 1.6.12
+	XrmQuark record_type;	See Section 1.6.12
+	long version;	See Section 1.6.12
+	Cardinal record_size;	See Section 1.6.12
+	XtArgsProc get_values_hook;	See Section 9.7.1
+} ConstraintClassExtensionRec, *ConstraintClassExtension;
+.De
+.LP
+.eM
+Constraint 
+classes have the Constraint class fields immediately following the
+Composite class fields.
+.LP
+.IN "ConstraintWidgetClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ConstraintClassRec {
+	CoreClassPart core_class;
+	CompositeClassPart composite_class;
+	ConstraintClassPart constraint_class;
+} ConstraintClassRec, *ConstraintWidgetClass;
+.De
+.LP
+.eM
+The single occurrences of the class record and pointer for creating
+instances of Constraint are
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern ConstraintClassRec constraintClassRec;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClass constraintWidgetClass;
+.De
+.LP
+.eM
+The opaque types
+.PN ConstraintWidget
+and
+.PN ConstraintWidgetClass
+and the opaque variable
+.PN constraintWidgetClass
+are defined for generic operations on widgets
+whose class is Constraint or a subclass
+of Constraint.
+The symbolic constant for the
+.PN ConstraintClassExtension
+version identifier is
+.PN XtConstraintExtensionVersion
+(see Section 1.6.12).
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ConstraintClassRec *ConstraintWidgetClass;
+.De
+.eM
+
+.NH 4
+ConstraintPart Structure
+.XS
+\*(SN ConstraintPart Structure
+.XE
+.LP
+In addition to the
+Core
+and
+Composite instance
+fields,
+widgets of the Constraint class have the following unused
+instance fields defined in the
+.PN ConstraintPart
+structure
+.LP
+.IN "ConstraintPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+        int empty;
+} ConstraintPart;
+.De
+.LP
+.eM
+Constraint 
+widgets have the Constraint instance fields immediately following the
+Composite instance fields.
+.LP
+.IN "ConstraintWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	CorePart core;
+	CompositePart composite;
+	ConstraintPart constraint;
+} ConstraintRec, *ConstraintWidget;
+.De
+.LP
+.eM
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ConstraintRec *ConstraintWidget;
+.De
+.eM
+
+.NH 4
+Constraint Resources
+.XS
+\fB\*(SN Constraint Resources\fP
+.XE
+.LP
+The
+.PN constraintClassRec
+\fIcore_class\fP and \fIconstraint_class resources\fP fields are NULL,
+and the \fInum_resources\fP fields are zero;
+no additional resources beyond those declared by
+the superclasses
+are defined for
+Constraint.
+
+.NH 2
+Implementation-Specific Types
+.XS
+\fB\*(SN Implementation-Specific Types\fP
+.XE
+.LP
+To increase the portability of widget and application source code
+between different system environments, the \*(xI define several
+types whose precise representation is explicitly dependent upon,
+and chosen by, each individual implementation of the \*(xI.
+.LP
+These implementation-defined types are
+.IN "Boolean" "" "@DEF@"
+.IP \fBBoolean\fP 11
+A datum that contains a zero or nonzero value.
+Unless explicitly stated, clients should not assume
+that the nonzero value is equal to the symbolic
+value
+.PN True .
+.IN "Cardinal" "" "@DEF@"
+.IP \fBCardinal\fP 11
+An unsigned integer datum with a minimum range of [0..2^16-1].
+.IN "Dimension" "" "@DEF@"
+.IP \fBDimension\fP 11
+An unsigned integer datum with a minimum range of [0..2^16-1].
+.IN "Position" "" "@DEF@"
+.IP \fBPosition\fP 11
+A signed integer datum with a minimum range of [-2^15..2^15-1].
+.IN "XtPointer" "" "@DEF@"
+.IP \fBXtPointer\fP 11
+A datum large enough to contain the largest of a char*, int*, function
+pointer, structure pointer, or long value.  A pointer
+to any type or function, or a long value may be converted
+to an
+.PN XtPointer
+and back again and the result will
+compare equal to the original value.  In ANSI C
+environments it is expected that
+.PN XtPointer
+will be
+defined as void*.
+.IN "XtArgVal" "" "@DEF@"
+.IP \fBXtArgVal\fP 11
+A datum large enough to contain an
+.PN XtPointer ,
+.PN Cardinal ,
+.PN Dimension ,
+or
+.PN Position
+value.
+.IN "XtEnum" "" "@DEF@"
+.IP \fBXtEnum\fP 11
+An integer datum large enough to encode at least 128 distinct
+values, two of which are the symbolic values
+.PN True
+and
+.PN False .
+The symbolic values
+.PN \s-1TRUE\s+1
+and
+.PN \s-1FALSE\s+1
+are
+also defined to be equal to
+.PN True
+and
+.PN False ,
+respectively.
+.LP
+In addition to these specific types, the precise order of the
+fields within the structure declarations for any of the instance
+part records
+.PN ObjectPart ,
+.PN RectObjPart ,
+.PN CorePart ,
+.PN CompositePart ,
+.PN ShellPart ,
+.PN WMShellPart ,
+.PN TopLevelShellPart ,
+and
+.PN ApplicationShellPart
+is implementation-defined.  These
+structures may also have additional private
+fields internal to the implementation.
+The
+.PN ObjectPart ,
+.PN RectObjPart ,
+and
+.PN CorePart
+structures must be defined so that any member with the same name
+appears at the same offset in
+.PN ObjectRec ,
+.PN RectObjRec ,
+and
+.PN CoreRec
+.Pn ( WidgetRec ).
+No other relations between the offsets of any two
+fields may be assumed.
+
+.NH 2
+Widget Classing
+.LP
+.XS
+\fB\*(SN Widget Classing\fP
+.XE
+.IN "widget_class" "" "@DEF@"
+The \fIwidget_class\fP field of a widget points to its widget class structure,
+which contains information that is constant across all widgets of that class.
+As a consequence, 
+widgets usually do not implement directly callable procedures;
+rather, they implement procedures, called methods, that are available through
+their widget class structure.
+These methods are invoked by generic procedures that envelop common actions 
+around the methods implemented by the widget class.
+Such procedures are applicable to all widgets
+of that class and also to widgets whose classes are subclasses of that class.
+.LP
+All widget classes are a subclass of 
+Core 
+and can be subclassed further.
+Subclassing reduces the amount of code and declarations
+necessary to make a
+new widget class that is similar to an existing class.
+For example, you do not have to describe every resource your widget uses in an
+.PN XtResourceList .
+Instead, you describe only the resources your widget has
+that its superclass does not.
+Subclasses usually inherit many of their superclasses' procedures
+(for example, the expose procedure or geometry handler).
+.LP
+Subclassing, however, can be taken too far.
+If you create a subclass that inherits none of the procedures of its
+superclass,
+you should consider whether you have chosen the most
+appropriate superclass.
+.LP
+To make good use of subclassing, 
+widget declarations and naming conventions are highly stylized.
+A widget consists of three files:
+.IP \(bu 5
+A public .h file, used by client widgets or applications.
+.IP \(bu 5
+A private .h file, used by widgets whose classes
+are subclasses of the widget class.
+.IP \(bu 5
+A .c file, which implements the widget.
+
+.NH 3
+Widget Naming Conventions
+.XS
+\fB\*(SN Widget Naming Conventions\fP
+.XE
+.LP
+The \*(xI provide a vehicle by which programmers can create
+new widgets and organize a collection of widgets into an application.
+To ensure that applications need not deal with as many styles of capitalization
+and spelling as the number of widget classes it uses,
+the following guidelines should be followed when writing new widgets:
+.IP \(bu 5
+Use the X library naming conventions that are applicable.
+For example, a record component name is all lowercase
+and uses underscores (_) for compound words (for example, background_pixmap).
+Type and procedure names start with uppercase and use capitalization for
+compound words (for example,
+.PN ArgList
+or
+.PN XtSetValues ).
+.IP \(bu 5
+A resource name is spelled identically to the field name
+except that compound names use capitalization rather than underscore.
+To let the compiler catch spelling errors,
+each resource name should have a symbolic identifier prefixed with
+``XtN''.
+For example,
+the \fIbackground_pixmap\fP field has the corresponding identifier
+XtNbackgroundPixmap,
+which is defined as the string ``backgroundPixmap''.
+Many predefined names are listed in 
+.Pn < X11/StringDefs.h >.
+Before you invent a new name,
+you should make sure there is not already a name that you can use.
+.IP \(bu 5
+A resource class string starts with a capital letter 
+and uses capitalization for compound names (for example,``BorderWidth'').
+Each resource class string should have a symbolic identifier prefixed with
+``XtC''
+(for example, XtCBorderWidth).
+Many predefined classes are listed in
+.Pn < X11/StringDefs.h >.
+.IP \(bu 5
+A resource representation string is spelled identically to the type name
+(for example, ``TranslationTable'').
+Each representation string should have a symbolic identifier prefixed with
+``XtR''
+(for example, XtRTranslationTable).
+Many predefined representation types are listed in
+.Pn < X11/StringDefs.h >.
+.IP \(bu 5
+New widget classes start with a capital and use uppercase for compound
+words.
+Given a new class name AbcXyz, you should derive several names:
+.RS
+.IP \- 5
+Additional widget instance structure part name AbcXyzPart.
+.IP \- 5
+Complete widget instance structure names AbcXyzRec and _AbcXyzRec.
+.IP \- 5
+Widget instance structure pointer type name AbcXyzWidget.
+.IP \- 5
+Additional class structure part name AbcXyzClassPart.
+.IP \- 5
+Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.
+.IP \- 5
+Class structure pointer type name AbcXyzWidgetClass.
+.IP \- 5
+Class structure variable abcXyzClassRec.
+.IP \- 5
+Class structure pointer variable abcXyzWidgetClass.
+.RE
+.IP \(bu 5
+Action procedures available to translation specifications should follow the
+same naming conventions as procedures.
+That is,
+they start with a capital letter, and compound names use uppercase
+(for example, ``Highlight'' and ``NotifyClient'').
+.LP
+The symbolic identifiers XtN..., XtC..., and XtR...
+may be implemented
+as macros, as global symbols, or as a mixture of the two.  The
+(implicit) type of the identifier is
+.PN String .
+The pointer value itself
+is not significant; clients must not assume that inequality of two
+identifiers implies inequality of the resource name, class, or
+representation string.  Clients should also note that although global
+symbols permit savings in literal storage in some environments, they
+also introduce the possibility of multiple definition conflicts when
+applications attempt to use independently developed widgets
+simultaneously.
+
+.NH 3
+Widget Subclassing in Public .h Files
+.XS
+\*(SN Widget Subclassing in Public .h Files
+.XE
+.LP
+The public .h file for a widget class is imported by clients
+and contains
+.IP \(bu 5
+A reference to the public .h file for the superclass.
+.IP \(bu 5
+Symbolic identifiers for
+the names and classes of the new resources that this widget adds
+to its superclass.
+The definitions should
+have a single space between the definition name and the value and no
+trailing space or comment in order to reduce the possibility of
+compiler warnings from similar declarations in multiple classes.
+.IP \(bu 5
+Type declarations for any new resource data types defined by the class.
+.IP \(bu 5
+The class record pointer variable used to create widget instances.
+.IP \(bu 5
+The C type that corresponds to widget instances of this class.
+.IP \(bu 5
+Entry points for new class methods.
+.LP
+For example, the following is the public .h file for a possible
+implementation of a Label widget:
+.LP
+.Ds
+.TA .5i 1.75i
+.ta .5i 1.75i
+#ifndef LABEL_H
+#define LABEL_H
+
+/* New resources */
+#define XtNjustify "justify"
+#define XtNforeground "foreground"
+#define XtNlabel "label"
+#define XtNfont "font"
+#define XtNinternalWidth "internalWidth"
+#define XtNinternalHeight "internalHeight"
+
+/* Class record pointer */
+extern WidgetClass labelWidgetClass;
+
+/* C Widget type definition */
+typedef struct _LabelRec      *LabelWidget;
+
+/* New class method entry points */
+extern void LabelSetText();
+	/* Widget w */
+	/* String text */
+
+extern String LabelGetText();
+	/* Widget w */
+
+#endif LABEL_H
+.De
+.LP
+The conditional inclusion of the text allows the application
+to include header files for different widgets without being concerned
+that they already may be included as a superclass of another widget.
+.LP
+To accommodate operating systems with file name length restrictions,
+the name of the public .h file is the first ten characters of the
+widget class.
+For example,
+the public .h file for the 
+Constraint 
+widget class is 
+.PN Constraint.h .
+
+.NH 3
+Widget Subclassing in Private .h Files
+.XS
+\*(SN Widget Subclassing in Private .h Files
+.XE
+.LP
+The private .h file for a widget is imported by widget classes that are
+subclasses of the widget and contains
+.IP \(bu 5
+A reference to the public .h file for the class.
+.IP \(bu 5
+A reference to the private .h file for the superclass.
+.IP \(bu 5
+Symbolic identifiers for any new resource representation types defined
+by the class.  The definitions should have a single space between the
+definition name and the value and no trailing space or comment.
+.IP \(bu 5
+A structure part definition for
+the new fields that the widget instance adds to its superclass's
+widget structure.
+.IP \(bu 5
+The complete widget instance structure definition for this widget.
+.IP \(bu 5
+A structure part definition for
+the new fields that this widget class adds to its superclass's
+constraint
+structure if the widget class is a subclass of
+Constraint.
+.IP \(bu 5
+The complete
+constraint
+structure definition if the widget class is a subclass of
+Constraint.
+.IP \(bu 5
+Type definitions for any new procedure types used by class methods
+declared in the widget class part.
+.IP \(bu 5
+A structure part definition for
+the new fields that this widget class adds to its superclass's widget class
+structure.
+.IP \(bu 5
+The complete widget class structure definition for this widget.
+.IP \(bu 5
+The complete widget class extension structure definition
+for this widget, if any.
+.IP \(bu 5
+The symbolic constant identifying the class extension version, if any.
+.IP \(bu 5
+The name of the global class structure variable containing the generic
+class structure for this class.
+.IP \(bu 5
+An inherit constant for each new procedure in the widget class part structure.
+.LP
+For example, the following is the private .h file for a possible Label widget:
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+#ifndef LABELP_H
+#define LABELP_H
+
+#include <X11/Label.h>
+
+/* New representation types used by the Label widget */
+#define XtRJustify "Justify"
+
+/* New fields for the Label widget record */
+typedef struct {
+/* Settable resources */
+	Pixel foreground;
+	XFontStruct *font;
+	String label;	/* text to display */
+	XtJustify justify;
+	Dimension internal_width;	/* # pixels horizontal border */
+	Dimension internal_height;	/* # pixels vertical border */
+
+/* Data derived from resources */
+	GC normal_GC;
+	GC gray_GC;
+	Pixmap gray_pixmap;
+	Position label_x;
+	Position label_y;
+	Dimension label_width;
+	Dimension label_height;
+	Cardinal label_len;
+	Boolean display_sensitive;
+} LabelPart;
+.De
+.sp
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+/* Full instance record declaration */
+typedef struct _LabelRec {
+	CorePart core;
+	LabelPart label;
+} LabelRec;
+
+/* Types for Label class methods */
+typedef void (*LabelSetTextProc)();
+	/* Widget w */
+	/* String text */
+
+typedef String (*LabelGetTextProc)();
+	/* Widget w */
+
+/* New fields for the Label widget class record */
+typedef struct {
+	LabelSetTextProc set_text;
+	LabelGetTextProc get_text;
+	XtPointer extension;
+} LabelClassPart;
+
+/* Full class record declaration */
+typedef struct _LabelClassRec {
+	CoreClassPart core_class;
+	LabelClassPart label_class;
+} LabelClassRec;
+
+/* Class record variable */
+extern LabelClassRec labelClassRec;
+
+#define LabelInheritSetText((LabelSetTextProc)_XtInherit)
+#define LabelInheritGetText((LabelGetTextProc)_XtInherit)
+#endif LABELP_H
+.De
+.LP
+To accommodate operating systems with file name length restrictions,
+the name of the private .h file is the first nine characters of the
+widget class followed by a capital P.
+For example,
+the private .h file for the 
+Constraint 
+widget class is 
+.PN ConstrainP.h .
+
+.NH 3
+Widget Subclassing in .c Files
+.XS
+\*(SN Widget Subclassing in .c Files
+.XE
+.LP
+The .c file for a widget contains the structure initializer
+for the class record variable,
+which contains the following parts:
+.IP \(bu 5
+Class information (for example, \fIsuperclass\fP, \fIclass_name\fP,
+\fIwidget_size\fP,
+\fIclass_initialize\fP, and \fIclass_inited\fP).
+.IP \(bu 5
+Data constants (for example, \fIresources\fP and \fInum_resources\fP, 
+\fIactions\fP and \fInum_actions\fP, \fIvisible_interest\fP,
+\fIcompress_motion\fP, 
+\fIcompress_exposure\fP, and \fIversion\fP).
+.IP \(bu 5
+Widget operations (for example, \fIinitialize\fP, \fIrealize\fP, \fIdestroy\fP,
+\fIresize\fP, \fIexpose\fP, \fIset_values\fP, \fIaccept_focus\fP,
+and any new operations specific to
+the widget).
+.LP
+.IN "superclass" "" "@DEF@"
+The \fIsuperclass\fP field points to the superclass
+global class
+record, declared in the superclass private .h file.
+For direct subclasses of the generic core widget,
+\fIsuperclass\fP should be initialized to the address of the
+.PN widgetClassRec
+structure.
+The superclass is used for class chaining operations and for
+inheriting or enveloping a superclass's operations
+(see Sections 1.6.7, 1.6.9, and 1.6.10).
+.LP
+.IN "class_name" "" "@DEF@"
+The \fIclass_name\fP field contains the text name for this class,
+which is used by
+the resource manager.
+For example, the Label widget has the string ``Label''.
+More than one widget class can share the same text class name.
+This string must be permanently allocated prior to or during the
+execution of the class initialization procedure and must not be
+subsequently deallocated.
+
+.LP
+.IN "widget_size" "" "@DEF@"
+The \fIwidget_size\fP field is the size of the corresponding widget
+instance structure
+(not the size of the class structure).
+.LP
+.IN "version" "" "@DEF@"
+The \fIversion\fP field indicates the toolkit
+implementation version number and is used for
+runtime consistency checking of the \*(tk and widgets in an application.
+Widget writers must set it to the
+implementation-defined symbolic value
+.PN XtVersion
+in the widget class structure initialization.
+Those widget writers who believe that their widget binaries are compatible 
+with other implementations of the \*(xI can put the special value
+.PN XtVersionDontCheck
+in the \fIversion\fP field to disable version checking for those widgets.
+If a widget needs to compile alternative code for different
+revisions of the \*(xI interface definition, it may use the symbol
+.PN XtSpecificationRelease ,
+as described in Chapter 13.
+Use of
+.PN XtVersion
+allows the \*(xI implementation to recognize widget binaries
+that were compiled with older implementations.
+.LP
+The \fIextension\fP field is for future upward compatibility.
+If the widget programmer adds fields to class parts, 
+all subclass structure layouts change,
+requiring complete recompilation. 
+To allow clients to avoid recompilation, 
+an extension field at the end of each class part can point to a record 
+that contains any additional class information required.
+.LP
+All other fields are described in their respective sections.
+.LP
+The .c file also contains the declaration of the global class
+structure pointer variable used to create instances of the class.
+The following is an abbreviated version of the .c file
+for a Label widget.
+The resources table is described in Chapter 9.
+.LP
+.Ds
+.TA .5i 1.5i 3i
+.ta .5i 1.5i 3i
+
+/* Resources specific to Label */
+static XtResource resources[] = {
+	{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
+	   XtOffset(LabelWidget, label.foreground), XtRString,
+	   XtDefaultForeground},
+	{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *),
+	   XtOffset(LabelWidget, label.font),XtRString,
+	   XtDefaultFont},
+	{XtNlabel, XtCLabel, XtRString, sizeof(String),
+	   XtOffset(LabelWidget, label.label), XtRString, NULL},
+		.
+		.
+		.
+}
+
+/* Forward declarations of procedures */
+static void ClassInitialize();
+static void Initialize();
+static void Realize();
+static void SetText();
+static void GetText();
+	.
+	.
+	.
+.De
+.sp
+.Ds
+.TA .5i 2i 3i
+.ta .5i 2i 3i
+/* Class record constant */
+LabelClassRec labelClassRec = {
+  {
+    /* core_class fields */
+	/* superclass	*/	(WidgetClass)&coreClassRec,
+	/* class_name	*/	"Label",
+	/* widget_size	*/	sizeof(LabelRec),
+	/* class_initialize	*/	ClassInitialize,
+	/* class_part_initialize	*/	NULL,
+	/* class_inited	*/	False,
+	/* initialize	*/	Initialize,
+	/* initialize_hook	*/	NULL,
+	/* realize	*/	Realize,
+	/* actions	*/	NULL,
+	/* num_actions	*/	0,
+	/* resources	*/	resources,
+	/* num_resources	*/	XtNumber(resources),
+	/* xrm_class	*/	NULLQUARK,
+	/* compress_motion	*/	True,
+	/* compress_exposure	*/	True,
+	/* compress_enterleave	*/	True,
+	/* visible_interest	*/	False,
+	/* destroy	*/	NULL,
+	/* resize	*/	Resize,
+	/* expose	*/	Redisplay,
+	/* set_values	*/	SetValues,
+	/* set_values_hook	*/	NULL,
+	/* set_values_almost	*/	XtInheritSetValuesAlmost,
+	/* get_values_hook	*/	NULL,
+	/* accept_focus	*/	NULL,
+	/* version	*/	XtVersion,
+	/* callback_offsets	*/	NULL,
+	/* tm_table	*/	NULL,
+	/* query_geometry	*/	XtInheritQueryGeometry,
+	/* display_accelerator	*/	NULL,
+	/* extension	*/	NULL
+  },
+  {
+    /* Label_class fields	*/
+	/* get_text	*/	GetText,
+	/* set_text	*/	SetText,
+	/* extension	*/	NULL
+  }
+};
+
+/* Class record pointer */
+WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec;
+
+/* New method access routines */
+void LabelSetText(w, text)
+	Widget w;
+	String text;
+{
+	LabelWidgetClass lwc = (Label WidgetClass)XtClass(w);
+	XtCheckSubclass(w, labelWidgetClass, NULL);
+	*(lwc->label_class.set_text)(w, text)
+}
+/* Private procedures */
+	.
+	.
+	.
+.De
+
+.NH 3
+Widget Class and Superclass Look Up
+.XS
+\*(SN Widget Class and Superclass Look Up
+.XE
+.LP
+To obtain the class of a widget, use
+.PN XtClass .
+.IN "XtClass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+WidgetClass XtClass(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(oI
+.LP
+.eM
+The
+.PN XtClass
+function returns a pointer to the widget's class structure.
+.sp
+.LP
+To obtain the superclass of a widget, use
+.PN XtSuperclass .
+.IN "XtSuperclass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+WidgetClass XtSuperclass(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(oI
+.LP
+.eM
+The
+.PN XtSuperclass
+function returns a pointer to the widget's superclass class structure.
+
+.NH 3
+Widget Subclass Verification
+.XS
+\*(SN Widget Subclass Verification
+.XE
+.LP
+To check the subclass to which a widget belongs, use
+.PN XtIsSubclass .
+.IN "XtIsSubclass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+Boolean XtIsSubclass(\fIw\fP, \fIwidget_class\fP)
+.br
+      Widget \fIw\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget or object instance whose class is to be checked.  \*(oI
+.IP \fIwidget_class\fP 1i
+Specifies the widget class for which to test. \*(oC
+.LP
+.eM
+The
+.PN XtIsSubclass
+function returns 
+.PN True 
+if the class of the specified widget is equal to
+or is a subclass of the specified class.
+The widget's class can be any number of subclasses down the chain
+and need not be an immediate subclass of the specified class.
+Composite widgets that need to restrict the class of the items they
+contain can use
+.PN XtIsSubclass
+to find out if a widget belongs to the desired class of objects.
+.sp
+.LP
+To test if a given widget belongs to a subclass of an \*(xI-defined
+class, the \*(xI define macros or functions equivalent to
+.PN XtIsSubclass
+for each of the built-in classes.  These procedures are
+.PN XtIsObject ,
+.PN XtIsRectObj ,
+.PN XtIsWidget ,
+.PN XtIsComposite ,
+.PN XtIsConstraint ,
+.PN XtIsShell ,
+.PN XtIsOverrideShell ,
+.PN XtIsWMShell ,
+.PN XtIsVendorShell ,
+.PN XtIsTransientShell ,
+.PN XtIsTopLevelShell ,
+.PN XtIsApplicationShell ,
+and
+.PN XtIsSessionShell .
+.IN "XtIsObject" "" "@DEF@"
+.IN "XtIsRectObj" "" "@DEF@"
+.IN "XtIsWidget" "" "@DEF@"
+.IN "XtIsComposite" "" "@DEF@"
+.IN "XtIsConstraint" "" "@DEF@"
+.IN "XtIsShell" "" "@DEF@"
+.IN "XtIsOverrideShell" "" "@DEF@"
+.IN "XtIsWMShell" "" "@DEF@"
+.IN "XtIsVendorShell" "" "@DEF@"
+.IN "XtIsTransientShell" "" "@DEF@"
+.IN "XtIsTopLevelShell" "" "@DEF@"
+.IN "XtIsApplicationShell" "" "@DEF@"
+.IN "XtIsSessionShell" "" "@DEF@"
+.LP
+All these macros and functions have the same argument description.
+.LP
+.sM
+.FD 0
+Boolean XtIs\fI<class>\fP (\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget or object instance whose class is to be checked.  \*(oI
+.LP
+.eM
+These procedures may be faster than calling
+.PN XtIsSubclass
+directly for the built-in classes.
+.sp
+.LP
+To check a widget's class
+and to generate a debugging error message, use
+.PN XtCheckSubclass ,
+defined in
+.Pn < X11/IntrinsicP.h >:
+.IN "XtCheckSubclass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+void XtCheckSubclass(\fIw\fP, \fIwidget_class\fP, \fImessage\fP)
+.br
+      Widget \fIw\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      String \fImessage\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget or object whose class is to be checked.  \*(oI
+.IP \fIwidget_class\fP 1i
+Specifies the widget class for which to test.  \*(oC
+.ds Me used
+.IP \fImessage\fP 1i
+Specifies the message to be used.
+.LP
+.eM
+The
+.PN XtCheckSubclass
+macro determines if the class of the specified widget is equal to
+or is a subclass of the specified class.
+The widget's class can be any number of subclasses down the chain
+and need not be an immediate subclass of the specified class.
+If the specified widget's class is not a subclass,
+.PN XtCheckSubclass
+constructs an error message from the supplied message,
+the widget's actual class, and the expected class and calls
+.PN XtErrorMsg .
+.PN XtCheckSubclass
+should be used at the entry point of exported routines to ensure 
+that the client has passed in a valid widget class for the exported operation.
+.LP
+.PN XtCheckSubclass
+is only executed when the module has been compiled with the compiler symbol
+DEBUG defined; otherwise, it is defined as the empty string 
+and generates no code.
+
+.NH 3
+Superclass Chaining
+.XS
+\*(SN Superclass Chaining
+.XE
+.LP
+.IN "Chaining" "superclass"
+.IN "Chaining" "Subclass"
+.IN "Superclass Chaining" "" "@DEF@"
+.IN "Subclass Chaining" "" "@DEF@"
+.IN "Inheritance"
+While most fields in a widget class structure are self-contained,
+some fields are linked to their corresponding fields in their superclass
+structures.
+With a linked field,
+the \*(xI access the field's value only after accessing its corresponding
+superclass value (called downward superclass chaining) or 
+before accessing its corresponding superclass value (called upward superclass
+chaining).  The self-contained fields are
+.sp
+.ta 2i
+In all widget classes:	\fIclass_name\fP
+.br
+	\fIclass_initialize\fP
+.br
+	\fIwidget_size\fP
+.br
+	\fIrealize\fP
+.br
+	\fIvisible_interest\fP
+.br
+	\fIresize\fP
+.br
+	\fIexpose\fP
+.br
+	\fIaccept_focus\fP
+.br
+	\fIcompress_motion\fP
+.br
+	\fIcompress_exposure\fP
+.br
+	\fIcompress_enterleave\fP
+.br
+	\fIset_values_almost\fP
+.br
+	\fItm_table\fP
+.br
+	\fIversion\fP
+.br
+	\fIallocate\fP
+.br
+	\fIdeallocate\fP
+.sp
+In Composite widget classes:	\fIgeometry_manager\fP
+.br
+	\fIchange_managed\fP
+.br
+	\fIinsert_child\fP
+.br
+	\fIdelete_child\fP
+.br
+	\fIaccepts_objects\fP
+.br
+	\fIallows_change_managed_set\fP
+.sp
+In Constraint widget classes:	\fIconstraint_size\fP
+.sp
+In Shell widget classes:	\fIroot_geometry_manager\fP
+.sp
+.LP
+With downward superclass chaining,
+the invocation of an operation first accesses the field from the
+Object,
+RectObj,
+and
+Core 
+class structures, then from the subclass structure, and so on down the class chain to
+that widget's class structure.  These superclass-to-subclass fields are
+.sp
+.ta 1i
+.br
+	\fIclass_part_initialize\fP
+.br
+	\fIget_values_hook\fP
+.br
+	\fIinitialize\fP
+.br
+	\fIinitialize_hook\fP
+.br
+	\fIset_values\fP
+.br
+	\fIset_values_hook\fP
+.br
+	\fIresources\fP
+.sp
+.LP
+In addition, for subclasses of
+Constraint,
+the following fields of the
+.PN ConstraintClassPart
+and
+.PN ConstraintClassExtensionRec
+structures are chained from the
+Constraint
+class down to the subclass:
+.ta 1i
+.br
+	\fIresources\fP
+.br
+	\fIinitialize\fP
+.br
+	\fIset_values\fP
+.br
+	\fIget_values_hook\fP
+.sp
+.LP
+With upward superclass chaining,
+the invocation of an operation first accesses the field from the widget 
+class structure, then from the superclass structure,
+and so on up the class chain to the 
+Core,
+RectObj,
+and
+Object
+class structures.
+The subclass-to-superclass fields are
+.sp
+.ta 1i
+.br
+	\fIdestroy\fP
+.br
+	\fIactions\fP
+.sp
+.LP
+For subclasses of
+Constraint,
+the following field of
+.PN ConstraintClassPart
+is chained from the subclass up to the
+Constraint class:
+.sp
+.ta 1i
+.br
+	\fIdestroy\fP
+
+.NH 3
+Class Initialization: class_initialize and class_part_initialize Procedures
+.XS
+\*(SN Class Initialization: class_initialize and class_part_initialize Procedures
+.XE
+.LP
+.IN "Class Initialization"
+.IN "Initialization"
+Many class records can be initialized completely at compile or link time.
+In some cases, however,
+a class may need to register type converters or perform other sorts of
+once-only runtime initialization.
+.LP
+Because the C language does not have initialization procedures
+that are invoked automatically when a program starts up,
+a widget class can declare a class_initialize procedure
+that will be automatically called exactly once by the \*(xI.
+A class initialization procedure pointer is of type
+.PN XtProc :
+.IN "class_initialize procedure" "" "@DEF@"
+.IN "XtProc" "" "@DEF@"
+.LP
+.sM
+.FD 0
+typedef void (*XtProc)(void);
+.FN
+.LP
+.eM
+A widget class indicates that it has no class initialization procedure by
+specifying NULL in the \fIclass_initialize\fP field.
+.LP
+In addition to the class initialization that is done exactly once,
+some classes perform initialization for fields in their parts
+of the class record.
+These are performed not just for the particular class,
+but for subclasses as well, and are
+done in the class's class part initialization procedure,
+a pointer to which is stored in the \fIclass_part_initialize\fP field.
+The class_part_initialize procedure pointer is of type
+.PN XtWidgetClassProc .
+.IN "XtWidgetClassProc" "" "@DEF@"
+.LP
+.sM
+.FD 0
+typedef void (*XtWidgetClassProc)(WidgetClass);
+.br
+      WidgetClass \fIwidget_class\fP;
+.FN
+.IP \fIwidget_class\fP 1i
+Points to the class structure for the class being initialized.
+.LP
+.eM
+During class initialization,
+the class part initialization procedures for the class and all its superclasses
+are called in superclass-to-subclass order on the class record.
+These procedures have the responsibility of doing any dynamic initializations
+necessary to their class's part of the record.
+The most common is the resolution of any inherited methods defined in the
+class.
+For example,
+if a widget class C has superclasses 
+Core, 
+Composite, 
+A, and B, the class record for C first is passed to 
+Core 's 
+class_part_initialize procedure.
+This resolves any inherited Core methods and compiles the textual
+representations of the resource list and action table that are defined in the
+class record.
+Next, Composite's 
+class_part_initialize procedure is called to initialize the
+composite part of C's class record.
+Finally, the class_part_initialize procedures for A, B, and C, in that order,
+are called.
+For further information,
+see Section 1.6.9.
+Classes that do not define any new class fields
+or that need no extra processing for them can specify NULL
+in the \fIclass_part_initialize\fP field.
+.LP
+All widget classes, whether they have a class initialization procedure or not,
+must start with their \fIclass_inited\fP field 
+.PN False .
+.LP
+The first time a widget of a class is created,
+.PN XtCreateWidget
+ensures that the widget class and all superclasses are initialized, in
+superclass-to-subclass order, by checking each \fIclass_inited\fP field and,
+if it is 
+.PN False , 
+by calling the class_initialize and the class_part_initialize procedures 
+for the class and all its superclasses.
+The \*(xI then set the \fIclass_inited\fP field to a nonzero value.
+After the one-time initialization,
+a class structure is constant.
+.LP
+The following example provides the class initialization procedure for a Label class.
+.LP
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+static void ClassInitialize()
+{
+	XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
+		NULL, 0, XtCacheNone, NULL);
+}
+.De
+
+.NH 3
+Initializing a Widget Class
+.XS
+\fB\*(SN Initializing a Widget Class\fP
+.XE
+.IN "Widget" "class initialization"
+.LP
+A class is initialized when the first widget of that class or any
+subclass is created.
+To initialize a widget class without creating any widgets, use
+.PN XtInitializeWidgetClass .
+.IN "XtInitializeWidgetClass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+void XtInitializeWidgetClass(\fIobject_class\fP)
+.br
+      WidgetClass \fIobject_class\fP;
+.br
+.FN
+.IP \fIobject_class\fP 1i
+Specifies the object class to initialize.  May be
+.PN objectClass
+or any subclass thereof.
+.LP
+.eM
+If the specified widget class is already initialized,
+.PN XtInitializeWidgetClass
+returns immediately.
+.LP
+If the class initialization procedure registers type converters, 
+these type converters are not available until the first object
+of the class or subclass is created or
+.PN XtInitializeWidgetClass
+is called
+(see Section 9.6).
+
+.NH 3
+Inheritance of Superclass Operations
+.XS
+\*(SN Inheritance of Superclass Operations
+.XE
+.LP
+A widget class is free to use any of its superclass's self-contained
+operations rather than implementing its own code.
+The most frequently inherited operations are
+.IP
+expose
+.IP
+realize
+.IP
+insert_child
+.IP
+delete_child
+.IP
+geometry_manager
+.IP
+set_values_almost
+.LP
+To inherit an operation \fIxyz\fP,
+specify the constant
+.PN XtInherit \fIXyz\fP
+in your class record.
+.LP
+Every class that declares a new procedure in its widget class part must
+provide for inheriting the procedure in its class_part_initialize
+procedure.
+The chained operations declared in Core
+and Constraint
+records are never inherited.
+Widget classes that do nothing beyond what their superclass does
+specify NULL for chained procedures
+in their class records.
+.LP
+Inheriting works by comparing the value of the field with a known, special
+value and by copying in the superclass's value for that field if a match
+occurs.
+This special value, called the inheritance constant,
+is usually the \*(xI internal value
+.PN _XtInherit
+cast to the appropriate type.
+.PN _XtInherit
+is a procedure that issues an error message if it is actually called.
+.LP
+For example,
+.PN CompositeP.h
+contains these definitions:
+.LP
+.Ds
+.TA .25i 1.5i 3i
+.ta .25i 1.5i 3i
+#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
+#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
+#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
+#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit)
+.De
+.LP
+Composite's class_part_initialize procedure begins as follows:
+.LP
+.Ds
+.TA .2i 1.5i 3i
+.ta .2i 1.5i 3i
+static void CompositeClassPartInitialize(widgetClass)
+	WidgetClass widgetClass;
+{
+	CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass;
+	CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass;
+
+	if (wc->composite_class.geometry_manager == XtInheritGeometryManager) {
+	    wc->composite_class.geometry_manager = super->composite_class.geometry_manager;
+	}
+
+	if (wc->composite_class.change_managed == XtInheritChangeManaged) {
+	    wc->composite_class.change_managed = super->composite_class.change_managed;
+	}
+	.
+	.
+	.
+.De
+.LP
+Nonprocedure fields may be inherited in the same manner as procedure
+fields.  The class may declare any reserved value it wishes for
+the inheritance constant for its new fields.  The following inheritance
+constants are defined:
+.LP
+For Object:
+.IP
+.PN XtInheritAllocate
+.IP
+.PN XtInheritDeallocate
+.LP
+For Core:
+.IP
+.PN XtInheritRealize
+.IP
+.PN XtInheritResize
+.IP
+.PN XtInheritExpose
+.IP
+.PN XtInheritSetValuesAlmost
+.IP
+.PN XtInheritAcceptFocus
+.IP
+.PN XtInheritQueryGeometry
+.IP
+.PN XtInheritTranslations
+.IP
+.PN XtInheritDisplayAccelerator
+.LP
+For Composite:
+.IP
+.PN XtInheritGeometryManager
+.IP
+.PN XtInheritChangeManaged
+.IP
+.PN XtInheritInsertChild
+.IP
+.PN XtInheritDeleteChild
+.LP
+For Shell:
+.IP
+.PN XtInheritRootGeometryManager
+
+.NH 3
+Invocation of Superclass Operations
+.XS
+\*(SN Invocation of Superclass Operations
+.XE
+.LP
+A widget sometimes needs to call a superclass operation
+that is not chained.
+For example,
+a widget's expose procedure might call its superclass's \fIexpose\fP
+and then perform a little more work on its own.
+For example, a Composite 
+class with predefined managed children can implement insert_child
+by first calling its superclass's \fIinsert_child\fP
+.IN "insert_child procedure"
+and then calling
+.PN XtManageChild
+to add the child to the managed set.
+.LP
+.NT
+A class method should not use
+.PN XtSuperclass
+but should instead call the class method of its own specific superclass
+directly through the superclass record.
+That is, it should use its own class pointers only,
+not the widget's class pointers,
+as the widget's class may be a subclass of the
+class whose implementation is being referenced.
+.NE
+This technique is referred to as \fIenveloping\fP the superclass's operation.
+
+.NH 3
+Class Extension Records
+.XS
+\*(SN Class Extension Records
+.XE
+.IN "Widget" "class extension records"
+.LP
+It may be necessary at times to add new fields to already existing
+widget class structures.  To permit this to be done without requiring
+recompilation of all subclasses, the last field in a class part structure
+should be an extension pointer.  If no extension fields for a class
+have yet been defined, subclasses should initialize the value of the
+extension pointer to NULL.
+.LP
+If extension fields exist, as is the case with the
+Composite,
+Constraint,
+and
+Shell
+classes, subclasses can provide values for these fields by setting the
+\fIextension\fP pointer for the appropriate part in their class structure to
+point to a statically declared extension record containing the
+additional fields.
+Setting the \fIextension\fP field is never mandatory; code that uses fields
+in the extension record must always check the \fIextension\fP field and take
+some appropriate default action if it is NULL.
+.LP
+In order to permit multiple subclasses and libraries to chain extension
+records from a single \fIextension\fP field, extension records should be
+declared as a linked list, and each extension record definition should
+contain the following four fields at the beginning of the structure
+declaration:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+struct {
+	XtPointer next_extension;
+	XrmQuark record_type;
+	long version;
+	Cardinal record_size;
+};
+.De
+.IP \fInext_extension\fP 1.25i
+Specifies the next record in the list, or NULL.
+.IP \fIrecord_type\fP 1.25i
+Specifies the particular structure declaration to which
+each extension record instance conforms.
+.IP \fIversion\fP 1.25i
+Specifies a version id symbolic constant supplied by
+the definer of the structure.
+.IP \fIrecord_size\fP 1.25i
+Specifies the total number of bytes allocated for the
+extension record.
+.LP
+.eM
+The \fIrecord_type\fP field identifies the contents of the extension record
+and is used by the definer of the record to locate its particular
+extension record in the list.  The
+\fIrecord_type\fP field is normally assigned the
+result of
+.PN XrmStringToQuark
+for a registered string constant.  The
+\*(xI reserve all record type strings beginning with the two
+characters ``XT'' for future standard uses.  The value
+.PN \s-1NULLQUARK\s+1
+may also be used
+by the class part owner in extension records attached to its own class
+part extension field to identify the extension record unique to that
+particular class.
+.LP
+The \fIversion\fP field is an owner-defined constant that may be used to
+identify binary files that have been compiled with alternate
+definitions of the remainder of the extension record data structure.  The private
+header file for a widget class should provide a symbolic constant for
+subclasses to use to initialize this field.
+The \fIrecord_size\fP field value includes the four common header fields and
+should normally be initialized with
+.PN sizeof ().
+.LP
+Any value stored in the class part extension fields of
+.PN CompositeClassPart ,
+.PN ConstraintClassPart ,
+or
+.PN ShellClassPart
+must point to an extension record conforming to this definition.
+.LP
+The \*(xI provide a utility function for widget writers to locate a
+particular class extension record in a linked list, given a widget class
+and the offset of the \fIextension\fP field in the class record.
+.LP
+To locate a class extension record, use
+.PN XtGetClassExtension .
+.IN "XtGetClassExtension" "" "@DEF@"
+.LP
+.sM
+.FD 0
+XtPointer XtGetClassExtension(\fIobject_class\fP, \fIbyte_offset\fP, \
+\fItype\fP, \fIversion\fP, \fIrecord_size\fP)
+.br
+      WidgetClass \fIobject_class\fP;
+.br
+      Cardinal \fIbyte_offset\fP;
+.br
+      XrmQuark \fItype\fP;
+.br
+      long \fIversion\fP;
+.br
+      Cardinal \fIrecord_size\fP;
+.FN
+.IP \fIobject_class\fP 1i
+Specifies the object class containing the extension list to be searched.
+.IP \fIbyte_offset\fP 1i
+Specifies the offset in bytes from the base of the
+class record of the extension field to be searched.
+.IP \fItype\fP 1i
+Specifies the record_type of the class extension to be located.
+.IP \fIversion\fP 1i
+Specifies the minimum acceptable version of the class
+extension required for a match.
+.IP \fIrecord_size\fP 1i
+Specifies the minimum acceptable length of the class
+extension record required for a match, or 0.
+.LP
+.eM
+The list of extension records at the specified offset in the specified
+object class will be searched for a match on the specified type,
+a version greater than or equal to the specified version, and a record
+size greater than or equal the specified record_size if it is nonzero.
+.PN XtGetClassExtension
+returns a pointer to a matching extension record or NULL if no match
+is found.  The returned extension record must not be modified or
+freed by the caller if the caller is not the extension owner.
+.bp
diff --git a/libXt/specs/CH02 b/libXt/specs/CH02
new file mode 100644
index 000000000..cbb4bb8a5
--- /dev/null
+++ b/libXt/specs/CH02
@@ -0,0 +1,3165 @@
+.\" $Xorg: CH02,v 1.3 2000/08/17 19:42:42 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\" 
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\" 
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\" 
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 2\fP\s-1
+
+\s+1\fBWidget Instantiation\fP\s-1
+.sp 2
+.nr H1 2
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 2 \(em Widget Instantiation
+.XE
+A hierarchy of widget instances constitutes a widget tree.
+The shell widget returned by
+.PN XtAppCreateShell
+is the root of the widget tree instance.
+The widgets with one or more children are the intermediate nodes of that tree,
+and the widgets with no children of any kind are the leaves of the widget tree.
+With the exception of pop-up children (see Chapter 5),
+this widget tree instance defines the associated X Window tree.
+.LP
+Widgets can be either composite or primitive.
+Both kinds of widgets can contain children,
+but the \*(xI provide a set of management mechanisms for constructing
+and interfacing between composite widgets, their children, and
+other clients.
+.LP
+Composite widgets, that is, members of the class
+.PN compositeWidgetClass ,
+are containers for an arbitrary, 
+but widget implementation-defined, collection of children,
+which may be instantiated by the composite widget itself, 
+by other clients, or by a combination of the two.
+Composite widgets also contain methods for managing the geometry (layout) 
+of any child widget.
+Under unusual circumstances,
+a composite widget may have zero children, 
+but it usually has at least one.
+By contrast, 
+primitive widgets that contain children typically instantiate 
+specific children of known classes themselves and do not expect external 
+clients to do so.
+Primitive widgets also do not have general geometry management methods.
+.LP
+In addition,
+the \*(xI recursively perform many operations 
+(for example, realization and destruction)
+on composite widgets and all their children.
+Primitive widgets that have children must be prepared 
+to perform the recursive operations themselves on behalf of their children. 
+.LP
+A widget tree is manipulated by several \*(xI functions.
+For example,
+.PN XtRealizeWidget
+traverses the tree downward and recursively realizes all 
+pop-up widgets and children of composite widgets.
+.PN XtDestroyWidget
+traverses the tree downward and destroys all pop-up widgets 
+and children of composite widgets.
+The functions that fetch and modify resources traverse the tree upward
+and determine the inheritance of resources from a widget's ancestors.
+.PN XtMakeGeometryRequest
+traverses the tree up one level and calls the geometry manager 
+that is responsible for a widget child's geometry.
+.LP
+To facilitate upward traversal of the widget tree,
+each widget has a pointer to its parent widget.
+The
+Shell 
+widget that
+.PN XtAppCreateShell 
+returns has a \fIparent\fP pointer of NULL.
+.LP
+To facilitate downward traversal of the widget tree,
+the \fIchildren\fP field of
+each composite widget is a pointer to an array of child widgets,
+which includes all normal children created,
+not just the subset of children that are managed by the composite widget's
+geometry manager.
+Primitive widgets
+that instantiate children are entirely responsible for all operations
+that require downward traversal below themselves.
+In addition,
+every widget has a pointer to an array of pop-up children.
+
+.NH 2
+Initializing the \*(tk
+.XS
+\fB\*(SN Initializing the \*(tk\fP
+.XE
+.LP
+Before an application can call any \*(xI function
+other than
+.PN XtSetLanguageProc 
+and 
+.PN XtToolkitThreadInitialize ,
+it must initialize the \*(xI by using
+.IP \(bu 5
+.PN XtToolkitInitialize ,
+which initializes the \*(xI internals
+.IP \(bu 5
+.PN XtCreateApplicationContext ,
+which initializes the per-application state
+.IP \(bu 5
+.PN XtDisplayInitialize
+or
+.PN XtOpenDisplay ,
+which initializes the per-display state
+.IP \(bu 5
+.PN XtAppCreateShell ,
+which creates the root of a widget tree
+.LP
+Or an application can call the convenience procedure
+.PN XtOpenApplication ,
+which combines the functions of the preceding procedures.
+An application wishing to use the ANSI C locale mechanism should call
+.PN XtSetLanguageProc
+prior to calling
+.PN XtDisplayInitialize ,
+.PN XtOpenDisplay ,
+.PN XtOpenApplication ,
+or 
+.PN XtAppInitialize .
+.LP
+Multiple instances of \*(tk applications may be implemented 
+in a single address space.
+Each instance needs to be able to read
+input and dispatch events independently of any other instance.
+Further, an application instance may need multiple display connections 
+to have widgets on multiple displays.
+From the application's point of view, multiple display connections
+usually are treated together as a single unit
+for purposes of event dispatching.
+.IN "application context" "" "@DEF@"
+To accommodate both requirements, 
+the \*(xI define application contexts,
+each of which provides the information needed to distinguish one application
+instance from another.
+The major component of an application context is a list of one or more X
+.PN Display
+pointers for that application.
+The \*(xI handle all display connections within a single application
+context simultaneously, handling input in a round-robin fashion.
+The application context type
+.PN XtAppContext
+.IN "XtAppContext" "" "@DEF@"
+is opaque to clients.
+.sp
+.LP
+To initialize the \*(xI internals, use
+.PN XtToolkitInitialize .
+.LP
+.IN "XtToolkitInitialize" "" "@DEF@"
+.sM
+.FD 0
+void XtToolkitInitialize()
+.FN
+.LP
+.eM
+If
+.PN XtToolkitInitialize
+was previously called, it returns immediately.
+When
+.PN XtToolkitThreadInitialize
+is called before
+.PN XtToolkitInitialize ,
+the latter is protected against
+simultaneous activation by multiple threads.
+.sp
+.LP
+To create an application context, use
+.PN XtCreateApplicationContext .
+.LP
+.IN "XtCreateApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+XtAppContext XtCreateApplicationContext()
+.FN
+.LP
+.eM
+The
+.PN XtCreateApplicationContext
+function returns an application context,
+which is an opaque type.
+Every application must have at least one application context.
+.sp
+.LP
+To destroy an application context and close any
+remaining display connections in it, use
+.PN XtDestroyApplicationContext .
+.LP
+.IN "XtDestroyApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+void XtDestroyApplicationContext(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+The
+.PN XtDestroyApplicationContext
+function destroys the specified application context.
+If called from within an event dispatch (for example, in a callback procedure),
+.PN XtDestroyApplicationContext
+does not destroy the application context until the dispatch is complete.
+.sp
+.LP
+To get the application context in which a given widget was created, use
+.PN XtWidgetToApplicationContext .
+.LP
+.IN "XtWidgetToApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+XtAppContext XtWidgetToApplicationContext(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which you want the application context.  \*(oI
+.LP
+.eM
+The
+.PN XtWidgetToApplicationContext
+function returns the application context for the specified widget.
+.sp
+.LP
+To initialize a display and add it to an application context, use
+.PN XtDisplayInitialize .
+.LP
+.IN "XtDisplayInitialize" "" "@DEF@"
+.sM
+.FD 0
+void XtDisplayInitialize(\fIapp_context\fP, \fIdisplay\fP, \
+\fIapplication_name\fP, \fIapplication_class\fP,
+.br
+                       \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      Display *\fIdisplay\fP;
+.br
+      String \fIapplication_name\fP;
+.br
+      String \fIapplication_class\fP;
+.br
+      XrmOptionDescRec *\fIoptions\fP;
+.br
+      Cardinal \fInum_options\fP;
+.br
+      int *\fIargc\fP;
+.br
+      String *\fIargv\fP;
+.FN
+.IP \fIapp_context\fP 1.4i
+Specifies the application context.
+.IP \fIdisplay\fP 1.4i
+Specifies a previously opened display connection.  Note that a single
+display connection can be in at most one application context.
+.IP \fIapplication_name\fP 1.4i
+Specifies the name of the application instance.
+.IP \fIapplication_class\fP 1.4i
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+.IP \fIoptions\fP 1.4i
+Specifies how to parse the command line for any application-specific resources.
+The \fIoptions\fP argument is passed as a parameter to
+.PN XrmParseCommand .
+For further information,
+see Section 15.9 in \fI\*(xL\fP and Section 2.4 of this specification.
+.IP \fInum_options\fP 1.4i
+Specifies the number of entries in the options list.
+.IP \fIargc\fP 1.4i
+Specifies a pointer to the number of command line parameters.
+.IP \fIargv\fP 1.4i
+Specifies the list of command line parameters.
+.LP
+.eM
+The
+.PN XtDisplayInitialize
+function retrieves the language string to be
+used for the specified display (see Section 11.11),
+calls the language procedure (if set) with that language string,
+builds the resource database for the default screen, calls the Xlib
+.PN XrmParseCommand
+function to parse the command line, 
+and performs other per-display initialization.
+After 
+.PN XrmParseCommand 
+has been called,
+\fIargc\fP and \fIargv\fP contain only those parameters that
+were not in the standard option table or in the table specified by the
+\fIoptions\fP argument.
+If the modified \fIargc\fP is not zero,
+most applications simply print out the modified \fIargv\fP along with a message
+listing the allowable options.
+On POSIX-based systems,
+the application name is usually the final component of \fIargv\fP[0].
+If the synchronous resource is
+.PN True ,
+.PN XtDisplayInitialize
+calls the Xlib
+.PN XSynchronize
+function to put Xlib into synchronous mode for this display connection
+and any others currently open in the application context.
+See Sections 2.3 and 2.4 for details on the \fIapplication_name\fP,
+\fIapplication_class\fP, \fIoptions\fP, and \fInum_options\fP arguments.
+.LP
+.PN XtDisplayInitialize
+calls
+.PN XrmSetDatabase
+to associate the resource database of the default screen with the
+display before returning.
+
+.KS
+.LP
+To open a display, initialize it, and then
+add it to an application context, use 
+.PN XtOpenDisplay .
+.LP
+.IN "XtOpenDisplay" "" "@DEF@"
+.sM
+.FD 0
+Display *XtOpenDisplay(\fIapp_context\fP, \fIdisplay_string\fP, \
+\fIapplication_name\fP, \fIapplication_class\fP, 
+.br
+                       \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
+.br
+       XtAppContext \fIapp_context\fP;
+.br
+       String \fIdisplay_string\fP;
+.br
+       String \fIapplication_name\fP;
+.br
+       String \fIapplication_class\fP;
+.br
+       XrmOptionDescRec *\fIoptions\fP;
+.br
+       Cardinal \fInum_options\fP;
+.br
+       int *\fIargc\fP;
+.br
+       String *\fIargv\fP;
+.FN
+.IP \fIapp_context\fP 1.4i
+Specifies the application context.
+.IP \fIdisplay_string\fP 1.4i
+Specifies the display string, or NULL.
+.IP \fIapplication_name\fP 1.4i
+Specifies the name of the application instance, or NULL.
+.IP \fIapplication_class\fP 1.4i
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+.IP \fIoptions\fP 1.4i
+Specifies how to parse the command line for any application-specific resources.
+The options argument is passed as a parameter to
+.PN XrmParseCommand .
+.IP \fInum_options\fP 1.4i
+Specifies the number of entries in the options list.
+.IP \fIargc\fP 1.4i
+Specifies a pointer to the number of command line parameters.
+.IP \fIargv\fP 1.4i
+Specifies the list of command line parameters.
+.KE
+.LP
+.eM
+The
+.PN XtOpenDisplay
+function calls
+.PN XOpenDisplay 
+with the specified \fIdisplay_string\fP.
+If \fIdisplay_string\fP is NULL,
+.PN XtOpenDisplay
+uses the current value of the \-display option specified in \fIargv\fP.
+If no display is specified in \fIargv\fP,
+the user's default display is retrieved from the environment.
+On POSIX-based systems, 
+this is the value of the
+.PN \s-1DISPLAY\s+1
+environment variable.
+.LP
+If this succeeds,
+.PN XtOpenDisplay
+then calls
+.PN XtDisplayInitialize
+and passes it the opened display and
+the value of the \-name option specified in \fIargv\fP as the application name.
+If no \-name option is specified
+and \fIapplication_name\fP is
+non-NULL, \fIapplication_name\fP is passed to
+.PN XtDisplayInitialize .
+If \fIapplication_name\fP is NULL and if the environment variable
+.PN \s-1RESOURCE_NAME\s+1
+is set, the value of
+.PN \s-1RESOURCE_NAME\s+1
+is used.  Otherwise, the application
+name is the name used to invoke the program.  On implementations that
+conform to ANSI C Hosted Environment support, the application name will
+be \fIargv\fP[0] less any directory and file type components, that is, the
+final component of \fIargv\fP[0], if specified.  If \fIargv\fP[0] does not exist or
+is the empty string, the application name is ``main''.
+.PN XtOpenDisplay
+returns the newly opened display or NULL if it failed.
+.LP
+See Section 7.12 for information regarding the use of
+.PN XtOpenDisplay
+in multiple threads.
+.sp
+.LP
+To close a display and remove it from an application context, use
+.PN XtCloseDisplay .
+.LP
+.IN "XtCloseDisplay" "" "@DEF@"
+.sM
+.FD 0
+void XtCloseDisplay(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display.
+.LP
+.eM
+The
+.PN XtCloseDisplay
+function calls
+.PN XCloseDisplay
+with the specified \fIdisplay\fP as soon as it is safe to do so.
+If called from within an event dispatch (for example, a callback procedure),
+.PN XtCloseDisplay
+does not close the display until the dispatch is complete.
+Note that applications need only call
+.PN XtCloseDisplay
+if they are to continue executing after closing the display; 
+otherwise, they should call
+.PN XtDestroyApplicationContext .
+.LP
+See Section 7.12 for information regarding the use of 
+.PN XtCloseDisplay
+in multiple threads.
+
+.NH 2
+Establishing the Locale
+.XS
+\fB\*(SN Establishing the Locale\fP
+.XE
+.LP
+Resource databases are specified to be created in the current process
+locale.  During display initialization prior to creating the
+per-screen resource database, the \*(xI will call out to a specified
+application procedure to set the locale according to options found on
+the command line or in the per-display resource specifications.
+.LP
+The callout procedure provided by the application is of type
+.PN XtLanguageProc .
+.LP
+.IN "XtLanguageProc" "" "@DEF@"
+.sM
+.FD 0
+typedef String (*XtLanguageProc)(Display*, String, XtPointer);
+.br
+      Display *\fIdisplay\fP;
+.br
+      String \fIlanguage\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Passes the display.
+.IP \fIlanguage\fP
+Passes the initial language value obtained from the command line
+or server per-display resource specifications.
+.IP \fIclient_data\fP
+Passes the additional client data specified in the call to
+.PN XtSetLanguageProc .
+.LP
+.eM
+The language procedure allows an application to set the locale to
+the value of the language resource determined by
+.PN XtDisplayInitialize .
+The function returns a new language string that
+will be subsequently used by
+.PN XtDisplayInitialize
+to establish the path for loading resource files.  The returned
+string  will be copied by the \*(xI into new memory.
+.LP
+Initially, no language procedure is set by the \*(xI.
+To set the language procedure for use by
+.PN XtDisplayInitialize ,
+use
+.PN XtSetLanguageProc .
+.LP
+.IN XtSetLanguageProc "" "@DEF@"
+.IN "language procedure" "" "@DEF@"
+.sM
+.FD 0
+XtLanguageProc XtSetLanguageProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtLanguageProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context in which the language procedure is
+to be used, or NULL.
+.IP \fIproc\fP 1i
+Specifies the language procedure.
+.IP \fIclient_data\fP 1i
+Specifies additional client data to be passed to the language
+procedure when it is called.
+.LP
+.eM
+.PN XtSetLanguageProc
+sets the language procedure that will be called from
+.PN XtDisplayInitialize
+for all subsequent Displays initialized in the specified application
+context.   If \fIapp_context\fP is NULL, the specified language
+procedure is registered in all application contexts created by the
+calling process, including any future application contexts that may
+be created.   If \fIproc\fP is NULL, a default language procedure is
+registered.
+.PN XtSetLanguageProc
+returns the previously registered language procedure.
+If a language procedure has not yet been registered, the return value
+is unspecified, but if this return value is used in a subsequent call to
+.PN XtSetLanguageProc ,
+it will cause the default language procedure to be registered.
+.LP
+The default language procedure does the following:
+.IP \(bu 5
+Sets the locale according to the environment.  On ANSI C-based
+systems this is done by calling
+.PN setlocale (
+.PN LC_ALL ,
+\fIlanguage\fP ).
+If an error is encountered, a warning message is issued with
+.PN XtWarning .
+.IP \(bu 5
+Calls
+.PN XSupportsLocale
+to verify that the current locale is supported.
+If the locale is not supported, a warning message is issued with
+.PN XtWarning
+and the locale is set to ``C''.
+.IP \(bu 5
+Calls
+.PN XSetLocaleModifiers
+specifying the empty string.
+.IP \(bu 5
+Returns the value of the current locale.  On ANSI C-based systems this
+is the return value from a final call to
+.PN setlocale (
+.PN LC_ALL ,
+NULL ).
+.LP
+A client wishing to use this mechanism to establish locale can do so
+by calling
+.PN XtSetLanguageProc
+prior to
+.PN XtDisplayInitialize ,
+as in the following example.
+.LP
+.Ds 0
+.TA .5i
+	Widget top;
+	XtSetLanguageProc(NULL, NULL, NULL);
+	top = XtOpenApplication(...);
+	...
+.De
+
+.NH 2
+Loading the Resource Database
+.XS
+\fB\*(SN Loading the Resource Database\fP
+.XE
+.LP
+The
+.PN XtDisplayInitialize
+function first determines the language
+string to be used for the specified display.  It then
+creates a resource database for the default screen of the display by
+combining the following sources in order, with the entries in the
+first named source having highest precedence:
+
+.IP \(bu 5
+Application command line (\fIargc\fP, \fIargv\fP).
+.IP \(bu 5
+Per-host user environment resource file on the local host.
+.IP \(bu 5
+Per-screen resource specifications from the server.
+.IP \(bu 5
+Per-display resource specifications from the server or from
+.br
+the user preference file on the local host.
+.IP \(bu 5
+Application-specific user resource file on the local host.
+.IP \(bu 5
+Application-specific class resource file on the local host.
+
+.LP
+When the resource database for a particular screen on the display
+is needed (either internally, or when
+.PN XtScreenDatabase
+is called),
+it is created in the following manner using the sources listed
+above in the same order:
+
+.IP \(bu 5
+A temporary database, the ``server resource database'', is
+created from the string returned by
+.PN XResourceManagerString
+or, if
+.PN XResourceManagerString
+returns NULL, the contents of a resource file in the user's home
+directory.  On POSIX-based systems, the usual name for this user
+preference resource file is $HOME/\fB.Xdefaults\fP.
+.IN ".Xdefaults" "" "@DEF@"
+
+.IP \(bu 5
+If a language procedure has been set,
+.PN XtDisplayInitialize
+first searches the command line for the option ``-xnlLanguage'', or
+for a -xrm option that specifies the xnlLanguage/XnlLanguage resource,
+as specified by Section 2.4.
+If such a resource is found, the value is assumed to be
+entirely in XPCS, the X Portable Character Set.  If neither option is
+specified on the command line,
+.PN XtDisplayInitialize
+queries the server resource database (which is assumed to be entirely
+in XPCS) for the resource
+\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
+where \fIname\fP
+.IN "xnlLanguage" "" "@DEF@"
+.IN "Resources" "xnlLanguage"
+and \fIClass\fP are the \fIapplication_name\fP and
+\fIapplication_class\fP specified to
+.PN XtDisplayInitialize .
+The language procedure is then invoked with
+the resource value if found, else the empty string.  The
+string returned from the language procedure is saved for all future
+references in the \*(xI that require the per-display language string.
+
+.IP \(bu 5
+The screen resource database is initialized by parsing the command
+line in the manner specified by Section 2.4.
+
+.IP \(bu 5
+If a language procedure has not been set,
+the initial database is then queried for the resource
+\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
+as specified above.
+If this database query fails, the server resource database is
+queried; if this query also fails, the language is determined from
+the environment; on POSIX-based systems, this is done by retrieving the
+value of the
+.PN \s-1LANG\s+1
+environment variable.  If no language string is
+found, the empty string is used.
+This language string is saved for all future references in the \*(xI
+that require the per-display language string.
+
+.IP \(bu 5
+After determining the language string, the user's environment resource
+file is then merged into the initial resource database if the file exists.
+This file is user-, host-, and process-specific and is expected to
+contain user preferences that are to override those specifications in
+the per-display and per-screen resources.
+On POSIX-based systems, the user's environment resource file name is
+specified by the value of the
+.PN \s-1XENVIRONMENT\s+1
+environment variable.
+If this environment variable does not exist, the user's home directory
+is searched for a file named
+.PN \&.Xdefaults-\fIhost\fP ,
+where \fIhost\fP is the host name of the machine on which the
+application is running.
+
+.IP \(bu 5
+The per-screen resource specifications are then merged into the screen
+resource database, if they exist.  These specifications are the string
+returned by
+.PN XScreenResourceString
+for the respective screen and are owned entirely by the user.
+
+.IP \(bu 5
+Next, the server resource database created earlier is merged into the
+screen resource database.  The server property, and corresponding user
+preference file, are owned and constructed entirely by the user.
+
+.IP \(bu 5
+The application-specific user resource file from the local host is
+then merged into the screen resource database.
+This file contains user customizations and is stored
+in a directory owned by the user.
+Either the user or the application or both can store resource specifications
+in the file.  Each should be prepared to find and respect entries made
+by the other.
+The file name is found by calling
+.PN XrmSetDatabase
+with the current screen resource database, after preserving the
+original display-associated database, then calling
+.PN XtResolvePathname
+with the parameters
+(\fIdisplay\fP, NULL, NULL, NULL, \fIpath\fP, NULL, 0, NULL),
+where \fIpath\fP is defined in an operating-system-specific way.
+On POSIX-based systems, \fIpath\fP is defined to be the value
+of the environment variable
+.PN \s-1XUSERFILESEARCHPATH\s+1
+if this is defined.  If
+.PN \s-1XUSERFILESEARCHPATH\s+1
+is not defined, an implementation-dependent default value is used.
+This default value is constrained in the following manner:
+
+.RS
+.IP \- 3
+If the environment variable
+.PN \s-1XAPPLRESDIR\s+1
+is not defined, the default
+.PN \s-1XUSERFILESEARCHPATH\s+1
+must contain at least six entries.  These entries must contain
+.IN "XUSERFILESEARCHPATH" "" "@DEF@"
+.IN "XAPPLRESDIR" "" "@DEF@"
+.IN "$HOME"
+$HOME as the directory prefix, plus the following substitutions:
+
+.nf
+.ta .3i 1.5i 2i
+1.	%C, %N, %L	or	%C, %N, %l, %t, %c
+2.	%C, %N, %l
+3.	%C, %N
+4.	%N, %L	or	%N, %l, %t, %c
+5.	%N, %l
+6.	%N
+.fi
+
+The order of these six entries within the path must be as given above.
+The order and use of substitutions within a given entry are
+implementation-dependent.
+
+.IP \- 3
+If
+.PN \s-1XAPPLRESDIR\s+1
+is defined, the default
+.PN \s-1XUSERFILESEARCHPATH\s+1
+must contain at least seven entries.  These entries must contain the
+following directory prefixes and substitutions:
+
+.ne 1.1
+.nf
+.ta .3i 1.6i 2.2i 3.3i 3.7i
+1.	$XAPPLRESDIR	with	%C, %N, %L	or	%C, %N, %l, %t, %c
+2.	$XAPPLRESDIR	with	%C, %N, %l
+3.	$XAPPLRESDIR	with	%C, %N
+4.	$XAPPLRESDIR	with	%N, %L	or	%N, %l, %t, %c
+5.	$XAPPLRESDIR	with	%N, %l
+6.	$XAPPLRESDIR	with	%N
+7.	$HOME	with	%N
+.fi
+
+The order of these seven entries within the path must be as given above.
+The order and use of substitutions within a given entry are
+implementation-dependent.
+.RE
+
+.IP \(bu 5
+Last, the application-specific class resource file from the local
+host is merged into the screen resource database.
+This file is owned by the application and is usually installed in
+a system directory when the application is installed.
+It may contain sitewide customizations specified by the system manager.
+The name of the application class resource file is found by calling
+.PN XtResolvePathname
+with the parameters
+(\fIdisplay\fP, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL).
+This file is expected to be provided by the developer of the application
+and may be required for the application to function properly.
+A simple application that wants to be assured of having a minimal
+set of resources in the absence of its class resource file can declare
+fallback resource specifications with
+.PN XtAppSetFallbackResources .
+Note that the customization substitution string is retrieved
+dynamically by
+.PN XtResolvePathname
+so that the resolved file name of the application class resource file
+can be affected by any of the earlier sources for the screen resource
+database, even though the contents of the class resource file have
+lowest precedence.  After calling
+.PN XtResolvePathname ,
+the original display-associated database is restored.
+.sp
+.LP
+To obtain the resource database for a particular screen, use
+.PN XtScreenDatabase .
+.LP
+.IN "XtScreenDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XtScreenDatabase(\fIscreen\fP)
+.br
+      Screen *\fIscreen\fP;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the screen whose resource database is to be returned.
+.LP
+.eM
+The
+.PN XtScreenDatabase
+function returns the fully merged resource database as specified above,
+associated with the specified screen.  If the specified \fIscreen\fP
+does not belong to a
+.PN Display
+initialized by
+.PN XtDisplayInitialize ,
+the results are undefined.
+.sp
+.LP
+To obtain the default resource database associated with a particular display, use
+.PN XtDatabase .
+.LP
+.IN "XtDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XtDatabase(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display.
+.LP
+.eM
+The
+.PN XtDatabase
+function is equivalent to
+.PN XrmGetDatabase .
+It returns the database associated with the specified display, or
+NULL if a database has not been set.
+.sp
+.LP
+To specify a default set of resource values that will be used to
+initialize the resource database if no application-specific class
+resource file is found (the last of the six sources listed above),
+use
+.PN XtAppSetFallbackResources .
+.LP
+.IN "XtAppSetFallbackResources" "" "@DEF@"
+.sM
+.FD 0
+void XtAppSetFallbackResources(\fIapp_context\fP, \fIspecification_list\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String *\fIspecification_list\fP;
+.FN
+.IP \fIapp_context\fP 1.25i
+Specifies the application context in which
+the fallback specifications will be used.
+.IP \fIspecification_list\fP 1.25i
+Specifies a NULL-terminated list of
+resource specifications to preload
+the database, or NULL.
+.LP
+.eM
+Each entry in \fIspecification_list\fP points to a string in the format of
+.PN XrmPutLineResource .
+Following a call to
+.PN XtAppSetFallbackResources ,
+when a resource database is being created for a particular screen and
+the \*(xI are not able
+to find or read an application-specific class resource file according to the
+rules given above and if \fIspecification_list\fP is not NULL, the
+resource specifications in \fIspecification_list\fP will be merged
+into the screen resource database in place of the application-specific
+class resource file.
+.PN XtAppSetFallbackResources
+is not
+required to copy \fIspecification_list\fP; the caller must ensure that the
+contents of the list and of the strings addressed by the list remain
+valid until all displays are initialized or until
+.PN XtAppSetFallbackResources
+is called again.  The value NULL for
+\fIspecification_list\fP removes any previous fallback resource specification
+for the application context.  The intended use for fallback resources
+is to provide a minimal
+number of resources that will make the application usable (or at
+least terminate with helpful diagnostic messages) when some problem
+exists in finding and loading the application defaults file.
+
+.NH 2
+Parsing the Command Line
+.XS
+\fB\*(SN Parsing the Command Line\fP
+.XE
+.LP
+The
+.PN XtOpenDisplay
+function first parses the command line for the following options:
+.IP \-display 1i
+Specifies the display name for
+.PN XOpenDisplay .
+.IP \-name 1i
+Sets the resource name prefix, 
+which overrides the application name passed to
+.PN XtOpenDisplay .
+.IP \-xnllanguage 1i
+Specifies the initial language string for establishing locale
+and for finding application class resource files.
+.LP
+.PN XtDisplayInitialize
+has a table of standard command line options that are passed to
+.PN XrmParseCommand
+for adding resources to the resource database, 
+and it takes as a parameter additional
+application-specific resource abbreviations.
+.IN "XrmOptionDescRec" "" "@DEF@"
+The format of this table is described in Section 15.9 in \fI\*(xL\fP.
+.LP
+.sM
+.Ds 0
+.TA .5i 2.75i
+.ta .5i 2.75i
+typedef enum {
+	XrmoptionNoArg,	/* Value is specified in OptionDescRec.value */
+	XrmoptionIsArg,	/* Value is the option string itself */
+	XrmoptionStickyArg,	/* Value is characters immediately following option */
+	XrmoptionSepArg,	/* Value is next argument in argv */
+	XrmoptionResArg,	/* Use the next argument as input to XrmPutLineResource*/
+	XrmoptionSkipArg,	/* Ignore this option and the next argument in argv */
+	XrmoptionSkipNArgs,	/* Ignore this option and the next */
+		/* OptionDescRec.value arguments in argv */
+	XrmoptionSkipLine	/* Ignore this option and the rest of argv */
+} XrmOptionKind;
+
+typedef struct {
+	char *option;	/* Option name in argv */
+	char *specifier;	/* Resource name (without application name) */
+	XrmOptionKind argKind;	/* Location of the resource value */
+	XPointer value;	/* Value to provide if XrmoptionNoArg */
+} XrmOptionDescRec, *XrmOptionDescList;
+
+.De
+.LP
+.eM
+The standard table contains the following entries:
+.TS H
+l l l l .
+_
+.sp 6p
+.TH
+Option String	Resource Name	Argument Kind	Resource Value
+.sp 6p
+_
+.sp 6p
+\-background	*background	SepArg	next argument
+\-bd	*borderColor	SepArg	next argument
+\-bg	*background	SepArg	next argument
+\-borderwidth	.borderWidth	SepArg	next argument
+\-bordercolor	*borderColor	SepArg	next argument
+\-bw	.borderWidth	SepArg	next argument
+\-display	.display	SepArg	next argument
+\-fg	*foreground	SepArg	next argument
+\-fn	*font	SepArg	next argument
+\-font	*font	SepArg	next argument
+\-foreground	*foreground	SepArg	next argument
+\-geometry	.geometry	SepArg	next argument
+\-iconic	.iconic	NoArg	``true''
+\-name	.name	SepArg	next argument
+\-reverse	.reverseVideo	NoArg	``on''
+\-rv	.reverseVideo	NoArg	``on''
++rv	.reverseVideo	NoArg	``off''
+\-selectionTimeout	.selectionTimeout	SepArg	next argument
+\-synchronous	.synchronous	NoArg	``on''
++synchronous	.synchronous	NoArg	``off''
+\-title	.title	SepArg	next argument
+\-xnllanguage	.xnlLanguage	SepArg	next argument
+\-xrm	next argument	ResArg	next argument
+\-xtsessionID	.sessionID	SepArg	next argument
+.sp 6p
+_
+.TE
+.LP
+Note that any unique abbreviation for an option name in the standard table
+or in the application table is accepted.
+.LP
+If reverseVideo is
+.PN True ,
+the values of
+.PN XtDefaultForeground
+and
+.PN XtDefaultBackground
+are exchanged for all screens on the Display.
+.LP
+.IN "synchronous" "" "@DEF@"
+.IN "Resources" "synchronous"
+The value of the synchronous resource specifies whether or not
+Xlib is put into synchronous mode.  If a value is found in the resource
+database during display initialization,
+.PN XtDisplayInitialize
+makes a call to
+.PN XSynchronize
+for all display
+connections currently open in the application context.  Therefore,
+when multiple displays are initialized in the same application
+context, the most recent value specified for the synchronous resource
+is used for all displays in the application context.
+.LP
+.IN "selectionTimeout" "" "@DEF@"
+.IN "Resources" "selectionTimeout"
+The value of the selectionTimeout resource applies to all displays
+opened in the same application context.  When multiple displays are
+initialized in the same application context, the most recent value
+specified is used for all displays in the application context.
+.LP
+The \-xrm option provides a method of setting any resource in an application.
+The next argument should be a quoted string identical in format to a line in
+the user resource file.
+For example,
+to give a red background to all command buttons in an application named
+.PN xmh ,
+you can start it up as
+.LP
+.Ds
+xmh \-xrm 'xmh*Command.background: red'
+.DE
+.LP
+When it parses the command line,
+.PN XtDisplayInitialize
+merges the application option table with the standard option table
+before calling the Xlib
+.PN XrmParseCommand
+function.
+An entry in the application table with the same name as an entry
+in the standard table overrides the standard table entry.
+If an option name is a prefix of another option name,
+both names are kept in the merged table.
+The \*(xI reserve all option names
+beginning with the characters ``-xt'' for future standard uses.
+
+.NH 2
+Creating Widgets
+.XS
+\fB\*(SN Creating Widgets\fP
+.XE
+.LP
+The creation of widget instances is a three-phase process:
+.IP 1. 5
+The widgets are allocated and initialized with resources
+and are optionally added to the managed subset of their parent.
+.IP 2. 5
+All composite widgets are notified of their managed children
+in a bottom-up traversal of the widget tree.
+.IP 3. 5
+The widgets create X windows, which then are mapped.
+.LP
+.EQ
+delim $$
+.EN
+To start the first phase, 
+the application calls
+.PN XtCreateWidget
+for all its widgets and adds some (usually, most or all) of its widgets
+to their respective parents' managed set by calling
+.PN XtManageChild .
+To avoid an $O( n sup 2 )$ creation process where each composite widget 
+lays itself out each time a widget is created and managed,
+parent widgets are not notified of changes in their managed set
+during this phase.
+.EQ
+delim off
+.EN
+.LP
+After all widgets have been created,
+the application calls
+.PN XtRealizeWidget
+with the top-level widget to execute the second and third phases.
+.PN XtRealizeWidget
+first recursively traverses the widget tree in a postorder (bottom-up)
+traversal and then notifies each composite widget with one
+or more managed children by means of its change_managed procedure.
+.LP
+Notifying a parent about its managed set involves geometry layout and
+possibly geometry negotiation.
+A parent deals with constraints on its size imposed from above
+(for example, when a user specifies the application window size)
+and suggestions made from below (for example, 
+when a primitive child computes its preferred size).
+One difference between the two can cause geometry changes to ripple
+in both directions through the widget tree.
+The parent may force some of its children to change size and position
+and may issue geometry requests to its own parent in order to better
+accommodate all its children.
+You cannot predict where anything will go on the screen
+until this process finishes.
+.LP
+Consequently, in the first and second phases,
+no X windows are actually created, because it is likely
+that they will get moved around after creation.
+This avoids unnecessary requests to the X server.
+.LP
+Finally,
+.PN XtRealizeWidget
+starts the third phase by making a preorder (top-down) traversal 
+of the widget tree, allocates an X window to each widget by means of 
+its realize procedure, and finally maps the widgets that are managed.
+
+.NH 3
+Creating and Merging Argument Lists
+.XS
+\fB\*(SN Creating and Merging Argument Lists\fP
+.XE
+.LP
+Many \*(xI functions may be passed pairs of resource names and
+values.
+These are passed as an arglist, a pointer to an array of
+.PN Arg
+structures, which contains
+.IN "ArgList" "" "@DEF@"
+.IN "Arg" "" "@DEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String name;
+	XtArgVal value;
+} Arg, *ArgList;
+.De
+.LP
+.eM
+where
+.PN XtArgVal
+is as defined in Section 1.5.
+.LP
+If the size of the resource is less than or equal to the size of an
+.PN XtArgVal ,
+the resource value is stored directly in \fIvalue\fP;
+otherwise, a pointer to it is stored in \fIvalue\fP.
+.LP
+To set values in an
+.PN ArgList ,
+use
+.PN XtSetArg .
+.LP
+.IN "XtSetArg" "" "@DEF@"
+.sM
+.FD 0
+void XtSetArg(\fIarg\fP, \fIname\fP, \fIvalue\fP)
+.br
+      Arg \fIarg\fP;
+.br
+      String \fIname\fP;
+.br
+      XtArgVal \fIvalue\fP;
+.FN
+.IP \fIarg\fP 1i
+Specifies the \fIname/value\fP pair to set.
+.IP \fIname\fP 1i
+Specifies the name of the resource.
+.IP \fIvalue\fP 1i
+Specifies the value of the resource if it will fit in an
+.PN XtArgVal ,
+else the address.
+.LP
+.eM
+The
+.PN XtSetArg
+function is usually used in a highly stylized manner to
+minimize the probability of making a mistake; for example:
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+Arg args[20];
+int n;
+
+n = 0;
+XtSetArg(args[n], XtNheight, 100);	n++;
+XtSetArg(args[n], XtNwidth, 200);	n++;
+XtSetValues(widget, args, n);
+.De
+.LP
+Alternatively, an application can statically declare the argument list
+and use
+.PN XtNumber :
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+static Args args[] = {
+	{XtNheight, (XtArgVal) 100},
+	{XtNwidth, (XtArgVal) 200},
+};
+XtSetValues(Widget, args, XtNumber(args));
+.De
+.LP
+Note that you should not use expressions with side effects such as
+auto-increment or auto-decrement
+within the first argument to
+.PN XtSetArg .
+.PN XtSetArg
+can be implemented as a macro that evaluates the first argument twice.
+.sp
+.LP
+To merge two
+arglist arrays, use
+.PN XtMergeArgLists .
+.LP
+.IN "XtMergeArgLists" "" "@DEF@"
+.sM
+.FD 0
+ArgList XtMergeArgLists(\fIargs1\fP, \fInum_args1\fP, \fIargs2\fP, \
+\fInum_args2\fP)
+.br
+     ArgList \fIargs1\fP;
+.br
+     Cardinal \fInum_args1\fP;
+.br
+     ArgList \fIargs2\fP;
+.br
+     Cardinal \fInum_args2\fP;
+.FN
+.IP \fIargs1\fP 1i
+Specifies the first argument list.
+.IP \fInum_args1\fP 1i
+Specifies the number of entries in the first argument list.
+.IP \fIargs2\fP 1i
+Specifies the second argument list.
+.IP \fInum_args2\fP 1i
+Specifies the number of entries in the second argument list.
+.LP
+.eM
+The
+.PN XtMergeArgLists
+function allocates enough storage to hold the combined
+arglist arrays and copies them into it.
+Note that it does not check for duplicate entries.
+The length of the returned list is the sum of the lengths of the
+specified lists.
+When it is no longer needed,
+free the returned storage by using
+.PN XtFree .
+.sp
+.LP
+.IN "varargs" "" "@DEF@"
+All \*(xI interfaces that require
+.PN ArgList
+arguments have analogs
+conforming to the ANSI C variable argument list
+(traditionally called ``varargs'')
+calling convention.  The name of the analog is formed by prefixing
+``Va'' to the name of the corresponding
+.PN ArgList
+procedure; e.g.,
+.PN XtVaCreateWidget .
+Each procedure named \fBXtVa\fP\fIsomething\fP takes as its
+last arguments, in place of the corresponding
+.PN ArgList /
+.PN Cardinal
+parameters, a variable parameter list of resource name and
+value pairs where each name is of type
+.PN String
+and each value is of type
+.PN XtArgVal .
+The end of the list is identified by a \fIname\fP entry
+containing NULL.  Developers writing in the C language wishing to pass
+resource name and value pairs to any of these interfaces may use the
+.PN ArgList
+and varargs forms interchangeably.
+.LP
+Two special names are defined for use only in varargs lists:
+.PN XtVaTypedArg
+and
+.PN XtVaNestedList .
+.sp
+.LP
+.IN "XtVaTypedArg" "" "@DEF@"
+.sM
+.Ds 0
+#define XtVaTypedArg "XtVaTypedArg"
+.De
+.LP
+.eM
+If the name
+.PN XtVaTypedArg
+is specified in place of a resource
+name, then the following four arguments are interpreted as a
+\fIname/type/value/size\fP tuple \fIwhere\fP name is of type
+.PN String ,
+\fItype\fP is of type
+.PN String ,
+\fIvalue\fP is of type
+.PN XtArgVal ,
+and \fIsize\fP is of type int.  When a varargs list containing
+.PN XtVaTypedArg
+is processed, a resource type
+conversion (see Section 9.6) is performed if necessary to convert the
+value into the format required by the associated resource.  If \fItype\fP is
+XtRString, then \fIvalue\fP contains a pointer to the string and \fIsize\fP
+contains the number of bytes allocated, including the trailing null
+byte.  If \fItype\fP is not XtRString, then \fIif\fP size is
+less than or equal to
+\fBsizeof\fP(\fBXtArgVal\fP), the value should be the data cast to the type
+.PN XtArgVal ,
+otherwise \fIvalue\fP is a pointer to the data.  If the type
+conversion fails for any reason, a warning message is issued and the
+list entry is skipped.
+.sp
+.LP
+.IN "XtVaNestedList" "" "@DEF@"
+.sM
+.Ds 0
+#define XtVaNestedList  "XtVaNestedList"
+.De
+.LP
+.eM
+If the name
+.PN XtVaNestedList
+is specified in place of a resource name,
+then the following argument is interpreted as an
+.PN XtVarArgsList
+value, which specifies another
+varargs list that is logically inserted into the original list at the
+point of declaration.  The end of the nested list is identified with a
+name entry containing NULL.  Varargs lists may nest to any depth.
+.sp
+.LP
+To dynamically allocate a varargs list for use with
+.PN XtVaNestedList
+in multiple calls, use
+.PN XtVaCreateArgsList .
+.IN "XtVaCreateArgsList" "" "@DEF@"
+.sp
+.LP
+.sM
+.Ds 0
+typedef XtPointer XtVarArgsList;
+.De
+.LP
+.FD 0
+XtVarArgsList XtVaCreateArgsList(\fIunused\fP, ...)
+.br
+      XtPointer \fIunused\fP;
+.FN
+.IP \fIunused\fP 1i
+This argument is not currently used and must be specified as NULL.
+.IP ... 1i
+Specifies a variable parameter list of resource
+name and value pairs.
+.LP
+.eM
+The
+.PN XtVaCreateArgsList
+function allocates memory and copies its arguments into a
+single list pointer, which may be used with
+.PN XtVaNestedList .
+The end of
+both lists is identified by a \fIname\fP entry containing NULL.  Any entries
+of type
+.PN XtVaTypedArg
+are copied as specified without applying
+conversions.  Data passed by reference (including Strings) are not
+copied, only the pointers themselves; the caller must ensure that the
+data remain valid for the lifetime of the created varargs list.  The
+list should be freed using
+.PN XtFree
+when no longer needed.
+.LP
+Use of resource files and of the resource database is generally
+encouraged over lengthy arglist or varargs lists whenever possible in
+order to permit modification without recompilation.
+
+.NH 3
+Creating a Widget Instance
+.XS
+\fB\*(SN Creating a Widget Instance\fP
+.XE
+.LP
+To create an instance of a widget, use
+.PN XtCreateWidget .
+.LP
+.IN "XtCreateWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIobject_class\fP;
+.br
+      Widget \fIparent\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the resource instance name for the created widget,
+which is used for retrieving resources
+and, for that reason, should not be the same as any other widget
+that is a child of the same parent.
+.IP \fIobject_class\fP 1i
+Specifies the widget class pointer for the created object.  \*(oC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(oI
+.IP \fIargs\fP 1i
+Specifies the argument list to override any other resource specifications.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtCreateWidget
+function performs all the boilerplate operations of widget
+creation, doing the following in order:
+.IP \(bu 5
+Checks to see if the class_initialize procedure has been called for this class
+and for all superclasses and, if not, calls those necessary in a
+superclass-to-subclass order.
+.IP \(bu 5
+If the specified class is not
+.PN coreWidgetClass
+or a subclass thereof,
+and the parent's class is a subclass of
+.PN compositeWidgetClass
+and either no extension record in
+the parent's composite class part extension field exists with the
+\fIrecord_type\fP
+.PN \s-1NULLQUARK\s+1
+or the \fIaccepts_objects\fP field in the extension
+record is
+.PN False ,
+.PN XtCreateWidget
+issues a fatal error; see Section 3.1 and Chapter 12.
+.IP \(bu 5
+If the specified class contains an extension record in the object class
+part \fIextension\fP field with \fIrecord_type\fP
+.PN \s-1NULLQUARK\s+1
+and the \fIallocate\fP field is not NULL,
+the procedure is invoked to allocate memory
+for the widget instance.  If the parent is a member of the class
+.PN constraintWidgetClass ,
+the procedure also allocates memory for the
+parent's constraints and stores the address of this memory into the
+\fIconstraints\fP field.  If no allocate procedure is found, the \*(xI
+allocate memory for the widget and, when applicable, the constraints,
+and initializes the \fIconstraints\fP field.
+.IP \(bu 5
+Initializes the Core nonresource data fields
+\fIself\fP, \fIparent\fP, \fIwidget_class\fP, \fIbeing_destroyed\fP,
+\fIname\fP, \fImanaged\fP, \fIwindow\fP, \fIvisible\fP,
+\fIpopup_list\fP, and \fInum_popups\fP. 
+.IP \(bu 5
+Initializes the resource fields (for example, \fIbackground_pixel\fP)
+by using the
+.PN CoreClassPart
+resource lists specified for this class and all superclasses.
+.IP \(bu 5
+If the parent is a member of the class
+.PN constraintWidgetClass ,
+initializes the resource fields of the constraints record
+by using the
+.PN ConstraintClassPart
+resource lists specified for the parent's class
+and all superclasses up to
+.PN constraintWidgetClass .
+.IP \(bu 5
+Calls the initialize procedures for the widget starting at the 
+Object
+initialize procedure on down to the widget's initialize procedure.
+.IP \(bu 5
+If the parent is a member of the class
+.PN constraintWidgetClass ,
+calls the
+.PN ConstraintClassPart
+initialize procedures,
+starting at
+.PN constraintWidgetClass
+on down to the parent's
+.PN ConstraintClassPart
+initialize procedure.
+.IP \(bu 5
+If the parent is a member of the class
+.PN compositeWidgetClass ,
+puts the widget into its parent's children list by calling its parent's
+insert_child procedure.
+For further information,
+see Section 3.1.
+.sp
+.LP
+To create an instance of a widget using varargs lists, use
+.PN XtVaCreateWidget .
+.LP
+.IN "XtVaCreateWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, ...)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIobject_class\fP;
+.br
+      Widget \fIparent\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the resource name for the created widget.
+.IP \fIobject_class\fP 1i
+Specifies the widget class pointer for the created object.  \*(oC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(oI
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+The
+.PN XtVaCreateWidget
+procedure is identical in function to
+.PN XtCreateWidget
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+
+.NH 3
+Creating an Application Shell Instance
+.XS
+\fB\*(SN Creating an Application Shell Instance\fP
+.XE
+.LP
+An application can have multiple top-level widgets, each of which
+specifies a unique widget tree
+that can potentially be on different screens or displays.
+An application uses 
+.PN XtAppCreateShell
+to create independent widget trees.
+.LP
+.IN "XtAppCreateShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtAppCreateShell(\fIname\fP, \
+\fIapplication_class\fP, \fIwidget_class\fP, \fIdisplay\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      String \fIname\fP;
+.br
+      String \fIapplication_class\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Display *\fIdisplay\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIname\fP 1.25i
+Specifies the instance name of the shell widget.
+If \fIname\fP is NULL,
+the application name passed to
+.PN XtDisplayInitialize
+is used.
+.IP \fIapplication_class\fP 1.25i
+Specifies the resource class string to be used in
+place of the widget \fIclass_name\fP string when
+\fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof.
+.IP \fIwidget_class\fP 1.25i
+Specifies the widget class for the top-level widget (e.g.,
+.PN applicationShellWidgetClass ).
+.IP \fIdisplay\fP 1.25i
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+.IP \fIargs\fP 1.25i
+Specifies the argument list to override any other resource specifications.
+.IP \fInum_args\fP 1.25i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtAppCreateShell
+function
+creates a new shell widget instance as the root of a widget tree.
+The screen resource for this widget is determined by first scanning
+\fIargs\fP for the XtNscreen argument.  If no XtNscreen argument is
+found, the resource database associated with the default screen of
+the specified display is queried for the resource \fIname\fP.screen,
+class \fIClass\fP.Screen where \fIClass\fP is the specified
+\fIapplication_class\fP if \fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof.  If \fIwidget_class\fP is not
+.PN application\%Shell\%Widget\%Class
+or a subclass, \fIClass\fP is the \fIclass_name\fP
+field from the
+.PN CoreClassPart
+of the specified \fIwidget_class\fP.
+If this query fails, the default
+screen of the specified display is used.  Once the screen is determined,
+the resource database associated with that screen is used to retrieve
+all remaining resources for the shell widget not specified in
+\fIargs\fP.  The widget name and \fIClass\fP as determined above are
+used as the leftmost (i.e., root) components in all fully qualified
+resource names for objects within this widget tree.
+
+.LP
+If the specified widget class is a subclass of WMShell, the name and
+\fIClass\fP as determined above will be stored into the
+.PN \s-1WM_CLASS\s+1
+property on the widget's window when it becomes realized.
+If the specified \fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof, the
+.PN \s-1WM_COMMAND\s+1
+property will also be set from the values of the XtNargv and
+XtNargc resources.
+
+.LP
+To create multiple top-level shells within a single (logical)
+application, 
+you can use one of two methods:
+.IP \(bu 5
+Designate one shell as the real top-level shell and
+create the others as pop-up children of it by using 
+.PN XtCreatePopupShell .
+.IP \(bu 5
+Have all shells as pop-up children of an unrealized top-level shell. 
+.LP
+The first method, 
+which is best used when there is a clear choice for what is the main window, 
+leads to resource specifications like the following:
+.LP
+.Ds
+.TA 2i
+.ta 2i
+xmail.geometry:...	(the main window)
+xmail.read.geometry:...	(the read window)
+xmail.compose.geometry:...	(the compose window)
+.De
+.LP
+The second method, 
+which is best if there is no main window,
+leads to resource specifications like the following:
+.LP
+.Ds
+.TA 2i
+.ta 2i
+xmail.headers.geometry:...	(the headers window)
+xmail.read.geometry:...	(the read window)
+xmail.compose.geometry:...	(the compose window)
+.De
+.sp
+.LP
+To create a top-level widget that is the root of a widget tree using
+varargs lists, use
+.PN XtVaAppCreateShell .
+.LP
+.IN "XtVaAppCreateShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaAppCreateShell(\fIname\fP, \fIapplication_class\fP, \
+\fIwidget_class\fP, \fIdisplay\fP, ...)
+.br
+    String \fIname\fP;
+.br
+    String \fIapplication_class\fP;
+.br
+    WidgetClass \fIwidget_class\fP;
+.br
+    Display *\fIdisplay\fP;
+.FN
+.IP \fIname\fP 1.5i
+Specifies the instance name of the shell widget.
+If \fIname\fP is NULL,
+the application name passed to
+.PN XtDisplayInitialize
+is used.
+.IP \fIapplication_class\fP 1.5i
+Specifies the resource class string to be used in
+place of the widget \fIclass_name\fP string when
+\fIwidget_class\fP is
+.PN applicationShellWidgetClass
+or a subclass thereof.
+.IP \fIwidget_class\fP 1.5i
+Specifies the widget class for the top-level widget.
+.IP \fIdisplay\fP 1.5i
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+.IP ... 1.5i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+The
+.PN XtVaAppCreateShell
+procedure is identical in function to
+.PN XtAppCreateShell
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
+described in Section 2.5.1.
+
+.NH 3
+Convenience Procedure to Initialize an Application
+.XS
+\fB\*(SN Convenience Procedure to Initialize an Application\fP
+.XE
+.LP
+To initialize the \*(xI internals, create an application context,
+open and initialize a display, and create the initial root shell
+instance, an application may use
+.PN XtOpenApplication
+or
+.PN XtVaOpenApplication .
+.LP
+.IN "XtOpenApplication" "" "@DEF@"
+.sM
+.FD 0
+Widget XtOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                       \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, \fIwidget_class\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      XtAppContext *\fIapp_context_return\fP;
+.br
+      String \fIapplication_class\fP;
+.br
+      XrmOptionDescList \fIoptions\fP;
+.br
+      Cardinal \fInum_options\fP;
+.br
+      int *\fIargc_in_out\fP;
+.br
+      String *\fIargv_in_out\fP;
+.br
+      String *\fIfallback_resources\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIapp_context_return\fP 1.5i
+Returns the application context, if non-NULL.
+.IP \fIapplication_class\fP 1.5i
+Specifies the class name of the application.
+.IP \fIoptions\fP 1.5i
+Specifies the command line options table.
+.IP \fInum_options\fP 1.5i
+Specifies the number of entries in \fIoptions\fP.
+.IP \fIargc_in_out\fP 1.5i
+Specifies a pointer to the number of command line arguments.
+.IP \fIargv_in_out\fP 1.5i
+Specifies a pointer to the command line arguments.
+.IP \fIfallback_resources\fP 1.5i
+Specifies resource values to be used if the application class resource
+file cannot be opened or read, or NULL.
+.IP \fIwidget_class\fP 1.5i
+Specifies the class of the widget to be created.  Must be shellWidgetClass
+or a subclass.
+.br
+.IP \fIargs\fP 1.5i
+Specifies the argument list to override any
+other resource specifications for the created shell widget.
+.IP \fInum_args\fP 1.5i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtOpenApplication
+function calls
+.PN XtToolkitInitialize
+followed by
+.PN XtCreateApplicationContext ,
+then calls
+.PN XtOpenDisplay
+with \fIdisplay_string\fP NULL and
+\fIapplication_name\fP NULL, and finally calls
+.PN XtAppCreateShell
+with \fIname\fP NULL, the specified \fIwidget_class\fP,
+an argument list and count,
+and returns the created shell.
+The recommended \fIwidget_class\fP is 
+.PN sessionShellWidgetClass .
+The argument list and count are created by merging
+the specified \fIargs\fP and \fInum_args\fP with a list 
+containing the specified \fIargc\fP and \fIargv\fP.
+The modified \fIargc\fP and \fIargv\fP returned by
+.PN XtDisplayInitialize
+are returned in \fIargc_in_out\fP and \fIargv_in_out\fP.  If
+\fIapp_context_return\fP is not NULL, the created application context is
+also returned.  If the display specified by the command line cannot be
+opened, an error message is issued and
+.PN XtOpenApplication
+terminates the application.  If \fIfallback_resources\fP is non-NULL,
+.PN XtAppSetFallbackResources
+is called with the value prior to calling
+.PN XtOpenDisplay .
+.sp
+.LP
+.IN "XtVaOpenApplication" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                         \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, \fIwidget_class\fP, ...)
+.br
+    XtAppContext *\fIapp_context_return\fP;
+.br
+    String \fIapplication_class\fP;
+.br
+    XrmOptionDescList \fIoptions\fP;
+.br
+    Cardinal \fInum_options\fP;
+.br
+    int *\fIargc_in_out\fP;
+.br
+    String *\fIargv_in_out\fP;
+.br
+    String *\fIfallback_resources\fP;
+.br
+    WidgetClass \fIwidget_class\fP;
+.FN
+.IP \fIapp_context_return\fP 1.5i
+Returns the application context, if non-NULL.
+.IP \fIapplication_class\fP 1.5i
+Specifies the class name of the application.
+.IP \fIoptions\fP 1.5i
+Specifies the command line options table.
+.IP \fInum_options\fP 1.5i
+Specifies the number of entries in \fIoptions\fP.
+.IP \fIargc_in_out\fP 1.5i
+Specifies a pointer to the number of command line arguments.
+.IP \fIargv_in_out\fP 1.5i
+Specifies the command line arguments array.
+.IP \fIfallback_resources\fP 1.5i
+Specifies resource values to be used if the application class
+resource file cannot be opened, or NULL.
+.IP \fIwidget_class\fP 1.5i
+Specifies the class of the widget to be created.  Must be shellWidgetClass
+or a subclass.
+.IP ... 1.5i
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+.LP
+.eM
+The
+.PN XtVaOpenApplication
+procedure is identical in function to
+.PN XtOpenApplication
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+
+.NH 3
+Widget Instance Allocation: The allocate Procedure
+.XS
+\*(SN Widget Instance Allocation: The allocate Procedure
+.XE
+.IN "Widget Allocation"
+.LP
+A widget class may optionally provide an instance allocation procedure
+in the
+.PN ObjectClassExtension
+record.
+.LP
+When the call to create a widget includes a varargs list containing
+.PN XtVaTypedArg ,
+these arguments will be passed to the allocation procedure in an
+.PN XtTypedArgList .
+.LP
+.IN "XtTypedArgList" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String name;
+	String type;
+	XtArgVal value;
+	int size;
+} XtTypedArg, *XtTypedArgList;
+.De
+.LP
+.eM
+.IN "allocate procedure" "" "@DEF@"
+The allocate procedure pointer in the
+.PN ObjectClassExtension
+record is of type
+.PN XtAllocateProc .
+.LP
+.IN "XtAllocateProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, \
+Cardinal*,
+                                            XtTypedArgList, Cardinal*, \
+Widget*, XtPointer*);
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Cardinal* \fIconstraint_size\fP;
+.br
+      Cardinal* \fImore_bytes\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal* \fInum_args\fP;
+.br
+      XtTypedArgList \fItyped_args\fP,
+.br
+      Cardinal* \fInum_typed_args\fP;
+.br
+      Widget* \fInew_return\fP;
+.br
+      XtPointer* \fImore_bytes_return\fP;
+.FN
+.IP \fIwidget_class\fP 1.5i
+Specifies the widget class of the instance to allocate.
+.IP \fIconstraint_size\fP 1.5i
+Specifies the size of the constraint record to allocate, or 0.
+.IP \fImore_bytes\fP 1.5i
+Specifies the number of auxiliary bytes of memory to allocate.
+.IP \fIargs\fP 1.5i
+Specifies the argument list as given in the call to create the widget.
+.IP \fInum_args\fP 1.5i
+Specifies the number of arguments.
+.IP \fItyped_args\fP 1.5i
+Specifies the list of typed arguments given in the call to create the widget.
+.IP \fInum_typed_args\fP 1.5i
+Specifies the number of typed arguments.
+.IP \fInew_return\fP 1.5i
+Returns a pointer to the newly allocated instance, or NULL in case of error.
+.IP \fImore_bytes_return\fP 1.5i
+Returns the auxiliary memory if it was requested, or NULL
+if requested and an error occurred; otherwise, unchanged.
+.LP
+.eM
+At widget allocation time, if an extension record with \fIrecord_type\fP
+equal to 
+.PN \s-1NULLQUARK\s+1
+is located through the object class part \fIextension\fP field
+and the \fIallocate\fP field is not NULL, the 
+.PN XtAllocateProc
+will be invoked to allocate memory for the widget.  If no ObjectClassPart
+extension record is declared with \fIrecord_type equal\fP to
+.PN \s-1NULLQUARK\s+1 ,
+then
+.PN XtInheritAllocate
+and 
+.PN XtInheritDeallocate
+are assumed.
+If no
+.PN XtAllocateProc
+is found, the \*(xI will allocate memory for the widget.
+.LP
+An 
+.PN XtAllocateProc
+must perform the following:
+.IP \(bu 5
+Allocate memory for the widget instance and return it in \fInew_return\fP.
+The memory must be at least \fIwc->core_class.widget_size\fP bytes in length,
+double-word aligned.
+.IP \(bu 5
+Initialize the \fIcore.constraints\fP field in the instance record to NULL
+or to point to a constraint record.  If \fIconstraint_size\fP
+is not 0, the procedure must allocate memory for the constraint record.
+The memory must be double-word aligned.
+.IP \(bu 5
+If \fImore_bytes\fP is not 0, then the address of a block of memory
+at least \fImore_bytes\fP in size, double-word aligned, must be
+returned in the \fImore_bytes_return\fP parameter,
+or NULL to indicate an error.
+.LP
+A class allocation procedure that envelops the allocation procedure of a
+superclass must rely on the enveloped procedure to perform the instance
+and constraint allocation.
+Allocation procedures should refrain from initializing fields in the
+widget record except to store pointers to newly allocated additional memory.
+Under no circumstances should an allocation procedure that envelopes
+its superclass allocation procedure modify fields in the
+instance part of any superclass.
+
+.NH 3
+Widget Instance Initialization: The initialize Procedure
+.XS
+\*(SN Widget Instance Initialization: The initialize Procedure
+.XE
+.IN "Initialization"
+.IN "Chaining"
+.IN "Superclass Chaining"
+.IN "Inheritance"
+.LP
+The initialize procedure pointer in a widget class is of type
+.PN XtInitProc .
+.LP
+.IN "XtInitProc" "" "@DEF@"
+.IN "initialize procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*);
+.br
+      Widget \fIrequest\fP;
+.br
+      Widget \fInew\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.FN
+.IP \fIrequest\fP 1i
+Specifies a copy of the widget with resource values as requested by the
+argument list, the resource database, and the widget defaults.
+.IP \fInew\fP 1i
+Specifies the widget with the new values, both resource and nonresource,
+that are actually allowed.
+.IP \fIargs\fP 1i
+Specifies the argument list passed by the client, for
+computing derived resource values.
+If the client created the widget using a varargs form, any resources
+specified via
+.PN XtVaTypedArg
+are converted to the widget representation and the list is transformed
+into the
+.PN ArgList
+format.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+An initialization procedure performs the following:
+.IP \(bu 5
+Allocates space for and copies any resources referenced by address
+that the client is allowed to free or modify
+after the widget has been created.
+For example,
+if a widget has a field that is a 
+.PN String ,
+it may choose not to
+depend on the characters at that address remaining constant 
+but dynamically allocate space for the string and copy it to the new space.
+Widgets that do not copy one or more resources referenced
+by address should clearly so state in their user documentation.
+.NT
+It is not necessary to allocate space for or to copy callback lists.
+.NE
+.IP \(bu 5
+Computes values for unspecified resource fields.
+For example, if \fIwidth\fP and \fIheight\fP are zero,
+the widget should compute an appropriate width and height 
+based on its other resources.
+.NT
+A widget may directly assign only
+its own \fIwidth\fP and \fIheight\fP within the initialize, initialize_hook,
+set_values, and
+set_values_hook procedures; see Chapter 6.
+.NE
+.IP \(bu 5
+Computes values for uninitialized nonresource fields that are derived from
+resource fields.
+For example, graphics contexts (GCs) that the widget uses are derived from
+resources like background, foreground, and font.
+.LP
+An initialization procedure also can check certain fields for
+internal consistency.
+For example, it makes no sense to specify a colormap for a depth
+that does not support that colormap.
+.LP
+Initialization procedures are called in superclass-to-subclass order
+after all fields specified in the resource lists have been
+initialized.  The initialize procedure does not need to examine
+\fIargs\fP and \fInum_args\fP
+if all public resources are declared in the resource list.
+Most of the initialization code for a specific widget class deals with fields
+defined in that class and not with fields defined in its superclasses.
+.LP
+If a subclass does not need an initialization procedure
+because it does not need to perform any of the above operations,
+it can specify NULL for the \fIinitialize\fP field in the class record.
+.LP
+Sometimes a subclass may want to overwrite values filled in by its
+superclass.
+In particular, size calculations of a superclass often are
+incorrect for a subclass, and in this case,
+the subclass must modify or recalculate fields declared
+and computed by its superclass.
+.LP
+As an example,
+a subclass can visually surround its superclass display.
+In this case, the width and height calculated by the superclass initialize
+procedure are too small and need to be incremented by the size of the surround.
+The subclass needs to know if its superclass's size was calculated by the
+superclass or was specified explicitly.
+All widgets must place themselves into whatever size is explicitly given,
+but they should compute a reasonable size if no size is requested.
+.LP
+The \fIrequest\fP and \fInew\fP arguments provide the necessary information for
+a subclass to determine the difference between an explicitly specified field
+and a field computed by a superclass.
+The \fIrequest\fP widget is a copy of the widget as initialized by the
+arglist and resource database.
+The \fInew\fP widget starts with the values in the request,
+but it has been updated by all superclass initialization procedures called
+so far.
+A subclass initialize procedure can compare these two to resolve
+any potential conflicts.
+.LP
+In the above example,
+the subclass with the visual surround can see
+if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero.
+If so,
+it adds its surround size to the \fIwidth\fP and \fIheight\fP
+fields in the \fInew\fP widget.
+If not, it must make do with the size originally specified.
+.LP
+The \fInew\fP widget will become the actual widget instance record.
+Therefore,
+the initialization procedure should do all its work on the \fInew\fP widget;
+the \fIrequest\fP widget should never be modified.
+If the initialize procedure
+needs to call any routines that operate on a widget,
+it should specify \fInew\fP as the widget instance.
+
+.NH 3
+Constraint Instance Initialization: The ConstraintClassPart initialize Procedure
+.XS
+\*(SN Constraint Instance Initialization: The ConstraintClassPart initialize Procedure
+.XE
+.IN "Initialization"
+.IN "XtInitProc"
+.IN "initialize procedure"
+.IN "Chaining"
+.IN "Superclass Chaining"
+.IN "Inheritance"
+.LP
+The constraint initialization procedure pointer, found in the
+.PN ConstraintClassPart
+\fIinitialize\fP field of the widget class record, is of type
+.PN XtInitProc .
+The values passed to the parent constraint initialization procedures
+are the same as those passed to the child's class widget initialization
+procedures.
+.LP
+The \fIconstraints\fP field of the \fIrequest\fP widget points to a copy of the
+constraints record as initialized by the arglist and resource database.
+.LP
+The constraint initialization procedure should compute any constraint fields
+derived from constraint resources.
+It can make further changes to the \fInew\fP widget to make the widget
+and any other constraint fields
+conform to the specified constraints, for example, 
+changing the widget's size or position.
+.LP
+If a constraint class does not need a constraint initialization procedure,
+it can specify NULL for the \fIinitialize\fP field of the
+.PN ConstraintClassPart
+in the class record.
+
+.NH 3
+Nonwidget Data Initialization: The initialize_hook Procedure
+.XS
+\*(SN Nonwidget Data Initialization: The initialize_hook Procedure
+.XE
+.IN "Initialization"
+.LP
+.NT
+The initialize_hook procedure is obsolete, as the same information
+is now available to the initialize procedure.  The procedure has been
+retained for those widgets that used it in previous releases.
+.NE
+.LP
+The initialize_hook procedure pointer is of type
+.PN XtArgsProc :
+.LP
+.IN "initialize_hook procedure" "" "@DEF@"
+.IN "XtArgsProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*);
+.br
+      Widget \fIw\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fIargs\fP 1i
+Specifies the argument list passed by the client.
+If the client created the widget using a varargs form, any resources
+specified via
+.PN XtVaTypedArg
+are converted to the widget representation and the list is transformed
+into the
+.PN ArgList
+format.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+If this procedure is not NULL,
+it is called immediately after the corresponding initialize
+procedure or in its place if the \fIinitialize\fP field is NULL.
+.LP
+The initialize_hook procedure allows a widget instance to initialize
+nonresource data using information from the specified argument list
+as if it were a resource.
+
+.NH 2
+Realizing Widgets
+.XS
+\fB\*(SN Realizing Widgets\fP
+.XE
+.LP
+To realize a widget instance, use
+.PN XtRealizeWidget .
+.LP
+.IN "XtRealizeWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtRealizeWidget(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.eM
+.LP
+If the widget is already realized,
+.PN XtRealizeWidget
+simply returns. 
+Otherwise it performs the following:
+.IP \(bu 5
+Binds all action names in the widget's
+translation table to procedures (see Section 10.1.2).
+.IP \(bu 5
+Makes a postorder traversal of the widget tree rooted
+at the specified widget and calls each non-NULL change_managed procedure
+of all composite widgets that have one or more managed children.
+.IP \(bu 5
+Constructs an
+.PN XSetWindowAttributes
+structure filled in with information derived from the 
+Core 
+widget fields and calls the realize procedure for the widget,
+which adds any widget-specific attributes and creates the X window.
+.IP \(bu 5
+If the widget is
+not a subclass of 
+.PN compositeWidgetClass ,
+.PN XtRealizeWidget
+returns; otherwise it continues and performs the following:
+.RS
+.IP \- 5
+Descends recursively to each of the widget's
+managed children and calls the realize procedures.
+Primitive widgets that instantiate children are responsible for realizing
+those children themselves.
+.IP \- 5
+Maps all of the managed children windows that have \fImapped_when_managed\fP 
+.PN True .
+If a widget is managed but \fImapped_when_managed\fP is 
+.PN False , 
+the widget is allocated visual space but is not displayed.
+.RE
+.LP
+If the widget is a top-level shell widget (that is, it has no parent), and
+\fImapped_when_managed\fP is 
+.PN True , 
+.PN XtRealizeWidget
+maps the widget window.
+.LP
+.PN XtCreateWidget ,
+.PN XtVaCreateWidget ,
+.PN XtRealizeWidget ,
+.PN XtManageChildren ,
+.PN XtUnmanage\%Children ,
+.PN XtUnrealizeWidget ,
+.PN XtSetMappedWhenManaged ,
+and
+.PN XtDestroy\%Widget
+maintain the following invariants:
+.IP \(bu 5
+If a composite widget is realized, then all its managed children are realized.
+.IP \(bu 5
+If a composite widget is realized, then all its managed children that have
+\fImapped_when_managed\fP
+.PN True
+are mapped.
+.LP
+All \*(xI functions and all widget routines should accept
+either realized or unrealized widgets.
+When calling the realize or change_managed
+procedures for children of a composite
+widget,
+.PN XtRealizeWidget
+calls the procedures in reverse order of
+appearance in the
+.PN CompositePart
+\fIchildren\fP list.  By default, this
+ordering of the realize procedures will
+result in the stacking order of any newly created subwindows being
+top-to-bottom in the order of appearance on the list, and the most
+recently created child will be at the bottom.
+.sp
+.LP
+To check whether or not a widget has been realized, use
+.PN XtIsRealized .
+.LP
+.IN "XtIsRealized" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtIsRealized(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+The
+.PN XtIsRealized
+function returns 
+.PN True 
+if the widget has been realized,
+that is, if the widget has a nonzero window ID.
+If the specified object is not a widget, the state of the nearest
+widget ancestor is returned.
+.LP
+Some widget procedures (for example, set_values) might wish to
+operate differently
+after the widget has been realized.
+
+.NH 3
+Widget Instance Window Creation: The realize Procedure
+.XS
+\*(SN Widget Instance Window Creation: The realize Procedure
+.XE
+.LP
+The realize procedure pointer in a widget class is of type
+.PN XtRealizeProc .
+.LP
+.IN "XtRealizeProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*);
+.br
+      Widget \fIw\fP;
+.br
+      XtValueMask *\fIvalue_mask\fP;
+.br
+      XSetWindowAttributes *\fIattributes\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fIvalue_mask\fP 1i
+Specifies which fields in the \fIattributes\fP structure are used.
+.IP \fIattributes\fP 1i
+Specifies the window attributes to use in the
+.PN XCreateWindow
+call.
+.LP
+.eM
+The realize procedure must create the widget's window.
+.LP
+Before calling the class realize procedure, the generic
+.PN XtRealizeWidget
+function fills in a mask and a corresponding
+.PN XSetWindowAttributes
+structure.
+It sets the following fields in \fIattributes\fP and
+corresponding bits in \fIvalue_mask\fP
+based on information in the widget
+core
+structure:
+.IP \(bu 5
+The \fIbackground_pixmap\fP (or \fIbackground_pixel\fP if \fIbackground_pixmap\fP is
+.PN XtUnspecifiedPixmap )
+is filled in from the corresponding field.
+.IP \(bu 5
+The \fIborder_pixmap\fP (or \fIborder_pixel\fP if \fIborder_pixmap\fP is
+.PN XtUnspecifiedPixmap )
+is filled in from the corresponding field.
+.IP \(bu 5
+The \fIcolormap\fP is filled in from the corresponding field.
+.IP \(bu 5
+The \fIevent_mask\fP is filled in based on the event handlers registered,
+the event translations specified, whether the \fIexpose\fP field is non-NULL,
+and whether \fIvisible_interest\fP is 
+.PN True .
+.IP \(bu 5
+The \fIbit_gravity\fP is set to
+.PN NorthWestGravity
+if the \fIexpose\fP field is NULL.
+.LP
+These or any other fields in attributes and the corresponding bits in
+\fIvalue_mask\fP can be set by the realize procedure.
+.LP
+Note that because realize is not a chained operation,
+the widget class realize procedure must update the
+.PN XSetWindowAttributes
+structure with all the appropriate fields from 
+non-Core
+superclasses.
+.LP
+.IN "Inheritance"
+A widget class can inherit its realize procedure from its superclass
+during class initialization.
+The realize procedure defined for
+.PN coreWidgetClass 
+calls
+.PN XtCreateWindow
+with the passed \fIvalue_mask\fP and \fIattributes\fP
+and with \fIwindow_class\fP and \fIvisual\fP set to
+.PN CopyFromParent .
+Both
+.PN compositeWidgetClass
+and
+.PN constraintWidgetClass
+inherit this realize procedure, and most new widget subclasses
+can do the same (see Section 1.6.10).
+.LP
+The most common noninherited realize procedures set \fIbit_gravity\fP in the mask
+and attributes to the appropriate value and then create the window.
+For example, depending on its justification, Label might set \fIbit_gravity\fP to
+.PN WestGravity ,
+.PN CenterGravity ,
+or
+.PN EastGravity .
+Consequently, shrinking it would just move the bits appropriately,
+and no
+exposure
+event is needed for repainting.
+.LP
+If a composite widget's children should be realized in an order other
+than that specified
+(to control the stacking order, for example),
+it should call
+.PN XtRealizeWidget
+on its children itself in the appropriate order from within its own
+realize procedure.
+.LP
+Widgets that have children and whose class is not a subclass of
+.PN compositeWidgetClass
+are responsible for calling
+.PN XtRealizeWidget
+on their children, usually from within the realize procedure.
+.LP
+Realize procedures cannot manage or unmanage their descendants.
+
+.NH 3
+Window Creation Convenience Routine
+.XS
+\*(SN Window Creation Convenience Routine
+.XE
+.LP
+Rather than call the Xlib
+.PN XCreateWindow
+.IN "realize procedure"
+function explicitly, a realize procedure should normally call the \*(xI analog
+.PN XtCreateWindow ,
+which simplifies the creation of windows for widgets.
+.LP
+.IN "XtCreateWindow" "" "@DEF@"
+.sM
+.FD 0
+void XtCreateWindow(\fIw\fP, \fIwindow_class\fP, \fIvisual\fP, \
+\fIvalue_mask\fP, \fIattributes\fP)
+.br
+      Widget \fIw\fP;
+.br
+      unsigned int \fIwindow_class\fP;
+.br
+      Visual *\fIvisual\fP;
+.br
+      XtValueMask \fIvalue_mask\fP;
+.br
+      XSetWindowAttributes *\fIattributes\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that defines the additional window attributed.  \*(cI
+.IP \fIwindow_class\fP 1i
+Specifies the Xlib window class (for example,
+.PN InputOutput ,
+.PN InputOnly ,
+or
+.PN CopyFromParent ).
+.IP \fIvisual\fP 1i
+Specifies the visual type (usually
+.PN CopyFromParent ).
+.ds Vm attribute fields to use
+.IP \fIvalue_mask\fP 1i
+Specifies which fields in the \fIattributes\fP structure are used.
+.IP \fIattributes\fP 1i
+Specifies the window attributes to use in the
+.PN XCreateWindow
+call.
+.LP
+.eM
+The
+.PN XtCreateWindow
+function calls the Xlib
+.PN XCreateWindow
+function with values from the widget structure and the passed parameters.
+Then, it assigns the created window to the widget's \fIwindow\fP field.
+.LP
+.PN XtCreateWindow
+evaluates the following fields of the widget core
+structure: \fIdepth\fP, \fIscreen\fP, \fIparent->core.window\fP, \fIx\fP,
+\fIy\fP, \fIwidth\fP, \fIheight\fP, and
+\fIborder_width\fP.
+
+.NH 2
+Obtaining Window Information from a Widget
+.XS
+\fB\*(SN Obtaining Window Information from a Widget\fP
+.XE
+.LP
+The 
+Core
+widget class definition contains the screen and window ids.
+The \fIwindow\fP field may be NULL for a while
+(see Sections 2.5 and 2.6).
+.LP
+The display pointer, the parent widget, screen pointer,
+and window of a widget are available to the widget writer by means of macros 
+and to the application writer by means of functions.
+.LP
+.IN "XtDisplay" "" "@DEF@"
+.sM
+.FD 0
+Display *XtDisplay(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+.PN XtDisplay
+returns the display pointer for the specified widget.
+.sp
+.LP
+.IN "XtParent" "" "@DEF@"
+.sM
+.FD 0
+Widget XtParent(\fIw\fP)
+.br
+     Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+.PN XtParent
+returns the parent object for the specified widget. The returned object
+will be of class Object or a subclass.
+.sp
+.LP
+.IN "XtScreen" "" "@DEF@"
+.sM
+.FD 0
+Screen *XtScreen(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+.PN XtScreen
+returns the screen pointer for the specified widget.
+.sp
+.LP
+.IN "XtWindow" "" "@DEF@"
+.sM
+.FD 0
+Window XtWindow(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+.PN XtWindow
+returns the window of the specified widget.
+.sp
+.LP
+The display pointer, screen pointer, and window of a widget or
+of the closest widget ancestor of a nonwidget object are available
+by means of
+.PN XtDisplayOfObject ,
+.PN XtScreenOfObject ,
+and
+.PN XtWindowOfObject .
+.IN "XtDisplayOfObject" "" "@DEF@"
+.sp
+.LP
+.sM
+.FD 0
+Display *XtDisplayOfObject(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+.PN XtDisplayOfObject
+is identical in function to
+.PN XtDisplay
+if the object is a widget; otherwise
+.PN XtDisplayOfObject
+returns the display
+pointer for the nearest ancestor of \fIobject\fP that is of class
+Widget or a subclass thereof.
+.LP
+.IN "XtScreenOfObject" "" "@DEF@"
+.sM
+.FD 0
+Screen *XtScreenOfObject(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+.PN XtScreenOfObject
+is identical in function to
+.PN XtScreen
+if the object is a widget; otherwise
+.PN XtScreenOfObject
+returns the screen pointer
+for the nearest ancestor of \fIobject\fP that is of class
+Widget or a subclass thereof.
+.LP
+.IN "XtWindowOfObject" "" "@DEF@"
+.sM
+.FD 0
+Window XtWindowOfObject(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+.PN XtWindowOfObject
+is identical in function to
+.PN XtWindow
+if the object is a widget; otherwise
+.PN XtWindowOfObject
+returns the window for the nearest ancestor of \fIobject\fP that is of class
+Widget or a subclass thereof.
+.sp
+.LP
+To retrieve the instance name of an object, use
+.PN XtName .
+.LP
+.IN "XtName" "" "@DEF@"
+.sM
+.FD 0
+String XtName(\fIobject\fP)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object whose name is desired.  \*(oI
+.LP
+.eM
+.PN XtName
+returns a pointer to the instance name of the specified object.
+The storage is owned by the \*(xI and must not be modified.  The
+name is not qualified by the names of any of the object's ancestors.
+.LP
+Several window attributes are locally cached in the widget instance.
+Thus, they can be set by the resource manager and
+.PN XtSetValues 
+as well as used by routines that derive structures from these values
+(for example, \fIdepth\fP for deriving pixmaps,
+\fIbackground_pixel\fP for deriving GCs, and so on) or in the
+.PN XtCreateWindow
+call.
+.LP
+The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
+window attributes are available to
+geometry managers.
+These fields are maintained synchronously inside the \*(xI.
+When an
+.PN XConfigureWindow
+is issued by the \*(xI on the widget's window (on request of its parent),
+these values are updated immediately rather than some time later
+when the server generates a
+.PN ConfigureNotify
+event.
+(In fact, most widgets do not select
+.PN SubstructureNotify
+events.)
+This ensures that all geometry calculations are based on the internally
+consistent toolkit world rather than on either
+an inconsistent world updated by asynchronous
+.PN ConfigureNotify
+events or a consistent, but slow, world in which geometry managers
+ask the server
+for window sizes whenever they need to lay out their managed children
+(see Chapter 6).
+
+.NH 3
+Unrealizing Widgets
+.XS
+\fB\*(SN Unrealizing Widgets\fP
+.XE
+.LP
+To destroy the windows associated with a widget and its
+non-pop-up descendants, use
+.PN XtUnrealizeWidget .
+.LP
+.IN "XtUnrealizeWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtUnrealizeWidget(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+If the widget is currently unrealized,
+.PN XtUnrealizeWidget
+simply returns.  Otherwise it performs the following:
+.IP \(bu 5
+Unmanages the widget if the widget is managed.
+.IP \(bu 5
+Makes a postorder (child-to-parent) traversal of the widget tree
+rooted at the specified widget and, for each widget that has
+declared a callback list resource named ``unrealizeCallback'', executes the
+procedures on the
+.IN XtNunrealizeCallback
+XtNunrealizeCallback
+list.
+.IN "unrealizeCallback" "" "@DEF@"
+.IP \(bu 5
+Destroys the widget's window and any subwindows by calling
+.PN XDestroyWindow
+with the specified widget's \fIwindow\fP field.
+.LP
+Any events in the queue or which arrive following a call to
+.PN XtUnrealizeWidget
+will be dispatched as if the window(s) of the
+unrealized widget(s) had never existed.
+
+.NH 2
+Destroying Widgets
+.XS
+\fB\*(SN Destroying Widgets\fP
+.XE
+.LP
+The \*(xI provide support
+.IP \(bu 5
+To destroy all the pop-up children of the widget being destroyed
+and destroy all children of composite widgets.
+.IP \(bu 5
+To remove (and unmap) the widget from its parent.
+.IP \(bu 5
+To call the callback procedures that have been registered to trigger 
+when the widget is destroyed.
+.IP \(bu 5
+To minimize the number of things a widget has to deallocate when destroyed.
+.IP \(bu 5
+To minimize the number of
+.PN XDestroyWindow
+calls when destroying a widget tree.
+.sp
+.LP
+To destroy a widget instance, use
+.PN XtDestroyWidget .
+.LP
+.IN "XtDestroyWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtDestroyWidget(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+The
+.PN XtDestroyWidget
+function provides the only method of destroying a widget,
+including widgets that need to destroy themselves.
+It can be called at any time,
+including from an application callback routine of the widget being destroyed.
+This requires a two-phase destroy process in order to avoid dangling
+references to destroyed widgets.
+.LP
+In phase 1,
+.PN XtDestroyWidget
+performs the following:
+.IP \(bu 5
+If the \fIbeing_destroyed\fP field of the widget is 
+.PN True ,
+it returns immediately.
+.IP \(bu 5
+Recursively descends the widget tree and
+sets the \fIbeing_destroyed\fP field to 
+.PN True 
+for the widget and all normal and pop-up children.
+.IP \(bu 5
+Adds the widget to a list of widgets (the destroy list) that should be
+destroyed when it is safe to do so.
+.LP
+Entries on the destroy list satisfy the invariant that
+if w2 occurs after w1 on the destroy list, then w2 is not a descendent,
+either normal or pop-up, of w1.
+.LP
+Phase 2 occurs when all procedures that should execute as a result of
+the current event have been called, including all procedures registered with
+the event and translation managers,
+that is, when the current invocation of
+.PN XtDispatchEvent
+is about to return, or immediately if not in
+.PN XtDispatchEvent .
+.LP
+In phase 2,
+.PN XtDestroyWidget
+performs the following on each entry in the destroy list in the order
+specified:
+.IP \(bu 5
+If the widget is not a pop-up child and the widget's parent is a subclass of 
+.PN composite\%WidgetClass ,
+and if the parent is not being destroyed, 
+it calls 
+.PN XtUnmanageChild 
+on the widget and then calls the widget's parent's delete_child procedure
+(see Section 3.3).
+.IP \(bu 5
+Calls the destroy callback procedures registered on the widget 
+and all normal and pop-up descendants in postorder (it calls child
+callbacks before parent callbacks).
+.LP
+The 
+.PN XtDestroyWidget
+function then makes second traversal of the widget and all normal
+and pop-up descendants to perform the following three items on each
+widget in postorder:
+.IP \(bu 5
+If the widget is not a pop-up child and the widget's parent is a subclass of
+.PN constraint\%WidgetClass ,
+it calls the
+.PN ConstraintClassPart
+destroy procedure for the parent,
+then for the parent's superclass,
+until finally it calls the
+.PN ConstraintClassPart
+destroy procedure for
+.PN constraintWidgetClass .
+.IP \(bu 5
+Calls the
+.PN CoreClassPart
+destroy procedure declared in the widget class,
+then the destroy procedure declared in its superclass,
+until finally it calls the destroy procedure declared in the Object
+class record.  Callback lists are deallocated.
+.IP \(bu 5
+If the widget class object class part contains an 
+.PN ObjectClassExtension
+record with the record_type
+.PN \s-1NULLQUARK\s+1
+and the \fIdeallocate\fP field is not NULL,
+calls the deallocate procedure to deallocate the instance and if one
+exists, the constraint record.  Otherwise, the \*(xI will deallocate
+the widget instance record and if one exists, the constraint record.
+.IP \(bu 5
+Calls
+.PN XDestroyWindow
+if the specified widget is realized (that is, has an X window).
+The server recursively destroys all normal descendant windows.
+(Windows of realized pop-up Shell children, and their
+descendants, are destroyed by a shell class destroy procedure.)
+
+.NH 3
+Adding and Removing Destroy Callbacks
+.XS
+\fB\*(SN Adding and Removing Destroy Callbacks\fP
+.XE
+.LP
+When an application needs to perform additional processing during the
+destruction of a widget,
+it should register a destroy callback procedure for the widget.
+The destroy callback procedures use the mechanism described in Chapter 8.
+.IN "Destroy Callbacks"
+The destroy callback list is identified by the resource name
+XtNdestroyCallback.
+.LP
+For example, the following adds an application-supplied destroy callback 
+procedure \fIClientDestroy\fP with client data to a widget by calling
+.PN XtAddCallback .
+.IN "XtAddCallback"
+.Ds
+XtAddCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
+.De
+.LP
+Similarly, the following removes the application-supplied destroy callback
+procedure \fIClientDestroy\fP by calling
+.PN XtRemoveCallback .
+.IN "XtRemoveCallback"
+.Ds
+XtRemoveCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
+.De
+.LP
+The \fIClientDestroy\fP argument is of type
+.PN XtCallbackProc ;
+see Section 8.1.
+
+.NH 3
+Dynamic Data Deallocation: The destroy Procedure
+.XS
+\*(SN Dynamic Data Deallocation: The destroy Procedure
+.XE
+.LP
+.IN "destroy procedure" "" "@DEF@"
+The destroy procedure pointers in the
+.PN ObjectClassPart ,
+.PN RectObjClassPart ,
+and
+.PN CoreClassPart
+structures are of type
+.PN XtWidgetProc .
+.LP
+.IN "XtWidgetProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtWidgetProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget being destroyed.
+.LP
+.eM
+The destroy procedures are called in subclass-to-superclass order.
+Therefore, a widget's destroy procedure should deallocate only storage
+that is specific to the subclass and should ignore the storage
+allocated by any of its superclasses.
+The destroy procedure should deallocate only resources that have been
+explicitly created by the subclass.
+Any resource that was obtained from the resource database 
+or passed in an argument list was not created by the widget
+and therefore should not be destroyed by it.
+If a widget does not need to deallocate any storage,
+the destroy procedure entry in its class record can be NULL.
+.LP
+Deallocating storage includes, but is not limited to,
+the following steps:
+.IP \(bu 5
+Calling
+.PN XtFree
+on dynamic storage allocated with
+.PN XtMalloc ,
+.PN XtCalloc ,
+and so on.
+.IP \(bu 5
+Calling
+.PN XFreePixmap
+on pixmaps created with direct X calls.
+.IP \(bu 5
+Calling
+.PN XtReleaseGC
+on GCs allocated with
+.PN XtGetGC .
+.IP \(bu 5
+Calling
+.PN XFreeGC
+on GCs allocated with direct X calls.
+.IP \(bu 5
+Calling
+.PN XtRemoveEventHandler
+on event handlers added to other widgets.
+.IP \(bu 5
+Calling
+.PN XtRemoveTimeOut
+on timers created with
+.PN XtAppAddTimeOut .
+.IP \(bu 5
+Calling
+.PN XtDestroyWidget
+for each child if the widget has children
+and is not a subclass of 
+.PN compositeWidgetClass .
+.LP
+During destroy phase 2 for each widget, the \*(xI remove the widget
+from the modal cascade, unregister all event handlers, remove all key,
+keyboard, button, and pointer grabs and remove all callback procedures
+registered on the widget.  Any outstanding selection transfers will time out.
+
+.NH 3
+Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure
+.XS
+\*(SN Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure
+.XE
+.LP
+The constraint destroy procedure identified in the
+.PN ConstraintClassPart
+structure is called for a widget whose parent is a subclass of
+.PN constraintWidgetClass .
+This constraint destroy procedure pointer is of type
+.PN XtWidgetProc .
+The constraint destroy procedures are called in subclass-to-superclass order,
+starting at the class of the widget's parent and ending at
+.PN constraint\%WidgetClass .
+Therefore, a parent's constraint destroy procedure should deallocate only
+storage that is specific to the constraint subclass
+and not storage allocated by any of its superclasses.
+.LP
+If a parent does not need to deallocate any constraint storage,
+the constraint destroy procedure entry
+in its class record can be NULL.
+
+.NH 3
+Widget Instance Deallocation: The deallocate Procedure
+.XS
+\*(SN Widget Instance Deallocation: The deallocate Procedure
+.XE
+.LP
+.IN "deallocate procedure" "" "@DEF@"
+The deallocate procedure pointer in the
+.PN ObjectClassExtension
+record is of type
+.PN XtDeallocateProc .
+.LP
+.IN "XtDeallocateProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtDeallocateProc)(Widget, XtPointer);
+.br
+      Widget \fIwidget\fP;
+.br
+      XtPointer \fImore_bytes\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget being destroyed.
+.IP \fImore_bytes\fP 1i
+Specifies the auxiliary memory received from the corresponding allocator
+along with the widget, or NULL.
+.LP
+.eM
+When a widget is destroyed, if an
+.PN ObjectClassExtension
+record exists in the object class part \fIextension\fP field
+with \fIrecord_type\fP
+.PN \s-1NULLQUARK\s+1
+and the \fIdeallocate\fP field is not NULL, the
+.PN XtDeallocateProc
+will be called.
+If no ObjectClassPart extension record is declared with \fIrecord_type\fP
+equal to 
+.PN \s-1NULLQUARK\s+1 ,
+then 
+.PN XtInheritAllocate
+and 
+.PN XtInheritDeallocate
+are assumed.
+The responsibilities of the deallocate procedure are to deallocate the
+memory specified by \fImore_bytes\fP if it is not NULL,
+to deallocate the constraints record as specified by the
+widget's \fIcore.constraints\fP field if it is
+not NULL, and to deallocate the widget instance itself.
+.LP
+If no
+.PN XtDeallocateProc
+is found, it is assumed that the \*(xI
+originally allocated the memory and is responsible for freeing it.
+
+.NH 2
+Exiting from an Application
+.XS
+\fB\*(SN Exiting from an Application\fP
+.XE
+.LP
+All \*(tk applications should terminate
+by calling
+.PN XtDestroyApplicationContext
+and then exiting
+using the
+standard method for their operating system (typically, by calling
+.PN exit
+for POSIX-based systems).
+The quickest way to make the windows disappear while exiting is to call
+.PN XtUnmapWidget
+on each top-level shell widget.
+The \*(xI have no resources beyond those in the program image,
+and the X server will free its resources when its connection
+to the application is broken.
+.LP
+Depending upon the widget set in use, it may be necessary to explicitly
+destroy individual widgets or widget trees with
+.PN XtDestroyWidget
+before calling
+.PN XtDestroyApplicationContext
+in order to ensure that any
+required widget cleanup is properly executed.  The application developer
+must refer to the widget documentation to learn if a widget needs to
+perform cleanup beyond that performed automatically by the
+operating system.  If the client is a session participant
+(see Section 4.2), then the client may wish to resign from the session
+before exiting.  See Section 4.2.4 for details.
+.bp
diff --git a/libXt/specs/CH03 b/libXt/specs/CH03
new file mode 100644
index 000000000..f96a79781
--- /dev/null
+++ b/libXt/specs/CH03
@@ -0,0 +1,1031 @@
+.\" $Xorg: CH03,v 1.3 2000/08/17 19:42:44 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 3\fP\s-1
+
+\s+1\fBComposite Widgets and Their Children\fP\s-1
+.sp 2
+.nr H1 3
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 3 \(em Composite Widgets and Their Children
+.XE
+.IN "Composite widgets"
+Composite widgets (widgets whose class is a subclass of 
+.PN compositeWidgetClass )
+can have an arbitrary number of children.
+Consequently, they are responsible for much more than primitive widgets.
+Their responsibilities (either implemented directly by the widget class
+or indirectly by \*(xI functions) include:
+.IP \(bu 5
+Overall management of children from creation to destruction.
+.IP \(bu 5
+Destruction of descendants when the composite widget is destroyed.
+.IP \(bu 5
+Physical arrangement (geometry management) of a displayable subset of
+children (that is, the managed children).
+.IP \(bu 5
+Mapping and unmapping of a subset of the managed children.
+.LP
+Overall management is handled by the generic procedures
+.PN XtCreateWidget
+and
+.PN XtDestroyWidget .
+.PN XtCreateWidget
+adds children to their parent by calling the parent's insert_child
+procedure.
+.PN XtDestroyWidget
+removes children from their parent by calling the parent's delete_child
+procedure and ensures that all children of a destroyed composite widget
+also get destroyed.
+.LP
+Only a subset of the total number of children is actually managed by
+the geometry manager and hence possibly visible.
+For example, a composite editor widget
+supporting multiple editing buffers might allocate one child
+widget for each file buffer,
+but it might display only a small number of the existing buffers.
+Widgets that are in this displayable subset are called managed widgets
+and enter into geometry manager calculations.
+The other children are called unmanaged widgets
+and, by definition, are not mapped by the \*(xI.
+.LP
+Children are added to and removed from their parent's managed set by using
+.PN XtManageChild ,
+.PN XtManageChildren ,
+.PN XtUnmanageChild ,
+.PN XtUnmanageChildren ,
+and
+.PN XtChangeManagedSet ,
+which notify the parent to recalculate the physical layout of its children
+by calling the parent's change_managed procedure.
+The 
+.PN XtCreateManagedWidget
+convenience function calls
+.PN XtCreateWidget
+and
+.PN XtManageChild
+on the result.
+.LP
+Most managed children are mapped,
+but some widgets can be in a state where they take up physical space
+but do not show anything.
+Managed widgets are not mapped automatically
+if their \fImap_when_managed\fP field is 
+.PN False .
+The default is 
+.PN True 
+and is changed by using
+.PN XtSetMappedWhenManaged .
+.LP
+Each composite widget class declares a geometry manager,
+which is responsible for figuring out where the managed children
+should appear within the composite widget's window.
+Geometry management techniques fall into four classes:
+.IP "Fixed boxes" 1.6i
+Fixed boxes have a fixed number of children created by the parent.
+All these children are managed,
+and none ever makes geometry manager requests.
+.IP "Homogeneous boxes" 1.6i
+Homogeneous boxes treat all children equally and apply the same geometry
+constraints to each child.
+Many clients insert and delete widgets freely.
+.IP "Heterogeneous boxes" 1.6i
+Heterogeneous boxes have a specific location where each child is placed.
+This location usually is not specified in pixels,
+because the window may be resized, but is expressed rather
+in terms of the relationship between a child
+and the parent or between the child and other specific children.
+The class of heterogeneous boxes is usually a subclass of
+Constraint.
+.IP "Shell boxes" 1.6i
+Shell boxes typically have only one child,
+and the child's size is usually
+exactly the size of the shell.
+The geometry manager must communicate with the window manager, if it exists,
+and the box must also accept
+.PN ConfigureNotify
+events when the window size is changed by the window manager.
+
+.NH 2
+Addition of Children to a Composite Widget: The insert_child Procedure
+.XS
+\*(SN Addition of Children to a Composite Widget: The insert_child Procedure
+.XE
+.LP
+.IN "insert_child procedure"
+To add a child to
+the parent's list of children, the
+.PN XtCreateWidget
+function calls the parent's class routine insert_child.
+The insert_child procedure pointer in a composite widget is of type
+.PN XtWidgetProc .
+.LP
+.IN "insert_child procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtWidgetProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Passes the newly created child.
+.LP
+.eM
+Most composite widgets inherit their superclass's operation.
+The insert_child routine in
+.PN CompositeWidgetClass calls the insert_position procedure
+and inserts the child at the specified position
+in the \fIchildren\fP list, expanding it if necessary.
+.LP
+Some composite widgets define their own insert_child routine
+so that they can order their children in some convenient way,
+create companion controller widgets for a new widget,
+or limit the number or class of their child widgets.
+A composite widget class that wishes
+to allow nonwidget children (see Chapter 12) must specify a
+.PN CompositeClassExtension
+extension record as described
+in Section 1.4.2.1 and set the \fIaccepts_objects\fP field in this record to
+.PN True .
+If the
+.PN CompositeClassExtension
+record is not specified or the
+\fIaccepts_objects\fP field is
+.PN False ,
+the composite widget can assume that all its children are of a subclass of Core
+without an explicit subclass test in the insert_child procedure.
+.LP
+If there is not enough room to insert a new child in the \fIchildren\fP array
+(that is, \fInum_children\fP is equal to \fInum_slots\fP),
+the insert_child procedure must first reallocate the array
+and update \fInum_slots\fP.
+The insert_child procedure then places the child at the appropriate position
+in the array and increments the \fInum_children\fP field.
+
+.NH 2
+Insertion Order of Children: The insert_position Procedure
+.XS
+\fB\*(SN Insertion Order of Children: The insert_position Procedure\fP
+.XE
+.LP
+Instances of composite widgets sometimes need to specify more about the order in which
+their children are kept.
+For example,
+an application may want a set of command buttons in some logical order
+grouped by function,
+and it may want buttons that represent file names to be kept
+in alphabetical order without constraining the order in which the
+buttons are created.
+.LP
+An application controls the presentation order of a set of children by
+supplying an
+.IN XtNinsertPosition
+XtNinsertPosition
+resource.
+The insert_position procedure pointer in a composite widget instance is of type
+.PN XtOrderProc .
+.LP
+.IN "XtOrderProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Cardinal (*XtOrderProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Passes the newly created widget.
+.LP
+.eM
+Composite widgets that allow clients to order their children (usually
+homogeneous boxes) can call their widget instance's insert_position
+procedure from the class's insert_child procedure to determine where a new
+child should go in its \fIchildren\fP array.
+Thus, a client using a composite class can apply different sorting criteria
+to widget instances of the class, passing in a different insert_position
+procedure resource when it creates each composite widget instance.
+.LP
+The return value of the insert_position procedure
+indicates how many children should go before the widget.
+Returning zero indicates that the widget should go before all other children,
+and returning \fInum_children\fP indicates that it should go after all other children.
+The default insert_position function returns \fInum_children\fP
+and can be overridden by a specific composite widget's resource list
+or by the argument list provided when the composite widget is created.
+
+.NH 2
+Deletion of Children: The delete_child Procedure
+.XS
+\*(SN Deletion of Children: The delete_child Procedure
+.XE
+.LP
+.IN "delete_child procedure"
+.LP
+To remove the child from the parent's \fIchildren\fP list, the
+.PN XtDestroyWidget
+function eventually causes a call to the Composite parent's class delete_child
+procedure.
+The delete_child procedure pointer is of type
+.PN XtWidgetProc .
+.LP
+.IN "delete_child procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtWidgetProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP
+Passes the child being deleted.
+.LP
+.eM
+Most widgets inherit the delete_child procedure from their superclass.
+Composite widgets that create companion widgets define their own
+delete_child procedure to remove these companion widgets.
+
+.NH 2
+Adding and Removing Children from the Managed Set
+.XS
+\fB\*(SN Adding and Removing Children from the Managed Set\fP
+.XE
+.LP
+The \*(xI provide a set of generic routines to permit the addition of
+widgets to or the removal of widgets from a composite widget's managed set.
+.IN "change_managed procedure"
+These generic routines eventually call the composite widget's change_managed
+procedure if the procedure pointer is non-NULL.
+The change_managed procedure pointer is of type
+.PN XtWidgetProc .
+The widget argument specifies the composite widget whose managed child
+set has been modified.
+
+.NH 3
+Managing Children
+.XS
+\fB\*(SN Managing Children\fP
+.XE
+.LP
+To add a list of widgets to the geometry-managed (and hence displayable)
+subset of their Composite parent, use
+.PN XtManageChildren .
+.LP
+.IN "XtManageChildren" "" "@DEF@"
+.sM
+.FD 0
+typedef Widget *WidgetList;
+.sp
+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 child widgets.  Each child must be of class
+RectObj or any subclass thereof.
+.IP \fInum_children\fP 1i
+Specifies the number of children in the list.
+.LP
+.eM
+The
+.PN XtManageChildren
+function performs the following:
+.IP \(bu 5
+Issues an error if the children do not all have the same parent or
+if the parent's class is not a subclass of 
+.PN compositeWidgetClass .
+.IP \(bu 5
+Returns immediately if the common parent is being destroyed;
+otherwise, for each unique child on the list,
+.PN XtManageChildren
+ignores the child if it already is managed or is being destroyed,
+and marks it if not.
+.IP \(bu 5
+If the parent is realized and after all children have been marked,
+it makes some of the newly managed children viewable:
+.RS
+.IP \- 5
+Calls the change_managed routine of the widgets' parent.
+.IP \- 5
+Calls
+.PN XtRealizeWidget
+on each previously unmanaged child that is unrealized.
+.IP \- 5
+Maps each previously unmanaged child that has \fImap_when_managed\fP 
+.PN True .
+.RE
+.LP
+Managing children is independent of the ordering of children and
+independent of creating and deleting children.
+The layout routine of the parent
+should consider children whose \fImanaged\fP field is
+.PN True 
+and should ignore all other children.
+Note that some composite widgets, especially fixed boxes, call
+.PN XtManageChild
+from their insert_child procedure.
+.LP
+If the parent widget is realized,
+its change_managed procedure is called to notify it
+that its set of managed children has changed.
+The parent can reposition and resize any of its children.
+It moves each child as needed by calling 
+.PN XtMoveWidget ,
+which first updates the \fIx\fP and \fIy\fP fields and which then calls
+.PN XMoveWindow .
+.LP
+If the composite widget wishes to change the size or border width of any of
+its children, it calls 
+.PN XtResizeWidget ,
+which first updates the
+\fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
+fields and then calls
+.PN XConfigureWindow .
+Simultaneous repositioning and resizing may be done with
+.PN XtConfigureWidget ;
+see Section 6.6.
+.sp
+.LP
+To add a single child to its parent widget's set of managed children, use
+.PN XtManageChild .
+.LP
+.IN "XtManageChild" "" "@DEF@"
+.sM
+.FD 0
+void XtManageChild(\fIchild\fP)
+.br
+      Widget \fIchild\fP;
+.FN
+.IP \fIchild\fP 1i
+Specifies the child.  \*(rI
+.LP
+.eM
+The
+.PN XtManageChild
+function constructs a
+.PN WidgetList
+of length 1 and calls
+.PN XtManageChildren .
+.sp
+.LP
+To create and manage a child widget in a single procedure, use
+.PN XtCreateManagedWidget
+or
+.PN XtVaCreateManagedWidget .
+.LP
+.IN "XtCreateManagedWidget" "" "@DEF@"
+.sM
+.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 resource instance name for the created widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created widget.  \*(rC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  Must be of class Composite or any
+subclass thereof.
+.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 XtCreateManagedWidget
+function is a convenience routine that calls
+.PN XtCreateWidget
+and
+.PN XtManageChild .
+.sp
+.LP
+.IN "XtVaCreateManagedWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Widget \fIparent\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the resource instance name for the created widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created widget.  \*(rC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  Must be of class Composite or any
+subclass thereof.
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+.PN XtVaCreateManagedWidget
+is identical in function to
+.PN XtCreateManagedWidget
+with the \fIargs\fP and \fInum_args\fP parameters replaced
+by a varargs list, as described in Section 2.5.1.
+
+.NH 3
+Unmanaging Children
+.XS
+\fB\*(SN Unmanaging Children\fP
+.XE
+.LP
+To remove a list of children from a parent widget's managed list, use
+.PN XtUnmanageChildren .
+.LP
+.IN "XtUnmanageChildren" "" "@DEF@"
+.sM
+.FD 0
+void XtUnmanageChildren(\fIchildren\fP, \fInum_children\fP)
+.br
+      WidgetList \fIchildren\fP;
+.br
+      Cardinal \fInum_children\fP;
+.FN
+.IP \fIchildren\fP 1i
+Specifies a list of child widgets.  Each child must be of class
+RectObj or any subclass thereof.
+.IP \fInum_children\fP 1i
+Specifies the number of children.
+.LP
+.eM
+The
+.PN XtUnmanageChildren
+function performs the following:
+.IP \(bu 5
+Returns immediately if the common parent is being destroyed.
+.IP \(bu 5
+Issues an error if the children do not all have the same parent
+or if the parent is not a subclass of 
+.PN compositeWidgetClass .
+.IP \(bu 5
+For each unique child on the list, 
+.PN XtUnmanageChildren
+ignores the child if it is unmanaged; otherwise it performs the following:
+.RS
+.IP \- 5
+Marks the child as unmanaged.
+.IP \- 5
+If the child is realized and the \fImap_when_managed\fP field is
+.PN True ,
+it is unmapped.
+.RE
+.IP \(bu 5
+If the parent is realized and if any children have become unmanaged,
+calls the change_managed routine of the widgets' parent.
+.LP
+.PN XtUnmanageChildren
+does not destroy the child widgets.
+Removing widgets from a parent's managed set is often a temporary banishment,
+and some time later the client may manage the children again.
+To destroy widgets entirely,
+.PN XtDestroyWidget
+should be called instead;
+see Section 2.9.
+.sp
+.LP
+To remove a single child from its parent widget's managed set, use
+.PN XtUnmanageChild .
+.LP
+.IN "XtUnmanageChild" "" "@DEF@"
+.sM
+.FD 0
+void XtUnmanageChild(\fIchild\fP)
+.br
+      Widget \fIchild\fP;
+.FN
+.IP \fIchild\fP 1i
+Specifies the child.  \*(rI
+.LP
+.eM
+The
+.PN XtUnmanageChild
+function constructs a widget list
+of length 1 and calls
+.PN XtUnmanageChildren .
+.LP
+These functions are low-level routines that are used by generic
+composite widget building routines.
+In addition, composite widgets can provide widget-specific,
+high-level convenience procedures.
+
+.NH 3
+Bundling Changes to the Managed Set
+.XS
+\fB\*(SN Bundling Changes to the Managed Set\fP
+.XE
+.LP
+A client may simultaneously unmanage and manage children
+with a single call to the \*(xI.  In this same call the
+client may provide a callback procedure that can modify the
+geometries of one or more children.  The composite widget class
+defines whether this single client call results in separate invocations
+of the change_managed method, one to unmanage and the other to
+manage, or in just a single invocation.
+.\" .LP
+.\" The composite widget class specifies how its change_managed method
+.\" should be invoked by declaring a
+.\" .PN CompositeClassExtension
+.\" structure as described in section 1.4.2.1.  If the
+.\" \fIallows_change_managed_set\fP field in the
+.\" .PN CompositeClassExtension
+.\" record is
+.\" .PN False ,
+.\" the change_managed method will be invoked twice; once before any
+.\" geometry changes are requested by the client callback and once
+.\" after.  If the \fIallows_change_managed_set\fP field is
+.\" .PN True ,
+.\" the change_managed method will be invoked just once after the
+.\" specified children have been marked as unmanaged or managed and
+.\" the client's callback has been invoked.
+.\" If no
+.\" .PN CompositeClassExtension
+.\" record is found in the extension field of the
+.\" composite class part with record type
+.\" .PN \s-1NULLQUARK\s+1
+.\" and version greater
+.\" than 1 and if
+.\" .PN XtInheritChangeManaged
+.\" was specified in the class record during class initialization, the
+.\" value of the \fIallows_change_managed_set\fP
+.\" field will be inherited from the superclass.
+.LP
+To simultaneously remove from and add to the geometry-managed
+set of children of a composite parent, use
+.PN XtChangeManagedSet .
+.LP
+.IN "XtChangeManagedSet" "" "@DEF@"
+.sM
+.FD 0
+void XtChangeManagedSet(\fIunmanage_children\fP, \fInum_unmanage_children\fP,
+                                              \fIdo_change_proc\fP, \fIclient_data\fP,
+                                              \fImanage_children\fP, \fInum_manage_children\fP)
+.br
+      WidgetList \fIunmanage_children\fP;
+.br
+      Cardinal \fInum_unmanage_children\fP;
+.br
+      XtDoChangeProc \fIdo_change_proc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      WidgetList \fImanage_children\fP;
+.br
+      Cardinal \fInum_manage_children\fP;
+.FN
+.IP \fIunmanage_children\fP 1.8i
+Specifies the list of widget children to initially remove from the managed set.
+.IP \fInum_unmanage_children\fP 1.8i
+Specifies the number of entries in the \fIunmanage_children\fP list.
+.IP \fIdo_change_proc\fP 1.8i
+Specifies a procedure to invoke between unmanaging
+and managing the children, or NULL.
+.IP \fIclient_data\fP 1.8i
+Specifies client data to be passed to the do_change_proc.
+.IP \fImanage_children\fP 1.8i
+Specifies the list of widget children to finally add to the managed set.
+.IP \fInum_manage_children\fP 1.8i
+Specifies the number of entries in the \fImanage_children\fP list.
+.LP
+.eM
+The 
+.PN XtChangeManagedSet
+function performs the following:
+.IP \(bu 5
+Returns immediately if \fInum_unmanage_children\fP and
+\fInum_manage_children\fP are both 0.
+.IP \(bu 5
+Issues a warning and returns if the widgets specified in the
+\fImanage_children\fP and
+the \fIunmanage_children\fP lists do not all have the same parent or if
+that parent is not a subclass of
+.PN compositeWidgetClass .
+.IP \(bu 5
+Returns immediately if the common parent is being destroyed.
+.IP \(bu 5
+If \fIdo_change_proc\fP is not NULL and the parent's
+.PN CompositeClassExtension
+\fIallows_change_managed_set\fP field is
+.PN False ,
+then
+.PN XtChangeManagedSet
+performs the following:
+.RS
+.IP \- 5
+Calls
+.PN XtUnmanageChildren
+(\fIunmanage_children\fP, \fInum_unmanage_children\fP).
+.IP \- 5
+Calls the \fIdo_change_proc\fP.
+.IP \- 5
+Calls
+.PN XtManageChildren
+(\fImanage_children\fP, \fInum_manage_children\fP).
+.RE
+.IP \(bu 5
+Otherwise, the following is performed:
+.RS
+.IP \- 5
+For each child on the \fIunmanage_children\fP list; if the child is
+already unmanaged it is ignored, otherwise it is marked as unmanaged,
+and if it is realized and its \fImap_when_managed\fP field is
+.PN True ,
+it is unmapped.
+.IP \- 5
+If \fIdo_change_proc\fP is non-NULL, the procedure is invoked.
+.IP \- 5
+For each child on the \fImanage_children\fP list; if the child is already
+managed or is being destroyed, it is ignored; otherwise it is 
+marked as managed.
+.IP \- 5
+If the parent is realized and after all children have been marked,
+the change_managed method of the parent is invoked, and subsequently 
+some of the newly managed children are made viewable by calling
+.PN XtRealizeWidget
+on each previously unmanaged child that is unrealized and
+mapping each previously unmanaged child that has \fImap_when_managed\fP
+.PN True .
+.RE
+.LP
+If no
+.PN CompositeClassExtension
+record is found in the parent's composite class part \fIextension\fP field
+with record type
+.PN \s-1NULLQUARK\s+1
+and version greater than 1, and if
+.PN XtInheritChangeManaged
+was specified in the parent's class record during class initialization,
+the value of the \fIallows_change_managed_set\fP
+field is inherited from the superclass.  The value inherited from
+.PN compositeWidgetClass
+for the \fIallows_change_managed_set\fP field is
+.PN False .
+.LP
+It is not an error to include a child in both the \fIunmanage_children\fP
+and the \fImanage_children\fP lists.  The effect of such a call is that
+the child remains managed following the call, but the \fIdo_change_proc\fP is
+able to affect the child while it is in an unmanaged state.
+.sp
+.LP
+The \fIdo_change_proc\fP is of type
+.PN XtDoChangeProc .
+.LP
+.IN "XtDoChangeProc" "" "@DEF"
+.sM
+.FD 0
+typedef void (*XtDoChangeProc)(Widget, WidgetList, Cardinal*, WidgetList, Cardinal*, XtPointer);
+.br
+      Widget \fIcomposite_parent\fP;
+.br
+      WidgetList \fIunmange_children\fP;
+.br
+      Cardinal *\fInum_unmanage_children\fP;
+.br
+      WidgetList \fImanage_children\fP;
+.br
+      Cardinal *\fInum_manage_children\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIcomposite_parent\fP 1.8i
+Passes the composite parent whose managed set is being altered.
+.IP \fIunmanage_children\fP 1.8i
+Passes the list of children just removed from the managed set.
+.IP \fInum_unmanage_children\fP 1.8i
+Passes the number of entries in the \fIunmanage_children\fP list.
+.IP \fImanage_children\fP 1.8i
+Passes the list of children about to be added to the managed set.
+.IP \fInum_manage_children\fP 1.8i
+Passes the number of entries in the \fImanage_children\fP list.
+.IP \fIclient_data\fP 1.8i
+Passes the client data passed to
+.PN XtChangeManagedSet .
+.LP
+.eM
+The \fIdo_change_proc\fP procedure is used by the caller of
+.PN XtChangeManagedSet
+to make changes to one or more children at the point when the
+managed set contains the fewest entries.  These changes may
+involve geometry requests, and in this case the caller of
+.PN XtChangeManagedSet
+may take advantage of the fact that the \*(xI internally grant
+geometry requests made by unmanaged children without invoking
+the parent's geometry manager.  To achieve this advantage, if
+the \fIdo_change_proc\fP procedure
+changes the geometry of a child or of a descendant of a child, then
+that child should be included in the \fIunmanage_children\fP and
+\fImanage_children\fP lists.
+
+.NH 3
+Determining if a Widget Is Managed
+.XS
+\fB\*(SN Determining if a Widget Is Managed\fP
+.XE
+.LP
+To determine the managed state of a given child widget, use
+.PN XtIsManaged .
+.LP
+.IN "XtIsManaged" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtIsManaged(\fIw\fP)
+.br
+       Widget \fIw\fP\^;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+The
+.PN XtIsManaged
+function returns
+.PN True
+if the specified widget is of class RectObj or any subclass thereof
+and is managed, or
+.PN False
+otherwise.
+
+.NH 2
+Controlling When Widgets Get Mapped
+.XS
+\fB\*(SN Controlling When Widgets Get Mapped\fP
+.XE
+.LP
+A widget is normally mapped if it is managed.
+However,
+this behavior can be overridden by setting the XtNmappedWhenManaged resource
+for the widget when it is created
+or by setting the \fImap_when_managed\fP field to 
+.PN False .
+.sp
+.LP
+To change the value of a given widget's \fImap_when_managed\fP field, use
+.PN XtSetMappedWhenManaged .
+.LP
+.IN "XtSetMappedWhenManaged" "" "@DEF@"
+.sM
+.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.  \*(cI
+.IP \fImap_when_managed\fP 1i
+Specifies a Boolean value that indicates the new value
+that is stored into the widget's \fImap_when_managed\fP 
+field.
+.LP
+.eM
+If the widget is realized and managed,
+and if \fImap_when_managed\fP is 
+.PN True ,
+.PN XtSetMappedWhenManaged
+maps the window.
+If the widget is realized and managed,
+and if \fImap_when_managed\fP is 
+.PN False ,
+it unmaps the window.
+.PN XtSetMappedWhenManaged
+is a convenience function that is equivalent to (but slightly faster than)
+calling
+.PN XtSetValues
+and setting the new value for the XtNmappedWhenManaged resource
+then mapping the widget as appropriate.
+As an alternative to using
+.PN XtSetMappedWhenManaged
+to control mapping,
+a client may set \fImapped_when_managed\fP to
+.PN False
+and use
+.PN XtMapWidget
+and
+.PN XtUnmapWidget
+explicitly.
+.sp
+.LP
+To map a widget explicitly, use
+.PN XtMapWidget .
+.LP
+.IN "XtMapWidget" "" "@DEF@"
+.sM
+.FD 0
+XtMapWidget(\fIw\fP)
+.br
+     Widget \fIw\fP\^;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+To unmap a widget explicitly, use
+.PN XtUnmapWidget .
+.LP
+.IN "XtUnmapWidget" "" "@DEF@"
+.sM
+.FD 0
+XtUnmapWidget(\fIw\fP)
+.br
+     Widget \fIw\fP\^;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+
+.NH 2
+Constrained Composite Widgets
+.XS
+\*(SN Constrained Composite Widgets
+.XE
+.LP
+The Constraint 
+widget class is a subclass of
+.PN compositeWidgetClass .
+The name is derived from the fact that constraint widgets
+may manage the geometry 
+of their children based on constraints associated with each child.
+These constraints can be as simple as the maximum width and height 
+the parent will allow the child to occupy or can be as complicated as
+how other children should change if this child is moved or resized.
+Constraint
+widgets let a parent define constraints as resources that are supplied for their children.
+For example, if the
+Constraint
+parent defines the maximum sizes for its children,
+these new size resources are retrieved for each child as if they were
+resources that were defined by the child widget's class.
+Accordingly,
+constraint resources may be included in the argument list or resource file just
+like any other resource for the child.
+.LP
+Constraint 
+widgets have all the responsibilities of normal composite widgets
+and, in addition, must process and act upon the constraint information
+associated with each of their children.
+.LP
+To make it easy for widgets and the \*(xI to keep track of the
+constraints associated with a child, 
+every widget has a \fIconstraints\fP field,
+which is the address of a parent-specific structure that contains
+constraint information about the child.
+If a child's parent does not belong to a subclass of
+.PN constraintWidgetClass ,
+then the child's \fIconstraints\fP field is NULL.
+.LP
+Subclasses of
+Constraint 
+can add constraint data to the constraint record defined by their superclass.
+To allow this, widget writers should define the constraint
+records in their private .h file by using the same conventions as used for
+widget records.
+For example, a widget class that needs to maintain a maximum
+width and height for each child might define its constraint record as
+follows:
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	Dimension max_width, max_height;
+} MaxConstraintPart;
+
+typedef struct {
+	MaxConstraintPart max;
+} MaxConstraintRecord, *MaxConstraint;
+.De
+.LP
+A subclass of this widget class that also needs to maintain a minimum size would
+define its constraint record as follows:
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	Dimension min_width, min_height;
+} MinConstraintPart;
+
+typedef struct {
+	MaxConstraintPart max;
+	MinConstraintPart min;
+} MaxMinConstraintRecord, *MaxMinConstraint;
+.De
+.LP
+Constraints are allocated, initialized, deallocated, and otherwise maintained
+insofar as possible by the \*(xI.
+The Constraint class record part has several entries that facilitate this.
+All entries in
+.PN ConstraintClassPart
+are fields and procedures that are defined and implemented by the parent,
+but they are called whenever actions are performed on the parent's children.
+.LP
+The
+.PN XtCreateWidget
+function uses the \fIconstraint_size\fP field in the parent's class record
+to allocate a constraint record when a child is created.
+.PN XtCreateWidget
+also uses the constraint resources to fill in resource fields in the
+constraint record associated with a child.
+It then calls the constraint initialize procedure so that the parent
+can compute constraint fields that are derived from constraint resources
+and can possibly move or resize the child to conform to the given constraints.
+.LP
+When the
+.PN XtGetValues
+and
+.PN XtSetValues
+functions are executed
+on a child, they use the constraint resources to get the values or
+set the values of constraints associated with that child.
+.PN XtSetValues
+then calls the constraint set_values procedures so that the parent can
+recompute derived constraint fields and move or resize the child
+as appropriate.
+If a
+Constraint
+widget class or any of its superclasses have declared a
+.PN ConstraintClassExtension
+record in the
+.PN ConstraintClassPart
+\fIextension\fP
+fields with a record type of
+.PN \s-1NULLQUARK\s+1
+and the \fIget_values_hook\fP field in
+.IN "get_values_hook procedure"
+.IN "Constraint" "get_values_hook"
+the extension record is non-NULL,
+.PN XtGetValues
+calls the get_values_hook
+procedure(s) to allow the parent to return derived constraint fields.
+.LP
+The
+.PN XtDestroyWidget
+function calls the constraint destroy procedure to deallocate any
+dynamic storage associated with a constraint record.
+The constraint record itself must not be deallocated by the constraint
+destroy procedure;
+.PN XtDestroyWidget
+does this automatically.
+.bp
diff --git a/libXt/specs/CH04 b/libXt/specs/CH04
new file mode 100644
index 000000000..0291aa333
--- /dev/null
+++ b/libXt/specs/CH04
@@ -0,0 +1,1998 @@
+.\" $Xorg: CH04,v 1.3 2000/08/17 19:42:44 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 4\fP\s-1
+
+\s+1\fBShell Widgets\fP\s-1
+.sp 2
+.nr H1 4
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 4 \(em Shell Widgets
+.XE
+.IN "Shell" "" "@DEF@"
+.LP
+Shell widgets hold an application's top-level widgets to allow them to
+communicate with the window manager and session manager.
+Shells have been designed to be as nearly invisible as possible.
+Clients have to create them,
+but they should never have to worry about their sizes.
+.LP
+If a shell widget is resized from the outside (typically by a window manager),
+the shell widget also resizes its managed child widget automatically.
+Similarly, if the shell's child widget needs to change size,
+it can make a geometry request to the shell,
+and the shell negotiates the size change with the outer environment.
+Clients should never attempt to change the size of their shells directly.
+.LP
+The five types of public shells are:
+.TS
+lw(1.5i) lw(4.25i).
+T{
+.PN OverrideShell
+T}	T{
+Used for shell windows that completely bypass the window manager
+(for example, pop-up menu shells).
+T}
+.sp
+T{
+.PN TransientShell
+T}	T{
+Used for shell windows that have the
+.PN \s-1WM_TRANSIENT_FOR\s+1
+property set. The effect of this property is dependent upon the
+window manager being used.
+T}
+.sp
+T{
+.PN TopLevelShell
+T}	T{
+Used for normal top-level windows
+(for example, any additional top-level widgets an application needs).
+T}
+.sp
+T{
+.PN ApplicationShell
+T}	T{
+Formerly used for the single main top-level window that
+the window manager identifies as an application instance and
+made obsolete by SessionShell.
+T}
+.IN "ApplicationShell" "" "@DEF@"
+.sp
+T{
+.PN SessionShell
+T}	T{
+Used for the single main top-level window that
+the window manager identifies as an application instance and
+that interacts with the session manager.
+T}
+.IN "SessionShell" "" "@DEF@"
+.TE
+
+.NH 2
+Shell Widget Definitions
+.XS
+\*(SN Shell Widget Definitions
+.XE
+.LP
+Widgets negotiate their size and position with their parent widget, 
+that is, the widget that directly contains them.
+Widgets at the top of the hierarchy do not have parent widgets. 
+Instead, they must deal with the outside world.
+To provide for this, 
+each top-level widget is encapsulated in a special widget, called a
+shell widget.
+.LP
+Shell
+widgets, whose class is a subclass of the 
+Composite class,
+encapsulate other widgets and can allow a widget to avoid the
+geometry clipping imposed by the parent-child window relationship.
+They also can provide a layer of communication with the window manager.
+.LP
+The eight different types of shells are:
+.TS
+lw(1.5i) lw(4.5i).
+T{
+.PN Shell
+T}	T{
+The base class for shell widgets; provides the
+fields needed for all types of shells.
+Shell
+is a direct subclass of
+.PN compositeWidgetClass .
+T}
+.sp 6p
+T{
+.PN OverrideShell
+T}	T{
+A subclass of Shell; used for shell windows that completely
+bypass the window manager.
+T}
+.sp 6p
+T{
+.PN WMShell
+T}	T{
+A subclass of Shell; contains fields needed by the
+common window manager protocol.
+T}
+.sp 6p
+T{
+.PN VendorShell
+T}	T{
+A subclass of WMShell; contains fields used by
+vendor-specific window managers.
+T}
+.sp 6p
+T{
+.PN TransientShell
+T}	T{
+A subclass of VendorShell; used for shell windows that
+desire the
+.PN \s-1WM_TRANSIENT_FOR\s+1
+property.
+T}
+.sp 6p
+T{
+.PN TopLevelShell
+T}	T{
+A subclass of VendorShell; used for normal top-level windows.
+T}
+.sp 6p
+T{
+.PN ApplicationShell
+T}	T{
+A subclass of TopLevelShell; may be used for an application's additional
+root windows.
+T}
+.sp 6p
+T{
+.PN SessionShell
+T}	T{
+A subclass of ApplicationShell; used for an application's
+main root window.
+T}
+.TE
+.LP
+Note that the classes
+Shell,
+WMShell,
+and
+VendorShell
+are internal and should not be instantiated or subclassed.
+Only
+OverrrideShell,
+TransientShell,
+TopLevelShell,
+ApplicationShell,
+and 
+SessionShell
+are intended for public use.
+
+.NH 3
+ShellClassPart Definitions
+.XS
+\*(SN ShellClassPart Definitions
+.XE
+.LP
+Only the
+Shell
+class has additional class fields, which are all contained in the
+.PN ShellClassExtensionRec .
+None of the other Shell classes have any additional class fields:
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+        XtPointer extension;
+} ShellClassPart, OverrideShellClassPart,
+WMShellClassPart, VendorShellClassPart, TransientShellClassPart,
+TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart;
+.De
+.LP
+.eM
+.KE
+The full Shell class record definitions are:
+.IN "ShellClassExtension" "" "@DEF@"
+.IN "ShellClassExtensionRec" "" "@DEF@"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _ShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+} ShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	XtPointer	next_extension;	See Section 1.6.12
+	XrmQuark	record_type;	See Section 1.6.12
+	long	version;	See Section 1.6.12
+	Cardinal	record_size;	See Section 1.6.12
+	XtGeometryHandler	root_geometry_manager;	See below
+} ShellClassExtensionRec, *ShellClassExtension;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _OverrideShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	OverrideShellClassPart	override_shell_class;
+} OverrideShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _WMShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	WMShellClassPart	wm_shell_class;
+} WMShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _VendorShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	WMShellClassPart	wm_shell_class;
+	VendorShellClassPart	vendor_shell_class;
+} VendorShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _TransientShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	WMShellClassPart	wm_shell_class;
+	VendorShellClassPart	vendor_shell_class;
+	TransientShellClassPart	transient_shell_class;
+} TransientShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _TopLevelShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	WMShellClassPart	wm_shell_class;
+	VendorShellClassPart	vendor_shell_class;
+	TopLevelShellClassPart	top_level_shell_class;
+} TopLevelShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _ApplicationShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	WMShellClassPart	wm_shell_class;
+	VendorShellClassPart	vendor_shell_class;
+	TopLevelShellClassPart	top_level_shell_class;
+	ApplicationShellClassPart	application_shell_class;
+} ApplicationShellClassRec;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct _SessionShellClassRec {
+	CoreClassPart	core_class;
+	CompositeClassPart	composite_class;
+	ShellClassPart	shell_class;
+	WMShellClassPart	wm_shell_class;
+	VendorShellClassPart	vendor_shell_class;
+	TopLevelShellClassPart	top_level_shell_class;
+	ApplicationShellClassPart	application_shell_class;
+	SessionShellClassPart	session_shell_class;
+} SessionShellClassRec;
+.De
+.LP
+.eM
+.KE
+.KS
+The single occurrences of the class records and pointers for creating
+instances of shells are:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern ShellClassRec shellClassRec;
+extern OverrideShellClassRec overrideShellClassRec;
+extern WMShellClassRec wmShellClassRec;
+extern VendorShellClassRec vendorShellClassRec;
+extern TransientShellClassRec transientShellClassRec;
+extern TopLevelShellClassRec topLevelShellClassRec;
+extern ApplicationShellClassRec applicationShellClassRec;
+extern SessionShellClassRec sessionShellClassRec;
+.sp
+extern WidgetClass shellWidgetClass;
+extern WidgetClass overrideShellWidgetClass;
+extern WidgetClass wmShellWidgetClass;
+extern WidgetClass vendorShellWidgetClass;
+extern WidgetClass transientShellWidgetClass;
+extern WidgetClass topLevelShellWidgetClass;
+extern WidgetClass applicationShellWidgetClass;
+extern WidgetClass sessionShellWidgetClass;
+.De
+.LP
+.eM
+.KE
+.KS
+The following opaque types and opaque variables are defined
+for generic operations on widgets whose class is a subclass of
+Shell.
+.TS
+lw(2.75i) lw(2.75i).
+_
+.sp 6p
+Types	Variables
+.sp 6p
+_
+.sp 6p
+T{
+.PN ShellWidget
+T}	T{
+.PN shellWidgetClass
+T}
+T{
+.PN OverrideShellWidget
+T}	T{
+.PN overrideShellWidgetClass
+T}
+T{
+.PN WMShellWidget
+T}	T{
+.PN wmShellWidgetClass
+T}
+T{
+.PN VendorShellWidget
+T}	T{
+.PN vendorShellWidgetClass
+T}
+T{
+.PN TransientShellWidget
+T}	T{
+.PN transientShellWidgetClass
+T}
+T{
+.PN TopLevelShellWidget
+T}	T{
+.PN topLevelShellWidgetClass
+T}
+T{
+.PN ApplicationShellWidget
+T}	T{
+.PN applicationShellWidgetClass
+T}
+T{
+.PN SessionShellWidget
+T}	T{
+.PN sessionShellWidgetClass
+T}
+.PN ShellWidgetClass
+.PN OverrideShellWidgetClass
+.PN WMShellWidgetClass
+.PN VendorShellWidgetClass
+.PN TransientShellWidgetClass
+.PN TopLevelShellWidgetClass
+.PN ApplicationShellWidgetClass
+.PN SessionShellWidgetClass
+.sp 6p
+_
+.TE
+.KE
+.LP
+The declarations for all Intrinsics-defined shells except
+VendorShell appear in
+.PN Shell.h
+and
+.PN ShellP.h .
+VendorShell has separate public and private .h files which are included by
+.PN Shell.h
+and
+.PN ShellP.h .
+.LP
+.PN Shell.h
+uses incomplete structure definitions to ensure that the
+compiler catches attempts to access private data in any of the Shell
+instance or class data structures.
+.LP
+The symbolic constant for the
+.PN ShellClassExtension
+version identifier is
+.PN XtShellExtensionVersion
+(see Section 1.6.12).
+.IN "XtShellExtensionVersion" "" "@DEF@"
+.LP
+.IN "Shell" "root_geometry_manager"
+.IN "root_geometry_manager procedure"
+The root_geometry_manager procedure acts as
+the parent geometry manager for geometry requests made by shell
+widgets.  When a shell widget calls either
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest ,
+the root_geometry_manager procedure is invoked to
+negotiate the new geometry with the window manager.  If the window
+manager permits the new geometry, the root_geometry_manager
+procedure should
+return
+.PN XtGeometryYes ;
+if the window manager denies the geometry
+request or does not change the window geometry within some timeout
+interval (equal to \fIwm_timeout\fP in the case of WMShells), the
+.IN "Shell" "wm_timeout" "@DEF@"
+.IN "wm_timeout" "" "@DEF@"
+root_geometry_manager procedure should return
+.PN XtGeometryNo .
+If the window manager makes some alternative geometry change, the
+root_geometry_manager procedure may return either
+.PN XtGeometryNo
+and handle the new geometry as a resize or
+.PN XtGeometryAlmost
+in anticipation that the shell will accept the compromise.  If the
+compromise is not accepted, the new size must then be handled as a
+resize.  Subclasses of
+Shell
+that wish to provide their own
+root_geometry_manager procedures are strongly encouraged to use enveloping to
+invoke their superclass's root_geometry_manager procedure under most
+situations, as the window manager interaction may be very complex.
+.LP
+If no
+.PN ShellClassPart
+extension record is declared with \fIrecord_type\fP
+equal to
+.PN \s-1NULLQUARK\s+1 ,
+then
+.PN XtInheritRootGeometryManager
+is assumed.
+
+.NH 3
+ShellPart Definition
+.XS
+\*(SN ShellPart Definition
+.XE
+.LP
+The various shell widgets have the following additional instance
+fields defined in
+their widget records:
+.LP
+.IN "ShellPart" "" "@DEF@"
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	String	geometry;
+	XtCreatePopupChildProc	create_popup_child_proc;
+	XtGrabKind	grab_kind;
+	Boolean	spring_loaded;
+	Boolean	popped_up;
+	Boolean	allow_shell_resize;
+	Boolean	client_specified;
+	Boolean	save_under;
+	Boolean	override_redirect;
+	XtCallbackList	popup_callback;
+	XtCallbackList	popdown_callback;
+	Visual *	visual;
+} ShellPart;
+.De
+.KE
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	int	empty;
+} OverrideShellPart;
+.De
+.Ds 0
+.TA .5i 1i 1.5i 2.5i
+.ta .5i 1i 1.5i 2.5i
+typedef struct {
+	String			title;
+	int			wm_timeout;
+	Boolean			wait_for_wm;
+	Boolean			transient;
+	Boolean			urgency;
+	Widget			client_leader;
+	String			window_role;
+	struct _OldXSizeHints {
+		long		flags;
+		int		 x, y;
+		int		width, height;
+		int		min_width, min_height;
+		int		max_width, max_height;
+		int		width_inc, height_inc;
+		struct {
+			int	x;
+			int	y;
+		} min_aspect, max_aspect;
+	} size_hints;
+	XWMHints			wm_hints;
+	int			base_width, base_height, win_gravity;
+	Atom			title_encoding;
+} WMShellPart;
+.De
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	int	vendor_specific;
+} VendorShellPart;
+.De
+.KE
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	Widget	transient_for;
+} TransientShellPart;
+
+typedef struct {
+	String	icon_name;
+	Boolean	iconic;
+	Atom	icon_name_encoding;
+} TopLevelShellPart;
+.De
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	char *	class;
+	XrmClass	xrm_class;
+	int	argc;
+	char **	argv;
+} ApplicationShellPart;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	SmcConn	connection;
+	String	session_id;
+	String *	restart_command;
+	String *	clone_command;
+	String *	discard_command;
+	String *	resign_command;
+	String *	shutdown_command;
+	String *	environment;
+	String	current_dir;
+	String	program_path;
+	unsigned char	restart_style;
+	Boolean	join_session;
+	XtCallbackList	save_callbacks;
+	XtCallbackList	interact_callbacks;
+	XtCallbackList	cancel_callbacks;
+	XtCallbackList	save_complete_callbacks;
+	XtCallbackList	die_callbacks;
+	XtCallbackList	error_callbacks;
+} SessionShellPart;
+.De
+.LP
+.eM
+.KE
+.KS
+The full shell widget instance record definitions are:
+.LP
+.IN "ShellWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+} ShellRec, *ShellWidget;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	OverrideShellPart	override;
+} OverrideShellRec, *OverrideShellWidget;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	WMShellPart	wm;
+} WMShellRec, *WMShellWidget;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	WMShellPart	wm;
+	VendorShellPart	vendor;
+} VendorShellRec, *VendorShellWidget;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	WMShellPart	wm;
+	VendorShellPart	vendor;
+	TransientShellPart	transient;
+} TransientShellRec, *TransientShellWidget;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	WMShellPart	wm;
+	VendorShellPart	vendor;
+	TopLevelShellPart	topLevel;
+} TopLevelShellRec, *TopLevelShellWidget;
+.De
+.KE
+.KS
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+.IN "ApplicationShellWidget" "" "@DEF@"
+typedef  struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	WMShellPart	wm;
+	VendorShellPart	vendor;
+	TopLevelShellPart	topLevel;
+	ApplicationShellPart	application;
+} ApplicationShellRec, *ApplicationShellWidget;
+.De
+.KE
+.KS
+.IN "SessionShellWidget" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i 4.5i
+.ta .5i 2.5i 4.5i
+typedef  struct {
+	CorePart	core;
+	CompositePart	composite;
+	ShellPart	shell;
+	WMShellPart	wm;
+	VendorShellPart	vendor;
+	TopLevelShellPart	topLevel;
+	ApplicationShellPart	application;
+	SessionShellPart	session;
+} SessionShellRec, *SessionShellWidget;
+.De
+.LP
+.eM
+.KE
+
+.NH 3
+Shell Resources
+.XS
+\fB\*(SN Shell Resources\fP
+.XE
+.LP
+.IN "ShellWidget" "Resources"
+The resource names, classes, and representation types specified in
+the
+.PN shellClassRec
+resource list are:
+.LP
+.TS
+lw(1.7i) lw(1.7i) lw(1.2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNallowShellResize	XtCAllowShellResize	XtRBoolean
+XtNcreatePopupChildProc	XtCCreatePopupChildProc	XtRFunction
+XtNgeometry	XtCGeometry	XtRString
+XtNoverrideRedirect	XtCOverrideRedirect	XtRBoolean
+XtNpopdownCallback	XtCCallback	XtRCallback
+XtNpopupCallback	XtCCallback	XtRCallback
+XtNsaveUnder	XtCSaveUnder	XtRBoolean
+XtNvisual	XtCVisual	XtRVisual
+.sp 6p
+_
+.TE
+.LP
+OverrideShell
+declares no additional resources beyond those defined by
+Shell.
+.LP
+The resource names, classes, and representation types specified in
+the
+.PN wmShellClassRec
+.IN "WMShell" "resources"
+resource list are:
+.LP
+.TS
+lw(2.1i) lw(2.1i) lw(1.2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNbaseHeight	XtCBaseHeight	XtRInt
+XtNbaseWidth	XtCBaseWidth	XtRInt
+XtNclientLeader	XtCClientLeader	XtRWidget
+XtNheightInc	XtCHeightInc	XtRInt
+XtNiconMask	XtCIconMask	XtRBitmap
+XtNiconPixmap	XtCIconPixmap	XtRBitmap
+XtNiconWindow	XtCIconWindow	XtRWindow
+XtNiconX	XtCIconX	XtRInt
+XtNiconY	XtCIconY	XtRInt
+XtNinitialState	XtCInitialState	XtRInitialState
+XtNinput	XtCInput	XtRBool
+XtNmaxAspectX	XtCMaxAspectX	XtRInt
+XtNmaxAspectY	XtCMaxAspectY	XtRInt
+XtNmaxHeight	XtCMaxHeight	XtRInt
+XtNmaxWidth	XtCMaxWidth	XtRInt
+XtNminAspectX	XtCMinAspectX	XtRInt
+XtNminAspectY	XtCMinAspectY	XtRInt
+XtNminHeight	XtCMinHeight	XtRInt
+XtNminWidth	XtCMinWidth	XtRInt
+XtNtitle	XtCTitle	XtRString
+XtNtitleEncoding	XtCTitleEncoding	XtRAtom
+XtNtransient	XtCTransient	XtRBoolean
+XtNwaitforwm, XtNwaitForWm	XtCWaitforwm, XtCWaitForWm	XtRBoolean
+XtNwidthInc	XtCWidthInc	XtRInt
+XtNwindowRole	XtCWindowRole	XtRString
+XtNwinGravity	XtCWinGravity	XtRGravity
+XtNwindowGroup	XtCWindowGroup	XtRWindow
+XtNwmTimeout	XtCWmTimeout	XtRInt
+XtNurgency	XtCUrgency	XtRBoolean
+.sp 6p
+_
+.TE
+.LP
+The class resource list for
+VendorShell
+is implementation-defined.
+.LP
+The resource names, classes, and representation types that are specified in the
+.PN transient\%ShellClassRec
+.IN "TransientShell" "resources"
+resource list are:
+.LP
+.TS
+lw(1.7i) lw(1.7i) lw(1.2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNtransientFor	XtCTransientFor	XtRWidget
+.sp 6p
+_
+.TE
+.LP
+The resource names, classes, and representation types that are specified in the
+.PN topLevelShellClassRec
+.IN "TopLevelShell" "resources"
+resource list are:
+.LP
+.TS
+lw(1.7i) lw(1.7i) lw(1.2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNiconName	XtCIconName	XtRString
+XtNiconNameEncoding	XtCIconNameEncoding	XtRAtom
+XtNiconic	XtCIconic	XtRBoolean
+.sp 6p
+_
+.TE
+.LP
+The resource names, classes, and representation types that are specified in the
+.PN application\%ShellClassRec
+resource list are:
+.LP
+.TS
+lw(1.7i) lw(1.7i) lw(1.2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNargc	XtCArgc	XtRInt
+XtNargv	XtCArgv	XtRStringArray
+.sp 6p
+_
+.TE
+.LP
+.KS
+The resource names, classes, and representation types that are specified
+in the
+.PN sessionShellClassRec
+resource list are:
+.LP
+.TS
+lw(1.7i) lw(1.7i) lw(1.2i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+XtNcancelCallback	XtCCallback	XtRCallback
+XtNcloneCommand	XtCCloneCommand	XtRCommandArgArray
+XtNconnection	XtCConnection	XtRSmcConn
+XtNcurrentDirectory	XtCCurrentDirectory	XtRDirectoryString
+XtNdieCallback	XtCCallback	XtRCallback
+XtNdiscardCommand	XtCDiscardCommand	XtRCommandArgArray
+XtNenvironment	XtCEnvironment	XtREnvironmentArray
+XtNerrorCallback	XtCCallback	XtRCallback
+XtNinteractCallback	XtCCallback	XtRCallback
+XtNjoinSession	XtCJoinSession	XtRBoolean
+XtNprogramPath	XtCProgramPath	XtRString
+XtNresignCommand	XtCResignCommand	XtRCommandArgArray
+XtNrestartCommand	XtCRestartCommand	XtRCommandArgArray
+XtNrestartStyle	XtCRestartStyle	XtRRestartStyle
+XtNsaveCallback	XtCCallback	XtRCallback
+XtNsaveCompleteCallback	XtCCallback	XtRCallback
+XtNsessionID	XtCSessionID	XtRString
+XtNshutdownCommand	XtCShutdownCommand	XtRCommandArgArray
+.sp 6p
+_
+.TE
+.KE
+.NH 3
+ShellPart Default Values
+.XS
+\fB\*(SN ShellPart Default Values\fP
+.XE
+.LP
+The default values for fields common to all classes of public shells
+(filled in by the 
+Shell
+resource lists and the 
+Shell 
+initialize procedures) are:
+.TS
+lw(1.75i) lw(3i).
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+geometry	NULL
+create_popup_child_proc	NULL
+grab_kind	(none)
+spring_loaded	(none)
+popped_up	T{
+.PN False
+T}
+allow_shell_resize	T{
+.PN False
+T}
+client_specified	(internal)
+save_under	T{
+.PN True 
+for
+OverrideShell 
+and
+TransientShell,
+.PN False 
+otherwise
+T}
+override_redirect	T{
+.PN True 
+for
+OverrideShell,
+.PN False 
+otherwise
+T}
+popup_callback	NULL
+popdown_callback	NULL
+visual	T{
+.PN CopyFromParent
+T}
+.sp 6p
+_
+.TE
+.LP
+The \fIgeometry\fP field specifies the size and position
+and is usually given only on a command line or in a defaults file.
+If the \fIgeometry\fP field is non-NULL when
+a widget of class WMShell
+is realized, the geometry specification is parsed using
+.PN XWMGeometry
+with a default geometry
+string constructed from the values of \fIx\fP, \fIy\fP, \fIwidth\fP,
+\fIheight\fP, \fIwidth_inc\fP,
+and \fIheight_inc\fP and the size and position flags in the window manager
+size hints are set.  If the geometry specifies an x or y position,
+then
+.PN USPosition
+is set.  If the geometry specifies a width or height, then
+.PN USSize
+is set.  Any fields in the geometry specification
+override the corresponding values in the
+Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields.
+If \fIgeometry\fP is NULL or contains only a partial specification, then the
+Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields are used and
+.PN PPosition
+and
+.PN PSize
+are set as appropriate.
+The geometry string is not copied by any of the \*(xI
+Shell classes; a client specifying the string in an arglist
+or varargs list must ensure
+that the value remains valid until the shell widget is realized.
+For further information on the geometry string, see Section 16.4
+in \fI\*(xL\fP.
+.LP
+The \fIcreate_popup_child_proc\fP procedure is called by the
+.PN XtPopup
+procedure and may remain NULL.
+The \fIgrab_kind\fP, \fIspring_loaded\fP,
+and \fIpopped_up\fP fields maintain widget
+state information as described under
+.PN XtPopup ,
+.PN XtMenuPopup ,
+.PN XtPopdown ,
+and
+.PN XtMenuPopdown .
+.IN "allowShellResize" "" "@DEF@"
+The \fIallow_shell_resize\fP field controls whether the widget contained
+by the shell is allowed to try to resize itself.
+If allow_shell_resize is 
+.PN False , 
+any geometry requests made by the child will always return
+.PN XtGeometryNo
+without interacting with the window manager.
+Setting \fIsave_under\fP
+.PN True
+instructs the server to attempt
+to save the contents of windows obscured by the shell when it is mapped
+and to restore those contents automatically when the shell is unmapped.
+It is useful for pop-up menus.
+Setting \fIoverride_redirect\fP
+.PN True
+determines
+whether the window manager can intercede when the shell window
+is mapped.
+For further information on override_redirect,
+see Section 3.2 in \fI\*(xL\fP and Sections 4.1.10 and 4.2.2 in the
+\fI\*(xC\fP.
+The pop-up and pop-down callbacks are called during
+.PN XtPopup
+and
+.PN XtPopdown .
+The default value of the \fIvisual\fP resource is the symbolic value
+.PN CopyFromParent .
+The \*(xI do not need to query the parent's visual type when the
+default value is used; if a client using
+.PN XtGetValues
+to examine the visual type receives the value
+.PN CopyFromParent ,
+it must then use
+.PN XGetWindowAttributes
+if it needs the actual visual type.
+
+.LP
+The default values for Shell fields in
+WMShell
+and its subclasses are:
+.LP
+.IN "XtUnspecifiedShellInt" "" "@DEF@"
+.IN "XtUnspecifiedWindow"
+.TS
+lw(1i) lw(4i).
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+title	T{
+Icon name, if specified, otherwise the application's name
+T}
+wm_timeout	Five seconds, in units of milliseconds
+wait_for_wm	T{
+.PN True
+T}
+transient	T{
+.PN True 
+for
+TransientShell,
+.PN False 
+otherwise
+T}
+urgency	T{
+.PN False
+T}
+client_leader	NULL
+window_role	NULL
+min_width	\fBXtUnspecifiedShellInt\fP
+min_height	\fBXtUnspecifiedShellInt\fP
+max_width	\fBXtUnspecifiedShellInt\fP
+max_height	\fBXtUnspecifiedShellInt\fP
+width_inc	\fBXtUnspecifiedShellInt\fP
+height_inc	\fBXtUnspecifiedShellInt\fP
+min_aspect_x	\fBXtUnspecifiedShellInt\fP
+min_aspect_y	\fBXtUnspecifiedShellInt\fP
+max_aspect_x	\fBXtUnspecifiedShellInt\fP
+max_aspect_y	\fBXtUnspecifiedShellInt\fP
+input	T{
+.PN False
+T}
+initial_state	Normal
+icon_pixmap	None
+icon_window	None
+icon_x	\fBXtUnspecifiedShellInt\fP
+icon_y	\fBXtUnspecifiedShellInt\fP
+icon_mask	None
+window_group	\fBXtUnspecifiedWindow\fP
+base_width	\fBXtUnspecifiedShellInt\fP
+base_height	\fBXtUnspecifiedShellInt\fP
+win_gravity	\fBXtUnspecifiedShellInt\fP
+title_encoding	See text
+.sp 6p
+_
+.TE
+.LP
+The \fItitle\fP and
+\fItitle_encoding\fP fields are stored in the
+.PN \s-1WM_NAME\s+1
+property on the shell's window by the WMShell realize procedure.
+If the \fItitle_encoding\fP field is
+.PN None ,
+the \fItitle\fP string is assumed to be in the encoding of the current
+locale and the encoding of the
+.PN \s-1WM_NAME\s+1
+property is set to
+.PN XStdICCTextStyle .
+If a language procedure has not been set
+the default value of \fItitle_encoding\fP is
+\fB\s-1XA_STRING\s+1\fP, otherwise the default value is
+.PN None .
+The \fIwm_timeout\fP field specifies, in milliseconds,
+the amount of time a shell is to wait for
+confirmation of a geometry request to the window manager.
+If none comes back within that time,
+the shell assumes the window manager is not functioning properly
+and sets \fIwait_for_wm\fP to
+.PN False 
+(later events may reset this value).
+When \fIwait_for_wm\fP is 
+.PN False ,
+the shell does not wait for a response, but relies on asynchronous 
+notification.
+If \fItransient\fP is
+.PN True ,
+the
+.PN \s-1WM_TRANSIENT_FOR\s+1
+property
+will be stored on the shell window with a value as specified below.
+The interpretation of this property is specific to the window manager
+under which the application is run; see the \fI\*(xC\fP for more details.
+.LP
+The realize and set_values procedures of WMShell store the 
+.PN \s-1WM_CLIENT_LEADER\s+1
+property on the shell window.
+When \fIclient_leader\fP is not NULL and the client leader widget is
+realized, the property will be created with the value of the window of the
+client leader widget.
+When \fIclient_leader\fP is NULL and the shell widget has a NULL parent,
+the widget's window is used as the value of the
+property.
+When \fIclient_leader\fP is NULL and the shell widget has a non-NULL parent,
+a search is made for the closest shell ancestor
+with a non-NULL \fIclient_leader\fP,
+and if none is found the shell ancestor with a NULL parent is the result.
+If the resulting widget is realized, the property is created 
+with the value of the widget's window.
+.LP
+When the value of \fIwindow_role\fP is not NULL, the
+realize and set_values procedures store the
+.PN \s-1WM_WINDOW_ROLE\s+1
+property on the shell's window with the value of the resource.
+.LP
+All other resources specify fields in the window manager hints
+and the window manager size hints.
+The realize and set_values procedures of
+WMShell
+set the corresponding flag bits in the
+hints if any of the fields contain nondefault values.  In addition, if
+a flag bit is set that refers to a field with the value
+.PN XtUnspecifiedShellInt ,
+the value of the field is modified as follows:
+.br
+.sp
+.TS
+lw(2i) lw(3i).
+_
+.sp 6p
+Field	Replacement
+.sp 6p
+_
+.sp 6p
+base_width, base_height	0
+width_inc, height_inc	1
+max_width, max_height	32767
+min_width, min_height	1
+min_aspect_x, min_aspect_y	-1
+max_aspect_x, max_aspect_y	-1
+icon_x, icon_y	-1
+win_gravity	T{
+Value returned by
+.PN XWMGeometry
+if called,
+else \fBNorthWestGravity\fP
+T}
+.sp 6p
+_
+.TE
+
+.IN "XWMGeometry"
+.LP
+If the shell widget has a non-NULL parent, then the
+realize and set_values procedures replace the value
+.PN XtUnspecifiedWindow
+.IN "XtUnspecifiedWindow" "" "@DEF@"
+in the \fIwindow_group\fP field with the window id of the root widget
+of the widget tree if the
+root widget is realized. The symbolic constant
+.PN XtUnspecifiedWindowGroup
+.IN "XtUnspecifiedWindowGroup" "" "@DEF@"
+may be used to indicate that the \fIwindow_group\fP hint flag bit is not
+to be set.  If \fItransient\fP is
+.PN True ,
+the shell's class is not a subclass of
+TransientShell,
+and \fIwindow_group\fP is not
+.PN XtUnspecifiedWindowGroup ,
+the WMShell realize and set_values procedures then store the
+.PN \s-1WM_TRANSIENT_FOR\s+1
+property with the value of \fIwindow_group\fP.
+.LP
+.KS
+Transient
+shells have the following additional resource:
+.TS
+l l.
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+transient_for	NULL
+.sp 6p
+_
+.TE
+.KE
+.LP
+The realize and set_values procedures of
+TransientShell
+store the
+.PN \s-1WM_TRANSIENT_FOR\s+1
+property on the shell window if \fItransient\fP is
+.PN True .
+If \fItransient_for\fP is non-NULL and the widget specified by
+\fItransient_for\fP is realized, then its window is used as the value of the
+.PN \s-1WM_TRANSIENT_FOR\s+1
+property; otherwise, the value of \fIwindow_group\fP is used.
+.LP
+.PN TopLevel
+shells have the the following additional resources:
+.TS
+l l.
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+icon_name	Shell widget's name
+iconic	T{
+.PN False
+T}
+icon_name_encoding	See text
+.sp 6p
+_
+.TE
+.LP
+The \fIicon_name\fP
+and \fIicon_name_encoding\fP fields are stored in the
+.PN \s-1WM_ICON_NAME\s+1
+property on the shell's window by the TopLevelShell realize
+procedure.
+If the \fIicon_name_encoding\fP field is
+.PN None ,
+the \fIicon_name\fP string is assumed to be in the encoding of the
+current locale and the encoding of the
+.PN \s-1WM_ICON_NAME\s+1
+property is set to
+.PN XStdICCTextStyle .
+If a language procedure has not been set,
+the default value of \fIicon_name_encoding\fP is
+\fB\s-1XA_STRING\s+1\fP, otherwise the default value is
+.PN None .
+The \fIiconic\fP field may be used by a client to request
+that the window manager iconify or deiconify the shell; the
+TopLevelShell
+set_values procedure will send the appropriate
+.PN \s-1WM_CHANGE_STATE\s+1
+message (as specified by the \fI\*(xC\fP)
+if this resource is changed from
+.PN False
+to
+.PN True
+and will call
+.PN XtPopup
+specifying \fIgrab_kind\fP as
+.PN XtGrabNone
+if \fIiconic\fP is changed from
+.PN True
+to
+.PN False .
+The XtNiconic resource is also an alternative way to set
+the XtNinitialState resource
+to indicate that a shell should be initially displayed as an icon; the
+TopLevelShell
+initialize procedure will set \fIinitial_state\fP to
+.PN IconicState
+if \fIiconic\fP is
+.PN True .
+.LP
+Application
+shells have the following additional resources:
+.br
+.ne 4
+.TS
+l l.
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+argc	0
+argv	NULL
+.sp 6p
+_
+.TE
+.LP
+The \fIargc\fP and \fIargv\fP fields are used to initialize
+the standard property
+.PN \s-1WM_COMMAND\s+1 .
+See the \fI\*(xC\fP for more information.
+.LP
+The default values for the SessionShell instance fields,
+which are filled in from the resource lists and by the
+initialize procedure, are
+.TS
+l l.
+_
+.sp 6p
+Field	Default Value
+.sp 6p
+_
+.sp 6p
+cancel_callbacks	NULL
+clone_command	See text
+connection	NULL
+current_dir	NULL
+die_callbacks	NULL
+discard_command	NULL
+environment	NULL
+error_callbacks	NULL
+interact_callbacks	NULL
+join_session	T{
+.PN True
+T}
+program_path	See text
+resign_command	NULL
+restart_command	See text
+restart_style	T{
+.PN SmRestartIfRunning
+T}
+save_callbacks	NULL
+save_complete_callbacks	NULL
+session_id	NULL
+shutdown_command	NULL
+.sp 6p
+_
+.TE
+.LP
+The \fIconnection\fP field contains the session connection object or NULL
+if a session connection is not being managed by this widget.
+.LP
+The \fIsession_id\fP is an identification assigned to the session
+participant by the session manager.
+The \fIsession_id\fP will be passed to the session
+manager as the client identifier of the previous session.
+When a connection is established with the session manager, 
+the client id assigned by the session manager is stored
+in the \fIsession_id\fP field.
+When not NULL, the \fIsession_id\fP of the Session shell widget that
+is at the root of the widget tree of the client leader widget will be
+used to create the
+.PN \s-1SM_CLIENT_ID\s+1
+property on the client leader's window.
+.LP
+If \fIjoin_session\fP is
+.PN False ,
+the widget will not attempt to establish a
+connection to the session manager at shell creation time.
+See Sections 4.2.1 and 4.2.4
+for more information on the functionality of this resource.
+.LP
+The \fIrestart_command\fP, \fIclone_command\fP, \fIdiscard_command\fP,
+\fIresign_command\fP, \fIshutdown_command\fP, \fIenvironment\fP,
+\fIcurrent_dir\fP, \fIprogram_path\fP, and
+\fIrestart_style\fP fields contain standard session properties.
+.LP
+When a session connection is established or newly managed by the shell,
+the shell initialize and set_values methods check the values of the
+\fIrestart_command\fP, \fIclone_command\fP, and \fIprogram_path\fP
+resources.  At that time, if \fIrestart_command\fP is NULL, the value
+of the \fIargv\fP resource will be copied to \fIrestart_command\fP.  
+Whether or not \fIrestart_command\fP was NULL,
+if \*Q\fR-xtsessionID\fP\*U \*Q\fR<session id>\*U does not
+already appear in the \fIrestart_command\fP, it will be added by the
+initialize and set_values methods at the beginning of the command arguments;
+if the \*Q\fR-xtsessionID\fP\*U argument already appears with an incorrect
+\fRsession id\fP in the following argument, that argument
+will be replaced with the current \fRsession id\fP.
+.LP
+After this, the shell initialize and set_values procedures check the
+\fIclone_command\fP.  If \fIclone_command\fP is NULL, 
+\fIrestart_command\fP will be copied to \fIclone_command\fP,
+except the \*Q\fR-xtsessionID\fP\*U and following argument will not be copied.
+.LP
+Finally, the shell initialize and set_values procedures check the
+\fIprogram_path\fP.  If \fIprogram_path\fP is NULL, the 
+first element of \fIrestart_command\fP is copied to \fIprogram_path\fP.
+.LP
+The possible values of \fIrestart_style\fP are
+.PN SmRestartIfRunning ,
+.PN SmRestartAnyway ,
+.PN SmRestartImmediately ,
+and
+.PN SmRestartNever .
+A resource converter is registered for this resource; 
+for the strings that it recognizes,
+see Section 9.6.1.
+.LP
+The resource type EnvironmentArray is a NULL-terminated array of
+pointers to strings;
+each string has the format "name=value".
+The `=' character may not appear in the name,
+and the string is terminated by a null character.
+
+.NH 2
+Session Participation
+.XS
+\fB\*(SN Session Participation\fP
+.XE
+.LP
+Applications can participate in a user's session, exchanging messages
+with the session manager as described in the \fIX Session Management
+Protocol\fP and the \fIX Session Management Library\fP.
+.LP
+When a widget of
+.PN sessionShellWidgetClass
+or a subclass is created, the widget provides support for the application
+as a session participant and continues to provide support until the
+widget is destroyed.
+
+.NH 3
+Joining a Session
+.XS
+\fB\*(SN Joining a Session\fP
+.XE
+.LP
+When a Session shell is created, 
+if \fIconnection\fP is NULL,
+and if \fIjoin_session\fP is
+.PN True ,
+and if \fIargv\fP or \fIrestart_command\fP is not NULL,
+and if in POSIX environments the 
+.PN \s-1SESSION_MANAGER\s+1
+environment variable is defined,
+the shell will attempt to establish a new connection with the session manager.
+.LP
+To transfer management of an existing session connection from an
+application to the shell at widget creation time, pass the existing
+session connection ID as the \fIconnection\fP resource value
+when creating the Session shell,
+and if the other creation-time conditions on session participation are met,
+the widget will maintain the connection with the session manager.
+The application must ensure that only one
+Session shell manages the connection.
+.LP
+In the Session shell set_values procedure,
+if \fIjoin_session\fP changes from 
+.PN False 
+to 
+.PN True
+and \fIconnection\fP is NULL and when in POSIX environments the
+.PN \s-1SESSION_MANAGER\s+1
+environment variable is defined, 
+the shell will attempt to open a connection to the session manager.
+If \fIconnection\fP changes from NULL to non-NULL, the
+Session shell
+will take over management of that session connection and will set
+\fIjoin_session\fP to
+.PN True .
+If \fIjoin_session\fP changes from
+.PN False
+to
+.PN True
+and \fIconnection\fP is not NULL, the
+Session shell will take over management of the session connection.
+.LP
+When a successful connection has been established, \fIconnection\fP
+contains the session connection ID for the session participant.
+When the shell begins to manage the connection, it will call
+.PN XtAppAddInput
+to register the handler which watches for protocol messages
+from the session manager.
+When the attempt to connect fails, a warning message is issued
+and \fIconnection\fP is set to NULL.
+.LP
+While the connection is being managed, if a 
+.PN SaveYourself ,
+.PN SaveYourselfPhase2 ,
+.PN Interact ,
+.PN ShutdownCancelled ,
+.PN SaveComplete ,
+or
+.PN Die
+message is received from the session manager, the Session shell will
+call out to application callback procedures registered
+on the respective callback list of the Session shell and will
+send 
+.PN SaveYourselfPhase2Request ,
+.PN InteractRequest ,
+.PN InteractDone ,
+.PN SaveYourselfDone ,
+and
+.PN ConnectionClosed
+messages as appropriate.
+Initially, all of the client's session properties are undefined.
+When any of the session property resource values are defined or change,
+the Session shell initialize and set_values procedures
+will update the client's session property value by a 
+.PN SetProperties
+or a
+.PN DeleteProperties
+message, as appropriate.
+The session ProcessID and UserID properties are always set by the shell
+when it is possible to determine the value of these properties.
+
+.NH 3
+Saving Application State
+.XS
+\fB\*(SN Saving Application State\fP
+.XE
+.LP
+The session manager instigates an application checkpoint by sending a
+.PN SaveYourself
+request.  
+Applications are responsible for saving their state in response to the
+request.
+.LP
+When the
+.PN SaveYourself
+request arrives, the procedures registered on the
+Session shell's save callback list are called.
+If the application does not register any save callback procedures on
+the save callback list, the shell will report to the session manager
+that the application failed to save its state.
+Each procedure on the save callback list receives a token
+in the \fIcall_data\fP parameter.
+.sp
+.LP
+.KS
+The checkpoint token in the \fIcall_data\fP parameter is of type
+.PN XtCheckpointToken .
+.LP
+.IN "XtCheckpointToken" "" "@DEF@"
+.IN "XtCheckpointTokenRec" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2i 4i
+.ta .5i 2i 4i
+typedef struct {
+	int	save_type;
+	int	interact_style;
+	Boolean	shutdown;
+	Boolean	fast;
+	Boolean	cancel_shutdown
+	int	phase;
+	int	interact_dialog_type;	/* return */
+	Boolean	request_cancel;	/* return */
+	Boolean	request_next_phase;	/* return */
+	Boolean	save_success;	/* return */
+} XtCheckpointTokenRec, *XtCheckpointToken;
+.De
+.LP
+.eM
+.KE
+The \fIsave_type\fP, \fIinteract_style\fP, \fIshutdown\fP, and \fIfast\fP
+fields of the token contain the parameters of the
+.PN SaveYourself
+message.
+The possible values of \fIsave_type\fP are
+.PN SmSaveLocal ,
+.PN SmSaveGlobal ,
+and 
+.PN SmSaveBoth ;
+these indicate the type of information to be saved.
+The possible values of \fIinteract_style\fP are
+.PN SmInteractStyleNone ,
+.PN SmInteractStyleErrors ,
+and
+.PN SmInteractStyleAny ;
+these indicate whether user interaction would be permitted
+and, if so, what kind of interaction.
+If \fIshutdown\fP is
+.PN True ,
+the checkpoint is being performed in preparation for the end of the session.
+If \fIfast\fP is
+.PN True ,
+the client should perform the checkpoint as quickly as possible.
+If \fIcancel_shutdown\fP is 
+.PN True ,
+a 
+.PN ShutdownCancelled
+message has been received for the current save operation.  (See Section 4.4.4.)
+The \fIphase\fP is used by manager clients, such as a window manager,
+to distinguish between the first and second phase of a save operation.
+The \fIphase\fP will be either 1 or 2.
+The remaining fields in the checkpoint token structure are provided for
+the application to communicate with the shell.
+.LP
+Upon entry to the first application save callback procedure, the return
+fields in the token have the following initial values:
+\fIinteract_dialog_type\fP is 
+.PN SmDialogNormal ;
+\fIrequest_cancel\fP is
+.PN False ;
+\fIrequest_next_phase\fP is
+.PN False ;
+and \fIsave_success\fP is
+.PN True .
+When a token is returned with any of the four return fields containing
+a noninitial value, and when the field is applicable, subsequent tokens
+passed to the application during the current save operation
+will always contain the noninitial value.
+.LP
+The purpose of the token's \fIsave_success\fP field is to 
+indicate the outcome of the entire operation to the
+session manager and ultimately, to the user.
+Returning 
+.PN False
+indicates some portion of the application state 
+could not be successfully saved.  If any token is returned
+to the shell with \fIsave_success\fP 
+.PN False ,
+tokens subsequently received
+by the application for the current save operation will show 
+\fIsave_success\fP as 
+.PN False .
+When the shell sends the final status of the checkpoint to the
+session manager, it will indicate failure to save application state
+if any token was returned with \fIsave_success\fP 
+.PN False .
+.LP
+Session participants that manage and save the state of other clients
+should structure their save or interact callbacks to
+set \fIrequest_next_phase\fP to 
+.PN True
+when phase is 1, which will cause the shell to send the 
+.PN SaveYourselfPhase2Request
+when the first phase is complete.  When the 
+.PN SaveYourselfPhase2 
+message is received, the shell will invoke the save callbacks a
+second time with \fIphase\fP equal to 2.
+Manager clients should save the state of other clients
+when the callbacks are invoked the second time and \fIphase\fP equal to 2.
+.LP
+The application may request additional tokens while a checkpoint is under way,
+and these additional tokens must be returned by an explicit call.
+.sp
+.LP
+.KS
+To request an additional token for a save callback response that has a
+deferred outcome, use
+.PN XtSessionGetToken .
+.LP
+.IN "XtSessionGetToken" "" "@DEF@"
+.sM
+.FD 0
+XtCheckpointToken XtSessionGetToken(\fIwidget\fP)
+.br
+      Widget \fIwidget\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the Session shell widget which manages session participation.
+.LP
+.eM
+The 
+.PN XtSessionGetToken
+function will return NULL if no checkpoint operation is currently under way.
+.KE
+.sp
+.LP
+.KS
+To indicate the completion of checkpoint processing including user 
+interaction, the application must signal the Session shell
+by returning all tokens.
+(See Sections 4.2.2.2 and 4.2.2.4).
+To return a token, use
+.PN  XtSessionReturnToken .
+.LP
+.IN "XtSessionReturnToken" "" "@DEF@"
+.sM
+.FD 0
+void XtSessionReturnToken(\fItoken\fP)
+.br
+      XtCheckpointToken \fItoken\fP;
+.FN
+.IP \fItoken\fP 1i
+Specifies a token that was received as the \fIcall_data\fP by a procedure
+on the interact callback list or a token that was received by a call to
+.PN XtSessionGetToken .
+.LP
+.eM
+.KE
+.LP
+Tokens passed as \fIcall_data\fP to save callbacks are implicitly
+returned when the save callback procedure returns.
+A save callback procedure should not call 
+.PN XtSessionReturnToken 
+on the token passed in its \fIcall_data\fP.
+
+.NH 4
+Requesting Interaction
+.XS
+\fB\*(SN Requesting Interaction\fP
+.XE
+.LP
+When the token \fIinteract_style\fP allows user interaction,
+the application may
+interact with the user during the checkpoint, but must wait for permission
+to interact.
+Applications request permission to interact with the user during the
+checkpointing operation by registering a procedure on the Session
+shell's interact callback list.  When all save callback procedures have
+returned, and each time a token that was granted by a call to 
+.PN XtSessionGetToken
+is returned, the Session shell examines the interact callback list.
+If interaction is permitted and the interact callback list is not empty,
+the shell will send an
+.PN InteractRequest
+to the session manager when an interact request is not already outstanding
+for the application.
+.LP
+The type of interaction dialog that will be requested is specified by
+the \fIinteract_dialog_type\fP field in the checkpoint token.
+The possible values for \fIinteract_dialog_type\fP are
+.PN SmDialogError
+and
+.PN SmDialogNormal .
+If a token is returned with \fIinteract_dialog_type\fP containing
+.PN SmDialogError ,
+the interact request and any subsequent interact requests will be for
+an error dialog; otherwise, the request will be for a normal dialog with
+the user.  
+.LP
+When a token is returned with \fIsave_success\fP
+.PN False
+or \fIinteract_dialog_type\fP
+.PN SmDialogError ,
+tokens subsequently passed to callbacks during the same active
+.PN SaveYourself
+response will reflect these changed values, indicating that
+an error condition has occurred during the checkpoint.
+.LP
+The \fIrequest_cancel\fP field is a return value for interact callbacks only.
+Upon return from a procedure on the save callback list, the value
+of the token's \fIrequest_cancel\fP field is not examined by the shell.
+This is also true of tokens received through a call to 
+.PN XtSessionGetToken .
+
+.NH 4
+Interacting with the User during a Checkpoint
+.XS
+\fB\*(SN Interacting with the User during a Checkpoint\fP
+.XE
+.LP
+When the session manager grants the application's request for user interaction,
+the Session shell receives an
+.PN Interact
+message.
+The procedures registered on the interact callback list are executed,
+but not as if executing a typical callback list.
+These procedures are individually executed in
+sequence, with a checkpoint token functioning as the sequencing mechanism.
+Each step in the sequence begins by removing a procedure
+from the interact callback list
+and executing it with a token passed in the \fIcall_data\fP.
+The interact callback will typically pop up a dialog box and return.
+When the user interaction and associated application checkpointing has
+completed, the application must return the token by calling
+.PN XtSessionReturnToken .
+Returning the token completes the current step and triggers the next step
+in the sequence.
+.LP
+During interaction the client may request cancellation of a shutdown.
+When a token passed as \fIcall_data\fP to an interact procedure is returned,
+if \fIshutdown\fP is 
+.PN True
+and \fIcancel_shutdown\fP is
+.PN False ,
+\fIrequest_cancel\fP indicates whether the 
+application requests that the pending shutdown be cancelled.
+If \fIrequest_cancel\fP is
+.PN True ,
+the field will also be
+.PN True
+in any tokens subsequently granted during the checkpoint operation.
+When a token is returned requesting cancellation of
+the session shutdown, pending interact procedures will still be
+called by the Session shell.
+When all interact procedures have been removed from the interact callback
+list, executed, and the final interact token returned to the shell, an
+.PN InteractDone
+message is sent to the session manager, indicating whether
+a pending session shutdown is requested to be cancelled.
+
+.NH 4
+Responding to a Shutdown Cancellation
+.XS
+\fB\*(SN Responding to a Shutdown Cancellation\fP
+.XE
+.LP
+Callbacks registered on the cancel callback list are invoked when the
+Session shell processes a
+.PN ShutdownCancelled
+message from the session manager.  This may occur during the
+processing of save callbacks, while waiting for interact permission,
+during user interaction, or after the save operation is complete and
+the application is expecting a
+.PN SaveComplete
+or a
+.PN Die
+message.
+The \fIcall_data\fP for these callbacks is NULL.
+.LP
+When the shell notices that a pending shutdown has been cancelled,
+the token \fIcancel_shutdown\fP field will be 
+.PN True
+in tokens subsequently given to the application.
+.LP
+Receiving notice of a shutdown cancellation does not cancel the 
+pending execution of save callbacks or interact callbacks.
+After the cancel callbacks execute, if \fIinteract_style\fP is not
+.PN SmInteractStyleNone
+and the interact list is not empty,
+the procedures on the interact callback list will be executed
+and passed a token with \fIinteract_style\fP 
+.PN SmInteractStyleNone .
+The application should not interact with the user, and the Session shell
+will not send an 
+.PN InteractDone
+message.
+
+.NH 4
+Completing a Save
+.XS
+\fB\*(SN Completing a Save\fP
+.XE
+.LP
+When there is no user interaction, the shell regards the application
+as having finished saving state when all callback procedures
+on the save callback list have returned, and any additional tokens
+passed out by
+.PN XtSessionGetToken
+have been returned by corresponding calls to
+.PN XtSessionReturnToken .
+If the save operation involved user interaction,
+the above completion conditions apply, and in addition, all requests for
+interaction have been granted or cancelled,
+and all tokens passed to interact callbacks have been returned
+through calls to
+.PN XtSessionReturnToken .
+If the save operation involved a manager client that requested the
+second phase, the above conditions apply to both the first and second
+phase of the save operation.
+.br
+.LP
+When the application has finished saving state,
+the Session shell will report the result to the session manager by
+sending the
+.PN SaveYourselfDone
+message.
+If the session is continuing, the shell will receive the
+.PN SaveComplete
+message when all applications have completed saving state.
+This message indicates that applications may again allow changes
+to their state.  The shell will execute the save_complete callbacks.
+The \fIcall_data\fP for these callbacks is NULL.
+
+.NH 3
+Responding to a Shutdown
+.XS
+\fB\*(SN Responding to a Shutdown\fP
+.XE
+.LP
+Callbacks registered on the die callback list are invoked when the
+session manager sends a
+.PN Die
+message.
+The callbacks on this list should do whatever is appropriate to quit
+the application.
+Before executing procedures on the die callback list,
+the Session shell will close the connection to the session manager
+and will remove the handler that watches for protocol messages.
+The \fIcall_data\fP for these callbacks is NULL.
+
+.NH 3
+Resigning from a Session
+.XS
+\fB\*(SN Resigning from a Session\fP
+.XE
+.LP
+When the Session shell widget is destroyed, the destroy method will
+close the connection to the session manager by sending a
+.PN ConnectionClosed 
+protocol message and will remove the input callback
+that was watching for session protocol messages.
+.LP
+When
+.PN XtSetValues
+is used to set \fIjoin_session\fP to
+.PN False ,
+the set_values method of the Session shell will close the
+connection to the session manager if one exists by sending a
+.PN ConnectionClosed 
+message, and \fIconnection\fP will be set to NULL.
+.LP
+Applications that exit in response to user actions and that do not
+wait for phase 2 destroy to complete on
+the Session shell should set \fIjoin_session\fP to
+.PN False
+before exiting.
+.LP
+When
+.PN XtSetValues 
+is used to set \fIconnection\fP to NULL,
+the Session shell will stop managing the connection, if one exists.
+However, that session connection will not be closed.
+.LP
+Applications that wish to ensure continuation of a session connection
+beyond the destruction of the shell should first retrieve the 
+\fIconnection\fP resource value,
+then set the \fIconnection\fP resource to NULL, 
+and then they may safely destroy the widget without losing control
+of the session connection.
+.LP
+The error callback list will be called if an unrecoverable
+communications error occurs while the shell is managing the connection.
+The shell will close the connection, set \fIconnection\fP to NULL,
+remove the input callback, and 
+call the procedures registered on the error callback list.
+The \fIcall_data\fP for these callbacks is NULL.
+.bp
diff --git a/libXt/specs/CH05 b/libXt/specs/CH05
new file mode 100644
index 000000000..4f15beab0
--- /dev/null
+++ b/libXt/specs/CH05
@@ -0,0 +1,783 @@
+.\" $Xorg: CH05,v 1.3 2000/08/17 19:42:44 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 5\fP\s-1
+
+\s+1\fBPop-Up Widgets\fP\s-1
+.sp 2
+.nr H1 5
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 5 \(em Pop-Up Widgets
+.XE
+Pop-up widgets are used to create windows outside of the
+window hierarchy defined by the widget tree.
+Each pop-up child has a window that is a descendant of the root window,
+so that the pop-up window is not clipped by the pop-up widget's parent window.
+.\"One thing that all pop-ups in common is that they break 
+.\"the widget/window hierarchy.
+.\"Pop-ups windows are not geometry constrained by their parent widget.
+.\"Instead, they are window children of the root.
+Therefore, pop-ups are created and attached differently to their widget parent 
+than normal widget children.
+.LP
+A parent of a pop-up widget does not actively manage its pop-up children;
+in fact, it usually does not operate upon them in any way.
+The \fIpopup_list\fP field in the
+.PN CorePart
+structure contains the list of its pop-up children.
+This pop-up list exists mainly to provide the proper place in the widget
+hierarchy for the pop-up to get resources and to provide a place for
+.PN XtDestroyWidget
+to look for all extant children.
+.LP
+A 
+composite 
+widget can have both normal and pop-up children.
+A pop-up can be popped up from almost anywhere, not just by its parent.
+The term \fIchild\fP always refers to a normal, geometry-managed widget
+on the composite widget's list of children, and the term
+\fIpop-up child\fP always refers to a
+widget on the pop-up list.
+.IN "pop-up" "" "@DEF@"
+.IN "pop-up" "list"
+.IN "pop-up" "child"
+
+.NH 2
+Pop-Up Widget Types
+.LP
+.XS
+\fB\*(SN Pop-Up Widget Types\fP
+.XE
+There are three kinds of pop-up widgets:
+.IP \(bu 5
+Modeless pop-ups
+.IP
+A modeless pop-up (for example, a dialog box that does not prevent
+continued interaction with the rest of the application)
+can usually be manipulated by the window manager
+and looks like any other application window from the
+user's point of view.
+The application main window itself is a special case of a modeless pop-up.
+.IP \(bu 5
+Modal pop-ups
+.IP
+A modal pop-up (for example, a dialog box that requires user input to
+continue)
+can sometimes be manipulated by the window manager,
+and except for events that occur in the dialog box,
+it disables user-event distribution to the rest of the application.
+.IP \(bu 5
+Spring-loaded pop-ups
+.IP
+A spring-loaded pop-up (for example, a menu)
+can seldom be manipulated by the window manager,
+and except for events that occur in the pop-up or its descendants,
+it disables user-event distribution to all other applications.
+.LP
+Modal pop-ups and spring-loaded pop-ups are very similar and should be coded as
+if they were the same.
+In fact, the same widget (for example, a ButtonBox or Menu widget) can be used both
+as a modal pop-up and as a spring-loaded pop-up within the same application.
+The main difference is that spring-loaded pop-ups are brought up
+with the pointer and, because of the grab that the pointer button causes,
+require different processing by the \*(xI.
+Furthermore, all user input remap events occurring outside the spring-loaded
+pop-up (e.g., in a descendant) are also delivered to the spring-loaded
+pop-up after they have been dispatched to the appropriate descendant, so
+that, for example, button-up can take down a spring-loaded pop-up no
+matter where the
+button-up occurs.
+.LP
+Any kind of pop-up, in turn, can pop up other widgets.
+Modal and spring-loaded pop-ups can constrain user events to
+the most recent such pop-up or allow user events to be dispatched
+to any of the modal or spring-loaded pop-ups
+currently mapped.
+.LP
+Regardless of their type,
+all pop-up widget classes are responsible for communicating with the
+X window manager and therefore are subclasses of
+one of the
+Shell
+widget classes.
+
+.NH 2
+Creating a Pop-Up Shell
+.XS
+\fB\*(SN Creating a Pop-Up Shell\fP
+.XE
+.LP
+.IN "pop-up" "shell"
+.IN "pop-up" "child"
+For a widget to be popped up,
+it must be the child of a pop-up shell widget.
+None of the \*(xI-supplied shells will
+simultaneously manage more than one child.
+Both the shell and child taken together are referred to as the pop-up.
+When you need to use a pop-up,
+you always refer to the pop-up by the pop-up shell,
+not the child.
+.sp
+.LP
+To create a pop-up shell, use
+.PN XtCreatePopupShell .
+.LP
+.IN "XtCreatePopupShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtCreatePopupShell(\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 shell widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created shell widget.
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(cI
+.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 XtCreatePopupShell
+function ensures that the specified class is a subclass of
+Shell
+and, rather than using insert_child to attach the widget to the parent's
+.IN "insert_child procedure"
+\fIchildren\fP list,
+attaches the shell to the parent's \fIpopup_list\fP directly.
+.LP
+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 parent's screen
+is queried for the resource \fIname\fP.screen, class
+\fIClass\fP.Screen where \fIClass\fP is the \fIclass_name\fP
+field from the
+.PN CoreClassPart
+of the specified \fIwidget_class\fP.
+If this query fails, the parent's screen is used.
+Once the screen is determined,
+the resource database associated with that screen is used to retrieve
+all remaining resources for the widget not specified in
+\fIargs\fP.
+
+.LP
+A spring-loaded pop-up invoked from a translation table via
+.PN XtMenuPopup
+must already exist
+at the time that the translation is invoked, 
+so the translation manager can find the shell by name.
+Pop-ups invoked in other ways can be created when
+the pop-up actually is needed.
+This delayed creation of the shell is particularly useful when you pop up
+an unspecified number of pop-ups.
+You can look to see if an appropriate unused shell (that is, not
+currently popped up) exists and create a new shell if needed.
+.sp
+.LP
+To create a pop-up shell using varargs lists, use
+.PN XtVaCreatePopupShell .
+.LP
+.IN "XtVaCreatePopupShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Widget \fIparent\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the instance name for the created shell widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created shell widget.
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(cI
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+.PN XtVaCreatePopupShell
+is identical in function to
+.PN XtCreatePopupShell
+with \fIthe\fP args and \fInum_args\fP parameters replaced by a varargs list as
+described in Section 2.5.1.
+
+.NH 2
+Creating Pop-Up Children
+.XS
+\fB\*(SN Creating Pop-Up Children\fP
+.XE
+.LP
+Once a pop-up shell is created,
+the single child of the pop-up shell can be created
+either statically or dynamically.
+.LP
+At startup,
+an application can create the child of the pop-up shell,
+which is appropriate for pop-up children composed of a fixed set
+of widgets. 
+The application can change the state of the subparts of
+the pop-up child as the application state changes.
+For example, if an application creates a static menu,
+it can call
+.PN XtSetSensitive
+(or, in general,
+.PN XtSetValues )
+on any of the buttons that make up the menu.
+Creating the pop-up child early means that pop-up time is minimized,
+especially if the application calls
+.PN XtRealizeWidget
+on the pop-up shell at startup.
+When the menu is needed,
+all the widgets that make up the menu already exist and need only be mapped.
+The menu should pop up as quickly as the X server can respond.
+.LP
+Alternatively,
+an application can postpone the creation of the child until it is needed,
+which minimizes application startup time and allows the pop-up child to
+reconfigure itself each time it is popped up.
+In this case,
+the pop-up child creation routine might poll the application
+to find out if it should change the sensitivity of any of its subparts.
+.LP
+Pop-up child creation does not map the pop-up,
+even if you create the child and call
+.PN XtRealizeWidget
+on the pop-up shell.
+.LP
+All shells have pop-up and pop-down callbacks,
+which provide the opportunity either to make last-minute changes to a
+pop-up child before it is popped up or to change it after it is popped down.
+Note that excessive use of pop-up callbacks can make
+popping up occur more slowly.
+
+.NH 2
+Mapping a Pop-Up Widget
+.XS
+\fB\*(SN Mapping a Pop-Up Widget\fP
+.XE
+.LP
+Pop-ups can be popped up through several mechanisms:
+.IP \(bu 5
+A call to
+.PN XtPopup
+or
+.PN XtPopupSpringLoaded .
+.IP \(bu 5
+One of the supplied callback procedures
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+or
+.PN XtCallbackExclusive .
+.IP \(bu 5
+The standard translation action
+.PN XtMenuPopup .
+.LP
+Some of these routines take an argument of type
+.PN XtGrabKind ,
+which is defined as
+.sp
+.sM
+.Ds 0
+typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind;
+.De
+.sp
+.eM
+.LP
+The create_popup_child_proc procedure pointer
+in the shell widget instance record is of type
+.PN XtCreatePopupChildProc .
+.LP
+.IN "create_popup_child_proc"
+.IN "Shell" "create_popup_child_proc"
+.IN "XtCreatePopupChildProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtCreatePopupChildProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the shell widget being popped up.
+.LP
+.eM
+To map a pop-up from within an application, use
+.PN XtPopup .
+.LP
+.IN "XtPopup" "" "@DEF@"
+.sM
+.FD 0
+void XtPopup(\fIpopup_shell\fP, \fIgrab_kind\fP)
+.br
+      Widget \fIpopup_shell\fP;
+.br
+      XtGrabKind \fIgrab_kind\fP;
+.FN
+.IP \fIpopup_shell\fP 1i
+Specifies the shell widget.
+.IP \fIgrab_kind\fP 1i
+Specifies the way in which user events should be constrained.
+.LP
+.eM
+The
+.PN XtPopup
+function performs the following:
+.IP \(bu 5
+Calls
+.PN XtCheckSubclass
+to ensure \fIpopup_shell\fP's class is a subclass of
+.PN shellWidgetClass .
+.IP \(bu 5
+Raises the window and returns if the shell's \fIpopped_up\fP field is already 
+.PN True .
+.IP \(bu 5
+Calls the callback procedures on the shell's \fIpopup_callback\fP list,
+specifying a pointer to the value of \fIgrab_kind\fP as the \fIcall_data\fP
+argument.
+.IP \(bu 5
+Sets the shell \fIpopped_up\fP field to 
+.PN True ,
+the shell \fIspring_loaded\fP field to 
+.PN False ,
+and the shell \fIgrab_kind\fP field from \fIgrab_kind\fP.
+.IP \(bu 5
+If the shell's \fIcreate_popup_child_proc\fP field is non-NULL,
+.PN XtPopup
+calls it with \fIpopup_shell\fP as the parameter.
+.IP \(bu 5
+If \fIgrab_kind\fP is either
+.PN XtGrabNonexclusive
+or
+.PN XtGrabExclusive ,
+it calls
+.LP
+.Ds
+XtAddGrab(\fIpopup_shell\fP, (\fIgrab_kind\fP == XtGrabExclusive), False)
+.De
+.IP \(bu 5
+Calls
+.PN XtRealizeWidget 
+with \fIpopup_shell\fP specified.
+.IP \(bu 5
+Calls
+.PN XMapRaised
+with the window of \fIpopup_shell\fP.
+.sp
+.LP
+To map a spring-loaded pop-up from within an application, use
+.PN XtPopupSpringLoaded .
+.LP
+.IN "XtPopupSpringLoaded" "" @DEF@"
+.sM
+.FD 0
+void XtPopupSpringLoaded(\fIpopup_shell\fP)
+.br
+      Widget \fIpopup_shell\fP;
+.FN
+.IP \fIpopup_shell\fP 1i
+Specifies the shell widget to be popped up.
+.LP
+.eM
+The
+.PN XtPopupSpringLoaded
+function performs exactly as
+.PN XtPopup
+except that it sets the shell \fIspring_loaded\fP field to
+.PN True
+and always calls
+.PN XtAddGrab
+with \fIexclusive\fP
+.PN True
+and \fIspring-loaded\fP
+.PN True .
+.sp
+.LP
+To map a pop-up from a given widget's callback list,
+you also can register one of the
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+or
+.PN XtCallbackExclusive
+convenience routines as callbacks, using the pop-up shell widget as the
+client data.
+.LP
+.IN "XtCallbackNone" "" "@DEF@"
+.sM
+.FD 0
+void XtCallbackNone(\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 the widget.
+.IP \fIclient_data\fP 1i
+Specifies the pop-up shell.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.sp
+.LP
+.IN "XtCallbackNonexclusive" "" "@DEF@"
+.FD 0
+void XtCallbackNonexclusive(\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 the widget.
+.IP \fIclient_data\fP 1i
+Specifies the pop-up shell.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.sp
+.LP
+.IN "XtCallbackExclusive" "" "@DEF@"
+.FD 0
+void XtCallbackExclusive(\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 the widget.
+.IP \fIclient_data\fP 1i
+Specifies the pop-up shell.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.LP
+.eM
+The
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+and
+.PN XtCallbackExclusive
+functions call
+.PN XtPopup
+with the shell specified by the \fIclient_data\fP argument
+and \fIgrab_kind\fP set as the name specifies.
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+and
+.PN XtCallbackExclusive
+specify
+.PN XtGrabNone ,
+.PN XtGrabNonexclusive ,
+and
+.PN XtGrabExclusive ,
+respectively.
+Each function then sets the widget that executed the callback list 
+to be insensitive by calling
+.PN XtSetSensitive .
+Using these functions in callbacks is not required.
+In particular,
+an application must provide customized code for
+callbacks that create pop-up shells dynamically or that must do more than
+desensitizing the button.
+.sp
+.LP
+Within a translation table,
+to pop up a menu when a key or pointer button is pressed or when the pointer
+is moved into a widget, use
+.PN XtMenuPopup ,
+or its synonym,
+.PN MenuPopup .
+From a translation writer's point of view,
+the definition for this translation action is
+.LP
+.IN "MenuPopup" "" "@DEF@"
+.IN "XtMenuPopup" "" "@DEF@"
+.sM
+.FD 0
+void XtMenuPopup(\fIshell_name\fP)
+.br
+      String \fIshell_name\fP;
+.FN
+.IP \fIshell_name\fP 1i
+Specifies the name of the shell widget to pop up.
+.LP
+.eM
+.PN XtMenuPopup
+is known to the translation manager,
+which registers the corresponding built-in action procedure
+.PN XtMenuPopupAction
+using
+.PN XtRegisterGrabAction
+specifying \fIowner_events\fP
+.PN True ,
+\fIevent_mask\fP
+.PN ButtonPressMask
+\fB|\fP
+.PN ButtonReleaseMask ,
+and \fIpointer_mode\fP and \fIkeyboard_mode\fP
+.PN GrabModeAsync .
+.LP
+If
+.PN XtMenuPopup
+is invoked on
+.PN ButtonPress ,
+it calls
+.PN XtPopupSpringLoaded
+on the specified shell widget.
+If
+.PN XtMenuPopup
+is invoked on
+.PN KeyPress
+or
+.PN EnterWindow ,
+it calls
+.PN XtPopup
+on the specified shell widget with \fIgrab_kind\fP set to
+.PN XtGrabNonexclusive .
+Otherwise, the translation manager generates a
+warning message and ignores the action.
+.LP
+.PN XtMenuPopup
+tries to find the shell by searching the widget tree starting at
+the widget in which it is invoked.
+If it finds a shell with the specified name in the pop-up children of
+that widget, it pops up the shell with the appropriate parameters.
+Otherwise, it moves up the parent chain to find a pop-up child with the
+specified name.
+If
+.PN XtMenuPopup
+gets to the application top-level shell widget and has not
+found a matching shell, it generates a warning and returns immediately.
+
+.NH 2
+Unmapping a Pop-Up Widget
+.XS
+\fB\*(SN Unmapping a Pop-Up Widget\fP
+.XE
+.LP
+Pop-ups can be popped down through several mechanisms:
+.IP \(bu 5
+A call to
+.PN XtPopdown 
+.IP \(bu 5
+The supplied callback procedure
+.PN XtCallbackPopdown 
+.IP \(bu 5
+The standard translation action
+.PN XtMenuPopdown 
+.sp
+.LP
+To unmap a pop-up from within an application, use
+.PN XtPopdown .
+.LP
+.IN "XtPopdown" "" "@DEF@"
+.sM
+.FD 0
+void XtPopdown(\fIpopup_shell\fP)
+.br
+      Widget \fIpopup_shell\fP;
+.FN
+.IP \fIpopup_shell\fP 1i
+Specifies the shell widget to pop down.
+.LP
+.eM
+The
+.PN XtPopdown
+function performs the following:
+.IP \(bu 5
+Calls
+.PN XtCheckSubclass
+.\".PN XtCheckSubclass(popup_shell, popupShellWidgetClass)
+to ensure \fIpopup_shell\fP's class is a subclass of
+.PN shellWidgetClass .
+.IP \(bu 5
+Checks that the \fIpopped_up\fP field of \fIpopup_shell\fP is
+.PN True ;
+otherwise, it returns immediately.
+.IP \(bu 5
+Unmaps \fIpopup_shell\fP's window and, if \fIoverride_redirect\fP is
+.PN False ,
+sends a synthetic
+.PN UnmapNotify
+event as specified by the \fI\*(xC\fP.
+.IP \(bu 5
+If \fIpopup_shell\fP's \fIgrab_kind\fP is either
+.PN XtGrabNonexclusive
+or
+.PN XtGrabExclusive ,
+it calls
+.PN XtRemoveGrab .
+.\".PN XtRemoveGrab(popup_shell)
+.IP \(bu 5
+Sets \fIpopup_shell\fP's \fIpopped_up\fP field to 
+.PN False .
+.IP \(bu 5
+Calls the callback procedures on the shell's \fIpopdown_callback\fP list,
+specifying a pointer to the value of the shell's \fIgrab_kind\fP field
+as the \fIcall_data\fP argument.
+.sp
+.LP
+To pop down a pop-up from a callback list, you may use the callback 
+.PN XtCallbackPopdown .
+.LP
+.IN "XtCallbackPopdown" "" "@DEF@"
+.sM
+.FD 0
+void XtCallbackPopdown(\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 the widget.
+.IP \fIclient_data\fP 1i
+Specifies a pointer to the
+.PN XtPopdownID
+structure.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.LP
+.eM
+The
+.PN XtCallbackPopdown
+function casts the \fIclient_data\fP parameter to a pointer of type
+.PN XtPopdownID .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	Widget shell_widget;
+	Widget enable_widget;
+} XtPopdownIDRec, *XtPopdownID;
+.De
+.LP
+.eM
+The \fIshell_widget\fP is the pop-up shell to pop down,
+and the \fIenable_widget\fP is usually the widget that was used to pop it up
+in one of the pop-up callback convenience procedures.
+.LP
+.PN XtCallbackPopdown
+calls
+.PN XtPopdown
+with the specified \fIshell_widget\fP 
+and then calls
+.PN XtSetSensitive
+to resensitize \fIenable_widget\fP.
+.sp
+.LP
+Within a translation table,
+to pop down a spring-loaded menu when a key or pointer button is
+released or when the
+pointer is moved into a widget, use
+.PN XtMenuPopdown
+or its synonym,
+.PN MenuPopdown .
+From a translation writer's point of view,
+the definition for this translation action is
+.LP
+.IN "XtMenuPopdown" "" "@DEF@"
+.IN "MenuPopdown" "" "@DEF@"
+.sM
+.FD 0
+void XtMenuPopdown(\fIshell_name\fP)
+.br
+      String \fIshell_name\fP;
+.FN
+.IP \fIshell_name\fP 1i
+Specifies the name of the shell widget to pop down.
+.LP
+.eM
+If a shell name is not given,
+.PN XtMenuPopdown
+calls
+.PN XtPopdown
+with the widget for which the translation is specified.
+If \fIshell_name\fP is specified in the translation table,
+.PN XtMenuPopdown
+tries to find the shell by looking up the widget tree starting at the
+widget in which it is invoked.
+If it finds a shell with the specified name in the pop-up children 
+of that widget, it pops down the shell;
+otherwise, it moves up the parent chain to find a pop-up child with the
+specified name.
+If 
+.PN XtMenuPopdown 
+gets to the application top-level shell widget 
+and cannot find a matching shell, 
+it generates a warning and returns immediately.
+.bp
diff --git a/libXt/specs/CH06 b/libXt/specs/CH06
new file mode 100644
index 000000000..34c2861b0
--- /dev/null
+++ b/libXt/specs/CH06
@@ -0,0 +1,1110 @@
+.\" $Xorg: CH06,v 1.3 2000/08/17 19:42:45 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 6\fP\s-1
+
+\s+1\fBGeometry Management\fP\s-1
+.sp 2
+.nr H1 6
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 6 \(em Geometry Management 
+.XE
+.LP
+.IN "geometry_manager procedure"
+.IN "Geometry Management"
+.IN "Configure Window"
+A widget does not directly control its size and location;
+rather, its parent is responsible for controlling them.
+Although the position of children is usually left up to their parent,
+the widgets themselves often have the best idea of their optimal sizes
+and, possibly, preferred locations.
+.LP
+To resolve physical layout conflicts between sibling widgets and between
+a widget and its parent, the \*(xI provide the geometry management mechanism.
+Almost all 
+composite
+widgets have a geometry manager specified in the \fIgeometry_manager\fP field
+in the widget class record that is responsible for the size, position, and
+stacking order of the widget's children.
+The only exception is fixed boxes,
+which create their children themselves and can ensure that
+their children will never make a geometry request.
+
+.NH 2
+Initiating Geometry Changes
+.LP
+.XS
+\*(SN Initiating Geometry Changes
+.XE
+Parents, children, and clients each initiate geometry changes differently.
+Because a parent has absolute control of its children's geometry,
+it changes the geometry directly by calling
+.PN XtMove\%Widget ,
+.PN XtResizeWidget ,
+or
+.PN XtConfigureWidget .
+A child must ask its parent for a geometry change by calling
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest .
+An application or other client code initiates a geometry change by calling
+.PN XtSetValues
+on the appropriate geometry fields,
+thereby giving the widget the opportunity to modify or reject the client
+request before it gets propagated to the parent and the opportunity 
+to respond appropriately to the parent's reply.
+.LP
+When a widget that needs to change its size, position, border width, 
+or stacking depth asks its parent's geometry manager to make the desired 
+changes,
+the geometry manager can allow the request, disallow the request, or
+suggest a compromise.
+.LP
+When the geometry manager is asked to change the geometry of a child,
+the geometry manager may also rearrange and resize any or all
+of the other children that it controls.
+The geometry manager can move children around freely using
+.PN XtMoveWidget .
+When it resizes a child (that is, changes the width, height, or
+border width) other than the one making the request,
+it should do so by calling
+.PN XtResizeWidget .
+The requesting child may be given special treatment; see Section 6.5.
+It can simultaneously move and resize a child with a single call to
+.PN XtConfigureWidget .
+.LP
+Often, geometry managers find that they can satisfy a request only if
+they can reconfigure a widget that they are not in control of; in particular,
+the 
+composite 
+widget may want to change its own size.
+In this case,
+the geometry manager makes a request to its parent's geometry manager.
+Geometry requests can cascade this way to arbitrary depth.
+.LP
+Because such cascaded arbitration of widget geometry can involve extended
+negotiation,
+windows are not actually allocated to widgets at application
+startup until all widgets are satisfied with their geometry;
+see Sections 2.5 and 2.6.
+.NT Notes
+.IP 1. 5
+The \*(xI treatment of stacking requests is deficient in several areas.
+Stacking requests for unrealized widgets are granted but will have no effect.
+In addition, there is no way to do an
+.PN XtSetValues
+that will generate a stacking geometry request.
+.IP 2. 5
+After a successful geometry request (one that returned
+.PN XtGeometryYes ),
+a widget does not know whether its resize procedure has been called.
+Widgets should have resize procedures that can be called more than once
+without ill effects.
+.NE
+
+.NH 2
+General Geometry Manager Requests
+.XS
+\*(SN General Geometry Manager Requests
+.XE
+.LP
+When making a geometry request, the child specifies an
+.PN XtWidgetGeometry
+structure.
+.LP
+.IN "XtGeometryMask"
+.KS
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef unsigned long XtGeometryMask;
+
+typedef struct {
+	XtGeometryMask request_mode;
+	Position x, y;
+	Dimension width, height;
+	Dimension border_width;
+	Widget sibling;
+	int stack_mode;
+} XtWidgetGeometry;
+.De
+.eM
+.KE
+.LP
+To make a general geometry manager request from a widget, use
+.PN XtMakeGeometryRequest .
+.LP
+.IN "XtMakeGeometryRequest" "" "@DEF@"
+.sM
+.FD 0
+XtGeometryResult XtMakeGeometryRequest(\fIw\fP, \fIrequest\fP, \
+\fIreply_return\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtWidgetGeometry *\fIrequest\fP;
+.br
+      XtWidgetGeometry *\fIreply_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(rI
+.IP \fIrequest\fP 1i
+Specifies the desired widget geometry (size, position, border width,
+and stacking order).
+.IP \fIreply_return\fP 1i
+Returns the allowed widget size, or may be NULL
+if the requesting widget is not interested in handling
+.PN XtGeometryAlmost .
+.LP
+.eM
+Depending on the condition,
+.PN XtMakeGeometryRequest
+performs the following:
+.IP \(bu 5
+If the widget is unmanaged or the widget's parent is not realized,
+it makes the changes and returns
+.PN XtGeometryYes .
+.IP \(bu 5
+If the parent's class is not a subclass of
+.PN compositeWidgetClass 
+or the parent's \fIgeometry_manager\fP field is NULL,
+it issues an error.
+.IP \(bu 5
+If the widget's \fIbeing_destroyed\fP field is 
+.PN True ,
+it returns
+.PN XtGeometryNo .
+.IP \(bu 5
+If the widget \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and
+\fIborder_width\fP fields are
+all equal to the requested values,
+it returns
+.PN XtGeometryYes ;
+otherwise, it calls the parent's geometry_manager procedure 
+with the given parameters.
+.IP \(bu 5
+If the parent's geometry manager returns
+.PN XtGeometryYes
+and if
+.PN XtCWQueryOnly
+is not set in \fIrequest->request_mode\fP
+and if the widget is realized,
+.PN XtMakeGeometryRequest
+calls the 
+.PN XConfigureWindow
+Xlib function to reconfigure the widget's window (set its size, location, 
+and stacking order as appropriate).
+.IP \(bu 5
+If the geometry manager returns
+.PN XtGeometryDone ,
+the change has been approved and actually has been done.
+In this case,
+.PN XtMakeGeometryRequest
+does no configuring and returns 
+.PN XtGeometryYes .
+.PN XtMakeGeometryRequest
+never returns
+.PN XtGeometryDone .
+.IP \(bu 5
+Otherwise,
+.PN XtMakeGeometryRequest
+just returns the resulting value from the parent's geometry manager.
+.LP
+Children of primitive widgets are always unmanaged; therefore,
+.PN XtMakeGeometryRequest
+always returns
+.PN XtGeometryYes
+when called by a child of a primitive widget.
+.LP
+The return codes from geometry managers are
+.IN "XtGeometryResult"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 1.75i
+.ta .5i 1.75i
+typedef enum {
+	XtGeometryYes,
+	XtGeometryNo,
+	XtGeometryAlmost,
+	XtGeometryDone
+} XtGeometryResult;
+.De
+.eM
+.KE
+.LP
+The \fIrequest_mode\fP definitions are from
+.Pn < X11/X.h >.
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T}	T{
+.PN CWX
+T}	T{
+(1<<0)
+T}
+T{
+#define
+T}	T{
+.PN CWY
+T}	T{
+(1<<1)
+T}
+T{
+#define
+T}	T{
+.PN CWWidth
+T}	T{
+(1<<2)
+T}
+T{
+#define
+T}	T{
+.PN CWHeight
+T}	T{
+(1<<3)
+T}
+T{
+#define
+T}	T{
+.PN CWBorderWidth
+T}	T{
+(1<<4)
+T}
+T{
+#define
+T}	T{
+.PN CWSibling
+T}	T{
+(1<<5)
+T}
+T{
+#define
+T}	T{
+.PN CWStackMode
+T}	T{
+(1<<6)
+T}
+.TE
+.LP
+.eM
+The \*(xI also support the following value.
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T}	T{
+.PN XtCWQueryOnly
+T}	T{
+(1<<7)
+T}
+.TE
+.LP
+.eM
+.PN XtCWQueryOnly
+indicates that the corresponding geometry request is only a query
+as to what would happen if this geometry request were made
+and that no widgets should actually be changed.
+.LP
+.PN XtMakeGeometryRequest ,
+like the 
+.PN XConfigureWindow 
+Xlib function, uses \fIrequest_mode\fP to determine which fields in the
+.PN XtWidgetGeometry
+structure the caller wants to specify.
+.LP
+The \fIstack_mode\fP definitions are from
+.Pn < X11/X.h >:
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T}	T{
+.PN Above
+T}	T{
+0
+T}
+T{
+#define
+T}	T{
+.PN Below
+T}	T{
+1
+T}
+T{
+#define
+T}	T{
+.PN TopIf
+T}	T{
+2
+T}
+T{
+#define
+T}	T{
+.PN BottomIf
+T}	T{
+3
+T}
+T{
+#define
+T}	T{
+.PN Opposite
+T}	T{
+4
+T}
+.TE
+.LP
+.eM
+The \*(xI also support the following value.
+.LP
+.sM
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+T{
+#define
+T}	T{
+.PN XtSMDontChange
+T}	T{
+5
+T}
+.TE
+.LP
+.eM
+For definition and behavior of
+.PN Above ,
+.PN Below ,
+.PN TopIf ,
+.PN BottomIf ,
+and
+.PN Opposite ,
+see Section 3.7 in \fI\*(xL\fP.
+.PN XtSMDontChange
+indicates that the widget wants its current stacking order preserved.
+
+.NH 2
+Resize Requests
+.XS
+\*(SN Resize Requests
+.XE
+.LP
+To make a simple resize request from a widget, you can use
+.PN XtMakeResizeRequest 
+as an alternative to
+.PN XtMakeGeometryRequest .
+.LP
+.IN "XtMakeResizeRequest" "" "@DEF@"
+.sM
+.FD 0
+XtGeometryResult XtMakeResizeRequest(\fIw\fP, \fIwidth\fP, \fIheight\fP, \
+\fIwidth_return\fP, \fIheight_return\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Dimension \fIwidth\fP, \fIheight\fP;
+.br
+      Dimension *\fIwidth_return\fP, *\fIheight_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(rI
+.IP \fIwidth\fP 1i
+Specify the desired widget width and height.
+.br
+.ns
+.IP \fIheight\fP 1i
+.IP \fIwidth_return\fP 1i
+Return the allowed widget width and height.
+.br
+.ns
+.IP \fIheight_return\fP 1i
+.LP
+.eM
+The
+.PN XtMakeResizeRequest
+function, a simple interface to
+.PN XtMakeGeometryRequest ,
+creates an
+.PN XtWidgetGeometry
+structure and specifies that width and height should change
+by setting \fIrequest_mode\fP to
+.PN CWWidth
+\fB|\fP
+.PN CWHeight .
+The geometry manager is free to modify any of the other window attributes
+(position or stacking order) to satisfy the resize request.
+If the return value is
+.PN XtGeometryAlmost ,
+\fIwidth_return\fP and \fIheight_return\fP contain a compromise width and height.
+If these are acceptable,
+the widget should immediately call
+.PN XtMakeResizeRequest
+again and request that the compromise width and height be applied.
+If the widget is not interested in
+.PN XtGeometryAlmost
+replies, 
+it can pass NULL for \fIwidth_return\fP and \fIheight_return\fP.
+
+.NH 2
+Potential Geometry Changes
+.XS
+\*(SN Potential Geometry Changes
+.XE
+.LP
+Sometimes a geometry manager cannot respond to
+a geometry request from a child without first making a geometry request
+to the widget's own parent (the original requestor's grandparent).
+If the request to the grandparent would allow the parent to satisfy the
+original request, 
+the geometry manager can make the intermediate geometry request 
+as if it were the originator.
+On the other hand,
+if the geometry manager already has determined that the original request
+cannot be completely satisfied (for example, if it always denies
+position changes),
+it needs to tell the grandparent to respond to the intermediate request 
+without actually changing the geometry
+because it does not know if the child will accept the compromise.
+To accomplish this, the geometry manager uses 
+.PN XtCWQueryOnly
+in the intermediate request.
+.LP
+When
+.PN XtCWQueryOnly
+is used, the geometry manager needs to cache
+enough information to exactly reconstruct the intermediate request.
+If the grandparent's response to the intermediate query was
+.PN XtGeometryAlmost ,
+the geometry manager needs to cache the entire
+reply geometry in the event the child accepts the parent's compromise.
+.LP
+If the grandparent's response was
+.PN XtGeometryAlmost ,
+it may also be necessary to cache the entire reply geometry from
+the grandparent when
+.PN XtCWQueryOnly
+is not used.
+If the geometry manager is still able to satisfy the original request,
+it may immediately accept the grandparent's compromise 
+and then act on the child's request.
+If the grandparent's compromise geometry is insufficient to allow 
+the child's request and if the geometry manager is willing to offer
+a different compromise to the child, 
+the grandparent's compromise should not be accepted until the child 
+has accepted the new compromise.
+.LP
+Note that a compromise geometry returned with
+.PN XtGeometryAlmost
+is guaranteed only for the next call to the same widget; 
+therefore, a cache of size 1 is sufficient.
+
+.NH 2
+Child Geometry Management: The geometry_manager Procedure
+.XS
+\*(SN Child Geometry Management: The geometry_manager Procedure
+.XE
+.LP
+The geometry_manager procedure pointer in a composite widget class is of type
+.PN XtGeometryHandler .
+.LP
+.IN "XtGeometryHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, \
+XtWidgetGeometry*);
+.br
+      Widget \fIw\fP;
+.br
+      XtWidgetGeometry *\fIrequest\fP;
+.br
+      XtWidgetGeometry *\fIgeometry_return\fP;
+.FN
+.IP \fIw\fP 1.2i
+Passes the widget making the request.
+.IP \fIrequest\fP 1.2i
+Passes the new geometry the child desires.
+.IP \fIgeometry_return\fP 1.2i
+Passes a geometry structure in which the geometry manager may store a
+compromise.
+.LP
+.eM
+A class can inherit its superclass's geometry manager during class
+initialization.
+.LP
+A bit set to zero in the request's \fIrequest_mode\fP
+field means that the child widget
+does not care about the value of the corresponding field,
+so the geometry manager can change this field as it wishes.
+A bit set to 1 means that the child wants that geometry element set
+to the value in the corresponding field.
+.LP
+If the geometry manager can satisfy all changes requested 
+and if 
+.PN XtCWQueryOnly 
+is not specified,
+it updates the widget's \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP fields
+appropriately.
+Then, it returns
+.PN XtGeometryYes ,
+and the values pointed to by the \fIgeometry_return\fP argument are undefined.
+The widget's window is moved and resized automatically by
+.PN XtMakeGeometryRequest .
+.LP
+Homogeneous composite widgets often find it convenient to treat the widget
+making the request the same as any other widget, including reconfiguring
+it using
+.PN XtConfigureWidget
+or
+.PN XtResizeWidget
+as part of its layout process, unless 
+.PN XtCWQueryOnly
+is specified.
+If it does this,
+it should return
+.PN XtGeometryDone
+to inform
+.PN XtMakeGeometryRequest
+that it does not need to do the configuration itself.
+.NT
+To remain
+compatible with layout techniques used in older widgets (before
+.PN XtGeometryDone
+was added to the \*(xI), a geometry manager should avoid using
+.PN XtResizeWidget
+or
+.PN XtConfigureWidget
+on the child making
+the request because the layout process of the child may be in an
+intermediate state in which it is not prepared to handle a call to its
+resize procedure.  A self-contained widget set may choose this
+alternative geometry management scheme, however, provided that it
+clearly warns widget developers of the compatibility consequences.
+.NE
+.LP
+Although
+.PN XtMakeGeometryRequest
+resizes the widget's window
+(if the geometry
+manager returns
+.PN XtGeometryYes ),
+it does not call the widget class's resize procedure.
+The requesting widget must perform whatever
+resizing calculations are needed explicitly.
+.LP
+If the geometry manager disallows the request,
+the widget cannot change its geometry.
+The values pointed to by \fIgeometry_return\fP are undefined,
+and the geometry manager returns
+.PN XtGeometryNo .
+.LP
+Sometimes the geometry manager cannot satisfy the request exactly
+but may be able to satisfy a similar request.
+That is,
+it could satisfy only a subset of the requests (for example,
+size but not position) or a lesser request
+(for example, it cannot make the child as big as the
+request but it can make the child bigger than its current size).
+In such cases,
+the geometry manager fills in the structure pointed to by
+\fIgeometry_return\fP with the actual changes
+it is willing to make, including an appropriate \fIrequest_mode\fP mask, and returns
+.PN XtGeometryAlmost .
+If a bit in \fIgeometry_return->request_mode\fP is zero,
+the geometry manager agrees not to change the corresponding value
+if \fIgeometry_return\fP is used immediately
+in a new request.
+If a bit is 1,
+the geometry manager does change that element to the corresponding
+value in \fIgeometry_return\fP.
+More bits may be set in \fIgeometry_return->request_mode\fP
+than in the original request if
+the geometry manager intends to change other fields should the
+child accept the compromise.
+.LP
+When
+.PN XtGeometryAlmost
+is returned,
+the widget must decide if the compromise suggested in \fIgeometry_return\fP
+is acceptable.
+If it is, the widget must not change its geometry directly;
+rather, it must make another call to
+.PN XtMakeGeometryRequest .
+.LP
+If the next geometry request from this child uses the
+\fIgeometry_return\fP values filled in by the geometry manager with an
+.PN XtGeometryAlmost
+return and if there have been no intervening geometry requests on
+either its parent or any of its other children,
+the geometry manager must grant the request, if possible.
+That is, if the child asks immediately with the returned geometry,
+it should get an answer of
+.PN XtGeometryYes .
+However,
+dynamic behavior in
+the user's window manager may affect the final outcome.
+.LP
+To return
+.PN XtGeometryYes ,
+the geometry manager frequently rearranges the position of other managed 
+children by calling
+.PN XtMoveWidget .
+However, a few geometry managers may sometimes change the
+size of other managed children by calling
+.PN XtResizeWidget
+or
+.PN XtConfigureWidget .
+If
+.PN XtCWQueryOnly
+is specified,
+the geometry manager must return data describing
+how it would react to this geometry
+request without actually moving or resizing any widgets.
+.LP
+Geometry managers must not assume that the \fIrequest\fP
+and \fIgeometry_return\fP arguments point to independent storage.
+The caller is permitted to use the same field for both,
+and the geometry manager must allocate its own temporary storage,
+if necessary.
+
+.NH 2
+Widget Placement and Sizing
+.XS
+\*(SN Widget Placement and Sizing
+.XE
+.LP
+To move a sibling widget of the child making the geometry request,
+the parent uses
+.PN XtMoveWidget .
+.LP
+.IN "XtMoveWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtMoveWidget(\fIw\fP, \fIx\fP, \fIy\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Position \fIx\fP;
+.br
+      Position \fIy\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the new widget x and y coordinates.
+.LP
+.eM
+The
+.PN XtMoveWidget
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+.PN XtMoveWidget
+writes the new \fIx\fP and \fIy\fP values into the object
+and, if the object is a widget and is realized, issues an Xlib
+.PN XMoveWindow
+call on the widget's window.
+.sp
+.LP
+To resize a sibling widget of the child making the geometry request,
+the parent uses
+.PN XtResizeWidget .
+.LP
+.IN "XtResizeWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtResizeWidget(\fIw\fP, \fIwidth\fP, \fIheight\fP, \fIborder_width\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Dimension \fIwidth\fP;
+.br
+      Dimension \fIheight\fP;
+.br
+      Dimension \fIborder_width\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+.br
+.ns
+.IP \fIborder_width\fP 1i
+Specify the new widget size.
+.LP
+.eM
+The
+.PN XtResizeWidget
+function returns immediately if the specified geometry fields
+are the same as the old values. 
+Otherwise,
+.PN XtResizeWidget
+writes the new \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP values into
+the object and, if the object is a widget and is realized, issues an
+.PN XConfigureWindow
+call on the widget's window.
+.LP
+If the new width or height is different from the old values,
+.PN XtResizeWidget
+calls the object's resize procedure to notify it of the size change.
+.sp
+.LP
+To move and resize the sibling widget of the child making the geometry request,
+the parent uses
+.PN XtConfigureWidget .
+.LP
+.IN "XtConfigureWidget" "" "@DEF@"
+.sM
+.FD 0
+void XtConfigureWidget(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, \
+\fIborder_width\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Position \fIx\fP;
+.br
+      Position \fIy\fP;
+.br
+      Dimension \fIwidth\fP;
+.br
+      Dimension \fIheight\fP;
+.br
+      Dimension \fIborder_width\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the new widget x and y coordinates.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+.br
+.ns
+.IP \fIborder_width\fP 1i
+Specify the new widget size.
+.LP
+.eM
+The
+.PN XtConfigureWidget
+function returns immediately if the specified new geometry fields
+are all equal to the current values.
+Otherwise,
+.PN XtConfigureWidget
+writes the new \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP values 
+into the object and, if the object is a widget and is realized, makes an Xlib
+.PN XConfigureWindow
+call on the widget's window.
+.LP
+If the new width or height is different from its old value,
+.PN XtConfigureWidget
+calls the object's resize procedure to notify it of the size change;
+otherwise, it simply returns.
+.sp
+.LP
+To resize a child widget that already has the new values of its width,
+height, and border width, the parent uses
+.PN XtResizeWindow .
+.LP
+.IN "XtResizeWindow" "" "@DEF@"
+.sM
+.FD 0
+void XtResizeWindow(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+The
+.PN XtResizeWindow
+function calls the 
+.PN XConfigureWindow
+Xlib function to make the window of the specified widget match its width,
+height, and border width. 
+This request is done unconditionally because there is no
+inexpensive way to tell if these
+values match the current values.
+Note that the widget's resize procedure is not called.
+.LP
+There are very few times to use
+.PN XtResizeWindow ;
+instead, the parent should use
+.PN XtResizeWidget .
+
+.NH 2
+Preferred Geometry
+.XS
+\*(SN Preferred Geometry
+.XE
+.LP
+Some parents may be willing to adjust their layouts to accommodate the
+preferred geometries of their children.
+They can use
+.PN XtQueryGeometry
+to obtain the preferred geometry 
+and, as they see fit, can use or ignore any portion of the response.
+.sp
+.LP
+To query a child widget's preferred geometry, use
+.PN XtQueryGeometry .
+.LP
+.IN "XtQueryGeometry" "" "@DEF@"
+.sM
+.FD 0
+XtGeometryResult XtQueryGeometry(\fIw\fP, \fIintended\fP, \
+\fIpreferred_return\fP)
+.br
+     Widget \fIw\fP;
+.br
+     XtWidgetGeometry *\fIintended\fP;
+.br
+     XtWidgetGeometry *\fIpreferred_return\fP;
+.FN
+.IP \fIw\fP 1.1i
+Specifies the widget.  \*(rI
+.IP \fIintended\fP 1.1i
+Specifies the new geometry the parent plans to give to the child, or
+NULL.
+.IP \fIpreferred_return\fP 1.1i
+Returns the child widget's preferred geometry.
+.LP
+.eM
+To discover a child's preferred geometry,
+the child's parent stores the new
+geometry in the corresponding fields of
+the intended structure, sets the corresponding bits in \fIintended.request_mode\fP,
+and calls
+.PN XtQueryGeometry .
+The parent should set only those fields that are important to it so
+that the child can determine whether it may be able to attempt changes to
+other fields.
+.LP
+.PN XtQueryGeometry
+clears all bits in the \fIpreferred_return->request_mode\fP
+field and checks the
+\fIquery_geometry\fP field of the specified widget's class record.
+If \fIquery_geometry\fP is not NULL,
+.PN XtQueryGeometry
+calls the query_geometry procedure and passes as arguments the
+specified widget, \fIintended\fP, and \fIpreferred_return\fP structures.
+If the \fIintended\fP argument is NULL,
+.PN XtQueryGeometry
+replaces it with a pointer to an
+.PN XtWidgetGeometry
+structure with \fIrequest_mode\fP equal to zero before calling the
+query_geometry procedure.
+.NT
+If
+.PN XtQueryGeometry
+is called from within a geometry_manager
+procedure for the widget that issued
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest ,
+the results
+are not guaranteed to be consistent with the requested changes.  The
+change request passed to the geometry manager takes precedence over
+the preferred geometry.
+.NE
+.sp
+.LP
+The query_geometry procedure pointer is of type
+.PN XtGeometryHandler .
+.LP
+.IN "query_geometry procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry*, \
+XtWidgetGeometry*);
+.br
+      Widget \fIw\fP;
+.br
+      XtWidgetGeometry *\fIrequest\fP;
+.br
+      XtWidgetGeometry *\fIpreferred_return\fP;
+.FN
+.IP \fIw\fP 1.2i
+Passes the child widget whose preferred geometry is required.
+.IP \fIrequest\fP 1.2i
+Passes the geometry changes that the parent plans to make.
+.IP \fIpreferred_return\fP 1.2i
+Passes a structure in which the child returns its preferred geometry.
+.LP
+.eM
+.IN "query_geometry procedure"
+The query_geometry procedure is expected to examine the bits set in
+\fIrequest->request_mode\fP, evaluate the preferred geometry of the widget,
+and store the result in \fIpreferred_return\fP
+(setting the bits in \fIpreferred_return->request_mode\fP corresponding
+to those geometry fields that it cares about).
+If the proposed geometry change is acceptable without modification,
+the query_geometry procedure should return
+.PN XtGeometryYes .
+If at least one field in \fIpreferred_return\fP
+with a bit set in \fIpreferred_return->request_mode\fP
+is different
+from the corresponding field in \fIrequest\fP
+or if a bit was set in \fIpreferred_return->request_mode\fP
+that was not set in the request,
+the query_geometry procedure should return
+.PN XtGeometryAlmost .
+If the preferred geometry is identical to the current geometry,
+the query_geometry procedure should return
+.PN XtGeometryNo .
+.NT
+The query_geometry procedure may assume
+that no
+.PN XtMakeResizeRequest
+or
+.PN XtMakeGeometryRequest
+is in progress
+for the specified widget; that is, it is not required to construct
+a reply consistent with the requested geometry if such a request
+were actually outstanding.
+.NE
+.LP
+After calling the query_geometry procedure
+or if the \fIquery_geometry\fP field is NULL,
+.PN XtQueryGeometry
+examines all the unset bits in \fIpreferred_return->request_mode\fP
+and sets the corresponding fields in \fIpreferred_return\fP
+to the current values from the widget instance.
+If
+.PN CWStackMode
+is not set,
+the \fIstack_mode\fP field is set to
+.PN XtSMDontChange .
+.PN XtQueryGeometry
+returns the value returned by the query_geometry procedure or
+.PN XtGeometryYes
+if the \fIquery_geometry\fP field is NULL.
+.LP
+Therefore, the caller can interpret a return of
+.PN XtGeometryYes
+as not needing to evaluate the contents of the reply and, more important,
+not needing to modify its layout plans.
+A return of
+.PN XtGeometryAlmost
+means either that both the parent and the child expressed interest
+in at least one common field and the child's preference does not match 
+the parent's intentions or that the child expressed interest in a field that
+the parent might need to consider.
+A return value of
+.PN XtGeometryNo
+means that both the parent and the child expressed interest in a field and
+that the child suggests that the field's current value in the widget instance
+is its preferred value.
+In addition, whether or not the caller ignores the return value or the
+reply mask, it is guaranteed that the \fIpreferred_return\fP structure contains complete
+geometry information for the child.
+.LP
+Parents are expected to call
+.PN XtQueryGeometry
+in their layout routine and wherever else the information is significant
+after change_managed has been called.
+The first time it is invoked,
+the changed_managed procedure may assume that the child's current geometry
+is its preferred geometry.
+Thus, the child is still responsible for storing values
+into its own geometry during its initialize procedure.
+
+.NH 2
+Size Change Management: The resize Procedure
+.XS
+\*(SN Size Change Management: The resize Procedure
+.XE
+.LP
+A child can be resized by its parent at any time.
+Widgets usually need to know when they have changed size
+so that they can lay out their displayed data again to match the new size.
+When a parent resizes a child, it calls
+.PN XtResizeWidget ,
+which updates the geometry fields in the widget,
+configures the window if the widget is realized,
+and calls the child's resize procedure to notify the child.
+The resize procedure pointer is of type
+.PN XtWidgetProc .
+.IN "resize procedure" "" "@DEF@"
+.LP
+If a class need not recalculate anything when a widget is resized,
+it can specify NULL for the \fIresize\fP field in its class record.
+This is an unusual case and should occur only for widgets
+with very trivial display semantics.
+The resize procedure takes a widget as its only argument.
+The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP fields of the widget contain the new values.
+The resize procedure should recalculate the layout of internal data
+as needed.
+(For example, a centered Label in a window that changes size
+should recalculate the starting position of the text.)
+The widget must obey resize as a command and must not treat it as a request.
+A widget must not issue an
+.PN XtMakeGeometryRequest
+or
+.PN XtMakeResizeRequest
+call from its resize procedure.
+.bp
diff --git a/libXt/specs/CH07 b/libXt/specs/CH07
new file mode 100644
index 000000000..07b36746b
--- /dev/null
+++ b/libXt/specs/CH07
@@ -0,0 +1,3555 @@
+.\" $Xorg: CH07,v 1.4 2000/08/17 19:42:45 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 7\fP\s-1
+
+\s+1\fBEvent Management\fP\s-1
+.sp 2
+.nr H1 7
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 7 \(em Event Management
+.XE
+While Xlib allows the reading and processing of events anywhere in an application,
+widgets in the \*(tk neither directly read events
+nor grab the server or pointer.
+Widgets register procedures that are to be called
+when an event or class of events occurs in that widget.
+.LP
+A typical application consists of startup code followed by an event loop
+that reads events and dispatches them by calling
+the procedures that widgets have registered.
+The default event loop provided by the \*(xI is
+.PN XtAppMainLoop .
+.LP
+The event manager is a collection of functions to perform the following tasks:
+.IP \(bu 5
+Add or remove event sources other than X server events (in particular,
+timer interrupts, file input, or POSIX signals).
+.IP \(bu 5
+Query the status of event sources.
+.IP \(bu 5
+Add or remove procedures to be called when an event occurs for a particular
+widget.
+.IP \(bu 5
+Enable and
+disable the dispatching of user-initiated events (keyboard and pointer events)
+for a particular widget.
+.IP \(bu 5
+Constrain the dispatching of events to a cascade of pop-up widgets.
+.IP \(bu 5
+Register procedures to be called when specific events arrive.
+.IP \(bu 5
+Register procedures to be called when the \*(xI will block.
+.IP \(bu 5
+Enable safe operation in a multi-threaded environment.
+.LP
+Most widgets do not need to call any of the event handler functions explicitly.
+The normal interface to X events is through the higher-level
+translation manager,
+which maps sequences of X events, with modifiers, into procedure calls.
+Applications rarely use any of the event manager routines besides
+.PN XtAppMainLoop .
+
+.NH 2
+Adding and Deleting Additional Event Sources
+.XS
+\fB\*(SN Adding and Deleting Additional Event Sources\fP
+.XE
+.LP
+While most applications are driven only by X events,
+some applications need to incorporate other sources of input 
+into the \*(xI event-handling mechanism.
+The event manager provides routines to integrate notification of timer events
+and file data pending into this mechanism.
+.LP
+The next section describes functions that provide input gathering from files.
+The application registers the files with the \*(xI read routine.
+When input is pending on one of the files,
+the registered callback procedures are invoked.
+
+.NH 3
+Adding and Removing Input Sources
+.XS
+\fB\*(SN Adding and Removing Input Sources\fP
+.XE
+.LP
+To register a new file as an input source for a given application context, use
+.PN XtAppAddInput .
+.LP
+.IN "XtAppAddInput" "" "@DEF@"
+.sM
+.FD 0
+XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      int \fIsource\fP;
+.br
+      XtPointer \fIcondition\fP;
+.br
+      XtInputCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIsource\fP 1i
+Specifies the source file descriptor on a POSIX-based system
+or other operating-system-dependent device specification.
+.IP \fIcondition\fP 1i
+Specifies the mask that indicates a read, write, or exception condition
+or some other operating-system-dependent condition.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the condition is found.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure
+when it is called.
+.LP
+.eM
+The
+.PN XtAppAddInput
+function registers with the \*(xI read routine a new source of events,
+which is usually file input but can also be file output.
+Note that \fIfile\fP should be loosely interpreted to mean any sink 
+or source of data.
+.PN XtAppAddInput
+also specifies the conditions under which the source can generate events.
+When an event is pending on this source,
+the callback procedure is called.
+.LP
+The legal values for the \fIcondition\fP argument are operating-system-dependent.
+On a POSIX-based system,
+\fIsource\fP is a file number and the condition is some union of the following:
+.IN "XtInputReadMask" "" "@DEF@"
+.IP \fBXtInputReadMask\fR 1.5i
+Specifies that \fIproc\fP is to be called when \fIsource\fP has data to be read.
+.IN "XtInputWriteMask" "" "@DEF@"
+.IP \fBXtInputWriteMask\fR 1.5i
+Specifies that \fIproc\fP is to be called when \fIsource\fP is ready
+for writing.
+.IN "XtInputExceptMask" "" "@DEF@"
+.IP \fBXtInputExceptMask\fR 1.5i
+Specifies that \fIproc\fP is to be called when \fIsource\fP has
+exception data.
+.LP
+Callback procedure pointers used to handle file events are of
+type
+.PN XtInputCallbackProc .
+.LP
+.IN "XtInputCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*);
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      int *\fIsource\fP;
+.br
+      XtInputId *\fIid\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtApp\%AddInput .
+.IP \fIsource\fP 1i
+Passes the source file descriptor generating the event.
+.IP \fIid\fP 1i
+Passes the id returned from the corresponding
+.PN XtAppAddInput
+call.
+.LP
+.eM
+See Section 7.12 for information regarding the use of
+.PN XtAppAddInput
+in multiple threads.
+.sp
+.LP
+To discontinue a source of input, use
+.PN XtRemoveInput .
+.LP
+.IN "XtRemoveInput" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveInput(\fIid\fP)
+.br
+      XtInputId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the id returned from the corresponding
+.PN XtAppAddInput
+call.
+.LP
+.eM
+The
+.PN XtRemoveInput
+function causes the \*(xI read routine to stop watching for events
+from the file source specified by \fIid\fP.
+.LP
+See Section 7.12 for information regarding the use of
+.PN XtRemoveInput
+in multiple threads.
+
+.NH 3
+Adding and Removing Blocking Notifications
+.XS
+\fB\*(SN Adding and Removing Blocking Notifications\fP
+.XE
+.LP
+Occasionally it is desirable for an application to receive notification
+when the \*(xI event manager detects no pending input from file sources
+and no pending input from X server event sources and is about to block
+in an operating system call.
+.sp
+.LP
+To register a hook that is called immediately prior to event blocking, use
+.PN XtAppAddBlockHook .
+.LP
+.IN "XtAppAddBlockHook" "" "@DEF@"
+.sM
+.FD 0
+XtBlockHookId XtAppAddBlockHook(\fIapp_context\fP, \fIproc\fP, \
+\fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtBlockHookProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called before blocking.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure when it is called.
+.LP
+.eM
+The
+.PN XtAppAddBlockHook 
+function registers the specified procedure and returns an identifier for it.
+The hook procedure \fIproc\fP is called at any time in the future when
+the \*(xI are about to block pending some input.
+.LP
+The procedure pointers used to provide notification of event blocking
+are of type
+.PN XtBlockHookProc .
+.LP
+.IN "XtBlockHookProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtBlockHookProc)(XtPointer);
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtApp\%AddBlockHook .
+.LP
+.eM
+To discontinue the use of a procedure for blocking notification, use
+.PN XtRemoveBlockHook .
+.LP
+.IN "XtRemoveBlockHook" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveBlockHook(\fIid\fP)
+.br
+      XtBlockHookId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the identifier returned from the corresponding call to
+.PN XtAppAddBlockHook .
+.LP
+.eM
+The 
+.PN XtRemoveBlockHook 
+function removes the specified procedure from the list of procedures
+that are called by the \*(xI read routine before blocking on event sources.
+
+.NH 3
+Adding and Removing Timeouts
+.XS
+\fB\*(SN Adding and Removing Timeouts\fP
+.XE
+.LP
+The timeout facility notifies the application or the widget
+through a callback procedure that a specified time interval has elapsed.
+Timeout values are uniquely identified by an interval id.
+.sp
+.LP
+To register a timeout callback, use
+.PN XtAppAddTimeOut .
+.LP
+.IN "XtAppAddTimeOut" "" "@DEF@"
+.sM
+.FD 0
+XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \
+\fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      unsigned long \fIinterval\fP;
+.br
+      XtTimerCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context for which the timer is to be set.
+.IP \fIinterval\fP 1i
+Specifies the time interval in milliseconds.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the time expires.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure
+when it is called.
+.LP
+.eM
+The
+.PN XtAppAddTimeOut
+function creates a timeout and returns an identifier for it.
+The timeout value is set to \fIinterval\fP.
+The callback procedure \fIproc\fP is called when
+.PN XtAppNextEvent
+or
+.PN XtAppProcessEvent
+is next called after the time interval elapses,
+and then the timeout is removed.
+.LP
+Callback procedure pointers used with timeouts are of
+type
+.PN XtTimerCallbackProc .
+.LP
+.IN "XtTimerCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*);
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtIntervalId *\fItimer\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtApp\%AddTimeOut .
+.IP \fItimer\fP 1i
+Passes the id returned from the corresponding
+.PN XtAppAddTimeOut
+call.
+.LP
+.eM
+See Section 7.12 for information regarding the use of
+.PN XtAppAddTimeOut
+in multiple threads.
+.sp
+.LP
+To clear a timeout value, use
+.PN XtRemoveTimeOut .
+.LP
+.IN "XtRemoveTimeOut" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveTimeOut(\fItimer\fP)
+.br
+      XtIntervalId \fItimer\fP;
+.FN
+.IP \fItimer\fP 1i
+Specifies the id for the timeout request to be cleared.
+.LP
+.eM
+The
+.PN XtRemoveTimeOut
+function removes the pending timeout.
+Note that timeouts are automatically removed once they trigger.
+.LP
+Please refer to Section 7.12 for information regarding the use of
+.PN XtRemoveTimeOut
+in multiple threads.
+
+.NH 3
+Adding and Removing Signal Callbacks
+.XS
+\fB\*(SN Adding and Removing Signal Callbacks\fP
+.XE
+.LP
+The signal facility notifies the application or the widget through a 
+callback procedure that a signal or other external asynchronous event 
+has occurred.  The registered callback procedures are uniquely identified 
+by a signal id.
+.sp
+.LP
+Prior to establishing a signal handler, the application or widget should
+call
+.PN XtAppAddSignal
+and store the resulting identifier in a place accessible to the signal
+handler.  When a signal arrives, the signal handler should call
+.PN XtNoticeSignal
+to notify the \*(xI that a signal has occured.  To register a signal 
+callback use
+.PN XtAppAddSignal .
+.LP
+.IN "XtAppAddSignal" "" "@DEF@"
+.sM
+.FD 0
+XtSignalId XtAppAddSignal(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtSignalCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the signal is noticed.
+.IP \fIclient_data\fP 1i
+Specifies an argument passed to the specified procedure when it is called.
+.LP
+.eM
+The callback procedure pointers used to handle signal events are of type
+.PN XtSignalCallbackProc .
+.LP
+.IN "XtSignalCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*);
+.br
+	XtPointer \fIclient_data\fP;
+.br
+	XtSignalId *\fIid\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data argument that was registered for this procedure in
+.PN XtAppAddSignal .
+.IP \fIid\fP 1i
+Passes the id returned from the corresponding 
+.PN XtAppAddSignal
+call.
+.LP
+.eM
+To notify the \*(xI that a signal has occured, use
+.PN XtNoticeSignal .
+.LP
+.IN "XtNoticeSignal" "" "@DEF@"
+.sp
+.sM
+.FD 0
+void XtNoticeSignal(\fIid\fP)
+.br
+      XtSignalId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the id returned from the corresponding
+.PN XtAppAddSignal
+call.
+.LP
+.eM
+On a POSIX-based system,
+.PN XtNoticeSignal
+is the only \*(xI function that can safely be called from a signal handler.
+If 
+.PN XtNoticeSignal
+is invoked multiple times before the \*(xI are able to invoke the
+registered callback, the callback is only called once.
+Logically, the \*(xI maintain ``pending'' flag for each registered callback.
+This flag is initially
+.PN False
+and is set to
+.PN True
+by
+.PN XtNoticeSignal .
+When 
+.PN XtAppNextEvent
+or
+.PN XtAppProcessEvent
+(with a mask including
+.PN XtIMSignal )
+is called, all registered callbacks with ``pending''
+.PN True
+are invoked and the flags are reset to
+.PN False .
+.LP
+If the signal handler wants to track how many times the signal has been
+raised, it can keep its own private counter.  Typically the handler would 
+not do any other work; the callback does the actual processing for the 
+signal. The \*(xI never block signals from being raised, so if a given 
+signal can be raised multiple times before the \*(xI can invoke the 
+callback for that signal, the callback must be designed to deal with 
+this.  In another case, a signal might be raised just after the \*(xI
+sets the pending flag to
+.PN False
+but before the callback can get control, in which case the pending flag
+will still be
+.PN True
+after the callback returns, and the \*(xI will invoke the callback
+again, even though all of the signal raises have been handled.  The
+callback must also be prepared to handle this case.
+.LP
+To remove a registered signal callback, call
+.PN XtRemoveSignal .
+.LP
+.IN "XtRemoveSignal" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveSignal(\fIid\fP)
+.br
+      XtSignalId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the id returned by the corresponding call to
+.PN XtAppAddSignal .
+.LP
+.eM
+The client should typically disable the source of the signal before calling
+.PN XtRemoveSignal .
+If the signal could have been raised again before the source was disabled
+and the client wants to process it, then after disabling the source but
+before calling
+.PN XtRemoveSignal
+the client can test for signals with
+.PN XtAppPending
+and process them by calling
+.PN XtAppProcessEvent
+with the mask
+.PN XtIMSignal .
+
+.NH 2
+Constraining Events to a Cascade of Widgets
+.XS
+\fB\*(SN Constraining Events to a Cascade of Widgets\fP
+.XE
+.LP
+.IN "Grabbing Input"
+.IN "Input Grabbing"
+Modal widgets are widgets that, except for the input directed to them,
+lock out user input to the application.
+.LP
+When a modal menu or modal dialog box is popped up using
+.PN XtPopup ,
+user events (keyboard and pointer events) that occur outside the modal
+widget should be delivered to the modal widget or ignored.
+In no case will user events be delivered to a widget outside
+the modal widget.
+.LP
+Menus can pop up submenus, and dialog boxes can pop up further dialog
+boxes to create a pop-up cascade.
+In this case,
+user events may be delivered to one of several modal widgets in the cascade.
+.LP
+Display-related events should be delivered outside the modal cascade so that
+exposure events and the like keep the application's display up-to-date.
+Any event that occurs within the cascade is delivered as usual.
+The user events delivered to the most recent spring-loaded shell 
+in the cascade when they occur outside the cascade are called remap events 
+and are
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+and
+.PN ButtonRelease .
+The user events ignored when they occur outside the cascade are
+.PN MotionNotify
+and
+.PN EnterNotify .
+All other events are delivered normally.
+In particular, note that this is one
+way in which widgets can receive
+.PN LeaveNotify
+events without first receiving
+.PN EnterNotify
+events; they should be prepared to deal with
+this, typically by ignoring any unmatched
+.PN LeaveNotify
+events.
+.LP
+.PN XtPopup
+uses the 
+.PN XtAddGrab
+and
+.PN XtRemoveGrab
+functions to constrain user events to a modal cascade 
+and subsequently to remove a grab when the modal widget is popped down.
+
+.sp
+.LP
+To constrain or redirect user input to a modal widget, use
+.PN XtAddGrab .
+.LP
+.IN "XtAddGrab" "" "@DEF@"
+.sM
+.FD 0
+void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Boolean \fIexclusive\fP;
+.br
+      Boolean \fIspring_loaded\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget to add to the modal cascade. \*(cI
+.IP \fIexclusive\fP 1i
+Specifies whether user events should be dispatched exclusively to this widget 
+or also to previous widgets in the cascade.
+.IP \fIspring_loaded\fP 1i
+Specifies whether this widget was popped up because the user pressed
+a pointer button.
+.LP
+.eM
+The
+.PN XtAddGrab
+function appends the widget to the modal cascade
+and checks that \fIexclusive\fP is 
+.PN True 
+if \fIspring_loaded\fP is 
+.PN True .
+If this condition is not met,
+.PN XtAddGrab
+generates a warning message.
+.LP
+The modal cascade is used by
+.PN XtDispatchEvent
+when it tries to dispatch a user event.
+When at least one modal widget is in the widget cascade, 
+.PN XtDispatchEvent
+first determines if the event should be delivered.
+It starts at the most recent cascade entry and follows the cascade up to and
+including the most recent cascade entry added with the \fIexclusive\fP parameter
+.PN True .
+.LP
+This subset of the modal cascade along with all descendants of these widgets
+comprise the active subset.
+User events that occur outside the widgets in this subset are ignored
+or remapped.
+Modal menus with submenus generally add a submenu widget to the cascade
+with \fIexclusive\fP 
+.PN False .
+Modal dialog boxes that need to restrict user input to the most deeply nested
+dialog box add a subdialog widget to the cascade with \fIexclusive\fP 
+.PN True .
+User events that occur within the active subset are delivered to the
+appropriate widget, which is usually a child or further descendant of the modal
+widget.
+.LP
+Regardless of where in the application they occur,
+remap events are always delivered to the most recent widget in the active
+subset of the cascade registered with \fIspring_loaded\fP 
+.PN True ,
+if any such widget exists.
+If the event
+occurred in the active subset of the cascade but outside the
+spring-loaded widget, it is delivered normally before being
+delivered also to the spring-loaded widget.
+Regardless of where it is dispatched, the \*(xI do not modify
+the contents of the event.
+.sp
+.LP
+To remove the redirection of user input to a modal widget, use
+.PN XtRemoveGrab .
+.LP
+.IN "XtRemoveGrab" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveGrab(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget to remove from the modal cascade.
+.LP
+.eM
+The
+.PN XtRemoveGrab
+function removes widgets from the modal cascade starting 
+at the most recent widget up to and including the specified widget.
+It issues a warning if the specified widget is not on the modal cascade.
+
+.NH 3
+Requesting Key and Button Grabs
+.XS
+\fB\*(SN Requesting Key and Button Grabs\fP
+.XE
+.LP
+The \*(xI provide a set of key and button grab interfaces that
+are parallel to those provided by Xlib and that allow the \*(xI
+to modify event dispatching when necessary.  \*(tk applications and
+widgets that need to passively grab keys or buttons or actively grab
+the keyboard or pointer should use the
+following \*(xI routines rather than the corresponding Xlib
+routines.
+.sp
+.LP
+To passively grab a single key of the keyboard, use
+.PN XtGrabKey .
+.LP
+.IN "XtGrabKey" "" "@DEF@"
+.sM
+.FD 0
+void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \
+\fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      KeyCode \fIkeycode\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the key is to be grabbed.  \*(cI
+.sp 6p
+.IP \fIkeycode\fP
+.br
+.ns
+.IP \fImodifiers\fP
+.br
+.ns
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP 1i
+Specify arguments to
+.PN XGrabKey ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtGrabKey
+calls
+.PN XGrabKey
+specifying the widget's window as the grab
+window if the widget is realized.  The remaining arguments are exactly
+as for
+.PN XGrabKey .
+If the widget is not realized, or is later unrealized, the call to
+.PN XGrabKey
+is performed (again) when
+the widget is realized and its window becomes mapped.  In the future,
+if
+.PN XtDispatchEvent
+is called with a
+.PN KeyPress
+event matching the specified keycode and modifiers (which may be
+.PN AnyKey
+or
+.PN AnyModifier ,
+respectively) for the
+widget's window, the \*(xI will call
+.PN XtUngrabKeyboard
+with the timestamp from the
+.PN KeyPress
+event if either of the following conditions is true:
+.IP \(bu 3
+There is a modal cascade and the widget is not in
+the active subset of the cascade and the keyboard was not previously
+grabbed, or
+.IP \(bu 3
+.PN XFilterEvent
+returns
+.PN True .
+
+.sp
+.LP
+To cancel a passive key grab, use
+.PN XtUngrabKey .
+.LP
+.IN "XtUngrabKey" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      KeyCode \fIkeycode\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the key was grabbed.
+.sp 6p
+.IP \fIkeycode\fP
+.br
+.ns
+.IP \fImodifiers\fP 1i
+Specify arguments to
+.PN XUngrabKey ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+The
+.PN XtUngrabKey
+procedure calls
+.PN XUngrabKey
+specifying the widget's
+window as the ungrab window if the widget is realized.  The remaining
+arguments are exactly as for
+.PN XUngrabKey .
+If the widget is not realized,
+.PN XtUngrabKey
+removes a deferred
+.PN XtGrabKey
+request, if any, for the specified widget, keycode, and modifiers.
+.sp
+.LP
+To actively grab the keyboard, use
+.PN XtGrabKeyboard .
+.LP
+.IN "XtGrabKeyboard" "" "@DEF@"
+.sM
+.FD 0
+int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \
+\fIkeyboard_mode\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.br
+      Time \fItime\fP;
+.br
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for whose window the keyboard is to be grabbed.
+\*(cI
+.sp 6p
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP
+.br
+.ns
+.IP \fItime\fP 1i
+Specify arguments to
+.PN XGrabKeyboard ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+If the specified widget is realized,
+.PN XtGrabKeyboard
+calls
+.PN XGrabKeyboard
+specifying the widget's window as the grab window.  The remaining
+arguments and return value are exactly as for
+.PN XGrabKeyboard .
+If the widget is not realized,
+.PN XtGrabKeyboard
+immediately returns
+.PN GrabNotViewable .
+No future automatic ungrab is implied by
+.PN XtGrabKeyboard .
+.sp
+.LP
+To cancel an active keyboard grab, use
+.PN XtUngrabKeyboard .
+.LP
+.IN "XtUngrabKeyboard" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget that has the active keyboard grab.
+.IP \fItime\fP 1i
+Specifies the additional argument to
+.PN XUngrabKeyboard ;
+see Section 12.2 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtUngrabKeyboard
+calls
+.PN XUngrabKeyboard
+with the specified time.
+.sp
+.LP
+To passively grab a single pointer button, use
+.PN XtGrabButton .
+.LP
+.IN "XtGrabButton" "" "@DEF@"
+.sM
+.FD 0
+void XtGrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP, \
+\fIowner_events\fP, \fIevent_mask\fP, \fIpointer_mode\fP,
+                  \fIkeyboard_mode\fP, \fIconfine_to\fP, \fIcursor\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      int \fIbutton\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      unsigned int \fIevent_mask\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.br
+      Window \fIconfine_to\fP;
+.br
+      Cursor \fIcursor\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the button is to be grabbed.  \*(cI
+.sp 6p
+.IP \fIbutton\fP
+.br
+.ns
+.IP \fImodifiers\fP
+.br
+.ns
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIevent_mask\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP
+.br
+.ns
+.IP \fIconfine_to\fP
+.br
+.ns
+.IP \fIcursor\fP 1i
+Specify arguments to
+.PN XGrabButton ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtGrabButton
+calls
+.PN XGrabButton
+specifying the widget's window as the
+grab window if the widget is realized.  The remaining arguments are
+exactly as for
+.PN XGrabButton .
+If the widget is not realized, or is later unrealized, the call to
+.PN XGrabButton
+is performed (again)
+when the widget is realized and its window becomes mapped.  In the
+future, if
+.PN XtDispatchEvent
+is called with a
+.PN ButtonPress
+event matching the specified button and modifiers (which may be
+.PN AnyButton
+or
+.PN AnyModifier ,
+respectively)
+for the widget's window, the \*(xI will call
+.PN XtUngrabPointer
+with the timestamp from the
+.PN ButtonPress
+event if either of the following conditions is true:
+.IP \(bu 3
+There is a modal cascade and the
+widget is not in the active subset of the cascade and the pointer was
+not previously grabbed, or
+.IP \(bu 3
+.PN XFilterEvent
+returns
+.PN True .
+
+.sp
+.LP
+To cancel a passive button grab, use
+.PN XtUngrabButton .
+.LP
+.IN "XtUngrabButton" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      unsigned int \fIbutton\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in whose window the button was grabbed.
+.IP \fIbutton\fP
+.br
+.ns
+.IP \fImodifiers\fP 1i
+Specify arguments to
+.PN XUngrabButton ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+The
+.PN XtUngrabButton
+procedure calls
+.PN XUngrabButton
+specifying the
+widget's window as the ungrab window if the widget is realized.  The
+remaining arguments are exactly as for
+.PN XUngrabButton .
+If the widget is not realized,
+.PN XtUngrabButton
+removes a deferred
+.PN XtGrabButton
+request, if any, for the specified widget, button, and modifiers.
+.sp
+.LP
+To actively grab the pointer, use
+.PN XtGrabPointer .
+.LP
+.IN "XtGrabPointer" "" "@DEF@"
+.sM
+.FD 0
+int XtGrabPointer(\fIwidget\fP, \fIowner_events\fP, \fIevent_mask\fP, \
+\fIpointer_mode\fP, \fIkeyboard_mode\fP,
+                  \fIconfine_to\fP, \fIcursor\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      unsigned int \fIevent_mask\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.br
+      Window \fIconfine_to\fP;
+.br
+      Cursor \fIcursor\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for whose window the pointer is to be grabbed.  \*(cI
+.sp 6p
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIevent_mask\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP
+.br
+.ns
+.IP \fIconfine_to\fP
+.br
+.ns
+.IP \fIcursor\fP
+.br
+.ns
+.IP \fItime\fP 1i
+Specify arguments to
+.PN XGrabPointer ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+If the specified widget is realized,
+.PN XtGrabPointer
+calls
+.PN XGrabPointer ,
+specifying the widget's window as the grab window.  The remaining
+arguments and return value are exactly as for
+.PN XGrabPointer .
+If the widget is not realized,
+.PN XtGrabPointer
+immediately returns
+.PN GrabNotViewable .
+No future automatic ungrab is implied by
+.PN XtGrabPointer .
+.sp
+.LP
+To cancel an active pointer grab, use
+.PN XtUngrabPointer .
+.LP
+.IN "XtUngrabPointer" "" "@DEF@"
+.sM
+.FD 0
+void XtUngrabPointer(\fIwidget\fP, \fItime\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget that has the active pointer grab.
+.IP \fItime\fP 1i
+Specifies the time argument to
+.PN XUngrabPointer ;
+see Section 12.1 in \fI\*(xL\fP.
+.LP
+.eM
+.PN XtUngrabPointer
+calls
+.PN XUngrabPointer
+with the specified time.
+
+.NH 2
+Focusing Events on a Child
+.XS
+\fB\*(SN Focusing Events on a Child\fP
+.XE
+.LP
+To redirect keyboard input to a normal descendant of a
+widget without calling
+.PN XSetInputFocus ,
+use
+.PN XtSetKeyboardFocus .
+.LP
+.IN "XtSetKeyboardFocus" "" "@DEF@"
+.sM
+.FD 0
+void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP)
+.br
+     Widget \fIsubtree\fP, \fIdescendant\fP;
+.FN
+.IP \fIsubtree\fP 1i
+Specifies the subtree of the hierarchy for which the keyboard focus is 
+to be set.  \*(cI
+.IP \fIdescendant\fP 1i
+Specifies either the normal (non-pop-up) descendant of \fIsubtree\fP to which
+keyboard events are logically directed, or 
+.PN None .
+It is not an error to specify
+.PN None
+when no input focus was previously set.  \*(oI
+.LP
+.eM
+.PN XtSetKeyboardFocus
+causes
+.PN XtDispatchEvent
+to remap keyboard events occurring within the specified subtree
+and dispatch them to the specified descendant widget or to an ancestor.
+If the descendant's class is not a subclass of Core, the descendant is
+replaced by its closest windowed ancestor.
+.LP
+When there is no modal cascade, keyboard events can be dispatched
+to a widget in one of five ways.  Assume the server delivered the
+event to the window for widget E (because of X input focus, key or
+keyboard grabs, or pointer position).
+.IP \(bu 3
+If neither E nor any of E's ancestors have redirected the keyboard
+focus, or if the event activated a grab for E as specified by a call
+to
+.PN XtGrabKey
+with any value of \fIowner_events\fP, or
+if the keyboard is actively grabbed by E with \fIowner_events\fP
+.PN False
+via
+.PN XtGrabKeyboard
+or
+.PN XtGrabKey
+on a previous key press, the event is dispatched to E.
+.IP \(bu 3
+Beginning with the ancestor of E closest to the root that has
+redirected the keyboard focus or E if no such ancestor exists, if
+the target of that focus redirection has in turn redirected the
+keyboard focus, recursively follow this focus chain to find a widget
+F that has not redirected focus.
+.RS
+.IP \- 3
+If E is the final focus target widget F or a descendant of F, the
+event is dispatched to E.
+.IP \- 3
+If E is not F, an ancestor of F, or a descendant of F, and the event
+activated a grab for E as specified by a call to
+.PN XtGrabKey
+for E,
+.PN XtUngrabKeyboard
+is called.
+.IP \- 3
+If E is an ancestor of F, and the event is a key press, and either
+.RS
+.IP + 3
+E has grabbed the key with
+.PN XtGrabKey
+and \fIowner_events\fP
+.PN False ,
+or
+.IP + 3
+E has grabbed the key with
+.PN XtGrabKey
+and \fIowner_events\fP
+.PN True ,
+and the coordinates of the event are outside the rectangle specified
+by E's geometry,
+.RE
+then the event is dispatched to E.
+.IP \- 3
+Otherwise, define A as the closest common ancestor of E and F:
+.RS
+.IP + 3
+If there is an active keyboard grab for any widget via either
+.PN XtGrabKeyboard
+or
+.PN XtGrabKey
+on a previous key press, or
+if no widget between F and A (noninclusive) has grabbed
+the key and modifier combination with
+.PN XtGrabKey
+and any value of \fIowner_events\fP, the event is dispatched to F.
+.IP + 3
+Else, the event is dispatched to the ancestor of F closest to A
+that has grabbed the key and modifier combination with
+.PN XtGrabKey .
+.RE
+.RE
+.LP
+When there is a modal cascade, if the final destination widget as
+identified above is in the active subset of the cascade, the event is
+dispatched; otherwise the event is remapped to a spring-loaded shell
+or discarded.
+Regardless of where it is dispatched, the \*(xI do not modify
+the contents of the event.
+.LP
+When \fIsubtree\fP or one of its descendants acquires the X input focus
+or the pointer moves into the subtree such that keyboard events would
+now be delivered to the subtree, a
+.PN FocusIn
+event is generated for the descendant if
+.PN FocusChange
+events have been selected by the descendant.
+Similarly, when \fIsubtree\fP loses the X input focus
+or the keyboard focus for one of its ancestors, a
+.PN FocusOut
+event is generated for descendant if
+.PN FocusChange
+events have been selected by the descendant.
+.sp
+.LP
+A widget tree may also actively manage the X server input focus.  To
+do so, a widget class specifies an accept_focus procedure.
+.LP
+.IN "accept_focus procedure"
+The accept_focus procedure pointer is of type
+.PN XtAcceptFocusProc .
+.LP
+.IN "XtAcceptFocusProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtAcceptFocusProc)(Widget, Time*);
+.br
+      Widget \fIw\fP;
+.br
+      Time *\fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fItime\fP 1i
+Specifies the X time of the event causing the accept focus.
+.LP
+.eM
+Widgets that need the input focus can call
+.PN XSetInputFocus
+explicitly, pursuant to the restrictions of the \fI\*(xC\fP.
+To allow outside agents, such as the parent,
+to cause a widget to take the input focus,
+every widget exports an accept_focus procedure.
+The widget returns a value indicating
+whether it actually took the focus or not,
+so that the parent can give the focus to another widget.
+Widgets that need to know when they lose the input focus must use
+the Xlib focus notification mechanism explicitly
+(typically by specifying translations for
+.PN FocusIn
+and
+.PN FocusOut
+events).
+Widgets classes that never want the input focus should set the
+\fIaccept_focus\fP field to NULL.
+.sp
+.LP
+To call a widget's accept_focus procedure, use
+.PN XtCallAcceptFocus .
+.LP
+.IN "XtCallAcceptFocus" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP)
+.br
+       Widget \fIw\fP;
+.br
+       Time *\fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.IP \fItime\fP 1i
+Specifies the X time of the event that is causing the focus change.
+.LP
+.eM
+The
+.PN XtCallAcceptFocus
+function calls the specified widget's accept_focus procedure,
+passing it the specified widget and time, and returns what the accept_focus
+procedure returns.
+If \fIaccept_focus\fP is NULL,
+.PN XtCallAcceptFocus
+returns
+.PN False .
+
+.NH 3
+Events for Drawables That Are Not a Widget's Window
+.XS 
+\fB\*(SN Events for Drawables That Are Not a Widget's Window\fP
+.XE
+.LP
+Sometimes an application must handle events for drawables that are not
+associated with widgets in its widget tree.  Examples include handling
+.PN GraphicsExpose
+and
+.PN NoExpose
+events on Pixmaps, and handling 
+.PN PropertyNotify
+events on the root window.
+.LP
+To register a drawable with the \*(xI event dispatching, use
+.PN XtRegisterDrawable .
+.LP
+.IN "XtRegisterDrawable" "" "@DEF@"
+.sM
+.FD 0
+void XtRegisterDrawable(\fIdisplay\fP, \fIdrawable\fP, \fIwidget\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      Drawable \fIdrawable\fP;
+.br
+      Widget \fIwidget\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the drawable's display.
+.IP \fIdrawable\fP 1i
+Specifies the drawable to register.
+.IP \fIwidget\fP 1i
+Specifies the widget to register the drawable for.
+.LP
+.eM
+.PN XtRegisterDrawable
+associates the specified drawable with the specified widget
+so that future calls to
+.PN XtWindowToWidget
+with the drawable will return the widget.
+The default event dispatcher will dispatch future events that
+arrive for the drawable to the widget in the same manner as
+events that contain the widget's window.
+.LP
+If the drawable is already registered with another widget, or if the
+drawable is the window of a widget in the client's widget tree, the
+results of calling
+.PN XtRegisterDrawable
+are undefined.
+
+.LP
+To unregister a drawable with the Intrinsics event dispatching, use
+.PN XtUnregisterDrawable .
+.LP
+.IN "XtUnregisterDrawable" "" "@DEF@"
+.sM
+.FD 0
+void XtUnregisterDrawable(\fIdisplay\fP, \fIdrawable\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      Drawable \fIdrawable\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the drawable's display.
+.IP \fIdrawable\fP 1i
+Specifies the drawable to unregister.
+.LP
+.eM
+.PN XtUnregisterDrawable
+removes an association created with 
+.PN XtRegisterDrawable .  
+If the drawable is the window of a widget in the client's widget tree
+the results of calling 
+.PN XtUnregisterDrawable
+are undefined.
+
+.NH 2
+Querying Event Sources
+.XS
+\fB\*(SN Querying Event Sources\fP
+.XE
+.LP
+The event manager provides several functions to examine and read events
+(including file and timer events) that are in the queue.
+The next three functions are \*(xI equivalents of the
+.PN XPending ,
+.PN XPeekEvent ,
+and
+.PN XNextEvent
+Xlib calls.
+.sp
+.LP
+.IN "Events"
+To determine if there are any events on the input queue for a given application,
+use
+.PN XtAppPending .
+.LP
+.IN "XtAppPending" "" "@DEF@"
+.sM
+.FD 0
+XtInputMask XtAppPending(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application to check.
+.LP
+.eM
+The
+.PN XtAppPending
+function returns a nonzero value if there are
+events pending from the X server, timer pending, other input sources
+pending, or signal sources pending.  The
+value returned is a bit mask that is the OR of
+.PN XtIMXEvent ,
+.PN XtIMTimer ,
+.PN XtIMAlternateInput ,
+and 
+.PN XtIMSignal 
+(see
+.PN XtAppProcessEvent ).
+If there are no events pending, 
+.PN XtAppPending
+flushes the output buffers of each Display in the application context
+and returns zero.
+.sp
+.LP
+To return the event from the head of a given application's input queue
+without removing input from the queue, use
+.PN XtAppPeekEvent .
+.LP
+.IN "XtAppPeekEvent" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If there is an X event in the queue,
+.PN XtAppPeekEvent
+copies it into \fIevent_return\fP and returns
+.PN True .
+If no X input is on the queue,
+.PN XtAppPeekEvent
+flushes the output buffers of each Display in the application context
+and blocks until some input is available
+(possibly calling some timeout callbacks in the interim).
+If the next available input is an X event,
+.PN XtAppPeekEvent
+fills in \fIevent_return\fP and returns
+.PN True .
+Otherwise, the input is for an input source
+registered with
+.PN XtAppAddInput ,
+and
+.PN XtAppPeekEvent
+returns
+.PN False .
+.FS
+The sample implementations provides XtAppPeekEvent as described.  Timeout callbacks
+are called while blocking for input.  If some input for an input source is
+available, 
+.PN XtAppPeekEvent
+will return 
+.PN True
+without returning an event.
+.FE
+.sp
+.LP
+To remove and return the event
+from the head of a given application's X event queue,
+use
+.PN XtAppNextEvent .
+.LP
+.IN "XtAppNextEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If the X event queue is empty,
+.PN XtAppNextEvent
+flushes the X output buffers of each Display in the application context
+and waits for an X event while looking at the other input sources
+and timeout values and calling any callback procedures triggered by them.
+This wait time can be used for background processing;
+see Section 7.8.
+
+.NH 2
+Dispatching Events
+.XS
+\fB\*(SN Dispatching Events\fP
+.XE
+.LP
+The \*(xI provide functions that dispatch events
+to widgets or other application code.
+Every client interested in X events on a widget uses
+.PN XtAddEventHandler
+to register which events it is
+interested in and a procedure (event handler) to be called
+when the event happens in that window.
+The translation manager automatically registers event handlers for widgets
+that use translation tables; see Chapter 10.
+.sp
+.LP
+Applications that need direct control of the processing of different types
+of input should use
+.PN XtAppProcessEvent .
+.LP
+.IN "XtAppProcessEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtInputMask \fImask\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the
+application for which to process input.
+.IP \fImask\fP 1i
+Specifies what types of events to process.
+The mask is the bitwise inclusive OR of any combination of
+.PN XtIMXEvent ,
+.PN XtIMTimer ,
+.PN XtIMAlternateInput ,
+and
+.PN XtIMSignal .
+As a convenience,
+.PN Intrinsic.h
+defines the symbolic name
+.PN XtIMAll
+to be the bitwise inclusive OR of these four event types.
+.LP
+.eM
+The
+.PN XtAppProcessEvent
+function processes one timer, input source, signal source, or X event.
+If there is no event or input of the appropriate type to process, then
+.PN XtAppProcessEvent
+blocks until there is.
+If there is more than one type of input available to process,
+it is undefined which will get processed.
+Usually, this procedure is not called by client applications; see
+.PN XtAppMainLoop .
+.PN XtAppProcessEvent
+processes timer events by calling any appropriate timer callbacks,
+input sources by calling any appropriate input callbacks, 
+signal source by calling any appropriate signal callbacks,
+and X events by
+calling
+.PN XtDispatchEvent .
+.LP
+When an X event is received,
+it is passed to
+.PN XtDispatchEvent ,
+which calls the appropriate event handlers
+and passes them the widget, the event, and client-specific data
+registered with each procedure.
+If no handlers for that event are registered,
+the event is ignored and the dispatcher simply returns.
+
+.sp
+.LP
+To dispatch an event returned by
+.PN XtAppNextEvent ,
+retrieved directly from the Xlib queue, or synthetically constructed,
+to any registered event filters or event handlers, call
+.PN XtDispatchEvent .
+.LP
+.IN "XtDispatchEvent" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtDispatchEvent(\fIevent\fP)
+.br
+      XEvent *\fIevent\fP;
+.FN
+.IP \fIevent\fP 1i
+Specifies a pointer to the event structure to be dispatched
+to the appropriate event handlers.
+.LP
+.eM
+The
+.PN XtDispatchEvent
+function first calls
+.PN XFilterEvent
+with the \fIevent\fP and the window of the widget to which the
+\*(xI intend to dispatch the event, or the event window if
+the \*(xI would not dispatch the event to any handlers.
+If
+.PN XFilterEvent
+returns
+.PN True
+and the event activated a server grab as identified
+by a previous call to
+.PN XtGrabKey
+or
+.PN XtGrabButton ,
+.PN XtDispatchEvent
+calls
+.PN XtUngrabKeyboard
+or
+.PN XtUngrabPointer
+with the timestamp from the event and immediately returns
+.PN True .
+If
+.PN XFilterEvent
+returns
+.PN True
+and a grab was not activated,
+.PN XtDispatchEvent
+just immediately returns
+.PN True .
+Otherwise,
+.PN XtDispatchEvent
+sends the event to the event handler functions that
+have been previously registered with the dispatch routine.
+.PN XtDispatchEvent
+returns 
+.PN True
+if
+.PN XFilterEvent
+returned
+.PN True ,
+or if the event was dispatched to some handler, and
+.PN False
+if it found no handler to which to dispatch the event.
+.PN XtDispatchEvent
+records the last timestamp in any event that
+contains a timestamp (see
+.PN XtLastTimestampProcessed ),
+regardless of whether it was filtered or dispatched.
+If a modal cascade is active with \fIspring_loaded\fP
+.PN True ,
+and if the event is a remap event as defined by
+.PN XtAddGrab ,
+.PN XtDispatchEvent
+may dispatch the event a second time.  If it does so,
+.PN XtDispatchEvent
+will call
+.PN XFilterEvent
+again with the window of the spring-loaded widget prior to the second
+dispatch, and if
+.PN XFilterEvent
+returns
+.PN True ,
+the second dispatch will not be performed.
+
+.NH 2
+The Application Input Loop
+.XS
+\fB\*(SN The Application Input Loop\fP
+.XE
+.LP
+To process all input from a given application in a continuous loop,
+use the convenience procedure
+.PN XtAppMainLoop .
+.LP
+.IN "XtAppMainLoop" "" "@DEF@"
+.sM
+.FD 0
+void XtAppMainLoop(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.LP
+.eM
+The
+.PN XtAppMainLoop
+function first reads the next incoming X event by calling
+.PN XtAppNextEvent 
+and then dispatches the event to the appropriate registered procedure 
+by calling
+.PN XtDispatchEvent .
+This constitutes the main loop of \*(tk applications.
+There is nothing special about
+.PN XtAppMainLoop ;
+it simply calls
+.PN XtAppNextEvent
+and then
+.PN XtDispatchEvent
+in a conditional loop.
+At the bottom of the loop, it checks to see if the specified
+application context's destroy flag is set.
+If the flag is set, the loop breaks.
+The whole loop is enclosed between a matching
+.PN XtAppLock
+and 
+.PN XtAppUnlock .
+.LP
+Applications can provide their own version of this loop,
+which tests some global termination flag or tests that the number
+of top-level widgets is larger than zero before circling back to the call to
+.PN XtAppNextEvent .
+
+.NH 2
+Setting and Checking the Sensitivity State of a Widget
+.XS
+\fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP
+.XE
+.LP
+Many widgets have a mode in which they assume a different appearance
+(for example, are grayed out or stippled), do not respond to user events,
+and become dormant.
+.LP
+When dormant,
+a widget is considered to be insensitive.
+If a widget is insensitive,
+the event manager does not dispatch any events to the widget
+with an event type of
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+.PN ButtonRelease ,
+.PN MotionNotify ,
+.PN EnterNotify ,
+.PN LeaveNotify ,
+.PN FocusIn ,
+or
+.PN FocusOut .
+.LP
+A widget can be insensitive because its \fIsensitive\fP field is
+.PN False
+or because one of its ancestors is insensitive and thus the widget's
+\fIancestor_sensitive\fP field also is 
+.PN False .
+A widget can but does not need to distinguish these two cases visually.
+.NT
+Pop-up shells will have
+\fIancestor_sensitive\fP
+.PN False
+if the parent was insensitive when the shell
+was created.  Since
+.PN XtSetSensitive
+on the parent will not
+modify the resource of the pop-up child, clients are advised to include
+a resource specification of the form
+``*TransientShell.ancestorSensitive: True''
+in the application defaults resource file or to
+otherwise ensure that the parent is
+sensitive when creating pop-up shells.
+.NE
+.sp
+.LP
+To set the sensitivity state of a widget, use
+.PN XtSetSensitive .
+.LP
+.IN "XtSetSensitive" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSensitive(\fIw\fP, \fIsensitive\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Boolean \fIsensitive\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIsensitive\fP 1i
+Specifies whether the widget should receive
+keyboard, pointer, and focus events.
+.LP
+.eM
+The
+.PN XtSetSensitive
+function first calls
+.PN XtSetValues
+on the current widget with an argument list specifying the
+XtNsensitive resource and the new value.
+If \fIsensitive\fP is
+.PN False
+and the widget's class is a subclass of
+Composite,
+.PN XtSetSensitive
+recursively propagates the new value
+down the child tree by calling
+.PN XtSetValues
+on each child to set \fIancestor_sensitive\fP to
+.PN False .
+If \fIsensitive\fP is
+.PN True
+and the widget's class is a subclass of
+Composite
+and the widget's \fIancestor_sensitive\fP field is
+.PN True ,
+.PN XtSetSensitive
+sets the \fIancestor_sensitive\fP of each child to
+.PN True
+and then recursively calls
+.PN XtSetValues
+on each normal descendant that is now sensitive to set
+\fIancestor_sensitive\fP to
+.PN True .
+.LP
+.PN XtSetSensitive
+calls
+.PN XtSetValues
+to change the \fIsensitive\fP and \fIancestor_sensitive\fP fields
+of each affected widget.
+Therefore, when one of these changes,
+the widget's set_values procedure should
+take whatever display actions are needed
+(for example, graying out or stippling the widget).
+.LP
+.PN XtSetSensitive
+maintains the invariant that, if the parent has either \fIsensitive\fP 
+or \fIancestor_sensitive\fP 
+.PN False ,
+then all children have \fIancestor_sensitive\fP 
+.PN False .
+.sp
+.LP
+To check the current sensitivity state of a widget,
+use
+.PN XtIsSensitive .
+.LP
+.IN "XtIsSensitive" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtIsSensitive(\fIw\fP)
+.br
+     Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the object.  \*(oI
+.LP
+.eM
+The
+.PN XtIsSensitive
+function returns 
+.PN True 
+or 
+.PN False 
+to indicate whether user input events are being dispatched.
+If object's class is a subclass of RectObj and
+both \fIsensitive\fP and \fIancestor_sensitive\fP are 
+.PN True ,
+.PN XtIsSensitive
+returns 
+.PN True ;
+otherwise, it returns 
+.PN False .
+
+.NH 2
+Adding Background Work Procedures
+.XS
+\fB\*(SN Adding Background Work Procedures\fP
+.XE
+.LP
+The \*(xI have some limited support for background processing.
+Because most applications spend most of their time waiting for input, 
+you can register an idle-time work procedure
+that is called when the toolkit would otherwise block in
+.PN XtAppNextEvent
+or
+.PN XtAppProcessEvent .
+Work procedure pointers are of type
+.PN XtWorkProc .
+.LP
+.IN "XtWorkProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtWorkProc)(XtPointer);
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIclient_data\fP 1i
+Passes the client data specified when the work procedure was registered.
+.LP
+.eM
+This procedure should return
+.PN True
+when it is done to indicate that it
+should be removed.
+If the procedure returns
+.PN False ,
+it will remain registered and called again when the
+application is next idle.
+Work procedures should be very judicious about how much they do. 
+If they run for more than a small part of a second,
+interactive feel is likely to suffer.
+.sp
+.LP
+To register a work procedure for a given application, use
+.PN XtAppAddWorkProc .
+.LP
+.IN "XtAppAddWorkProc" "" "@DEF@"
+.sM
+.FD 0
+XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtWorkProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that identifies the application.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when the application is idle.
+.IP \fIclient_data\fP 1i
+Specifies the argument passed to the specified procedure
+when it is called.
+.LP
+.eM
+The
+.PN XtAppAddWorkProc
+function adds the specified work procedure for the application identified
+by \fIapp_context\fP
+and returns an opaque unique identifier for this work procedure.
+Multiple work procedures can be registered,
+and the most recently added one is always the one that is called.
+However, if a work procedure adds another work procedure, 
+the newly added one has lower priority than the current one.
+.sp
+.LP
+To remove a work procedure, either return 
+.PN True 
+from the procedure when it is called or use
+.PN XtRemoveWorkProc
+outside of the procedure.
+.LP
+.IN "XtRemoveWorkProc" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveWorkProc(\fIid\fP)
+.br
+      XtWorkProcId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies which work procedure to remove.
+.LP
+.eM
+The
+.PN XtRemoveWorkProc
+function explicitly removes the specified background work procedure.
+
+.NH 2
+X Event Filters
+.XS
+\*(SN X Event Filters
+.XE
+.LP
+The event manager provides filters that can be applied to
+specific X events.
+The filters, which screen out events that are redundant or are temporarily
+unwanted, handle
+pointer motion compression,
+enter/leave compression, and
+exposure compression.
+
+.NH 3
+Pointer Motion Compression
+.XS
+\*(SN Pointer Motion Compression
+.XE
+.LP
+Widgets can have a hard time keeping up with a rapid stream of
+pointer motion events.  Furthermore,
+they usually do not care about every motion event.  To throw out
+redundant motion events, the widget class field \fIcompress_motion\fP should be
+.PN True .
+.IN "compress_motion field"
+When a request for an event would return a motion event,
+the \*(xI check if there are any other motion events
+for the same widget immediately
+following the current one and, if so, skip all but the last of them.
+
+.NH 3
+Enter/Leave Compression
+.XS
+\*(SN Enter/Leave Compression
+.XE
+.LP
+To throw out pairs of enter and leave events that have no intervening events,
+as can happen when the user moves the pointer across a widget 
+without stopping in it,
+the widget class field \fIcompress_enterleave\fP should be 
+.PN True .
+.IN "compress_enterleave field"
+These enter and leave events are not delivered to the client
+if they are found together in the input queue.
+
+.NH 3
+Exposure Compression
+.XS
+\*(SN Exposure Compression
+.XE
+.LP
+.IN "compress_expose field"
+Many widgets prefer to process a series of exposure events as a
+single expose region rather than as individual rectangles.  Widgets
+with complex displays might use the expose region as a clip list
+in a graphics context, and widgets with simple displays might
+ignore the region entirely and redisplay their whole window or
+might get the bounding box from the region and redisplay only that
+rectangle.
+.LP
+In either case, these widgets do not care about getting partial exposure events.
+The \fIcompress_exposure\fP field in the widget class
+structure specifies the type and number of exposure events that are
+dispatched to the widget's expose procedure.  This field must be
+initialized to one of the following values:
+.sp
+.sM
+.Ds 0
+.TA 3i
+.ta 3i
+#define XtExposeNoCompress	((XtEnum)False)
+#define XtExposeCompressSeries	((XtEnum)True)
+#define XtExposeCompressMultiple	<implementation-defined>
+#define XtExposeCompressMaximal	<implementation-defined>
+.De
+.LP
+.eM
+optionally ORed with any combination of the following flags (all with
+implementation-defined values):
+.PN XtExposeGraphicsExpose ,
+.PN XtExposeGraphicsExposeMerged ,
+.PN XtExposeNoExpose ,
+and
+.PN XtExposeNoRegion .
+
+.LP
+If the \fIcompress_exposure\fP field in the widget class structure does not
+specify
+.PN XtExposeNoCompress ,
+the event manager calls the widget's expose procedure only
+once for a series of exposure events.
+In this case, all
+.PN Expose
+or
+.PN GraphicsExpose
+events are accumulated into a region.
+When the final event is received,
+the event manager replaces the rectangle in the event with the
+bounding box for the region
+and calls the widget's expose procedure,
+passing the modified exposure event and (unless 
+.PN XtExposeNoRegion
+is specified) the region.
+For more information on regions, see Section 16.5 in \fI\*(xL\fP.)
+.LP
+The values have the following interpretation:
+.sp
+.LP
+.PN XtExposeNoCompress
+.IN "XtExposeNoCompress" "" "@DEF@"
+.IP
+No exposure compression is performed; every selected event is
+individually dispatched to the expose procedure with a \fIregion\fP
+argument of NULL.
+.sp
+.LP
+.PN XtExposeCompressSeries
+.IN "XtExposeCompressSeries" "" "@DEF@"
+.IP
+Each series of exposure events is coalesced into a single event,
+which is dispatched
+when an exposure event with count equal to zero is reached.
+.sp
+.LP
+.PN XtExposeCompressMultiple
+.IN "XtExposeCompressMultiple" "" "@DEF@"
+.IP
+Consecutive series of exposure events are coalesced into a single
+event, which is dispatched
+when an exposure event with count equal to zero is reached and either
+the event queue is empty or the next event is not an exposure event
+for the same widget.
+.sp
+.LP
+.PN XtExposeCompressMaximal
+.IN "XtExposeCompressMaximal" "" "@DEF"
+.IP
+All expose series currently in the queue for the widget
+are coalesced into a single
+event without regard to intervening nonexposure events.  If a
+partial series is in the end of the queue, the \*(xI will
+block until the end of the series is received.
+.sp
+.LP
+The additional flags have the following meaning:
+.sp
+.LP
+.PN XtExposeGraphicsExpose
+.IN "XtExposeGraphicsExpose" "" "@DEF@"
+.IP
+Specifies that
+.PN GraphicsExpose
+events are also to be dispatched to
+the expose procedure.
+.PN GraphicsExpose
+events are compressed, if specified, in the same manner as
+.PN Expose
+events.
+.sp
+.LP
+.PN XtExposeGraphicsExposeMerged
+.IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
+.IP
+Specifies in the case of
+.PN XtExposeCompressMultiple
+and
+.PN XtExposeCompressMaximal
+that series of
+.PN GraphicsExpose
+and
+.PN Expose
+events are to be compressed together, with the final event type
+determining the type of the event passed to the expose procedure.
+If this flag is not set, then only series of the same event type
+as the event at the head of the queue are coalesced.  This flag
+also implies
+.PN XtExposeGraphicsExpose .
+.sp
+.LP
+.PN XtExposeNoExpose
+.IN "XtExposeNoExpose" "" "@DEF@"
+.IP
+Specifies that
+.PN NoExpose
+events are also to be dispatched to the expose procedure.
+.PN NoExpose
+events are never coalesced with
+other exposure events or with each other.
+.sp
+.LP
+.PN XtExposeNoRegion
+.IN "XtExposeNoRegion" "" "@DEF"
+.IP
+Specifies that the final region argument passed to the expose
+procedure is NULL.  The rectangle in the event will still
+contain bounding box information for the entire series of
+compressed exposure events.  This option saves processing time when the
+region is not needed by the widget.
+
+.NH 2
+Widget Exposure and Visibility
+.XS
+\*(SN Widget Exposure and Visibility
+.XE
+.LP
+Every primitive widget and some composite widgets display data on the screen
+by means of direct Xlib calls.
+Widgets cannot simply write to the screen and forget what they have done.
+They must keep enough state to redisplay the window or parts
+of it if a portion is obscured and then reexposed.
+
+.NH 3
+Redisplay of a Widget: The expose Procedure
+.XS
+\*(SN Redisplay of a Widget: The expose Procedure
+.XE
+.IN "expose procedure"
+.LP
+The expose procedure pointer in a widget class is of type
+.PN XtExposeProc .
+.LP
+.IN "XtExposeProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtExposeProc)(Widget, XEvent*, Region);
+.br
+      Widget \fIw\fP;
+.br
+      XEvent *\fIevent\fP;
+.br
+      Region \fIregion\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget instance requiring redisplay.
+.IP \fIevent\fP 1i
+Specifies the exposure event giving the rectangle requiring redisplay.
+.IP \fIregion\fP 1i
+Specifies the union of all rectangles in this exposure sequence.
+.LP
+.eM
+The redisplay of a widget upon exposure is the responsibility of the
+expose procedure in the widget's class record.
+If a widget has no display semantics,
+it can specify NULL for the \fIexpose\fP field.
+Many composite widgets serve only as containers for their children
+and have no expose procedure.
+.NT
+If the \fIexpose\fP procedure is NULL,
+.PN XtRealizeWidget
+fills in a default bit gravity of
+.PN NorthWestGravity
+before it calls the widget's realize procedure.
+.NE
+.LP
+If the widget's \fIcompress_exposure\fP class field specifies
+.PN XtExposeNoCompress
+or 
+.PN XtExposeNoRegion ,
+or if the event type is
+.PN NoExpose
+(see Section 7.9.3),
+\fIregion\fP is NULL.  If
+.PN XtExposeNoCompress
+is not specified and the event type is not
+.PN NoExpose ,
+the event is the final event in the compressed series
+but \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP contain
+the bounding box for all the compressed events.
+The region is created and destroyed by the \*(xI, but
+the widget is permitted to modify the region contents.
+.LP
+A small simple widget (for example, Label) can ignore the bounding box
+information in the event and redisplay the entire window.
+A more complicated widget (for example, Text) can use the bounding box
+information to minimize the amount of calculation and redisplay it does.
+A very complex widget uses the region as a clip list in a GC and
+ignores the event information.
+The expose procedure is not chained and is therefore
+responsible for exposure of all superclass data
+as well as its own.
+.LP
+However,
+it often is possible to anticipate the display needs of several levels
+of subclassing.
+For example, rather than implement separate display procedures for
+the widgets Label, Pushbutton, and Toggle,
+you could write a single display routine in Label that uses display state
+fields like
+.LP
+.DS
+Boolean invert;
+Boolean highlight;
+Dimension highlight_width;
+.DE
+Label would have \fIinvert\fP and \fIhighlight\fP always 
+.PN False
+and \fIhighlight_width\fP zero.
+Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP, 
+but it would leave \fIinvert\fP always 
+.PN False .
+Finally, Toggle would dynamically set all three.
+In this case,
+the expose procedures for Pushbutton and Toggle inherit
+their superclass's expose procedure;
+see Section 1.6.10.
+
+.NH 3
+Widget Visibility
+.XS
+\*(SN Widget Visibility
+.XE
+.LP
+Some widgets may use substantial computing resources to produce the
+data they will display.
+However, this effort is wasted if the widget is not actually visible
+on the screen, that is, if the widget is obscured by another application 
+or is iconified.
+.LP
+.IN "Visibility"
+The \fIvisible\fP field in the
+core
+widget structure provides a hint to the widget that it need not compute
+display data.
+This field is guaranteed to be
+.PN True
+by the time an
+exposure
+event is processed if any part of the widget is visible,
+but is
+.PN False 
+if the widget is fully obscured.
+.LP
+Widgets can use or ignore the \fIvisible\fP hint.
+If they ignore it,
+they should have \fIvisible_interest\fP in their widget class record set 
+.PN False .
+In such cases,
+the \fIvisible\fP field is initialized 
+.PN True 
+and never changes.
+If \fIvisible_interest\fP is 
+.PN True ,
+the event manager asks for
+.PN VisibilityNotify
+events for the widget and sets \fIvisible\fP to
+.PN True
+on
+.PN VisibilityUnobscured
+or
+.PN VisibilityPartiallyObscured
+.IN VisibilityNotify
+events and
+.PN False
+on
+.PN VisibilityFullyObscured
+events.
+
+.NH 2
+X Event Handlers
+.XS
+\*(SN X Event Handlers
+.XE
+.LP
+Event handlers are procedures called when specified events
+occur in a widget.
+Most widgets need not use event handlers explicitly.
+Instead, they use the \*(xI translation manager.
+Event handler procedure pointers are of the type
+.PN XtEventHandler .
+.LP
+.IN "XtEventHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XEvent *\fIevent\fP;
+.br
+      Boolean *\fIcontinue_to_dispatch\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which the event arrived.
+.IP \fIclient_data\fP 1i
+Specifies any client-specific information registered with the event handler.
+.IP \fIevent\fP 1i
+Specifies the triggering event.
+.IP \fIcontinue_to_dispatch\fP 1i
+Specifies whether the remaining event
+handlers registered for the current event
+should be called.
+.LP
+.eM
+After receiving an event and before calling any event handlers, the
+Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
+.PN True .
+When an event handler is called, it may decide that further processing
+of the event is not desirable and may store
+.PN False
+in this Boolean, in
+which case any handlers remaining to be called for the event are
+ignored.
+.LP
+The circumstances under which the \*(xI may add event handlers
+to a widget are currently implementation-dependent.  Clients must
+therefore be aware that storing
+.PN False
+into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
+
+.NH 3
+Event Handlers That Select Events
+.XS
+\*(SN Event Handlers That Select Events
+.XE
+.LP
+To register an event handler procedure with the dispatch mechanism, use
+.PN XtAddEventHandler .
+.LP
+.IN "XtAddEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered.  \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the event handler.
+.LP
+.eM
+The
+.PN XtAddEventHandler
+function registers a procedure with the dispatch mechanism that is
+to be called when an event that matches the mask occurs on the specified
+widget.
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once regardless of
+the manner in which it is registered.
+If the procedure is already registered with the same \fIclient_data\fP
+value,
+the specified mask augments the existing mask.
+If the widget is realized,
+.PN XtAddEventHandler
+calls
+.PN XSelectInput ,
+if necessary.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+.sp
+.LP
+To remove a previously registered event handler, use
+.PN XtRemoveEventHandler .
+.LP
+.IN "XtRemoveEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this procedure is registered.  \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to unregister this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+removed on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be removed.
+.IP \fIclient_data\fP 1i
+Specifies the registered client data.
+.LP
+.eM
+The
+.PN XtRemoveEventHandler
+function unregisters an event handler registered with
+.PN XtAddEventHandler
+or
+.PN XtInsertEventHandler
+for the specified events.
+The request is ignored if \fIclient_data\fP does not match the value given
+when the handler was registered.
+If the widget is realized and no other event handler requires the event,
+.PN XtRemoveEventHandler
+calls
+.PN XSelectInput .
+If the specified procedure has not been registered 
+or if it has been registered with a different value of \fIclient_data\fP,
+.PN XtRemoveEventHandler
+returns without reporting an error.
+.LP
+To stop a procedure registered with
+.PN XtAddEventHandler
+or
+.PN XtInsertEventHandler
+from receiving all selected events, call
+.PN XtRemoveEventHandler
+with an \fIevent_mask\fP of
+.PN XtAllEvents
+and \fInonmaskable\fP 
+.PN True .
+The procedure will continue to receive any events
+that have been specified in calls to
+.PN XtAddRawEventHandler
+or
+.PN XtInsertRawEventHandler .
+.sp
+.LP
+To register an event handler procedure that receives events before or
+after all previously registered event handlers, use
+.PN XtInsertEventHandler .
+.LP
+.IN "XtListPosition" "" "@DEF@"
+.IN "XtInsertEventHandler" "" "@DEF@"
+.sM
+.Ds 0
+typedef enum {XtListHead, XtListTail} XtListPosition;
+.De
+.LP
+.FD 0
+void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtListPosition \fIposition\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered. \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the client's event handler.
+.IP \fIposition\fP 1i
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+.LP
+.eM
+.PN XtInsertEventHandler
+is identical to
+.PN XtAddEventHandler
+with the additional \fIposition\fP argument.  If \fIposition\fP is
+.PN XtListHead ,
+the event
+handler is registered so that it is called before any event
+handlers that were previously registered for the same widget.  If
+\fIposition\fP is
+.PN XtListTail ,
+the event handler is registered to be called
+after any previously registered event handlers.  If the procedure is
+already registered with the same \fIclient_data\fP value, the specified mask
+augments the existing mask and the procedure is repositioned in
+the list.
+
+.NH 3
+Event Handlers That Do Not Select Events
+.XS
+\*(SN Event Handlers That Do Not Select Events
+.XE
+.LP
+On occasion,
+clients need to register an event handler procedure with the
+dispatch mechanism without explicitly
+causing the X server to select for that event.
+To do this, use
+.PN XtAddRawEventHandler .
+.LP
+.IN "XtAddRawEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered. \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the client's event handler.
+.LP
+.eM
+The
+.PN XtAddRawEventHandler
+function is similar to
+.PN XtAddEventHandler 
+except that it does not affect the widget's event mask and never causes an
+.PN XSelectInput
+for its events.
+Note that the widget might already have those mask bits set
+because of other nonraw event handlers registered on it.
+If the procedure is already registered with the same \fIclient_data\fP,
+the specified mask augments the existing mask.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+.sp
+.LP
+To remove a previously registered raw event handler, use
+.PN XtRemoveRawEventHandler .
+.LP
+.IN "XtRemoveRawEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this procedure is registered.  \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to unregister this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+removed on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be registered.
+.IP \fIclient_data\fP 1i
+Specifies the registered client data.
+.LP
+.eM
+The
+.PN XtRemoveRawEventHandler
+function unregisters an event handler registered with
+.PN XtAddRawEventHandler
+or
+.PN XtInsertRawEventHandler
+for the specified events without changing
+the window event mask.
+The request is ignored if \fIclient_data\fP does not match the value given
+when the handler was registered.
+If the specified procedure has not been registered 
+or if it has been registered with a different value of \fIclient_data\fP,
+.PN XtRemoveRawEventHandler
+returns without reporting an error.
+.LP
+To stop a procedure
+registered with
+.PN XtAddRawEventHandler
+or
+.PN XtInsertRawEventHandler
+from receiving all nonselected events, call
+.PN XtRemoveRawEventHandler
+with an \fIevent_mask\fP of
+.PN XtAllEvents
+and \fInonmaskable\fP
+.PN True .
+The procedure
+will continue to receive any events that have been specified in calls to
+.PN XtAddEventHandler
+or
+.PN XtInsertEventHandler .
+.sp
+.LP
+To register an event handler procedure that receives events before or
+after all previously registered event handlers without selecting for
+the events, use
+.PN XtInsertRawEventHandler .
+.LP
+.IN "XtInsertRawEventHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
+\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+      Widget \fIw\fP;
+.br
+      EventMask \fIevent_mask\fP;
+.br
+      Boolean \fInonmaskable\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtListPosition \fIposition\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget for which this event handler is being registered. \*(cI
+.IP \fIevent_mask\fP 1i
+Specifies the event mask for which to call this procedure.
+.IP \fInonmaskable\fP 1i
+Specifies whether this procedure should be 
+called on the nonmaskable events
+.Pn ( GraphicsExpose ,
+.PN NoExpose ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+.PN ClientMessage ,
+and
+.PN MappingNotify ).
+.IP \fIproc\fP 1i
+Specifies the procedure to be registered.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the client's event handler.
+.IP \fIposition\fP 1i
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+.LP
+.eM
+The
+.PN XtInsertRawEventHandler
+function is similar to
+.PN XtInsertEventHandler
+except that it does not modify the widget's event
+mask and never causes an
+.PN XSelectInput
+for the specified events.  If
+the procedure is already registered with the same \fIclient_data\fP
+value, the
+specified mask augments the existing mask and the procedure is
+repositioned in the list.
+
+.NH 3
+Current Event Mask
+.XS
+\*(SN Current Event Mask
+.XE
+.LP
+To retrieve the event mask for a given widget, use
+.PN XtBuildEventMask .
+.LP
+.IN "XtBuildEventMask" "" "@DEF@"
+.sM
+.FD 0
+EventMask XtBuildEventMask(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+The
+.PN XtBuildEventMask
+function returns the event mask representing the logical OR
+of all event masks for event handlers registered on the widget with
+.PN XtAddEventHandler
+and
+.PN XtInsertEventHandler
+and all event translations, including accelerators,
+installed on the widget.
+This is the same event mask stored into the 
+.PN XSetWindowAttributes
+structure by
+.PN XtRealizeWidget
+and sent to the server when event handlers and translations are installed or
+removed on the realized widget.
+
+.NH 3
+Event Handlers for X11 Protocol Extensions
+.XS
+\fB\*(SN Event Handlers for X11 Protocol Extensions\fP
+.XE
+.LP
+To register an event handler procedure with the \*(xI dispatch
+mechanism according to an event type, use 
+.PN XtInsertEventTypeHandler .
+.LP
+.IN "XtInsertEventTypeHandler" "" "@DEF"
+.sM
+.FD 0
+void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
+\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      int \fIevent_type\fP;
+.br
+      XtPointer \fIselect_data\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtListPosition \fIposition\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for which this event handler is being registered.  \*(cI
+.IP \fIevent_type\fP 1i
+Specifies the event type for which to call this event handler.
+.IP \fIselect_data\fP 1i
+Specifies data used to request events of the specified type from the server,
+or NULL.
+.IP \fIproc\fP 1i
+Specifies the event handler to be called.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the event handler.
+.IP \fIposition\fP 1i
+Specifies when the event handler is to be called relative to other
+previously registered handlers.
+.LP
+.eM
+.PN XtInsertEventTypeHandler
+registers a procedure with the
+dispatch mechanism that is to be called when an event that matches the
+specified \fIevent_type\fP is dispatched to the specified \fIwidget\fP.  
+.LP
+If \fIevent_type\fP specifies one of the core X protocol events, then
+\fIselect_data\fP must be a pointer to a value of type 
+.PN EventMask ,
+indicating
+the event mask to be used to select for the desired event.  This event
+mask is included in the value returned by 
+.PN XtBuildEventMask .
+If the widget is realized,
+.PN XtInsertEventTypeHandler 
+calls 
+.PN XSelectInput
+if necessary.  Specifying NULL for \fIselect_data\fP is equivalent to
+specifying a pointer to an event mask containing 0.  This is similar
+to the 
+.PN XtInsertRawEventHandler
+function.  
+.LP
+If \fIevent_type\fP specifies an extension event type, then the semantics of
+the data pointed to by \fIselect_data\fP are defined by the extension
+selector registered for the specified event type.
+.LP
+In either case the \*(xI are not required to copy the data
+pointed to by \fIselect_data\fP, so the caller must ensure that it remains
+valid as long as the event handler remains registered with this value
+of \fIselect_data\fP.
+.LP
+The \fIposition\fP argument allows the client to control the order of
+invocation of event handlers registered for the same event type.  If
+the client does not care about the order, it should normally specify
+.PN XtListTail ,
+which registers this event handler after any previously
+registered handlers for this event type.
+.LP
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once if it is
+registered with 
+.PN XtInsertEventTypeHandler ,
+regardless of the manner
+in which it is registered and regardless of the value(s)
+of \fIselect_data\fP.  If the procedure is already registered with the
+same \fIclient_data\fP value, the specified mask augments the existing
+mask and the procedure is repositioned in the list.
+.sp
+.LP
+To remove an event handler registered with 
+.PN XtInsertEventTypeHandler ,
+use
+.PN XtRemoveEventTypeHandler .
+.LP
+.IN "XtRemoveEventTypeHandler" "" "@DEF"
+.sM
+.FD 0
+void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
+\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      int \fIevent_type\fP;
+.br
+      XtPointer \fIselect_data\fP;
+.br
+      XtEventHandler \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget for which the event handler was registered.  \*(cI
+.IP \fIevent_type\fP 1i
+Specifies the event type for which the handler was registered.
+.IP \fIselect_data\fP 1i
+Specifies data used to deselect events of the specified type 
+from the server, or NULL.
+.IP \fIproc\fP 1i
+Specifies the event handler to be removed.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data with which the procedure was registered.
+.LP
+.eM
+The
+.PN XtRemoveEventTypeHandler
+function unregisters an event handler
+registered with
+.PN XtInsertEventTypeHandler
+for the specified event type.
+The request is ignored if \fIclient_data\fP does not match the value given
+when the handler was registered.
+.LP
+If \fIevent_type\fP specifies one of the core X protocol events,
+\fIselect_data\fP must be a pointer to a value of type 
+.PN EventMask, indicating the event
+mask to be used to deselect for the appropriate event.  If the widget
+is realized, 
+.PN XtRemoveEventTypeHandler
+calls
+.PN XSelectInput
+if necessary.
+Specifying NULL for \fIselect_data\fP is equivalent to specifying a pointer
+to an event mask containing 0.  This is similar to the
+.PN XtRemoveRawEventHandler
+function.
+.LP
+If \fIevent_type\fP specifies an extension event type, then the semantics of
+the data pointed to by \fIselect_data\fP are defined by the extension
+selector registered for the specified event type.
+.sp
+.LP
+To register a procedure to select extension events for a widget, use
+.PN XtRegisterExtensionSelector .
+.LP
+.IN "XtRegisterExtensionSelector" "" "@DEF@"
+.sM
+.FD 0
+void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \
+\fImax_event_type\fP, \fIproc\fP,
+                                                     \fIclient_data\fP)
+.br
+      Display \fI*display\fP;
+.br
+      int \fImin_event_type\fP;
+.br
+      int \fImax_event_type\fP;
+.br
+      XtExtensionSelectProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIdisplay\fP 1.5i
+Specifies the display for which the extension selector is to be registered.
+.IP \fImin_event_type\fP
+.IP \fImax_event_type\fP 1.5i
+Specifies the range of event types for the extension.
+.IP \fIproc\fP 1.5i
+Specifies the extension selector procedure.
+.IP \fIclient_data\fP 1.5i
+Specifies additional data to be passed to the extension selector.
+.LP
+.eM
+The
+.PN XtRegisterExtensionSelector
+function registers a procedure to arrange 
+for the delivery of extension events to widgets.
+.LP
+If \fImin_event_type\fP and \fImax_event_type\fP match the parameters
+to a previous call to
+.PN XtRegisterExtensionSelector
+for the same \fIdisplay\fP, then \fIproc\fP and \fIclient_data\fP
+replace the previously
+registered values.  If the range specified by \fImin_event_type\fP
+and \fImax_event_type\fP overlaps the range of the parameters to a
+previous call for the same display in any other way, an error results.
+.LP
+When a widget is realized, 
+after the \fIcore.realize\fP method is called,
+the \*(xI check to see if any event
+handler specifies an event type within the range of a registered
+extension selector.  If so, the \*(xI call each such selector.
+If an event type handler is added or removed, the \*(xI check to
+see if the event type falls within the range of a registered extension
+selector, and if it does, calls the selector.  In either case the \*(xI
+pass a list of all the widget's event types that are within the
+selector's range.  The corresponding select data are also passed.  The
+selector is responsible for enabling the delivery of extension events
+required by the widget.
+.sp
+.LP
+An extension selector is of type
+.PN XtExtensionSelectProc .
+.LP
+.IN "XtExtensionSelectProc" "" "@DEF"
+.sM
+.FD 0
+typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \
+XtPointer);
+.br
+      Widget \fIwidget\fP;
+.br
+      int *\fIevent_types\fP;
+.br
+      XtPointer *\fIselect_data\fP;
+.br
+      int \fIcount\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget that is being realized or is having
+an event handler added or removed.
+.IP \fIevent_types\fP 1i
+Specifies a list of event types that the widget has
+registered event handlers for.
+.IP \fIselect_data\fP 1i
+Specifies a list of the select_data parameters specified in
+.PN XtInsertEventTypeHandler .
+.IP \fIcount\fP 1i
+Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP
+lists.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data with which the procedure was registered.
+.LP
+.eM
+The \fIevent_types\fP and \fIselect_data\fP lists will always have the
+same number of elements, specified by \fIcount\fP.  
+Each event type/select data pair represents one call to
+.PN XtInsertEventTypeHandler .
+.sp
+.LP
+To register a procedure to dispatch events of a specific type within
+.PN XtDispatchEvent ,
+use
+.PN XtSetEventDispatcher .
+.LP
+.IN "XtSetEventDispatcher" "" "@DEF@"
+.sM
+.FD 0
+XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \
+\fIproc\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      int \fIevent_type\fP;
+.br
+      XtEventDispatchProc \fIproc\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display for which the event dispatcher is to be registered.
+.IP \fIevent_type\fP 1i
+Specifies the event type for which the dispatcher should be invoked.
+.IP \fIproc\fP 1i
+Specifies the event dispatcher procedure.
+.LP
+.eM
+The 
+.PN XtSetEventDispatcher
+function registers the event dispatcher procedure specified by \fIproc\fP
+for events with the type \fIevent_type\fP.  The previously registered
+dispatcher (or the default dispatcher if there was no previously registered
+dispatcher) is returned.  If \fIproc\fP is NULL, the default procedure is
+restored for the specified type.
+.LP
+In the future, when
+.PN XtDispatchEvent
+is called with an event type of \fIevent_type\fP, the specified \fIproc\fP
+(or the default dispatcher) is invoked to determine a widget
+to which to dispatch the event. 
+.LP
+The default dispatcher handles the \*(xI modal cascade and keyboard
+focus mechanisms, handles the semantics of \fIcompress_enterleave\fP
+and \fIcompress_motion\fP, and discards all extension events.
+.sp
+.LP
+An event dispatcher procedure pointer is of type
+.PN XtEventDispatchProc .
+.LP
+.IN "XtEventDispatchProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtEventDispatchProc)(XEvent*)
+.br
+      XEvent *\fIevent\fP;
+.FN
+.IP \fIevent\fP 1i
+Passes the event to be dispatched.
+.LP
+.eM
+The event dispatcher procedure should determine whether this event is of
+a type that should be dispatched to a widget.  
+.LP
+If the event should be dispatched to a widget, the event dispatcher
+procedure should determine the appropriate widget to receive the
+event, call 
+.PN XFilterEvent
+with the window of this widget, or
+.PN None
+if the event is to be discarded, and if
+.PN XFilterEvent
+returns
+.PN False ,
+dispatch the event to the widget using
+.PN XtDispatchEventToWidget .
+The procedure should return
+.PN True
+if either
+.PN XFilterEvent
+or
+.PN XtDispatchEventToWidget
+returned
+.PN True
+and
+.PN False
+otherwise.
+.LP
+If the event should not be dispatched to a widget, the event
+dispatcher procedure should attempt to dispatch the event elsewhere as
+appropriate and return
+.PN True
+if it successfully dispatched the event and
+.PN False
+otherwise.
+.sp
+.LP
+Some dispatchers for extension events may wish to forward events
+according to the Intrinsics' keyboard focus mechanism.  To determine
+which widget is the end result of keyboard event forwarding, use
+.PN XtGetKeyboardFocusWidget .
+.LP
+.IN "XtGetKeyboardFocusWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtGetKeyboardFocusWidget(\fIwidget\fP)
+.br
+      Widget \fIwidget\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget to get forwarding information for.
+.LP
+.eM
+The
+.PN XtGetKeyboardFocusWidget 
+function returns the widget that would be the end result of keyboard
+event forwarding for a keyboard event for the specified widget.
+.sp
+.LP
+To dispatch an event to a specified widget, use
+.PN XtDispatchEventToWidget .
+.LP
+.IN "XtDispatchEventToWidget" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      XEvent *\fIevent\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget to which to dispatch the event.
+.IP \fIevent\fP 1i
+Specifies a pointer to the event to be dispatched.
+.LP
+.eM
+The 
+.PN XtDispatchEventToWidget
+function scans the list of registered event handlers for the
+specified widget and calls each handler that has been registered
+for the specified event type, subject to the \fIcontinue_to_dispatch\fP
+value returned by each handler.
+The \*(xI behave as if event handlers were registered at the head
+of the list for
+.PN Expose ,
+.PN NoExpose ,
+.PN GraphicsExpose ,
+and
+.PN VisibilityNotify
+events to invoke the widget's expose procedure according to the exposure
+compression rules and to update the widget's \fIvisible\fP field
+if \fIvisible_interest\fP is
+.PN True .
+These internal event handlers never set \fIcontinue_to_dispatch\fP to
+.PN False .
+.LP
+.PN XtDispatchEventToWidget
+returns
+.PN True
+if any event handler was called and
+.PN False
+otherwise.
+
+.NH 2
+Using the \*(xI in a Multi-Threaded Environment
+.XS
+\*(SN Using the \*(xI in a Multi-Threaded Environment
+.XE
+.LP
+The \*(xI may be used in environments that offer multiple threads
+of execution within the context of a single process.  A multi-threaded 
+application using the \*(xI must explicitly initialize the toolkit 
+for mutually exclusive access by calling
+.PN XtToolkitThreadInitialize .
+
+.NH 3
+Initializing a Multi-Threaded \*(xI Application
+.XS
+\fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP
+.XE
+.LP
+To test and initialize \*(xI support for mutually exclusive thread
+access, call
+.PN XtToolkitThreadInitialize .
+.LP
+.IN "XtToolkitThreadInitialize" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtToolkitThreadInitialize()
+.FN
+.LP
+.eM
+.PN XtToolkitThreadInitialize
+returns \fBTrue\fP if the \*(xI support mutually exclusive thread 
+access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP
+must be called before
+.PN XtCreateApplicationContext ,
+.PN XtAppInitialize ,
+.PN XtOpenApplication ,
+or
+.PN XtSetLanguageProc
+is called. \fBXtToolkitThreadInitialize\fP may be called more than once;
+however, the application writer must ensure that it is not called 
+simultaneously by two or more threads.
+
+.NH 3
+Locking \*(tk Data Structures
+.XS
+\fB\*(SN Locking \*(tk Data Structures\fP
+.XE
+.LP
+The \*(xI employs two levels of locking: application context and
+process.  Locking an application context ensures mutually exclusive
+access by a thread to the state associated with the application context,
+including all displays and widgets associated with it.  Locking a
+process ensures mutually exclusive access by a thread to \*(xI process
+global data.
+.LP
+A client may acquire a lock multiple times and the effect is cumulative.
+The client must ensure that the lock is released an equal number of times in
+order for the lock to be acquired by another thread.
+.LP
+Most application writers will have little need to use locking as the
+\*(xI performs the necessary locking internally.
+Resource converters are an exception.
+They require the application context or process to be locked
+before the application can safely call them directly, for example:
+.LP
+.KS
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+	...
+	XtAppLock(app_context);
+	XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
+	XtAppUnlock(app_context);
+	...
+.De
+.KE
+.LP
+When the application relies upon
+.PN XtConvertAndStore
+or a converter to provide the storage for the results of a
+conversion, the application should acquire the process lock before
+calling out and hold the lock until the results have been copied.
+.LP
+Application writers who write their own
+utility functions, such as one which retrieves the being_destroyed field from
+a widget instance, must lock the application context before accessing
+widget internal data.  For example:
+.LP
+.KS
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+#include <X11/CoreP.h>
+Boolean BeingDestroyed (widget)
+	Widget widget;
+{
+	Boolean ret;
+	XtAppLock(XtWidgetToApplicationContext(widget));
+	ret = widget->core.being_destroyed;
+	XtAppUnlock(XtWidgetToApplicationContext(widget));
+	return ret;
+}
+.De
+.KE
+A client that wishes to atomically call two or more \*(xI functions 
+must lock the application context.  For example:
+.LP
+.KS
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+	...
+	XtAppLock(XtWidgetToApplicationContext(widget));
+	XtUnmanageChild (widget1);
+	XtManageChild (widget2);
+	XtAppUnlock(XtWidgetToApplicationContext(widget));
+	...
+.De
+.KE
+
+.NH 4
+Locking the Application Context
+.XS
+\fB\*(SN Locking the Application Context\fP
+.XE
+.LP
+To ensure mutual exclusion of application context, display, or 
+widget internal state, use
+.PN XtAppLock.
+.LP
+.IN "XtAppLock" "" "@DEF@"
+.sM
+.FD 0
+void XtAppLock(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context to lock.
+.LP
+.eM
+\fBXtAppLock\fP blocks until it is able to acquire the lock.  Locking the 
+application context also ensures that only the thread holding the lock 
+makes Xlib calls from within Xt.  An application that makes its own
+direct Xlib calls must either lock the application context around every 
+call or enable thread locking in Xlib.
+.LP
+To unlock a locked application context, use
+.PN XtAppUnlock.
+.LP
+.IN "XtAppUnlock" "" "@DEF@"
+.sM
+.FD 0
+void XtAppUnlock(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context that was previously locked.
+.LP
+.eM
+
+.NH 4
+Locking the Process
+.XS
+\*(SN Locking the Process
+.XE
+.LP
+To ensure mutual exclusion of \*(tk process global data, a
+widget writer must use
+.PN XtProcessLock.
+.LP
+.IN "XtProcessLock" "" "@DEF@"
+.sM
+.FD 0
+void XtProcessLock()
+.FN
+.LP
+.eM
+\fBXtProcessLock\fP blocks until it is able to acquire the lock.
+Widget writers may use XtProcessLock to guarantee mutually exclusive 
+access to widget static data.
+.LP
+To unlock a locked process, use
+.PN XtProcessUnlock .
+.LP
+.IN "XtProcessUnlock" "" "@DEF@"
+.sM
+.FD 0
+void XtProcessUnlock()
+.FN
+.LP
+.eM
+To lock both an application context and the process at the same 
+time, call
+.PN XtAppLock
+first and then
+.PN XtProcessLock .
+To release both locks, call
+.PN XtProcessUnlock
+first and then
+.PN XtAppUnlock .
+The order is important to avoid deadlock.
+
+.NH 3
+Event Management in a Multi-Threaded Environment
+.XS
+\fB\*(SN Event Management in a Multi-Threaded Environment\fP
+.XE
+.LP
+In a nonthreaded environment an application writer could reasonably
+assume that it is safe to exit the application from a quit callback. 
+This assumption may no longer hold true in a multi-threaded environment; 
+therefore it is desirable to provide a mechanism to terminate an
+event-processing loop without necessarily terminating its thread.
+.LP
+To indicate that the event loop should terminate after the current 
+event dispatch has completed, use
+.PN XtAppSetExitFlag .
+.LP
+.IN "XtAppSetExitFlag" "" "@DEF@"
+.sM
+.FD 0
+void XtAppSetExitFlag(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+.PN XtAppMainLoop
+tests the value of the flag and will return if the flag is \fBTrue\fP.
+.LP
+Application writers who implement their own main loop may test the 
+value of the exit flag with
+.PN XtAppGetExitFlag .
+.LP
+.IN "XtAppGetExitFlag" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtAppGetExitFlag(\fIapp_context\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+.PN XtAppGetExitFlag
+will normally return \fBFalse\fP, indicating that event processing
+may continue.  When
+.PN XtAppGetExitFlag
+returns \fBTrue\fP, the loop must terminate and return to the caller,
+which might then destroy the application context.
+.LP
+Application writers should be aware that, if a thread is blocked in 
+.PN XtAppNextEvent , 
+.PN XtAppPeekEvent , 
+or 
+.PN XtAppProcessEvent
+and another thread in the same application context opens a new display, 
+adds an alternate input, or a timeout, any new source(s) will not 
+normally be "noticed" by the blocked thread.  Any new sources are
+"noticed" the next time one of these functions is called.
+.LP
+The \*(xI manage access to events on a last-in, first-out basis.  If 
+multiple threads in the same application context block in
+.PN XtAppNextEvent , 
+.PN XtAppPeekEvent , 
+or 
+.PN XtAppProcessEvent ,
+the last thread to call one of these functions is the first
+thread to return.
+.bp
diff --git a/libXt/specs/CH08 b/libXt/specs/CH08
new file mode 100644
index 000000000..6dfb5290b
--- /dev/null
+++ b/libXt/specs/CH08
@@ -0,0 +1,452 @@
+.\" $Xorg: CH08,v 1.3 2000/08/17 19:42:46 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 8\fP\s-1
+
+\s+1\fBCallbacks\fP\s-1
+.sp 2
+.nr H1 8
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 8 \(em Callbacks
+.XE
+.IN "Destroy Callbacks"
+Applications and other widgets often need to register a procedure
+with a widget that gets called under certain prespecified conditions.
+For example,
+when a widget is destroyed,
+every procedure on the widget's \fIdestroy_callbacks\fP
+list is called to notify clients of the widget's impending doom.
+.LP
+Every widget has an XtNdestroyCallbacks callback list resource.
+Widgets can define additional callback lists as they see fit.
+For example, the Pushbutton widget has a callback
+list to notify clients when the button has been activated.
+.LP
+Except where otherwise noted, it is the intent that all Intrinsics
+functions may be called at any time, including from within callback
+procedures, action routines, and event handlers.
+
+.NH 2
+Using Callback Procedure and Callback List Definitions
+.XS
+\fB\*(SN Using Callback Procedure and Callback List Definitions\fP
+.XE
+.IN "XtCallbackList"
+.IN "XtCallbackProc"
+.LP
+Callback procedure pointers for use in callback lists are of type
+.PN XtCallbackProc .
+.LP
+.IN "XtCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget owning the list in which the callback is registered.
+.IP \fIclient_data\fP 1i
+Specifies additional data supplied by the client when the procedure
+was registered.
+.IP \fIcall_data\fP 1i
+Specifies any callback-specific data the widget wants to pass to the client.
+For example,  when Scrollbar executes its XtNthumbChanged callback list,
+it passes the new position of the thumb.
+.LP
+.eM
+The \fIclient_data\fP argument provides a way for the
+client registering the callback procedure also to register client-specific data,
+for example, a pointer to additional information about the widget, 
+a reason for invoking the callback, and so on.
+The \fIclient_data\fP value may be NULL
+if all necessary information is in the widget.
+The \fIcall_data\fP argument is a convenience to avoid having simple
+cases where the client could otherwise always call
+.PN XtGetValues
+or a widget-specific function to retrieve data from the widget.
+Widgets should generally avoid putting complex state information 
+in \fIcall_data\fP.
+The client can use the more general data retrieval methods, if necessary.
+.LP
+Whenever a client wants to pass a callback list as an argument in an
+.PN XtCreateWidget ,
+.PN XtSetValues ,
+or
+.PN XtGetValues
+call, it should specify the address
+of a NULL-terminated array of type
+.PN XtCallbackList .
+.IN "XtCallbackList" "" "@DEF@"
+.IN "XtCallbackRec" "" "@DEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XtCallbackProc callback;
+	XtPointer closure;
+} XtCallbackRec, *XtCallbackList;
+.De
+.LP
+.eM
+For example, the callback list for procedures A and B with client data
+clientDataA and clientDataB, respectively, is
+.LP
+.KS
+.Ds 5
+.TA .5i 3i
+.ta .5i 3i
+static XtCallbackRec callbacks[] = {
+	{A, (XtPointer) clientDataA},
+	{B, (XtPointer) clientDataB},
+	{(XtCallbackProc) NULL, (XtPointer) NULL}
+};
+.De
+.KE
+.LP
+Although callback lists are passed by address in arglists
+and varargs lists,
+the \*(xI recognize callback lists
+through the widget resource list and will copy the contents
+when necessary.
+Widget initialize and set_values procedures
+should not allocate memory for the callback list contents.
+The \*(xI automatically do this,
+potentially using a different structure for their
+internal representation.
+
+.NH 2
+Identifying Callback Lists
+.XS
+\fB\*(SN Identifying Callback Lists\fP
+.XE
+.LP
+Whenever a widget contains a callback list for use by clients, 
+it also exports in its public .h file the resource name of the callback list.
+Applications and client widgets never access callback list fields directly.
+Instead, they always identify the desired callback list by using the exported
+resource name.
+All the callback manipulation functions described in this chapter 
+except
+.PN XtCallCallbackList
+check 
+to see that the requested callback list is indeed implemented by the widget.
+.LP
+For the \*(xI to find and correctly handle callback lists,
+they must be declared with a resource type of
+.PN XtRCallback .
+The internal representation of a callback list is
+implementation-dependent; widgets may make no assumptions about the
+value stored in this resource if it is non-NULL.  Except to compare
+the value to NULL (which is equivalent to
+.PN XtCallbackStatus
+.PN XtCallbackHasNone ),
+access to callback list resources must be made
+through other \*(xI procedures.
+
+.NH 2
+Adding Callback Procedures
+.XS
+\fB\*(SN Adding Callback Procedures\fP
+.XE
+.LP
+To add a callback procedure to a widget's callback list, use
+.PN XtAddCallback .
+.LP
+.IN "XtAddCallback" "" "@DEF@"
+.sM
+.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.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list to which the procedure is to be appended.
+.IP \fIcallback\fP 1i
+Specifies the callback procedure.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the specified procedure
+when it is invoked,
+or NULL.
+.LP
+.eM
+A callback will be invoked as many times as it occurs in the callback list.
+.sp
+.LP
+To add a list of callback procedures to a given widget's callback list, use
+.PN XtAddCallbacks .
+.LP
+.IN "XtAddCallbacks" "" "@DEF@"
+.sM
+.FD 0
+void XtAddCallbacks(\fIw\fP, \fIcallback_name, \fP\fIcallbacks\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIcallback_name\fP;
+.br
+      XtCallbackList \fIcallbacks\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list to which the procedures are to be appended.
+.IP \fIcallbacks\fP 1i
+Specifies the null-terminated list of callback procedures and corresponding
+client data.
+.LP
+.eM
+.NH 2
+Removing Callback Procedures
+.XS
+\fB\*(SN Removing Callback Procedures\fP
+.XE
+.LP
+To delete a callback procedure from a widget's callback list, use
+.PN XtRemoveCallback .
+.LP
+.IN "XtRemoveCallback" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveCallback(\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.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list from which the procedure is to be deleted.
+.IP \fIcallback\fP 1i
+Specifies the callback procedure.
+.IP \fIclient_data\fP 1i
+Specifies the client data to match with the registered callback entry.
+.LP
+.eM
+The
+.PN XtRemoveCallback
+function removes a callback only if both the procedure and the client
+data match.
+.sp
+.LP
+To delete a list of callback procedures from a given widget's callback list, use
+.PN XtRemoveCallbacks .
+.LP
+.IN "XtRemoveCallbacks" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcallbacks\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIcallback_name\fP;
+.br
+      XtCallbackList \fIcallbacks\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list from which the procedures are to be deleted.
+.IP \fIcallbacks\fP 1i
+Specifies the null-terminated list of callback procedures and corresponding
+client data.
+.LP
+.eM
+To delete all callback procedures from a given widget's callback list
+and free all storage associated with the callback list, use
+.PN XtRemoveAllCallbacks .
+.LP
+.IN "XtRemoveAllCallbacks" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveAllCallbacks(\fIw\fP, \fIcallback_name\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIcallback_name\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list to be cleared.
+.LP
+.eM
+.NH 2
+Executing Callback Procedures
+.XS
+\*(SN Executing Callback Procedures
+.XE
+.LP
+To execute the procedures in a given widget's callback list,
+specifying the callback list by resource name, use
+.PN XtCallCallbacks .
+.LP
+.IN "XtCallCallbacks" "" "@DEF@"
+.sM
+.FD 0
+void XtCallCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcall_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIcallback_name\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list to be executed.
+.IP \fIcall_data\fP 1i
+Specifies a callback-list-specific data value to pass to each of the callback
+procedure in the list, or NULL.
+.LP
+.eM
+.LP
+.PN XtCallCallbacks
+calls each of the callback procedures in the list
+named by \fIcallback_name\fP in the specified widget, passing the client
+data registered with the procedure and \fIcall-data\fP.
+.sp
+.LP
+To execute the procedures in a callback list, specifying the callback
+list by address, use
+.PN XtCallCallbackList .
+.LP
+.IN "XtCallCallbackList" "" "@DEF@"
+.sM
+.FD 0
+void XtCallCallbackList(\fIwidget\fP, \fIcallbacks\fP, \fIcall_data\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      XtCallbackList \fIcallbacks\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget instance that contains the callback list.  \*(oI
+.IP \fIcallbacks\fP 1i
+Specifies the callback list to be executed.
+.IP \fIcall_data\fP 1i
+Specifies a callback-list-specific data value to pass
+to each of the callback procedures in the list, or NULL.
+.LP
+.eM
+The \fIcallbacks\fP parameter must specify the contents of a widget or
+object resource declared with representation type
+.PN XtRCallback .
+If \fIcallbacks\fP is NULL,
+.PN XtCallCallbackList
+returns immediately; otherwise it calls each of the callback
+procedures in the list, passing the client data and \fIcall_data\fP.
+
+.NH 2
+Checking the Status of a Callback List
+.XS
+\*(SN Checking the Status of a Callback List
+.XE
+.LP
+To find out the status of a given widget's callback list, use
+.PN XtHasCallbacks .
+.LP
+.IN "XtHasCallbacks" "" "@DEF@"
+.sp
+.sM
+.FD 0
+typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} \
+XtCallbackStatus;
+.sp
+XtCallbackStatus XtHasCallbacks(\fIw\fP, \fIcallback_name\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIcallback_name\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.IP \fIcallback_name\fP 1i
+Specifies the callback list to be checked.
+.LP
+.eM
+The
+.PN XtHasCallbacks
+function first checks to see if the widget has a callback list identified 
+by \fIcallback_name\fP.
+If the callback list does not exist,
+.PN XtHasCallbacks
+returns
+.PN XtCallbackNoList .
+If the callback list exists but is empty,
+it returns
+.PN XtCallbackHasNone .
+If the callback list exists and has at least one callback registered,
+it returns
+.PN XtCallbackHasSome .
+.bp
diff --git a/libXt/specs/CH09 b/libXt/specs/CH09
new file mode 100644
index 000000000..9538651bc
--- /dev/null
+++ b/libXt/specs/CH09
@@ -0,0 +1,3211 @@
+.\" $Xorg: CH09,v 1.3 2000/08/17 19:42:46 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 9\fP\s-1
+
+\s+1\fBResource Management\fP\s-1
+.sp 2
+.nr H1 9
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 9 \(em Resource Management
+.XE
+A resource is a field in the widget record with a corresponding
+resource entry in the \fIresources\fP list of the widget or any of its
+superclasses.
+This means that the field is
+settable by
+.PN XtCreateWidget
+(by naming the field in the argument list), by an
+entry in a resource file (by using either the name or class), and by
+.PN XtSetValues .
+In addition, it is readable by
+.PN XtGetValues .
+Not all fields in a widget record are resources.
+Some are for bookkeeping use by the
+generic routines (like \fImanaged\fP and \fIbeing_destroyed\fP).
+Others can be for local bookkeeping,
+and still others are derived from resources 
+(many graphics contexts and pixmaps).
+.LP
+Widgets typically need to obtain a large set of resources at widget
+creation time.
+Some of the resources come from the argument list supplied in the call to
+.PN XtCreateWidget ,
+some from the resource database,
+and some from the internal defaults specified by the widget.
+Resources are obtained first from the argument list,
+then from the resource database for all resources not specified
+in the argument list,
+and last, from the internal default, if needed.
+
+.NH 2
+Resource Lists
+.XS
+\*(SN Resource Lists
+.XE
+.LP
+.IN "Resource Management"
+A resource entry specifies a field in the widget,
+the textual name and class of the field that argument lists
+and external resource files use to refer to the field,
+and a default value that the field should get if no value is specified.
+The declaration for the
+.PN XtResource
+structure is
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String resource_name;
+	String resource_class;
+	String resource_type;
+	Cardinal resource_size;
+	Cardinal resource_offset;
+	String default_type;
+	XtPointer default_addr;
+} XtResource, *XtResourceList;
+.De
+.IN "XtResourceList"
+.eM
+
+.LP
+When the resource list is specified as the
+.PN CoreClassPart ,
+.PN ObjectClassPart ,
+.PN RectObjClassPart ,
+or
+.PN ConstraintClassPart
+\fIresources\fP field, the strings pointed to by \fIresource_name\fP,
+\fIresource_class\fP, \fIresource_type\fP, and \fIdefault_type\fP must
+be permanently allocated prior to or during the execution of the class
+initialization procedure and must not be subsequently deallocated.
+
+.LP
+The \fIresource_name\fP field contains the name used by clients to access the field
+in the widget.
+By convention, it starts with a lowercase letter
+and is spelled exactly like the field name,
+except all underscores (_) are deleted and the next letter is replaced by its 
+uppercase counterpart.
+For example, the resource name for background_pixel becomes backgroundPixel.
+Resource names beginning with the two-character
+sequence ``xt'', and resource classes beginning with the two-character
+sequence ``Xt'' are reserved to the \*(xI for future standard and
+implementation-dependent uses.
+Widget header files typically contain a symbolic name for each resource name.
+All resource names, classes, and types used by the \*(xI are named in
+.Pn < X11/StringDefs.h >.
+The \*(xI's symbolic resource names begin with
+``XtN''
+and are followed by the string name (for example, XtNbackgroundPixel
+for backgroundPixel).
+
+.LP
+The \fIresource_class\fP field contains the class string used in resource
+specification files to identify the field.
+A resource class provides two functions:
+.IP \(bu 5
+It isolates an application from different representations that widgets 
+can use for a similar resource.
+.IP \(bu 5
+It lets you specify values for several actual resources with a single name.
+A resource class should be chosen to span a group of closely related fields.
+.LP
+For example,
+a widget can have several pixel resources: background, foreground,
+border, block cursor, pointer cursor, and so on.
+Typically, the background defaults to white
+and everything else to black.
+The resource class for each of these resources in the resource list
+should be chosen so that it takes the minimal number of entries
+in the resource database to make the background ivory
+and everything else darkblue.
+.LP
+In this case, the background pixel should have a resource class of
+``Background''
+and all the other pixel entries a resource class of
+``Foreground''.
+Then, the resource file needs only two lines to
+change all pixels to ivory or darkblue:
+.LP
+.Ds 5
+.TA .5i 1.5i
+.ta .5i 1.5i
+*Background:	ivory
+*Foreground:	darkblue
+.De
+.LP
+Similarly, a widget may have several font resources (such as normal and bold),
+but all fonts should have the class Font.
+Thus, changing all fonts simply requires only a single line in the 
+default resource file:
+.LP
+.Ds 5
+.TA .5i 3i
+.ta .5i 3i
+*Font:	6x13
+.De
+.LP
+By convention,
+resource classes are always spelled starting with a capital letter
+to distinguish them from resource names.
+Their symbolic names are preceded with
+``XtC''
+(for example, XtCBackground).
+.LP
+The \fIresource_type\fP field gives the physical representation type of the resource
+and also encodes information about the specific usage of the field.
+By convention, it starts with an uppercase letter and is
+spelled identically to the type name of the field.
+The resource type is used when resources are fetched to
+convert from the resource database format (usually
+.PN String )
+or the format of the resource default value
+(almost anything, but often
+.PN String )
+to the desired
+physical representation (see Section 9.6).
+The \*(xI define the following resource types:
+.TS H
+lw(2.5i) lw(2.5i).
+_
+.sp 6p
+Resource Type	Structure or Field Type
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN XtRAcceleratorTable
+T}	XtAccelerators
+T{
+.PN XtRAtom
+T}	Atom
+T{
+.PN XtRBitmap
+T}	Pixmap, depth=1
+T{
+.PN XtRBoolean
+T}	Boolean
+T{
+.PN XtRBool
+T}	Bool
+T{
+.PN XtRCallback
+T}	XtCallbackList
+T{
+.PN XtRCardinal
+T}	Cardinal
+T{
+.PN XtRColor
+T}	XColor
+T{
+.PN XtRColormap
+T}	Colormap
+T{
+.PN XtRCommandArgArray
+T}	String*
+T{
+.PN XtRCursor
+T}	Cursor
+T{
+.PN XtRDimension
+T}	Dimension
+T{
+.PN XtRDirectoryString
+T}	String
+T{
+.PN XtRDisplay
+T}	Display*
+T{
+.PN XtREnum
+T}	XtEnum
+T{
+.PN XtREnvironmentArray
+T}	String*
+T{
+.PN XtRFile
+T}	FILE*
+T{
+.PN XtRFloat
+T}	float
+T{
+.PN XtRFont
+T}	Font
+T{
+.PN XtRFontSet
+T}	XFontSet
+T{
+.PN XtRFontStruct
+T}	XFontStruct*
+T{
+.PN XtRFunction
+T}	(*)()
+T{
+.PN XtRGeometry
+T}	T{
+char*, format as defined by
+.PN XParseGeometry
+T}
+T{
+.PN XtRGravity
+T}	int
+T{
+.PN XtRInitialState
+T}	int
+T{
+.PN XtRInt
+T}	int
+T{
+.PN XtRLongBoolean
+T}	long
+T{
+.PN XtRObject
+T}	Object
+T{
+.PN XtRPixel
+T}	Pixel
+T{
+.PN XtRPixmap
+T}	Pixmap
+T{
+.PN XtRPointer
+T}	XtPointer
+T{
+.PN XtRPosition
+T}	Position
+T{
+.PN XtRRestartStyle
+T}	unsigned char
+T{
+.PN XtRScreen
+T}	Screen*
+T{
+.PN XtRShort
+T}	short
+T{
+.PN XtRSmcConn
+T}	XtPointer
+T{
+.PN XtRString
+T}	String
+T{
+.PN XtRStringArray
+T}	String*
+T{
+.PN XtRStringTable
+T}	String*
+T{
+.PN XtRTranslationTable
+T}	XtTranslations
+T{
+.PN XtRUnsignedChar
+T}	unsigned char
+T{
+.PN XtRVisual
+T}	Visual*
+T{
+.PN XtRWidget
+T}	Widget
+T{
+.PN XtRWidgetClass
+T}	WidgetClass
+T{
+.PN XtRWidgetList
+T}	WidgetList
+T{
+.PN XtRWindow
+T}	Window
+.sp 6p
+_
+.TE
+.sp
+.LP
+.Pn < X11/StringDefs.h >
+also defines the following resource types as a
+convenience for widgets, although they do not have any corresponding
+data type assigned:
+.PN XtREditMode ,
+.PN XtRJustify ,
+and
+.PN XtROrientation .
+.LP
+The \fIresource_size\fP field is the size of the physical representation in bytes;
+you should specify it as
+.PN sizeof (\fItype\fP)
+so that the
+compiler fills in the value.
+The \fIresource_offset\fP field is the offset in bytes of the field 
+within the widget.
+You should use the
+.PN XtOffsetOf
+macro to retrieve this value.
+The \fIdefault_type\fP field is the representation type of the default
+resource value.
+If \fIdefault_type\fP is different from \fIresource_type\fP and the default value
+is needed,
+the resource manager invokes a conversion procedure from \fIdefault_type\fP
+to \fIresource_type\fP.
+Whenever possible,
+the default type should be identical to the resource type in order
+to minimize widget creation time.
+However, there are sometimes no values of the type that the program 
+can easily specify.
+In this case,
+it should be a value for which the converter is guaranteed to work (for example, 
+.PN XtDefaultForeground
+for a pixel resource).
+The \fIdefault_addr\fP field specifies the address of the default resource value.
+As a special case, if \fIdefault_type\fP is
+.PN XtRString ,
+then the value in the \fIdefault_addr\fP field is the pointer to
+the string rather than a pointer to the pointer.
+The default is used if a resource is not specified in the argument list
+or in the resource database or if the conversion from the representation
+type stored in the resource database fails,
+which can happen for various reasons (for example, a misspelled entry in a
+resource file).
+.LP
+Two special representation types 
+(XtRImmediate
+and
+XtRCallProc)
+are usable only as default resource types.
+XtRImmediate
+indicates that the value in the \fIdefault_addr\fP field is the actual value of
+the resource rather than the address of the value. 
+The value must be in the correct representation type for the resource,
+coerced to an
+.PN XtPointer .
+No conversion is possible, since there is no source representation type.
+XtRCallProc
+indicates that the value in the \fIdefault_addr\fP field is a procedure
+pointer.
+This procedure is automatically invoked with the widget,
+\fIresource_offset\fP, and a pointer to an
+.PN XrmValue
+in which to store the result.
+XtRCallProc
+procedure pointers are of type
+.PN XtResourceDefaultProc .
+.LP
+.sM
+.FD 0
+typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue*);
+.br
+      Widget \fIw\fP;
+.br
+      int \fIoffset\fP;
+.br
+      XrmValue *\fIvalue\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget whose resource value is to be obtained.
+.IP \fIoffset\fP 1i
+Specifies the offset of the field in the widget record.
+.IP \fIvalue\fP 1i
+Specifies the resource value descriptor to return.
+.LP
+.eM
+The
+.PN XtResourceDefaultProc
+procedure should fill in the \fIvalue->addr\fP field with a pointer 
+to the resource value in its correct representation type.
+.sp
+.LP
+To get the resource list structure for a particular class, use
+.PN XtGetResourceList .
+.LP
+.IN "XtGetResourceList" "" "@DEF@"
+.sM
+.FD 0
+void XtGetResourceList(\fIclass\fP, \fIresources_return\fP, \fInum_resources_return\fP);
+.br
+      WidgetClass \fIclass\fP;
+.br
+      XtResourceList *\fIresources_return\fP;
+.br
+      Cardinal *\fInum_resources_return\fP;
+.FN
+.IP \fIclass\fP 1.5i
+Specifies the object class to be queried.  It must be
+.PN objectClass
+or any subclass thereof.
+.IP \fIresources_return\fP 1.5i
+Returns the resource list.
+.IP \fInum_resources_return\fP 1.5i
+Returns the number of entries in the resource list.
+.LP
+.eM
+If
+.PN XtGetResourceList
+is called before the class is initialized,
+it returns the resource list as specified in the class record.
+If it is called after the class has been initialized,
+.PN XtGetResourceList
+returns a merged resource list that includes the resources 
+for all superclasses.
+The list returned by
+.PN XtGetResourceList
+should be freed using
+.PN XtFree
+when it is no longer needed.
+.sp
+.LP
+To get the constraint resource list structure for a particular widget
+class, use
+.PN XtGetConstraintResourceList .
+.LP
+.IN "XtGetConstraintResourceList" "" "@DEF@"
+.sM
+.FD 0
+void XtGetConstraintResourceList(\fIclass\fP, \fIresources_return\fP, \
+\fInum_resources_return\fP)
+.br
+      WidgetClass \fIclass\fP;
+.br
+      XtResourceList *\fIresources_return\fP;
+.br
+      Cardinal *\fInum_resources_return\fP;
+.FN
+.IP \fIclass\fP 1.5i
+Specifies the object class to be queried.  It must be
+.PN objectClass
+or any subclass thereof.
+.IP \fIresources_return\fP 1.5i
+Returns the constraint resource list.
+.IP \fInum_resources_return\fP 1.5i
+Returns the number of entries in the constraint resource list.
+.LP
+.eM
+If
+.PN XtGetConstraintResourceList
+is called before the widget class is
+initialized, the resource list as specified in the widget
+class Constraint part is returned.  If
+.PN XtGetConstraintResourceList
+is called after the widget class has been initialized, the merged
+resource list for the class and all Constraint superclasses is
+returned.  If the
+specified class is not a subclass of
+.PN constraintWidgetClass ,
+*\fIresources_return\fP is set to NULL
+and *\fInum_resources_return\fP is set to zero.
+The list returned by
+.PN XtGetConstraintResourceList
+should be freed using
+.PN XtFree
+when it is no longer needed.
+.sp
+.LP
+The routines
+.PN XtSetValues
+and
+.PN XtGetValues
+also use the resource list to set and get widget state;
+see Sections 9.7.1 and 9.7.2.
+.LP
+Here is an abbreviated version of a possible resource list for a Label widget:
+.LP
+.Ds
+.TA .5i 1.5i 3i
+.ta .5i 1.5i 3i
+/* Resources specific to Label */
+static XtResource resources[] = {
+{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
+   XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground},
+{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
+   XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont},
+{XtNlabel, XtCLabel, XtRString, sizeof(String),
+   XtOffsetOf(LabelRec, label.label), XtRString, NULL},
+	.
+	.
+	.
+}
+.De
+.LP
+The complete resource name for a field of a widget instance is the
+concatenation of the application shell name (from 
+.PN XtAppCreateShell ),
+the instance names of all the widget's parents up to the 
+top of the widget tree,
+the instance name of the widget itself,
+and the resource name of the specified field of the widget.
+Similarly,
+the full resource class of a field of a widget instance is the
+concatenation of the application class (from
+.PN XtAppCreateShell ),
+the widget class names of all the widget's parents up to the 
+top of the widget tree,
+the widget class name of the widget itself,
+and the resource class of the specified field of the widget.
+
+.NH 2
+Byte Offset Calculations
+.XS
+\*(SN Byte Offset Calculations
+.XE
+.LP
+To determine the byte offset of a field within a structure type, use
+.PN XtOffsetOf .
+.LP
+.IN "XtOffsetOf" "" "@DEF@"
+.sM
+.FD 0
+Cardinal XtOffsetOf(\fIstructure_type\fP, \fIfield_name\fP)
+.br
+      \fIType structure_type\fP;
+.br
+      \fIField field_name\fP;
+.FN
+.IP \fIstructure_type\fP 1i
+Specifies a type that is declared as a structure.
+.IP \fIfield_name\fP 1i
+Specifies the name of a member within the structure.
+.LP
+.eM
+The
+.PN XtOffsetOf
+macro expands to a constant expression that gives the
+offset in bytes to the specified structure member from the beginning
+of the structure.  It is normally used to statically initialize
+resource lists and is more portable than
+.PN XtOffset ,
+which serves the same function.
+
+.LP
+To determine the byte offset of a field within a structure pointer type, use
+.PN XtOffset .
+.LP
+.IN "XtOffset" "" "@DEF@"
+.sM
+.FD 0
+Cardinal XtOffset(\fIpointer_type\fP, \fIfield_name\fP)
+.br
+      \fIType pointer_type\fP;
+.br
+      \fIField field_name\fP;
+.FN
+.IP \fIpointer_type\fP 1i
+Specifies a type that is declared as a pointer to a structure.
+.IP \fIfield_name\fP 1i
+Specifies the name of a member within the structure.
+.LP
+.eM
+The
+.PN XtOffset
+macro expands to a constant expression that gives the
+offset in bytes to the specified structure member from the beginning
+of the structure.  It may be used to statically initialize
+resource lists.
+.PN XtOffset
+is less portable than
+.PN XtOffsetOf .
+
+.NH 2
+Superclass-to-Subclass Chaining of Resource Lists
+.XS
+\*(SN Superclass-to-Subclass Chaining of Resource Lists
+.XE
+.LP
+.IN "Inheritance"
+.IN "Superclass Chaining"
+.IN "Chaining"
+The 
+.PN XtCreateWidget
+function gets resources as a superclass-to-subclass chained operation.
+That is, the resources specified in the
+.PN objectClass
+resource list are fetched,
+then those in
+.PN rectObjClass ,
+and so on down to the resources specified
+for this widget's class. Within a class, resources are fetched in the order
+they are declared.
+.LP
+In general, if a widget resource field is declared in a superclass,
+that field is included in the superclass's resource list and need not be
+included in the subclass's resource list.
+For example, the
+Core 
+class contains a resource entry for \fIbackground_pixel\fP.
+Consequently,
+the implementation of Label need not also have a resource entry
+for \fIbackground_pixel\fP.
+However, a subclass,
+by specifying a resource entry for that field in its own resource list,
+can override the resource entry for any field declared in a superclass.
+This is most often done to override the defaults provided in the
+superclass with new ones.
+At class initialization time, 
+resource lists for that class are scanned from the superclass down 
+to the class to look for resources with the same offset.
+A matching resource in a subclass will be reordered to override
+the superclass entry.
+If reordering is necessary, a copy of the superclass resource list is made to
+avoid affecting other subclasses of the superclass.
+.LP
+.IN "class_initialize procedure"
+.IN "Widget" "class initialization"
+Also at class initialization time, the \*(xI produce an
+internal representation of the resource list to optimize access time
+when creating widgets.  In order to save memory, the \*(xI may
+overwrite the storage allocated for the resource list in the class
+record; therefore, widgets must allocate resource lists in writable
+storage and must not access the list contents directly after the
+class_initialize procedure has returned.
+
+.NH 2
+Subresources
+.XS
+\*(SN Subresources
+.XE
+.LP
+A widget does not do anything to retrieve its own resources;
+instead,
+.PN XtCreateWidget
+does this automatically before calling the class initialize procedure.
+.LP
+Some widgets have subparts that are not widgets but for which the widget
+would like to fetch resources.
+Such widgets call
+.PN XtGetSubresources
+to accomplish this.
+.LP
+.IN "XtGetSubresources" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
+\fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIbase\fP;
+.br
+      String \fIname\fP;
+.br
+      String \fIclass\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the object used to qualify the subpart resource name and
+class.  \*(oI
+.IP \fIbase\fP 1i
+Specifies the base address of the subpart data structure into which the
+resources will be written.
+.IP \fIname\fP 1i
+Specifies the name of the subpart.
+.IP \fIclass\fP 1i
+Specifies the class of the subpart.
+.IP \fIresources\fP 1i
+Specifies the resource list for the subpart.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.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 XtGetSubresources
+function constructs a name and class list from the application name and class,
+the names and classes of all the object's ancestors, and the object itself.
+Then it appends to this list the \fIname\fP and \fIclass\fP pair passed in.
+The resources are fetched from the argument list, the resource database,
+or the default values in the resource list.
+Then they are copied into the subpart record.
+If \fIargs\fP is NULL,
+\fInum_args\fP must be zero.
+However, if \fInum_args\fP is zero,
+the argument list is not referenced.
+.LP
+.PN XtGetSubresources
+may overwrite the specified resource list with an
+equivalent representation in an internal format, which optimizes access
+time if the list is used repeatedly.  The resource list must be
+allocated in writable storage, and the caller must not modify the list
+contents after the call if the same list is to be used again.
+Resources fetched by
+.PN XtGetSubresources
+are reference-counted as
+if they were referenced by the specified object.  Subresources might
+therefore be freed from the conversion cache and destroyed
+when the object is destroyed, but not before then.
+.sp
+.LP
+To fetch resources for widget subparts using varargs lists, use
+.PN XtVaGetSubresources .
+.LP
+.IN "XtVaGetSubresources" "" "@DEF@"
+.sM
+.FD 0
+void XtVaGetSubresources(\fIw\fP, \fIbase\fP, \fIname\fP, \fIclass\fP, \
+\fIresources\fP, \fInum_resources\fP, ...)
+.br
+    Widget \fIw\fP;
+.br
+    XtPointer \fIbase\fP;
+.br
+    String \fIname\fP;
+.br
+    String \fIclass\fP;
+.br
+    XtResourceList \fIresources\fP;
+.br
+    Cardinal \fInum_resources\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the object used to qualify the subpart resource name and
+class.  \*(oI
+.IP \fIbase\fP 1i
+Specifies the base address of the subpart data structure into which the
+resources will be written.
+.IP \fIname\fP 1i
+Specifies the name of the subpart.
+.IP \fIclass\fP 1i
+Specifies the class of the subpart.
+.IP \fIresources\fP 1i
+Specifies the resource list for the subpart.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+.PN XtVaGetSubresources
+is identical in function to
+.PN XtGetSubresources
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
+described in Section 2.5.1.
+
+.NH 2
+Obtaining Application Resources
+.XS
+\fB\*(SN Obtaining Application Resources\fP
+.XE
+.LP
+To retrieve resources that are not specific to a widget
+but apply to the overall application, use
+.PN XtGetApplicationResources .
+.LP
+.IN "XtGetApplicationResources" "" "@DEF@"
+.sM
+.FD 0
+void XtGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \
+\fInum_resources\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIbase\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the object that identifies the resource database to search
+(the database is that associated with the display for this object).  \*(oI
+.IP \fIbase\fP 1i
+Specifies the base address into which
+the resource values will be written.
+.IP \fIresources\fP 1i
+Specifies the resource list.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.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 XtGetApplicationResources
+function first uses the passed object,
+which is usually an application shell widget,
+to construct a resource name and class list.
+The full name and class of the specified object (that is, including its
+ancestors, if any) is logically added to the
+front of each resource name and class.
+Then it retrieves the resources from the argument list,
+the resource database, or the resource list default values.
+After adding base to each address,
+.PN XtGetApplicationResources
+copies the resources into the addresses
+obtained by adding \fIbase\fP to each \fIoffset\fP in the resource list.
+If \fIargs\fP is NULL,
+\fInum_args\fP must be zero.
+However, if \fInum_args\fP is zero,
+the argument list is not referenced.
+The portable way to specify application resources is to declare them
+as members of a structure and pass the address of the structure 
+as the \fIbase\fP argument.
+.LP
+.PN XtGetApplicationResources
+may overwrite the specified resource list
+with an equivalent representation in an internal format, which
+optimizes access time if the list is used repeatedly.  The resource
+list must be allocated in writable storage, and the caller must not
+modify the list contents after the call if the same list is to be
+used again.  Any per-display resources fetched by
+.PN XtGetApplicationResources
+will not be freed from the resource cache until the display is closed.
+.sp
+.LP
+To retrieve resources for the overall application using varargs lists, use
+.PN XtVaGetApplicationResources .
+.LP
+.IN "XtVaGetApplicationResources" "" "@DEF@"
+.sM
+.FD 0
+void XtVaGetApplicationResources(\fIw\fP, \fIbase\fP, \fIresources\fP, \
+\fInum_resources\fP, ...)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIbase\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the object that identifies the resource database to search
+(the database is that associated with the display for this object).  \*(oI
+.IP \fIbase\fP 1i
+Specifies the base address into which
+the resource values will be written.
+.IP \fIresources\fP 1i
+Specifies the resource list for the subpart.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+.PN XtVaGetApplicationResources
+is identical in function to
+.PN XtGetApplicationResources
+with the \fIargs\fP and \fInum_args\fP parameters
+replaced by a varargs list, as described in Section 2.5.1.
+
+.NH 2
+Resource Conversions
+.XS
+\*(SN Resource Conversions
+.XE
+.LP
+The \*(xI provide a mechanism for registering representation converters that
+are automatically invoked by the resource-fetching routines.
+The \*(xI additionally provide and register several commonly used converters.
+This resource conversion mechanism serves several purposes:
+.IP \(bu 5
+It permits user and application resource files to contain textual
+representations of nontextual values.
+.IP \(bu 5
+It allows textual or other representations of default resource values that
+are dependent on the display, screen, or colormap, and thus must be
+computed at runtime.
+.IP \(bu 5
+It caches conversion source and result data.
+Conversions that require much computation or space
+(for example, string-to-translation-table)
+or that require round-trips to the server
+(for example, string-to-font or string-to-color) are performed only once.
+
+.NH 3
+Predefined Resource Converters
+.XS
+\*(SN Predefined Resource Converters
+.XE
+.LP
+The \*(xI define all the representations used in the 
+Object,
+RectObj,
+Core, 
+Composite, 
+Constraint, 
+and 
+Shell 
+widget classes.
+The \*(xI register the following resource converters that accept
+input values of representation type
+.PN XtRString .
+.LP
+.TS
+lw(1.7i) lw(2.4i) lw(1.5i) .
+_
+.sp 6p
+Target Representation	Converter Name	Additional Args
+.sp 6p
+_
+.sp 6p
+T{
+.PN XtRAcceleratorTable
+T}	T{
+.PN XtCvtStringToAcceleratorTable
+T}
+T{
+.PN XtRAtom
+T}	T{
+.PN XtCvtStringToAtom
+T}	Display*
+T{
+.PN XtRBoolean
+T}	T{
+.PN XtCvtStringToBoolean
+T}
+T{
+.PN XtRBool
+T}	T{
+.PN XtCvtStringToBool
+T}
+T{
+.PN XtRCommandArgArray
+T}	T{
+.PN XtCvtStringToCommandArgArray
+T}
+T{
+.PN XtRCursor
+T}	T{
+.PN XtCvtStringToCursor
+T}	Display*
+T{
+.PN XtRDimension
+T}	T{
+.PN XtCvtStringToDimension
+T}
+T{
+.PN XtRDirectoryString
+T}	T{
+.PN XtCvtStringToDirectoryString
+T}
+T{
+.PN XtRDisplay
+T}	T{
+.PN XtCvtStringToDisplay
+T}
+T{
+.PN XtRFile
+T}	T{
+.PN XtCvtStringToFile
+T}
+T{
+.PN XtRFloat
+T}	T{
+.PN XtCvtStringToFloat
+T}
+T{
+.PN XtRFont
+T}	T{
+.PN XtCvtStringToFont
+T}	Display*
+T{
+.PN XtRFontSet
+T}	T{
+.PN XtCvtStringToFontSet
+T}	Display*, String \fIlocale\fP
+T{
+.PN XtRFontStruct
+T}	T{
+.PN XtCvtStringToFontStruct
+T}	Display*
+T{
+.PN XtRGravity
+T}	T{
+.PN XtCvtStringToGravity
+T}
+T{
+.PN XtRInitialState
+T}	T{
+.PN XtCvtStringToInitialState
+T}
+T{
+.PN XtRInt
+T}	T{
+.PN XtCvtStringToInt
+T}
+T{
+.PN XtRPixel
+T}	T{
+.PN XtCvtStringToPixel
+T}	T{
+.PN colorConvertArgs
+T}
+T{
+.PN XtRPosition
+T}	T{
+.PN XtCvtStringToPosition
+T}
+T{
+.PN XtRRestartStyle
+T}	T{
+.PN XtCvtStringToRestartStyle
+T}
+T{
+.PN XtRShort
+T}	T{
+.PN XtCvtStringToShort
+T}
+T{
+.PN XtRTranslationTable
+T}	T{
+.PN XtCvtStringToTranslationTable
+T}
+T{
+.PN XtRUnsignedChar
+T}	T{
+.PN XtCvtStringToUnsignedChar
+T}
+T{
+.PN XtRVisual
+T}	T{
+.PN XtCvtStringToVisual
+T}	Screen*, Cardinal \fIdepth\fP
+.sp 6p
+_
+.TE
+
+.LP
+The String-to-Pixel conversion has two predefined constants that are
+guaranteed to work and contrast with each other:
+.PN XtDefaultForeground
+and
+.PN XtDefaultBackground .
+.IN "XtDefaultBackground" "" "@DEF@"
+.IN "XtDefaultForeground" "" "@DEF@"
+They evaluate to the black and white pixel values of the widget's screen, 
+respectively.
+.IN "Resources" "reverseVideo"
+If the application resource reverseVideo is
+.PN True ,
+they evaluate to the white and black pixel values of the widget's screen,
+respectively.
+Similarly, the String-to-Font and String-to-FontStruct converters recognize
+the constant
+.PN XtDefaultFont
+.IN "XtDefaultFont" "" "@DEF@"
+.IN "Resources" "xtDefaultFont"
+and evaluate this in the following manner:
+.IP \(bu 5
+Query the resource database for the resource whose full name
+is ``xtDefaultFont'', class ``XtDefaultFont'' (that is, no widget
+name/class prefixes), and use a type
+.PN XtRString
+value returned as the font name or a type
+.PN XtRFont
+or
+.PN XtRFontStruct
+value directly as the resource value.
+.IP \(bu 5
+If the resource database does not contain a value for xtDefaultFont,
+class XtDefaultFont, or if the returned font name cannot be
+successfully opened, an implementation-defined font in ISO8859-1
+character set encoding is opened.  (One possible algorithm is to
+perform an
+.PN XListFonts
+using a wildcard font name and use the first
+font in the list.  This wildcard font name should be as broad as
+possible to maximize the probability of locating a useable font;
+for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".)
+.IP \(bu 5
+If no suitable ISO8859-1 font can be found, issue a warning message
+and return
+.PN False .
+.LP
+The String-to-FontSet converter recognizes the constant
+.PN XtDefaultFontSet
+.IN "XtDefaultFontSet" "" "@DEF@"
+.IN "Resources" "xtDefaultFontSet"
+and evaluate this in the following manner:
+.IP \(bu 5
+Query the resource database for the resource whose full name
+is ``xtDefaultFontSet'', class ``XtDefaultFontSet'' (that is, no widget
+name/class prefixes), and use a type
+.PN XtRString
+value returned as the base font name list or a type
+.PN XtRFontSet
+value directly as the resource value.
+.IP \(bu 5
+If the resource database does not contain a value for xtDefaultFontSet,
+class XtDefaultFontSet, or if a font set cannot be
+successfully created from this resource,
+an implementation-defined font set is created.
+(One possible algorithm is to
+perform an
+.PN XCreateFontSet
+using a wildcard base font name.
+This wildcard base font name should be as broad as
+possible to maximize the probability of locating a useable font;
+for example, "-*-*-*-R-*-*-*-120-*-*-*-*".)
+.IP \(bu 5
+If no suitable font set can be created, issue a warning message
+and return
+.PN False .
+.LP
+If a font set is created but \fImissing_charset_list\fP is not
+empty, a warning is issued and the partial font set is returned.
+The \*(xI register the String-to-FontSet converter with
+a conversion argument list that extracts the current process
+locale at the time the converter is invoked.   This ensures
+that the converter is invoked again if the same conversion
+is required in a different locale.
+.LP
+The String-to-Gravity conversion accepts string values that are the
+names of window and bit gravities and their numerical equivalents,
+as defined in \fI\*(xL\fP:
+.PN ForgetGravity ,
+.PN UnmapGravity ,
+.PN NorthWestGravity ,
+.PN NorthGravity ,
+.PN NorthEastGravity ,
+.PN WestGravity ,
+.PN CenterGravity ,
+.PN EastGravity ,
+.PN SouthWestGravity ,
+.PN SouthGravity , 
+.PN SouthEastGravity , 
+and
+.PN StaticGravity .
+Alphabetic case is not significant in the conversion.
+.LP
+The String-to-CommandArgArray conversion parses a String into an
+array of strings.
+White space characters separate elements of the command line.
+The converter recognizes the backslash character ``\\'' as an escape
+character to allow the following white space character to be part of the
+array element.
+.LP
+.IN "XtCurrentDirectory" "" "@DEF@"
+The String-to-DirectoryString conversion recognizes the
+string ``XtCurrentDirectory'' and returns the result of a call
+to the operating system to get the current directory.
+.LP
+The String-to-RestartStyle conversion accepts the values 
+.PN RestartIfRunning ,
+.PN RestartAnyway ,
+.PN RestartImmediately ,
+and
+.PN RestartNever
+as defined by the \fIX Session Management Protocol\fP.
+.LP
+The String-to-InitialState conversion accepts the values
+.PN NormalState
+or
+.PN IconicState
+as defined by the \fI\*(xC\fP.
+.LP
+The String-to-Visual conversion calls
+.PN XMatchVisualInfo
+using the
+\fIscreen\fP and \fIdepth\fP fields from the core part and returns the first
+matching Visual on the list.  The widget resource list must be certain
+to specify any resource of type
+.PN XtRVisual
+after the depth resource.
+The allowed string values are the visual class names defined in \fI\*(xP\fP,
+Section 8;
+.PN StaticGray ,
+.PN StaticColor ,
+.PN TrueColor ,
+.PN GrayScale ,
+.PN PseudoColor ,
+and
+.PN DirectColor .
+
+.LP
+The \*(xI register the following resource converter that accepts
+an input value of representation type
+.PN XtRColor .
+.LP
+.TS
+lw(1.5i) lw(2.25i) lw(1.5i) .
+_
+.sp 6p
+Target Representation	Converter Name	Additional Args
+.sp 6p
+_
+.sp 6p
+T{
+.PN XtRPixel
+T}	T{
+.PN XtCvtColorToPixel
+T}
+.sp 6p
+_
+.TE
+
+.LP
+The \*(xI register the following resource converters that accept
+input values of representation type
+.PN XtRInt .
+.LP
+.TS
+lw(1.5i) lw(2.25i) lw(1.5i) .
+_
+.sp 6p
+Target Representation	Converter Name	Additional Args
+.sp 6p
+_
+.sp 6p
+T{
+.PN XtRBoolean
+T}	T{
+.PN XtCvtIntToBoolean
+T}
+T{
+.PN XtRBool
+T}	T{
+.PN XtCvtIntToBool
+T}
+T{
+.PN XtRColor
+T}	T{
+.PN XtCvtIntToColor
+T}	T{
+.PN colorConvertArgs
+T}
+T{
+.PN XtRDimension
+T}	T{
+.PN XtCvtIntToDimension
+T}
+T{
+.PN XtRFloat
+T}	T{
+.PN XtCvtIntToFloat
+T}
+T{
+.PN XtRFont
+T}	T{
+.PN XtCvtIntToFont
+T}
+T{
+.PN XtRPixel
+T}	T{
+.PN XtCvtIntToPixel
+T}
+T{
+.PN XtRPixmap
+T}	T{
+.PN XtCvtIntToPixmap
+T}
+T{
+.PN XtRPosition
+T}	T{
+.PN XtCvtIntToPosition
+T}
+T{
+.PN XtRShort
+T}	T{
+.PN XtCvtIntToShort
+T}
+T{
+.PN XtRUnsignedChar
+T}	T{
+.PN XtCvtIntToUnsignedChar
+T}
+.sp 6p
+_
+.TE
+
+.LP
+The \*(xI register the following resource converter that accepts
+an input value of representation type
+.PN XtRPixel .
+.LP
+.TS
+lw(1.5i) lw(2.25i) lw(1.5i) .
+_
+.sp 6p
+Target Representation	Converter Name	Additional Args
+.sp 6p
+_
+.sp 6p
+T{
+.PN XtRColor
+T}	T{
+.PN XtCvtPixelToColor
+T}
+.sp 6p
+_
+.TE
+
+.NH 3
+New Resource Converters
+.XS
+\*(SN New Resource Converters
+.XE
+.LP
+Type converters use pointers to
+.PN XrmValue
+structures (defined in
+.Pn < X11/Xresource.h >;
+see Section 15.4 in \fI\*(xL\fP)
+for input and output values.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	unsigned int size;
+	XPointer addr;
+} XrmValue, *XrmValuePtr;
+.De
+.LP
+.eM
+The \fIaddr\fP field specifies the address of the data, and the \fIsize\fP
+field gives the total number of significant bytes in the data.
+For values of type
+.PN String ,
+\fIaddr\fP is the address of the first character and \fIsize\fP
+includes the NULL-terminating byte. 
+.LP
+A resource converter procedure pointer is of type
+.PN XtTypeConverter .
+.LP
+.IN "XtTypeConverter" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*,
+                              XrmValue*, XrmValue*, XtPointer*);
+.br
+      Display *\fIdisplay\fP;
+.br
+      XrmValue *\fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.br
+      XrmValue *\fIfrom\fP;
+.br
+      XrmValue *\fIto\fP;
+.br
+      XtPointer *\fIconverter_data\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection with which this conversion is associated.
+.IP \fIargs\fP 1i
+Specifies a list of additional
+.PN XrmValue
+arguments to the converter if additional context is needed
+to perform the conversion, or NULL.
+For example, the String-to-Font converter needs the widget's \fIdisplay\fP,
+and the String-to-Pixel converter needs the widget's \fIscreen\fP and \fIcolormap\fP.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.IP \fIfrom\fP 1i
+Specifies the value to convert.
+.IP \fIto\fP 1i
+Specifies a descriptor for a location into which to store the converted value.
+.IP \fIconverter_data\fP 1i
+Specifies a location into which the converter may
+store converter-specific data associated
+with this conversion.
+.LP
+.eM
+The \fIdisplay\fP argument is normally used only when generating error
+messages, to identify the application context (with the function
+.PN XtDisplayToApplicationContext ).
+.LP
+The \fIto\fP argument specifies the size and location into which the
+converter should store the converted value.  If the \fIaddr\fP field is NULL,
+the converter should allocate appropriate storage and store the size
+and location into the \fIto\fP descriptor.  If the type converter allocates
+the storage, it remains under the ownership of the converter and must
+not be modified by the caller.  The type converter is permitted to use
+static storage for this purpose, and therefore the caller must
+immediately copy the data upon return from the converter.  If the
+\fIaddr\fP field is not NULL, the converter must check the \fIsize\fP field to
+ensure that sufficient space has been allocated before storing the
+converted value.  If insufficient space is specified, the converter
+should update the \fIsize\fP field with the number of bytes required and
+return
+.PN False
+without modifying the data at the specified location.
+If sufficient space was allocated by the caller, the converter should
+update the \fIsize\fP field with the number of bytes actually occupied by the
+converted value.  For converted values of type
+.PN XtRString ,
+the size should
+include the NULL-terminating byte, if any.
+The converter may store any value in the location specified
+in \fIconverter_data\fP; this value will be passed to the destructor, if any,
+when the resource is freed by the \*(xI.
+.LP
+The converter must return
+.PN True
+if the conversion was successful and
+.PN False
+otherwise.  If the conversion cannot be performed because of an
+improper source value, a warning message should also be issued with
+.PN XtAppWarningMsg .
+
+.LP
+Most type converters just take the data described by the specified \fIfrom\fP
+argument and return data by writing into the location specified in
+the \fIto\fP argument.
+A few need other information, which is available in \fIargs\fP.
+A type converter can invoke another type converter,
+which allows differing sources that may convert into a common intermediate
+result to make maximum use of the type converter cache.
+.LP
+Note that if an address is written into \fIto->addr\fP, it cannot be that
+of a local variable of the converter because the data will not be
+valid after the converter returns.  Static variables may be used,
+as in the following example.
+If the converter modifies the resource database,
+the changes affect any in-progress widget creation,
+.PN XtGetApplicationResources ,
+or
+.PN XtGetSubresources
+in an implementation-defined manner; however, insertion of new entries
+or changes to existing entries is allowed and will not directly cause
+an error.
+
+.LP
+The following is an example of a converter that takes a
+.PN string
+and converts it to a
+.PN Pixel .
+Note that the \fIdisplay\fP parameter is
+used only to generate error messages; the
+.PN Screen
+conversion argument is
+still required to inform the \*(xI that the converted value is
+a function of the particular display (and colormap).
+.LP
+.Ds 0
+.TA .3i .7i 1i 1.3i 1.7i 2i 4i
+.ta .3i .7i 1i 1.3i 1.7i 2i 4i
+
+#define done(type, value) \\
+	{						\\
+		if (toVal->addr != NULL) {		\\
+			if (toVal->size < sizeof(type)) {	\\
+				toVal->size = sizeof(type);	\\
+				return False;	\\
+			}				\\
+			*(type*)(toVal->addr) = (value);	\\
+		}					\\
+		else {				\\
+			static type static_val;	\\
+			static_val = (value);	\\
+			toVal->addr = (XPointer)&static_val;	\\
+		}					\\
+		toVal->size = sizeof(type);	\\
+		return True;			\\
+	}
+
+static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_data)
+	Display	*dpy;
+	XrmValue	*args;
+	Cardinal	*num_args;
+	XrmValue	*fromVal;
+	XrmValue	*toVal;
+	XtPointer	*converter_data;
+{
+	static XColor	screenColor;
+	XColor		exactColor;
+	Screen		*screen;
+	Colormap		colormap;
+	Status			status;
+
+	if (*num_args != 2)
+		XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
+			"wrongParameters", "cvtStringToPixel", "XtToolkitError",
+			"String to pixel conversion needs screen and colormap arguments",
+			(String *)NULL, (Cardinal *)NULL);
+
+	screen = *((Screen**) args[0].addr);
+	colormap = *((Colormap *) args[1].addr);
+
+	if (CompareISOLatin1(str, XtDefaultBackground) == 0) {
+		*closure_ret = False;
+		done(Pixel, WhitePixelOfScreen(screen));
+	}
+	if (CompareISOLatin1(str, XtDefaultForeground) == 0) {
+		*closure_ret = False;
+		done(Pixel, BlackPixelOfScreen(screen));
+	}
+
+
+	status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal->addr, 
+				               &screenColor, &exactColor);
+
+	if (status == 0) {
+		String params[1];
+		Cardinal num_params = 1;
+		params[0] = (String)fromVal->addr;
+		XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
+			"noColormap", "cvtStringToPixel", "XtToolkitError",
+			"Cannot allocate colormap entry for \\"%s\\"", params,\
+ &num_params);
+	        *converter_data = (char *) False;
+                return False;
+	} else {
+                *converter_data = (char *) True;
+		done(Pixel, &screenColor.pixel);
+	}
+}
+.De
+.LP
+All type converters should define some set of conversion values for which they
+are guaranteed to succeed so these can be used in the resource defaults.
+This issue arises only with conversions, such as fonts and colors,
+where there is no string representation that all server implementations
+will necessarily recognize.
+For resources like these,
+the converter should define a symbolic constant
+in the same manner as
+.PN XtDefaultForeground ,
+.PN XtDefaultBackground ,
+and
+.PN XtDefaultFont .
+.sp
+.LP
+To allow the \*(xI to deallocate resources produced by type
+converters, a resource destructor procedure may also be provided.
+.LP
+A resource destructor procedure pointer is of type
+.PN XtDestructor .
+.LP
+.IN "XtDestructor" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, \
+Cardinal*);
+.br
+      XtAppContext \fIapp\fP;
+.br
+      XrmValue *\fIto\fP;
+.br
+      XtPointer \fIconverter_data\fP;
+.br
+      XrmValue *\fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.FN
+.IP \fIapp\fP 1i
+Specifies an application context in which the resource is being freed.
+.IP \fIto\fP 1i
+Specifies a descriptor for the resource produced by the type converter.
+.IP \fIconverter_data\fP 1i
+Specifies the converter-specific data returned by the type converter.
+.IP \fIargs\fP 1i
+Specifies the additional converter arguments as passed
+to the type converter when the conversion was performed.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.LP
+.eM
+The destructor procedure is responsible for freeing the resource
+specified by the \fIto\fP argument, including any auxiliary storage
+associated with that resource, but not the memory directly addressed
+by the size and location in the \fIto\fP argument or the memory specified
+by \fIargs\fP.
+
+.NH 3
+Issuing Conversion Warnings
+.XS
+\*(SN Issuing Conversion Warnings
+.XE
+.LP
+The
+.PN XtDisplayStringConversionWarning
+procedure is a convenience routine for resource type converters
+that convert from string values.
+.LP
+.IN "XtDisplayStringConversionWarning" "" "@DEF@"
+.sM
+.FD 0
+void XtDisplayStringConversionWarning(\fIdisplay\fP, \fIfrom_value\fP, \
+\fIto_type\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      String \fIfrom_value\fP, \fIto_type\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection with which the conversion is associated.
+.IP \fIfrom_value\fP 1i
+Specifies the string that could not be converted.
+.IP \fIto_type\fP 1i
+Specifies the target representation type requested.
+.LP
+.eM
+The
+.PN XtDisplayStringConversionWarning
+procedure issues a warning message using
+.PN XtAppWarningMsg
+with \fIname\fP ``conversionError'',
+\fItype\fP ``string'', \fIclass\fP ``XtToolkitError'', and the default message
+``Cannot convert "\fIfrom_value\fP" to type \fIto_type\fP''.
+.LP
+To issue other types of warning or error messages, the type converter
+should use
+.PN XtAppWarningMsg
+or
+.PN XtAppErrorMsg .
+.sp
+.LP
+To retrieve the application context associated with a given
+display connection, use
+.PN XtDisplayToApplicationContext .
+.LP
+.IN "XtDisplayToApplicationContext" "" "@DEF@"
+.sM
+.FD 0
+XtAppContext XtDisplayToApplicationContext( \fIdisplay\fP )
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies an open and initialized display connection.
+.LP
+.eM
+The
+.PN XtDisplayToApplicationContext
+function returns the application
+context in which the specified \fIdisplay\fP was initialized.  If the
+display is not known to the \*(xI, an error message is issued.
+
+.NH 3
+Registering a New Resource Converter
+.XS
+\fB\*(SN Registering a New Resource Converter\fP
+.XE
+.LP
+When registering a resource converter, the client must specify the
+manner in which the conversion cache is to be used when there are multiple
+calls to the converter.  Conversion cache control is specified
+via an
+.PN XtCacheType
+.LP
+.IN "XtCacheType" "" "@DEF@"
+argument.
+.sM
+.Ds 0
+typedef int XtCacheType;
+.De
+.LP
+.eM
+An
+.PN XtCacheType
+field may contain one of the following values:
+.br
+.sp
+.LP
+.PN XtCacheNone
+.IN "XtCacheNone" "" "@DEF@"
+.IP
+Specifies that the results of a previous conversion
+may not be reused to satisfy any other resource
+requests; the specified converter will be called
+each time the converted value is required.
+.br
+.sp
+.LP
+.PN XtCacheAll
+.IN "XtCacheAll" "" "@DEF@"
+.IP
+Specifies that the results of a previous conversion
+should be reused for any resource request that depends
+upon the same source value and conversion arguments.
+.br
+.sp
+.LP
+.PN XtCacheByDisplay
+.IN "XtCacheByDisplay" "" "@DEF@"
+.IP  
+Specifies that the results of a previous conversion
+should be used as for
+.PN XtCacheAll
+but the destructor will be called, if specified, if
+.PN XtCloseDisplay
+is called
+for the display connection associated with the converted value, and
+the value will be removed from the conversion cache.
+.LP
+The qualifier
+.PN XtCacheRefCount
+.IN "XtCacheRefCount" "" "@DEF@"
+may be ORed with any of the above values.  If
+.PN XtCacheRefCount
+is specified, calls to
+.PN XtCreateWidget ,
+.PN XtCreateManagedWidget ,
+.PN XtGetApplicationResources ,
+and
+.PN XtGetSubresources
+that use the converted value will be counted.  When a widget using the
+converted value is destroyed, the count is decremented, and, if the
+count reaches zero, the destructor procedure will be called and the
+converted value will be removed from the conversion cache.
+
+.LP
+To register a type converter for all application contexts in a
+process, use 
+.PN XtSetTypeConverter ,
+and to register a type converter in a single application context, use
+.PN XtAppSetTypeConverter .
+.LP
+.IN "XtSetTypeConverter" "" "@DEF@"
+.sM
+.FD 0
+void XtSetTypeConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
+\fIconvert_args\fP, \fInum_args\fP,
+                        \fIcache_type\fP, \fIdestructor\fP)
+.br
+      String \fIfrom_type\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XtTypeConverter \fIconverter\fP;
+.br
+      XtConvertArgList \fIconvert_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.br
+      XtCacheType \fIcache_type\fP;
+.br
+      XtDestructor \fIdestructor\fP;
+.FN
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIconverter\fP 1i
+Specifies the resource type converter procedure.
+.IP \fIconvert_args\fP 1i
+Specifies additional conversion arguments, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIconvert_args\fP.
+.IP \fIcache_type\fP 1i
+Specifies whether or not resources produced by this
+converter are sharable or display-specific and when
+they should be freed.
+.IP \fIdestructor\fP 1i
+Specifies a destroy procedure for resources produced by
+this conversion, or NULL if no additional action is
+required to deallocate resources produced by the converter.
+.LP
+.IN "XtAppSetTypeConverter" "" "@DEF@"
+.FD 0
+void XtAppSetTypeConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
+\fIconverter\fP, \fIconvert_args\fP,
+                           \fInum_args\fP, \fIcache_type\fP, \fIdestructor\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIfrom_type\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XtTypeConverter \fIconverter\fP;
+.br
+      XtConvertArgList \fIconvert_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.br
+      XtCacheType \fIcache_type\fP;
+.br
+      XtDestructor \fIdestructor\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIconverter\fP 1i
+Specifies the resource type converter procedure.
+.IP \fIconvert_args\fP 1i
+Specifies additional conversion arguments, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIconvert_args\fP.
+.IP \fIcache_type\fP 1i
+Specifies whether or not resources produced by this
+converter are sharable or display-specific and when
+they should be freed.
+.IP \fIdestructor\fP 1i
+Specifies a destroy procedure for resources produced by
+this conversion, or NULL if no additional action is
+required to deallocate resources produced by the converter.
+.LP
+.eM
+.PN XtSetTypeConverter
+registers the specified type converter and
+destructor in all application contexts created by the calling process,
+including any future application contexts that may be created.
+.PN XtAppSetTypeConverter
+registers the specified type converter in the
+single application context specified.  If the same \fIfrom_type\fP and
+\fIto_type\fP are specified in multiple calls to either function, the most
+recent overrides the previous ones.
+.sp
+.LP
+For the few type converters that need additional arguments,
+the \*(xI conversion mechanism provides a method of specifying
+how these arguments should be computed.
+The enumerated type
+.PN XtAddressMode
+and the structure
+.PN XtConvertArgRec
+specify how each argument is derived.
+These are defined in
+.Pn < X11/Intrinsic.h >.
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef enum {
+	/* address mode	parameter representation */
+	   XtAddress,	/* address */
+	   XtBaseOffset,	/* offset */
+	   XtImmediate,	/* constant */
+	   XtResourceString,	/* resource name string */
+	   XtResourceQuark,	/* resource name quark */
+	   XtWidgetBaseOffset,	/* offset */
+	   XtProcedureArg	/* procedure to call */
+} XtAddressMode;
+.sp
+typedef struct {
+	XtAddressMode address_mode;
+	XtPointer address_id;
+	Cardinal size;
+} XtConvertArgRec, *XtConvertArgList;
+.De
+.eM
+.LP
+The \fIsize\fP field specifies the length of the data in bytes.
+The \fIaddress_mode\fP field specifies how the \fIaddress_id\fP field should be
+interpreted.
+.PN XtAddress
+.IN "XtAddress" "" "@DEF@"
+causes \fIaddress_id\fP to be interpreted as the address of the data.
+.PN XtBaseOffset
+.IN "XtBaseOffset" "" "@DEF@"
+causes \fIaddress_id\fP to be interpreted as the offset from the widget base.
+.PN XtImmediate
+.IN "XtImmediate" "" "@DEF@"
+causes \fIaddress_id\fP to be interpreted as a constant.
+.PN XtResourceString
+.IN "XtResourceString" "" "@DEF@"
+causes \fIaddress_id\fP to be interpreted as the name of a resource
+that is to be converted into an offset from the widget base.
+.PN XtResourceQuark
+.IN "XtResourceQuark" "" "@DEF@"
+causes \fIaddress_id\fP to be interpreted as the result of an
+.PN XrmStringToQuark
+conversion on the name of a resource,
+which is to be converted into an offset from the widget base.
+.PN XtWidgetBaseOffset
+.IN "XtWidgetBaseOffset" "" "@DEF@"
+is similar to
+.PN XtBaseOffset
+except that it
+searches for the closest windowed ancestor if the object is not
+of a subclass of
+Core
+(see Chapter 12).
+.PN XtProcedureArg
+.IN "XtProcedureArg" "" "@DEF@"
+specifies that \fIaddress_id\fP is a pointer to a procedure to
+be invoked to return the conversion argument.  If
+.PN XtProcedureArg
+is specified, \fIaddress_id\fP must contain
+the address of a function of type
+.PN XtConvertArgProc .
+.LP
+.IN "XtConvertArgProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*);
+.br
+      Widget \fIobject\fP;
+.br
+      Cardinal *\fIsize\fP;
+.br
+      XrmValue *\fIvalue\fP;
+.FN
+.IP \fIobject\fP 1i
+Passes the object for which the resource is being
+converted, or NULL if the converter was invoked by
+.PN XtCallConverter
+or
+.PN XtDirectConvert .
+.IP \fIsize\fP 1i
+Passes a pointer to the \fIsize\fP field from the
+.PN XtConvertArgRec .
+.IP \fIvalue\fP 1i
+Passes a pointer to a descriptor into which the procedure
+must store the conversion argument.
+.LP
+.eM
+When invoked, the
+.PN XtConvertArgProc
+procedure must derive a conversion
+argument and store the address and size of the argument in the location
+pointed to by \fIvalue\fP.
+.LP
+In order to permit reentrancy, the
+.PN XtConvertArgProc
+should return the address of storage whose lifetime is no shorter than the
+lifetime of \fIobject\fP.  If \fIobject\fP is NULL, the lifetime of the conversion
+argument must be no shorter than the lifetime of the resource with
+which the conversion argument is associated.  The \*(xI do not
+guarantee to copy this storage but do guarantee not to reference it if
+the resource is removed from the conversion cache.
+.LP
+The following example illustrates how to register the CvtStringToPixel 
+routine given earlier:
+.LP
+.Ds
+.TA .2i 3i
+.ta .2i 3i
+static XtConvertArgRec colorConvertArgs[] = {
+	{XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.screen),  sizeof(Screen*)},
+	{XtWidgetBaseOffset, (XtPointer)XtOffset(Widget, core.colormap),sizeof(Colormap)}
+};
+
+XtSetTypeConverter(XtRString, XtRPixel, CvtStringToPixel,
+    colorConvertArgs, XtNumber(colorConvertArgs), XtCacheByDisplay, NULL);
+.De
+.LP
+The conversion argument descriptors
+.PN colorConvertArgs
+and
+.PN screenConvertArg
+are predefined by the \*(xI.  Both take the
+values from the closest windowed ancestor if the object is not of a
+subclass of
+Core.
+The
+.PN screenConvertArg
+descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0].  The
+.PN colorConvertArgs
+descriptor puts the widget's \fIscreen\fP field into \fIargs\fP[0],
+and the widget's \fIcolormap\fP field into \fIargs\fP[1].
+.LP
+Conversion routines should not just put a descriptor for the address of the
+base of the widget into \fIargs\fP[0], and use that in the routine.
+They should pass in the actual values on which the conversion depends.
+By keeping the dependencies of the conversion procedure specific,
+it is more likely that subsequent conversions will find what they need
+in the conversion cache.
+This way the cache is smaller and has fewer and more widely applicable entries.
+.LP
+If any conversion arguments of type
+.PN XtBaseOffset ,
+.PN XtResourceString ,
+.PN XtResourceQuark ,
+and
+.PN XtWidgetBaseOffset
+are specified for conversions performed by
+.PN XtGetApplicationResources ,
+.PN XtGetSubresources ,
+.PN XtVaGetApplicationResources ,
+or
+.PN XtVaGetSubresources ,
+the arguments are
+computed with respect to the specified widget, not the base address or
+resource list specified in the call.
+.LP
+If the
+.PN XtConvertArgProc
+modifies the resource database,
+the changes affect any in-progress widget creation,
+.PN XtGetApplicationResources ,
+or
+.PN XtGetSubresources
+in an implementation-defined manner; however, insertion of new entries
+or changes to existing entries are allowed and will not directly cause
+an error.
+
+.NH 3
+Resource Converter Invocation
+.XS
+\fB\*(SN Resource Converter Invocation\fP
+.XE
+.LP
+All resource-fetching routines (for example,
+.PN XtGetSubresources ,
+.PN XtGetApplicationResources ,
+and so on) call resource converters if the resource database or
+varargs list specifies a value
+that has a different representation from the desired representation or if the
+widget's default resource value representation is different from the desired
+representation.
+.sp
+.LP
+To invoke explicit resource conversions, use
+.PN XtConvertAndStore
+or
+.PN XtCallConverter .
+.LP
+.sM
+.Ds 0
+typedef XtPointer XtCacheRef;
+.De
+.IN "XtCallConverter" "" "@DEF@"
+.FD 0
+Boolean XtCallConverter(\fIdisplay\fP, \fIconverter\fP, \
+\fIconversion_args\fP, \fInum_args\fP, \fIfrom\fP, \fIto_in_out\fP,
+                                              \fIcache_ref_return\fP)
+.br
+      Display* \fIdisplay\fP;
+.br
+      XtTypeConverter \fIconverter\fP;
+.br
+      XrmValuePtr \fIconversion_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.br
+      XrmValuePtr \fIfrom\fP;
+.br
+      XrmValuePtr \fIto_in_out\fP;
+.br
+      XtCacheRef *\fIcache_ref_return\fP;
+.FN
+.IP \fIdisplay\fP 1.5i
+Specifies the display with which the conversion is to be associated.
+.IP \fIconverter\fP 1.5i
+Specifies the conversion procedure to be called.
+.IP \fIconversion_args\fP 1.5i
+Specifies the additional conversion arguments needed
+to perform the conversion, or NULL.
+.IP \fInum_args\fP 1.5i
+Specifies the number of entries in \fIconversion_args\fP.
+.IP \fIfrom\fP 1.5i
+Specifies a descriptor for the source value.
+.IP \fIto_in_out\fP 1.5i
+Returns the converted value.
+.IP \fIcache_ref_return\fP 1.5i
+Returns a conversion cache id.
+.LP
+.eM
+The
+.PN XtCallConverter
+function looks up the
+specified type converter in the application context associated with
+the display and, if the converter was not registered or was registered
+with cache type
+.PN XtCacheAll
+or
+.PN XtCacheByDisplay ,
+looks in the conversion cache to see if this conversion procedure
+has been called with the specified conversion arguments.  If so, it
+checks the success status of the prior call, and if
+the conversion failed,
+.PN XtCallConverter
+returns
+.PN False
+immediately;
+otherwise it checks the size specified in the \fIto\fP argument, and, if it is
+greater than or equal to the size stored in the cache, copies the
+information stored in the cache into the location specified by
+\fIto->addr\fP, stores the cache size into \fIto->size\fP, and returns
+.PN True .
+If the size specified in the \fIto\fP argument is smaller than the size stored
+in the cache,
+.PN XtCallConverter
+copies the cache size into \fIto->size\fP and returns
+.PN False .
+If the converter was registered with cache type
+.PN XtCacheNone
+or no value was found in the conversion cache,
+.PN XtCallConverter
+calls the converter, and if it was not registered with cache type
+.PN XtCacheNone ,
+enters the result in the cache.  
+.PN XtCallConverter
+then returns what the converter returned.
+.LP
+The \fIcache_ref_return\fP field specifies storage allocated by the caller in which
+an opaque value will be stored.  If the type converter has been
+registered with the
+.PN XtCacheRefCount
+modifier and if the value returned
+in \fIcache_ref_return\fP is non-NULL, then the caller should store the
+\fIcache_ref_return\fP value in order to decrement the reference count when
+the converted value is no longer required.  The \fIcache_ref_return\fP
+argument should be
+NULL if the caller is unwilling or unable to store the
+value.
+.sp
+.LP
+To explicitly decrement the reference counts for resources obtained
+from
+.PN XtCallConverter ,
+use
+.PN XtAppReleaseCacheRefs .
+.LP
+.IN "XtAppReleaseCacheRefs" "" "@DEF@"
+.sM
+.FD 0
+void XtAppReleaseCacheRefs(\fIapp_context\fP, \fIrefs\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtCacheRef *\fIrefs\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIrefs\fP 1i
+Specifies the list of cache references to be released.
+.LP
+.eM
+.PN XtAppReleaseCacheRefs
+decrements the reference count for the
+conversion entries identified by the \fIrefs\fP argument.
+This argument is a
+pointer to a NULL-terminated list of
+.PN XtCacheRef
+values.  If any reference
+count reaches zero, the destructor, if any, will be called and
+the resource removed from the conversion cache.
+.sp
+.LP
+As a convenience to clients needing to explicitly decrement reference
+counts via a callback function, the \*(xI define two callback
+procedures,
+.PN XtCallbackReleaseCacheRef
+and
+.PN XtCallbackReleaseCacheRefList .
+.LP
+.IN "XtCallbackReleaseCacheRef" "" "@DEF@"
+.sM
+.FD 0
+void XtCallbackReleaseCacheRef(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object with which the resource is associated.
+.IP \fIclient_data\fP 1i
+Specifies the conversion cache entry to be released.
+.IP \fIcall_data\fP 1i
+Is ignored.
+.LP
+.eM
+This callback procedure may be added to a callback list to release a
+previously returned
+.PN XtCacheRef
+value.  When adding the callback, the
+callback \fIclient_data\fP argument must be specified as the value of the
+.PN XtCacheRef
+data cast to type
+.PN XtPointer .
+.LP
+.IN "XtCallbackReleaseCacheRefList" "" "@DEF@"
+.sM
+.FD 0
+void XtCallbackReleaseCacheRefList(\fIobject\fP, \fIclient_data\fP, \fIcall_data\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object with which the resources are associated.
+.IP \fIclient_data\fP 1i
+Specifies the conversion cache entries to be released.
+.IP \fIcall_data\fP 1i
+Is ignored.
+.LP
+.eM
+This callback procedure may be added to a callback list to release a
+list of previously returned
+.PN XtCacheRef
+values.  When adding the
+callback, the callback \fIclient_data\fP argument must be specified as a
+pointer to a NULL-terminated list of
+.PN XtCacheRef
+values.
+.sp
+.LP
+To lookup and call a resource converter, copy the resulting value,
+and free a cached resource when a widget is destroyed, use
+.PN XtConvertAndStore .
+.LP
+.IN "XtConvertAndStore" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtConvertAndStore(\fIobject\fP, \fIfrom_type\fP, \fIfrom\fP, \
+\fIto_type\fP, \fIto_in_out\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      String \fIfrom_type\fP;
+.br
+      XrmValuePtr \fIfrom\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XrmValuePtr \fIto_in_out\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object to use for additional arguments, if any are needed,
+and the destroy callback list.  \*(oI
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIfrom\fP 1i
+Specifies the value to be converted.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIto_in_out\fP 1i
+Specifies a descriptor for storage into which the converted value
+will be returned.
+.LP
+.eM
+The
+.PN XtConvertAndStore
+function looks up the type converter registered
+to convert \fIfrom_type\fP to \fIto_type\fP, computes any additional arguments
+needed, and then calls
+.PN XtCallConverter
+(or
+.PN XtDirectConvert
+if an old-style converter was registered with
+.PN XtAddConverter
+or
+.PN XtAppAddConverter ;
+see Appendix C) with the \fIfrom\fP and \fIto_in_out\fP arguments.  The
+\fIto_in_out\fP argument specifies the size and location into which the
+converted value will be stored and is passed directly to the
+converter.  If the location is specified as NULL, it will be replaced
+with a pointer to private storage and the size will be returned in the
+descriptor.  The caller is expected to copy this private storage
+immediately and must not modify it in any way.  If a non-NULL location
+is specified, the caller must allocate sufficient storage to hold the
+converted value and must also specify the size of that storage in the
+descriptor.
+The \fIsize\fP field will be modified on return to indicate the actual
+size of the converted data.
+If the conversion succeeds,
+.PN XtConvertAndStore
+returns
+.PN True ;
+otherwise, it returns
+.PN False .
+.LP
+.PN XtConvertAndStore
+adds
+.PN XtCallbackReleaseCacheRef
+.IN "destroyCallback"
+to the destroyCallback list of the specified object if the conversion
+returns an
+.PN XtCacheRef
+value.  The resulting resource should not be referenced
+after the object has been destroyed.
+.LP
+.PN XtCreateWidget
+performs processing equivalent to
+.PN XtConvertAndStore
+when initializing the object instance.  Because there is extra memory
+overhead required to implement reference counting, clients may
+distinguish those objects that are never destroyed before the
+application exits from those that may be destroyed and whose
+resources should be deallocated.
+.LP
+To specify whether reference counting is to be enabled for the
+resources of a particular object when the object is created, the
+client can specify a value for the
+.PN Boolean
+resource
+XtNinitialResourcesPersistent,
+.IN "XtNinitialResourcesPersistent" "" "@DEF@"
+class
+XtCInitialResourcesPersistent.
+.LP
+When
+.PN XtCreateWidget
+is called, if this resource is not specified as
+.PN False
+in either the arglist or the resource database, then the
+resources referenced by this object are not reference-counted, regardless of
+how the type converter may have been registered.  The effective
+default value is
+.PN True ;
+thus clients that expect to destroy one or
+more objects and want resources deallocated must explicitly specify
+.PN False
+for
+.IN XtNinitialResourcesPersistent
+XtNinitialResourcesPersistent.
+.LP
+The resources are still freed and destructors called when
+.PN XtCloseDisplay
+is called if the conversion was registered as
+.PN XtCacheByDisplay .
+
+.NH 2
+Reading and Writing Widget State
+.XS
+\fB\*(SN Reading and Writing Widget State\fP
+.XE
+.LP
+Any resource field in a widget can be read or written by a client.
+On a write operation,
+the widget decides what changes it will actually allow and updates all
+derived fields appropriately.
+
+.NH 3
+Obtaining Widget State
+.XS
+\fB\*(SN Obtaining Widget State\fP
+.XE
+.LP
+To retrieve the current values of resources associated with a
+widget instance, use
+.PN XtGetValues .
+.LP
+.IN "XtGetValues" "" "@DEF@"
+.sM
+.FD 0
+void XtGetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object whose resource values are to be returned.  \*(oI
+.IP \fIargs\fP 1i
+Specifies the argument list of name/address pairs that contain the
+resource names and the addresses into which the resource values are to
+be stored.
+The resource names are widget-dependent.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtGetValues
+function starts with the resources specified for the Object class
+and proceeds down the subclass chain to the class of the object.
+The \fIvalue\fP field of a passed argument list must contain the
+address into which to copy the contents of the corresponding
+object instance field.  If the field is a pointer type, the lifetime
+of the pointed-to data is defined by the object class.  For the
+\*(xI-defined resources, the following lifetimes apply:
+.IP \(bu 3
+Not valid following any operation that modifies the resource:
+.RS
+.IP \- 3
+XtNchildren resource of composite widgets.
+.IP \- 3
+All resources of representation type XtRCallback.
+.RE
+.IP \(bu 3
+Remain valid at least until the widget is destroyed:
+.RS
+.IP \- 3
+XtNaccelerators, XtNtranslations.
+.RE
+.IP \(bu 3
+Remain valid until the Display is closed:
+.RS
+.IP \- 3
+XtNscreen.
+.RE
+.LP
+It is the caller's responsibility
+to allocate and deallocate storage for the copied data
+according to the size of the
+resource representation type used within the object.
+.LP
+If the class of the object's parent is a subclass of
+.PN constraintWidgetClass ,
+.PN XtGetValues
+then fetches the values for any constraint resources requested.
+It starts with the constraint resources specified for
+.PN constraintWidgetClass
+and proceeds down the subclass chain to the parent's constraint resources.
+If the argument list contains a resource name that is not found in any of the
+resource lists searched, 
+the value at the corresponding address is not modified.
+.IN "get_values_hook procedure"
+If any get_values_hook procedures in the
+object's class or superclass records are non-NULL, 
+they are called in superclass-to-subclass order after
+all the resource values have been fetched by
+.PN XtGetValues .
+Finally, if the object's parent is a
+subclass of
+.PN constraintWidgetClass ,
+and if any of the parent's class or
+superclass records have declared
+.PN ConstraintClassExtension
+records in
+the Constraint class part \fIextension\fP field with a record type of
+.PN \s-1NULLQUARK\s+1 ,
+and if the \fIget_values_hook\fP field in the extension record is non-NULL,
+.PN XtGetValues
+calls the get_values_hook procedures in superclass-to-subclass order.
+This permits a Constraint parent to provide
+nonresource data via
+.PN XtGetValues .
+.LP
+Get_values_hook procedures may modify the data stored at the
+location addressed by the \fIvalue\fP field, including (but not
+limited to) making a copy of data whose resource representation is a
+pointer.  None of the \*(xI-defined object classes copy
+data in this manner.  Any operation that modifies the queried
+object resource may invalidate the pointed-to data.
+
+.sp
+.LP
+To retrieve the current values of resources associated with a widget
+instance using varargs lists, use
+.PN XtVaGetValues .
+.LP
+.IN "XtVaGetValues" "" "@DEF@"
+.sM
+.FD 0
+void XtVaGetValues(\fIobject\fP, ...)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object whose resource values are to be returned.  \*(oI
+.IP ... 1i
+Specifies the variable argument list for the resources to
+be returned.
+.LP
+.eM
+.PN XtVaGetValues
+is identical in function to
+.PN XtGetValues
+with the \fIargs\fP
+and \fInum_args\fP parameters replaced by a varargs list, as described in
+Section 2.5.1.  All value entries in the list must specify pointers to
+storage allocated by the caller to which the resource value will be
+copied.  It is the caller's responsibility to ensure that sufficient
+storage is allocated.  If
+.PN XtVaTypedArg
+is specified, the \fItype\fP argument
+specifies the representation desired by the caller and \fIthe\fP size argument
+specifies the number of bytes allocated to store the result of the
+conversion.  If the size is insufficient, a warning message is issued
+and the list entry is skipped.
+
+.NH 4
+Widget Subpart Resource Data: The get_values_hook Procedure
+.XS
+\*(SN Widget Subpart Resource Data: The get_values_hook Procedure
+.XE
+.LP
+Widgets that have subparts can return resource values from them through
+.PN XtGetValues
+by supplying a get_values_hook procedure.
+The get_values_hook procedure pointer is of type
+.PN XtArgsProc .
+.LP
+.IN "get_values_hook procedure" "" "@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 whose subpart resource values are to be retrieved.
+.IP \fIargs\fP 1i
+Specifies the argument list that was passed to
+.PN XtGetValues
+or the transformed varargs list passed to
+.PN XtVaGetValues .
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The widget with subpart resources should call
+.PN XtGetSubvalues
+in the get_values_hook procedure
+and pass in its subresource list and the \fIargs\fP and \fInum_args\fP parameters.
+
+.NH 4
+Widget Subpart State
+.XS
+\*(SN Widget Subpart State
+.XE
+.LP
+To retrieve the current values of subpart resource data associated with a
+widget instance, use
+.PN XtGetSubvalues .
+For a discussion of subpart resources,
+see Section 9.4.
+.LP
+.IN "XtGetSubvalues" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      XtPointer \fIbase\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIbase\fP 1i
+Specifies the base address of the subpart data structure for which the
+resources should be retrieved.
+.IP \fIresources\fP 1i
+Specifies the subpart resource list.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.IP \fIargs\fP 1i
+Specifies the argument list of name/address pairs that contain the
+resource names and the addresses into which the resource values are to
+be stored.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtGetSubvalues
+function obtains resource values from the structure identified by \fIbase\fP.
+The \fIvalue\fP field in each argument entry must contain the address into
+which to store the corresponding resource value.  It is the caller's
+responsibility to allocate and deallocate this storage according to
+the size of the resource representation type used within the subpart.
+If the argument list contains a resource name that is not found in the
+resource list, the value at the corresponding address is not modified.
+
+.sp
+.LP
+To retrieve the current values of subpart resources associated with
+a widget instance using varargs lists, use
+.PN XtVaGetSubvalues .
+.LP
+.IN "XtVaGetSubvalues" "" "@DEF@"
+.sM
+.FD 0
+void XtVaGetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...)
+.br
+      XtPointer \fIbase\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.FN
+.IP \fIbase\fP 1i
+Specifies the base address of the subpart data structure for which the
+resources should be retrieved.
+.IP \fIresources\fP 1i
+Specifies the subpart resource list.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.IP ... 1i
+Specifies a variable argument list of name/address pairs that
+contain the resource names and the addresses into which the resource
+values are to be stored.
+.LP
+.eM
+.PN XtVaGetSubvalues
+is identical in function to
+.PN XtGetSubvalues
+with the
+\fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as described
+in Section 2.5.1.
+.PN XtVaTypedArg
+is not supported for
+.PN XtVaGetSubvalues .
+If
+.PN XtVaTypedArg
+is specified in the list, a warning message is issued
+and the entry is then ignored.
+
+.NH 3
+Setting Widget State
+.XS
+\fB\*(SN Setting Widget State\fP
+.XE
+.LP
+To modify the current values of resources associated with a widget
+instance, use
+.PN XtSetValues .
+.LP
+.IN "XtSetValues" "" "@DEF@"
+.sM
+.FD 0
+void XtSetValues(\fIobject\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object whose resources are to be modified.  \*(oI
+.IP \fIargs\fP 1i
+Specifies the argument list of name/value pairs that contain the
+resources to be modified and their new values.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtSetValues
+function starts with the resources specified for the 
+Object
+class fields and proceeds down the subclass chain to the object.
+At each stage, it replaces the \fIobject\fP resource fields with any values
+specified in the argument list.
+.PN XtSetValues
+then calls the set_values procedures for the object in superclass-to-subclass 
+order.
+.IN "set_values_hook procedure"
+If the object has any non-NULL \fIset_values_hook\fP fields,
+these are called immediately after the
+corresponding set_values procedure.
+This procedure permits subclasses to set subpart data via
+.PN XtSetValues .
+.LP
+If the class of the object's parent is a subclass of
+.PN constraintWidgetClass ,
+.PN XtSetValues
+also updates the object's constraints.
+It starts with the constraint resources specified for
+.PN constraintWidgetClass
+and proceeds down the subclass chain to the parent's class.
+At each stage, it replaces the constraint resource fields with any
+values specified in the argument list.
+It then calls the constraint set_values procedures from
+.PN constraintWidgetClass
+down to the parent's class.
+The constraint set_values procedures are called with widget arguments,
+as for all set_values procedures, not just the constraint records,
+so that they can make adjustments to the desired values based
+on full information about the widget.  Any arguments specified that
+do not match a resource list entry are silently ignored.
+.LP
+If the object is of a subclass of
+RectObj,
+.PN XtSetValues
+determines if a geometry request is needed by comparing the old object to
+the new object.
+If any geometry changes are required,
+.PN XtSetValues
+restores the original geometry and makes the request on behalf of the widget.
+If the geometry manager returns
+.PN XtGeometryYes ,
+.PN XtSetValues
+calls the object's resize procedure.
+If the geometry manager returns
+.PN XtGeometryDone ,
+.PN XtSetValues
+continues, as the object's resize procedure should have been called
+by the geometry manager.
+If the geometry manager returns
+.PN XtGeometryNo ,
+.PN XtSetValues
+ignores the geometry request and continues.
+If the geometry manager returns
+.PN XtGeometryAlmost ,
+.PN XtSetValues
+calls the set_values_almost procedure,
+which determines what should be done.
+.PN XtSetValues
+then repeats this process,
+deciding once more whether the geometry manager should be called.
+.LP
+Finally, if any of the set_values procedures returned 
+.PN True ,
+and the widget is realized,
+.PN XtSetValues
+causes the widget's expose procedure to be invoked by calling
+.PN XClearArea
+on the widget's window.
+.sp
+.LP
+To modify the current values of resources associated with a widget
+instance using varargs lists, use
+.PN XtVaSetValues .
+.LP
+.IN "XtVaSetValues" "" "@DEF@"
+.sM
+.FD 0
+void XtVaSetValues(\fIobject\fP, ...)
+.br
+      Widget \fIobject\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object whose resources are to be modified.  \*(oI
+.IP ... 1i
+Specifies the variable argument list of name/value pairs that
+contain the resources to be modified and their new values.
+.LP
+.eM
+.PN XtVaSetValues
+is identical in function to
+.PN XtSetValues
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
+described in Section 2.5.1.
+
+.NH 4
+Widget State: The set_values Procedure
+.XS
+\*(SN Widget State: The set_values Procedure
+.XE
+.LP
+The set_values procedure pointer in a widget class is of type
+.PN XtSetValuesFunc .
+.LP
+.IN "XtSetValuesFunc" "" "@DEF@"
+.IN "set_values procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*);
+.br
+      Widget \fIcurrent\fP;
+.br
+      Widget \fIrequest\fP;
+.br
+      Widget \fInew\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.FN
+.IP \fIcurrent\fP 1i
+Specifies a copy of the widget as it was before the
+.PN XtSetValues
+call.
+.IP \fIrequest\fP 1i
+Specifies a copy of the widget with all values changed as asked for by the
+.PN XtSetValues
+call before any class set_values procedures have been called.
+.IP \fInew\fP 1i
+Specifies the widget with the new values that are actually allowed.
+.IP \fIargs\fP 1i
+Specifies the argument list passed to
+.PN XtSetValues
+or the transformed argument list passed to
+.PN XtVaSetValues .
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The set_values procedure should recompute any field
+derived from resources that are changed
+(for example, many GCs depend on foreground and background pixels).
+If no recomputation is necessary, and if none of the resources specific to a
+subclass require the window to be redisplayed when their values are changed,
+you can specify NULL for the \fIset_values\fP field in the class record.
+.LP
+Like the initialize procedure,
+set_values mostly deals only with the fields defined in the subclass,
+but it has to resolve conflicts with its superclass,
+especially conflicts over width and height.
+.LP
+Sometimes a subclass may want to overwrite values filled in by its
+superclass.
+In particular, size calculations of a superclass are often
+incorrect for a subclass, and, in this case,
+the subclass must modify or recalculate fields declared
+and computed by its superclass.
+.LP
+As an example,
+a subclass can visually surround its superclass display.
+In this case, the width and height calculated by the superclass set_values
+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.
+How does a subclass know the difference between a specified size
+and a size computed by a superclass?
+.LP
+The \fIrequest\fP and \fInew\fP parameters provide the necessary information.
+The \fIrequest\fP widget is a copy of the widget, updated as originally requested.
+The \fInew\fP widget starts with the values in the request,
+but it has additionally been updated by all superclass set_values
+procedures called so far.
+A subclass set_values procedure can compare these two to resolve
+any potential conflicts.
+The set_values procedure need not refer to the \fIrequest\fP widget
+unless it must resolve conflicts between the \fIcurrent\fP and \fInew\fP widgets.
+Any changes the widget needs to make, including geometry changes,
+should be made in the \fInew\fP widget.
+.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.
+In this case, zero is a special value defined by the class to permit
+the application to invoke this behavior.
+.LP
+The \fInew\fP widget is the actual widget instance record.
+Therefore,
+the set_values procedure should do all its work on the \fInew\fP widget;
+the \fIrequest\fP widget should never be modified.
+If the set_values procedure needs to call any routines that operate on
+a widget, it should specify \fInew\fP as the widget instance.
+.LP
+Before calling the set_values procedures, the \*(xI modify the
+resources of the \fIrequest\fP widget according to the contents of the arglist;
+if the widget names all its resources in the class resource list, it is
+never necessary to examine the contents of \fIargs\fP.
+.LP
+Finally, the set_values procedure must return a Boolean that indicates whether
+the widget needs to be redisplayed.
+Note that a change in the geometry fields alone does not require
+the set_values procedure to return 
+.PN True ;
+the X server will eventually generate an
+.PN Expose
+event, if necessary.
+After calling all the set_values procedures,
+.PN XtSetValues
+forces a redisplay by calling
+.PN XClearArea
+if any of the set_values procedures returned 
+.PN True .
+Therefore, a set_values procedure should not try to do its own redisplaying.
+.LP
+Set_values procedures should not do any work in response to changes in
+geometry because
+.PN XtSetValues
+eventually will perform a geometry request, and that request might be denied.
+If the widget actually changes size in response to a
+call to
+.PN XtSetValues ,
+its resize procedure is called.
+Widgets should do any geometry-related work in their resize procedure.
+.LP
+Note that it is permissible to call
+.PN XtSetValues
+before a widget is realized.
+Therefore, the set_values procedure must not assume that the widget is realized.
+
+.NH 4
+Widget State: The set_values_almost Procedure
+.XS
+\*(SN Widget State: The set_values_almost Procedure
+.XE
+.LP
+The set_values_almost procedure pointer in the widget class record is of type
+.PN XtAlmostProc .
+.LP
+.IN "set_values_almost procedure" "" "@DEF@"
+.IN "XtAlmostProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, \
+XtWidgetGeometry*);
+.br
+      Widget \fIold\fP;
+.br
+      Widget \fInew\fP;
+.br
+      XtWidgetGeometry *\fIrequest\fP;
+.br
+      XtWidgetGeometry *\fIreply\fP;
+.FN
+.IP \fIold\fP 1i
+Specifies a copy of the object as it was before the
+.PN XtSetValues
+call.
+.IP \fInew\fP 1i
+Specifies the object instance record.
+.IP \fIrequest\fP 1i
+Specifies the original geometry request that was sent to the geometry
+manager that caused
+.PN XtGeometryAlmost
+to be returned.
+.IP \fIreply\fP 1i
+Specifies the compromise geometry that was returned by the geometry
+manager with
+.PN XtGeometryAlmost .
+.LP
+.eM
+Most classes inherit the set_values_almost procedure from their superclass by
+specifying 
+.PN XtInheritSetValuesAlmost 
+in the class initialization.
+The
+set_values_almost procedure in
+.PN rectObjClass
+accepts the compromise suggested.
+.LP
+The set_values_almost procedure is called when a client tries to set a widget's
+geometry by means of a call to
+.PN XtSetValues
+and the geometry manager cannot
+satisfy the request but instead returns
+.PN XtGeometryNo
+or
+.PN XtGeometryAlmost
+and a compromise geometry.
+The \fInew\fP object is the actual instance record.  The \fIx\fP, \fIy\fP,
+\fIwidth\fP, \fIheight\fP,
+and \fIborder_width\fP fields contain the original values as they were
+before the
+.PN XtSetValues
+call, and all other fields contain the new
+values.  The \fIrequest\fP parameter contains the new geometry request that
+was made to the parent.  The \fIreply\fP parameter contains
+\fIreply->request_mode\fP equal to zero if the parent returned
+.PN XtGeometryNo
+and contains the parent's compromise geometry otherwise.  The
+set_values_almost procedure takes the original geometry and the 
+compromise geometry and determines if the compromise is
+acceptable or whether
+to try a different compromise.
+It returns its results in the \fIrequest\fP parameter,
+which is then sent back to the geometry manager for another try.
+To accept the compromise, the procedure must copy the contents
+of the \fIreply\fP geometry into the \fIrequest\fP geometry; to attempt an
+alternative geometry, the procedure may modify any part of the \fIrequest\fP
+argument; to terminate the geometry negotiation and retain the
+original geometry, the procedure must set \fIrequest->request_mode\fP to
+zero.  The geometry fields of the \fIold\fP and \fInew\fP instances must not be modified
+directly.
+
+.NH 4
+Widget State: The ConstraintClassPart set_values Procedure
+.XS
+\*(SN Widget State: The ConstraintClassPart set_values Procedure
+.XE
+.IN "set_values procedure"
+.LP
+The constraint set_values procedure pointer is of type
+.PN XtSetValuesFunc .
+The values passed to the parent's constraint set_values procedure
+are the same as those passed to the child's class
+set_values procedure.
+A class can specify NULL for the \fIset_values\fP field of the
+.PN ConstraintPart
+if it need not compute anything.
+.LP
+The constraint set_values procedure should recompute any constraint fields
+derived from constraint resources that are changed.
+Furthermore, it may modify other widget fields as appropriate.
+For example, if a constraint for the maximum height of a widget is changed
+to a value smaller than the widget's current height,
+the constraint set_values procedure may reset the \fIheight\fP field in the
+widget.
+
+.NH 4
+Widget Subpart State
+.XS
+\*(SN Widget Subpart State
+.XE
+.LP
+To set the current values of subpart resources associated with a
+widget instance, use
+.PN XtSetSubvalues .
+For a discussion of subpart resources,
+see Section 9.4.
+.LP
+.IN "XtSetSubvalues" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      XtPointer \fIbase\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIbase\fP 1i
+Specifies the base address of the subpart data structure into which the
+resources should be written.
+.IP \fIresources\fP 1i
+Specifies the subpart resource list.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.IP \fIargs\fP 1i
+Specifies the argument list of name/value pairs that contain the
+resources to be modified and their new values.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtSetSubvalues
+function updates the resource fields of the structure identified by
+\fIbase\fP.  Any specified arguments that do not match an entry in the
+resource list are silently ignored.
+.sp
+.LP
+To set the current values of subpart resources associated with
+a widget instance using varargs lists, use
+.PN XtVaSetSubvalues .
+.LP
+.IN "XtVaSetSubvalues" "" "@DEF@"
+.sM
+.FD 0 
+void XtVaSetSubvalues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, ...)
+.br
+      XtPointer \fIbase\fP;
+.br
+      XtResourceList \fIresources\fP;
+.br
+      Cardinal \fInum_resources\fP;
+.FN
+.IP \fIbase\fP 1i
+Specifies the base address of the subpart data structure into which the
+resources should be written.
+.IP \fIresources\fP 1i
+Specifies the subpart resource list.
+.IP \fInum_resources\fP 1i
+Specifies the number of entries in the resource list.
+.IP ... 1i
+Specifies the variable argument list of name/value pairs that
+contain the resources to be modified and their new values.
+.LP
+.eM
+.PN XtVaSetSubvalues
+is identical in function to
+.PN XtSetSubvalues
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
+described in Section 2.5.1.
+.PN XtVaTypedArg
+is not supported for
+.PN XtVaSetSubvalues .
+If an entry containing
+.PN XtVaTypedArg
+is specified in the list, a warning message is issued
+and the entry is ignored.
+
+.NH 4
+Widget Subpart Resource Data: The set_values_hook Procedure
+.XS
+\*(SN Widget Subpart Resource Data: The set_values_hook Procedure
+.XE
+.IN "set_values_hook procedure"
+.NT
+The set_values_hook procedure is obsolete, as the same information
+is now available to the set_values procedure.  The procedure has been
+retained for those widgets that used it in versions prior to Release 4.
+.NE
+.LP
+Widgets that have a subpart can set the subpart resource values through
+.PN XtSetValues
+by supplying a set_values_hook procedure.
+The set_values_hook procedure pointer in a widget class is of type
+.PN XtArgsFunc .
+.LP
+.IN "set_values_hook procedure" "" "@DEF@"
+.IN "XtArgsFunc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal*);
+.br
+      Widget \fIw\fP;
+.br
+      Arglist \fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget whose subpart resource values are to be changed.
+.IP \fIargs\fP 1i
+Specifies the argument list that was passed to
+.PN XtSetValues
+or the transformed varargs list passed to
+.PN XtVaSetValues .
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The widget with subpart resources may call
+.PN XtSetValues
+from the set_values_hook procedure
+and pass in its subresource list and the
+\fIargs\fP and \fInum_args\fP parameters.
+.bp
diff --git a/libXt/specs/CH10 b/libXt/specs/CH10
new file mode 100644
index 000000000..b7c0139ca
--- /dev/null
+++ b/libXt/specs/CH10
@@ -0,0 +1,1521 @@
+.\" $Xorg: CH10,v 1.3 2000/08/17 19:42:46 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 10\fP\s-1
+
+\s+1\fBTranslation Management\s-1 
+.sp 2
+.nr H1 10
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 10 \(em Translation Management 
+.XE
+Except under unusual circumstances,
+widgets do not hardwire the mapping of user events into widget behavior
+by using the event manager.
+Instead, they provide a default mapping of events into behavior
+that you can override.
+.LP
+The translation manager provides an interface to specify and manage the
+mapping of X event sequences into widget-supplied functionality,
+for example, calling procedure \fIAbc\fP when the \fIy\fP key 
+is pressed.
+.LP
+The translation manager uses two kinds of tables to perform translations:
+.IP \(bu 5
+The action tables, which are in the widget class structure,
+specify the mapping of externally available procedure name strings
+to the corresponding procedure implemented by the widget class.
+.IP \(bu 5
+A translation table, which is in the widget class structure,
+specifies the mapping of event sequences to procedure name strings.
+.LP
+You can override the translation table in the class structure 
+for a specific widget instance by supplying a different translation table
+for the widget instance.  The resources
+XtNtranslations and XtNbaseTranslations are used to modify the class
+default translation table; see Section 10.3.
+
+.NH 2
+Action Tables
+.XS
+\fB\*(SN Action Tables\fP
+.XE
+.LP
+All widget class records contain an action table,
+an array of
+.PN XtActionsRec
+entries.
+In addition,
+an application can register its own action tables with the translation manager
+so that the translation tables it provides to widget instances can access
+application functionality directly.
+The translation action procedure pointer is of type
+.PN XtActionProc .
+.LP
+.IN "action_proc procedure" "" "@DEF@"
+.IN "XtActionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*);
+.br
+      Widget \fIw\fP;
+.br
+      XEvent *\fIevent\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that caused the action to be called.
+.IP \fIevent\fP 1i
+Specifies the event that caused the action to be called.
+If the action is called after a sequence of events,
+then the last event in the sequence is used.
+.IP \fIparams\fP 1i
+Specifies a pointer to the list of strings that were specified
+in the translation table as arguments to the action, or NULL.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.IN "XtActionsRec"
+.IN "XtActionList"
+.LP
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _XtActionsRec {
+	String string;
+	XtActionProc proc;
+} XtActionsRec, *XtActionList;
+.De
+.LP
+.eM
+The \fIstring\fP field is the name used in translation tables to access
+the procedure.
+The \fIproc\fP field is a pointer to a procedure that implements
+the functionality.
+.LP
+When the action list is specified as the
+.PN CoreClassPart
+\fIactions\fP field, the string pointed to by \fIstring\fP must be
+permanently allocated prior to or during the execution of the class
+initialization procedure and must not be subsequently deallocated.
+.LP
+Action procedures should not assume that the widget in which they
+are invoked is realized; an accelerator specification can cause
+an action procedure to be called for a widget that does not yet
+have a window.  Widget writers should also note which of a widget's
+callback lists are invoked from action procedures and warn clients
+not to assume the widget is realized in those callbacks.
+.LP
+For example, a Pushbutton widget has procedures to take the following actions:
+.IP \(bu 5
+Set the button to indicate it is activated.
+.IP \(bu 5
+Unset the button back to its normal mode.
+.IP \(bu 5
+Highlight the button borders.
+.IP \(bu 5
+Unhighlight the button borders.
+.IP \(bu 5
+Notify any callbacks that the button has been activated.
+.LP
+The action table for the Pushbutton widget class makes these functions
+available to translation tables written for Pushbutton or any subclass.
+The string entry is the name used in translation tables.
+The procedure entry (usually spelled identically to the string)
+is the name of the C procedure that implements that function:
+.LP
+.IN "Action Table"
+.Ds
+.TA .5i 1.5i
+.ta .5i 1.5i
+XtActionsRec actionTable[] = {
+	{"Set",	Set},
+	{"Unset",	Unset},
+	{"Highlight",	Highlight},
+	{"Unhighlight",	Unhighlight}
+	{"Notify",	Notify},
+};
+.De
+.LP
+The \*(xI reserve all action names and parameters starting with
+the characters ``Xt'' for future standard enhancements.  Users,
+applications, and widgets should not declare action names or pass
+parameters starting with these characters except to invoke specified
+built-in \*(xI functions.
+
+.NH 3
+Action Table Registration
+.XS
+\fB\*(SN Action Table Registration\fP
+.XE
+.LP
+.IN "actions"
+The \fIactions\fP and \fInum_actions\fP fields of
+.PN CoreClassPart
+specify the actions implemented by a widget class.  These are
+automatically registered with the \*(xI when the class is initialized
+and must be allocated in writable storage prior to Core class_part
+initialization, and never deallocated.  To save memory and optimize
+access, the \*(xI may overwrite the storage in order to compile the
+list into an internal representation.
+.sp
+.LP
+To declare an action table within an application
+and register it with the translation manager, use
+.PN XtAppAddActions .
+.LP
+.IN "XtAppAddActions" "" "@DEF@"
+.sM
+.FD 0
+void XtAppAddActions(\fIapp_context\fP, \fIactions\fP, \fInum_actions\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtActionList \fIactions\fP;
+.br
+      Cardinal \fInum_actions\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIactions\fP 1i
+Specifies the action table to register.
+.IP \fInum_actions\fP 1i
+Specifies the number of entries in this action table.
+.LP
+.eM
+If more than one action is registered with the same name, 
+the most recently registered action is used.
+If duplicate actions exist in an action table,
+the first is used.
+The \*(xI register an action table containing
+.PN XtMenuPopup
+and
+.PN XtMenuPopdown
+as part of
+.PN XtCreateApplicationContext .
+
+.NH 3
+Action Names to Procedure Translations
+.XS
+\fB\*(SN Action Names to Procedure Translations\fP
+.XE
+.LP
+The translation manager uses a simple algorithm to resolve the name of
+a procedure specified in a translation table into the
+actual procedure specified
+in an action table.
+When the widget
+is realized, the translation manager
+performs a search for the name in the following tables, in order:
+.IP \(bu 5
+The widget's class and all superclass action tables, in subclass-to-superclass
+order.
+.IP \(bu 5
+The parent's class and all superclass action tables, in subclass-to-superclass
+order, then on up the ancestor tree.
+.IP \(bu 5
+The action tables registered with
+.PN XtAppAddActions
+and
+.PN XtAddActions
+from the most recently added table to the oldest table.
+.LP
+As soon as it finds a name,
+the translation manager stops the search.
+If it cannot find a name,
+the translation manager generates a warning message.
+
+.NH 3
+Action Hook Registration
+.XS
+\fB\*(SN Action Hook Registration\fP
+.XE
+.LP
+An application can specify a procedure that will be called just before
+every action routine is dispatched by the translation manager.  To do
+so, the application supplies a procedure pointer of type
+.PN XtActionHookProc .
+.LP
+.IN "XtActionHookProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, \
+String*, Cardinal*);
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      String \fIaction_name\fP;
+.br
+      XEvent* \fIevent\fP;
+.br
+      String* \fIparams\fP;
+.br
+      Cardinal* \fInum_params\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget whose action is about to be dispatched.
+.IP \fIclient_data\fP 1i
+Specifies the application-specific closure that was passed to
+.PN XtAppAddActionHook.
+.IP \fIaction_name\fP 1i
+Specifies the name of the action to be dispatched.
+.IP \fIevent\fP 1i
+Specifies the event argument that will be passed to the action routine.
+.IP \fIparams\fP 1i
+Specifies the action parameters that will be passed to the action routine.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+Action hooks should not modify any of the data pointed to by the
+arguments other than the \fIclient_data\fP argument.
+.sp
+.LP
+To add an action hook, use
+.PN XtAppAddActionHook .
+.LP
+.IN "XtAppAddActionHook" "" "@DEF@"
+.sM
+.FD 0
+XtActionHookId XtAppAddActionHook(\fIapp\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      XtAppContext \fIapp\fP;
+.br
+      XtActionHookProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIapp\fP 1i
+Specifies the application context.
+.IP \fIproc\fP 1i
+Specifies the action hook procedure.
+.IP \fIclient_data\fP 1i
+Specifies application-specific data to be passed to the action hook.
+.LP
+.eM
+.PN XtAppAddActionHook
+adds the specified procedure to the front of a list
+maintained in the application context.  In the future, when an action
+routine is about to be invoked for any widget in this application
+context, either through the translation manager or via
+.PN XtCallActionProc ,
+the action hook procedures will be called in reverse
+order of registration just prior to invoking the action routine.
+.LP
+Action hook procedures are removed automatically and the
+.PN XtActionHookId is
+destroyed when the application context in which
+they were added is destroyed.
+.sp
+.LP
+To remove an action hook procedure without destroying the application
+context, use
+.PN XtRemoveActionHook .
+.LP
+.IN "XtRemoveActionHook" "" "@DEF@"
+.sM
+.FD 0
+void XtRemoveActionHook(\fIid\fP)
+.br
+      XtActionHookId \fIid\fP;
+.FN
+.IP \fIid\fP 1i
+Specifies the action hook id returned by
+.PN XtAppAddActionHook .
+.LP
+.eM
+.PN XtRemoveActionHook
+removes the specified action hook procedure from
+the list in which it was registered.
+
+.NH 2
+Translation Tables
+.XS
+\fB\*(SN Translation Tables\fP
+.XE
+.LP
+All widget instance records contain a translation table,
+which is a resource with a default value specified elsewhere in the
+class record.
+A translation table specifies what action procedures are invoked for
+an event or a sequence of events.
+A translation table
+is a string containing a list of translations from an event sequence
+into one or more action procedure calls.
+The translations are separated from one another by newline characters
+(ASCII LF).
+The complete syntax of translation tables is specified in Appendix B.
+.LP
+As an example, the default behavior of Pushbutton is
+.IP \(bu 5
+Highlight on enter window.
+.IP \(bu 5
+Unhighlight on exit window.
+.IP \(bu 5
+Invert on left button down.
+.IP \(bu 5
+Call callbacks and reinvert on left button up.
+.LP
+The following illustrates Pushbutton's default translation table:
+.LP
+.IN "Translation tables"
+.Ds
+.TA .5i 1.5i
+.ta .5i 1.5i
+static String defaultTranslations =
+	"<EnterWindow>:	Highlight()\\n\\
+	<LeaveWindow>:	Unhighlight()\\n\\
+	<Btn1Down>:	Set()\\n\\
+	<Btn1Up>:	Notify() Unset()";
+.De
+.LP
+The \fItm_table\fP field of the
+.PN CoreClassPart
+should be filled in at class initialization time with
+the string containing the class's default translations.
+If a class wants to inherit its superclass's translations,
+it can store the special value
+.PN XtInheritTranslations
+into \fItm_table\fP.
+In Core's class part initialization procedure,
+the \*(xI compile this translation table into an efficient internal form.
+Then, at widget creation time,
+this default translation table is
+combined with the XtNtranslations
+and XtNbaseTranslations resources; see Section 10.3.
+.LP
+The resource conversion mechanism automatically compiles
+string translation tables that are specified in the resource database.
+If a client uses translation tables that are not retrieved via a
+resource conversion,
+it must compile them itself using
+.PN XtParseTranslationTable .
+.LP
+The \*(xI use the compiled form of the translation table to register the
+necessary events with the event manager.
+Widgets need do nothing other than specify the action and translation tables
+for events to be processed by the translation manager.
+
+.NH 3
+Event Sequences
+.XS
+\fB\*(SN Event Sequences\fP
+.XE
+.LP
+An event sequence is a comma-separated list of X event descriptions 
+that describes a specific sequence of X events to map to a set of 
+program actions. 
+Each X event description consists of three parts: 
+The X event type, a prefix consisting of the X modifier bits, and
+an event-specific suffix.
+.LP
+Various abbreviations are supported to make translation tables easier
+to read.  The events must match incoming events in left-to-right order
+to trigger the action sequence.
+
+.NH 3
+Action Sequences
+.XS
+\fB\*(SN Action Sequences\fP
+.XE
+.LP
+Action sequences specify what program or widget actions to take in response to
+incoming X events. An action sequence consists of space-separated
+action procedure call specifications.
+Each action procedure call consists of the name of an action procedure and a
+parenthesized list of zero or more comma-separated
+string parameters to pass to that procedure.
+The actions are invoked in left-to-right order as specified in the
+action sequence.
+
+.NH 3
+Multi-Click Time
+.XS
+\fB\*(SN Multi-Click Time\fP
+.XE
+.LP
+Translation table entries may specify actions that are taken when two
+or more identical events occur consecutively within a short time
+interval, called the multi-click time.  The multi-click time value may
+be specified as an application resource with name ``multiClickTime'' and
+.IN "multiClickTime" "" "@DEF@"
+.IN "Resources" "multiClickTime"
+class ``MultiClickTime'' and may also be modified dynamically by the
+application.  The multi-click time is unique for each Display value and
+is retrieved from the resource database by
+.PN XtDisplayInitialize .
+If no value is specified, the initial value is 200 milliseconds.
+.sp
+.LP
+To set the multi-click time dynamically, use
+.PN XtSetMultiClickTime .
+.LP
+.IN "XtSetMultiClickTime" "" "@DEF@"
+.sM
+.FD 0
+void XtSetMultiClickTime(\fIdisplay\fP, \fItime\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      int \fItime\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection.
+.IP \fItime\fP 1i
+Specifies the multi-click time in milliseconds.
+.LP
+.eM
+.PN XtSetMultiClickTime
+sets the time interval used by the translation
+manager to determine when multiple events are interpreted as a
+repeated event.  When a repeat count is specified in a translation
+entry, the interval between the timestamps in each pair of repeated
+events (e.g., between two
+.PN ButtonPress
+events) must be less than the
+multi-click time in order for the translation actions to be taken. 
+.sp
+.LP
+To read the multi-click time, use
+.PN XtGetMultiClickTime .
+.LP
+.IN "XtGetMultiClickTime" "" "@DEF@"
+.sM
+.FD 0
+int XtGetMultiClickTime(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection.
+.LP
+.eM
+.PN XtGetMultiClickTime
+returns the time in milliseconds that the
+translation manager uses to determine if multiple events are to be
+interpreted as a repeated event for purposes of matching a translation
+entry containing a repeat count.
+
+.NH 2
+Translation Table Management
+.XS
+\fB\*(SN Translation Table Management\fP
+.XE
+.LP
+Sometimes an application needs to merge
+its own translations with a widget's translations.
+For example, a window manager provides functions to move a window.
+The window manager wishes to bind this operation to a specific
+pointer button in the title bar without the possibility of user
+override and bind it to other buttons that may be overridden by the user.
+.LP
+To accomplish this,
+the window manager should first create the title bar
+and then should merge the two translation tables into
+the title bar's translations.
+One translation table contains the translations that the window manager
+wants only if the user has not specified a translation for a particular event
+or event sequence (i.e., those that may be overridden).
+The other translation table contains the translations that the
+window manager wants regardless of what the user has specified.
+.LP
+Three \*(xI functions support this merging:
+.TS
+lw(2i) lw(3.75i).
+T{
+.PN XtParseTranslationTable
+T}	T{
+Compiles a translation table.
+T}
+.sp
+T{
+.PN XtAugmentTranslations
+T}	T{
+Merges a compiled translation table into a widget's
+compiled translation table, ignoring any new translations that
+conflict with existing translations.
+T}
+.sp
+T{
+.PN XtOverrideTranslations
+T}	T{
+Merges a compiled translation table into a widget's
+compiled translation table, replacing any existing translations that
+conflict with new translations.
+T}
+.TE
+.sp
+.LP
+To compile a translation table, use
+.PN XtParseTranslationTable .
+.LP
+.IN "XtParseTranslationTable" "" "@DEF@"
+.sM
+.FD 0
+XtTranslations XtParseTranslationTable(\fItable\fP)
+.br
+      String \fItable\fP;
+.FN
+.IP \fItable\fP 1i
+Specifies the translation table to compile.
+.LP
+.eM
+The
+.PN XtParseTranslationTable
+function compiles the translation table, provided in the format given
+in Appendix B, into an opaque internal representation
+of type
+.PN XtTranslations .
+Note that if an empty translation table is required for any purpose,
+one can be obtained by calling
+.PN XtParseTranslationTable
+and passing an empty string.
+.sp
+.LP
+To merge additional translations into an existing translation table, use
+.PN XtAugmentTranslations .
+.LP
+.IN "XtAugmentTranslations" "" "@DEF@"
+.sM
+.FD 0
+void XtAugmentTranslations(\fIw\fP, \fItranslations\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtTranslations \fItranslations\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget into which the new translations are to be merged.  \*(cI
+.IP \fItranslations\fP 1i
+Specifies the compiled translation table to merge in.
+.LP
+.eM
+The
+.PN XtAugmentTranslations
+function merges the new translations into the existing widget
+translations, ignoring any
+.PN #replace ,
+.PN #augment ,
+or
+.PN #override
+directive that may have been specified
+in the translation string.  The translation table specified by
+\fItranslations\fP is not altered by this process.
+.PN XtAugmentTranslations
+logically appends the string representation of the new translations to
+the string representation of the widget's current translations and reparses
+the result with no warning messages about duplicate left-hand sides, then
+stores the result back into the widget instance; i.e.,
+if the new translations contain an event or event sequence that
+already exists in the widget's translations,
+the new translation is ignored.
+.sp
+.LP
+To overwrite existing translations with new translations, use
+.PN XtOverrideTranslations .
+.LP
+.IN "XtOverrideTranslations" "" "@DEF@"
+.sM
+.FD 0
+void XtOverrideTranslations(\fIw\fP, \fItranslations\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtTranslations \fItranslations\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget into which the new translations are to be merged. \*(cI
+.IP \fItranslations\fP 1i
+Specifies the compiled translation table to merge in.
+.LP
+.eM
+The
+.PN XtOverrideTranslations
+function merges the new translations into the existing widget
+translations, ignoring any
+.PN #replace ,
+.PN #augment ,
+or
+.PN #override
+directive that may have been
+specified in the translation string.  The translation table
+specified by \fItranslations\fP is not altered by this process.
+.PN XtOverrideTranslations
+logically appends the string representation of the widget's current
+translations to the string representation of the new translations and
+reparses the result with no warning messages about duplicate left-hand
+sides, then stores the result back into the widget instance; i.e.,
+if the new translations contain an event or event sequence that
+already exists in the widget's translations,
+the new translation overrides the widget's translation.
+.LP
+To replace a widget's translations completely, use
+.PN XtSetValues
+on the XtNtranslations resource and specify a compiled translation table
+as the value.
+.sp
+.LP
+To make it possible for users to easily modify translation tables in their
+resource files, 
+the string-to-translation-table resource type converter
+allows the string to specify whether the table should replace,
+augment, or override any
+existing translation table in the widget. 
+To specify this,
+a pound sign (#) is given as the first character of the table 
+followed by one of the keywords ``replace'', ``augment'', or
+``override'' to indicate
+whether to replace, augment, or override the existing table.
+The replace or merge
+operation is performed during the
+Core
+instance initialization.
+Each merge operation produces a new
+translation resource value; if the original tables were shared by
+other widgets, they are unaffected.  If no directive is
+specified, ``#replace'' is assumed.
+.LP
+At instance initialization
+the XtNtranslations resource is first fetched.  Then, if it was
+not specified or did not contain ``#replace'', the
+resource database is searched for the resource XtNbaseTranslations.
+If XtNbaseTranslations is found, it is merged into the widget class
+translation table.  Then the widget \fItranslations\fP field is
+merged into the result or into the class translation table if
+XtNbaseTranslations was not found.  This final table is then
+stored into the widget \fItranslations\fP field.  If the XtNtranslations
+resource specified ``#replace'', no merge is done.
+If neither XtNbaseTranslations or XtNtranslations are specified,
+the class translation table is copied into the widget instance.
+.sp
+.LP
+To completely remove existing translations, use
+.PN XtUninstallTranslations .
+.LP
+.IN "XtUninstallTranslations" "" "@DEF@"
+.sM
+.FD 0
+void XtUninstallTranslations(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget from which the translations are to be removed.   \*(cI
+.LP
+.eM
+The
+.PN XtUninstallTranslations
+function causes the entire translation table for the widget to be removed.
+
+.NH 2
+Using Accelerators
+.XS
+\fB\*(SN Using Accelerators\fP
+.XE
+.LP
+It is often desirable to be able to bind events in one widget to actions in
+another.
+In particular,
+it is often useful to be able to invoke menu actions from the keyboard.
+The \*(xI provide a facility, called accelerators, that lets you 
+accomplish this.
+.IN "Accelerator" "" "@DEF@"
+An accelerator table is a translation table that is bound with its
+actions in the context of a particular widget, the \fIsource\fP widget.
+The accelerator table can then be installed on one or more \fIdestination\fP widgets.
+When an event sequence in the destination widget would cause an
+accelerator action to be taken, and if the source widget is sensitive,
+the actions are executed as though triggered by the same event sequence
+in the accelerator source
+widget.  The event is
+passed to the action procedure without modification.  The action
+procedures used within accelerators must not assume that the source
+widget is realized nor that any fields of the event are in reference
+to the source widget's window if the widget is realized.
+.LP
+Each widget instance contains that widget's exported accelerator table
+as a resource.
+Each class of widget exports a method that takes a
+displayable string representation of the accelerators
+so that widgets can display their current accelerators.
+The representation is the accelerator table in canonical
+translation table form (see Appendix B).
+The display_accelerator procedure pointer is of type
+.PN XtStringProc .
+.LP
+.IN "display_accelerator procedure" "" "@DEF@"
+.IN "XtStringProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtStringProc)(Widget, String);
+.br
+      Widget \fIw\fP;
+.br
+      String \fIstring\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the source widget that supplied the accelerators.
+.IP \fIstring\fP 1i
+Specifies the string representation of the accelerators for this widget.
+.LP
+.eM
+Accelerators can be specified in resource files, 
+and the string representation is the same as for a translation table.
+However,
+the interpretation of the
+.PN #augment
+and
+.PN #override
+directives applies to
+what will happen when the accelerator is installed;
+that is, whether or not the accelerator translations will override the
+translations in the destination widget.
+The default is
+.PN #augment ,
+which means that the accelerator translations have lower priority
+than the destination translations.
+The
+.PN #replace
+directive is ignored for accelerator tables.
+.sp
+.LP
+To parse an accelerator table, use
+.PN XtParseAcceleratorTable .
+.LP
+.IN "XtParseAcceleratorTable" "" "@DEF@"
+.sM
+.FD 0
+XtAccelerators XtParseAcceleratorTable(\fIsource\fP)
+.br
+      String \fIsource\fP;
+.FN
+.IP \fIsource\fP 1i
+Specifies the accelerator table to compile.
+.LP
+.eM
+The
+.PN XtParseAcceleratorTable
+function compiles the accelerator table into an opaque internal representation.
+The client
+should set the XtNaccelerators resource of
+each widget that is to be activated by these translations
+to the returned value.
+.sp
+.LP
+To install accelerators from a widget on another widget, use
+.PN XtInstallAccelerators .
+.LP
+.IN "XtInstallAccelerators" "" "@DEF@"
+.sM
+.FD 0
+void XtInstallAccelerators(\fIdestination\fP, \fIsource\fP)
+.br
+      Widget \fIdestination\fP;
+.br
+      Widget \fIsource\fP;
+.FN
+.IP \fIdestination\fP 1i
+Specifies the widget on which the accelerators are to be installed.  \*(cI
+.IP \fIsource\fP 1i
+Specifies the widget from which the accelerators are to come.  \*(cI
+.LP
+.eM
+The
+.PN XtInstallAccelerators
+function installs the \fIaccelerators\fP resource value from
+\fIsource\fP onto \fIdestination\fP
+by merging the source accelerators into the destination translations.
+If the source \fIdisplay_accelerator\fP field is non-NULL, 
+.PN XtInstallAccelerators
+calls it with the source widget and a string representation 
+of the accelerator table,
+which indicates that its accelerators have been installed 
+and that it should display them appropriately.
+The string representation of the accelerator table is its
+canonical translation table representation.
+.sp
+.LP
+As a convenience for installing all accelerators from a widget and all its
+descendants onto one destination, use
+.PN XtInstallAllAccelerators .
+.LP
+.IN "XtInstallAllAccelerators" "" "@DEF@"
+.sM
+.FD 0
+void XtInstallAllAccelerators(\fIdestination\fP, \fIsource\fP)
+.br
+      Widget \fIdestination\fP;
+.br
+      Widget \fIsource\fP;
+.FN
+.IP \fIdestination\fP 1i
+Specifies the widget on which the accelerators are to be installed.  \*(cI
+.IP \fIsource\fP 1i
+Specifies the root widget of the widget tree
+from which the accelerators are to come.  \*(cI
+.LP
+.eM
+The
+.PN XtInstallAllAccelerators
+function recursively descends the widget tree rooted at \fIsource\fP 
+and installs the accelerators resource value
+of each widget encountered onto \fIdestination\fP.
+A common use is to call
+.PN XtInstallAllAccelerators
+and pass the application main window as the source.
+
+.NH 2
+KeyCode-to-KeySym Conversions
+.XS
+\*(SN KeyCode-to-KeySym Conversions
+.XE
+.LP
+The translation manager provides support for automatically translating
+KeyCodes in incoming key events into KeySyms.
+KeyCode-to-KeySym translator procedure pointers are of type
+.PN XtKeyProc .
+.LP
+.IN "XtKeyProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, \
+KeySym*);
+.br
+      Display *\fIdisplay\fP;
+.br
+      KeyCode \fIkeycode\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.br
+      Modifiers *\fImodifiers_return\fP;
+.br
+      KeySym *\fIkeysym_return\fP;
+.FN
+.IP \fIdisplay\fP 1.1i
+Specifies the display that the KeyCode is from.
+.IP \fIkeycode\fP 1.1i
+Specifies the KeyCode to translate.
+.IP \fImodifiers\fP 1.1i
+Specifies the modifiers to the KeyCode.
+.IP \fImodifiers_return\fP 1.1i
+Specifies a location in which to store
+a mask that indicates the subset of all
+modifiers that are examined by the key translator for the specified keycode.
+.IP \fIkeysym_return\fP 1.1i
+Specifies a location in which to store the resulting KeySym.
+.LP
+.eM
+This procedure takes a KeyCode and modifiers and produces a KeySym.
+For any given key translator function and keyboard encoding,
+\fImodifiers_return\fP will be a constant per KeyCode that indicates
+the subset of all modifiers that are examined by the key translator
+for that KeyCode.
+.LP
+The KeyCode-to-KeySym translator procedure
+must be implemented such that multiple calls with the same
+\fIdisplay\fP, \fIkeycode\fP, and \fImodifiers\fP return the same
+result until either a new case converter, an
+.PN XtCaseProc ,
+is installed or a
+.PN MappingNotify
+event is received.
+
+.sp
+.LP
+The \*(xI maintain tables internally to map KeyCodes to KeySyms
+for each open display.  Translator procedures and other clients may
+share a single copy of this table to perform the same mapping.
+.LP
+To return a pointer to the KeySym-to-KeyCode mapping table for a
+particular display, use
+.PN XtGetKeysymTable .
+.LP
+.IN "XtGetKeysymTable" "" "@DEF@"
+.sM
+.FD 0
+KeySym *XtGetKeysymTable(\fIdisplay\fP, \fImin_keycode_return\fP, \
+\fIkeysyms_per_keycode_return\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      KeyCode *\fImin_keycode_return\fP;
+.br
+      int *\fIkeysyms_per_keycode_return\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display whose table is required.
+.IP \fImin_keycode_return\fP 1i
+Returns the minimum KeyCode valid for the display.
+.IP \fIkeysyms_per_keycode_return\fP 1i
+Returns the number of KeySyms stored for each KeyCode.
+.LP
+.eM
+.PN XtGetKeysymTable
+returns a pointer to the \*(xI' copy of the
+server's KeyCode-to-KeySym table.  This table must not be modified.
+There are \fIkeysyms_per_keycode_return\fP KeySyms associated with each
+KeyCode, located in the table with indices starting at index
+.IP
+    (test_keycode - min_keycode_return) * keysyms_per_keycode_return
+.LP
+for KeyCode \fItest_keycode\fP.  Any entries that have no KeySyms associated
+with them contain the value
+.PN NoSymbol .
+Clients should not cache the KeySym table but should call
+.PN XtGetKeysymTable
+each time the value is
+needed, as the table may change prior to dispatching each event.
+.LP
+For more information on this table, see Section 12.7 in \fI\*(xL\fP.
+.sp
+.LP
+To register a key translator, use
+.PN XtSetKeyTranslator .
+.LP
+.IN "XtSetKeyTranslator" "" "@DEF@"
+.sM
+.FD 0
+void XtSetKeyTranslator(\fIdisplay\fP, \fIproc\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      XtKeyProc \fIproc\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display from which to translate the events.
+.IP \fIproc\fP 1i
+Specifies the procedure to perform key translations.
+.LP
+.eM
+The
+.PN XtSetKeyTranslator
+function sets the specified procedure as the current key translator.
+The default translator is 
+.PN XtTranslateKey ,
+an
+.PN XtKeyProc
+that uses the Shift, Lock, numlock, and group modifiers
+with the interpretations defined in \fI\*(xP\fP, Section 5.
+It is provided so that new translators can call it to get default 
+KeyCode-to-KeySym translations and so that the default translator 
+can be reinstalled.
+.sp
+.LP
+To invoke the currently registered KeyCode-to-KeySym translator,
+use
+.PN XtTranslateKeycode .
+.LP
+.IN "XtTranslateKeycode" "" "@DEF@"
+.sM
+.FD 0
+void XtTranslateKeycode(\fIdisplay\fP, \fIkeycode\fP, \fImodifiers\fP, \
+\fImodifiers_return\fP, \fIkeysym_return\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      KeyCode \fIkeycode\fP;
+.br
+      Modifiers \fImodifiers\fP;
+.br
+      Modifiers *\fImodifiers_return\fP;
+.br
+      KeySym *\fIkeysym_return\fP;
+.FN
+.IP \fIdisplay\fP 1.1i
+Specifies the display that the KeyCode is from.
+.IP \fIkeycode\fP 1.1i
+Specifies the KeyCode to translate.
+.IP \fImodifiers\fP 1.1i
+Specifies the modifiers to the KeyCode.
+.IP \fImodifiers_return\fP 1.1i
+Returns a mask that indicates the modifiers actually used 
+to generate the KeySym.
+.IP \fIkeysym_return\fP 1.1i
+Returns the resulting KeySym.
+.LP
+.eM
+The
+.PN XtTranslateKeycode
+function passes the specified arguments 
+directly to the currently registered KeyCode-to-KeySym translator.
+.sp
+.LP
+To handle capitalization of nonstandard KeySyms, the \*(xI allow
+clients to register case conversion routines.
+Case converter procedure pointers are of type
+.PN XtCaseProc .
+.LP
+.IN "XtCaseProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*);
+.br
+      Display *\fIdisplay\fP;
+.br
+      KeySym \fIkeysym\fP;
+.br
+      KeySym *\fIlower_return\fP;
+.br
+      KeySym *\fIupper_return\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection for which the conversion is required.
+.IP \fIkeysym\fP 1i
+Specifies the KeySym to convert.
+.IP \fIlower_return\fP 1i
+Specifies a location into which to store the lowercase equivalent for
+the KeySym.
+.IP \fIupper_return\fP 1i
+Specifies a location into which to store the uppercase equivalent for
+the KeySym.
+.LP
+.eM
+If there is no case distinction, 
+this procedure should store the KeySym into both return values.
+.sp
+.LP
+To register a case converter, use
+.PN XtRegisterCaseConverter .
+.LP
+.IN "XtRegisterCaseConverter" "" "@DEF@"
+.sM
+.FD 0
+void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP)
+.br
+    Display *\fIdisplay\fP;
+.br
+    XtCaseProc \fIproc\fP;
+.br
+    KeySym \fIstart\fP;
+.br
+    KeySym \fIstop\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display from which the key events are to come.
+.IP \fIproc\fP 1i
+Specifies the 
+.PN XtCaseProc 
+to do the conversions.
+.IP \fIstart\fP 1i
+Specifies the first KeySym for which this converter is valid.
+.IP \fIstop\fP 1i
+Specifies the last KeySym for which this converter is valid.
+.LP
+.eM
+The
+.PN XtRegisterCaseConverter
+registers the specified case converter.
+The \fIstart\fP and \fIstop\fP arguments provide the inclusive range of KeySyms 
+for which this converter is to be called.
+The new converter overrides any previous converters for KeySyms in that range.
+No interface exists to remove converters; 
+you need to register an identity converter.
+When a new converter is registered,
+the \*(xI  refresh the keyboard state if necessary.
+The default converter understands case conversion for all
+Latin KeySyms defined in \fI\*(xP\fP, Appendix A.
+.sp
+.LP
+To determine uppercase and lowercase equivalents for a KeySym, use
+.PN XtConvertCase .
+.LP
+.IN "XtConvertCase" "" "@DEF@"
+.sM
+.FD 0
+void XtConvertCase(\fIdisplay\fP, \fIkeysym\fP, \fIlower_return\fP, \
+\fIupper_return\fP)
+.br
+    Display *\fIdisplay\fP;
+.br
+    KeySym \fIkeysym\fP;
+.br
+    KeySym *\fIlower_return\fP;
+.br
+    KeySym *\fIupper_return\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display that the KeySym came from.
+.IP \fIkeysym\fP 1i
+Specifies the KeySym to convert.
+.IP \fIlower_return\fP 1i
+Returns the lowercase equivalent of the KeySym.
+.IP \fIupper_return\fP 1i
+Returns the uppercase equivalent of the KeySym.
+.LP
+.eM
+The
+.PN XtConvertCase
+function calls the appropriate converter and returns the results.
+A user-supplied
+.PN XtKeyProc 
+may need to use this function.
+
+.NH 2
+Obtaining a KeySym in an Action Procedure
+.XS
+\fB\*(SN Obtaining a KeySym in an Action Procedure\fP
+.XE
+.LP
+When an action procedure is invoked on a
+.PN KeyPress
+or
+.PN KeyRelease
+event, it often has a need to retrieve the KeySym and modifiers
+corresponding to the event that caused it to be invoked.  In order to
+avoid repeating the processing that was just performed by the
+\*(xI to match the translation entry, the KeySym and modifiers
+are stored for the duration of the action procedure and are made
+available to the client.
+.LP
+To retrieve the KeySym and modifiers that matched the final event
+specification in the translation table entry, use
+.PN XtGetActionKeysym .
+.LP
+.IN "XtGetActionKeysym" "" "@DEF@"
+.sM
+.FD 0
+KeySym XtGetActionKeysym(\fIevent\fP, \fImodifiers_return\fP)
+.br
+      XEvent *\fIevent\fP;
+.br
+      Modifiers *\fImodifiers_return\fP;
+.FN
+.IP \fIevent\fP 1.25i
+Specifies the event pointer passed to the action procedure by the \*(xI.
+.IP \fImodifiers_return\fP 1.25i
+Returns the modifiers that caused the match, if non-NULL.
+.LP
+.eM
+If
+.PN XtGetActionKeysym
+is called after an action procedure has been
+invoked by the \*(xI and before that action procedure returns, and
+if the event pointer has the same value as the event pointer passed to
+that action routine, and if the event is a
+.PN KeyPress
+or
+.PN KeyRelease
+event, then
+.PN XtGetActionKeysym
+returns the KeySym that matched the final
+event specification in the translation table and, if \fImodifiers_return\fP
+is non-NULL, the modifier state actually used to generate this KeySym;
+otherwise, if the event is a
+.PN KeyPress
+or
+.PN KeyRelease
+event, then
+.PN XtGetActionKeysym
+calls
+.PN XtTranslateKeycode
+and returns the results;
+else it returns
+.PN NoSymbol
+and does not examine \fImodifiers_return\fP.
+.LP
+Note that if an action procedure invoked by the \*(xI
+invokes a subsequent action procedure (and so on) via
+.PN XtCallActionProc ,
+the nested action procedure may also call
+.PN XtGetActionKeysym
+to retrieve the \*(xI' KeySym and modifiers.
+
+.NH 2
+KeySym-to-KeyCode Conversions
+.XS
+\*(SN KeySym-to-KeyCode Conversions
+.XE
+.LP
+To return the list of KeyCodes that map to a particular KeySym in
+the keyboard mapping table maintained by the \*(xI, use
+.PN XtKeysymToKeycodeList .
+.LP
+.IN "XtKeysymToKeycodeList" "" "@DEF@"
+.sM
+.FD 0
+void XtKeysymToKeycodeList(\fIdisplay\fP, \fIkeysym\fP, \fIkeycodes_return\fP, \
+\fIkeycount_return\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      KeySym \fIkeysym\fP;
+.br
+      KeyCode **\fIkeycodes_return\fP;
+.br
+      Cardinal *\fIkeycount_return\fP;
+.FN
+.IP \fIdisplay\fP 1.25i
+Specifies the display whose table is required.
+.IP \fIkeysym\fP 1.25i
+Specifies the KeySym for which to search.
+.IP \fIkeycodes_return\fP 1.25i
+Returns a list of KeyCodes that have \fIkeysym\fP
+associated with them, or NULL if \fIkeycount_return\fP is 0.
+.IP \fIkeycount_return\fP 1.25i
+Returns the number of KeyCodes in the keycode list.
+.LP
+.eM
+The
+.PN XtKeysymToKeycodeList
+procedure returns all the KeyCodes that have \fIkeysym\fP
+in their entry for the keyboard mapping table associated with \fIdisplay\fP.
+For each entry in the
+table, the first four KeySyms (groups 1 and 2) are interpreted as
+specified by \fI\*(xP\fP, Section 5.  If no KeyCodes map to the
+specified KeySym, \fIkeycount_return\fP is zero and *\fIkeycodes_return\fP is NULL.
+.LP
+The caller should free the storage pointed to by \fIkeycodes_return\fP using
+.PN XtFree
+when it is no longer useful.  If the caller needs to examine
+the KeyCode-to-KeySym table for a particular KeyCode, it should call
+.PN XtGetKeysymTable .
+
+.NH 2
+Registering Button and Key Grabs for Actions
+.XS
+\fB\*(SN Registering Button and Key Grabs for Actions\fP
+.XE
+.LP
+To register button and key grabs for a widget's window according to the
+event bindings in the widget's translation table, use
+.PN XtRegisterGrabAction .
+.LP
+.IN "XtRegisterGrabAction" "" "@DEF@"
+.sM
+.FD 0
+void XtRegisterGrabAction(\fIaction_proc\fP, \fIowner_events\fP, \
+\fIevent_mask\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
+.br
+      XtActionProc \fIaction_proc\fP;
+.br
+      Boolean \fIowner_events\fP;
+.br
+      unsigned int \fIevent_mask\fP;
+.br
+      int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
+.FN
+.IP \fIaction_proc\fP 1i
+Specifies the action procedure to search for in translation tables.
+.sp
+.IP \fIowner_events\fP
+.br
+.ns
+.IP \fIevent_mask\fP
+.br
+.ns
+.IP \fIpointer_mode\fP
+.br
+.ns
+.IP \fIkeyboard_mode\fP 1i
+Specify arguments to
+.PN XtGrabButton
+or 
+.PN XtGrabKey .
+.LP
+.eM
+.PN XtRegisterGrabAction
+adds the specified \fIaction_proc\fP to a list known to
+the translation manager.  When a widget is realized, or when the
+translations of a realized widget or the accelerators installed on a
+realized widget are modified, its translation table and any installed
+accelerators are scanned for action procedures on this list.
+If any are invoked on
+.PN ButtonPress
+or
+.PN KeyPress
+events as the only or final event
+in a sequence, the \*(xI will call
+.PN XtGrabButton
+or
+.PN XtGrabKey
+for the widget with every button or KeyCode which maps to the
+event detail field, passing the specified \fIowner_events\fP, \fIevent_mask\fP,
+\fIpointer_mode\fP, and \fIkeyboard_mode\fP.  For
+.PN ButtonPress
+events, the modifiers
+specified in the grab are determined directly from the translation
+specification and \fIconfine_to\fP and \fIcursor\fP are specified as
+.PN None .
+For
+.PN KeyPress
+events, if the translation table entry specifies colon (:) in
+the modifier list, the modifiers are determined by calling the key
+translator procedure registered for the display and calling
+.PN XtGrabKey
+for every combination of standard modifiers which map the KeyCode to
+the specified event detail KeySym, and ORing any modifiers specified in
+the translation table entry, and \fIevent_mask\fP is ignored.  If the
+translation table entry does not specify colon in the modifier list,
+the modifiers specified in the grab are those specified in the
+translation table entry only.  For both
+.PN ButtonPress
+and
+.PN KeyPress
+events, don't-care modifiers are ignored unless the translation entry
+explicitly specifies ``Any'' in the \fImodifiers\fP field.
+.LP
+If the specified \fIaction_proc\fP is already registered for the calling
+process, the new values will replace the previously specified values
+for any widgets that become realized following the call, but existing
+grabs are not altered on currently realized widgets.
+.LP
+When translations or installed accelerators are modified for a
+realized widget, any previous key or button grabs registered
+as a result of the old bindings are released if they do not appear in
+the new bindings and are not explicitly grabbed by the client with
+.PN XtGrabKey
+or
+.PN XtGrabButton .
+
+.NH 2
+Invoking Actions Directly
+.XS
+\fB\*(SN Invoking Actions Directly\fP
+.XE
+.LP
+Normally action procedures are invoked by the \*(xI when an
+event or event sequence arrives for a widget. To
+invoke an action procedure directly, without generating
+(or synthesizing) events, use
+.PN XtCallActionProc .
+.LP
+.IN "XtCallActionProc" "" "@DEF@"
+.sM
+.FD 0
+void XtCallActionProc(\fIwidget\fP, \fIaction\fP, \fIevent\fP, \fIparams\fP, \
+\fInum_params\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      String \fIaction\fP;
+.br
+      XEvent *\fIevent\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal \fInum_params\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget in which the action is to be invoked.  \*(cI
+.IP \fIaction\fP 1i
+Specifies the name of the action routine.
+.IP \fIevent\fP 1i
+Specifies the contents of the \fIevent\fP passed to the action routine.
+.IP \fIparams\fP 1i
+Specifies the contents of the \fIparams\fP passed to the action routine.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+.PN XtCallActionProc
+searches for the named action routine in the same
+manner and order as translation tables are bound, as described in
+Section 10.1.2, except that application action tables are searched, if
+necessary, as of the time of the call to
+.PN XtCallActionProc .
+If found,
+the action routine is invoked with the specified widget, event pointer,
+and parameters.  It is the responsibility of the caller to ensure that
+the contents of the \fIevent\fP, \fIparams\fP, and \fInum_params\fP arguments are
+appropriate for the specified action routine and, if necessary, that
+the specified widget is realized or sensitive.  If the named action
+routine cannot be found,
+.PN XtCallActionProc
+generates a warning message and returns.
+
+.NH 2
+Obtaining a Widget's Action List
+.XS
+\*(SN Obtaining a Widget's Action List
+.XE
+.LP
+Occasionally a subclass will require the pointers to one or more of
+its superclass's action procedures.  This would be needed, for
+example, in order to envelop the superclass's action.  To retrieve
+the list of action procedures registered in the superclass's
+\fIactions\fP field, use
+.PN XtGetActionList .
+.LP
+.IN "XtGetActionList" "" "@DEF@"
+.sM
+.FD 0
+void XtGetActionList(\fIwidget_class\fP, \fIactions_return\fP, \
+\fInum_actions_return\fP)
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      XtActionList *\fIactions_return\fP;
+.br
+      Cardinal *\fInum_actions_return\fP;
+.FN
+.IP \fIwidget_class\fP 1.5i
+Specifies the widget class whose actions are to be returned.
+.IP \fIactions_return\fP 1.5i
+Returns the action list.
+.IP \fInum_actions_return\fP 1.5i
+Returns the number of action procedures declared by the class.
+.LP
+.eM
+.PN XtGetActionList
+returns the action table defined by the specified
+widget class.  This table does not include actions defined by the
+superclasses.  If \fIwidget_class\fP is not initialized, or is not
+.PN coreWidgetClass
+or a subclass thereof, or if the class does not define any actions,
+*\fIactions_return\fP will be NULL and *\fInum_actions_return\fP
+will be zero.
+If *\fIactions_return\fP is non-NULL the client is responsible for freeing
+the table using
+.PN XtFree
+when it is no longer needed.
+.bp
diff --git a/libXt/specs/CH11 b/libXt/specs/CH11
new file mode 100644
index 000000000..55b8d92f3
--- /dev/null
+++ b/libXt/specs/CH11
@@ -0,0 +1,3566 @@
+.\" $Xorg: CH11,v 1.3 2000/08/17 19:42:47 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 11\fP\s-1
+
+\s+1\fBUtility Functions\fP\s-1
+.sp 2
+.nr H1 11
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 11 \(em Utility Functions
+.XE
+The \*(xI provide a number of utility functions that you can use to
+.IP \(bu 5
+Determine the number of elements in an array.
+.IP \(bu 5
+Translate strings to widget instances.
+.IP \(bu 5
+Manage memory usage.
+.IP \(bu 5
+Share graphics contexts.
+.IP \(bu 5
+Manipulate selections.
+.IP \(bu 5
+Merge exposure events into a region.
+.IP \(bu 5
+Translate widget coordinates.
+.IP \(bu 5
+Locate a widget given a window id.
+.IP \(bu 5
+Handle errors.
+.IP \(bu 5
+Set the WM_COLORMAP_WINDOWS property.
+.IP \(bu 5
+Locate files by name with string substitutions.
+.IP \(bu 5
+Register callback functions for external agents.
+.IP \(bu 5
+Locate all the displays of an application context.
+
+.NH 2
+Determining the Number of Elements in an Array
+.XS
+\fB\*(SN Determining the Number of Elements in an Array\fP
+.XE
+.LP
+To determine the number of elements in a fixed-size array, use
+.PN XtNumber .
+.LP
+.IN "XtNumber" "" "@DEF@"
+.sM
+.FD 0
+Cardinal XtNumber(\fIarray\fP)
+.br
+      \fIArrayType array\fP;
+.FN
+.IP \fIarray\fP 1i
+Specifies a fixed-size array of arbitrary type.
+.LP
+.eM
+The
+.PN XtNumber
+macro returns the number of elements allocated to the array.
+
+.NH 2
+Translating Strings to Widget Instances
+.XS
+\fB\*(SN Translating Strings to Widget Instances\fP
+.XE
+.LP
+To translate a widget name to a widget instance, use
+.PN XtNameToWidget .
+.LP
+.IN "XtNameToWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtNameToWidget(\fIreference\fP, \fInames\fP)
+.br
+      Widget \fIreference\fP;
+.br
+      String \fInames\fP;
+.FN
+.IP \fIreference\fP 1i
+Specifies the widget from which the search is to start.  \*(cI
+.IP \fInames\fP 1i
+Specifies the partially qualified name of the desired widget.
+.LP
+.eM
+The
+.PN XtNameToWidget
+function searches for a descendant of the \fIreference\fP
+widget whose name matches the specified names.  The \fInames\fP parameter
+specifies a simple object name or a series of simple object name
+components separated by periods or asterisks.
+.PN XtNameToWidget
+returns the descendant with the shortest name matching the specification
+according to the following rules, where child is either a pop-up child
+or a normal child if the widget's class is a subclass of
+Composite :
+.IP \(bu 5
+Enumerate the object subtree rooted at the reference widget in
+breadth-first order, qualifying the name of each object with the
+names of all its ancestors up to, but not including, the reference
+widget.  The ordering between children of a common parent is
+not defined.
+.IP \(bu 5
+Return the first object in the enumeration that matches the
+specified name, where each component of \fInames\fP matches exactly the
+corresponding component of the qualified object name and asterisk
+matches any series of components, including none.
+.IP \(bu 5
+If no match is found, return NULL.
+.LP
+Since breadth-first traversal is specified, the descendant with the
+shortest matching name (i.e., the fewest number of components), if any,
+will always be returned.  However, since the order of enumeration of
+children is undefined and since the \*(xI do not require that all
+children of a widget have unique names,
+.PN XtNameToWidget
+may return any
+child that matches if there are multiple objects in the subtree with
+the same name.  Consecutive separators (periods or asterisks)
+including at least one asterisk are treated as a single asterisk.
+Consecutive periods are treated as a single period.
+
+.NH 2
+Managing Memory Usage
+.XS
+\fB\*(SN Managing Memory Usage\fP
+.XE
+.LP
+The \*(xI memory management functions provide uniform checking for
+null pointers and error reporting on memory allocation errors.
+These functions are completely compatible with their standard C language 
+runtime counterparts
+.PN malloc ,
+.PN calloc ,
+.PN realloc ,
+and
+.PN free
+with the following added functionality:
+.IP \(bu 5
+.PN XtMalloc ,
+.PN XtCalloc ,
+and
+.PN XtRealloc
+give an error if there is not enough memory.
+.IP \(bu 5
+.PN XtFree
+simply returns if passed a NULL pointer.
+.IP \(bu 5
+.PN XtRealloc
+simply allocates new storage if passed a NULL pointer.
+.LP
+See the standard C library documentation on
+.PN malloc ,
+.PN calloc ,
+.PN realloc ,
+and
+.PN free
+for more information.
+.sp
+.LP
+To allocate storage, use
+.PN XtMalloc .
+.LP
+.IN "XtMalloc" "" "@DEF@"
+.sM
+.FD 0
+char *XtMalloc(\fIsize\fP)
+.br
+      Cardinal \fIsize\fP;
+.FN
+.IP \fIsize\fP 1i
+Specifies the number of bytes desired.
+.LP
+.eM
+The
+.PN XtMalloc
+function returns a pointer to a block of storage of at least 
+the specified \fIsize\fP bytes.
+If there is insufficient memory to allocate the new block,
+.PN XtMalloc
+calls
+.PN XtErrorMsg .
+.sp
+.LP
+To allocate and initialize an array, use
+.PN XtCalloc .
+.LP
+.IN "XtCalloc" "" "@DEF@"
+.sM
+.FD 0
+char *XtCalloc(\fInum\fP, \fIsize\fP)
+.br
+      Cardinal \fInum\fP;
+.br
+      Cardinal \fIsize\fP;
+.FN
+.IP \fInum\fP 1i
+Specifies the number of array elements to allocate.
+.IP \fIsize\fP 1i
+Specifies the size of each array element in bytes.
+.LP
+.eM
+The
+.PN XtCalloc
+function allocates space for the specified number of array elements 
+of the specified size and initializes the space to zero.
+If there is insufficient memory to allocate the new block,
+.PN XtCalloc
+calls
+.PN XtErrorMsg .
+.PN XtCalloc
+returns the address of the allocated storage.
+.sp
+.LP
+To change the size of an allocated block of storage, use
+.PN XtRealloc .
+.LP
+.IN "XtRealloc" "" "@DEF@"
+.sM
+.FD 0
+char *XtRealloc(\fIptr\fP, \fInum\fP)
+.br
+      char *\fIptr\fP;
+.br
+      Cardinal \fInum\fP;
+.FN
+.IP \fIptr\fP 1i
+Specifies a pointer to the old storage allocated with
+.PN XtMalloc ,
+.PN XtCalloc ,
+or
+.PN XtRealloc ,
+or NULL.
+.IP \fInum\fP 1i
+Specifies number of bytes desired in new storage.
+.LP
+.eM
+The
+.PN XtRealloc
+function changes the size of a block of storage, possibly moving it.
+Then it copies the old contents (or as much as will fit) into the new block
+and frees the old block.
+If there is insufficient memory to allocate the new block,
+.PN XtRealloc
+calls
+.PN XtErrorMsg .
+If \fIptr\fP is NULL,
+.PN XtRealloc
+simply calls
+.PN XtMalloc .
+.PN XtRealloc
+then returns the address of the new block.
+.sp
+.LP
+To free an allocated block of storage, use
+.PN XtFree .
+.LP
+.IN "XtFree" "" "@DEF@"
+.sM
+.FD 0
+void XtFree(\fIptr\fP)
+.br
+      char *\fIptr\fP;
+.FN
+.IP \fIptr\fP 1i
+Specifies a pointer to a block of storage allocated with
+.PN XtMalloc ,
+.PN XtCalloc ,
+or
+.PN XtRealloc ,
+or NULL.
+.LP
+.eM
+The
+.PN XtFree
+function returns storage, allowing it to be reused.
+If \fIptr\fP is NULL,
+.PN XtFree
+returns immediately.
+.sp
+.LP
+To allocate storage for a new instance of a type, use
+.PN XtNew .
+.LP
+.IN "XtNew" "" "@DEF@"
+.sM
+.FD 0
+\fItype\fP *XtNew(\fItype\fP)
+.br
+      \fItype t\fP;
+.FN
+.IP \fItype\fP 1i
+Specifies a previously declared type.
+.LP
+.eM
+.PN XtNew
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+.PN XtNew
+calls
+.PN XtErrorMsg .
+.PN XtNew
+is a convenience macro that calls
+.PN XtMalloc
+with the following arguments specified:
+.LP
+.Ds
+.TA .5i
+.ta .5i
+((type *) XtMalloc((unsigned) sizeof(type)))
+.De
+.LP
+The storage allocated by
+.PN XtNew
+should be freed using
+.PN XtFree .
+.sp
+.LP
+To copy an instance of a string, use
+.PN XtNewString .
+.LP
+.IN "XtNewString" "" "@DEF@"
+.sM
+.FD 0
+String XtNewString(\fIstring\fP)
+.br
+      String \fIstring\fP;
+.FN
+.IP \fIstring\fP 1i
+Specifies a previously declared string.
+.LP
+.eM
+.PN XtNewString
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+.PN XtNewString
+calls
+.PN XtErrorMsg .
+.PN XtNewString
+is a convenience macro that calls
+.PN XtMalloc
+with the following arguments specified:
+.LP
+.Ds 
+.TA .5i
+.ta .5i
+(strcpy(XtMalloc((unsigned)strlen(str) + 1), str))
+.De
+.LP
+The storage allocated by
+.PN XtNewString
+should be freed using
+.PN XtFree .
+
+.NH 2
+Sharing Graphics Contexts
+.XS
+\fB\*(SN Sharing Graphics Contexts\fP
+.XE
+.LP
+The \*(xI provide a mechanism whereby cooperating objects can share a
+graphics context (GC), thereby reducing both the number of GCs
+created and the total number of server calls in any given application.
+The mechanism is a simple caching scheme
+and allows for clients to declare both modifiable and nonmodifiable
+fields of the shared GCs.
+.LP
+To obtain a shareable GC with modifiable fields, use
+.PN XtAllocateGC .
+.LP
+.IN "XtAllocateGC" "" "@DEF@"
+.sM
+.FD 0
+GC XtAllocateGC(\fIwidget\fP, \fIdepth\fP, \fIvalue_mask\fP, \fIvalues\fP, \
+\fIdynamic_mask\fP, \fIunused_mask\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      Cardinal \fIdepth\fP;
+.br
+      XtGCMask \fIvalue_mask\fP;
+.br
+      XGCValues *\fIvalues\fP;
+.br
+      XtGCMask \fIdynamic_mask\fP;
+.br
+      XtGCMask \fIunused_mask\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies an object, giving the screen for which the
+returned GC is valid.  \*(oI
+.IP \fIdepth\fP 1i
+Specifies the depth for which the returned GC is valid, or 0.
+.IP \fIvalue_mask\fP 1i
+Specifies fields of the GC that are initialized from \fIvalues\fP.
+.IP \fIvalues\fP 1i
+Specifies the values for the initialized fields.
+.IP \fIdynamic_mask\fP 1i
+Specifies fields of the GC that will be modified by the caller.
+.IP \fIunused_mask\fP 1i
+Specifies fields of the GC that will not be needed by the caller.
+.LP
+.eM
+The
+.PN XtAllocateGC
+function returns a shareable GC that may be
+modified by the client.  The \fIscreen\fP field of the specified
+widget or of the nearest widget ancestor of the specified
+object and the specified \fIdepth\fP argument supply
+the root and drawable depths for which the GC is to be
+valid.  If \fIdepth\fP is zero, the depth is taken from the
+\fIdepth\fP field of the specified widget or of the nearest
+widget ancestor of the specified object.
+.LP
+The \fIvalue_mask\fP argument specifies fields of the GC
+that are initialized with the respective member of the
+\fIvalues\fP structure.  The \fIdynamic_mask\fP argument specifies fields
+that the caller intends to modify during program execution.
+The caller must ensure that the corresponding GC field is set
+prior to each use of the GC.  The \fIunused_mask\fP argument
+specifies fields of the GC that are of no interest to the
+caller.  The caller may make no assumptions about the contents
+of any fields specified in \fIunused_mask\fP.  The caller may assume
+that at all times all fields not specified in either
+\fIdynamic_mask\fP or \fIunused_mask\fP have their default value if not
+specified in \fIvalue_mask\fP or the value specified by \fIvalues\fP.
+If a field is specified in both \fIvalue_mask\fP and \fIdynamic_mask\fP,
+the effect is as if it were specified only in \fIdynamic_mask\fP
+and then immediately set to the value in \fIvalues\fP.  If a field
+is set in \fIunused_mask\fP and also in either \fIvalue_mask\fP or
+\fIdynamic_mask\fP, the specification in \fIunused_mask\fP is ignored.
+.LP
+.PN XtAllocateGC
+tries to minimize the number of unique GCs
+created by comparing the arguments with those of previous
+calls and returning an existing GC when there are no
+conflicts.
+.PN XtAllocateGC
+may modify and return an existing GC if it was allocated with a
+nonzero \fIunused_mask\fP.
+.sp
+.LP
+To obtain a shareable GC with no modifiable fields, use
+.PN XtGetGC .
+.LP
+.IN "XtGetGC" "" "@DEF@"
+.sM
+.FD 0
+GC XtGetGC(\fIobject\fP, \fIvalue_mask\fP, \fIvalues\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      XtGCMask \fIvalue_mask\fP;
+.br
+      XGCValues *\fIvalues\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies an object, giving the screen and depth for which the
+returned GC is valid.  \*(oI
+.IP \fIvalue_mask\fP 1i
+Specifies which fields of the \fIvalues\fP structure are specified.
+.IP \fIvalues\fP 1i
+Specifies the actual values for this GC.
+.LP
+.eM
+The
+.PN XtGetGC
+function returns a shareable, read-only GC.
+The parameters to this function are the same as those for
+.PN XCreateGC 
+except that an Object is passed instead of a Display.
+.PN XtGetGC
+is equivalent to
+.PN XtAllocateGC
+with \fIdepth\fP, \fIdynamic_mask\fP, and \fIunused_mask\fP all zero.
+.LP
+.PN XtGetGC
+shares only GCs in which all values in the GC returned by
+.PN XCreateGC
+are the same.
+In particular, it does not use the \fIvalue_mask\fP provided to
+determine which fields of the GC a widget considers relevant.
+The \fIvalue_mask\fP is used only to tell the server which fields should be
+filled in from \fIvalues\fP and which it should fill in with default values.
+.sp
+.LP
+To deallocate a shared GC when it is no longer needed, use
+.PN XtReleaseGC .
+.LP
+.IN "XtReleaseGC" "" "@DEF@"
+.sM
+.FD 0
+void XtReleaseGC(\fIobject\fP, \fIgc\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      GC \fIgc\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies any object on the Display for which the GC was created.  \*(oI
+.IP \fIgc\fP 1i
+Specifies the shared GC obtained with either
+.PN XtAllocateGC
+or
+.PN XtGetGC .
+.LP
+.eM
+References to shareable GCs are counted and a free request is generated to the
+server when the last user of a given GC releases it.
+
+.NH 2
+Managing Selections
+.XS
+\*(SN Managing Selections
+.XE
+.LP
+Arbitrary widgets in multiple applications can communicate 
+with each other by means of the \*(xI global selection mechanism,
+which conforms to the specifications in the \fI\*(xC\fP.
+The \*(xI supply functions for providing and receiving selection data in
+one logical piece (atomic transfers)
+or in smaller logical segments (incremental transfers).
+.LP
+The incremental interface is provided for a selection owner or
+selection requestor that cannot or prefers not to pass the selection
+value to and from the \*(xI in a single call.  For instance,
+either an application that is running on a machine with limited memory
+may not be able to store the entire selection value in memory or a
+selection owner may already have the selection value available in
+discrete chunks, and it would be more efficient not to have to
+allocate additional storage to copy the pieces contiguously.  Any
+owner or requestor that prefers to deal with the selection value in
+segments can use the incremental interfaces to do so.
+The transfer between the selection owner or requestor and the \*(xI is not
+required to match the underlying
+transport protocol between the application and the X server;
+the \*(xI will break too large a selection 
+into smaller pieces for transport if necessary
+and will coalesce a selection transmitted incrementally if the value
+was requested atomically.
+
+.NH 3
+Setting and Getting the Selection Timeout Value
+.XS
+\fB\*(SN Setting and Getting the Selection Timeout Value\fP
+.XE
+.LP
+To set the \*(xI selection timeout, use
+.PN XtAppSetSelectionTimeout .
+.LP
+.IN "XtAppSetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+void XtAppSetSelectionTimeout(\fIapp_context\fP, \fItimeout\fP)
+.br
+    XtAppContext \fIapp_context\fP;
+.br
+    unsigned long \fItimeout\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fItimeout\fP 1i
+Specifies the selection timeout in milliseconds.
+.eM
+.LP
+To get the current selection timeout value, use
+.PN XtAppGetSelectionTimeout .
+.LP
+.IN "XtAppGetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+unsigned long XtAppGetSelectionTimeout(\fIapp_context\fP)
+.br
+     XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+The
+.PN XtAppGetSelectionTimeout
+function returns the current selection timeout value in milliseconds.
+The selection timeout is the time within which the two communicating 
+applications must respond to one another.
+The initial timeout value is set by the 
+selectionTimeout
+.IN "selectionTimeout"
+application resource as retrieved by
+.PN XtDisplayInitialize .
+If
+selectionTimeout
+is not specified,
+the default is five seconds.
+
+.NH 3
+Using Atomic Transfers
+.XS
+\*(SN Using Atomic Transfers
+.XE
+.LP
+When using atomic transfers, the owner will completely
+process one selection request at a time.
+The owner may consider each request individually,
+since there is no possibility for overlap
+between evaluation of two requests.
+
+.NH 4
+Atomic Transfer Procedures
+.XS
+\*(SN Atomic Transfer Procedures
+.XE
+.IN "Selections" "atomic"
+.LP
+The following procedures are used by the selection owner when
+providing selection data in a single unit.
+.LP
+The procedure pointer specified by the owner to supply the selection
+data to the \*(xI is of type
+.PN XtConvertSelectionProc .
+.LP
+.IN "XtConvertSelectionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtConvertSelectionProc)(Widget, Atom*, Atom*, Atom*,
+.br
+                      XtPointer*, unsigned long*, int*);
+.br
+    Widget \fIw\fP;
+.br
+    Atom *\fIselection\fP;
+.br
+    Atom *\fItarget\fP;
+.br
+    Atom *\fItype_return\fP;
+.br
+    XtPointer *\fIvalue_return\fP;
+.br
+    unsigned long *\fIlength_return\fP;
+.br
+    int *\fIformat_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that currently owns this selection.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection requested
+(for example,
+.PN XA_PRIMARY
+or 
+.PN XA_SECONDARY ).
+.IP \fItarget\fP 1i
+Specifies the target type of the selection that has been requested,
+which indicates the desired information about the selection 
+(for example, File Name, Text, Window).
+.IP \fItype_return\fP 1i
+Specifies a pointer to an atom into which the property type of the 
+converted value of the selection is to be stored.
+For instance, either File Name or Text might have property type 
+.PN XA_STRING .
+.IP \fIvalue_return\fP 1i
+Specifies a pointer into which a pointer to the converted value of the 
+selection is to be stored.
+The selection owner is responsible for allocating this storage.
+If the selection owner has provided an
+.PN XtSelectionDoneProc
+for the selection, 
+this storage is owned by the selection owner; 
+otherwise, it is owned by the \*(xI selection mechanism, 
+which frees it by calling
+.PN XtFree
+when it is done with it.
+.IP \fIlength_return\fP 1i
+Specifies a pointer into which the number of elements in \fIvalue_return\fP,
+each of size indicated by \fIformat_return\fP, is to be stored.
+.IP \fIformat_return\fP 1i
+Specifies a pointer into which the size in bits of the data elements 
+of the selection value is to be stored.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism 
+to get the value of a selection as a given type 
+from the current selection owner.
+It returns 
+.PN True 
+if the owner successfully converted the selection to the target type or
+.PN False
+otherwise.
+If the procedure returns
+.PN False ,
+the values of the return arguments are undefined.
+Each
+.PN XtConvertSelectionProc
+should respond to target value
+.PN TARGETS 
+by returning a value containing the list of the targets
+into which it is
+prepared to convert the selection.
+The value returned in
+\fIformat_return\fP must be one of 8, 16, or 32 to allow the server to
+byte-swap the data if necessary.
+.LP
+.IN "Selections" "MULTIPLE"
+.IN "Selections" "TIMESTAMP"
+This procedure does not need to worry about responding to the
+MULTIPLE or the TIMESTAMP target values (see Section 2.6.2 in the \fI\*(xC\fP).
+A selection request with
+the MULTIPLE target type is transparently transformed into a
+series of calls to this procedure, one for each target type, and a
+selection request with the TIMESTAMP target value is answered
+automatically by the \*(xI using the time specified in the
+call to
+.PN XtOwnSelection
+or
+.PN XtOwnSelectionIncremental .
+.sp
+.LP
+To retrieve the
+.PN SelectionRequest
+event that triggered the
+.PN XtConvertSelectionProc
+procedure, use
+.PN XtGetSelectionRequest .
+.LP
+.IN "XtGetSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+XSelectionRequestEvent *XtGetSelectionRequest(\fIw\fP, \fIselection\fP, \
+\fIrequest_id\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      XtRequestId \fIrequest_id\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that currently owns this selection.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the selection being processed.
+.IP \fIrequest_id\fP 1i
+Specifies the requestor id in the case of incremental
+selections, or NULL in the case of atomic transfers.
+.LP
+.eM
+.PN XtGetSelectionRequest
+may be called only from within an
+.PN XtConvertSelectionProc
+procedure and returns a pointer to the
+.PN SelectionRequest
+event that caused the conversion procedure to be invoked.
+\fIRequest_id\fP specifies a unique id for the individual request in the
+case that multiple incremental transfers are outstanding.  For atomic
+transfers, \fIrequest_id\fP must be specified as NULL.  If no
+.PN SelectionRequest
+event is being processed for the specified
+\fIwidget\fP, \fIselection\fP, and \fIrequest_id\fP,
+.PN XtGetSelectionRequest
+returns NULL.
+.sp
+.LP
+The procedure pointer specified by the owner when it desires
+notification upon losing ownership is of type
+.PN XtLoseSelectionProc .
+.LP
+.IN "XtLoseSelectionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtLoseSelectionProc)(Widget, Atom*);
+.br
+    Widget \fIw\fP;
+.br
+    Atom *\fIselection\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that has lost selection ownership.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism
+to inform the specified widget that it has lost the given selection.
+Note that this procedure does not ask the widget to relinquish the 
+selection ownership; it is merely informative.
+.sp
+.LP
+The procedure pointer specified by the owner when it desires
+notification of receipt of the data or when it manages the storage
+containing the data is of type
+.PN XtSelectionDoneProc .
+.LP
+.IN "XtSelectionDoneProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSelectionDoneProc)(Widget, Atom*, Atom*);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that owns the converted selection.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection that was converted.
+.IP \fItarget\fP 1i
+Specifies the target type to which the conversion was done.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism
+to inform the selection owner that a selection requestor has successfully
+retrieved a selection value.
+If the selection owner has registered an
+.PN XtSelectionDoneProc ,
+it should expect it to be called once for each conversion that it performs,
+after the converted value has been successfully transferred
+to the requestor.
+If the selection owner has registered an
+.PN XtSelectionDoneProc ,
+it also owns the storage containing the converted
+selection value.
+
+.NH 4
+Getting the Selection Value
+.XS
+\*(SN Getting the Selection Value
+.XE
+.LP
+The procedure pointer specified by the requestor to receive the
+selection data from the \*(xI is of type
+.PN XtSelectionCallbackProc .
+.LP
+.IN "XtSelectionCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom*, Atom*, \
+XtPointer, unsigned long*, int*);
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItype\fP;
+.br
+      XtPointer \fIvalue\fP;
+.br
+      unsigned long *\fIlength\fP;
+.br
+      int *\fIformat\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that requested the selection value.
+.IP \fIclient_data\fP 1i
+Specifies a value passed in by the widget when it requested the
+selection.
+.IP \fIselection\fP 1i
+Specifies the name of the selection that was requested.
+.IP \fItype\fP 1i
+Specifies the representation type of the selection value (for example,
+.PN XA_STRING ).
+Note that it is not the target that was requested (which the client
+must remember for itself), but the type that
+is used to represent the target.
+The special symbolic constant
+.PN XT_CONVERT_FAIL 
+is used to indicate that the selection conversion failed because the
+selection owner did not respond within the \*(xI selection timeout
+interval.
+.IP \fIvalue\fP 1i
+Specifies a pointer to the selection value.
+The requesting client owns this storage and is responsible for freeing it 
+by calling
+.PN XtFree
+when it is done with it.
+.IP \fIlength\fP 1i
+Specifies the number of elements in \fIvalue\fP.
+.IP \fIformat\fP 1i
+Specifies the size in bits of the data in each element of \fIvalue\fP.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism to deliver the
+requested selection to the requestor.
+.LP
+If the
+.PN SelectionNotify
+event returns a property of
+.PN None ,
+meaning the conversion has been refused because there is no owner for the
+specified selection or the owner cannot convert the selection to the
+requested target for any reason, the procedure is called with a value
+of NULL and a length of zero.
+.sp
+.LP
+To obtain the selection value in a single logical unit, use
+.PN XtGetSelectionValue
+or
+.PN XtGetSelectionValues .
+.LP
+.IN "XtGetSelectionValue" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValue(\fIw\fP, \fIselection\fP, \fItarget\fP, \
+\fIcallback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom \fItarget\fP;
+.br
+      XtSelectionCallbackProc \fIcallback\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired; for example,
+.PN XA_PRIMARY .
+.IP \fItarget\fP 1i
+Specifies the type of information needed about the selection.
+.IP \fIcallback\fP 1i
+Specifies the procedure to be called when the selection value
+has been obtained.
+Note that this is how the selection value is communicated back to the client.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the specified procedure
+when it is called.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the selection request was
+initiated.
+This should be the timestamp of the event that triggered this request;
+the value 
+.PN CurrentTime 
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValue
+function requests the value of the selection converted to 
+the target type. 
+The specified callback is called at some time after 
+.PN XtGetSelectionValue 
+is called, when the selection value is received from the X server.
+It may be called before or after 
+.PN XtGetSelectionValue 
+returns.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+.sp
+.LP
+.IN "XtGetSelectionValues" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValues(\fIw\fP, \fIselection\fP, \fItargets\fP, \
+\fIcount\fP, \fIcallback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom *\fItargets\fP;
+.br
+      int \fIcount\fP;
+.br
+      XtSelectionCallbackProc \fIcallback\fP;
+.br
+      XtPointer *\fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired (that is, primary or secondary).
+.IP \fItargets\fP 1i
+Specifies the types of information needed about the selection.
+.IP \fIcount\fP 1i
+Specifies the length of the \fItargets\fP and \fIclient_data\fP lists.
+.IP \fIcallback\fP 1i
+Specifies the callback procedure
+to be called with each selection value obtained.
+Note that this is how the selection values are communicated back to the
+client.
+.IP \fIclient_data\fP 1i
+Specifies a list of additional data values, one for each target type,
+that are passed to the callback procedure when it is called for that target.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the selection request was
+initiated.
+This should be the timestamp of the event that triggered this request;
+the value 
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValues
+function is similar to multiple calls to
+.PN XtGetSelectionValue 
+except that it guarantees that no other client can assert ownership
+between requests and therefore that all the conversions will refer to
+the same selection value.  The callback is invoked once for each
+target value with the corresponding client data.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+
+.NH 4
+Setting the Selection Owner
+.XS
+\*(SN Setting the Selection Owner
+.XE
+.LP
+To set the selection owner and indicate that the selection value will
+be provided in one piece, use
+.PN XtOwnSelection .
+.LP
+.IN "XtOwnSelection" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtOwnSelection(\fIw\fP, \fIselection\fP, \fItime\fP, \
+\fIconvert_proc\fP, \fIlose_selection\fP, \fIdone_proc\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.br
+      XtConvertSelectionProc \fIconvert_proc\fP;
+.br
+      XtLoseSelectionProc \fIlose_selection\fP;
+.br
+      XtSelectionDoneProc \fIdone_proc\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that wishes to become the owner.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the name of the selection (for example,
+.PN XA_PRIMARY ).
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the ownership request was
+initiated.
+This should be the timestamp of the event that triggered ownership;
+the value
+.PN CurrentTime 
+is not acceptable.
+.IP \fIconvert_proc\fP 1i
+Specifies the procedure to be called whenever a client requests the 
+current value of the selection.
+.IP \fIlose_selection\fP 1i
+Specifies the procedure to be called whenever the widget has 
+lost selection ownership, or NULL if the owner is not interested in being 
+called back.
+.IP \fIdone_proc\fP 1i
+Specifies the procedure called 
+after the requestor has received the selection value, or NULL if the
+owner is not
+interested in being called back.
+.LP
+.eM
+The
+.PN XtOwnSelection
+function informs the \*(xI selection mechanism that a
+widget wishes to own a selection.
+It returns 
+.PN True 
+if the widget successfully becomes the owner and 
+.PN False
+otherwise.
+The widget may fail to become the owner if some other widget 
+has asserted ownership at a time later than this widget.
+The widget can lose selection ownership either 
+because some other widget asserted later ownership of the selection 
+or because the widget voluntarily gave up ownership of the selection.
+The lose_selection procedure is not called 
+if the widget fails to obtain selection ownership in the first place.
+.LP
+If a done_proc is specified, the client owns the storage allocated
+for passing the value to the \*(xI.  If \fIdone_proc\fP is NULL,
+the convert_proc must allocate storage using
+.PN XtMalloc ,
+.PN XtRealloc ,
+or
+.PN XtCalloc ,
+and the value specified is freed by the
+\*(xI when the transfer is complete.
+.sp
+.LP
+Usually, a selection owner maintains ownership indefinitely until some
+other widget requests ownership, at which time
+the \*(xI selection mechanism informs the previous owner that it
+has lost ownership of the selection.
+However, in response to some user actions 
+(for example, when a user deletes the information selected),
+the application may wish to explicitly inform the \*(xI
+by using
+.PN XtDisownSelection
+that it no longer is to be the selection owner.
+.LP
+.IN "XtDisownSelection" "" "@DEF@"
+.sM
+.FD 0
+void XtDisownSelection(\fIw\fP, \fIselection\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that wishes to relinquish ownership.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection being given up.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the request to
+relinquish selection ownership was initiated.
+.LP
+.eM
+The
+.PN XtDisownSelection
+function informs the \*(xI selection mechanism that
+the specified widget is to lose ownership of the selection.
+If the widget does not currently own the selection, either 
+because it lost the selection 
+or because it never had the selection to begin with,
+.PN XtDisownSelection
+does nothing.
+.LP
+After a widget has called
+.PN XtDisownSelection ,
+its convert procedure is not called even if a request arrives later 
+with a timestamp during the period that this widget owned the selection.
+However, its done procedure is called if a conversion that started 
+before the call to
+.PN XtDisownSelection
+finishes after the call to
+.PN XtDisownSelection .
+
+.NH 3
+Using Incremental Transfers
+.XS
+\*(SN Using Incremental Transfers
+.XE
+.LP
+When using the incremental interface, an owner may have to process
+more than one selection request for the same selection, converted to
+the same target, at the same time.  The incremental functions take a
+\fIrequest_id\fP argument, which is an identifier that is guaranteed to be
+unique among all incremental requests that are active concurrently.
+.LP
+For example, consider the following:
+.IP \(bu 5
+Upon receiving a request for the selection value, the owner sends
+the first segment.
+.IP \(bu 5
+While waiting to be called to provide the next segment value but
+before sending it, the owner receives another request from a
+different requestor for the same selection value. 
+.IP \(bu 5
+To distinguish between the requests, the owner uses the request_id
+value.  This allows the owner to distinguish between the first
+requestor, which is asking for the second segment, and the second
+requestor, which is asking for the first segment. 
+
+.NH 4
+Incremental Transfer Procedures
+.XS
+\*(SN Incremental Transfer Procedures
+.XE
+.IN "Selections" "incremental"
+.LP
+The following procedures are used by selection owners who wish to
+provide the selection data in multiple segments.
+.LP
+The procedure pointer specified by the incremental owner to supply the
+selection data to the \*(xI is of type
+.PN XtConvertSelectionIncrProc .
+.LP
+.sM
+.Ds 0
+typedef XtPointer XtRequestId;
+.De
+.IN "XtRequestId" "" "@DEF@"
+.IN "XtConvertSelectionIncrProc" "" "@DEF@"
+.FD 0
+typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*, \
+Atom*, XtPointer*,
+                               unsigned long*, int*, unsigned long*, \
+XtPointer, XtRequestId*);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.br
+      Atom *\fItype_return\fP;
+.br
+      XtPointer *\fIvalue_return\fP;
+.br
+      unsigned long *\fIlength_return\fP;
+.br
+      int *\fIformat_return\fP;
+.br
+      unsigned long *\fImax_length\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtRequestId *\fIrequest_id\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that currently owns this selection.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection requested.
+.IP \fItarget\fP 1i
+Specifies the type of information required about the selection.
+.IP \fItype_return\fP 1i
+Specifies a pointer to an atom into which the property
+type of the converted value of the selection is to be
+stored.
+.IP \fIvalue_return\fP 1i
+Specifies a pointer into which a pointer to the
+converted value of the selection is to be stored.
+The selection owner is responsible for allocating this storage.
+.IP \fIlength_return\fP 1i
+Specifies a pointer into which the number of elements
+in \fIvalue_return\fP, each of size indicated by
+\fIformat_return\fP, is to be stored.
+.IP \fIformat_return\fP 1i
+Specifies a pointer into which the size in bits of the
+data elements of the selection value is to be stored so that the
+server may byte-swap the data if necessary.
+.IP \fImax_length\fP 1i
+Specifies the maximum number of bytes which may be
+transferred at any one time.
+.IP \fIclient_data\fP 1i
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+.IP \fIrequest_id\fP 1i
+Specifies an opaque identification for a specific request.
+.LP
+.eM
+This procedure is called repeatedly by the \*(xI selection mechanism to get
+the next incremental chunk of data from a selection owner who has
+called
+.PN XtOwnSelectionIncremental .
+It must return
+.PN True
+if the procedure has succeeded in converting the selection data or
+.PN False
+otherwise.
+On the first call with a particular request id, the owner must begin
+a new incremental transfer for the requested selection and target.  On
+subsequent calls with the same request id, the owner may assume that
+the previously supplied value is no longer needed by the \*(xI;
+that is, a fixed transfer area may be allocated and returned in \fIvalue_return\fP
+for each segment to be transferred.  This procedure should store a
+non-NULL value in \fIvalue_return\fP and zero in \fIlength_return\fP to indicate that the
+entire selection has been delivered.  After returning this final
+segment, the request id may be reused by the \*(xI to begin a
+new transfer.
+.LP
+To retrieve the
+.PN SelectionRequest
+event that triggered the selection conversion procedure, use
+.PN XtGetSelectionRequest ,
+described in Section 11.5.2.1.
+.sp
+.LP
+The procedure pointer specified by the incremental selection owner
+when it desires notification upon no longer having ownership is of
+type
+.PN XtLoseSelectionIncrProc .
+.LP
+.IN "XtLoseSelectionIncrProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtLoseSelectionIncrProc)(Widget, Atom*, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that has lost the selection ownership.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection.
+.IP \fIclient_data\fP 1i
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+.LP
+.eM
+This procedure, which is optional, is called by the \*(xI to
+inform the selection owner that it no longer owns the selection.
+.sp
+.LP
+The procedure pointer specified by the incremental selection owner
+when it desires notification of receipt of the data or when it manages
+the storage containing the data is of type
+.PN XtSelectionDoneIncrProc .
+.LP
+.IN "XtSelectionDoneIncrProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSelectionDoneIncrProc)(Widget, Atom*, Atom*, \
+XtRequestId*, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.br
+      XtRequestId *\fIrequest_id\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that owns the selection.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection being transferred.
+.IP \fItarget\fP 1i
+Specifies the target type to which the conversion was done.
+.IP \fIrequest_id\fP 1i
+Specifies an opaque identification for a specific request.
+.IP \fIclient_data\fP 1i
+Specified the value passed in by the widget when it
+took ownership of the selection.
+.LP
+.eM
+This procedure, which is optional, is called by the \*(xI after
+the requestor has retrieved the final (zero-length) segment of the
+incremental transfer to indicate that the entire transfer is complete.
+If this procedure is not specified, the \*(xI will free only the
+final value returned by the selection owner using
+.PN XtFree .
+.sp
+.LP
+The procedure pointer specified by the incremental selection owner to
+notify it if a transfer should be terminated prematurely is of type
+.PN XtCancelConvertSelectionProc .
+.LP
+.IN "XtCancelConvertSelectionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtCancelConvertSelectionProc)(Widget, Atom*, Atom*, \
+XtRequestId*, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.br
+      XtRequestId *\fIrequest_id\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that owns the selection.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection being transferred.
+.IP \fItarget\fP 1i
+Specifies the target type to which the conversion was done.
+.IP \fIrequest_id\fP 1i
+Specifies an opaque identification for a specific request.
+.IP \fIclient_data\fP 1i
+Specifies the value passed in by the widget when it took ownership of
+the selection.
+.LP
+.eM
+This procedure is called by the \*(xI when it has been determined
+by means of a timeout or other mechanism that any remaining segments
+of the selection no longer need to be transferred.  Upon receiving
+this callback, the selection request is considered complete and the
+owner can free the memory and any other resources that have been
+allocated for the transfer.
+
+.NH 4
+Getting the Selection Value Incrementally
+.XS
+\*(SN Getting the Selection Value Incrementally
+.XE
+.LP
+To obtain the value of the selection using incremental transfers, use
+.PN XtGetSelectionValueIncremental
+or
+.PN XtGetSelectionValuesIncremental .
+.LP
+.IN "XtGetSelectionValueIncremental" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValueIncremental(\fIw\fP, \fIselection\fP, \fItarget\fP, \
+\fIselection_callback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom \fItarget\fP;
+.br
+      XtSelectionCallbackProc \fIselection_callback\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.IP \fItarget\fP 1i
+Specifies the type of information needed
+about the selection.
+.IP \fIselection_callback\fP 1i
+Specifies the callback procedure to be
+called to receive each data segment.
+.IP \fIclient_data\fP 1i
+Specifies client-specific data to be passed to
+the specified callback procedure when it is invoked.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the
+selection request was initiated.  This should be the
+timestamp of the event that triggered this request;
+the value
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValueIncremental
+function is similar to
+.PN XtGetSelectionValue
+except that the selection_callback procedure will
+be called repeatedly upon delivery of multiple segments of the
+selection value.  The end of the selection value is indicated when
+\fIselection_callback\fP is called with a non-NULL value of length zero,
+which must still be freed by the client.  If the
+transfer of the selection is aborted in the middle of a transfer
+(for example, because of a timeout), the selection_callback procedure is
+called with a type value equal to the symbolic constant
+.PN XT_CONVERT_FAIL
+so that the requestor can dispose
+of the partial selection value it has collected up until that point.
+Upon receiving
+.PN XT_CONVERT_FAIL ,
+the requesting client must determine
+for itself whether or not a partially completed data transfer is meaningful.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+.LP
+.IN "XtGetSelectionValuesIncremental" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValuesIncremental(\fIw\fP, \fIselection\fP, \fItargets\fP, \
+\fIcount\fP, \fIselection_callback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom *\fItargets\fP;
+.br
+      int \fIcount\fP;
+.br
+      XtSelectionCallbackProc \fIselection_callback\fP;
+.br
+      XtPointer *\fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.IP \fItargets\fP 1i
+Specifies the types of information needed about
+the selection.
+.IP \fIcount\fP 1i
+Specifies the length of the \fItargets\fP and \fIclient_data\fP lists.
+.IP \fIselection_callback\fP 1i
+Specifies the callback procedure to be called
+to receive each selection value.
+.IP \fIclient_data\fP 1i
+Specifies a list of client data (one for each target
+type) values that are passed to the callback procedure when
+it is invoked for the corresponding target.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the
+selection request was initiated.  This should be the
+timestamp of the event that triggered this request;
+the value
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValuesIncremental
+function is similar to
+.PN XtGetSelectionValueIncremental
+except that it takes a list of targets and client data.
+.PN XtGetSelectionValuesIncremental
+is equivalent to calling
+.PN XtGetSelectionValueIncremental
+successively for each \fItarget/client_data\fP pair except that
+.PN XtGetSelectionValuesIncremental
+does guarantee that all the conversions will use the same selection
+value because the ownership of the selection cannot change in the
+middle of the list, as would be possible when calling
+.PN XtGetSelectionValueIncremental
+repeatedly.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+
+.NH 4
+Setting the Selection Owner for Incremental Transfers
+.XS
+\*(SN Setting the Selection Owner for Incremental Transfers
+.XE
+.LP
+To set the selection owner when using incremental transfers, use
+.PN XtOwnSelectionIncremental .
+.LP
+.IN "XtOwnSelectionIncremental" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtOwnSelectionIncremental(\fIw\fP, \fIselection\fP, \fItime\fP, \
+\fIconvert_callback\fP, \fIlose_callback\fP,
+                                  \fIdone_callback\fP, \
+\fIcancel_callback\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.br
+      XtConvertSelectionIncrProc \fIconvert_callback\fP;
+.br
+      XtLoseSelectionIncrProc \fIlose_callback\fP;
+.br
+      XtSelectionDoneIncrProc \fIdone_callback\fP;
+.br
+      XtCancelConvertSelectionProc \fIcancel_callback\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1.25i
+Specifies the widget that wishes to become the owner.  \*(cI
+.IP \fIselection\fP 1.25i
+Specifies the atom that names the selection.
+.IP \fItime\fP 1.25i
+Specifies the timestamp that indicates when the
+selection ownership request was initiated.  This should be
+the timestamp of the event that triggered ownership; the value
+.PN CurrentTime
+is not acceptable.
+.IP \fIconvert_callback\fP 1.25i
+Specifies the procedure to be called whenever
+the current value of the selection is requested.
+.IP \fIlose_callback\fP 1.25i
+Specifies the procedure to be called whenever
+the widget has lost selection ownership, or NULL if the
+owner is not interested in being notified.
+.IP \fIdone_callback\fP 1.25i
+Specifies the procedure called after the
+requestor has received the entire selection, or NULL if
+the owner is not interested in being notified.
+.IP \fIcancel_callback\fP 1.25i
+Specifies the callback procedure to be called
+when a selection request aborts because a timeout expires,
+or NULL if the owner is not interested in being notified.
+.IP \fIclient_data\fP 1.25i
+Specifies the argument to be passed to each of
+the callback procedures when they are called.
+.LP
+.eM
+The
+.PN XtOwnSelectionIncremental
+procedure informs the \*(xI
+incremental selection mechanism that the specified widget wishes to
+own the selection.  It returns
+.PN True
+if the specified widget successfully becomes the selection owner or
+.PN False
+otherwise.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+.LP
+If a done_callback procedure is specified, the client owns the storage allocated
+for passing the value to the \*(xI.  If \fIdone_callback\fP is NULL,
+the convert_callback procedure must allocate storage using
+.PN XtMalloc ,
+.PN XtRealloc ,
+or
+.PN XtCalloc ,
+and the final value specified is freed by the
+\*(xI when the transfer is complete.  After a selection transfer
+has started, only one of the done_callback or cancel_callback
+procedures is invoked to indicate completion of the transfer.
+.LP
+The lose_callback procedure does not indicate completion of any in-progress
+transfers; it is invoked at the time a
+.PN SelectionClear
+event is dispatched regardless of any active transfers, which are still
+expected to continue.
+.LP
+A widget that becomes the selection owner using
+.PN XtOwnSelectionIncremental
+may use
+.PN XtDisownSelection
+to relinquish selection ownership.
+
+.NH 3
+Setting and Retrieving Selection Target Parameters
+.XS
+\*(SN Setting and Retrieving Selection Target Parameters
+.XE
+.LP
+To specify target parameters for a selection request with a single target,
+use
+.PN XtSetSelectionParameters .
+.LP
+.IN "XtSetSelectionParameters" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSelectionParameters(\fIrequestor\fP, \fIselection\fP, \fItype\fP, \
+\fIvalue\fP, \fIlength\fP, \fIformat\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom \fItype\fP;
+.br
+      XtPointer \fIvalue\fP;
+.br
+      unsigned long \fIlength\fP;
+.br
+      int \fIformat\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection.
+.IP \fItype\fP 1i
+Specifies the type of the property in which the parameters are passed.
+.IP \fIvalue\fP 1i
+Specifies a pointer to the parameters.
+.IP \fIlength\fP 1i
+Specifies the number of elements containing data in \fIvalue\fP,
+each element of a size indicated by \fIformat\fP.
+.IP \fIformat\fP 1i
+Specifies the size in bits of the data in the elements of \fIvalue\fP.
+.LP
+The specified parameters are copied and stored in a new property 
+of the specified type and format on the requestor's window.  To initiate
+a selection request with a target and these parameters, a subsequent
+call to 
+.PN XtGetSelectionValue
+or to
+.PN XtGetSelectionValueIncremental
+specifying the same requestor widget and selection atom will generate a
+.PN ConvertSelection
+request referring to the property containing the parameters.  If 
+.PN XtSetSelectionParameters
+is called more than once with the same widget and selection without
+a call to specify a request, the most recently specified parameters
+are used in the subsequent request.
+.LP
+.eM
+The possible values of \fIformat\fP are 8, 16, or 32.  If the format is 8,
+the elements of \fIvalue\fP are assumed to be sizeof(char);
+if 16, sizeof(short); if 32, sizeof(long).
+.LP
+To generate a MULTIPLE
+target request with parameters for any of the multiple targets of the
+selection request, precede individual calls to
+.PN XtGetSelectionValue
+and
+.PN XtGetSelectionValueIncremental
+with corresponding individual calls to
+.PN XtSetSelectionParameters ,
+and enclose these all within 
+.PN XtCreateSelectionRequest
+and
+.PN XtSendSelectionRequest.  
+.PN XtGetSelectionValues
+and
+.PN XtGetSelectionValuesIncremental
+cannot be used to make selection requests with parameterized targets.
+.sp
+.LP
+To retrieve any target parameters needed to perform a selection conversion,
+the selection owner calls 
+.PN XtGetSelectionParameters .
+.LP
+.IN "XtGetSelectionParameters" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionParameters(\fIowner\fP, \fIselection\fP, \
+\fIrequest_id\fP, \fItype_return\fP, \fIvalue_return\fP,
+                                                 \fIlength_return\fP, \
+\fIformat_return\fP)
+.br
+      Widget \fIowner\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      XtRequestId \fIrequest_id\fP;
+.br
+      Atom *\fItype_return\fP;
+.br
+      XtPointer *\fIvalue_return\fP;
+.br
+      unsigned long *\fIlength_return\fP;
+.br
+      int *\fIformat_return\fP;
+.FN
+.IP \fIowner\fP 1i
+Specifies the widget that owns the specified selection.
+.IP \fIselection\fP 1i
+Specifies the selection being processed.
+.IP \fIrequest_id\fP 1i
+Specifies the requestor id in the case of incremental selections,
+or NULL in the case of atomic transfers.
+.IP \fItype_return\fP 1i
+Specifies a pointer to an atom in which the property type
+of the parameters is stored.
+.IP \fIvalue_return\fP 1i
+Specifies a pointer into which a pointer to the parameters is to be stored.
+A NULL is stored if no parameters accompany the request.
+.IP \fIlength_return\fP 1i
+Specifies a pointer into which the number of data elements
+in \fIvalue_return\fP of size indicated by \fIformat_return\fP are stored.
+.IP \fIformat_return\fP 1i
+Specifies a pointer into which the size in bits of the parameter data
+in the elements of \fIvalue\fP is stored.
+.LP
+.eM
+.PN XtGetSelectionParameters
+may be called only from within an
+.PN XtConvertSelectionProc
+or from within the first call to an 
+.PN XtConvertSelectionIncrProc
+with a new request_id.
+.LP
+It is the responsibility of the caller to free the returned parameters using
+.PN XtFree
+when the parameters are no longer needed.
+
+.NH 3
+Generating MULTIPLE Requests
+.XS
+\*(SN Generating MULTIPLE Requests
+.XE
+.LP
+To have the \*(xI bundle multiple calls to make selection requests into
+a single request using a \s-1MULTIPLE\s+1 target, use 
+.PN XtCreateSelectionRequest
+and
+.PN XtSendSelectionRequest .
+.LP
+.IN "XtCreateSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+void XtCreateSelectionRequest(\fIrequestor\fP, \fIselection\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.LP
+.eM
+When 
+.PN XtCreateSelectionRequest
+is called, subsequent calls to 
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValueIncremental ,
+.PN XtGetSelectionValues ,
+and
+.PN XtGetSelectionValuesIncremental ,
+with the requestor and selection as specified to 
+.PN XtCreateSelectionRequest ,
+are bundled into a single selection request with
+multiple targets.  The request is made by calling 
+.PN XtSendSelectionRequest .
+.LP
+.IN "XtSendSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+void XtSendSelectionRequest(\fIrequestor\fP, \fIselection\fP, \fItime\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the selection request was
+initiated.  The value 
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+When 
+.PN XtSendSelectionRequest
+is called with a value of \fIrequestor\fP and \fIselection\fP matching
+a previous call to 
+.PN XtCreateSelectionRequest ,
+a selection request is sent to the selection owner.
+If a single target request is queued, that request is made.
+If multiple targets are queued, they are bundled into a single request
+with a target of MULTIPLE using the specified timestamp.
+As the values are returned, the callbacks specified in
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValueIncremental ,
+.PN XtGetSelectionValues ,
+and
+.PN XtGetSelectionValueIncremental
+are invoked.
+.LP
+Multi-threaded applications should lock the application context before
+calling
+.PN XtCreateSelectionRequest
+and release the lock after calling
+.PN XtSendSelectionRequest
+to ensure that the thread assembling the request is safe from interference
+by another thread assembling a different request naming the same widget
+and selection.
+.sp
+.LP
+To relinquish the composition of a MULTIPLE request without sending it, use
+.PN XtCancelSelectionRequest .
+.LP
+.IN "XtCancelSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+void XtCancelSelectionRequest(\fIrequestor\fP, \fIselection\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.LP
+.eM
+When
+.PN XtCancelSelectionRequest
+is called, any requests queued since the last call to
+.PN XtCreateSelectionRequest
+for the same widget and selection are discarded
+and any resources reserved are released.
+A subsequent call to
+.PN XtSendSelectionRequest
+will not result in any request being made.
+Subsequent calls to
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValues ,
+.PN XtGetSelectionValueIncremental ,
+or
+.PN XtGetSelectionValuesIncremental
+will not be deferred.
+
+.NH 3
+Auxiliary Selection Properties
+.XS
+\*(SN Auxiliary Selection Properties
+.XE
+.LP
+Certain uses of parameterized selections require clients to name
+other window properties within a selection parameter.  To permit
+reuse of temporary property names in these circumstances and
+thereby reduce the number of unique atoms created in the server,
+the \*(xI provides two interfaces for acquiring temporary property names.
+.LP
+To acquire a temporary property name atom for use in a selection
+request, the client may call
+.PN XtReservePropertyAtom .
+.LP
+.IN "XtReservePropertyAtom" "" "@DEF@"
+.sM
+.FD 0
+Atom XtReservePropertyAtom(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making a selection request.
+.LP
+.eM
+.PN XtReservePropertyAtom
+returns an atom that may be used as a property name during selection
+requests involving the specified widget. 
+As long as the atom remains reserved, it is unique with respect to all
+other reserved atoms for the widget.
+.LP
+To return a temporary property name atom for reuse and to delete
+the property named by that atom, use
+.PN XtReleasePropertyAtom .
+.LP
+.IN "XtReleasePropertyAtom" "" "@DEF@"
+.sM
+.FD 0
+void XtReleasePropertyAtom(\fIw\fP, \fIatom\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIatom\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget used to reserve the property name atom.
+.IP \fIatom\fP 1i
+Specifies the property name atom returned by
+.PN XtReservePropertyAtom
+that is to be released for reuse.
+.LP
+.eM
+.PN XtReleasePropertyAtom
+marks the specified property name atom as
+no longer in use and ensures that any property having that name
+on the specified widget's window is deleted.  If \fIatom\fP does not
+specify a value returned by
+.PN XtReservePropertyAtom
+for the specified widget, the results are undefined.
+
+.NH 3
+Retrieving the Most Recent Timestamp
+.XS
+\*(SN Retrieving the Most Recent Timestamp
+.XE
+.LP
+To retrieve the timestamp from the most recent call to
+.PN XtDispatchEvent
+that contained a timestamp, use
+.PN XtLastTimestampProcessed .
+.LP
+.IN "XtLastTimestampProcessed" "" "@DEF@"
+.sM
+.FD 0
+Time XtLastTimestampProcessed(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies an open display connection.
+.LP
+.eM
+If no
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+.PN ButtonRelease ,
+.PN MotionNotify ,
+.PN EnterNotify ,
+.PN LeaveNotify ,
+.PN PropertyNotify ,
+or
+.PN SelectionClear
+event has yet been passed to
+.PN XtDispatchEvent
+for the specified display,
+.PN XtLastTimestampProcessed
+returns zero.
+
+.NH 3
+Retrieving the Most Recent Event
+.XS
+\*(SN Retrieving the Most Recent Event
+.XE
+.LP
+To retrieve the event from the most recent call to
+.PN XtDispatchEvent
+for a specific display, use
+.PN XtLastEventProcessed .
+.LP
+.IN "XtLastEventProcessed" "" "@DEF@"
+.sM
+.FD 0
+XEvent *XtLastEventProcessed(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection from which to retrieve the event.
+.LP
+.eM
+Returns the last event passed to
+.PN XtDispatchEvent
+for the specified display.  Returns NULL if there is no such event.
+The client must not modify the contents of the returned event.
+
+.NH 2
+Merging Exposure Events into a Region
+.XS
+\*(SN Merging Exposure Events into a Region
+.XE
+.LP
+The \*(xI provide an
+.PN XtAddExposureToRegion
+utility function that merges
+.PN Expose
+and
+.PN GraphicsExpose
+events into a region for clients to process at once
+rather than processing individual rectangles.
+For further information about regions,
+see Section 16.5 in \fI\*(xL\fP.
+.sp
+.LP
+To merge
+.PN Expose
+and
+.PN GraphicsExpose
+events into a region, use
+.PN XtAddExposureToRegion .
+.LP
+.IN "XtAddExposureToRegion" "" "@DEF@"
+.sM
+.FD 0
+void XtAddExposureToRegion(\fIevent\fP, \fIregion\fP)
+.br
+     XEvent *\fIevent\fP;
+.br
+     Region \fIregion\fP;
+.FN
+.IP \fIevent\fP 1i
+Specifies a pointer to the
+.PN Expose
+or
+.PN GraphicsExpose
+event.
+.IP \fIregion\fP 1i
+Specifies the region object (as defined in
+.Pn < X11/Xutil.h >).
+.LP
+.eM
+The
+.PN XtAddExposureToRegion
+function computes the union of the rectangle defined by the exposure
+event and the specified region.
+Then it stores the results back in \fIregion\fP.
+If the event argument is not an
+.PN Expose
+or
+.PN GraphicsExpose
+event,
+.PN XtAddExposureToRegion
+returns without an error and without modifying \fIregion\fP.
+.LP
+This function is used by the exposure compression mechanism;
+see Section 7.9.3.
+
+.NH 2
+Translating Widget Coordinates
+.XS
+\fB\*(SN Translating Widget Coordinates\fP
+.XE
+.LP
+To translate an x-y coordinate pair from widget coordinates to root
+window absolute coordinates, use
+.PN XtTranslateCoords .
+.LP
+.IN "XtTranslateCoords" "" "@DEF@"
+.sM
+.FD 0
+void XtTranslateCoords(\fIw\fP, \fIx\fP, \fIy\fP, \fIrootx_return\fP, \
+\fIrooty_return\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Position \fIx\fP, \fIy\fP;
+.br
+      Position *\fIrootx_return\fP, *\fIrooty_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the widget-relative x and y coordinates.
+.IP \fIrootx_return\fP 1i
+.br
+.ns
+.IP \fIrooty_return\fP 1i
+Return the root-relative x and y coordinates.
+.LP
+.eM
+While
+.PN XtTranslateCoords
+is similar to the Xlib
+.PN XTranslateCoordinates 
+function, it does not generate a server request because all the required
+information already is in the widget's data structures.
+
+.NH 2
+Translating a Window to a Widget
+.XS
+\fB\*(SN Translating a Window to a Widget\fP
+.XE
+.LP
+To translate a given window and display pointer into a widget instance, use
+.PN XtWindowToWidget .
+.LP
+.IN "XtWindowToWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtWindowToWidget(\fIdisplay\fP, \fIwindow\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      Window \fIwindow\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display on which the window is defined.
+.IP \fIwindow\fP 1i
+Specifies the drawable for which you want the widget.
+.LP
+.eM
+If there is a realized widget whose window is the specified drawable on
+the specified \fIdisplay\fP,
+.PN XtWindowToWidget
+returns that widget.
+If not and if the drawable has been associated with a widget through
+.PN XtRegisterDrawable ,
+.PN XtWindowToWidget
+returns the widget associated with the drawable.  In other cases it
+returns NULL.
+
+.NH 2
+Handling Errors
+.XS
+\fB\*(SN Handling Errors\fP
+.XE
+.LP
+The \*(xI allow a client to register procedures that are called
+whenever a fatal or nonfatal error occurs.
+These facilities are intended for both error reporting and logging
+and for error correction or recovery.
+.LP
+Two levels of interface are provided: 
+.IP \(bu 5
+A high-level interface that takes an error
+name and class and retrieves the error message text from
+an error resource database.
+.IP \(bu 5
+A low-level interface that takes a simple string to display.
+.LP
+The high-level functions construct a string to pass to the lower-level
+interface.
+The strings may be specified in application code and are
+overridden by the contents of an external systemwide file,
+the ``error database file''.  The location and name of this file are
+implementation-dependent.
+.NT
+The application-context-specific error handling is not
+implemented on many systems, although the interfaces are
+always present.
+Most implementations will have just one set of error handlers
+for all application contexts within a process.
+If they are set for different application contexts,
+the ones registered last will prevail.
+.NE
+.sp
+.LP
+To obtain the error database (for example, to merge with
+an application- or widget-specific database), use
+.PN XtAppGetErrorDatabase .
+.LP
+.IN "XtAppGetErrorDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase *XtAppGetErrorDatabase(\^\fIapp_context\fP\^)
+.br
+     XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+The
+.PN XtAppGetErrorDatabase
+function returns the address of the error database.
+The \*(xI do a lazy binding of the error database and do not merge in the
+database file until the first call to
+.PN XtAppGetErrorDatabaseText .
+.LP
+For a complete listing of all errors and warnings 
+that can be generated by the \*(xI, see Appendix D.
+.sp
+.LP
+The high-level error and warning handler procedure pointers are of type
+.PN XtErrorMsgHandler .
+.LP
+.IN "XtErrorMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtErrorMsgHandler)(String, String, String, String, \
+String*, Cardinal*);
+.br
+    String \fIname\fP;
+.br
+    String \fItype\fP;
+.br
+    String \fIclass\fP;
+.br
+    String \fIdefaultp\fP;
+.br
+    String *\fIparams\fP;
+.br
+    Cardinal *\fInum_params\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the name to be concatenated with the specified type to form 
+the resource name of the error message.
+.IP \fItype\fP 1i
+Specifies the type to be concatenated with the name to form the 
+resource name of the error message.
+.IP \fIclass\fP 1i
+Specifies the resource class of the error message.
+.IP \fIdefaultp\fP 1i
+Specifies the default message to use if no error database entry is found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of parameters to be substituted in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+The specified name can be a general kind of error, 
+like ``invalidParameters'' or ``invalidWindow'', 
+and the specified type gives extra information
+such as the name of the routine in which the error was detected.
+Standard 
+.PN printf 
+notation is used to substitute the parameters into the message.
+.sp
+.LP
+An error message handler can obtain the error database text for an
+error or a warning by calling
+.PN XtAppGetErrorDatabaseText .
+.LP
+.IN "XtAppGetErrorDatabaseText" "" "@DEF@"
+.sM
+.FD 0
+void XtAppGetErrorDatabaseText(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP, \fIdatabase\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIname\fP, \fItype\fP, \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String \fIbuffer_return\fP;
+.br
+      int \fInbytes\fP;
+.br
+      XrmDatabase \fIdatabase\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIname\fP 1i
+.br
+.ns
+.IP \fItype\fP 1i
+Specify the name and type concatenated to form the resource name 
+of the error message.
+.IP \fIclass\fP 1i
+Specifies the resource class of the error message.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIbuffer_return\fP 1i
+Specifies the buffer into which the error message is to be returned.
+.IP \fInbytes\fP 1i
+Specifies the size of the buffer in bytes.
+.IP \fIdatabase\fP 1i
+Specifies the name of the alternative database to be used,
+or NULL if the application context's error database is to be used.
+.LP
+.eM
+The
+.PN XtAppGetErrorDatabaseText
+returns the appropriate message from the error database
+or returns the specified default message if one is not found in the
+error database.
+To form the full resource name and class when querying the database,
+the \fIname\fP and \fItype\fP are concatenated with a single ``.''
+between them and the \fIclass\fP is concatenated with itself with a
+single ``.'' if it does not already contain a ``.''.
+.sp
+.LP
+To return the application name and class as passed to
+.PN XtDisplayInitialize
+for a particular Display, use
+.PN XtGetApplicationNameAndClass .
+.LP
+.IN "XtGetApplicationNameAndClass" "" "@DEF@"
+.sM
+.FD 0
+void XtGetApplicationNameAndClass(\fIdisplay\fP, \fIname_return\fP, \
+\fIclass_return\fP)
+.br
+      Display* \fIdisplay\fP;
+.br
+      String* \fIname_return\fP;
+.br
+      String* \fIclass_return\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies an open display connection that has been initialized with
+.PN XtDisplayInitialize .
+.IP \fIname_return\fP 1i
+Returns the application name.
+.IP \fIclass_return\fP 1i
+Returns the application class.
+.LP
+.eM
+.PN XtGetApplicationNameAndClass
+returns the application name and class passed to
+.PN XtDisplayInitialize
+for the specified display.  If the display was
+never initialized or has been closed, the result is undefined.  The
+returned strings are owned by the \*(xI and must not be modified
+or freed by the caller.
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtAppSetErrorMsgHandler .
+.LP
+.IN "XtAppSetErrorMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorMsgHandler XtAppSetErrorMsgHandler(\fIapp_context\fP, \fImsg_handler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImsg_handler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+.PN XtAppSetErrorMsgHandler
+returns a pointer to the previously
+installed high-level fatal error handler.
+The default high-level fatal error handler provided by the \*(xI is named
+.PN _XtDefaultErrorMsg
+.IN "_XtDefaultErrorMsg" "" "@DEF"
+and constructs a string from the error resource database and calls
+.PN XtError .
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(xI behavior is undefined.
+.sp
+.LP
+To call the high-level error handler, use
+.PN XtAppErrorMsg .
+.LP
+.IN "XtAppErrorMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtAppErrorMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \
+\fIdefault\fP, \ \fIparams\fP, \fInum_params\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+The \*(xI internal errors all have class
+``XtToolkitError''.
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtAppSetWarningMsgHandler .
+.LP
+.IN "XtAppSetWarningMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorMsgHandler XtAppSetWarningMsgHandler(\fIapp_context\fP, \fImsg_handler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImsg_handler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+.PN XtAppSetWarningMsgHandler
+returns a pointer to the previously
+installed high-level warning handler.
+The default high-level warning handler provided by the \*(xI is named
+.PN _XtDefaultWarningMsg
+.IN "_XtDefaultWarningMsg" "" "@DEF@"
+and constructs a string
+from the error resource database and calls
+.PN XtWarning .
+.sp
+.LP
+To call the installed high-level warning handler, use
+.PN XtAppWarningMsg .
+.LP
+.IN "XtAppWarningMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtAppWarningMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIparams\fP, \fInum_params\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+The \*(xI internal warnings all have class
+``XtToolkitError''.
+.sp
+.LP
+The low-level error and warning handler procedure pointers are of type
+.PN XtErrorHandler .
+.LP
+.IN "XtErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtErrorHandler)(String);
+.br
+      String \fImessage\fP;
+.FN
+.IP \fImessage\fP 1i
+Specifies the error message.
+.LP
+.eM
+The error handler should display the message string in some appropriate fashion.
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtAppSetErrorHandler .
+.LP
+.IN "XtAppSetErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorHandler XtAppSetErrorHandler(\fIapp_context\fP, \fIhandler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIhandler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+.PN XtAppSetErrorHandler
+returns a pointer to the previously installed
+low-level fatal error handler.
+The default low-level error handler provided by the \*(xI is
+.PN _XtDefaultError .
+.IN "_XtDefaultError" "" "@DEF@"
+On POSIX-based systems,
+it prints the message to standard error and terminates the application.
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(xI behavior is undefined.
+.sp
+.LP
+To call the installed fatal error procedure, use
+.PN XtAppError .
+.LP
+.IN "XtAppError" "" "@DEF@"
+.sM
+.FD 0
+void XtAppError(\fIapp_context\fP, \fImessage\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fImessage\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImessage\fP 1i
+Specifies the message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppErrorMsg ,
+not
+.PN XtAppError ,
+to provide for customization and internationalization of error messages.
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtAppSetWarningHandler .
+.LP
+.IN "XtAppSetWarningHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorHandler XtAppSetWarningHandler(\fIapp_context\fP, \fIhandler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIhandler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+.PN XtAppSetWarningHandler
+returns a pointer to the previously installed
+low-level warning handler.
+The default low-level warning handler provided by the \*(xI is
+.PN _XtDefaultWarning .
+.IN "_XtDefaultWarning" "" "@DEF@"
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+.sp
+.LP
+To call the installed nonfatal error procedure, use
+.PN XtAppWarning .
+.LP
+.IN "XtAppWarning" "" "@DEF@"
+.sM
+.FD 0
+void XtAppWarning(\fIapp_context\fP, \fImessage\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fImessage\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImessage\fP 1i
+Specifies the nonfatal error message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppWarningMsg ,
+not
+.PN XtAppWarning ,
+to provide for customization and internationalization of warning messages.
+
+.NH 2
+Setting WM_COLORMAP_WINDOWS
+.XS
+\fB\*(SN Setting WM_COLORMAP_WINDOWS\fP
+.XE
+.LP
+A client may set the value of the \s-1WM_COLORMAP_WINDOWS\s+1
+.IN "WM_COLORMAP_WINDOWS" "" "@DEF@"
+property on a widget's window by calling
+.PN XtSetWMColormapWindows .
+.LP
+.IN "XtSetWMColormapWindows" "" "@DEF@"
+.sM
+.FD 0
+void XtSetWMColormapWindows(\fIwidget\fP, \fIlist\fP, \fIcount\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Widget* \fIlist\fP;
+.br
+      Cardinal \fIcount\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget on whose window the \s-1WM_COLORMAP_WINDOWS\s+1
+property is stored.  \*(cI
+.IP \fIlist\fP 1i
+Specifies a list of widgets whose windows are potentially to be
+listed in the \s-1WM_COLORMAP_WINDOWS\s+1 property.
+.IP \fIcount\fP 1i
+Specifies the number of widgets in \fIlist\fP.
+.LP
+.eM
+.PN XtSetWMColormapWindows
+returns immediately if \fIwidget\fP is not realized or if \fIcount\fP is 0.
+Otherwise,
+.PN XtSetWMColormapWindows
+constructs an ordered list of windows
+by examining each widget in \fIlist\fP in turn and
+ignoring the widget if it is not realized, or
+adding the widget's window to the window list if the widget is realized
+and if its colormap resource is different from the colormap
+resources of all widgets whose windows are already on the window list.
+.LP
+Finally,
+.PN XtSetWMColormapWindows
+stores the resulting window list in the \s-1WM_COLORMAP_WINDOWS\s+1
+property on the specified widget's window.
+Refer to Section 4.1.8 in the \fI\*(xC\fP for details of
+the semantics of the \s-1WM_COLORMAP_WINDOWS\s+1 property.
+
+.NH 2
+Finding File Names
+.XS
+\fB\*(SN Finding File Names\fP
+.XE
+.LP
+The \*(xI provide procedures to look for a file by name, allowing
+string substitutions in a list of file specifications.  Two
+routines are provided for this:
+.PN XtFindFile
+and
+.PN XtResolvePathname .
+.PN XtFindFile
+uses an arbitrary set of client-specified substitutions, and
+.PN XtResolvePathname
+uses a set of standard substitutions corresponding
+to the \fIX/Open Portability Guide\fP language localization conventions.
+Most applications should use
+.PN XtResolvePathname .
+.LP
+A string substitution is defined by a list of
+.PN Substitution
+.IN "Substitution" "" "@DEF@"
+entries.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	char match;
+	String substitution;
+} SubstitutionRec, *Substitution;
+.De
+.eM
+.LP
+File name evaluation is handled in an operating-system-dependent
+fashion by an
+.PN XtFilePredicate
+.IN "XtFilePredicate" "" "@DEF@"
+procedure.
+.LP
+.sM
+.FD 0
+typedef Boolean (*XtFilePredicate)(String);
+.br
+      String \fIfilename\fP;
+.FN
+.IP \fIfilename\fP 1i
+Specifies a potential filename.
+.LP
+.eM
+A file predicate procedure is called with a string that is
+potentially a file name.  It should return
+.PN True 
+if this string specifies a file that is appropriate for the intended use and 
+.PN False
+otherwise.
+.sp
+.LP
+To search for a file using substitutions in a path list, use
+.PN XtFindFile .
+.LP
+.IN "XtFindFile" "" "@DEF@"
+.sM
+.FD 0
+String XtFindFile(\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \
+\fIpredicate\fP)
+.br
+      String \fIpath\fP;
+.br
+      Substitution \fIsubstitutions\fP;
+.br
+      Cardinal \fInum_substitutions\fP;
+.br
+      XtFilePredicate \fIpredicate\fP;
+.FN
+.IP \fIpath\fP 1.2i
+Specifies a path of file names, including substitution characters.
+.IP \fIsubstitutions\fP 1.2i
+Specifies a list of substitutions to make into the path.
+.IP \fInum_substitutions\fP 1.2i
+Specifies the number of substitutions passed in.
+.IP \fIpredicate\fP 1.2i
+Specifies a procedure called to judge each potential file name, or NULL.
+.LP
+.eM
+The \fIpath\fP parameter specifies a string that consists of a series of
+potential file names delimited by colons.  Within each name, the
+percent character specifies a string substitution selected by the
+following character.  The character sequence ``%:'' specifies an
+embedded colon that is not a delimiter; the sequence is replaced by a
+single colon.  The character sequence ``%%'' specifies a percent
+character that does not introduce a substitution; the sequence is
+replaced by a single percent character.  If a percent character is
+followed by any other character,
+.PN XtFindFile
+looks through the
+specified \fIsubstitutions\fP for that character in the \fImatch\fP field
+and, if found,
+replaces the percent and match characters with the string in the
+corresponding \fIsubstitution\fP field.  A \fIsubstitution\fP field entry of NULL
+is equivalent to a pointer to an empty string.  If the operating
+system does not interpret multiple embedded name separators in the
+path (i.e., ``/'' in POSIX) the same way as a single separator,
+.PN XtFindFile
+will collapse multiple separators into a single one after performing
+all string substitutions.  Except for collapsing embedded separators,
+the contents of the string substitutions are not interpreted by
+.PN XtFindFile
+and may therefore contain any operating-system-dependent
+characters, including additional name separators.  Each resulting
+string is passed to the predicate procedure until a string is found for
+which the procedure returns
+.PN True ;
+this string is the return value for
+.PN XtFindFile .
+If no string yields a
+.PN True
+return from the predicate,
+.PN XtFindFile
+returns NULL.
+.LP
+If the \fIpredicate\fP parameter is NULL, an internal procedure that checks
+if the file exists, is readable, and is not a directory is used.
+.LP
+It is the responsibility of the caller to free the returned string using
+.PN XtFree
+when it is no longer needed.
+.sp
+.LP
+To search for a file using standard substitutions in a path list, use
+.PN XtResolvePathname .
+.LP
+.IN "XtResolvePathname" "" "@DEF@"
+.sM
+.FD 0
+String XtResolvePathname(\fIdisplay\fP, \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \
+\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \fIpredicate\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      String \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \fIpath\fP;
+.br
+      Substitution \fIsubstitutions\fP;
+.br
+      Cardinal \fInum_substitutions\fP;
+.br
+      XtFilePredicate \fIpredicate\fP;
+.FN
+.IP \fIdisplay\fP 1.2i
+Specifies the display to use to find the language for language substitutions.
+.IP \fItype\fP
+.br
+.ns
+.IP \fIfilename\fP
+.br
+.ns
+.IP \fIsuffix\fP 1.2i
+Specify values to substitute into the path.
+.IP \fIpath\fP 1.2i
+Specifies the list of file specifications, or NULL.
+.IP \fIsubstitutions\fP 1.2i
+Specifies a list of additional substitutions to make into the path, or NULL.
+.IP \fInum_substitutions\fP 1.2i
+Specifies the number of entries in \fIsubstitutions\fP.
+.IP \fIpredicate\fP 1.2i
+Specifies a procedure called to judge each potential file name, or NULL.
+.LP
+.eM
+The substitutions specified by
+.PN XtResolvePathname
+are determined from the value of the language string retrieved by
+.PN XtDisplayInitialize
+for the specified display.
+To set the
+language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the
+resource database. 
+.IN "xnlLanguage"
+The format and content of the language string are
+implementation-defined.   One suggested syntax is to compose
+the language string of three parts;  a  ``language  part'',  a
+``territory  part'' and a ``codeset part''.  The manner in which
+this composition is accomplished is implementation-defined,
+and the \*(xI make no interpretation of the parts other
+than to use them in substitutions as described below.
+.LP
+.PN XtResolvePathname
+calls
+.PN XtFindFile
+with the following substitutions
+in addition to any passed by the caller and returns the value returned by
+.PN XtFindFile :
+.IP %N 5
+The value of the \fIfilename\fP parameter, or the application's
+class name if \fIfilename\fP is NULL.
+.IP %T 5
+The value of the \fItype\fP parameter.
+.IP %S 5
+The value of the \fIsuffix\fP parameter.
+.IP %L 5
+The language string associated with the specified display.
+.IP %l 5
+The language part of the display's language string.
+.IP %t 5
+The territory part of the display's language string.
+.IP %c 5
+The codeset part of the display's language string.
+.IP %C 5
+The customization string retrieved from the resource
+database associated with \fIdisplay\fP.
+.IP %D 5
+The value of the implementation-specific default path.
+.LP
+If a path is passed to
+.PN XtResolvePathname ,
+it is passed along to
+.PN XtFindFile .
+If the \fIpath\fP argument is NULL, the value of the
+.PN \s-1XFILESEARCHPATH\s+1
+.IN "XFILESEARCHPATH" "" "@DEF@"
+environment variable is passed to
+.PN XtFindFile .
+If
+.PN \s-1XFILESEARCHPATH\s+1
+is not defined, an implementation-specific default path is used
+that contains at least six entries.  These entries
+must contain the following substitutions:
+
+.nf
+.ta .3i 2i 2.5i
+1.	%C, %N, %S, %T, %L	or	%C, %N, %S, %T, %l, %t, %c
+2.	%C, %N, %S, %T, %l
+3.	%C, %N, %S, %T
+4.	%N, %S, %T, %L	or	%N, %S, %T, %l, %t, %c
+5.	%N, %S, %T, %l
+6.	%N, %S, %T
+.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.
+If the path begins
+with a colon, it is preceded by %N%S.  If the path includes two
+adjacent colons, \fB%N%S\fP is inserted between them.
+.LP
+The \fItype\fP parameter is intended to be a category of files, usually
+being translated into a directory in the pathname.  Possible values
+might include ``app-defaults'', ``help'', and ``bitmap''.
+.LP
+The \fIsuffix\fP parameter is intended to be appended to the file name.
+Possible values might include ``.txt'', ``.dat'', and ``.bm''.
+.LP
+A suggested value for the default path on POSIX-based systems is
+.IP
+/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\\
+.br
+/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\\
+.br
+/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
+
+.LP
+Using this example, if the user has specified a language, it is
+used as a subdirectory of /usr/lib/X11 that is searched for other
+files.  If the desired file is not found there, the lookup is
+tried again using just the language part of the specification.  If the
+file is not there, it is looked for in /usr/lib/X11.  The \fItype\fP
+parameter is used as a subdirectory of the language directory or of
+/usr/lib/X11, and \fIsuffix\fP is appended to the file name.
+.LP
+The %D substitution allows the addition of path
+elements to the implementation-specific default path, typically to
+allow additional directories to be searched without preventing
+resources in the system directories from being found.  For example, a
+user installing resource files under a directory called ``ourdir''
+might set
+.PN \s-1XFILESEARCHPATH\s+1
+to
+.IP
+%D:ourdir/%T/%N%C:ourdir/%T/%N
+.LP
+The customization string is obtained by querying the resource database
+currently associated with the display (the database returned by
+.PN XrmGetDatabase )
+for the resource \fIapplication_name\fP.customization, class
+\fIapplication_class\fP.Customization, where \fIapplication_name\fP
+and \fIapplication_class\fP are the values returned by
+.PN XtGetApplicationNameAndClass .
+If no value is specified in the database, the empty string is used.
+.LP
+It is the responsibility of the caller to free the returned string using
+.PN XtFree
+when it is no longer needed.
+
+.NH 2
+Hooks for External Agents
+.XS
+\fB\*(SN Hooks for External Agents\fP
+.XE
+.LP
+Applications may register
+functions that are called at a particular control points in the \*(xI.
+These functions are intended to be used to provide notification
+of an \*Q\*(tk event\*U, such as widget creation, to an external agent,
+such as an interactive resource editor, drag-and-drop server, or
+an aid for physically challenged users.
+The control points containing such registration hooks are identified
+in a \*Qhook registration\*U object.
+.LP
+To retrieve the hook registration widget, use
+.PN XtHooksOfDisplay .
+.LP
+.IN "XtHooksOfDisplay" "" "@DEF@"
+.sM
+.FD 0
+Widget XtHooksOfDisplay(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the desired display.
+.LP
+.eM
+The class of this object is a private, implementation-dependent
+subclass of
+.PN Object .
+The hook object has no parent.  The resources of this object are 
+the callback lists for hooks and the read-only resources for getting 
+a list of parentless shells.  All of the callback lists are initially 
+empty.  When a display is closed, the hook object associated with it 
+is destroyed. 
+.LP
+The following procedures can be called with the hook registration object
+as an argument:
+.sp
+.IP
+.PN XtAddCallback ,
+.PN XtAddCallbacks ,
+.PN XtRemoveCallback ,
+.PN XtRemoveCallbacks ,
+.PN XtRemoveAllCallbacks ,
+.PN XtCallCallbacks ,
+.PN XtHasCallbacks ,
+.PN XtCallCallbackList
+.IP
+.PN XtClass ,
+.PN XtSuperclass ,
+.PN XtIsSubclass ,
+.PN XtCheckSubclass ,
+.PN XtIsObject ,
+.PN XtIsRectObj ,
+.PN XtIsWidget ,
+.PN XtIsComposite ,
+.PN XtIsConstraint ,
+.PN XtIsShell ,
+.PN XtIsOverrideShell ,
+.PN XtIsWMShell ,
+.PN XtIsVendorShell ,
+.PN XtIsTransientShell ,
+.PN XtIsToplevelShell ,
+.PN XtIsApplicationShell ,
+.PN XtIsSessionShell
+.IP
+.PN XtWidgetToApplicationContext
+.IP
+.PN XtName ,
+.PN XtParent ,
+.PN XtDisplayOfObject ,
+.PN XtScreenOfObject
+.IP
+.PN XtSetValues ,
+.PN XtGetValues ,
+.PN XtVaSetValues ,
+.PN XtVaGetValues
+.sp
+.LP
+
+.NH 3
+Hook Object Resources
+.XS
+\fB\*(SN Hook Object Resources\fP
+.XE
+.LP
+The resource names, classes, and representation types that are specified
+in the hook object resource list are:
+.KS
+.TS
+lw(1.5i) lw(1.5i) lw(2.5i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNcreateHook	XtCCallback	XtRCallback
+XtNchangeHook	XtCCallback	XtRCallback
+XtNconfigureHook	XtCCallback	XtRCallback
+XtNgeometryHook	XtCCallback	XtRCallback
+XtNdestroyHook	XtCCallback	XtRCallback
+XtNshells	XtCReadOnly	XtRWidgetList
+XtNnumShells	XtCReadOnly	XtRCardinal
+.sp 6p
+_
+.TE
+.KE
+.LP
+Descriptions of each of these resources:
+.LP
+The XtNcreateHook callback list is called from:
+.PN XtCreateWidget ,
+.PN XtCreateManagedWidget ,
+.PN XtCreatePopupShell ,
+.PN XtAppCreateShell ,
+and their corresponding varargs versions.
+.LP
+The \fIcall_data\fP parameter in a createHook callback may be 
+cast to type
+.PN XtCreateHookData .
+.LP
+.IN "XtCreateHookData" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String   type;
+	Widget   widget;
+	ArgList  args;
+	Cardinal num_args;
+} XtCreateHookDataRec, *XtCreateHookData;
+.De
+.eM
+.LP
+The \fItype\fP is set to
+.PN XtHcreate ,
+\fIwidget\fP is the newly created widget, and \fIargs\fP and \fInum_args\fP
+are the arguments passed to the create function. The callbacks are 
+called before returning from the create function.
+.LP
+The XtNchangeHook callback list is called from:
+.IP
+.PN XtSetValues ,
+.PN XtVaSetValues
+.IP
+.PN XtManageChild ,
+.PN XtManageChildren ,
+.PN XtUnmanageChild ,
+.PN XtUnmanageChildren
+.IP
+.PN XtRealizeWidget ,
+.PN XtUnrealizeWidget
+.IP
+.PN XtAddCallback ,
+.PN XtRemoveCallback ,
+.PN XtAddCallbacks, 
+.PN XtRemoveCallbacks ,
+.PN XtRemoveAllCallbacks
+.IP
+.PN XtAugmentTranslations ,
+.PN XtOverrideTranslations ,
+.PN XtUninstallTranslations
+.IP
+.PN XtSetKeyboardFocus ,
+.PN XtSetWMColormapWindows
+.IP
+.PN XtSetMappedWhenManaged ,
+.PN XtMapWidget ,
+.PN XtUnmapWidget
+.IP
+.PN XtPopup ,
+.PN XtPopupSpringLoaded ,
+.PN XtPopdown
+.LP
+.sp
+.LP
+The \fIcall_data\fP parameter in a changeHook callback may
+be cast to type
+.PN XtChangeHookData .
+.IN "XtChangeHookData" "" "@DFEF@"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	String  type;
+	Widget  widget;
+	XtPointer event_data;
+	Cardinal num_event_data;
+} XtChangeHookDataRec, *XtChangeHookData;
+.De
+.eM
+.KE
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetValues
+or
+.PN XtVaSetValues ,
+\fItype\fP is set to
+.PN XtHsetValues ,
+\fIwidget\fP is the new widget passed to the set_values procedure, and
+\fIevent_data\fP may be cast to type 
+.PN XtChangeHookSetValuesData .
+.IN "XtChangeHookSetValuesData" "" "@DEF@"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	Widget   old, req;
+	ArgList  args;
+	Cardinal num_args;
+} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData;
+.De
+.eM
+.KE
+.LP
+The \fIold\fP, \fIreq\fP, \fIargs\fP, and \fInum_args\fP are the
+parameters passed to the set_values procedure.  The callbacks are called 
+after the set_values and constraint set_values procedures have been called.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtManageChild
+or
+.PN XtManageChildren ,
+\fItype\fP is set to
+.PN XtHmanageChildren ,
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type
+WidgetList and is the list of children being managed, and 
+\fInum_event_data\fP is the length of the widget list.
+The callbacks are called after the children have been managed.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUnmanageChild
+or
+.PN XtUnmanageChildren ,
+\fItype\fP is set to
+.PN XtHunmanageChildren ,
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type
+WidgetList and is a list of the children being unmanaged, and
+\fInum_event_data\fP is the length of the widget list.
+The callbacks are called after the children have been unmanaged.
+.LP
+The changeHook callbacks are called twice as a result of a call to
+.PN XtChangeManagedSet ,
+once after unmanaging and again after managing.
+When the callbacks are called the first time, \fItype\fP is set to
+.PN XtHunmanageSet , 
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type 
+WidgetList and is a list of the children being unmanaged, and 
+\fInum_event_data\fP is the length of the widget list.
+When the callbacks are called the second time, the \fItype\fP is set to
+.PN XtHmanageSet , 
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type 
+WidgetList and is a list of the children being managed, and 
+\fInum_event_data\fP is the length of the widget list.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRealizeWidget ,
+the \fItype\fP is set to
+.PN XtHrealizeWidget 
+and \fIwidget\fP is the widget being realized.
+The callbacks are called after the widget has been realized.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUnrealizeWidget ,
+the \fItype\fP is set to
+.PN XtHunrealizeWidget ,
+and \fIwidget\fP is the widget being unrealized.
+The callbacks are called after the widget has been unrealized.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtAddCallback ,
+\fItype\fP is set to
+.PN XtHaddCallback ,
+\fIwidget\fP is the widget to which the callback is being added, and
+\fIevent_data\fP may be cast to type String and is the name of the 
+callback being added.
+The callbacks are called after the callback has been added to the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtAddCallbacks ,
+the \fItype\fP is set to
+.PN XtHaddCallbacks ,
+\fIwidget\fP is the widget to which the callbacks are being added, and
+\fIevent_data\fP may be cast to type String and is the name of the 
+callbacks being added.
+The callbacks are called after the callbacks have been added to the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRemoveCallback ,
+the \fItype\fP is set to
+.PN XtHremoveCallback ,
+\fIwidget\fP is the widget from which the callback is being removed, and
+\fIevent_data\fP may be cast to type String and is the name of
+the callback being removed.  The callbacks are called after the callback 
+has been removed from the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRemoveCallbacks ,
+the \fItype\fP is set to
+.PN XtHremoveCallbacks ,
+\fIwidget\fP is the widget from which the callbacks are being removed, and
+\fIevent_data\fP may be cast to type String and is the name of the 
+callbacks being removed.  The callbacks are called after the callbacks 
+have been removed from the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRemoveAllCallbacks ,
+the \fItype\fP is set to
+.PN XtHremoveAllCallbacks
+and \fIwidget\fP is the widget from which the callbacks are being removed.
+The callbacks are called after the callbacks have been removed from the
+widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtAugmentTranslations ,
+the \fItype\fP is set to
+.PN XtHaugmentTranslations
+and \fIwidget\fP is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been 
+modified.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtOverrideTranslations ,
+the \fItype\fP is set to
+.PN XtHoverrideTranslations
+and \fIwidget\fP is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been 
+modified.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUninstallTranslations ,
+The \fItype\fP is
+.PN XtHuninstallTranslations
+and \fIwidget\fP is the widget whose translations are being uninstalled.
+The callbacks are called after the widget's translations have been 
+uninstalled.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetKeyboardFocus ,
+the \fItype\fP is set to
+.PN XtHsetKeyboardFocus
+and \fIevent_data\fP may be cast to type Widget and is the value of 
+the descendant argument passed to \fBXtSetKeyboardFocus\fP. The 
+callbacks are called before returning from \fBXtSetKeyboardFocus\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetWMColormapWindows ,
+\fItype\fP is set to
+.PN XtHsetWMColormapWindows ,
+\fIevent_data\fP may be cast to type WidgetList and is the value of 
+the list argument passed to \fBXtSetWMColormapWindows\fP, and 
+\fInum_event_data\fP is the length of the list. The callbacks are 
+called before returning from \fBXtSetWMColormapWindows\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetMappedWhenManaged ,
+the \fItype\fP is set to
+.PN XtHsetMappedWhenManaged
+and \fIevent_data\fP may be cast to type Boolean and is the value of 
+the mapped_when_managed argument passed to \fBXtSetMappedWhenManaged\fP. 
+The callbacks are called after setting the widget's mapped_when_managed 
+field and before realizing or unrealizing the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtMapWidget ,
+the \fItype \fP is set to
+.PN XtHmapWidget
+and \fIwidget\fP is the widget being mapped.
+The callbacks are called after mapping the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUnmapWidget ,
+the \fItype \fP is set to
+.PN XtHunmapWidget
+and \fIwidget\fP is the widget being unmapped.
+The callbacks are called after unmapping the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtPopup ,
+the \fItype\fP is set to
+.PN XtHpopup ,
+\fIwidget\fP is the widget being popped up, and \fIevent_data\fP may 
+be cast to type XtGrabKind and is the value of the grab_kind argument 
+passed to \fBXtPopup\fP.
+The callbacks are called before returning from \fBXtPopup\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtPopupSpringLoaded ,
+the \fItype\fP is set to
+.PN XtHpopupSpringLoaded
+and \fIwidget\fP is the widget being popped up.
+The callbacks are called 
+before returning from \fBXtPopupSpringLoaded\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtPopdown ,
+the \fItype\fP is set to
+.PN XtHpopdown
+and \fIwidget\fP is the widget being popped down.
+The callbacks are called 
+before returning from \fBXtPopdown\fP.
+.LP
+A widget set that exports interfaces that change application state
+without employing the \*(xI library should invoke the change hook
+itself.  This is done by:
+.sp
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+        XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data);
+.De
+.sp
+.LP
+The XtNconfigureHook callback list is called any time the \*(xI
+move, resize, or configure a widget and when
+.PN XtResizeWindow
+is called.
+.LP
+The \fIcall_data\fP parameter may be cast to type
+.PN XtConfigureHookData.
+.LP
+.IN "XtConfigureHookData" "" "@DEF@"
+.KS
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String type;
+	Widget widget;
+	XtGeometryMask changeMask;
+	XWindowChanges changes;	
+} XtConfigureHookDataRec, *XtConfigureHookData;
+.De
+.eM
+.KE
+.sp
+.LP
+When the configureHook callbacks are called, the \fItype\fP is
+.PN XtHconfigure ,
+\fIwidget\fP is the widget being configured, and \fIchangeMask\fP and 
+\fIchanges\fP reflect the changes made to the widget. The callbacks 
+are called after changes have been made to the widget.
+.LP
+The XtNgeometryHook callback list is called from 
+.PN XtMakeGeometryRequest
+and
+.PN XtMakeResizeRequest
+once before and once after geometry negotiation occurs.
+.LP
+The \fIcall_data\fP parameter may be cast to type
+.PN XtGeometryHookData .
+.LP
+.IN "XtGeometryHookData" "" "@DFEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String type;
+	Widget widget;
+	XtWidgetGeometry* request;
+	XtWidgetGeometry* reply;
+	XtGeometryResult result;
+} XtGeometryHookDataRec, *XtGeometryHookData;
+.De
+.eM
+.sp
+.LP
+When the geometryHook callbacks are called prior to geometry negotiation, 
+the \fItype\fP is
+.PN XtHpreGeometry ,
+\fIwidget\fP is the widget for which the request is being made, and
+\fIrequest\fP is the requested geometry.
+When the geometryHook callbacks 
+are called after geometry negotiation, the \fItype\fP is
+.PN XtHpostGeometry ,
+\fIwidget\fP is the widget for which the request was made, \fIrequest\fP
+is the requested geometry, \fIreply\fP is the resulting geometry granted, 
+and \fIresult\fP is the value returned from the geometry negotiation.
+.LP
+The XtNdestroyHook callback list is called when a widget is destroyed.
+The \fIcall_data parameter\fP may be cast to type
+.PN XtDestroyHookData .
+.LP
+.IN "XtDestroyHookData" "" "@DFEF@"
+.sp
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String type;
+	Widget widget;
+} XtDestroyHookDataRec, *XtDestroyHookData;
+.De
+.eM
+.sp
+.LP
+When the destroyHook callbacks are called as a result of a call to
+.PN XtDestroyWidget ,
+the \fItype\fP is
+.PN XtHdestroy
+and \fIwidget\fP is the widget being destroyed. The callbacks are
+called upon completion of phase one destroy for a widget.
+.LP
+The XtNshells and XtnumShells are read-only resources that report a
+list of all parentless shell widgets associated with a display.
+.LP
+Clients who use these hooks must exercise caution in calling \*(xI
+functions in order to avoid recursion.
+
+.NH 3
+Querying Open Displays
+.XS
+\fB\*(SN Querying Open Displays\fP
+.XE
+.LP
+To retrieve a list of the Displays associated with an application context,
+use
+.PN XtGetDisplays .
+.LP
+.IN "XtGetDisplays" "" "@DEF@"
+.sM
+.FD 0
+void XtGetDisplays(\fIapp_context\fP, \fIdpy_return\fP, \fInum_dpy_return\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      Display ***\fIdpy_return\fP;
+.br
+      Cardinal *\fInum_dpy_return\fP;
+.FN
+.IP \fIapp_context\fP 1.5i
+Specifies the application context.
+.IP \fIdpy_return\fP 1.5i
+Returns a list of open Display connections in the specified application
+context.
+.IP \fInum_dpy_return\fP 1.5i
+Returns the count of open Display connections in \fIdpy_return\fP.
+.LP
+.eM
+\fBXtGetDisplays\fP may be used by an external agent to query the
+list of open displays that belong to an application context. To free 
+the list of displays, use
+.PN XtFree .
+.bp
diff --git a/libXt/specs/CH12 b/libXt/specs/CH12
new file mode 100644
index 000000000..34e8ec77e
--- /dev/null
+++ b/libXt/specs/CH12
@@ -0,0 +1,1067 @@
+.\" $Xorg: CH12,v 1.3 2000/08/17 19:42:47 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 12\fP\s-1
+
+\s+1\fBNonwidget Objects\fP\s-1
+.sp 2
+.nr H1 12
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 12 \(em Nonwidget Objects
+.XE
+.LP
+Although widget writers are free to treat
+Core
+as the base class of
+the widget hierarchy, there are actually three classes above it.
+These classes are
+Object,
+RectObj
+(Rectangle Object), and (\fIunnamed\fP),
+and members of these classes
+are referred to generically as \fIobjects\fP.  By convention, the term
+\fIwidget\fP refers only to objects that are a subclass of
+Core,
+and the term \fInonwidget\fP refers to objects that are not a subclass of
+Core.
+In the preceding portion of this specification, the interface
+descriptions indicate explicitly whether the generic \fIwidget\fP argument
+is restricted to particular subclasses of Object.  Sections 12.2.5,
+12.3.5, and 12.5 summarize the permissible classes of the arguments to, and
+return values from, each of the \*(xI routines.
+
+.NH 2
+Data Structures
+.XS
+\*(SN Data Structures
+.XE
+.LP
+In order not to conflict with previous widget code, the data
+structures used by nonwidget objects do not follow all the same
+conventions as those for widgets.  In particular, the class records
+are not composed of parts but instead are complete data structures
+with filler for the widget fields they do not use.  This
+allows the static class initializers for existing widgets to remain
+unchanged.
+
+.NH 2
+Object Objects
+.XS
+\fB\*(SN Object Objects\fP
+.XE
+.LP
+.IN "Object" "" "@DEF@"
+The
+Object
+object contains the definitions of fields common to all
+objects.  It encapsulates the mechanisms for resource management.
+All objects and widgets are members of subclasses of
+Object,
+which is defined by the
+.PN ObjectClassPart
+and
+.PN ObjectPart
+structures.
+
+.NH 3
+ObjectClassPart Structure
+.XS
+\*(SN ObjectClassPart Structure
+.XE
+.LP
+The common fields for all object classes are defined in the
+.PN ObjectClassPart
+structure.  All fields have the same purpose,
+function, and restrictions as the corresponding fields in
+.PN CoreClassPart ;
+fields whose
+names are obj\fI\s+1n\s-1\fP for some integer \s+1\fIn\fP\s-1 are not
+used for Object,
+but exist to pad the data structure so that it matches Core's class
+record.  The class record initialization must fill all
+obj\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
+.LP
+.IN "ObjectClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ObjectClassPart {
+	WidgetClass superclass;
+	String class_name;
+	Cardinal widget_size;
+	XtProc class_initialize;
+	XtWidgetClassProc class_part_initialize;
+	XtEnum class_inited;
+	XtInitProc initialize;
+	XtArgsProc initialize_hook;
+	XtProc obj1;
+	XtPointer obj2;
+	Cardinal obj3;
+	XtResourceList resources;
+	Cardinal num_resources;
+	XrmClass xrm_class;
+	Boolean obj4;
+	XtEnum obj5;
+	Boolean obj6;
+	Boolean obj7;
+	XtWidgetProc destroy;
+	XtProc obj8;
+	XtProc obj9;
+	XtSetValuesFunc set_values;
+	XtArgsFunc set_values_hook;
+	XtProc obj10;
+	XtArgsProc get_values_hook;
+	XtProc obj11;
+	XtVersionType version;
+	XtPointer callback_private;
+	String obj12;
+	XtProc obj13;
+	XtProc obj14;
+	XtPointer extension;
+} ObjectClassPart;
+.De
+.LP
+.eM
+The extension record defined for
+.PN ObjectClassPart
+with a \fIrecord_type\fP equal to 
+.PN \s-1NULLQUARK\s+1
+is
+.PN ObjectClassExtensionRec .
+.LP
+.IN "ObjectClassExtensionRec" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XtPointer next_extension;	See Section 1.6.12
+	XrmQuark record_type;	See Section 1.6.12
+	long version;	See Section 1.6.12
+	Cardinal record_size;	See Section 1.6.12
+	XtAllocateProc allocate;	See Section 2.5.5.
+	XtDeallocateProc deallocate;	See Section 2.8.4.
+} ObjectClassExtensionRec, *ObjectClassExtension;
+.De
+.LP
+.eM
+The prototypical
+.PN ObjectClass
+consists of just the
+.PN ObjectClassPart .
+.LP
+.IN "ObjectClassRec" "" "@DEF@"
+.IN "ObjectClass" "" "@DEF@"
+.IN "objectClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ObjectClassRec {
+	ObjectClassPart object_class;
+} ObjectClassRec, *ObjectClass;
+.De
+.LP
+.eM
+The predefined class record and pointer for
+.PN ObjectClassRec
+are
+.LP
+In
+.PN IntrinsicP.h :
+.sM
+.Ds 0
+extern ObjectClassRec objectClassRec;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.sM
+.Ds 0
+extern WidgetClass objectClass;
+.De
+.LP
+.eM
+The opaque types
+.PN Object
+and
+.PN ObjectClass
+and the opaque variable
+.PN objectClass
+are defined for generic actions on objects.
+The symbolic constant for the
+.PN ObjectClassExtension
+version identifier is
+.PN XtObjectExtensionVersion
+(see Section 1.6.12).
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data:
+.LP
+.sM
+.Ds 0
+typedef struct _ObjectClassRec* ObjectClass;
+.De
+.LP
+.eM
+
+.NH 3
+ObjectPart Structure
+.XS
+\*(SN ObjectPart Structure
+.XE
+.LP
+The common fields for all object instances are defined in the
+.PN ObjectPart
+structure.  All fields have the same meaning as the
+corresponding fields in
+.PN CorePart .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.IN "ObjectPart" "" "@DEF@"
+typedef struct _ObjectPart {
+	Widget self;
+	WidgetClass widget_class;
+	Widget parent;
+	Boolean being_destroyed;
+	XtCallbackList destroy_callbacks;
+	XtPointer constraints;
+} ObjectPart;
+.De
+.LP
+.eM
+All object instances have the
+Object
+fields as their first component.  The prototypical type
+.PN Object
+is defined with only this set of fields.
+Various routines can cast object pointers, as needed, to specific
+object types.
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ObjectRec {
+	ObjectPart object;
+} ObjectRec, *Object;
+.De
+.LP
+.eM
+.IN "ObjectRec" "" "@DEF@"
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+typedef struct _ObjectRec *Object;
+.De
+.LP
+.eM
+
+.NH 3
+Object Resources
+.XS
+\fB\*(SN Object Resources\fP
+.XE
+.LP
+The resource names, classes, and representation types specified in the
+.PN objectClassRec
+resource list are:
+.LP
+.TS
+lw(1.5i) lw(1.5i) lw(2.5i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNdestroyCallback	XtCCallback	XtRCallback
+.sp 6p
+_
+.TE
+
+.NH 3
+ObjectPart Default Values
+.XS
+\fB\*(SN ObjectPart Default Values\fP
+.XE
+.LP
+All fields in
+.PN ObjectPart
+have the same default values as the corresponding fields in
+.PN CorePart .
+
+.NH 3
+Object Arguments to \*(xI Routines
+.XS
+\*(SN Object Arguments to \*(xI Routines
+.XE
+.LP
+The WidgetClass arguments to the following procedures may be
+.PN objectClass
+or any subclass:
+.sp
+.IP
+.PN XtInitializeWidgetClass ,
+.PN XtCreateWidget ,
+.PN XtVaCreateWidget
+.IP
+.PN XtIsSubclass ,
+.PN XtCheckSubclass
+.IP
+.PN XtGetResourceList ,
+.PN XtGetConstraintResourceList
+.sp
+.LP
+The Widget arguments to the following procedures may be of class
+Object
+or any subclass:
+.sp
+.IP
+.PN XtCreateWidget ,
+.PN XtVaCreateWidget
+.IP
+.PN XtAddCallback ,
+.PN XtAddCallbacks ,
+.PN XtRemoveCallback ,
+.PN XtRemoveCallbacks ,
+.PN XtRemoveAllCallbacks ,
+.PN XtCallCallbacks ,
+.PN XtHasCallbacks ,
+.PN XtCallCallbackList
+.IP
+.PN XtClass ,
+.PN XtSuperclass ,
+.PN XtIsSubclass ,
+.PN XtCheckSubclass ,
+.PN XtIsObject ,
+.PN XtIsRectObj ,
+.PN XtIsWidget ,
+.PN XtIsComposite ,
+.PN XtIsConstraint ,
+.PN XtIsShell ,
+.PN XtIsOverrideShell ,
+.PN XtIsWMShell ,
+.PN XtIsVendorShell ,
+.PN XtIsTransientShell ,
+.PN XtIsToplevelShell ,
+.PN XtIsApplicationShell ,
+.PN XtIsSessionShell
+.IP
+.PN XtIsManaged ,
+.PN XtIsSensitive
+.br
+(both will return
+.PN False
+if argument is not a subclass of
+RectObj)
+.IP
+.PN XtIsRealized
+.br
+(returns the state of the nearest windowed ancestor
+if class of argument is not a subclass of
+Core)
+.IP
+.PN XtWidgetToApplicationContext
+.IP    
+.PN XtDestroyWidget
+.IP
+.PN XtParent ,
+.PN XtDisplayOfObject ,
+.PN XtScreenOfObject ,
+.PN XtWindowOfObject
+.IP
+.PN XtSetKeyboardFocus
+(descendant)
+.IP
+.PN XtGetGC ,
+.PN XtReleaseGC
+.IP
+.PN XtName
+.IP
+.PN XtSetValues ,
+.PN XtGetValues ,
+.PN XtVaSetValues ,
+.PN XtVaGetValues
+.IP
+.PN XtGetSubresources ,
+.PN XtGetApplicationResources ,
+.PN XtVaGetSubresources ,
+.PN XtVaGetApplicationResources
+.IP
+.PN XtConvert ,
+.PN XtConvertAndStore
+.sp
+.LP
+The return value of the following procedures will be of class
+Object
+or a subclass:
+.sp
+.IP
+.PN XtCreateWidget ,
+.PN XtVaCreateWidget
+.IP
+.PN XtParent
+.IP
+.PN XtNameToWidget
+.sp
+.LP
+The return value of the following procedures will be
+.PN objectClass
+or a subclass:
+.sp
+.IP
+.PN XtClass ,
+.PN XtSuperclass
+
+.NH 3
+Use of Objects
+.XS
+\fB\*(SN Use of Objects\fP
+.XE
+.LP
+The
+Object
+class exists to enable programmers to use the \*(xI'
+classing and resource-handling mechanisms for things smaller
+and simpler than widgets.
+Objects make obsolete many common uses of subresources as described in
+Sections 9.4, 9.7.2.4, and 9.7.2.5.
+.LP
+Composite
+widget classes that wish to accept nonwidget children must
+set the \fIaccepts_objects\fP field in the
+.PN CompositeClassExtension
+structure to
+.PN True .
+.PN XtCreateWidget
+will otherwise generate an error message on an attempt to create a
+nonwidget child.
+.LP
+Of the classes defined by the \*(xI,
+ApplicationShell 
+and
+SessionShell
+accept nonwidget children, and the class of any nonwidget child
+must not be
+.PN rectObjClass
+or any subclass.  The intent of allowing
+Object
+children of
+ApplicationShell
+and
+SessionShell
+is to provide clients a simple mechanism
+for establishing the resource-naming root of an object hierarchy.
+
+.NH 2
+Rectangle Objects
+.XS
+\fB\*(SN Rectangle Objects\fP
+.XE
+.LP
+The class of rectangle objects is a subclass of
+Object
+that represents
+rectangular areas.  It encapsulates the mechanisms for geometry
+management and is called RectObj
+.IN "RectObj" "" "@DEF@"
+to avoid conflict with the Xlib
+.PN Rectangle
+data type.
+
+.NH 3
+RectObjClassPart Structure
+.XS
+\*(SN RectObjClassPart Structure
+.XE
+.LP
+As with the
+.PN ObjectClassPart
+structure, all fields in the
+.PN RectObjClassPart
+structure have the same
+purpose and function as the corresponding fields in
+.PN CoreClassPart ;
+fields whose names are rect\fI\s+1n\s-1\fP for some integer
+\fI\s+1n\s-1\fP are not used for
+RectObj, but exist to pad the data structure so that it matches
+Core's
+class record.  The class record initialization must fill all
+rect\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.IN "RectObjClassPart" "" "@DEF@"
+typedef struct _RectObjClassPart {
+	WidgetClass superclass;
+	String class_name;
+	Cardinal widget_size;
+	XtProc class_initialize;
+	XtWidgetClassProc class_part_initialize;
+	XtEnum class_inited;
+	XtInitProc initialize;
+	XtArgsProc initialize_hook;
+	XtProc rect1;
+	XtPointer rect2;
+	Cardinal rect3;
+	XtResourceList resources;
+	Cardinal num_resources;
+	XrmClass xrm_class;
+	Boolean rect4;
+	XtEnum rect5;
+	Boolean rect6;
+	Boolean rect7;
+	XtWidgetProc destroy;
+	XtWidgetProc resize;
+	XtExposeProc expose;
+	XtSetValuesFunc set_values;
+	XtArgsFunc set_values_hook;
+	XtAlmostProc set_values_almost;
+	XtArgsProc get_values_hook;
+	XtProc rect9;
+	XtVersionType version;
+	XtPointer callback_private;
+	String rect10;
+	XtGeometryHandler query_geometry;
+	XtProc rect11;
+	XtPointer extension ;
+} RectObjClassPart;
+.De
+.LP
+.eM
+The
+RectObj
+class record consists of just the
+.PN RectObjClassPart .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.IN "RectObjClassRec" "" "@DEF@"
+.IN "RectObjClass" "" "@DEF@"
+typedef struct _RectObjClassRec {
+	RectObjClassPart rect_class;
+} RectObjClassRec, *RectObjClass;
+.De
+.LP
+.eM
+The predefined class record and pointer for
+.PN RectObjClassRec
+are
+.LP
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+extern RectObjClassRec rectObjClassRec;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+extern WidgetClass rectObjClass;
+.De
+.LP
+.eM
+The opaque types
+.PN RectObj
+and
+.PN RectObjClass
+and the opaque variable
+.PN rectObjClass
+are defined for generic actions on objects
+whose class is RectObj or a subclass of
+RectObj.
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the compiler
+catches attempts to access private data:
+.LP
+.sM
+.Ds 0
+typedef struct _RectObjClassRec* RectObjClass;
+.De
+.LP
+.eM
+
+.NH 3
+RectObjPart Structure
+.XS
+\*(SN RectObjPart Structure
+.XE
+.LP
+In addition to the
+.PN ObjectPart
+fields,
+RectObj
+objects have the following fields defined in the
+.PN RectObjPart
+structure.  All fields have the same meaning as the corresponding field in
+.PN CorePart .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.IN "RectObjPart" "" "@DEF@"
+typedef struct _RectObjPart {
+	Position x, y;
+	Dimension width, height;
+	Dimension border_width;
+	Boolean managed;
+	Boolean sensitive;
+	Boolean ancestor_sensitive;
+} RectObjPart;
+.De
+.LP
+.eM
+RectObj
+objects have the RectObj fields immediately following the Object fields.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.IN "RectObjRec" "" "@DEF@"
+typedef struct _RectObjRec {
+	ObjectPart object;
+	RectObjPart rectangle;
+} RectObjRec, *RectObj;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+typedef struct _RectObjRec* RectObj;
+.De
+.LP
+.eM
+
+.NH 3
+RectObj Resources
+.XS
+\fB\*(SN RectObj Resources\fP
+.XE
+.LP
+The resource names, classes, and representation types that are specified in the
+.PN rectObjClassRec
+resource list are:
+.TS
+lw(1.5i) lw(1.5i) lw(2.5i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNancestorSensitive	XtCSensitive	XtRBoolean
+XtNborderWidth	XtCBorderWidth	XtRDimension
+XtNheight	XtCHeight	XtRDimension
+XtNsensitive	XtCSensitive	XtRBoolean
+XtNwidth	XtCWidth	XtRDimension
+XtNx	XtCPosition	XtRPosition
+XtNy	XtCPosition	XtRPosition
+.sp 6p
+_
+.TE
+
+.NH 3
+RectObjPart Default Values
+.XS
+\fB\*(SN RectObjPart Default Values\fP
+.XE
+.LP
+All fields in
+.PN RectObjPart
+have the same default values as the corresponding fields in
+.PN CorePart .
+
+.NH 3
+Widget Arguments to \*(xI Routines
+.XS
+\fB\*(SN Widget Arguments to \*(xI Routines\fP
+.XE
+.LP
+The WidgetClass arguments to the following procedures may be
+.PN rectObjClass
+or any subclass:
+.sp
+.IP
+.PN XtCreateManagedWidget ,
+.PN XtVaCreateManagedWidget
+.sp
+.LP
+The Widget arguments to the following procedures may be of class
+RectObj
+or any subclass:
+.sp
+.IP
+.PN XtConfigureWidget ,
+.PN XtMoveWidget ,
+.PN XtResizeWidget
+.IP
+.PN XtMakeGeometryRequest ,
+.PN XtMakeResizeRequest
+.IP
+.PN XtManageChildren ,
+.PN XtManageChild ,
+.PN XtUnmanageChildren ,
+.PN XtUnmanageChild ,
+.PN XtChangeManagedSet
+.IP
+.PN XtQueryGeometry
+.IP
+.PN XtSetSensitive
+.IP
+.PN XtTranslateCoords
+.sp
+.LP
+The return value of the following procedures will be of class
+RectObj
+or a subclass:
+.sp
+.IP
+.PN XtCreateManagedWidget ,
+.PN XtVaCreateManagedWidget
+
+.NH 3
+Use of Rectangle Objects
+.XS
+\*(SN Use of Rectangle Objects
+.XE
+.LP
+RectObj
+can be subclassed to provide widgetlike objects (sometimes
+called gadgets) that do not use windows and do not have those
+features that are seldom used in simple widgets.  This can save memory
+resources both in the server and in applications
+but requires additional support code in the parent.
+In the following
+discussion, \fIrectobj\fP refers only to objects
+whose class is RectObj or a subclass of
+RectObj,
+but not Core or a subclass of
+Core. 
+.LP
+Composite
+widget classes that wish to accept rectobj children must set
+the \fIaccepts_objects\fP field in the
+.PN CompositeClassExtension
+extension structure to
+.PN True .
+.PN XtCreateWidget
+or
+.PN XtCreateManagedWidget
+will otherwise generate an error if called to create a nonwidget child.
+If the composite widget supports only children of class
+RectObj
+or a subclass (i.e., not of the general Object class), it
+must declare an insert_child procedure and check the subclass of each
+new child in that procedure.  None of the classes defined by the
+\*(xI accept rectobj children.
+.LP
+If gadgets are defined in an object set, the parent is responsible for
+much more than the parent of a widget.  The parent must request and handle
+input events that occur for the gadget and is responsible for making
+sure that when it receives an exposure event the gadget children get
+drawn correctly.
+Rectobj children may
+have expose procedures
+specified in their class records, but the parent is free to
+ignore them, instead drawing the contents of the child itself.  This
+can potentially save graphics context switching.  The precise contents
+of the exposure event and region arguments to the RectObj expose
+procedure are not specified by the \*(xI; a particular rectangle object is
+free to define the coordinate system origin (self-relative or
+parent-relative) and whether or not the rectangle or region is assumed to
+have been intersected with the visible region of the object.
+.LP
+In general, it is expected that a composite widget that accepts
+nonwidget children will document those children it is able to handle,
+since a gadget cannot be viewed as a completely self-contained entity,
+as can a widget.  Since a particular composite widget class is usually
+designed to handle nonwidget children of only a limited set of classes, it should
+check the classes of newly added children in its insert_child
+procedure to make sure that it can deal with them.
+.LP
+The \*(xI will clear areas of a parent window obscured by
+rectobj children, causing exposure events, under the following
+circumstances:
+.IP \(bu 5
+A rectobj child is managed or unmanaged.
+.IP \(bu 5
+In a call to
+.PN XtSetValues
+on a rectobj child, one or more of the set_values procedures returns
+.PN True .
+.IP \(bu 5
+In a call to
+.PN XtConfigureWidget
+on a rectobj child, areas will
+be cleared corresponding to both the old and the new child
+geometries, including the border, if the geometry changes.
+.IP \(bu 5
+In a call to
+.PN XtMoveWidget
+on a rectobj child, areas will be
+cleared corresponding to both the old and the new child
+geometries, including the border, if the geometry changes.
+.IP \(bu 5
+In a call to
+.PN XtResizeWidget
+on a rectobj child, a single
+rectangle will be cleared corresponding to the larger of the
+old and the new child geometries if they are different.
+.IP \(bu 5
+In a call to
+.PN XtMakeGeometryRequest
+(or
+.PN XtMakeResizeRequest )
+on a rectobj child with
+.PN XtQueryOnly
+not set, if the manager returns
+.PN XtGeometryYes ,
+two rectangles will be cleared corresponding to both the old and
+the new child geometries.
+.LP
+Stacking order is not supported for rectobj children.  Composite widgets with
+rectobj children are free to define any semantics desired if the child
+geometries overlap, including making this an error.
+.LP
+When a rectobj is playing the role of a widget, developers must be
+reminded to avoid making assumptions about the object passed in the
+Widget argument to a callback procedure.
+
+.NH 2
+Undeclared Class
+.XS
+\*(SN Undeclared Class
+.XE
+.LP
+The \*(xI define an unnamed class between
+RectObj
+and
+Core
+for possible future use by the X Consortium. The only assumptions that
+may be made about the unnamed class are
+.IP \(bu 5
+The \fIcore_class.superclass\fP field of
+.PN coreWidgetClassRec
+contains a pointer to the unnamed class record.
+.IP \(bu 5
+A pointer to the unnamed class record when dereferenced as an
+.PN ObjectClass
+will contain a pointer to
+.PN rectObjClassRec
+in its \fIobject_class.superclass\fP field.
+.LP
+Except for the above, the contents of the class record for this class
+and the result of an attempt to subclass or to create a widget of this
+unnamed class are undefined.
+
+.NH 2
+Widget Arguments to \*(xI Routines
+.XS
+\*(SN Widget Arguments to \*(xI Routines
+.XE
+.LP
+The WidgetClass arguments to the following procedures must be of class
+Shell
+or a subclass:
+.sp
+.IP
+.PN XtCreatePopupShell ,
+.PN XtVaCreatePopupShell ,
+.PN XtAppCreateShell ,
+.PN XtVaAppCreateShell ,
+.PN XtOpenApplication ,
+.PN XtVaOpenApplication
+.sp
+.LP
+The Widget arguments to the following procedures must be of class
+Core
+or any subclass:
+.sp
+.IP
+.PN XtCreatePopupShell ,
+.PN XtVaCreatePopupShell
+.IP
+.PN XtAddEventHandler ,
+.PN XtAddRawEventHandler ,
+.PN XtRemoveEventHandler ,
+.br
+.PN XtRemoveRawEventHandler ,
+.PN XtInsertEventHandler ,
+.PN XtInsertRawEventHandler
+.br
+.PN XtInsertEventTypeHandler ,
+.PN XtRemoveEventTypeHandler ,
+.IP
+.PN XtRegisterDrawable
+.PN XtDispatchEventToWidget
+.IP
+.PN XtAddGrab ,
+.PN XtRemoveGrab ,
+.PN XtGrabKey ,
+.PN XtGrabKeyboard ,
+.PN XtUngrabKey ,
+.PN XtUngrabKeyboard ,
+.PN XtGrabButton ,
+.PN XtGrabPointer ,
+.PN XtUngrabButton ,
+.br
+.PN XtUngrabPointer
+.IP
+.PN XtBuildEventMask
+.IP
+.PN XtCreateWindow ,
+.PN XtDisplay ,
+.PN XtScreen ,
+.PN XtWindow
+.IP
+.PN XtNameToWidget
+.IP
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValues ,
+.PN XtOwnSelection ,
+.PN XtDisownSelection ,
+.PN XtOwnSelectionIncremental ,
+.PN XtGetSelectionValueIncremental ,
+.PN XtGetSelectionValuesIncremental ,
+.br
+.PN XtGetSelectionRequest
+.IP
+.PN XtInstallAccelerators ,
+.PN XtInstallAllAccelerators
+(both destination and source)
+.IP
+.PN XtAugmentTranslations ,
+.PN XtOverrideTranslations ,
+.PN XtUninstallTranslations ,
+.br
+.PN XtCallActionProc
+.IP
+.PN XtMapWidget ,
+.PN XtUnmapWidget
+.IP
+.PN XtRealizeWidget ,
+.PN XtUnrealizeWidget
+.IP
+.PN XtSetMappedWhenManaged
+.IP
+.PN XtCallAcceptFocus ,
+.PN XtSetKeyboardFocus
+(subtree)
+.IP
+.PN XtResizeWindow
+.IP
+.PN XtSetWMColormapWindows
+.sp
+.LP
+The Widget arguments to the following procedures must be of class
+Composite
+or any subclass:
+.sp
+.IP
+.PN XtCreateManagedWidget ,
+.PN XtVaCreateManagedWidget
+.sp
+.LP
+The Widget arguments to the following procedures must be of a subclass of
+Shell:
+.sp
+.IP
+.PN XtPopdown ,
+.PN XtCallbackPopdown ,
+.PN XtPopup ,
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+.PN XtCallbackExclusive ,
+.PN XtPopupSpringLoaded
+.sp
+.LP
+The return value of the following procedure will be of class
+Core
+or a subclass:
+.sp
+.IP
+.PN XtWindowToWidget
+.sp
+.LP
+The return value of the following procedures will be of a subclass of
+Shell:
+.sp
+.IP
+.PN XtAppCreateShell ,
+.PN XtVaAppCreateShell ,
+.PN XtAppInitialize ,
+.PN XtVaAppInitialize ,
+.PN XtCreatePopupShell ,
+.PN XtVaCreatePopupShell
+.bp
diff --git a/libXt/specs/CH13 b/libXt/specs/CH13
new file mode 100644
index 000000000..8c944a615
--- /dev/null
+++ b/libXt/specs/CH13
@@ -0,0 +1,805 @@
+.\" $Xorg: CH13,v 1.3 2000/08/17 19:42:47 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 13\fP\s-1
+
+\s+1\fBEvolution of the \*(xI\fP\s-1
+.sp 2
+.nr H1 13
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 13 \(em Evolution of the \*(xI
+.XE
+.LP
+The interfaces described by this specification have undergone several
+sets of revisions in the course of adoption as an X Consortium
+standard specification.  Having now been adopted by the Consortium as
+a standard part of the X Window System, it is expected that this and
+future revisions will retain
+backward compatibility in the sense that fully conforming
+implementations of these specifications may be produced that provide
+source compatibility with widgets and applications written to
+previous Consortium standard revisions.
+.LP
+The \*(xI do not place any special requirement on widget
+programmers to retain source or binary compatibility for their widgets
+as they evolve, but several conventions have been established to
+assist those developers who want to provide such compatibility.
+.LP
+In particular, widget programmers may wish to conform to the convention
+described in Section 1.6.12 when defining class extension records.
+
+.NH 2
+Determining Specification Revision Level
+.XS
+\fB\*(SN Determining Specification Revision Level\fP
+.XE
+.LP
+Widget and application developers who wish to maintain a common source
+pool that will build properly with implementations of the \*(xI
+at different revision levels of these specifications but that take
+advantage of newer features added in later revisions may use the
+symbolic macro
+.PN XtSpecificationRelease .
+.LP
+.Ds 0
+#define XtSpecificationRelease 6
+.De
+.IN "XtSpecificationRelease" "" "@DEF@"
+.LP
+As the symbol
+.PN XtSpecificationRelease
+was new to Release 4, widgets and
+applications desiring to build against earlier implementations should
+test for the presence of this symbol and assume only Release 3
+interfaces if the definition is not present.
+
+.NH 2
+Release 3 to Release 4 Compatibility
+.XS
+\fB\*(SN Release 3 to Release 4 Compatibility\fP
+.XE
+.LP
+At the data structure level, Release 4 retains binary compatibility
+with Release 3 (the first X Consortium standard release) for all data
+structures except
+.PN WMShellPart, 
+.PN TopLevelShellPart ,
+and
+.PN TransientShellPart .
+Release 4 changed the argument type to most procedures that now take
+arguments of type
+.PN XtPointer
+and structure members that are now of type
+.PN XtPointer
+in order to avoid potential ANSI C conformance problems.  It is
+expected that most implementations will be binary compatible with the
+previous definition.
+.LP
+Two fields in
+.PN CoreClassPart
+were changed from
+.PN Boolean
+to
+.PN XtEnum
+to allow implementations additional freedom in specifying the
+representations of each.  This change should require no source
+modification.
+
+.NH 3
+Additional Arguments
+.XS
+\*(SN Additional Arguments
+.XE
+.LP
+Arguments were added to the procedure definitions for
+.PN XtInitProc ,
+.PN XtSetValuesFunc ,
+and
+.PN XtEventHandler
+to provide more information and to
+allow event handlers to abort further dispatching of the current event
+(caution is advised!).  The added arguments to
+.PN XtInitProc
+and
+.PN XtSetValuesFunc
+make the initialize_hook and set_values_hook methods
+obsolete, but the hooks have been retained for those widgets that used
+them in Release 3.
+
+.NH 3
+set_values_almost Procedures
+.XS
+\*(SN set_values_almost Procedures
+.XE
+.LP
+The use of the arguments by a set_values_almost procedure was poorly
+described in Release 3 and was inconsistent with other conventions.
+.LP
+The current specification for the manner in which a set_values_almost
+procedure returns information to the \*(xI is not compatible with
+the Release 3 specification, and all widget implementations should
+verify that any set_values_almost procedures conform to the current
+interface.
+.LP
+No known implementation of the \*(xI correctly implemented the
+Release 3 interface, so it is expected that the impact of this
+specification change is small.
+
+.NH 3
+Query Geometry
+.XS
+\*(SN Query Geometry
+.XE
+.LP
+A composite widget layout routine that calls
+.PN XtQueryGeometry
+is now expected to store the complete new geometry in the intended structure;
+previously the specification said ``store the changes it intends to
+make''.  Only by storing the complete geometry does the child have
+any way to know what other parts of the geometry may still be
+flexible.  Existing widgets should not be affected by this, except
+to take advantage of the new information.
+
+.NH 3
+unrealizeCallback Callback List
+.XS
+\*(SN unrealizeCallback Callback List
+.XE
+.LP
+In order to provide a mechanism for widgets to be notified when they
+become unrealized through a call to
+.PN XtUnrealizeWidget ,
+the callback
+list name ``unrealizeCallback'' has been defined by the \*(xI.  A
+widget class that requires notification on unrealize may declare a
+callback list resource by this name.  No class is required to declare
+this resource, but any class that did so in a prior revision may find
+it necessary to modify the resource name if it does not wish to use the new
+semantics.
+
+.NH 3
+Subclasses of WMShell
+.XS
+\*(SN Subclasses of WMShell
+.XE
+.LP
+The formal adoption of the \fI\*(xC\fP as
+an X Consortium standard has meant the addition of four fields to
+.PN WMShellPart
+and one field to
+.PN TopLevelShellPart .
+In deference to some
+widget libraries that had developed their own additional conventions
+to provide binary compatibility, these five new fields were added at
+the end of the respective data structures. 
+.LP
+To provide more convenience for TransientShells, a field was added
+to the previously empty
+.PN TransientShellPart .
+On some architectures the size of the part structure will not
+have changed as a result of this.
+.LP
+Any widget implementation whose class is a subclass of
+TopLevelShell
+or
+TransientShell
+must at minimum be
+recompiled with the new data structure declarations.  Because
+.PN WMShellPart
+no longer contains a contiguous
+.PN XSizeHints
+data structure,
+a subclass that expected to do a single structure assignment of an
+.PN XSizeHints
+structure to the \fIsize_hints\fP field of
+.PN WMShellPart
+must be revised, though the old fields remain at the same positions within
+.PN WMShellPart .
+
+.NH 3
+Resource Type Converters
+.XS
+\*(SN Resource Type Converters
+.XE
+.LP
+A new interface declaration for resource type converters was defined
+to provide more information to converters, to support conversion
+cache cleanup with resource reference counting, and to allow
+additional procedures to be declared to free resources.  The old
+interfaces remain (in the compatibility section), and a new set of
+procedures was defined that work only with the new type converter
+interface.
+.LP
+In the now obsolete old type converter interface, converters are
+reminded that they must return the size of the converted value as well
+as its address.  The example indicated this, but the description of
+.PN XtConverter
+was incomplete.
+
+.NH 3
+KeySym Case Conversion Procedure
+.XS
+\*(SN KeySym Case Conversion Procedure
+.XE
+.LP
+The specification for the
+.PN XtCaseProc
+function type has been changed
+to match the Release 3 implementation, which included necessary
+additional information required by the function (a pointer to the
+display connection), and corrects the argument type of the source
+KeySym parameter.  No known implementation of the \*(xI
+implemented the previously documented interface.
+
+.NH 3
+Nonwidget Objects
+.XS
+\*(SN Nonwidget Objects
+.XE
+.LP
+Formal support for nonwidget objects is new to Release 4.  A
+prototype implementation was latent in at least one Release 3
+implementation of the \*(xI, but the specification has changed
+somewhat.  The most significant change is the requirement for a
+composite widget to declare the
+.PN CompositeClassExtension
+record with the \fIaccepts_objects\fP field set to
+.PN True
+in order to permit a client to create a nonwidget child.
+.LP
+The addition of this extension field ensures that composite widgets
+written under Release 3 will not encounter unexpected errors if an
+application attempts to create a nonwidget child.  In Release 4 there
+is no requirement that all composite widgets implement the extra
+functionality required to manage windowless children, so the
+\fIaccepts_objects\fP field allows a composite widget to declare that it
+is not prepared to do so.
+
+.NH 2
+Release 4 to Release 5 Compatibility
+.XS
+\fB\*(SN Release 4 to Release 5 Compatibility\fP
+.XE
+.LP
+At the data structure level, Release 5 retains complete binary
+compatibility with Release 4.  The specification of the
+.PN ObjectPart ,
+.PN RectObjPart ,
+.PN CorePart ,
+.PN CompositePart ,
+.PN ShellPart ,
+.PN WMShellPart ,
+.PN TopLevelShellPart ,
+and
+.PN ApplicationShellPart
+instance records was made less strict to permit implementations to
+add internal fields to these structures.  Any implementation that
+chooses to do so would, of course, force a recompilation.
+The Xlib specification for
+.PN XrmValue
+and
+.PN XrmOptionDescRec
+was updated to use a new type,
+.PN XPointer ,
+for the \fIaddr\fP and \fIvalue\fP fields, respectively, to avoid
+ANSI C conformance problems.  The definition of
+.PN XPointer
+is binary compatible with the previous implementation.
+
+.NH 3
+baseTranslations Resource
+.XS
+\fB\*(SN baseTranslations Resource\fP
+.XE
+
+.LP
+A new pseudo-resource, XtNbaseTranslations, was defined to permit
+application developers to specify translation tables in application
+defaults files while still giving end users the ability to augment
+or override individual event sequences.  This change will affect
+only those applications that wish to take advantage of the new
+functionality or those widgets that may have previously defined
+a resource named ``baseTranslations''.
+.LP
+Applications wishing to take advantage of the new functionality
+would change their application defaults file, e.g., from
+.Ds
+	app.widget.translations: \fIvalue\fP
+.DE
+to
+.Ds
+	app.widget.baseTranslations: \fIvalue\fP
+.DE
+If it is important to the application to preserve complete
+compatibility of the defaults file between different versions
+of the application running under Release 4 and Release 5,
+the full translations can be replicated in both the ``translations''
+and the ``baseTranslations'' resource.
+
+.NH 3
+Resource File Search Path
+.XS
+\fB\*(SN Resource File Search Path\fP
+.XE
+
+.LP
+The current specification allows implementations greater flexibility
+in defining the directory structure used to hold the application class
+and per-user application defaults files.  Previous specifications
+required the substitution strings to appear in the default path in a
+certain order, preventing sites from collecting all the files for
+a specific application together in one directory.  The Release 5
+specification allows the default path to specify the substitution
+strings in any order within a single path entry.  Users will need to
+pay close attention to the documentation for the specific
+implementation to know where to find these files and how to specify
+their own
+.PN \s-1XFILESEARCHPATH\s+1
+and
+.PN \s-1XUSERFILESEARCHPATH\s+1
+values when overriding the system defaults.
+
+.NH 3
+Customization Resource
+.XS
+\fB\*(SN Customization Resource\fP
+.XE
+
+.LP
+.PN XtResolvePathname
+supports a new substitution string, %C, for specifying separate
+application class resource files according to arbitrary user-specified
+categories.  The primary motivation for this addition was separate
+monochrome and color application class defaults files.  The
+substitution value is obtained by querying the current resource
+database for the application resource name ``customization'', class
+``Customization''.  Any application that previously used this
+resource name and class will need to be aware of the possibly
+conflicting semantics.
+
+.NH 3
+Per-Screen Resource Database
+.XS
+\fB\*(SN Per-Screen Resource Database\fP
+.XE
+
+.LP
+To allow a user to specify separate preferences for each screen of a
+display, a per-screen resource specification string has been added and
+multiple resource databases are created; one for each screen.  This
+will affect any application that modified the (formerly unique)
+resource database associated with the display subsequent to the \*(xI
+database initialization.  Such applications will need to be aware
+of the particular screen on which each shell widget is to be created.
+.LP
+Although the wording of the specification changed substantially in the
+description of the process by which the resource database(s) is
+initialized, the net effect is the same as in prior releases with the
+exception of the added per-screen resource specification and the new
+customization substitution string in
+.PN XtResolvePathname .
+
+.NH 3
+Internationalization of Applications
+.XS
+\fB\*(SN Internationalization of Applications\fP
+.XE
+
+.LP
+Internationalization as defined by ANSI is a technology that
+allows support of an application in a single locale.  In
+adding support for internationalization to the \*(xI
+the restrictions of this model have been followed.
+In particular, the new \*(xI interfaces are designed not to
+preclude an application from using other alternatives.
+For this reason, no \*(xI routine makes a call to establish the
+locale.   However, a convenience routine to establish the
+locale at initialize time has been provided, in the form
+of a default procedure that must be explicitly installed
+if the application desires ANSI C locale behavior.
+.LP
+As many objects in X, particularly resource databases, now inherit
+the global locale when they are created, applications wishing to use
+the ANSI C locale model should use the new function
+.PN XtSetLanguageProc
+to do so.
+.LP
+The internationalization additions also define event filters
+as a part of the Xlib Input Method specifications.  The
+\*(xI enable the use of event filters through additions to
+.PN XtDispatchEvent .
+Applications that may not be dispatching all events through
+.PN XtDispatchEvent
+should be reviewed in the context of this new input method mechanism.
+.LP
+In order to permit internationalization of error messages, the name
+and path of the error database file are now allowed to be
+implementation-dependent.
+No adequate standard mechanism has yet been suggested to
+allow the \*(xI to locate the database from localization information
+supplied by the client.
+.LP
+The previous specification for the syntax of the language string
+specified by
+.PN xnlLanguage
+has been dropped to avoid potential conflicts with other standards.
+The language string syntax is now implementation-defined.
+The example syntax cited is consistent with the previous
+specification.
+
+.NH 3
+Permanently Allocated Strings
+.XS
+\*(SN Permanently Allocated Strings
+.XE
+
+.LP
+In order to permit additional memory savings, an Xlib interface was
+added to allow the resource manager to avoid copying certain string
+constants.  The \*(xI specification was updated to explicitly require
+the Object \fIclass_name\fP, \fIresource_name\fP, \fIresource_class\fP,
+\fIresource_type\fP, \fIdefault_type\fP in resource tables, Core \fIactions\fP
+\fIstring\fP field, and Constraint \fIresource_name\fP, \fIresource_class\fP,
+\fIresource_type\fP, and \fIdefault_type\fP resource fields to be
+permanently allocated.  This explicit requirement is expected to
+affect only applications that may create and destroy classes
+on the fly.
+
+.NH 3
+Arguments to Existing Functions
+.XS
+\fB\*(SN Arguments to Existing Functions\fP
+.XE
+
+.LP
+The \fIargs\fP argument to
+.PN XtAppInitialize ,
+.PN XtVaAppInitialize ,
+.PN XtOpenDisplay ,
+.PN XtDisplayInitialize ,
+and
+.PN XtInitialize
+were changed from
+.PN Cardinal *
+to int* to conform to pre-existing convention and avoid otherwise
+annoying typecasting in ANSI C environments.
+
+.NH 2
+Release 5 to Release 6 Compatibility
+.XS
+\fB\*(SN Release 5 to Release 6 Compatibility\fP
+.XE
+.LP
+At the data structure level, Release 6 retains binary compatibility
+with Release 5 for all data structures except 
+.PN WMShellPart .
+Three resources were added to the specification.  
+The known implementations had unused space in the data structure,
+therefore on some architectures and implementations,
+the size of the part structure will not have changed as a result of this.
+
+.NH 3
+Widget Internals
+.XS
+\*(SN Widget Internals
+.XE
+.LP
+Two new widget methods for instance allocation and deallocation were added
+to the Object class.  These new methods 
+allow widgets to be treated as C++ objects in the C++ environment
+when an appropriate allocation method is specified or inherited 
+by the widget class.
+.LP
+The textual descriptions of the processes of widget creation and
+widget destruction have been edited to provide clarification to widget
+writers.  Widgets writers may have reason to rely on the specific order of 
+the stages of widget creation and destruction; with that motivation,
+the specification now more exactly describes the process.
+.LP
+As a convenience, an interface to locate a widget class extension
+record on a linked list, 
+.PN XtGetClassExtension ,
+has been added.
+.LP
+A new option to allow bundled changes to the managed set of a Composite
+widget is introduced in the Composite class extension record.
+Widgets that define a change_managed procedure that can accommodate
+additions and deletions to the managed set of children in a single
+invocation should set allows_change_managed_set to \fBTrue\fP in the
+extension record.
+.LP
+The wording of the process followed by
+.PN XtUnmanageChildren
+has changed slightly to better handle changes to the managed set
+during phase 2 destroy processing.
+.LP
+A new exposure event compression flag,
+.PN XtExposeNoRegion ,
+was added.  Many widgets specify exposure compression, but either
+ignore the actual damage region passed to the core expose procedure or
+use only the cumulative bounding box data available in the event.
+Widgets with expose procedures that do not make use of exact
+exposure region information can indicate that the \*(xI need not
+compute the region.
+
+.NH 3
+General Application Development
+.XS
+\*(SN General Application Development
+.XE
+.LP
+.PN XtOpenApplication
+is a new convenience procedure to initialize the toolkit, create an
+application context, open an X display connection, and create the
+root of the widget instance tree.  It is identical to the interface
+it replaces, 
+.PN XtAppInitialize ,
+in all respects except that it takes an additional argument specifying
+the widget class of the root shell to create.
+This interface is now the recommended one so that clients may easily
+become session participants.
+The old convenience procedures appear in the compatibility section.
+.LP
+The toolkit initialization function
+.PN XtToolkitInitialize
+may be called multiple times without penalty.
+.LP
+In order to optimize changes in geometry to a set of geometry-managed
+children, a new interface,
+.PN XtChangeManagedSet ,
+has been added.
+
+.NH 3
+Communication with Window and Session Managers
+.XS
+\*(SN Communication with Window and Session Managers
+.XE
+.LP
+The revision of the \fI\*(xC\fP as an X Consortium standard has resulted
+in the addition of three fields to the specification of
+.PN WMShellPart .
+These are \fIurgency\fP, \fIclient_leader\fP, and \fIwindow_role\fP.
+.LP
+The adoption of the \fIX Session Management Protocol\fP as an X Consortium
+standard has resulted in the addition of a new shell widget, 
+.PN SessionShell ,
+and an accompanying subclass verification interface,
+.PN XtIsSessionShell .
+This widget provides support for communication between an application
+and a session manager, as well as a window manager.
+In order to preserve compatibility with existing subclasses of 
+.PN ApplicationShell ,
+the 
+.PN ApplicationShell 
+was subclassed to create the new widget class.
+The session protocol requires a modal response to certain checkpointing
+operations by participating applications.  The
+.PN SessionShell
+structures
+the application's notification of and responses to messages from the session
+manager by use of various callback lists and by use of the new interfaces
+.PN XtSessionGetToken
+and 
+.PN XtSessionReturnToken .
+There is also a new command line argument, -xtsessionID, which facilitates
+the session manager in restarting applications based on the \*(xI.
+.LP
+The resource name and class strings defined by the \*(xI shell
+widgets in 
+.Pn < X11/Shell.h > 
+are now listed in Appendix E.  The addition of a new symbol
+for the 
+.PN WMShell
+\fIwait_for_wm\fP resource was made to bring the external symbol
+and the string it represents into agreement.  The actual resource name
+string in 
+.PN WMShell
+has not changed.
+The resource representation type of the XtNwinGravity resource of the 
+.PN WMShell
+was changed to XtRGravity in order to register a type 
+converter so that window gravity resource values could be specified by name.
+
+.NH 3
+Geometry Management
+.XS
+\*(SN Geometry Management
+.XE
+.LP
+A clarification to the specification was made to indicate that geometry
+requests may include current values along with the requested changes.
+
+.NH 3
+Event Management
+.XS
+\*(SN Event Management
+.XE
+.LP
+In Release 6, support is provided for registering selectors
+and event handlers for events generated by X protocol extensions
+and for dispatching those events to the appropriate widget.
+The new event handler registration interfaces are
+.PN XtInsertEventTypeHandler
+and
+.PN XtRemoveEventTypeHandler .
+Since the mechanism to indicate selection of extension events is specific
+to the extension being used, the \*(xI introduces 
+.PN XtRegisterExtensionSelector ,
+which allows the application to select for the events of interest.
+In order to change the dispatching algorithm to accommodate extension events
+as well as core X protocol events,
+the \*(xI event dispatcher may now be replaced or enveloped
+by the application with
+.PN XtSetEventDispatcher .
+The dispatcher may wish to call 
+.PN XtGetKeyboardFocusWidget
+to determine the widget with the current \*(xI keyboard focus.
+A dispatcher, after determining the destination widget, may use
+.PN XtDispatchEventToWidget
+to cause the event to be dispatched to the event handlers registered
+by a specific widget.
+.LP
+To permit the dispatching of events
+for nonwidget drawables, such as pixmaps that are not associated
+with a widget's window, 
+.PN XtRegisterDrawable
+and 
+.PN XtUnregisterDrawable
+have been added to the library.  A related update was made to
+the description of
+.PN XtWindowToWidget .
+.LP
+The library is now thread-safe, allowing one thread at a time to
+enter the library and protecting global data as necessary from concurrent use.
+Threaded toolkit applications are supported by the 
+new interfaces
+.PN XtToolkitThreadInitialize ,
+.PN XtAppLock ,
+.PN XtAppUnlock ,
+.PN XtAppSetExitFlag ,
+and 
+.PN XtAppGetExitFlag .
+Widget writers may also use 
+.PN XtProcessLock
+and 
+.PN XtProcessUnlock .
+.LP
+Safe handling of POSIX signals and other asynchronous notifications
+is now provided by use of 
+.PN XtAppAddSignal ,
+.PN XtNoticeSignal ,
+and
+.PN XtRemoveSignal .
+.LP
+The application can receive notification of an impending block
+in the \*(xI event manager by registering interest through
+.PN XtAppAddBlockHook
+and 
+.PN XtRemoveBlockHook .
+.LP
+.PN XtLastEventProcessed
+returns the most recent event passed to
+.PN XtDispatchEvent
+for a specified display.
+
+.NH 3
+Resource Management
+.XS
+\*(SN Resource Management
+.XE
+.LP
+Resource converters are registered by the \*(xI for window gravity
+and for three new resource types associated with session participation:
+RestartStyle, CommandArgArray and DirectoryString.
+.LP
+The file search path syntax has been extended to make it easier to
+include the default search path, which controls resource
+database construction, by using the new substitution string, %D.
+
+.NH 3
+Translation Management
+.XS
+\*(SN Translation Management
+.XE
+.LP
+The default key translator now recognizes the NumLock modifier.
+If NumLock is on and the second keysym is a keypad keysym
+(a standard keysym named with a ``KP'' prefix or a
+vendor-specific keysym in the hexadecimal range 0x11000000 to 0x1100FFFF),
+then the default key translator will
+use the first keysym if Shift and/or ShiftLock is on and will 
+use the second keysym if neither is on.  Otherwise, it will
+ignore NumLock and apply the normal protocol semantics.
+
+.NH 3
+Selections
+.XS
+\*(SN Selections
+.XE
+.LP
+The targets of selection requests may be parameterized, as described
+by the revised \fI\*(xC\fP.
+When such requests are made,
+.PN XtSetSelectionParameters
+is used by the requestor to specify the target parameters and
+.PN XtGetSelectionParameters
+is used by the selection owner to retrieve the parameters.
+When a parameterized target is specified in the context of a bundled
+request for multiple targets, 
+.PN XtCreateSelectionRequest ,
+.PN XtCancelSelectionRequest ,
+and 
+.PN XtSendSelectionRequest 
+are used to envelop the assembly of the request.
+When the parameters themselves are the names of properties, 
+the \*(xI provides support for the economical use of property atom names;
+see 
+.PN XtReservePropertyAtom
+and 
+.PN XtReleasePropertyAtom .
+
+.NH 3
+External Agent Hooks
+.XS
+\*(SN External Agent Hooks
+.XE
+.LP
+External agent hooks were added for the benefit of applications
+that instrument other applications for purposes of accessibility,
+testing, and customization.  The external agent and the application
+communicate by a shared protocol which is transparent to the application.
+The hook callbacks permit the external agent to register interest
+in groups or classes of toolkit activity and to be notified of the
+type and details of the activity as it occurs.  The new interfaces
+related to this effort are
+.PN XtHooksOfDisplay ,
+which returns the hook registration widget, and 
+.PN XtGetDisplays ,
+which returns a list of the X displays associated with an application context.
+.bp
diff --git a/libXt/specs/Makefile.am b/libXt/specs/Makefile.am
new file mode 100644
index 000000000..887eb7e1e
--- /dev/null
+++ b/libXt/specs/Makefile.am
@@ -0,0 +1,24 @@
+EXTRA_DIST = \
+	CH01 \
+	CH02 \
+	CH03 \
+	CH04 \
+	CH05 \
+	CH06 \
+	CH07 \
+	CH08 \
+	CH09 \
+	CH10 \
+	CH11 \
+	CH12 \
+	CH13 \
+	appA \
+	appB \
+	appC \
+	appD \
+	appE \
+	appF \
+	intr.idxmac.t \
+	postproc \
+	strings.mit \
+	Xtk.intr.front
diff --git a/libXt/specs/Xtk.intr.front b/libXt/specs/Xtk.intr.front
new file mode 100644
index 000000000..353467fdf
--- /dev/null
+++ b/libXt/specs/Xtk.intr.front
@@ -0,0 +1,333 @@
+.\" MIT header page and copyright notice
+.\" MIT page header and footers
+.\"
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 11
+.nr PS 11
+\&
+.sp 8
+.ce 4
+\s+2\fB\*(xT\fP\s-2
+
+\s+1\fBX Window System\fP\s-1
+
+\s+1\fBX Version 11, Release \*(Rn\fP\s-1
+
+
+First Revision - April, 1994
+.sp 5
+.ce 4
+\s-1Joel McCormack
+.sp 6p
+Digital Equipment Corporation
+Western Software Laboratory
+.sp 2
+.ce 4
+Paul Asente
+.sp 6p
+Digital Equipment Corporation
+Western Software Laboratory
+.sp 2
+.ce 4
+Ralph R. Swick
+.sp 6p
+Digital Equipment Corporation
+External Research Group
+MIT X Consortium
+.sp 2
+.ce 3
+version 6 edited by Donna Converse
+.sp 6p
+X Consortium, Inc.\s+1
+.bp
+\&
+.ps 9
+.nr PS 9
+.sp 8
+.LP
+X Window System is a trademark of X Consortium, Inc.
+.LP
+Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+X Consortium
+.LP
+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:
+.LP
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+.LP
+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.
+.LP
+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.
+.LP
+Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+Digital Equipment Corporation, Maynard, Massachusetts.
+.LP
+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.
+.ps 11
+.nr PS 11
+.bp 11
+.EF ''\fB \\\\n(PN \fP''
+.OF ''\fB \\\\n(PN \fP''
+.af PN i
+.XS ix
+Acknowledgments
+.XE
+\&
+.sp 1
+.ce 3
+\s+1\fBAcknowledgments\fP\s-1
+.sp 2
+.na
+.LP
+The design of the X11 Intrinsics was done primarily 
+by Joel McCormack of Digital WSL. 
+Major contributions to the design and implementation also
+were done by Charles Haynes, Mike Chow, and Paul Asente of Digital WSL.
+Additional contributors to the design and/or implementation were:
+.LP
+.Ds
+.ta 3i
+Loretta Guarino-Reid (Digital WSL)	Rich Hyde (Digital WSL)
+Susan Angebranndt (Digital WSL)	Terry Weissman (Digital WSL)
+Mary Larson (Digital UEG)	Mark Manasse (Digital SRC)
+Jim Gettys  (Digital SRC)	Leo Treggiari  (Digital SDT)
+Ralph Swick (Project Athena and Digital ERP)	Mark Ackerman (Project Athena)
+Ron Newman (Project Athena)	Bob Scheifler (MIT LCS)
+.De
+.LP
+The contributors to the X10 toolkit also deserve mention.
+Although the X11 Intrinsics present an entirely different programming style, 
+they borrow heavily from the implicit and explicit concepts in the X10 
+toolkit.
+.LP
+The design and implementation of the X10 Intrinsics were done by:
+.LP
+.Ds
+Terry Weissman (Digital WSL)
+Smokey Wallace (Digital WSL)
+Phil Karlton (Digital WSL)
+Charles Haynes (Digital WSL)
+Frank Hall (HP)
+.De
+.LP
+The design and implementation of the X10 toolkit's sample widgets were 
+by the above, as well as by:
+.LP
+.Ds
+Ram Rao (Digital UEG)
+Mary Larson (Digital UEG)
+Mike Gancarz (Digital UEG)
+Kathleen Langone  (Digital UEG)
+.De
+These widgets provided a checklist of requirements that we
+had to address in the X11 Intrinsics.
+.LP
+Thanks go to Al Mento of Digital's UEG Documentation Group for 
+formatting and generally improving this document
+and to John Ousterhout of Berkeley for extensively reviewing 
+early drafts of it.
+.LP
+Finally, a special thanks to Mike Chow,
+whose extensive performance analysis of the X10 toolkit provided
+the justification to redesign it entirely for X11.
+.LP
+.sp
+.Ds 0
+Joel McCormack
+Western Software Laboratory
+Digital Equipment Corporation
+
+March 1988
+.De
+.bp
+.LP
+The current design of the \*(xI has benefited greatly from the
+input of several dedicated reviewers in the membership of the
+X Consortium.
+In addition to those already mentioned,
+the following individuals have dedicated significant time
+to suggesting improvements to the \*(xI:
+.LP
+.Ds
+.ta 3i
+Steve Pitschke (Stellar)	C. Doug Blewett (AT&T)
+Bob Miller (HP)	David Schiferl (Tektronix)
+Fred Taft (HP)	Michael Squires (Sequent)
+Marcel Meth (AT&T)	Jim Fulton (MIT)
+Mike Collins (Digital)	Kerry Kimbrough (Texas Instruments)
+Scott McGregor (Digital)	Phil Karlton (Digital)
+Julian Payne (ESS)	Jacques Davy (Bull)
+Gabriel Beged-Dov (HP)	Glenn Widener (Tektronix)
+.De
+.LP
+Thanks go to each of them for the countless hours spent
+reviewing drafts and code.
+.LP
+.sp
+.Ds 0
+Ralph R. Swick
+External Research Group
+Digital Equipment Corporation
+MIT Project Athena
+
+June 1988
+.De
+.sp
+.LP
+From Release 3 to Release 4, several new members joined the design
+team.  We greatly appreciate the thoughtful comments, suggestions,
+lengthy discussions, and in some cases implementation code contributed by each
+of the following:
+.LP
+.Ds
+.ta 3i
+Don Alecci (AT&T)	Ellis Cohen (OSF)
+Donna Converse (MIT)	Clive Feather (IXI)
+Nayeem Islam (Sun)	Dana Laursen (HP)
+Keith Packard (MIT)	Chris Peterson (MIT)
+Richard Probst (Sun)	Larry Cable (Sun)
+.De
+.sp
+.LP
+In Release 5, the effort to define the internationalization additions was
+headed by Bill McMahon of Hewlett Packard and Frank Rojas of IBM.  This
+has been an educational process for many of us, and Bill and Frank's
+tutelage has carried us through.  Vania Joloboff of the OSF also contributed
+to the internationalization additions.  The implementation efforts of
+Bill, Gabe Beged-Dov, and especially Donna Converse for this release
+are also gratefully acknowledged.
+.sp
+.Ds 0
+Ralph R. Swick
+
+December 1989
+and
+July 1991
+.De
+.bp
+.LP
+The Release 6 Intrinsics is a result of the collaborative
+efforts of participants in the X Consortium's \fBintrinsics\fP
+working group.  
+A few individuals contributed substantial design proposals,
+participated in lengthy discussions, reviewed final specifications,
+and in most cases, were also responsible for sections of the implementation.
+They deserve recognition and thanks for their major contributions:
+.LP
+.Ds
+.ta 3i
+Paul Asente (Adobe)		Larry Cable (SunSoft)
+Ellis Cohen (OSF)		Daniel Dardailler (OSF)
+Vania Joloboff (OSF)		Kaleb Keithley (X Consortium)
+Courtney Loomis (HP)		Douglas Rand (OSF)
+Bob Scheifler (X Consortium)	Ajay Vohra (SunSoft)
+.De
+.LP
+Many others analyzed designs, offered useful comments and suggestions,
+and participated in a significant subset of the process.
+The following people deserve thanks for their contributions:
+Andy Bovingdon, Sam Chang, Chris Craig,
+George Erwin-Grotsky, Keith Edwards, Clive Feather, Stephen Gildea,
+Dan Heller, Steve Humphrey, David Kaelbling,
+Jaime Lau, Rob Lembree, Stuart Marks, Beth Mynatt,
+Tom Paquin, Chris Peterson, Kamesh Ramakrishna, Tom Rodriguez,
+Jim VanGilder, Will Walker, and Mike Wexler.
+.LP
+I am especially grateful to two of my colleagues: Ralph Swick for
+expert editorial guidance, and Kaleb Keithley for leadership in
+the implementation and the specification work.
+.sp
+.Ds 0
+Donna Converse
+X Consortium
+April 1994
+.De
+.bp
+.XS xii
+About This Manual
+.XE
+\&
+.sp 1
+.ce 3
+\s+1\fBAbout This Manual\fP\s-1
+.sp 2
+.na
+.LP
+\fI\*(xT\fP is intended to be read by both application programmers who will
+use one or more of the many widget sets built with the \*(xI 
+and by widget programmers who will use the \*(xI to build widgets 
+for one of the widget sets.
+Not all the information in this manual, however, applies to both audiences.
+That is, because the application programmer is likely to use only a number of
+the \*(xI functions in writing an application and because the widget programmer
+is likely to use many more, if not all, of the \*(xI functions in building 
+a widget,
+an attempt has been made to highlight those areas of information that are
+deemed to be of special interest for the application programmer.
+(It is assumed the widget programmer will have to be familiar with all 
+the information.)
+Therefore, all entries in the table of contents that are printed in \fBbold\fP 
+indicate the information that should be of special interest to an 
+application programmer.
+.LP
+It is also assumed that, as application programmers become
+more familiar with the concepts discussed in this manual,
+they will find it more convenient to implement
+portions of their applications as special-purpose or custom widgets.
+It is possible, nonetheless, to use widgets without knowing how to build them.
+.SH
+Conventions Used in this Manual
+.LP
+This document uses the following conventions:
+.IP \(bu 5
+Global symbols are printed in
+.PN this
+.PN special
+.PN font .
+These can be either function names,
+symbols defined in include files, data types, or structure names.
+Arguments to functions, procedures, or macros are printed in \fIitalics\fP.
+.IP \(bu 5
+Each function is introduced by a general discussion that
+distinguishes it from other functions.
+The function declaration itself follows,
+and each argument is specifically explained.
+General discussion of the function, if any is required,
+follows the arguments.
+.IP \(bu 5
+To eliminate any ambiguity between those arguments that you pass and those that
+a function returns to you,
+the explanations for all arguments that you pass start with the word
+\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\fP.
+The explanations for all arguments that are returned to you start with the
+word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
+.bp 1
+.af PN 1
+.EH '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP'
+.OH '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP'
diff --git a/libXt/specs/appA b/libXt/specs/appA
new file mode 100644
index 000000000..57a1890a7
--- /dev/null
+++ b/libXt/specs/appA
@@ -0,0 +1,107 @@
+.\" $Xorg: appA,v 1.3 2000/08/17 19:42:48 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix A\fP\s-1
+
+\s+1\fBResource File Format\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix A \(em Resource File Format\fP
+.XE
+A resource file contains text representing the default resource values for an
+application or set of applications.
+.LP
+The format of resource files is defined by \fI\*(xL\fP and is reproduced here
+for convenience only. 
+.LP
+The format of a resource specification is
+.TS
+l l .
+ResourceLine	= Comment | IncludeFile | ResourceSpec | <empty line>
+Comment	= ``!'' {<any character except null or newline>}
+IncludeFile	= ``#'' WhiteSpace ``include'' WhiteSpace FileName WhiteSpace
+FileName	= <valid filename for operating system>
+ResourceSpec	= WhiteSpace ResourceName WhiteSpace ``:'' WhiteSpace Value
+ResourceName	= [Binding] {Component Binding} ComponentName
+Binding	= ``.'' | ``*''
+WhiteSpace	= {<space> | <horizontal tab>}
+Component	= ``?'' | ComponentName
+ComponentName	= NameChar {NameChar}
+NameChar	= ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-''
+Value	= {<any character except null or unescaped newline>}
+.TE
+.LP
+Elements separated by vertical bar (|) are alternatives.
+Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
+of the enclosed elements.
+Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional.
+Quotes (``\&.\&.\&.'') are used around literal characters.
+.LP
+If the last character on a line is a backslash (\\),
+that line is assumed to continue on the next line.
+.LP
+To allow a Value to begin with whitespace,
+the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space)
+is recognized and replaced by a space character,
+and the two-character sequence ``\\\^\fItab\fP''
+(backslash followed by horizontal tab)
+is recognized and replaced by a horizontal tab character.
+
+To allow a Value to contain embedded newline characters,
+the two-character sequence ``\\\^n'' is recognized and replaced by a
+newline character.
+To allow a Value to be broken across multiple lines in a text file,
+the two-character sequence ``\\\^\fInewline\fP''
+(backslash followed by newline) is
+recognized and removed from the value.
+
+To allow a Value to contain arbitrary character codes,
+the four-character sequence ``\\\^\fInnn\fP'',
+where each \fIn\fP is a digit character in the range of ``0''\-``7'',
+is recognized and replaced with a single byte that contains
+the octal value specified by the sequence.
+Finally, the two-character sequence ``\\\\'' is recognized
+and replaced with a single backslash.
diff --git a/libXt/specs/appB b/libXt/specs/appB
new file mode 100644
index 000000000..3eb9ccc7b
--- /dev/null
+++ b/libXt/specs/appB
@@ -0,0 +1,783 @@
+.\" $Xorg: appB,v 1.3 2000/08/17 19:42:48 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix B\fP\s-1
+
+\s+1\fBTranslation Table Syntax\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix B \(em Translation Table Syntax\fP
+.XE
+.IN "Translation tables"
+.SH
+Notation
+.LP
+Syntax is specified in EBNF notation with the following conventions:
+.TS
+l l.
+[ a ]	Means either nothing or ``a''
+{ a }	Means zero or more occurrences of ``a''
+( a | b )	Means either ``a'' or ``b''
+\\\\n	Is the newline character
+.TE
+.LP
+All terminals are enclosed in double quotation marks (`` '').
+Informal descriptions are enclosed in angle brackets (< >).
+.SH
+Syntax
+.LP
+The syntax of a translation table is
+.TS
+l l .
+translationTable	= [ directive ] { production }
+directive	= ( ``#replace'' | ``#override'' | ``#augment'' ) ``\\\\n''
+production	= lhs ``:'' rhs ``\\\\n''
+lhs	= ( event | keyseq ) { ``,'' (event | keyseq) }
+keyseq	= ``"'' keychar {keychar} ``"''
+keychar	= [ ``^'' | ``$'' | ``\\\\'' ] <ISO Latin 1 character>
+event	= [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail}
+modifier_list	= ( [``!''] [``:''] {modifier} ) | ``None''
+modifier	= [``~''] modifier_name
+count	= (``1'' | ``2'' | ``3'' | ``4'' | ...)
+modifier_name	= ``@'' <keysym> | <see ModifierNames table below>
+event_type	= <see Event Types table below>
+detail	= <event specific details>
+rhs	= { name ``('' [params] ``)'' }
+name	= namechar { namechar }
+namechar	= { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' }
+params	= string {``,'' string}
+string	= quoted_string | unquoted_string
+quoted_string	= ``"'' {<Latin 1 character> | escape_char} [``\\\\\\\\'' ] ``"''
+escape_char	= ``\\\\"''
+unquoted_string	= {<Latin 1 character except space, tab, ``,'', ``\\\\n'', ``)''>}
+.TE
+
+.LP
+The \fIparams\fP field is parsed into a list of
+.PN String
+values that will be passed to the named action procedure.  A
+\fIquoted string\fP may contain an embedded quotation mark if the
+quotation mark is preceded by a single backslash (\\).  The
+three-character sequence ``\\\\"'' is interpreted as ``single backslash
+followed by end-of-string''.
+
+.SH
+Modifier Names
+.LP
+The modifier field is used to specify standard X keyboard and button
+modifier mask bits.
+Modifiers are legal on event types 
+.PN KeyPress ,
+.PN KeyRelease , 
+.PN ButtonPress ,
+.PN ButtonRelease ,
+.PN MotionNotify ,
+.PN EnterNotify ,
+.PN LeaveNotify ,
+and their abbreviations.
+An error is generated when a translation table 
+that contains modifiers for any other events is parsed.
+.IP \(bu 5
+If the modifier list has no entries and is not ``None'',
+it means ``don't care'' on all modifiers.
+.IP \(bu 5
+If an exclamation point (!) is specified at the beginning 
+of the modifier list,
+it means that the listed modifiers must be in the correct state
+and no other modifiers can be asserted.
+.IP \(bu 5
+If any modifiers are specified 
+and an exclamation point (!) is not specified,
+it means that the listed modifiers must be in the
+correct state and ``don't care'' about any other modifiers.
+.IP \(bu 5
+If a modifier is preceded by a tilde (~),
+it means that that modifier must not be asserted.
+.IP \(bu 5
+If ``None'' is specified, it means no modifiers can be asserted.
+.IP \(bu 5
+If a colon (:) is specified at the beginning of the modifier list,
+it directs the \*(xI to apply any standard modifiers in the
+event to map the event keycode into a KeySym.
+The default standard modifiers are Shift and Lock, 
+with the interpretation as defined in \fI\*(xP\fP, Section 5.
+The resulting KeySym must exactly match the specified
+KeySym, and the nonstandard modifiers in the event must match the
+modifier list.
+For example, ``:<Key>a'' is distinct from ``:<Key>A'', 
+and ``:Shift<Key>A'' is distinct from ``:<Key>A''.
+.IP \(bu 5
+If both an exclamation point (!) and a colon (:) are specified at
+the beginning of the modifier list, it means that the listed
+modifiers must be in the correct state and that no other modifiers
+except the standard modifiers can be asserted.  Any standard
+modifiers in the event are applied as for colon (:) above.
+.IP \(bu 5
+If a colon (:) is not specified,
+no standard modifiers are applied.
+Then, for example, ``<Key>A'' and ``<Key>a'' are equivalent.
+.LP
+In key sequences,
+a circumflex (^) is an abbreviation for the Control modifier,
+a dollar sign ($) is an abbreviation for Meta, 
+and a backslash (\\) can be used to quote any
+character, in particular a double quote ("), a circumflex (^), 
+a dollar sign ($), and another backslash (\\).
+Briefly:
+.LP
+.Ds 0
+.TA 2.5i
+.ta 2.5i
+No modifiers:	None <event> detail
+Any modifiers:	<event> detail
+Only these modifiers:	! mod1 mod2 <event> detail
+These modifiers and any others:	mod1 mod2 <event> detail
+.De
+.LP
+The use of ``None'' for a modifier list is identical to the use
+of an exclamation point with no modifers.
+.LP
+.TS H
+lw(1i) lw(1i) lw(3i).
+_
+.sp 6p
+Modifier	Abbreviation	Meaning
+.sp 6p
+_
+.sp 6p
+.R
+.TH
+Ctrl	c	Control modifier bit
+Shift	s	Shift modifier bit
+Lock	l	Lock modifier bit
+Meta	m	Meta key modifier
+Hyper	h	Hyper key modifier
+Super	su	Super key modifier
+Alt	a	Alt key modifier
+Mod1		Mod1 modifier bit
+Mod2		Mod2 modifier bit
+Mod3		Mod3 modifier bit
+Mod4		Mod4 modifier bit
+Mod5		Mod5 modifier bit
+Button1		Button1 modifier bit
+Button2		Button2 modifier bit
+Button3		Button3 modifier bit
+Button4		Button4 modifier bit
+Button5		Button5 modifier bit
+None		No modifiers
+Any		Any modifier combination
+.sp 6p
+_
+.TE
+.LP
+.IN "key modifier"
+A key modifier is any modifier bit one of whose corresponding KeyCodes
+contains the corresponding left or right KeySym.
+For example, 
+``m'' or ``Meta'' means any modifier bit mapping to a KeyCode 
+whose KeySym list contains XK_Meta_L or XK_Meta_R.
+Note that this interpretation is for each display, 
+not global or even for each application context.
+The Control, Shift, and Lock modifier names refer
+explicitly to the corresponding modifier bits; 
+there is no additional interpretation of KeySyms for these modifiers.
+.LP
+Because it is possible to associate arbitrary KeySyms with modifiers, the set of
+key modifiers is extensible.  The ``@'' <keysym> syntax means any
+modifier bit whose corresponding KeyCode contains the specified KeySym name.
+.LP
+A modifier_list/KeySym combination in a translation matches a
+modifiers/KeyCode combination in an event in the following ways:
+.IP 1. 5
+If a colon (:) is used, the \*(xI call the display's 
+.PN XtKeyProc 
+with the KeyCode and modifiers.
+To match, (\fImodifiers\fP & ~\fImodifiers_return\fP) must equal \fImodifier_list\fP, and
+\fIkeysym_return\fP must equal the given KeySym.
+.IP 2. 5
+If (:) is not used, the \*(xI mask off all don't-care bits from the 
+modifiers.
+This value must be equal to \fImodifier_list\fP.
+Then, for each possible combination of
+don't-care modifiers in the modifier list, the \*(xI call the display's 
+.PN XtKeyProc
+with the KeyCode and that combination ORed with the cared-about modifier bits 
+from the event.
+\fIKeysym_return\fP must match the KeySym in the translation.
+.SH
+Event Types
+.LP
+The event-type field describes XEvent types.
+In addition to the standard
+Xlib symbolic event type names, the following event type synonyms
+are defined:
+.TS H
+lw(1.5i) lw(3i).
+_
+.sp 6p
+Type	Meaning
+.sp 6p
+_
+.sp 6p
+.TH
+Key	T{
+.PN KeyPress
+T}
+KeyDown	T{
+.PN KeyPress
+T}
+KeyUp	T{
+.PN KeyRelease
+T}
+BtnDown	T{
+.PN ButtonPress
+T}
+BtnUp	T{
+.PN ButtonRelease
+T}
+Motion	T{
+.PN MotionNotify
+T}
+PtrMoved	T{
+.PN MotionNotify
+T}
+MouseMoved	T{
+.PN MotionNotify
+T}
+Enter	T{
+.PN EnterNotify
+T}
+EnterWindow	T{
+.PN EnterNotify
+T}
+Leave	T{
+.PN LeaveNotify
+T}
+LeaveWindow	T{
+.PN LeaveNotify
+T}
+FocusIn	T{
+.PN FocusIn
+T}
+FocusOut	T{
+.PN FocusOut
+T}
+Keymap	T{
+.PN KeymapNotify
+T}
+Expose	T{
+.PN Expose
+T}
+GrExp	T{
+.PN GraphicsExpose
+T}
+NoExp	T{
+.PN NoExpose
+T}
+Visible	T{
+.PN VisibilityNotify
+T}
+Create	T{
+.PN CreateNotify
+T}
+Destroy	T{
+.PN DestroyNotify
+T}
+Unmap	T{
+.PN UnmapNotify
+T}
+Map	T{
+.PN MapNotify
+T}
+MapReq	T{
+.PN MapRequest
+T}
+Reparent	T{
+.PN ReparentNotify
+T}
+Configure	T{
+.PN ConfigureNotify
+T}
+ConfigureReq	T{
+.PN ConfigureRequest
+T}
+Grav	T{
+.PN GravityNotify
+T}
+ResReq	T{
+.PN ResizeRequest
+T}
+Circ	T{
+.PN CirculateNotify
+T}
+CircReq	T{
+.PN CirculateRequest
+T}
+Prop	T{
+.PN PropertyNotify
+T}
+SelClr	T{
+.PN SelectionClear
+T}
+SelReq	T{
+.PN SelectionRequest
+T}
+Select	T{
+.PN SelectionNotify
+T}
+Clrmap	T{
+.PN ColormapNotify
+T}
+Message	T{
+.PN ClientMessage
+T}
+Mapping	T{
+.PN MappingNotify
+T}
+.sp 6p
+_
+.TE
+The supported abbreviations are:
+.TS H
+lw(1.5i) lw(1.25i) lw(1.75i).
+_
+.sp 6p
+Abbreviation	Event Type	Including
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Ctrl	T{
+.PN KeyPress
+T}	with Control modifier
+Meta	T{
+.PN KeyPress
+T}	with Meta modifier
+Shift	T{
+.PN KeyPress
+T}	with Shift modifier
+Btn1Down	T{
+.PN ButtonPress
+T}	with Button1 detail
+Btn1Up	T{
+.PN ButtonRelease
+T}	with Button1 detail
+Btn2Down	T{
+.PN ButtonPress
+T}	with Button2 detail
+Btn2Up	T{
+.PN ButtonRelease
+T}	with Button2 detail
+Btn3Down	T{
+.PN ButtonPress
+T}	with Button3 detail
+Btn3Up	T{
+.PN ButtonRelease
+T}	with Button3 detail
+Btn4Down	T{
+.PN ButtonPress
+T}	with Button4 detail
+Btn4Up	T{
+.PN ButtonRelease
+T}	with Button4 detail
+Btn5Down	T{
+.PN ButtonPress
+T}	with Button5 detail
+Btn5Up	T{
+.PN ButtonRelease
+T}	with Button5 detail
+BtnMotion	T{
+.PN MotionNotify
+T}	with any button modifier
+Btn1Motion	T{
+.PN MotionNotify
+T}	with Button1 modifier
+Btn2Motion	T{
+.PN MotionNotify
+T}	with Button2 modifier
+Btn3Motion	T{
+.PN MotionNotify
+T}	with Button3 modifier
+Btn4Motion	T{
+.PN MotionNotify
+T}	with Button4 modifier
+Btn5Motion	T{
+.PN MotionNotify
+T}	with Button5 modifier
+.sp 6p
+_
+.TE
+.sp
+.LP
+The detail field is event-specific and normally corresponds to the
+detail field of the corresponding event as described
+by \fI\*(xP\fP, Section 11.  The detail field is supported
+for the following event types:
+.LP
+.TS H
+l l .
+_
+.sp 6p
+Event	Event Field
+.sp 6p
+_
+.TH
+.sp 6p
+KeyPress	KeySym from event \fIdetail\fP (keycode)
+KeyRelease	KeySym from event \fIdetail\fP (keycode)
+ButtonPress	button from event \fIdetail\fP
+ButtonRelease	button from event \fIdetail\fP
+MotionNotify	event \fIdetail\fP
+EnterNotify	event \fImode\fP
+LeaveNotify	event \fImode\fP
+FocusIn	event \fImode\fP
+FocusOut	event \fImode\fP
+PropertyNotify	\fIatom\fP
+SelectionClear	\fIselection\fP
+SelectionRequest	\fIselection\fP
+SelectionNotify	\fIselection\fP
+ClientMessage	\fItype\fP
+MappingNotify	\fIrequest\fP
+.sp 6p
+_
+.TE
+.LP
+If the event type is
+.PN KeyPress
+or
+.PN KeyRelease ,
+the detail field
+specifies a KeySym name in standard format which is matched against
+the event as described above, for example, <Key>A.
+.LP
+For the
+.PN PropertyNotify ,
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+and
+.PN ClientMessage
+events the detail field is specified
+as an atom name; for example, <Message>WM_PROTOCOLS.  For the
+.PN MotionNotify ,
+.PN EnterNotify ,
+.PN LeaveNotify ,
+.PN FocusIn ,
+.PN FocusOut ,
+and
+.PN MappingNotify
+events, either the symbolic constants as defined by
+\fI\*(xP\fP, Section 11,
+or the numeric values may be specified.
+.LP
+If no detail field is specified, then any value in the event detail is
+accepted as a match.
+.LP
+A KeySym can be specified as any of the standard KeySym names, 
+a hexadecimal number prefixed with ``0x'' or ``0X'', 
+an octal number prefixed with ``0'', or a decimal number.
+A KeySym expressed as a single digit is interpreted as the
+corresponding Latin 1 KeySym, for example, ``0'' is the KeySym XK_0.
+Other single character KeySyms are treated as literal constants from Latin 1,
+for example, ``!'' is treated as 0x21.
+Standard KeySym names are as defined in 
+.Pn < X11/keysymdef.h >
+with the ``XK_'' prefix removed.
+.LP
+.SH
+Canonical Representation
+.LP
+Every translation table has a unique, canonical text representation. This
+representation is passed to a widget's
+.PN display_accelerator
+procedure to describe the accelerators installed on that widget.
+The canonical representation of a translation table is (see also
+``Syntax'')
+.TS
+l l .
+translationTable	= { production }
+production	= lhs ``:'' rhs ``\\\\n''
+lhs	= event { ``,'' event  }
+event	= [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail}
+modifier_list	= [``!''] [``:''] {modifier}
+modifier	= [``~''] modifier_name
+count	= (``1'' | ``2'' | ``3'' | ``4'' | ...)
+modifier_name	= ``@'' <keysym> | <see canonical modifier names below>
+event_type	= <see canonical event types below>
+detail	= <event-specific details>
+rhs	= { name ``('' [params] ``)'' }
+name	= namechar { namechar }
+namechar	= { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' }
+params	= string {``,'' string}
+string	= quoted_string
+quoted_string	= ``"'' {<Latin 1 character> | escape_char} [``\\\\\\\\'' ] ``"''
+escape_char	= ``\\\\"''
+.TE
+.LP
+The canonical modifier names are
+.LP
+.Ds
+.TA 1i 2.5i
+.ta 1i 2.5i
+Ctrl	Mod1	Button1
+Shift	Mod2	Button2
+Lock	Mod3	Button3
+	Mod4	Button4
+	Mod5	Button5
+.De
+.LP
+The canonical event types are
+.IP
+.TS
+l l.
+T{
+.PN KeyPress
+T}	T{
+.PN KeyRelease
+T}
+T{
+.PN ButtonPress
+T}	T{
+.PN ButtonRelease
+T}
+T{
+.PN MotionNotify
+T}	T{
+.PN EnterNotify
+T}
+T{
+.PN LeaveNotify
+T}	T{
+.PN FocusIn
+T}
+T{
+.PN FocusOut
+T}	T{
+.PN KeymapNotify
+T}
+T{
+.PN Expose
+T}	T{
+.PN GraphicsExpose,
+T}
+T{
+.PN NoExpose
+T}	T{
+.PN VisibilityNotify
+T}
+T{
+.PN CreateNotify
+T}	T{
+.PN DestroyNotify
+T}
+T{
+.PN UnmapNotify
+T}	T{
+.PN MapNotify
+T}
+T{
+.PN MapRequest
+T}	T{
+.PN ReparentNotify
+T}
+T{
+.PN ConfigureNotify
+T}	T{
+.PN ConfigureRequest
+T}
+T{
+.PN GravityNotify
+T}	T{
+.PN ResizeRequest
+T}
+T{
+.PN CirculateNotify
+T}	T{
+.PN CirculateRequest
+T}
+T{
+.PN PropertyNotify
+T}	T{
+.PN SelectionClear
+T}
+T{
+.PN SelectionRequest
+T}	T{
+.PN SelectionNotify
+T}
+T{
+.PN ColormapNotify
+T}	T{
+.PN ClientMessage
+T}
+.TE
+.LP
+
+.SH
+Examples
+.LP
+.IP \(bu 5
+Always put more specific events in the table before more general ones:
+.LP
+.Ds
+Shift <Btn1Down> : twas()\\n\\
+<Btn1Down> : brillig()
+.De
+.LP
+.IP \(bu 5
+For double-click on Button1 Up with Shift, use this specification:
+.IP
+.Ds
+Shift<Btn1Up>(2) : and()
+.DE
+.IP
+This is equivalent to the following line with appropriate timers set 
+between events:
+.IP
+.Ds
+Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down>,Shift<Btn1Up> : and()
+.De
+.IP \(bu 5
+For double-click on Button1 Down with Shift, use this specification:
+.IP
+.Ds
+Shift<Btn1Down>(2) : the()
+.De
+.IP
+This is equivalent to the following line with appropriate timers set
+between events:
+.IP
+.Ds
+Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down> : the()
+.De
+.IP \(bu 5
+Mouse motion is always discarded when it occurs between events in a table
+where no motion event is specified:
+.IP
+.Ds
+<Btn1Down>,<Btn1Up> : slithy()
+.De
+.IP
+This is taken, even if the pointer moves a bit between the down and
+up events.
+Similarly, any motion event specified in a translation matches any number
+of motion events.
+If the motion event causes an action procedure to be invoked,
+the procedure is invoked after each motion event.
+.IP \(bu 5
+If an event sequence consists of a sequence of events that is also a
+noninitial subsequence of another translation,
+it is not taken if it occurs in the context of the longer sequence.
+This occurs mostly in sequences like the following:
+.IP
+.Ds
+<Btn1Down>,<Btn1Up> : toves()\\n\\
+<Btn1Up> :  did()
+.De
+.IP
+The second translation is taken only if the button release is not
+preceded by a button press or if there are intervening events between the
+press and the release.
+Be particularly aware of this when using the repeat notation, above,
+with buttons and keys,
+because their expansion includes additional events;
+and when specifying motion events, because they are implicitly included
+between any two other events.
+In particular,
+pointer motion and double-click translations cannot coexist in the same
+translation table.
+.IP \(bu 5
+For single click on Button1 Up with Shift and Meta, use this specification:
+.IP
+.Ds
+Shift Meta <Btn1Down>, Shift Meta<Btn1Up>: gyre()
+.De
+.IP \(bu 5
+For multiple clicks greater or equal to a minimum number,
+a plus sign (+) may be appended to the final (rightmost)
+count in an event sequence.  The actions will be invoked
+on the \fIcount\fP-th click and each subsequent one arriving
+within the multi-click time interval.  For example:
+.IP
+.Ds
+Shift <Btn1Up>(2+) : and()
+.De
+.IP \(bu 5
+To indicate 
+.PN EnterNotify
+with any modifiers, use this specification:
+.IP
+.Ds
+<Enter> : gimble()
+.De
+.IP \(bu 5
+To indicate 
+.PN EnterNotify
+with no modifiers, use this specification:
+.IP
+.Ds
+None <Enter> : in()
+.De
+.IP \(bu 5
+To indicate 
+.PN EnterNotify 
+with Button1 Down and Button2 Up and ``don't care'' about
+the other modifiers, use this specification:
+.IP
+.Ds
+Button1 ~Button2 <Enter> : the()
+.De
+.IP \(bu 5
+To indicate 
+.PN EnterNotify
+with Button1 down and Button2 down exclusively, use this specification:
+.IP
+.Ds
+! Button1 Button2 <Enter> : wabe()
+.De
+.IP
+You do not need to use a tilde (~) with an exclamation point (!).
diff --git a/libXt/specs/appC b/libXt/specs/appC
new file mode 100644
index 000000000..6f31fd7d5
--- /dev/null
+++ b/libXt/specs/appC
@@ -0,0 +1,1204 @@
+.\" $Xorg: appC,v 1.3 2000/08/17 19:42:48 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix C\fP\s-1
+
+\s+1\fBCompatibility Functions\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix C \(em Compatibility Functions\fP
+.XE
+.FS
+This appendix is part of the formal Intrinsics Specification.
+.FE
+.LP
+In prototype versions of the \*(tk
+each widget class
+implemented an Xt<\^\fIWidget\fP\^>Create (for example,
+.PN XtLabelCreate )
+function, in which most of the code was identical from widget to widget.
+In the \*(xI, a single generic
+.PN XtCreateWidget
+performs most of the common work and then calls the initialize procedure
+implemented for the particular widget class.
+.LP
+Each Composite class also implemented the procedures
+Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example,
+.PN XtButtonBoxAddButton
+and
+.PN XtButtonBoxDeleteButton ).
+In the \*(xI, the Composite generic procedures
+.PN XtManageChildren
+and
+.PN XtUnmanageChildren
+perform error checking and screening out of certain children.
+Then they call the change_managed procedure
+implemented for the widget's Composite class.
+If the widget's parent has not yet been realized,
+the call to the change_managed procedure is delayed until realization time.
+.LP
+Old-style calls can be implemented in the \*(tk by defining
+one-line procedures or macros that invoke a generic routine.  For example,
+you could define the macro
+.PN XtLabelCreate
+as:
+.IP
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+#define XtLabelCreate(\fIname\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP) \\
+        ((LabelWidget) XtCreateWidget(\fIname\fP, \fIlabelWidgetClass\fP,   \
+\fIparent\fP, \fIargs\fP, \fInum_args\fP))
+.De
+.sp
+.LP
+Pop-up shells in some of the prototypes automatically performed an
+.PN XtManageChild
+on their child within their insert_child procedure.
+.IN "insert_child procedure"
+Creators of pop-up children need to call
+.PN XtManageChild
+themselves.
+.sp
+.LP
+.PN XtAppInitialize
+and 
+.PN XtVaAppInitialize 
+have been replaced by 
+.PN XtOpenApplication
+and
+.PN XtVaOpenApplication .
+.LP
+To initialize the \*(xI internals, create an application context,
+open and initialize a display, and create the initial application shell
+instance, an application may use
+.PN XtAppInitialize
+or
+.PN XtVaAppInitialize .
+.LP
+.IN "XtAppInitialize" "" "@DEF@"
+.sM
+.FD 0
+Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                       \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      XtAppContext *\fIapp_context_return\fP;
+.br
+      String \fIapplication_class\fP;
+.br
+      XrmOptionDescList \fIoptions\fP;
+.br
+      Cardinal \fInum_options\fP;
+.br
+      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_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 \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 XtAppInitialize
+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 \fIapplication_name\fP NULL, \fIwidget_class\fP
+.PN application\%Shell\%Widget\%Class ,
+and the specified \fIargs\fP and \fInum_args\fP
+and returns the created shell.  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 XtAppInitialize
+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 "XtVaAppInitialize" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                         \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, ...)
+.br
+    XtAppContext *\fIapp_context_return\fP;
+.br
+    String \fIapplication_class\fP;
+.br
+    XrmOptionDescList \fIoptions\fP;
+.br
+    Cardinal \fInum_options\fP;
+.br
+    int *\fIargc_in_out\fP;
+.br
+    String *\fIargv_in_out\fP;
+.br
+    String *\fIfallback_resources\fP;
+.FN
+.IP \fIapp_context_return\fP 1.5i
+Returns the application context, if non-NULL.
+.IP \fIapplication_class\fP 1.5i
+Specifies the class name of the application.
+.IP \fIoptions\fP 1.5i
+Specifies the command line options table.
+.IP \fInum_options\fP 1.5i
+Specifies the number of entries in \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 ... 1.5i
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+.LP
+.eM
+The
+.PN XtVaAppInitialize
+procedure is identical in function to
+.PN XtAppInitialize
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+.sp
+.LP
+As a convenience to people converting from earlier versions of the toolkit
+without application contexts, the following routines exist:
+.PN XtInitialize ,
+.PN XtMainLoop ,
+.PN XtNextEvent ,
+.PN XtProcessEvent ,
+.PN XtPeekEvent ,
+.PN XtPending ,
+.PN XtAddInput ,
+.PN XtAddTimeOut ,
+.PN XtAddWorkProc ,
+.PN XtCreateApplicationShell ,
+.PN XtAddActions ,
+.PN XtSetSelectionTimeout ,
+and
+.PN XtGetSelectionTimeout .
+.LP
+.IN "XtInitialize" "" "@DEF@"
+.sM
+.FD 0
+Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \
+\fInum_options\fP, \fIargc\fP, \fIargv\fP)
+.br
+      String \fIshell_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 \fIshell_name\fP 1i
+This parameter is ignored; therefore, you can specify NULL.
+.IP \fIapplication_class\fP 1i
+Specifies the class name of this application.
+.IP \fIoptions\fP 1i
+Specifies how to parse the command line for any application-specific resources.
+The \fIoptions\fP argument is passed as a parameter to 
+.PN XrmParseCommand .
+.IP \fInum_options\fP 1i
+Specifies the number of entries in the options list.
+.IP \fIargc\fP 1i
+Specifies a pointer to the number of command line parameters.
+.IP \fIargv\fP 1i
+Specifies the command line parameters.
+.LP
+.eM
+.PN XtInitialize
+calls
+.PN XtToolkitInitialize
+to initialize the toolkit internals,
+creates a default application context for use by the other convenience
+routines, calls
+.PN XtOpenDisplay
+with \fIdisplay_string\fP NULL and \fIapplication_name\fP NULL, and
+finally calls
+.PN XtAppCreateShell
+with \fIapplication_name\fP NULL and
+returns the created shell.
+The semantics of calling
+.PN XtInitialize
+more than once are undefined.
+This routine has been replaced by
+.PN XtOpenApplication .
+.sp
+.IN "XtMainLoop" "" "@DEF@"
+.sM
+.FD 0
+void XtMainLoop(void)
+.FN
+.LP
+.eM
+.PN XtMainLoop
+first reads the next alternate input, timer, or X event by calling
+.PN XtNextEvent .
+Then it dispatches this to the appropriate registered procedure by calling
+.PN XtDispatchEvent .
+This routine has been replaced by
+.PN XtAppMainLoop .
+.sp
+.IN "XtNextEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtNextEvent(\fIevent_return\fP)
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If no input is on the X input queue for the default application context, 
+.PN XtNextEvent 
+flushes the X output buffer 
+and waits for an event while looking at the alternate input sources 
+and timeout values and calling any callback procedures triggered by them.
+This routine has been replaced by
+.PN XtAppNextEvent .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtProcessEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtProcessEvent(\fImask\fP)
+.br
+      XtInputMask \fImask\fP;
+.FN
+.IP \fImask\fP 1i
+Specifies the type of input to process.
+.LP
+.eM
+.PN XtProcessEvent
+processes one X event, timeout, or alternate input source 
+(depending on the value of \fImask\fP), blocking if necessary.
+It has been replaced by
+.PN XtAppProcessEvent .
+.PN XtInitialize
+must be called before using this function.
+.sp
+.IN "XtPeekEvent" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtPeekEvent(\fIevent_return\fP)
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If there is an event in the queue for the default application context, 
+.PN XtPeekEvent
+fills in the event and returns a nonzero value.
+If no X input is on the queue, 
+.PN XtPeekEvent
+flushes the output buffer and blocks until input is available, possibly
+calling some timeout callbacks in the process.
+If the input is an event,
+.PN XtPeekEvent
+fills in the event and returns a nonzero value. 
+Otherwise, the input is for an alternate input source, and
+.PN XtPeekEvent
+returns zero. 
+This routine has been replaced by
+.PN XtAppPeekEvent .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtPending" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtPending()
+.FN
+.LP
+.eM
+.PN XtPending
+returns a nonzero value if there are 
+events pending from the X server or alternate input sources in the default
+application context.
+If there are no events pending, 
+it flushes the output buffer and returns a zero value.
+It has been replaced by
+.PN XtAppPending .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtAddInput" "" "@DEF@"
+.sM
+.FD 0
+XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \
+\fIclient_data\fP)
+.br
+      int \fIsource\fP;
+.br
+      XtPointer \fIcondition\fP;
+.br
+      XtInputCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIsource\fP 1i
+Specifies the source file descriptor on a POSIX-based system 
+or other operating-system-dependent device specification.
+.IP \fIcondition\fP 1i
+Specifies the mask that indicates either a read, write, or exception condition
+or some operating-system-dependent condition.
+.IP \fIproc\fP 1i
+Specifies the procedure called when input is available.
+.IP \fIclient_data\fP 1i
+Specifies the parameter to be passed to \fIproc\fP when input is available.
+.LP
+.eM
+The 
+.PN XtAddInput
+function registers in the default application context a new 
+source of events, 
+which is usually file input but can also be file output.
+(The word \fIfile\fP should be loosely interpreted to mean any sink 
+or source of data.)
+.PN XtAddInput
+also specifies the conditions under which the source can generate events.
+When input is pending on this source in the default application context, 
+the callback procedure is called.
+This routine has been replaced by
+.PN XtAppAddInput .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtAddTimeOut" "" "@DEF@"
+.sM
+.FD 0
+XtIntervalId XtAddTimeOut(\fIinterval\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      unsigned long \fIinterval\fP;
+.br
+      XtTimerCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIinterval\fP 1i
+Specifies the time interval in milliseconds.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when time expires.
+.IP \fIclient_data\fP 1i
+Specifies the parameter to be passed to \fIproc\fP when it is called.
+.LP
+.eM
+The 
+.PN XtAddTimeOut
+function creates a timeout in the default application context
+and returns an identifier for it.
+The timeout value is set to \fIinterval\fP.
+The callback procedure will be called after
+the time interval elapses, after which the timeout is removed.
+This routine has been replaced by 
+.PN XtAppAddTimeOut .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtAddWorkProc" "" "@DEF@"
+.sM
+.FD 0
+XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclient_data\fP)
+.br
+      XtWorkProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIproc\fP 1i
+Procedure to call to do the work.
+.IP \fIclient_data\fP 1i
+Client data to pass to \fIproc\fP when it is called.
+.LP
+.eM
+This routine registers a work procedure in the default application context. It has
+been replaced by
+.PN XtAppAddWorkProc .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtCreateApplicationShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \
+\fInum_args\fP)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIname\fP 1i
+This parameter is ignored; therefore, you can specify NULL.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created application shell widget.
+This will usually be 
+.PN topLevelShellWidgetClass 
+or a subclass thereof.
+.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 \fIargs\fP.
+.LP
+.eM
+The procedure
+.PN XtCreateApplicationShell
+calls
+.PN XtAppCreateShell
+with \fIapplication_name\fP NULL, the application class passed to
+.PN XtInitialize ,
+and the default application context created by
+.PN XtInitialize .
+This routine has been replaced by
+.PN XtAppCreateShell .
+.sp
+.LP
+An old-format resource type converter procedure pointer is of type
+.PN XtConverter .
+.LP
+.IN "XtConverter" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtConverter)(XrmValue*, Cardinal*, XrmValue*, XrmValue*);
+.br
+      XrmValue *\fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.br
+      XrmValue *\fIfrom\fP;
+.br
+      XrmValue *\fIto\fP;
+.FN
+.IP \fIargs\fP 1i
+Specifies a list of additional
+.PN XrmValue
+arguments to the converter if additional context is needed
+to perform the conversion, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.IP \fIfrom\fP 1i
+Specifies the value to convert.
+.IP \fIto\fP 1i
+Specifies the descriptor to use to return the converted value.
+.LP
+.eM
+Type converters should perform the following actions:
+.IP \(bu 5
+Check to see that the number of arguments passed is correct.
+.IP \(bu 5
+Attempt the type conversion.
+.IP \(bu 5
+If successful, return the size and pointer to the data in the \fIto\fP argument;
+otherwise, call
+.PN XtWarningMsg
+and return without modifying the \fIto\fP argument.
+.LP
+Most type converters just take the data described by the specified \fIfrom\fP
+argument and return data by writing into the specified \fIto\fP argument.
+A few need other information, which is available in the specified 
+argument list.
+A type converter can invoke another type converter,
+which allows differing sources that may convert into a common intermediate
+result to make maximum use of the type converter cache.
+.LP
+Note that the address returned in \fIto->addr\fP cannot be that of a local variable of 
+the converter because this is not valid after the converter returns.
+It should be a pointer to a static variable.
+.LP
+The procedure type
+.PN XtConverter
+has been replaced by
+.PN XtTypeConverter .
+.sp
+.LP
+The
+.PN XtStringConversionWarning
+.IN "XtStringConversionWarning" "" "@DEF@"
+function is a convenience routine for old-format resource converters
+that convert from strings.
+.LP
+.sM
+.FD 0
+void XtStringConversionWarning(\fIsrc\fP, \fIdst_type\fP)
+.br
+      String \fIsrc\fP, \fIdst_type\fP;
+.FN
+.IP \fIsrc\fP 1i
+Specifies the string that could not be converted.
+.IP \fIdst_type\fP 1i
+Specifies the name of the type to which the string could not be converted.
+.LP
+.eM
+The
+.PN XtStringConversionWarning
+function issues a warning message with name ``conversionError'',
+type ``string'', class ``XtToolkitError, and the default message string
+``Cannot convert "\fIsrc\fP" to type \fIdst_type\fP''.  This routine
+has been superseded by
+.PN XtDisplayStringConversionWarning .
+.sp
+.LP
+To register an old-format converter, use
+.PN XtAddConverter
+.IN "XtAddConverter" "" "@DEF@"
+or
+.PN XtAppAddConverter .
+.IN "XtAppAddConverter" "" "@DEF@"
+.LP
+.sM
+.FD 0
+void XtAddConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
+\fIconvert_args\fP, \fInum_args\fP)
+.br
+      String \fIfrom_type\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XtConverter \fIconverter\fP;
+.br
+      XtConvertArgList \fIconvert_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIconverter\fP 1i
+Specifies the type converter procedure.
+.IP \fIconvert_args\fP 1i
+Specifies how to compute the additional arguments to the converter, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIconvert_args\fP.
+.sp
+.LP
+.eM
+.PN XtAddConverter
+is equivalent in function to
+.PN XtSetTypeConverter
+with \fIcache_type\fP equal to
+.PN XtCacheAll
+for old-format type converters.  It has been superseded by
+.PN XtSetTypeConverter .
+.sp
+.sM
+.FD 0
+void XtAppAddConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
+\fIconverter\fP, \fIconvert_args\fP, \fInum_args\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIfrom_type\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XtConverter \fIconverter\fP;
+.br
+      XtConvertArgList \fIconvert_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIconverter\fP 1i
+Specifies the type converter procedure.
+.IP \fIconvert_args\fP 1i
+Specifies how to compute the additional arguments to the converter, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIconvert_args\fP.
+.LP
+.eM
+.PN XtAppAddConverter
+is equivalent in function to
+.PN XtAppSetTypeConverter
+with \fIcache_type\fP equal to
+.PN XtCacheAll
+for old-format type converters.  It has been superseded by
+.PN XtAppSetTypeConverter .
+.sp
+.LP
+To invoke resource conversions, a client may use
+.PN XtConvert
+or, for old-format converters only,
+.PN XtDirectConvert .
+.LP
+.IN "XtConvert" "" "@DEF@"
+.sM
+.FD 0
+void XtConvert(\fIw\fP, \fIfrom_type\fP, \fIfrom\fP, \fIto_type\fP, \
+\fIto_return\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIfrom_type\fP;
+.br
+      XrmValuePtr \fIfrom\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XrmValuePtr \fIto_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget to use for additional arguments, if any are
+needed.
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIfrom\fP 1i
+Specifies the value to be converted.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIto_return\fP 1i
+Returns the converted value.
+.LP
+.IN "XtDirectConvert" "" "@DEF@"
+.FD 0
+void XtDirectConvert(\fIconverter\fP, \fIargs\fP, \fInum_args\fP, \fIfrom\fP, \
+\fIto_return\fP)
+.br
+      XtConverter \fIconverter\fP;
+.br
+      XrmValuePtr \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.br
+      XrmValuePtr \fIfrom\fP;
+.br
+      XrmValuePtr \fIto_return\fP;
+.FN
+.IP \fIconverter\fP 1i
+Specifies the conversion procedure to be called.
+.IP \fIargs\fP 1i
+Specifies the argument list that contains the additional arguments
+needed to perform the conversion (often NULL).
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.IP \fIfrom\fP 1i
+Specifies the value to be converted.
+.IP \fIto_return\fP 1i
+Returns the converted value.
+.LP
+.eM
+The
+.PN XtConvert
+function looks up the type converter registered to convert \fIfrom_type\fP 
+to \fIto_type\fP, computes any additional arguments needed, and then calls
+.PN XtDirectConvert
+or
+.PN XtCallConverter .
+The
+.PN XtDirectConvert
+function looks in the converter cache to see if this conversion procedure
+has been called with the specified arguments.
+If so, it returns a descriptor for information stored in the cache;
+otherwise, it calls the converter and enters the result in the cache.
+.LP
+Before calling the specified converter,
+.PN XtDirectConvert
+sets the return value size to zero and the return value address to NULL.
+To determine if the conversion was successful,
+the client should check \fIto_return.addr\fP for non-NULL.
+The data returned by
+.PN XtConvert
+must be copied immediately by the caller,
+as it may point to static data in the type converter.
+.LP
+.PN XtConvert
+has been replaced by
+.PN XtConvertAndStore ,
+and
+.PN XtDirectConvert
+has been superseded by
+.PN XtCallConverter .
+.sp
+.LP
+To deallocate a shared GC when it is no longer needed, use
+.PN XtDestroyGC .
+.LP
+.IN "XtDestroyGC" "" "@DEF@"
+.sM
+.FD 0
+void XtDestroyGC(\fIw\fP, \fIgc\fP)
+.br
+      Widget \fIw\fP;
+.br
+      GC \fIgc\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies any object on the display for which the shared GC was
+created.  \*(oI
+.IP \fIgc\fP 1i
+Specifies the shared GC to be deallocated.
+.LP
+.eM
+References to sharable GCs are counted and a free request is generated to the
+server when the last user of a given GC destroys it.
+Note that some earlier versions of
+.PN XtDestroyGC
+had only a \fIgc\fP argument.
+Therefore, this function is not very portable,
+and you are encouraged to use
+.PN XtReleaseGC
+instead.
+.sp
+.LP
+To declare an action table in the default application context
+and register it with the translation manager, use
+.PN XtAddActions .
+.LP
+.IN "XtAddActions" "" "@DEF@"
+.sM
+.FD 0
+void XtAddActions(\fIactions\fP, \fInum_actions\fP)
+.br
+      XtActionList \fIactions\fP;
+.br
+      Cardinal \fInum_actions\fP;
+.FN
+.IP \fIactions\fP 1i
+Specifies the action table to register.
+.IP \fInum_actions\fP 1i
+Specifies the number of entries in \fIactions\fP.
+.LP
+.eM
+If more than one action is registered with the same name, 
+the most recently registered action is used.
+If duplicate actions exist in an action table,
+the first is used.
+The \*(xI register an action table for
+.PN XtMenuPopup
+and
+.PN XtMenuPopdown
+as part of \*(tk initialization.
+This routine has been replaced by
+.PN XtAppAddActions .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.LP
+To set the \*(xI selection timeout in the default application context, use
+.PN XtSetSelectionTimeout .
+.LP
+.IN "XtSetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSelectionTimeout(\fItimeout\fP)
+.br
+      unsigned long \fItimeout\fP;
+.FN
+.IP \fItimeout\fP 1i
+Specifies the selection timeout in milliseconds.
+This routine has been replaced by
+.PN XtAppSetSelectionTimeout .
+.PN XtInitialize
+must be called before using this routine.
+.LP
+.eM
+.sp
+.LP
+To get the current selection timeout value in the default application
+context, use
+.PN XtGetSelectionTimeout .
+.LP
+.IN "XtGetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+unsigned long XtGetSelectionTimeout()
+.FN
+.LP
+.eM
+The selection timeout is the time within which the two communicating 
+applications must respond to one another.
+If one of them does not respond within this interval,
+the \*(xI abort the selection request.
+.LP
+This routine has been replaced by
+.PN XtAppGetSelectionTimeout .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.LP
+To obtain the global error database (for example, to merge with
+an application- or widget-specific database), use
+.PN XtGetErrorDatabase .
+.LP
+.IN "XtGetErrorDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase *XtGetErrorDatabase()
+.FN
+.LP
+.eM
+The
+.PN XtGetErrorDatabase
+function returns the address of the error database.
+The \*(xI do a lazy binding of the error database and do not merge in the
+database file until the first call to
+.PN XtGetErrorDatbaseText .
+This routine has been replaced by
+.PN XtAppGetErrorDatabase .
+.sp
+.LP
+An error message handler can obtain the error database text for an
+error or a warning by calling
+.PN XtGetErrorDatabaseText .
+.LP
+.IN "XtGetErrorDatabaseText" "" "@DEF@"
+.sM
+.FD 0
+void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \
+\fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP)
+.br
+      String \fIname\fP, \fItype\fP, \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String \fIbuffer_return\fP;
+.br
+      int \fInbytes\fP;
+.FN
+.IP \fIname\fP 1i
+.br
+.ns
+.IP \fItype\fP 1i
+Specify the name and type that are concatenated to form the resource name 
+of the error message.
+.IP \fIclass\fP 1i
+Specifies the resource class of the error message.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIbuffer_return\fP 1i
+Specifies the buffer into which the error message is to be returned.
+.IP \fInbytes\fP 1i
+Specifies the size of the buffer in bytes.
+.LP
+.eM
+The
+.PN XtGetErrorDatabaseText
+returns the appropriate message from the error database
+associated with the default application context
+or returns the specified default message if one is not found in the
+error database.
+To form the full resource name and class when querying the database,
+the \fIname\fP and \fItype\fP are concatenated with a single ``.''
+between them and the \fIclass\fP is concatenated with itself with a
+single ``.'' if it does not already contain a ``.''.
+This routine has been superseded by
+.PN XtAppGetErrorDatabaseText .
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtSetErrorMsgHandler .
+.LP
+.IN "XtSetErrorMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetErrorMsgHandler(\fImsg_handler\fP)
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fImsg_handler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+The default error handler provided by the \*(xI constructs a
+string from the error resource database and calls
+.PN XtError .
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(xI behavior is undefined.
+This routine has been superseded by
+.PN XtAppSetErrorMsgHandler .
+.sp
+.LP
+To call the high-level error handler, use
+.PN XtErrorMsg .
+.LP
+.IN "XtErrorMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtErrorMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
+\fIparams\fP, \fInum_params\fP)
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+This routine has been superseded by
+.PN XtAppErrorMsg .
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtSetWarningMsgHandler .
+.LP
+.IN "XtSetWarningMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetWarningMsgHandler(\fImsg_handler\fP)
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fImsg_handler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+The default warning handler provided by the \*(xI constructs a string
+from the error resource database and calls
+.PN XtWarning .
+This routine has been superseded by
+.PN XtAppSetWarningMsgHandler .
+.sp
+.LP
+To call the installed high-level warning handler, use
+.PN XtWarningMsg .
+.LP
+.IN "XtWarningMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtWarningMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
+\fIparams\fP, \fInum_params\fP)
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+This routine has been superseded by
+.PN XtAppWarningMsg .
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtSetErrorHandler .
+.LP
+.IN "XtSetErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetErrorHandler(\fIhandler\fP)
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIhandler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+The default error handler provided by the \*(xI is
+.PN _XtError .
+On POSIX-based systems,
+it prints the message to standard error and terminates the application.
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(tk behavior is undefined.
+This routine has been superseded by
+.PN XtAppSetErrorHandler .
+.sp
+.LP
+To call the installed fatal error procedure, use
+.PN XtError .
+.LP
+.IN "XtError" "" "@DEF@"
+.sM
+.FD 0
+void XtError(\fImessage\fP)
+.br
+      String \fImessage\fP;
+.FN
+.IP \fImessage\fP 1i
+Specifies the message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppErrorMsg ,
+not
+.PN XtError ,
+to provide for customization and internationalization of error
+messages.  This routine has been superseded by
+.PN XtAppError .
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtSetWarningHandler .
+.LP
+.IN "XtSetWarningHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetWarningHandler(\fIhandler\fP)
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIhandler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+The default warning handler provided by the \*(xI is
+.PN _XtWarning .
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+This routine has been superseded by
+.PN XtAppSetWarningHandler .
+.sp
+.LP
+To call the installed nonfatal error procedure, use
+.PN XtWarning .
+.LP
+.IN "XtWarning" "" "@DEF@"
+.sM
+.FD 0
+void XtWarning(\fImessage\fP)
+.br
+      String \fImessage\fP;
+.FN
+.IP \fImessage\fP 1i
+Specifies the nonfatal error message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppWarningMsg ,
+not
+.PN XtWarning ,
+to provide for customization and internationalization of warning messages.
+This routine has been superseded by
+.PN XtAppWarning .
diff --git a/libXt/specs/appD b/libXt/specs/appD
new file mode 100644
index 000000000..5322ff97b
--- /dev/null
+++ b/libXt/specs/appD
@@ -0,0 +1,602 @@
+.\" $Xorg: appD,v 1.3 2000/08/17 19:42:48 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix D\fP\s-1
+
+\s+1\fBIntrinsics Error Messages\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix D \(em Intrinsics Error Messages\fP
+.XE
+.LP
+All \*(xI errors and warnings have class
+``XtToolkitError''.
+The following two tables summarize the common errors and warnings that can be
+generated by the \*(xI.
+Additional implementation-dependent messages are permitted.
+.SH 
+Error Messages
+.LP
+.ps 9
+.nr PS 9
+.TS
+lw(1.3i) lw(1.4i) lw(2.9i).
+_
+.sp 6p
+Name	Type	Default Message
+.sp 6p
+_
+.sp 6p
+allocError	calloc	T{
+Cannot perform calloc
+T}
+allocError	malloc	T{
+Cannot perform malloc
+T}
+allocError	realloc	T{
+Cannot perform realloc
+T}
+internalError	xtMakeGeometryRequest	T{
+internal error; ShellClassExtension is NULL
+T}
+invalidArgCount	xtGetValues	T{
+Argument count > 0 on NULL argument list in XtGetValues
+T}
+invalidArgCount	xtSetValues	T{
+Argument count > 0 on NULL argument list in XtSetValues
+T}
+invalidClass	applicationShellInsertChild	T{
+ApplicationShell does not accept RectObj children; ignored
+T}
+invalidClass	constraintSetValue	T{
+Subclass of Constraint required in CallConstraintSetValues
+T}
+invalidClass	xtAppCreateShell	T{
+XtAppCreateShell requires non-NULL widget class
+T}
+invalidClass	xtCreatePopupShell	T{
+XtCreatePopupShell requires non-NULL widget class
+T}
+invalidClass	xtCreateWidget	T{
+XtCreateWidget requires non-NULL widget class
+T}
+invalidClass	xtPopdown	T{
+XtPopdown requires a subclass of shellWidgetClass
+T}
+invalidClass	xtPopup	T{
+XtPopup requires a subclass of shellWidgetClass
+T}
+invalidDimension	xtCreateWindow	T{
+Widget %s has zero width and/or height
+T}
+invalidDimension	shellRealize	T{
+Shell widget %s has zero width and/or height
+T}
+invalidDisplay	xtInitialize	T{
+Can't open display: %s
+T}
+invalidGetValues	xtGetValues	T{
+NULL ArgVal in XtGetValues
+T}
+invalidExtension	shellClassPartInitialize	T{
+widget class %s has invalid ShellClassExtension record
+T}
+invalidExtension	xtMakeGeometryRequest	T{
+widget class %s has invalid ShellClassExtension record
+T}
+invalidGeometryManager	xtMakeGeometryRequest	T{
+XtMakeGeometryRequest - parent has no geometry manager
+T}
+invalidParameter	xtAddInput	T{
+invalid condition passed to XtAddInput
+T}
+invalidParameter	xtAddInput	T{
+invalid condition passed to XtAppAddInput
+T}
+invalidParent	xtChangeManagedSet	T{
+Attempt to manage a child when parent is not Composite
+T}
+invalidParent	xtChangeManagedSet	T{
+Attempt to unmanage a child when parent is not Composite
+T}
+invalidParent	xtCreatePopupShell	T{
+XtCreatePopupShell requires non-NULL parent
+T}
+invalidParent	xtCreateWidget	T{
+XtCreateWidget requires non-NULL parent
+T}
+invalidParent	xtMakeGeometryRequest	T{
+non-shell has no parent in XtMakeGeometryRequest
+T}
+invalidParent	xtMakeGeometryRequest	T{
+XtMakeGeometryRequest - parent not composite
+T}
+invalidParent	xtManageChildren	T{
+Attempt to manage a child when parent is not Composite
+T}
+invalidParent	xtUnmanageChildren	T{
+Attempt to unmanage a child when parent is not Composite
+T}
+invalidProcedure	inheritanceProc	T{
+Unresolved inheritance operation
+T}
+invalidProcedure	realizeProc	T{
+No realize class procedure defined
+T}
+invalidWindow	eventHandler	T{
+Event with wrong window
+T}
+missingWidget	fetchDisplayArg	T{
+FetchDisplayArg called without a widget to reference
+T}
+nonWidget	xtCreateWidget	T{
+attempt to add non-widget child "%s" to parent "%s" which supports only widgets
+T}
+noPerDisplay	closeDisplay	T{
+Couldn't find per display information
+T}
+noPerDisplay	getPerDisplay	T{
+Couldn't find per display information
+T}
+noSelectionProperties	freeSelectionProperty	T{
+internal error: no selection property context for display
+T}
+noWidgetAncestor	windowedAncestor	T{
+Object "%s" does not have windowed ancestor
+T}
+nullDisplay	xtRegisterExtensionSelector	T{
+XtRegisterExtensionSelector requires a non-NULL display
+T}
+nullProc	insertChild	T{
+"%s" parent has NULL insert_child method
+T}
+r2versionMismatch	widget	T{
+Widget class %s must be re-compiled.
+T}
+R3versionMismatch	widget	T{
+Widget class %s must be re-compiled.
+T}
+R4orR5versionMismatch	widget	T{
+Widget class %s must be re-compiled.
+T}
+rangeError	xtRegisterExtensionSelector	T{
+Attempt to register multiple selectors for one extension event type
+T}
+sessionManagement	SmcOpenConnection	T{
+Tried to connect to session manager, %s
+T}
+subclassMismatch	xtCheckSubclass	T{
+Widget class %s found when subclass of %s expected: %s
+T}
+.sp 6p
+_
+.TE
+.ps 11
+.nr PS 11
+.SH
+Warning Messages
+.LP
+.ps 9
+.nr PS 9
+.TS
+lw(1.3i) lw(1.4i) lw(2.9i).
+_
+.sp 6p
+Name	Type	Default Message
+.sp 6p
+_
+.sp 6p
+ambiguousParent	xtChangeManagedSet	T{
+Not all children have same parent
+T}
+ambiguousParent	xtManageChildren	T{
+Not all children have same parent in XtManageChildren
+T}
+ambiguousParent	xtUnmanageChildren	T{
+Not all children have same parent in XtUnmanageChildren
+T}
+badFormat	xtGetSelectionValue	T{
+Selection owner returned type INCR property with format != 32
+T}
+badGeometry	shellRealize	T{
+Shell widget "%s" has an invalid geometry specification: "%s"
+T}
+badValue	cvtStringToPixel	T{
+Color name "%s" is not defined
+T}
+communicationError	select	T{
+Select failed; error code %s
+T}
+conversionError	string	T{
+Cannot convert string "%s" to type %s
+T}
+conversionError	stringToVisual	T{
+Cannot find Visual of class %s for display %s
+T}
+conversionFailed	xtConvertVarToArgList	T{
+Type conversion failed
+T}
+conversionFailed	xtGetTypedArg	T{
+Type conversion (%s to %s) failed for widget '%s'
+T}
+displayError	invalidDisplay	T{
+Can't find display structure
+T}
+grabError	xtAddGrab	T{
+XtAddGrab requires exclusive grab if spring_loaded is TRUE
+T}
+grabError	xtRemoveGrab	T{
+XtRemoveGrab asked to remove a widget not on the list
+T}
+.TE
+.TS
+lw(1.3i) lw(1.4i) lw(2.9i).
+initializationError	xtInitialize	T{
+Initializing Resource Lists twice
+T}
+insufficientSpace	xtGetTypedArg	T{
+Insufficient space for converted type '%s' in widget '%s'
+T}
+internalError	shell	T{
+Shell's window manager interaction is broken
+T}
+invalidAddressMode	computeArgs	T{
+Conversion arguments for widget '%s' contain an unsupported address mode
+T}
+invalidArgCount	getResources	T{
+argument count > 0 on NULL argument list
+T}
+invalidCallbackList	xtAddCallback	T{
+Cannot find callback list in XtAddCallback
+T}
+invalidCallbackList	xtAddCallback	T{
+Cannot find callback list in XtAddCallbacks
+T}
+invalidCallbackList	xtCallCallback	T{
+Cannot find callback list in XtCallCallbacks
+T}
+invalidCallbackList	xtRemoveAllCallback	T{
+Cannot find callback list in XtRemoveAllCallbacks
+T}
+invalidCallbackList	xtRemoveCallback	T{
+Cannot find callback list in XtRemoveCallbacks
+T}
+invalidChild	xtChangeManagedSet	T{
+Null child passed to UnmanageChildren
+T}
+invalidChild	xtManageChildren	T{
+null child passed to ManageChildren
+T}
+invalidChild	xtManageChildren	T{
+null child passed to XtManageChildren
+T}
+invalidChild	xtUnmanageChildren	T{
+Null child passed to XtUnmanageChildren
+T}
+invalidChild	xtUnmanageChildren	T{
+Null child found in argument list to unmanage
+T}
+invalidDepth	setValues	T{
+Can't change widget depth
+T}
+invalidExtension	xtCreateWidget	T{
+widget "%s" class %s has invalid CompositeClassExtension record
+T}
+invalidExtension	xtCreateWidget	T{
+widget class %s has invalid ConstraintClassExtension record
+T}
+invalidGrab	ungrabKeyOrButton	T{
+Attempt to remove nonexistent passive grab
+T}
+invalidGrabKind	xtPopup	T{
+grab kind argument has invalid value; XtGrabNone assumed
+T}
+invalidParameters	freeTranslations	T{
+Freeing XtTranslations requires no extra arguments
+T}
+invalidParameters	mergeTranslations	T{
+MergeTM to TranslationTable needs no extra arguments
+T}
+invalidParameters	xtMenuPopdown	T{
+XtMenuPopdown called with num_params != 0 or 1
+T}
+invalidParameters	xtMenuPopupAction	T{
+MenuPopup wants exactly one argument
+T}
+invalidParent	xtCopyFromParent	T{
+CopyFromParent must have non-NULL parent
+T}
+invalidPopup	xtMenuPopup	T{
+Can't find popup widget "%s" in XtMenuPopup
+T}
+invalidPopup	xtMenuPopdown	T{
+Can't find popup in widget "%s" in XtMenuPopdown
+T}
+invalidPopup	unsupportedOperation	T{
+Pop-up menu creation is only supported on ButtonPress, KeyPress or EnterNotify events.
+T}
+invalidPopup	unsupportedOperation	T{
+Pop-up menu creation is only supported on Button, Key or EnterNotify events.
+T}
+invalidProcedure	deleteChild	T{
+null delete_child procedure for class %s in XtDestroy
+T}
+invalidProcedure	inputHandler	T{
+XtRemoveInput: Input handler not found
+T}
+invalidProcedure	set_values_almost	T{
+set_values_almost procedure shouldn't be NULL
+T}
+invalidResourceCount	getResources	T{
+resource count > 0 on NULL resource list
+T}
+invalidResourceName	computeArgs	T{
+Cannot find resource name %s as argument to conversion
+T}
+invalidShell	xtTranslateCoords	T{
+Widget has no shell ancestor
+T}
+invalidSizeOverride	xtDependencies	T{
+Representation size %d must match superclass's to override %s
+T}
+missingCharsetList	cvtStringToFontSet	T{
+Missing charsets in String to FontSet conversion
+T}
+noActionProc	xtCallActionProc	T{
+No action proc named "%s" is registered for widget "%s"
+T}
+noColormap	cvtStringToPixel	T{
+Cannot allocate colormap entry for "%s"
+T}
+noFont	cvtStringToFont	T{
+Unable to load any usable ISO8859-1 font
+T}
+noFont	cvtStringToFontSet	T{
+Unable to load any usable fontset
+T}
+noFont	cvtStringToFontStruct	T{
+Unable to load any usable ISO8859-1 font
+T}
+.TE
+.TS
+lw(1.3i) lw(1.4i) lw(2.9i).
+notInConvertSelection	xtGetSelectionRequest	T{
+XtGetSelectionRequest or XtGetSelectionParameters called for widget "%s" outside of ConvertSelection proc
+T}
+notRectObj	xtChangeManagedSet	T{
+child "%s", class %s is not a RectObj
+T}
+notRectObj	xtManageChildren	T{
+child "%s", class %s is not a RectObj
+T}
+nullWidget	xtConvertVarToArgList	T{
+XtVaTypedArg conversion needs non-NULL widget handle
+T}
+r3versionMismatch	widget	T{
+Shell Widget class %s binary compiled for R3
+T}
+translationError	nullTable	T{
+Can't remove accelerators from NULL table
+T}
+translationError	nullTable	T{
+Tried to remove nonexistent accelerators
+T}
+translationError	ambiguousActions	T{
+Overriding earlier translation manager actions.
+T}
+translationError	newActions	T{
+New actions are:%s
+T}
+translationError	nullTable	T{
+table to (un)merge must not be null
+T}
+translationError	nullTable	T{
+Can't translate event through NULL table
+T}
+translationError	oldActions	T{
+Previous entry was: %s %s
+T}
+translationError	unboundActions	T{
+Actions not found: %s
+T}
+translationError	xtTranslateInitialize	T{
+Initializing Translation manager twice.
+T}
+translationParseError	missingComma	T{
+ ... possibly due to missing ',' in event sequence.
+T}
+translationParseError	nonLatin1	T{
+ ... probably due to non-Latin1 character in quoted string
+T}
+translationParseError	parseError	T{
+translation table syntax error: %s
+T}
+translationParseError	parseString	T{
+Missing '"'.
+T}
+translationParseError	showLine	T{
+ ... found while parsing '%s'
+T}
+typeConversionError	noConverter	T{
+No type converter registered for '%s' to '%s' conversion.
+T}
+unknownType	xtConvertVarToArgList	T{
+Unable to find type of resource for conversion
+T}
+unknownType	xtGetTypedArg	T{
+Unable to find type of resource for conversion
+T}
+versionMismatch	widget	T{
+Widget class %s version mismatch (recompilation needed):\\n widget %d vs. intrinsics %d.
+T}
+wrongParameters	cvtIntOrPixelToXColor	T{
+Pixel to color conversion needs screen and colormap arguments
+T}
+wrongParameters	cvtIntToBool	T{
+Integer to Bool conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToBoolean	T{
+Integer to Boolean conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToFloat	T{
+Integer to Float conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToFont	T{
+Integer to Font conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToPixel	T{
+Integer to Pixel conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToPixmap	T{
+Integer to Pixmap conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToShort	T{
+Integer to Short conversion needs no extra arguments
+T}
+wrongParameters	cvtIntToUnsignedChar	T{
+Integer to UnsignedChar conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToAcceleratorTable	T{
+String to AcceleratorTable conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToAtom	T{
+String to Atom conversion needs Display argument
+T}
+wrongParameters	cvtStringToBool	T{
+String to Bool conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToBoolean	T{
+String to Boolean conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToCommandArgArray	T{
+String to CommandArgArray conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToCursor	T{
+String to cursor conversion needs display argument
+T}
+wrongParameters	cvtStringToDimension	T{
+String to Dimension conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToDirectoryString	T{
+String to DirectoryString conversion needs no extra arguments
+T}
+.TE
+.TS
+lw(1.3i) lw(1.4i) lw(2.9i).
+wrongParameters	cvtStringToDisplay	T{
+String to Display conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToFile	T{
+String to File conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToFloat	T{
+String to Float conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToFont	T{
+String to font conversion needs display argument
+T}
+wrongParameters	cvtStringToFontSet	T{
+String to FontSet conversion needs display and locale arguments
+T}
+wrongParameters	cvtStringToFontStruct	T{
+String to font conversion needs display argument
+T}
+wrongParameters	cvtStringToGravity	T{
+String to Gravity conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToInitialState	T{
+String to InitialState conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToInt	T{
+String to Integer conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToPixel	T{
+String to pixel conversion needs screen and colormap arguments
+T}
+wrongParameters	cvtStringToRestartStyle	T{
+String to RestartStyle conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToShort	T{
+String to Integer conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToTranslationTable	T{
+String to TranslationTable conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToUnsignedChar	T{
+String to Integer conversion needs no extra arguments
+T}
+wrongParameters	cvtStringToVisual	T{
+String to Visual conversion needs screen and depth arguments
+T}
+wrongParameters	cvtXColorToPixel	T{
+Color to Pixel conversion needs no extra arguments
+T}
+wrongParameters	freeCursor	T{
+Free Cursor requires display argument
+T}
+wrongParameters	freeDirectoryString	T{
+Free Directory String requires no extra arguments
+T}
+wrongParameters	freeFile	T{
+Free File requires no extra arguments
+T}
+wrongParameters	freeFont	T{
+Free Font needs display argument
+T}
+wrongParameters	freeFontSet	T{
+FreeFontSet needs display and locale arguments
+T}
+wrongParameters	freeFontStruct	T{
+Free FontStruct requires display argument
+T}
+wrongParameters	freePixel	T{
+Freeing a pixel requires screen and colormap arguments
+T}
+.sp 6p
+_
+.TE
+.ps 11
+.nr PS 11
diff --git a/libXt/specs/appE b/libXt/specs/appE
new file mode 100644
index 000000000..1ce7270bf
--- /dev/null
+++ b/libXt/specs/appE
@@ -0,0 +1,606 @@
+.\" $Xorg: appE,v 1.3 2000/08/17 19:42:48 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix E\fP\s-1
+
+\s+1\fB\fBDefined Strings\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix E \(em Defined Strings\fP
+.XE
+.LP
+The 
+.PN StringDefs.h
+header file contains definitions for the following resource name,
+class, and representation type symbolic constants.
+.IN "String Constants" "resource names"
+.LP
+Resource names:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtNaccelerators	"accelerators"
+XtNallowHoriz	"allowHoriz"
+XtNallowVert	"allowVert"
+XtNancestorSensitive	"ancestorSensitive"
+XtNbackground	"background"
+XtNbackgroundPixmap	"backgroundPixmap"
+XtNbitmap	"bitmap"
+XtNborder	"borderColor"
+XtNborderColor	"borderColor"
+XtNborderPixmap	"borderPixmap"
+XtNborderWidth	"borderWidth"
+XtNcallback	"callback"
+XtNchangeHook	"changeHook"
+XtNchildren	"children"
+XtNcolormap	"colormap"
+XtNconfigureHook	"configureHook"
+XtNcreateHook	"createHook"
+XtNdepth	"depth"
+XtNdestroyCallback	"destroyCallback"
+XtNdestroyHook	"destroyHook"
+XtNeditType	"editType"
+XtNfile	"file"
+XtNfont	"font"
+XtNfontSet	"fontSet"
+XtNforceBars	"forceBars"
+XtNforeground	"foreground"
+XtNfunction	"function"
+XtNgeometryHook	"geometryHook"
+XtNheight	"height"
+XtNhighlight	"highlight"
+XtNhSpace	"hSpace"
+XtNindex	"index"
+XtNinitialResourcesPersistent	"initialResourcesPersistent"
+XtNinnerHeight	"innerHeight"
+XtNinnerWidth	"innerWidth"
+XtNinnerWindow	"innerWindow"
+XtNinsertPosition	"insertPosition"
+XtNinternalHeight	"internalHeight"
+XtNinternalWidth	"internalWidth"
+XtNjumpProc	"jumpProc"
+XtNjustify	"justify"
+XtNknobHeight	"knobHeight"
+XtNknobIndent	"knobIndent"
+XtNknobPixel	"knobPixel"
+XtNknobWidth	"knobWidth"
+XtNlabel	"label"
+XtNlength	"length"
+XtNlowerRight	"lowerRight"
+XtNmappedWhenManaged	"mappedWhenManaged"
+XtNmenuEntry	"menuEntry"
+XtNname	"name"
+XtNnotify	"notify"
+XtNnumChildren	"numChildren"
+XtNnumShells	"numShells"
+XtNorientation	"orientation"
+XtNparameter	"parameter"
+XtNpixmap	"pixmap"
+XtNpopupCallback	"popupCallback"
+XtNpopdownCallback	"popdownCallback"
+XtNresize	"resize"
+XtNreverseVideo	"reverseVideo"
+XtNscreen	"screen"
+XtNscrollProc	"scrollProc"
+XtNscrollDCursor	"scrollDCursor"
+XtNscrollHCursor	"scrollHCursor"
+XtNscrollLCursor	"scrollLCursor"
+XtNscrollRCursor	"scrollRCursor"
+XtNscrollUCursor	"scrollUCursor"
+XtNscrollVCursor	"scrollVCursor"
+XtNselection	"selection"
+XtNselectionArray	"selectionArray"
+XtNsensitive	"sensitive"
+XtNsession	"session"
+XtNshells	"shells"
+XtNshown	"shown"
+XtNspace	"space"
+XtNstring	"string"
+XtNtextOptions	"textOptions"
+XtNtextSink	"textSink"
+XtNtextSource	"textSource"
+XtNthickness	"thickness"
+XtNthumb	"thumb"
+XtNthumbProc	"thumbProc"
+XtNtop	"top"
+XtNtranslations	"translations"
+XtNunrealizeCallback	"unrealizeCallback"
+XtNupdate	"update"
+XtNuseBottom	"useBottom"
+XtNuseRight	"useRight"
+XtNvalue	"value"
+XtNvSpace	"vSpace"
+XtNwidth	"width"
+XtNwindow	"window"
+XtNx	"x"
+XtNy	"y"
+.sp 6p
+_
+.TE
+.sp 6p
+.IN "String Constants" "resource classes"
+.LP
+Resource classes:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtCAccelerators	"Accelerators"
+XtCBackground	"Background"
+XtCBitmap	"Bitmap"
+XtCBoolean	"Boolean"
+XtCBorderColor	"BorderColor"
+XtCBorderWidth	"BorderWidth"
+XtCCallback	"Callback"
+XtCColormap	"Colormap"
+XtCColor	"Color"
+XtCCursor	"Cursor"
+XtCDepth	"Depth"
+XtCEditType	"EditType"
+XtCEventBindings	"EventBindings"
+XtCFile	"File"
+XtCFont	"Font"
+XtCFontSet	"FontSet"
+XtCForeground	"Foreground"
+XtCFraction	"Fraction"
+XtCFunction	"Function"
+XtCHeight	"Height"
+XtCHSpace	"HSpace"
+XtCIndex	"Index"
+XtCInitialResourcesPersistent	"InitialResourcesPersistent"
+XtCInsertPosition	"InsertPosition"
+XtCInterval	"Interval"
+XtCJustify	"Justify"
+XtCKnobIndent	"KnobIndent"
+XtCKnobPixel	"KnobPixel"
+XtCLabel	"Label"
+XtCLength	"Length"
+XtCMappedWhenManaged	"MappedWhenManaged"
+XtCMargin	"Margin"
+XtCMenuEntry	"MenuEntry"
+XtCNotify	"Notify"
+XtCOrientation	"Orientation"
+XtCParameter	"Parameter"
+XtCPixmap	"Pixmap"
+XtCPosition	"Position"
+XtCReadOnly	"ReadOnly"
+XtCResize	"Resize"
+XtCReverseVideo	"ReverseVideo"
+XtCScreen	"Screen"
+XtCScrollProc	"ScrollProc"
+XtCScrollDCursor	"ScrollDCursor"
+XtCScrollHCursor	"ScrollHCursor"
+XtCScrollLCursor	"ScrollLCursor"
+XtCScrollRCursor	"ScrollRCursor"
+XtCScrollUCursor	"ScrollUCursor"
+XtCScrollVCursor	"ScrollVCursor"
+XtCSelection	"Selection"
+XtCSelectionArray	"SelectionArray"
+XtCSensitive	"Sensitive"
+XtCSession	"Session"
+XtCSpace	"Space"
+XtCString	"String"
+XtCTextOptions	"TextOptions"
+XtCTextPosition	"TextPosition"
+XtCTextSink	"TextSink"
+XtCTextSource	"TextSource"
+XtCThickness	"Thickness"
+XtCThumb	"Thumb"
+XtCTranslations	"Translations"
+XtCValue	"Value"
+XtCVSpace	"VSpace"
+XtCWidth	"Width"
+XtCWindow	"Window"
+XtCX	"X"
+XtCY	"Y"
+.sp 6p
+_
+.TE
+.sp 6p
+.IN "String Constants" "representation types"
+.LP
+Resource representation types:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtRAcceleratorTable	"AcceleratorTable"
+XtRAtom	"Atom"
+XtRBitmap	"Bitmap"
+XtRBool	"Bool"
+XtRBoolean	"Boolean"
+XtRCallback	"Callback"
+XtRCallProc	"CallProc"
+XtRCardinal	"Cardinal"
+XtRColor	"Color"
+XtRColormap	"Colormap"
+XtRCommandArgArray	"CommandArgArray"
+XtRCursor	"Cursor"
+XtRDimension	"Dimension"
+XtRDirectoryString	"DirectoryString"
+XtRDisplay	"Display"
+XtREditMode	"EditMode"
+XtREnum	"Enum"
+XtREnvironmentArray	"EnvironmentArray"
+XtRFile	"File"
+XtRFloat	"Float"
+XtRFont	"Font"
+XtRFontSet	"FontSet"
+XtRFontStruct	"FontStruct"
+XtRFunction	"Function"
+XtRGeometry	"Geometry"
+XtRGravity	"Gravity"
+XtRImmediate	"Immediate"
+XtRInitialState	"InitialState"
+XtRInt	"Int"
+XtRJustify	"Justify"
+XtRLongBoolean	XtRBool
+XtRObject	"Object"
+XtROrientation	"Orientation"
+XtRPixel	"Pixel"
+XtRPixmap	"Pixmap"
+XtRPointer	"Pointer"
+XtRPosition	"Position"
+XtRRestartStyle	"RestartStyle"
+XtRScreen	"Screen"
+XtRShort	"Short"
+XtRSmcConn	"SmcConn"
+XtRString	"String"
+XtRStringArray	"StringArray"
+XtRStringTable	"StringTable"
+XtRUnsignedChar	"UnsignedChar"
+XtRTranslationTable	"TranslationTable"
+XtRVisual	"Visual"
+XtRWidget	"Widget"
+XtRWidgetClass	"WidgetClass"
+XtRWidgetList	"WidgetList"
+XtRWindow	"Window"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+Boolean enumeration constants:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtEoff	"off"
+XtEfalse	"false"
+XtEno	"no"
+XtEon	"on"
+XtEtrue	"true"
+XtEyes	"yes"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+Orientation enumeration constants:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtEvertical	"vertical"
+XtEhorizontal	"horizontal"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+Text edit enumeration constants:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtEtextRead	"read"
+XtEtextAppend	"append"
+XtEtextEdit	"edit"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+Color enumeration constants:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtExtdefaultbackground	"xtdefaultbackground"
+XtExtdefaultforeground	"xtdefaultforeground"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+Font constant:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtExtdefaultfont	"xtdefaultfont"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+Hooks for External Agents constants:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtHcreate	"Xtcreate"
+XtHsetValues	"Xtsetvalues"
+XtHmanageChildren	"XtmanageChildren"
+XtHunmanageChildren	"XtunmanageChildren"
+XtHmanageSet	"XtmanageSet"
+XtHunmanageSet	"XtunmanageSet"
+XtHrealizeWidget	"XtrealizeWidget"
+XtHunrealizeWidget	"XtunrealizeWidget"
+XtHaddCallback	"XtaddCallback"
+XtHaddCallbacks	"XtaddCallbacks"
+XtHremoveCallback	"XtremoveCallback"
+XtHremoveCallbacks	"XtremoveCallbacks"
+XtHremoveAllCallbacks	"XtremoveAllCallbacks"
+XtHaugmentTranslations	"XtaugmentTranslations"
+XtHoverrideTranslations	"XtoverrideTranslations"
+XtHuninstallTranslations	"XtuninstallTranslations"
+XtHsetKeyboardFocus	"XtsetKeyboardFocus"
+XtHsetWMColormapWindows	"XtsetWMColormapWindows"
+XtHmapWidget	"XtmapWidget"
+XtHunmapWidget	"XtunmapWidget"
+XtHpopup	"Xtpopup"
+XtHpopupSpringLoaded	"XtpopupSpringLoaded"
+XtHpopdown	"Xtpopdown"
+XtHconfigure	"Xtconfigure"
+XtHpreGeometry	"XtpreGeometry"
+XtHpostGeometry	"XtpostGeometry"
+XtHdestroy	"Xtdestroy"
+.sp 6p
+_
+.TE
+.sp 6p
+.LP
+The 
+.PN Shell.h
+header file contains definitions for the following resource name,
+class, and representation type symbolic constants.
+.IN "String Constants" "resource names"
+.LP
+Resource names:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtNallowShellResize	"allowShellResize"
+XtNargc	"argc"
+XtNargv	"argv"
+XtNbaseHeight	"baseHeight"
+XtNbaseWidth	"baseWidth"
+XtNcancelCallback	"cancelCallback"
+XtNclientLeader	"clientLeader"
+XtNcloneCommand	"cloneCommand"
+XtNconnection	"connection"
+XtNcreatePopupChildProc	"createPopupChildProc"
+XtNcurrentDirectory	"currentDirectory"
+XtNdieCallback	"dieCallback"
+XtNdiscardCommand	"discardCommand"
+XtNenvironment	"environment"
+XtNerrorCallback	"errorCallback"
+XtNgeometry	"geometry"
+XtNheightInc	"heightInc"
+XtNiconMask	"iconMask"
+XtNiconName	"iconName"
+XtNiconNameEncoding	"iconNameEncoding"
+XtNiconPixmap	"iconPixmap"
+XtNiconWindow	"iconWindow"
+XtNiconX	"iconX"
+XtNiconY	"iconY"
+XtNiconic	"iconic"
+XtNinitialState	"initialState"
+XtNinput	"input"
+XtNinteractCallback	"interactCallback"
+XtNjoinSession	"joinSession"
+XtNmaxAspectX	"maxAspectX"
+XtNmaxAspectY	"maxAspectY"
+XtNmaxHeight	"maxHeight"
+XtNmaxWidth	"maxWidth"
+XtNminAspectX	"minAspectX"
+XtNminAspectY	"minAspectY"
+XtNminHeight	"minHeight"
+XtNminWidth	"minWidth"
+XtNoverrideRedirect	"overrideRedirect"
+XtNprogramPath	"programPath"
+XtNresignCommand	"resignCommand"
+XtNrestartCommand	"restartCommand"
+XtNrestartStyle	"restartStyle"
+XtNsaveCallback	"saveCallback"
+XtNsaveCompleteCallback	"saveCompleteCallback"
+XtNsaveUnder	"saveUnder"
+XtNsessionID	"sessionID"
+XtNshutdownCommand	"shutdownCommand"
+XtNtitle	"title"
+XtNtitleEncoding	"titleEncoding"
+XtNtransient	"transient"
+XtNtransientFor	"transientFor"
+XtNurgency	"urgency"
+XtNvisual	"visual"
+XtNwaitForWm	"waitforwm"
+XtNwaitforwm	"waitforwm"
+XtNwidthInc	"widthInc"
+XtNwindowGroup	"windowGroup"
+XtNwindowRole	"windowRole"
+XtNwinGravity	"winGravity"
+XtNwmTimeout	"wmTimeout"
+.sp 6p
+_
+.TE
+.sp 6p
+.IN "String Constants" "resource classes"
+.LP
+Resource classes:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtCAllowShellResize	"allowShellResize"
+XtCArgc	"Argc"
+XtCArgv	"Argv"
+XtCBaseHeight	"BaseHeight"
+XtCBaseWidth	"BaseWidth"
+XtCClientLeader	"ClientLeader"
+XtCCloneCommand	"CloneCommand"
+XtCConnection	"Connection"
+XtCCreatePopupChildProc	"CreatePopupChildProc"
+XtCCurrentDirectory	"CurrentDirectory"
+XtCDiscardCommand	"DiscardCommand"
+XtCEnvironment	"Environment"
+XtCGeometry	"Geometry"
+XtCHeightInc	"HeightInc"
+XtCIconMask	"IconMask"
+XtCIconName	"IconName"
+XtCIconNameEncoding	"IconNameEncoding"
+XtCIconPixmap	"IconPixmap"
+XtCIconWindow	"IconWindow"
+XtCIconX	"IconX"
+XtCIconY	"IconY"
+XtCIconic	"Iconic"
+XtCInitialState	"InitialState"
+XtCInput	"Input"
+XtCJoinSession	"JoinSession"
+XtCMaxAspectX	"MaxAspectX"
+XtCMaxAspectY	"MaxAspectY"
+XtCMaxHeight	"MaxHeight"
+XtCMaxWidth	"MaxWidth"
+XtCMinAspectX	"MinAspectX"
+XtCMinAspectY	"MinAspectY"
+XtCMinHeight	"MinHeight"
+XtCMinWidth	"MinWidth"
+XtCOverrideRedirect	"OverrideRedirect"
+XtCProgramPath	"ProgramPath"
+XtCResignCommand	"ResignCommand"
+XtCRestartCommand	"RestartCommand"
+XtCRestartStyle	"RestartStyle"
+XtCSaveUnder	"SaveUnder"
+XtCSessionID	"SessionID"
+XtCShutdownCommand	"ShutdownCommand"
+XtCTitle	"Title"
+XtCTitleEncoding	"TitleEncoding"
+XtCTransient	"Transient"
+XtCTransientFor	"TransientFor"
+XtCUrgency	"Urgency"
+XtCVisual	"Visual"
+XtCWaitForWm	"Waitforwm"
+XtCWaitforwm	"Waitforwm"
+XtCWidthInc	"WidthInc"
+XtCWindowGroup	"WindowGroup"
+XtCWindowRole	"WindowRole"
+XtCWinGravity	"WinGravity"
+XtCWmTimeout	"WmTimeout"
+.sp 6p
+_
+.TE
+.sp 6p
+.IN "String Constants" "representation types"
+.LP
+Resource representation types:
+.TS
+lw(2i) lw(2.5i).
+_
+.sp 6p
+Symbol	Definition
+.sp 6p
+_
+.sp 6p
+XtRAtom	"Atom"
+.sp 6p
+_
+.TE
diff --git a/libXt/specs/appF b/libXt/specs/appF
new file mode 100644
index 000000000..b74cf4a3e
--- /dev/null
+++ b/libXt/specs/appF
@@ -0,0 +1,125 @@
+.\" $Xorg: appF,v 1.3 2000/08/17 19:42:49 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix F\fP\s-1
+
+\s+1\fBResource Configuration Management\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix F \(em Resource Configuration Management\fP
+.XE
+Setting and changing resources in X applications can be difficult for
+both the application programmer and the end user.  \fBResource
+Configuration Management (RCM)\fP addresses this problem by changing 
+the \fBX Intrinsics\fP to immediately modify a resource for a 
+specified widget and each child widget in the hierarchy.  
+In this context, immediate means: no sourcing of a resource 
+file is required; the application does not need to be restarted for the 
+new resource values to take effect; and the change
+occurs immediately.
+.LP
+The main difference between \fBRCM\fP and the \fBEditres\fP 
+protocol is that the \fBRCM\fP
+customizing hooks reside in the \fBIntrinsics\fP and thus are linked with
+other toolkits such as Motif and the Athena widgets.  However, the
+\fBEditRes\fP protocol requires the application to link with the 
+\fBEditRes\fP
+routines in the Xmu library and Xmu is not used by all applications that
+use Motif.  Also, the \fBEditRes\fP protocol uses ClientMessage, 
+whereas the
+\fBRCM\fP \fBIntrinsics\fP hooks use \fBPropertyNotify\fP events.
+.LP
+X Properties and the \fBPropertyNotify\fP events are used 
+to implement \fBRCM\fP and
+allow on-the-fly resource customization.  When the X Toolkit is
+initialized, two atoms are interned with the strings 
+\fICustom Init\fP and
+\fICustom Data\fP.  Both 
+.PN _XtCreatePopupShell
+and
+.PN _XtAppCreateShell
+register a \fBPropertyNotify\fP event handler to handle these properties.
+.LP
+A customization tool uses the \fICustom Init\fP property to \fIping\fP an
+application to get the application's toplevel window.  When the
+application's property notify event handler is invoked, the handler
+deletes the property.  No data is transferred in this property.
+.LP
+A customization tool uses the \fICustom Data\fP property to tell an
+application that it should change a resource's value.  The data in
+the property contains the length of the resource name (the number
+of bytes in the resource name), the resource name and the new
+value for the resource.  This property's type is \fBXA_STRING\fP and
+the format of the string is:
+.IP 1. 5
+The length of the resource name (the number of bytes in
+the resource name)
+.IP 2. 5
+One space character
+.IP 3. 5
+The resource name
+.IP 4. 5
+One space character
+.IP 5. 5
+The resource value
+.LP
+When setting the application's resource, the event handler calls
+functions to walk the application's widget tree, determining which
+widgets are affected by the resource string, and then applying the value
+with 
+.PN XtSetValues.
+As the widget tree is recursively descended, at
+each level in the widget tree a resource part is tested for a match.
+When the entire resource string has been matched, the value is applied
+to the widget or widgets.
+.LP
+Before a value is set on a widget, it is first determined if the last
+part of the resource is a valid resource for that widget.  It must also
+add the resource to the application's resource database and then query
+it using specific resource strings that is builds from the widget
+information.
+
+
diff --git a/libXt/specs/intr.idxmac.t b/libXt/specs/intr.idxmac.t
new file mode 100644
index 000000000..9a3572d2e
--- /dev/null
+++ b/libXt/specs/intr.idxmac.t
@@ -0,0 +1,3 @@
+.eh '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP'
+.oh '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP'
+.so index.pageno
diff --git a/libXt/specs/postproc b/libXt/specs/postproc
new file mode 100644
index 000000000..588b1de2c
--- /dev/null
+++ b/libXt/specs/postproc
@@ -0,0 +1,19 @@
+.\" $Xorg: postproc,v 1.3 2000/08/17 19:42:49 cpqbld Exp $
+.EH ''''
+.OH ''''
+.if o .bp \" blank page to make index and ToC start on odd page
+\&
+.nr PN +1
+.XS
+Index
+.XE
+.EQ
+delim $$
+.EN
+.tm .pn \n(PN
+.nr PN -1
+.\" print Table of Contents
+.bp 3
+.af PN i
+.PX
+
diff --git a/libXt/specs/strings.mit b/libXt/specs/strings.mit
new file mode 100644
index 000000000..87cc71081
--- /dev/null
+++ b/libXt/specs/strings.mit
@@ -0,0 +1,16 @@
+.ds tk X Toolkit
+.ds xT X Toolkit Intrinsics \(em C Language Interface
+.ds xI Intrinsics
+.ds xW X Toolkit Athena Widgets \(em C Language Interface
+.ds xL Xlib \(em C Language X Interface
+.ds xC Inter-Client Communication Conventions Manual
+.ds xP X Window System Protocol
+.ds Rn 6.8
+.ds Vn 2.2
+.ds oI Must be of class Object or any subclass thereof.
+.ds rI Must be of class RectObj or any subclass thereof.
+.ds cI Must be of class Core or any subclass thereof.
+.ds oC Must be \fBobjectClass\fP or any subclass thereof.
+.ds rC Must be \fBrectObjClass\fP or any subclass thereof.
+.hw XtMake-Geometry-Request XtQuery-Geometry wid-get Composite-Part \
+Rect-Obj-Rec XtIsOverrideShell super-class