summaryrefslogtreecommitdiff
path: root/specs
diff options
context:
space:
mode:
authorMatt Dew <marcoz@osource.org>2011-12-28 20:34:51 -0700
committerMatt Dew <marcoz@osource.org>2011-12-28 20:34:51 -0700
commitb8818e1233b75c6bd47a6d2197fabf3a036a2119 (patch)
treeb2d5563cee3b4dcda51b5dd5c7af52c058260fe8 /specs
parentfd0da0d44a8501edaac3be7fac9449ad730d8bf4 (diff)
Initial docbook conversion.
Diffstat (limited to 'specs')
-rw-r--r--specs/CH01.xml2798
-rw-r--r--specs/CH02.xml4538
-rw-r--r--specs/CH03.xml1406
-rw-r--r--specs/CH04.xml2498
-rw-r--r--specs/CH05.xml1063
-rw-r--r--specs/CH06.xml1369
-rw-r--r--specs/CH07.xml4989
-rw-r--r--specs/CH08.xml613
-rw-r--r--specs/CH09.xml4326
-rw-r--r--specs/CH10.xml2211
-rw-r--r--specs/CH11.xml5538
-rw-r--r--specs/CH12.xml1166
-rw-r--r--specs/CH13.xml770
-rw-r--r--specs/Makefile.am61
-rw-r--r--specs/acknowledgement.xml323
-rw-r--r--specs/appA.xml112
-rw-r--r--specs/appB.xml1181
-rw-r--r--specs/appC.xml1970
-rw-r--r--specs/appD.xml880
-rw-r--r--specs/appE.xml1703
-rw-r--r--specs/appF.xml103
-rw-r--r--specs/intrinsics.xml128
-rw-r--r--specs/preface.xml51
23 files changed, 39773 insertions, 24 deletions
diff --git a/specs/CH01.xml b/specs/CH01.xml
new file mode 100644
index 0000000..2f6a36f
--- /dev/null
+++ b/specs/CH01.xml
@@ -0,0 +1,2798 @@
+<chapter id='Intrinsics_and_Widgets'>
+<title>Intrinsics and Widgets</title>
+<para>
+The Intrinsics are a programming library tailored to the special requirements
+of user interface construction within a network window system,
+specifically the X Window System.
+The Intrinsics and a widget set make up an X Toolkit.
+</para>
+<sect1 id="Intrinsics">
+<title>Intrinsics</title>
+<para>
+The Intrinsics 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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+When the Intrinsics were first conceived, the root of the object
+hierarchy was a widget class named
+Core.
+In Release 4 of the
+Intrinsics, three nonwidget superclasses were added above Core.
+These superclasses are described in <xref linkend='Nonwidget_Objects' />.
+The name of the class
+now at the root of the Intrinsics class hierarchy is
+Object.
+The remainder of this
+specification refers uniformly to <emphasis remap='I'>widgets</emphasis> and <emphasis remap='I'>Core</emphasis>
+as if they were the
+base class for all Intrinsics operations. The argument descriptions
+for each Intrinsics procedure and <xref linkend='Nonwidget_Objects' />
+describe which operations
+are defined for the nonwidget superclasses of Core. The reader may
+determine by context whether a specific reference to <emphasis remap='I'>widget</emphasis>
+actually means ``widget'' or ``object.''
+</para>
+</sect1>
+
+<sect1 id="Languages">
+<title>Languages</title>
+<para>
+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 <emphasis remap='I'>client</emphasis> refers to
+any module, widget, or application that calls an Intrinsics procedure.
+</para>
+
+<para>
+Applications that use the Intrinsics mechanisms
+must include the header files
+<function>&lt;X11/Intrinsic.h&gt;</function>
+and
+<function>&lt;X11/StringDefs.h&gt;</function>,
+or their equivalent,
+and they may also include
+<function>&lt;X11/Xatoms.h&gt;</function>
+and
+<function>&lt;X11/Shell.h&gt;</function>.
+In addition, widget implementations should include
+<function>&lt;X11/IntrinsicP.h&gt;</function>
+instead of
+<function>&lt;X11/Intrinsic.h&gt;</function>.
+</para>
+
+<para>
+The applications must also include the additional header files for
+each widget class that they are to use (for example,
+<function>&lt;X11/Xaw/Label.h&gt;</function>
+or
+<function>&lt;X11/Xaw/Scrollbar.h&gt;).</function>
+On a POSIX-based system,
+the Intrinsics object library file is named
+<function>libXt.a</function>
+and is usually referenced as \-lXt when linking the application.
+</para>
+</sect1>
+
+<sect1 id="Procedures_and_Macros">
+<title>Procedures and Macros</title>
+<para>
+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.
+</para>
+
+<para>
+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:
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
+<xref linkend='XtNew' xrefstyle='select: title'/>,
+<xref linkend='XtNumber' xrefstyle='select: title'/>,
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>,
+<xref linkend='XtOffset' xrefstyle='select: title'/>,
+and
+<xref linkend='XtSetArg' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Widgets">
+<title>Widgets</title>
+<para>
+The fundamental abstraction and data type of the X Toolkit 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.
+</para>
+
+<para>
+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 <xref linkend='Creating_Widgets' />
+</para>
+
+<para>
+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 <xref linkend='Widget_Classing' />
+The predefined widget classes adhere to these conventions.
+</para>
+
+<para>
+A widget instance is composed of two parts:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A data structure which contains instance-specific values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A class structure which contains information that is applicable to
+all widgets of that class.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Much of the input/output of a widget (for example, fonts, colors, sizes,
+or border widths) is customizable by users.
+</para>
+
+<para>
+This chapter discusses the base widget classes,
+Core, Composite, and Constraint, and
+ends with a discussion of widget classing.
+</para>
+<sect2 id="Core_Widgets">
+<title>Core Widgets</title>
+<para>
+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
+<function>CoreClassPart</function>
+and
+<function>CorePart</function>
+structures.
+</para>
+<sect3 id="CoreClassPart_Structure">
+<title>CoreClassPart Structure</title>
+<para>
+All widget classes contain the fields defined in the
+<function>CoreClassPart</function>
+structure.
+</para>
+<literallayout>
+typedef struct {
+ WidgetClass superclass; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+ String class_name; See <xref linkend="Resource_Management" xrefstyle='select: label' />
+ Cardinal widget_size; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+ XtProc class_initialize; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+ XtWidgetClassProc class_part_initialize; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+ XtEnum class_inited; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+ XtInitProc initialize; See <xref linkend='Creating_Widgets' xrefstyle='select: label' />
+ XtArgsProc initialize_hook; See <xref linkend='Creating_Widgets' xrefstyle='select: label' />
+ XtRealizeProc realize; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ XtActionList actions; See <xref linkend='Translation_Management' xrefstyle='select: label' />
+ Cardinal num_actions; See <xref linkend='Translation_Management' xrefstyle='select: label' />
+ XtResourceList resources; See <xref linkend="Resource_Management" xrefstyle='select: label' />
+ Cardinal num_resources; See <xref linkend="Resource_Management" xrefstyle='select: label' />
+ XrmClass xrm_class; Private to resource manager
+ Boolean compress_motion; See <xref linkend='X_Event_Filters' xrefstyle='select: label' />
+ XtEnum compress_exposure; See <xref linkend='X_Event_Filters' xrefstyle='select: label' />
+ Boolean compress_enterleave; See <xref linkend='X_Event_Filters' xrefstyle='select: label' />
+ Boolean visible_interest; See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: label' />
+ XtWidgetProc destroy; See <xref linkend='Destroying_Widgets' xrefstyle='select: label' />
+ XtWidgetProc resize; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ XtExposeProc expose; See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: label' />
+ XtSetValuesFunc set_values; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
+ XtArgsFunc set_values_hook; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
+ XtAlmostProc set_values_almost; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
+ XtArgsProc get_values_hook; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
+ XtAcceptFocusProc accept_focus; See <xref linkend='Focusing_Events_on_a_Child' xrefstyle='select: label' />
+ XtVersionType version; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+ XtPointer callback_private; Private to callbacks
+ String tm_table; See <xref linkend='Translation_Management' xrefstyle='select: label' />
+ XtGeometryHandler query_geometry; See <xref linkend ='Geometry_Management' xrefstyle='select: label' />
+ XtStringProc display_accelerator; See <xref linkend='Translation_Management' xrefstyle='select: label' />
+ XtPointer extension; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
+} CoreClassPart;
+</literallayout>
+<para>
+All widget classes have the Core class fields as their first component.
+The prototypical
+<function>WidgetClass</function>
+and
+<function>CoreWidgetClass</function>
+are defined with only this set of fields.
+</para>
+<literallayout>
+typedef struct {
+ CoreClassPart core_class;
+} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
+</literallayout>
+<para>
+Various routines can cast widget class pointers, as needed,
+to specific widget class types.
+</para>
+
+<para>
+The single occurrences of the class record and pointer for
+creating instances of Core are
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout>
+extern WidgetClassRec widgetClassRec;
+#define coreClassRec widgetClassRec
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout>
+extern WidgetClass widgetClass, coreWidgetClass;
+</literallayout>
+<para>
+The opaque types
+<function>Widget</function>
+and
+<function>WidgetClass</function>
+and the opaque variable
+<function>widgetClass</function>
+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 Intrinsics use
+incomplete structure definitions in
+<function>Intrinsic.h</function>:
+</para>
+<literallayout>
+typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
+</literallayout>
+</sect3>
+<sect3 id="CorePart_Structure">
+<title>CorePart Structure</title>
+<para>
+All widget instances contain the fields defined in the
+<function>CorePart</function>
+structure.
+</para>
+<literallayout>
+typedef struct _CorePart {
+ Widget self; Described below
+ WidgetClass widget_class; See <xref linkend='Widget_Classing' xrefstyle='select: label' />
+ Widget parent; See <xref linkend='Creating_Widgets' xrefstyle='select: label' />
+ Boolean being_destroyed; See <xref linkend='Destroying_Widgets' xrefstyle='select: label' />
+ XtCallbackList destroy_callbacks; <xref linkend='Destroying_Widgets' xrefstyle='select: label' />
+ XtPointer constraints; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
+ Position x; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ Position y; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ Dimension width; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ Dimension height; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ Dimension border_width; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ Boolean managed; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ Boolean sensitive; See <xref linkend='Setting_and_Checking_the_Sensitivity_State_of_a_Widget' xrefstyle='select: label' />
+ Boolean ancestor_sensitive; See <xref linkend='Setting_and_Checking_the_Sensitivity_State_of_a_Widget' xrefstyle='select: label' />
+ XtTranslations accelerators; See <xref linkend='Translation_Management' xrefstyle='select: label' />
+ Pixel border_pixel; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Pixmap border_pixmap; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ WidgetList popup_list; See <xref linkend='Pop_Up_Widgets' xrefstyle='select: label' />
+ Cardinal num_popups; See <xref linkend='Pop_Up_Widgets' xrefstyle='select: label' />
+ String name; See <xref linkend='Resource_Management' xrefstyle='select: label' />
+ Screen *screen; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Colormap colormap; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Window window; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Cardinal depth; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Pixel background_pixel; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Pixmap background_pixmap; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
+ Boolean visible; See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: label' />
+ Boolean mapped_when_managed; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+} CorePart;
+</literallayout>
+<para>
+All widget instances have the Core fields as their first component.
+The prototypical type
+<function>Widget</function>
+is defined with only this set of fields.
+</para>
+<literallayout>
+typedef struct {
+ CorePart core;
+} WidgetRec, *Widget, CoreRec, *CoreWidget;
+</literallayout>
+<para>
+Various routines can cast widget pointers, as needed,
+to specific widget types.
+</para>
+
+<para>
+In order to make these types opaque and ensure that the compiler
+does not allow applications to access private data, the Intrinsics use
+incomplete structure definitions in
+<function>Intrinsic.h</function>.
+</para>
+<literallayout>
+typedef struct _WidgetRec *Widget, *CoreWidget;
+</literallayout>
+</sect3>
+<sect3 id="Core_Resources">
+<title>Core Resources</title>
+<para>
+The resource names, classes, and representation types specified in the
+<function>coreClassRec</function>
+resource list are
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNaccelerators</entry>
+ <entry>XtCAccelerators</entry>
+ <entry>XtRAcceleratorTable</entry>
+ </row>
+ <row>
+ <entry>XtNbackground</entry>
+ <entry>XtCBackground</entry>
+ <entry>XtRPixel</entry>
+ </row>
+ <row>
+ <entry>XtNbackgroundPixmap</entry>
+ <entry>XtCPixmap</entry>
+ <entry>XtRPixmap</entry>
+ </row>
+ <row>
+ <entry>XtNborderColor</entry>
+ <entry>XtCBorderColor</entry>
+ <entry>XtRPixel</entry>
+ </row>
+ <row>
+ <entry>XtNborderPixmap</entry>
+ <entry>XtCPixmap</entry>
+ <entry>XtRPixmap</entry>
+ </row>
+ <row>
+ <entry>XtNcolormap</entry>
+ <entry>XtCColormap</entry>
+ <entry>XtRColormap</entry>
+ </row>
+ <row>
+ <entry>XtNdepth</entry>
+ <entry>XtCDepth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmappedWhenManaged</entry>
+ <entry>XtCMappedWhenManaged</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNscreen</entry>
+ <entry>XtCScreen</entry>
+ <entry>XtRScreen</entry>
+ </row>
+ <row>
+ <entry>XtNtranslations</entry>
+ <entry>XtCTranslations</entry>
+ <entry>XtRTranslationTable</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<para>
+Additional resources are defined for all widgets via the
+<function>objectClassRec</function>
+and
+<function>rectObjClassRec</function>
+resource lists; see <xref linkend='Object_Objects' /> and <xref linkend='Rectangle_Objects' /> for details.
+</para>
+</sect3>
+<sect3 id="CorePart_Default_Values">
+<title>CorePart Default Values</title>
+<para>
+The default values for the Core fields, which are filled in by the Intrinsics,
+from the resource lists, and by the initialize procedures, are
+</para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='0.4*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>self</entry>
+ <entry>Address of the widget structure (may not be changed).</entry>
+ </row>
+ <row>
+ <entry>widget_class</entry>
+ <entry><emphasis remap='I'>widget_class</emphasis> argument to
+ <xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+ (may not be changed).</entry>
+ </row>
+ <row>
+ <entry>parent</entry>
+ <entry><emphasis remap='I'>parent</emphasis> argument to
+ <xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+ (may not be changed).</entry>
+ </row>
+ <row>
+ <entry>being_destroyed</entry>
+ <entry>Parent's <emphasis remap='I'>being_destroyed</emphasis> value.</entry>
+ </row>
+ <row>
+ <entry>destroy_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>constraints</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>x</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>y</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>width</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>height</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>border_width</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>managed</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>sensitive</entry>
+ <entry><function>True</function></entry>
+ </row>
+ <row>
+ <entry>ancestor_sensitive</entry>
+ <entry>logical AND of parent's <emphasis remap='I'>sensitive</emphasis> and
+ <emphasis remap='I'>ancestor_sensitive</emphasis> values.</entry>
+ </row>
+ <row>
+ <entry>accelerators</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>border_pixel</entry>
+ <entry><function>XtDefaultForeground</function></entry>
+ </row>
+ <row>
+ <entry>border_pixmap</entry>
+ <entry><function>XtUnspecifiedPixmap</function></entry>
+ </row>
+ <row>
+ <entry>popup_list</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>num_popups</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>name</entry>
+ <entry><emphasis remap='I'>name</emphasis> argument to
+ <xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+ (may not be changed).</entry>
+ </row>
+ <row>
+ <entry>screen</entry>
+ <entry>Parent's <emphasis remap='I'>screen</emphasis>; top-level widget gets screen from display specifier
+ (may not be changed).</entry>
+ </row>
+ <row>
+ <entry>colormap</entry>
+ <entry>Parent's <emphasis remap='I'>colormap</emphasis> value.</entry>
+ </row>
+ <row>
+ <entry>window</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>depth</entry>
+ <entry>Parent's <emphasis remap='I'>depth</emphasis>; top-level widget gets root window depth.</entry>
+ </row>
+ <row>
+ <entry>background_pixel</entry>
+ <entry><function>XtDefaultBackground</function></entry>
+ </row>
+ <row>
+ <entry>background_pixmap</entry>
+ <entry><function>XtUnspecifiedPixmap</function></entry>
+ </row>
+ <row>
+ <entry>visible</entry>
+ <entry><function>True</function></entry>
+ </row>
+ <row>
+ <entry>mapped_when_managed</entry>
+ <entry><function>True</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+<para>
+<function>XtUnspecifiedPixmap</function>
+is a symbolic constant guaranteed to be unequal to
+any valid Pixmap id,
+<function>None</function>,
+and
+<function>ParentRelative</function>.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Composite_Widgets">
+<title>Composite Widgets</title>
+<para>
+The Composite
+widget class is a subclass of the
+Core
+widget class (see <xref linkend='Composite_Widgets_and_Their_Children' />).
+Composite widgets are intended to be containers for other widgets.
+The additional data used by composite widgets are defined by the
+<function>CompositeClassPart</function>
+and
+<function>CompositePart</function>
+structures.
+</para>
+<sect3 id="CompositeClassPart_Structure">
+<title>CompositeClassPart Structure</title>
+<para>
+In addition to the
+Core
+class fields,
+widgets of the Composite class have the following class fields.
+</para>
+<literallayout>
+typedef struct {
+ XtGeometryHandler geometry_manager; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
+ XtWidgetProc change_managed; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ XtWidgetProc insert_child; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ XtWidgetProc delete_child; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ XtPointer extension; See <xref linkend='Widget_Classing' xrefstyle='select: label' />
+} CompositeClassPart;
+</literallayout>
+<para>
+The extension record defined for
+<function>CompositeClassPart</function>
+with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>
+is
+<function>CompositeClassExtensionRec</function>.
+</para>
+<literallayout>
+typedef struct {
+ XtPointer next_extension; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ XrmQuark record_type; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ long version; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ Cardinal record_size; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ Boolean accepts_objects; See <xref linkend='Creating_a_Widget_Instance' xrefstyle='select: label' />
+ Boolean allows_change_managed_set; See <xref linkend='Bundling_Changes_to_the_Managed_Set' xrefstyle='select: label' />
+} CompositeClassExtensionRec, *CompositeClassExtension;
+</literallayout>
+<para>
+Composite
+classes have the Composite class fields immediately following the
+Core class fields.
+</para>
+<literallayout>
+typedef struct {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+} CompositeClassRec, *CompositeWidgetClass;
+</literallayout>
+<para>
+The single occurrences of the class record and pointer for creating
+instances of Composite are
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout>
+extern CompositeClassRec compositeClassRec;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout>
+extern WidgetClass compositeWidgetClass;
+</literallayout>
+<para>
+The opaque types
+<function>CompositeWidget</function>
+and
+<function>CompositeWidgetClass</function>
+and the opaque variable
+<function>compositeWidgetClass</function>
+are defined for generic operations on widgets whose class
+is Composite or a subclass of Composite.
+The symbolic constant for the
+<function>CompositeClassExtension</function>
+version identifier is
+<function>XtCompositeExtensionVersion</function>
+(see <xref linkend='Class_Extension_Records' />).
+<function>Intrinsic.h</function>
+uses an incomplete structure
+definition to ensure that the compiler catches attempts to access
+private data.
+</para>
+<literallayout>
+typedef struct _CompositeClassRec *CompositeWidgetClass;
+</literallayout>
+</sect3>
+<sect3 id="CompositePart_Structure">
+<title>CompositePart Structure</title>
+<para>
+In addition to the
+Core instance
+fields,
+widgets of the Composite class have the following
+instance fields defined in the
+<function>CompositePart</function>
+structure.
+</para>
+<literallayout>
+typedef struct {
+ WidgetList children; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ Cardinal num_children; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ Cardinal num_slots; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
+ XtOrderProc insert_position; See <xref linkend='Insertion_Order_of_Children_The_insert_position_Procedure' xrefstyle='select: label' />
+} CompositePart;
+</literallayout>
+<para>
+Composite
+widgets have the Composite instance fields immediately following the Core
+instance fields.
+</para>
+<literallayout>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+} CompositeRec, *CompositeWidget;
+</literallayout>
+<para>
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+</para>
+<literallayout>
+typedef struct _CompositeRec *CompositeWidget;
+</literallayout>
+</sect3>
+<sect3 id="Composite_Resources">
+<title>Composite Resources</title>
+<para>
+The resource names, classes, and representation types
+that are specified in
+the
+<function>compositeClassRec</function>
+resource list are
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNchildren</entry>
+ <entry>XtCReadOnly</entry>
+ <entry>XtRWidgetList</entry>
+ </row>
+ <row>
+ <entry>XtNinsertPosition</entry>
+ <entry>XtCInsertPosition</entry>
+ <entry>XtRFunction</entry>
+ </row>
+ <row>
+ <entry>XtNnumChildren</entry>
+ <entry>XtCReadOnly</entry>
+ <entry>XtRCardinal</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect3>
+<sect3 id="CompositePart_Default_Values">
+<title>CompositePart Default Values</title>
+<para>
+The default values for the Composite fields,
+which are filled in from the
+Composite
+resource list and by the
+Composite
+initialize procedure, are
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <?dbfo table-width="50%" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*' colsep='0'/>
+ <colspec colname='c2' colwidth='1.0*' colsep='0'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep='0'>
+ <entry>children</entry><entry>NULL</entry>
+ </row>
+ <row rowsep='0'>
+ <entry>num_children</entry><entry>0</entry>
+ </row>
+ <row rowsep='0'>
+ <entry>num_slots</entry><entry>0</entry>
+ </row>
+ <row rowsep='0'>
+ <entry>insert_position</entry><entry>Internal function to insert at end</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>children</emphasis>, <emphasis remap='I'>num_children</emphasis>,
+and <emphasis remap='I'>insert_position</emphasis> fields are declared
+as resources;
+XtNinsertPosition
+is a settable resource,
+XtNchildren
+and
+XtNnumChildren
+may be read by any client but should only be modified by the composite
+widget class procedures.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Constraint_Widgets">
+<title>Constraint Widgets</title>
+<para>
+The Constraint
+widget class is a subclass of the
+Composite
+widget class (see <xref linkend='Constrained_Composite_Widgets' />). 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
+<function>ConstraintClassPart</function>
+and
+<function>ConstraintPart</function>
+structures.
+</para>
+<sect3 id="ConstraintClassPart_Structure">
+<title>ConstraintClassPart Structure</title>
+<para>
+In addition to the
+Core
+and
+Composite
+class fields,
+widgets of the Constraint class
+have the following class fields.
+</para>
+<literallayout>
+typedef struct {
+ XtResourceList resources; See <xref linkend='Resource_Management' xrefstyle='select: label' />
+ Cardinal num_resources; See <xref linkend='Resource_Management' xrefstyle='select: label' />
+ Cardinal constraint_size; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
+ XtInitProc initialize; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
+ XtWidgetProc destroy; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
+ XtSetValuesFunc set_values; See <xref linkend='Setting_Widget_State' xrefstyle='select: label' />
+ XtPointer extension; See <xref linkend='Widget_Classing' xrefstyle='select: label' />
+} ConstraintClassPart;
+</literallayout>
+<para>
+The extension record defined for
+<function>ConstraintClassPart</function>
+with <emphasis remap='I'>record_type</emphasis> equal to
+<emphasis role='strong'>NULLQUARK</emphasis>
+is
+<function>ConstraintClassExtensionRec</function>.
+</para>
+<literallayout>
+typedef struct {
+ XtPointer next_extension; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ XrmQuark record_type; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ long version; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ Cardinal record_size; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
+ XtArgsProc get_values_hook; See <xref linkend='Obtaining_Widget_State' xrefstyle='select: label' />
+} ConstraintClassExtensionRec, *ConstraintClassExtension;
+</literallayout>
+<para>
+Constraint
+classes have the Constraint class fields immediately following the
+Composite class fields.
+</para>
+<literallayout>
+typedef struct _ConstraintClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ConstraintClassPart constraint_class;
+} ConstraintClassRec, *ConstraintWidgetClass;
+</literallayout>
+<para>
+The single occurrences of the class record and pointer for creating
+instances of Constraint are
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout>
+extern ConstraintClassRec constraintClassRec;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout>
+extern WidgetClass constraintWidgetClass;
+</literallayout>
+<para>
+The opaque types
+<function>ConstraintWidget</function>
+and
+<function>ConstraintWidgetClass</function>
+and the opaque variable
+<function>constraintWidgetClass</function>
+are defined for generic operations on widgets
+whose class is Constraint or a subclass
+of Constraint.
+The symbolic constant for the
+<function>ConstraintClassExtension</function>
+version identifier is
+<function>XtConstraintExtensionVersion</function>
+(see <xref linkend='Class_Extension_Records' />).
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+</para>
+<literallayout>
+typedef struct _ConstraintClassRec *ConstraintWidgetClass;
+</literallayout>
+</sect3>
+<sect3 id="ConstraintPart_Structure">
+<title>ConstraintPart Structure</title>
+<para>
+In addition to the
+Core
+and
+Composite instance
+fields,
+widgets of the Constraint class have the following unused
+instance fields defined in the
+<function>ConstraintPart</function>
+structure
+</para>
+<literallayout>
+typedef struct {
+ int empty;
+} ConstraintPart;
+</literallayout>
+<para>
+Constraint
+widgets have the Constraint instance fields immediately following the
+Composite instance fields.
+</para>
+<literallayout>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ConstraintPart constraint;
+} ConstraintRec, *ConstraintWidget;
+</literallayout>
+<para>
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+</para>
+<literallayout>
+typedef struct _ConstraintRec *ConstraintWidget;
+</literallayout>
+</sect3>
+<sect3 id="Constraint_Resources">
+<title>Constraint Resources</title>
+<para>
+The
+<function>constraintClassRec</function>
+<emphasis remap='I'>core_class</emphasis> and <emphasis remap='I'>constraint_class resources</emphasis> fields are NULL,
+and the <emphasis remap='I'>num_resources</emphasis> fields are zero;
+no additional resources beyond those declared by
+the superclasses
+are defined for
+Constraint.
+</para>
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="Implementation_Specific_Types">
+<title>Implementation-Specific Types</title>
+<para>
+To increase the portability of widget and application source code
+between different system environments, the Intrinsics define several
+types whose precise representation is explicitly dependent upon,
+and chosen by, each individual implementation of the Intrinsics.
+</para>
+
+<para>
+These implementation-defined types are
+</para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>Boolean</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>True</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>Cardinal</emphasis>
+ </term>
+ <listitem>
+ <para>
+An unsigned integer datum with a minimum range of [0..2^16-1].
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>Dimension</emphasis>
+ </term>
+ <listitem>
+ <para>
+An unsigned integer datum with a minimum range of [0..2^16-1].
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>Position</emphasis>
+ </term>
+ <listitem>
+ <para>
+A signed integer datum with a minimum range of [-2^15..2^15-1].
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtPointer</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>XtPointer</function>
+and back again and the result will
+compare equal to the original value. In ANSI C
+environments it is expected that
+<function>XtPointer</function>
+will be
+defined as void*.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtArgVal</emphasis>
+ </term>
+ <listitem>
+ <para>
+A datum large enough to contain an
+<function>XtPointer</function>,
+<function>Cardinal</function>,
+<function>Dimension</function>,
+or
+<function>Position</function>
+value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtEnum</emphasis>
+ </term>
+ <listitem>
+ <para>
+An integer datum large enough to encode at least 128 distinct
+values, two of which are the symbolic values
+<function>True</function>
+and
+<function>False</function>.
+The symbolic values
+<emphasis role='strong'>TRUE</emphasis>
+and
+<emphasis role='strong'>FALSE</emphasis>
+are
+also defined to be equal to
+<function>True</function>
+and
+<function>False</function>,
+respectively.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+In addition to these specific types, the precise order of the
+fields within the structure declarations for any of the instance
+part records
+<function>ObjectPart</function>,
+<function>RectObjPart</function>,
+<function>CorePart</function>,
+<function>CompositePart</function>,
+<function>ShellPart</function>,
+<function>WMShellPart</function>,
+<function>TopLevelShellPart</function>,
+and
+<function>ApplicationShellPart</function>
+is implementation-defined. These
+structures may also have additional private
+fields internal to the implementation.
+The
+<function>ObjectPart</function>,
+<function>RectObjPart</function>,
+and
+<function>CorePart</function>
+structures must be defined so that any member with the same name
+appears at the same offset in
+<function>ObjectRec</function>,
+<function>RectObjRec</function>,
+and
+<function>CoreRec</function>
+<function>( WidgetRec ).</function>
+No other relations between the offsets of any two
+fields may be assumed.
+</para>
+</sect1>
+
+<sect1 id="Widget_Classing">
+<title>Widget Classing</title>
+<para>
+The <emphasis remap='I'>widget_class</emphasis> 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.
+</para>
+
+<para>
+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
+<function>XtResourceList</function>.
+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).
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+To make good use of subclassing,
+widget declarations and naming conventions are highly stylized.
+A widget consists of three files:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A public .h file, used by client widgets or applications.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A private .h file, used by widgets whose classes
+are subclasses of the widget class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A .c file, which implements the widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Widget_Naming_Conventions">
+<title>Widget Naming Conventions</title>
+<para>
+The Intrinsics 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:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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,
+<function>ArgList</function>
+or
+<function>XtSetValues ).</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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 <emphasis remap='I'>background_pixmap</emphasis> field has the corresponding identifier
+XtNbackgroundPixmap,
+which is defined as the string ``backgroundPixmap''.
+Many predefined names are listed in
+<function>&lt;X11/StringDefs.h&gt;</function>.
+Before you invent a new name,
+you should make sure there is not already a name that you can use.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<function>&lt;X11/StringDefs.h&gt;</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<function>&lt;X11/StringDefs.h&gt;</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+New widget classes start with a capital and use uppercase for compound
+words.
+Given a new class name AbcXyz, you should derive several names:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Additional widget instance structure part name AbcXyzPart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Complete widget instance structure names AbcXyzRec and _AbcXyzRec.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Widget instance structure pointer type name AbcXyzWidget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Additional class structure part name AbcXyzClassPart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Class structure pointer type name AbcXyzWidgetClass.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Class structure variable abcXyzClassRec.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Class structure pointer variable abcXyzWidgetClass.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+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'').
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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
+<function>String</function>.
+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.
+</para>
+</sect2>
+
+<sect2 id="Widget_Subclassing_in_Public_h_Files">
+<title>Widget Subclassing in Public .h Files</title>
+<para>
+The public .h file for a widget class is imported by clients
+and contains
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A reference to the public .h file for the superclass.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Type declarations for any new resource data types defined by the class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The class record pointer variable used to create widget instances.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The C type that corresponds to widget instances of this class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Entry points for new class methods.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+For example, the following is the public .h file for a possible
+implementation of a Label widget:
+</para>
+<literallayout>
+#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
+</literallayout>
+<para>
+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.
+</para>
+
+<para>
+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
+<function>Constraint.h</function>.
+</para>
+</sect2>
+
+<sect2 id="Widget_Subclassing_in_Private_h_Files">
+<title>Widget Subclassing in Private .h Files</title>
+<para>
+The private .h file for a widget is imported by widget classes that are
+subclasses of the widget and contains
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A reference to the public .h file for the class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A reference to the private .h file for the superclass.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A structure part definition for
+the new fields that the widget instance adds to its superclass's
+widget structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The complete widget instance structure definition for this widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The complete
+constraint
+structure definition if the widget class is a subclass of
+Constraint.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Type definitions for any new procedure types used by class methods
+declared in the widget class part.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A structure part definition for
+the new fields that this widget class adds to its superclass's widget class
+structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The complete widget class structure definition for this widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The complete widget class extension structure definition
+for this widget, if any.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The symbolic constant identifying the class extension version, if any.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The name of the global class structure variable containing the generic
+class structure for this class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An inherit constant for each new procedure in the widget class part structure.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+For example, the following is the private .h file for a possible Label widget:
+</para>
+<literallayout>
+#ifndef LABELP_H
+#define LABELP_H
+#include &lt;X11/Label.h&gt;
+/* 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;
+</literallayout>
+<literallayout>
+/* 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
+</literallayout>
+<para>
+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
+<function>ConstrainP.h</function>.
+</para>
+</sect2>
+
+<sect2 id="Widget_Subclassing_in_c_Files">
+<title>Widget Subclassing in .c Files</title>
+<para>
+The .c file for a widget contains the structure initializer
+for the class record variable,
+which contains the following parts:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Class information (for example, <emphasis remap='I'>superclass</emphasis>, <emphasis remap='I'>class_name</emphasis>,
+<emphasis remap='I'>widget_size</emphasis>,
+<emphasis remap='I'>class_initialize</emphasis>, and <emphasis remap='I'>class_inited</emphasis>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Data constants (for example, <emphasis remap='I'>resources</emphasis> and <emphasis remap='I'>num_resources</emphasis>,
+<emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis>, <emphasis remap='I'>visible_interest</emphasis>,
+<emphasis remap='I'>compress_motion</emphasis>,
+<emphasis remap='I'>compress_exposure</emphasis>, and <emphasis remap='I'>version</emphasis>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Widget operations (for example, <emphasis remap='I'>initialize</emphasis>, <emphasis remap='I'>realize</emphasis>, <emphasis remap='I'>destroy</emphasis>,
+<emphasis remap='I'>resize</emphasis>, <emphasis remap='I'>expose</emphasis>, <emphasis remap='I'>set_values</emphasis>, <emphasis remap='I'>accept_focus</emphasis>,
+and any new operations specific to
+the widget).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The <emphasis remap='I'>superclass</emphasis> field points to the superclass
+global class
+record, declared in the superclass private .h file.
+For direct subclasses of the generic core widget,
+<emphasis remap='I'>superclass</emphasis> should be initialized to the address of the
+<function>widgetClassRec</function>
+structure.
+The superclass is used for class chaining operations and for
+inheriting or enveloping a superclass's operations
+(see <xref linkend='Superclass_Chaining' />,
+<xref linkend='Initializing_a_Widget_Class' />, and
+<xref linkend='Inheritance_of_Superclass_Operations' />.
+</para>
+
+<para>
+The <emphasis remap='I'>class_name</emphasis> 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.
+</para>
+
+<para>
+The <emphasis remap='I'>widget_size</emphasis> field is the size of the corresponding widget
+instance structure
+(not the size of the class structure).
+</para>
+
+<para>
+The <emphasis remap='I'>version</emphasis> field indicates the toolkit
+implementation version number and is used for
+runtime consistency checking of the X Toolkit and widgets in an application.
+Widget writers must set it to the
+implementation-defined symbolic value
+<function>XtVersion</function>
+in the widget class structure initialization.
+Those widget writers who believe that their widget binaries are compatible
+with other implementations of the Intrinsics can put the special value
+<function>XtVersionDontCheck</function>
+in the <emphasis remap='I'>version</emphasis> field to disable version checking for those widgets.
+If a widget needs to compile alternative code for different
+revisions of the Intrinsics interface definition, it may use the symbol
+<function>XtSpecificationRelease</function>,
+as described in <xref linkend='Evolution_of_the_Intrinsics' />.
+Use of
+<function>XtVersion</function>
+allows the Intrinsics implementation to recognize widget binaries
+that were compiled with older implementations.
+</para>
+
+<para>
+The <emphasis remap='I'>extension</emphasis> 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.
+</para>
+
+<para>
+All other fields are described in their respective sections.
+</para>
+
+<para>
+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 <xref linkend='Resource_Management' />.
+</para>
+<literallayout>
+/* 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();
+ .
+ .
+ .
+</literallayout>
+<literallayout>
+/* Class record constant */
+LabelClassRec labelClassRec = {
+ {
+ /* core_class fields */
+ /* superclass */ (WidgetClass)&amp;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) &amp;labelClassRec;
+/* New method access routines */
+void LabelSetText(w, text)
+ Widget w;
+ String text;
+{
+ LabelWidgetClass lwc = (Label WidgetClass)XtClass(w);
+ XtCheckSubclass(w, labelWidgetClass, NULL);
+ *(lwc-&gt;label_class.set_text)(w, text)
+}
+/* Private procedures */
+ .
+ .
+ .
+</literallayout>
+</sect2>
+
+<sect2 id="Widget_Class_and_Superclass_Look_Up">
+<title>Widget Class and Superclass Look Up</title>
+<para>
+To obtain the class of a widget, use
+<xref linkend='XtClass' xrefstyle='select: title'/>.
+</para>
+
+
+
+<funcsynopsis id='XtClass'>
+ <funcprototype>
+ <funcdef>WidgetClass <function>XtClass</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<xref linkend='XtClass' xrefstyle='select: title'/>
+function returns a pointer to the widget's class structure.
+</para>
+
+<para>
+To obtain the superclass of a widget, use
+<function>XtSuperclass</function>.
+</para>
+
+<!--
+-->
+<funcsynopsis id='XtSuperClass'>
+<funcprototype>
+ <funcdef>WidgetClass <function>XtSuperClass</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<!--
+-->
+
+<para>
+The
+<function>XtSuperclass</function>
+function returns a pointer to the widget's superclass class structure.
+</para>
+</sect2>
+
+<sect2 id="Widget_Subclass_Verification">
+<title>Widget Subclass Verification</title>
+<para>
+To check the subclass to which a widget belongs, use
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtIsSubclass'>
+<funcprototype>
+ <funcdef>Boolean <function>XtIsSubclass</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class for which to test. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
+function returns
+<function>True</function>
+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
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
+to find out if a widget belongs to the desired class of objects.
+</para>
+
+<para>
+To test if a given widget belongs to a subclass of an Intrinsics-defined
+class, the Intrinsics define macros or functions equivalent to
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
+for each of the built-in classes. These procedures are
+<function>XtIsObject</function>,
+<function>XtIsRectObj</function>,
+<function>XtIsWidget</function>,
+<function>XtIsComposite</function>,
+<function>XtIsConstraint</function>,
+<function>XtIsShell</function>,
+<function>XtIsOverrideShell</function>,
+<function>XtIsWMShell</function>,
+<function>XtIsVendorShell</function>,
+<function>XtIsTransientShell</function>,
+<function>XtIsTopLevelShell</function>,
+<function>XtIsApplicationShell</function>,
+and
+<function>XtIsSessionShell</function>.
+</para>
+
+<para>
+All these macros and functions have the same argument description.
+</para>
+
+<funcsynopsis id='XtIs'>
+<funcprototype>
+ <funcdef>Boolean <function>XtIs</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+These procedures may be faster than calling
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
+directly for the built-in classes.
+</para>
+
+<para>
+To check a widget's class
+and to generate a debugging error message, use
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
+defined in
+<function>&lt;X11/IntrinsicP.h&gt;</function>:
+</para>
+
+<funcsynopsis id='XtCheckSubclass'>
+<funcprototype>
+ <funcdef>void <function>XtCheckSubclass</function></funcdef>
+ <paramdef>Widget<parameter> w</parameter></paramdef>
+ <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
+ <paramdef>String<parameter> message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class for which to test. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the message to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
+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,
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
+constructs an error message from the supplied message,
+the widget's actual class, and the expected class and calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+
+<sect2 id="Superclass_Chaining">
+<title>Superclass Chaining</title>
+<para>
+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 Intrinsics 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</para>
+<literallayout>
+In all widget classes: <emphasis remap='I'>class_name</emphasis>
+ <emphasis remap='I'>class_initialize</emphasis>
+ <emphasis remap='I'>widget_size</emphasis>
+ <emphasis remap='I'>realize</emphasis>
+ <emphasis remap='I'>visible_interest</emphasis>
+ <emphasis remap='I'>resize</emphasis>
+ <emphasis remap='I'>expose</emphasis>
+ <emphasis remap='I'>accept_focus</emphasis>
+ <emphasis remap='I'>compress_motion</emphasis>
+ <emphasis remap='I'>compress_exposure</emphasis>
+ <emphasis remap='I'>compress_enterleave</emphasis>
+ <emphasis remap='I'>set_values_almost</emphasis>
+ <emphasis remap='I'>tm_table</emphasis>
+ <emphasis remap='I'>version</emphasis>
+ <emphasis remap='I'>allocate</emphasis>
+ <emphasis remap='I'>deallocate</emphasis>
+
+In Composite widget classes: <emphasis remap='I'>geometry_manager</emphasis>
+ <emphasis remap='I'>change_managed</emphasis>
+ <emphasis remap='I'>insert_child</emphasis>
+ <emphasis remap='I'>delete_child</emphasis>
+ <emphasis remap='I'>accepts_objects</emphasis>
+ <emphasis remap='I'>allows_change_managed_set</emphasis>
+
+In Constraint widget classes: <emphasis remap='I'>constraint_size</emphasis>
+
+In Shell widget classes: <emphasis remap='I'>root_geometry_manager</emphasis>
+</literallayout>
+
+<para>
+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
+</para>
+<literallayout>
+ <emphasis remap='I'>class_part_initialize</emphasis>
+ <emphasis remap='I'>get_values_hook</emphasis>
+ <emphasis remap='I'>initialize</emphasis>
+ <emphasis remap='I'>initialize_hook</emphasis>
+ <emphasis remap='I'>set_values</emphasis>
+ <emphasis remap='I'>set_values_hook</emphasis>
+ <emphasis remap='I'>resources</emphasis>
+</literallayout>
+
+<para>
+In addition, for subclasses of
+Constraint,
+the following fields of the
+<function>ConstraintClassPart</function>
+and
+<function>ConstraintClassExtensionRec</function>
+structures are chained from the
+Constraint
+class down to the subclass:
+</para>
+<literallayout>
+ <emphasis remap='I'>resources</emphasis>
+ <emphasis remap='I'>initialize</emphasis>
+ <emphasis remap='I'>set_values</emphasis>
+ <emphasis remap='I'>get_values_hook</emphasis>
+</literallayout>
+
+<para>
+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
+</para>
+<literallayout>
+ <emphasis remap='I'>destroy</emphasis>
+ <emphasis remap='I'>actions</emphasis>
+</literallayout>
+
+<para>
+For subclasses of
+Constraint,
+the following field of
+<function>ConstraintClassPart</function>
+is chained from the subclass up to the
+Constraint class:
+ <emphasis remap='I'>destroy</emphasis>
+</para>
+</sect2>
+
+<sect2 id="Class_Initialization_class_initialize_and_class_part_initialize_Procedures">
+<title>Class Initialization: class_initialize and class_part_initialize Procedures</title>
+<para>
+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.
+</para>
+
+<para>
+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 Intrinsics.
+A class initialization procedure pointer is of type
+<function>XtProc</function>:
+</para>
+
+<para>
+typedef void (*XtProc)(void);
+</para>
+<para>
+A widget class indicates that it has no class initialization procedure by
+specifying NULL in the <emphasis remap='I'>class_initialize</emphasis> field.
+</para>
+
+<para>
+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 <emphasis remap='I'>class_part_initialize</emphasis> field.
+The class_part_initialize procedure pointer is of type
+<function>XtWidgetClassProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>(*XtWidgetClassProc)(WidgetClass)</function></funcdef>
+ <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Points to the class structure for the class being initialized.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+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 <xref linkend='Initializing_a_Widget_Class' />
+Classes that do not define any new class fields
+or that need no extra processing for them can specify NULL
+in the <emphasis remap='I'>class_part_initialize</emphasis> field.
+</para>
+
+<para>
+All widget classes, whether they have a class initialization procedure or not,
+must start with their <emphasis remap='I'>class_inited</emphasis> field
+<function>False</function>.
+</para>
+
+<para>
+The first time a widget of a class is created,
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+ensures that the widget class and all superclasses are initialized, in
+superclass-to-subclass order, by checking each <emphasis remap='I'>class_inited</emphasis> field and,
+if it is
+<function>False</function>,
+by calling the class_initialize and the class_part_initialize procedures
+for the class and all its superclasses.
+The Intrinsics then set the <emphasis remap='I'>class_inited</emphasis> field to a nonzero value.
+After the one-time initialization,
+a class structure is constant.
+</para>
+
+<para>
+The following example provides the class initialization procedure for a Label class.
+</para>
+<literallayout>
+static void ClassInitialize()
+{
+ XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
+ NULL, 0, XtCacheNone, NULL);
+}
+</literallayout>
+</sect2>
+
+<sect2 id="Initializing_a_Widget_Class">
+<title>Initializing a Widget Class</title>
+<para>
+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
+<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInitializeWidgetClass'>
+<funcprototype>
+ <funcdef>void <function>XtInitializeWidgetClass</function></funcdef>
+ <paramdef>WidgetClass<parameter> object_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object class to initialize. May be
+<function>objectClass</function>
+or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the specified widget class is already initialized,
+<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>
+returns immediately.
+</para>
+
+<para>
+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
+<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>
+is called
+(see <xref linkend='Resource_Conversions' />).
+</para>
+</sect2>
+
+<sect2 id="Inheritance_of_Superclass_Operations">
+<title>Inheritance of Superclass Operations</title>
+<para>
+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
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+expose
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+realize
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+insert_child
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+delete_child
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+geometry_manager
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+set_values_almost
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+To inherit an operation <emphasis remap='I'>xyz</emphasis>,
+specify the constant
+<function>XtInherit</function> <emphasis remap='I'>Xyz</emphasis>
+in your class record.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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 Intrinsics internal value
+<function>_XtInherit</function>
+cast to the appropriate type.
+<function>_XtInherit</function>
+is a procedure that issues an error message if it is actually called.
+</para>
+
+<para>
+For example,
+<function>CompositeP.h</function>
+contains these definitions:
+</para>
+<literallayout>
+#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
+#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
+#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
+#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit)
+</literallayout>
+<para>
+Composite's class_part_initialize procedure begins as follows:
+</para>
+<literallayout>
+static void CompositeClassPartInitialize(widgetClass)
+ WidgetClass widgetClass;
+{
+ CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass;
+ CompositeWidgetClass super = (CompositeWidgetClass)wc-&gt;core_class.superclass;
+ if (wc-&gt;composite_class.geometry_manager == XtInheritGeometryManager) {
+ wc-&gt;composite_class.geometry_manager = super-&gt;composite_class.geometry_manager;
+ }
+ if (wc-&gt;composite_class.change_managed == XtInheritChangeManaged) {
+ wc-&gt;composite_class.change_managed = super-&gt;composite_class.change_managed;
+ }
+ .
+ .
+ .
+</literallayout>
+<para>
+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:
+</para>
+
+<para>
+For Object:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<function>XtInheritAllocate</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritDeallocate</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+For Core:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<function>XtInheritRealize</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritResize</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritExpose</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritSetValuesAlmost</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritAcceptFocus</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritQueryGeometry</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritTranslations</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritDisplayAccelerator</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+For Composite:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<function>XtInheritGeometryManager</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritChangeManaged</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritInsertChild</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtInheritDeleteChild</function>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+For Shell:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<function>XtInheritRootGeometryManager</function>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="Invocation_of_Superclass_Operations">
+<title>Invocation of Superclass Operations</title>
+<para>
+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 <emphasis remap='I'>expose</emphasis>
+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 <emphasis remap='I'>insert_child</emphasis>
+and then calling
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+to add the child to the managed set.
+</para>
+
+<note>
+<para>
+A class method should not use
+<function>XtSuperclass</function>
+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.
+</para>
+</note>
+<para>
+This technique is referred to as <emphasis remap='I'>enveloping</emphasis> the superclass's operation.
+</para>
+</sect2>
+
+<sect2 id="Class_Extension_Records">
+<title>Class Extension Records</title>
+<para>
+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.
+</para>
+
+<para>
+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
+<emphasis remap='I'>extension</emphasis> pointer for the appropriate part in their class structure to
+point to a statically declared extension record containing the
+additional fields.
+Setting the <emphasis remap='I'>extension</emphasis> field is never mandatory; code that uses fields
+in the extension record must always check the <emphasis remap='I'>extension</emphasis> field and take
+some appropriate default action if it is NULL.
+</para>
+
+<para>
+In order to permit multiple subclasses and libraries to chain extension
+records from a single <emphasis remap='I'>extension</emphasis> 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:
+</para>
+<literallayout>
+struct {
+ XtPointer next_extension;
+ XrmQuark record_type;
+ long version;
+ Cardinal record_size;
+};
+</literallayout>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>next_extension</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the next record in the list, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>record_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular structure declaration to which
+each extension record instance conforms.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>version</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a version id symbolic constant supplied by
+the definer of the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>record_size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the total number of bytes allocated for the
+extension record.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>record_type</emphasis> 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
+<emphasis remap='I'>record_type</emphasis> field is normally assigned the
+result of
+<function>XrmStringToQuark</function>
+for a registered string constant. The
+Intrinsics reserve all record type strings beginning with the two
+characters ``XT'' for future standard uses. The value
+<emphasis role='strong'>NULLQUARK</emphasis>
+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.
+</para>
+
+<para>
+The <emphasis remap='I'>version</emphasis> 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 <emphasis remap='I'>record_size</emphasis> field value includes the four common header fields and
+should normally be initialized with
+<function>sizeof ().</function>
+</para>
+
+<para>
+Any value stored in the class part extension fields of
+<function>CompositeClassPart</function>,
+<function>ConstraintClassPart</function>,
+or
+<function>ShellClassPart</function>
+must point to an extension record conforming to this definition.
+</para>
+
+<para>
+The Intrinsics 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 <emphasis remap='I'>extension</emphasis> field in the class record.
+</para>
+
+<para>
+To locate a class extension record, use
+<xref linkend='XtGetClassExtension' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetClassExtension'>
+<funcprototype>
+ <funcdef>XtPointer <function>XtGetClassExtension</function></funcdef>
+ <paramdef>WidgetClass<parameter> object_class</parameter></paramdef>
+ <paramdef>Cardinal<parameter> byte_offset</parameter></paramdef>
+ <paramdef>XrmQuark<parameter> type</parameter></paramdef>
+ <paramdef>long<parameter> version</parameter></paramdef>
+ <paramdef>Cardinal<parameter> record_size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object class containing the extension list to be searched.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>byte_offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset in bytes from the base of the
+class record of the extension field to be searched.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the record_type of the class extension to be located.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>version</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the minimum acceptable version of the class
+extension required for a match.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>record_size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the minimum acceptable length of the class
+extension record required for a match, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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.
+<xref linkend='XtGetClassExtension' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/specs/CH02.xml b/specs/CH02.xml
new file mode 100644
index 0000000..9cfd447
--- /dev/null
+++ b/specs/CH02.xml
@@ -0,0 +1,4538 @@
+<chapter id='Widget_Instantiation'>
+<title>Widget Instantiation</title>
+<para>
+A hierarchy of widget instances constitutes a widget tree.
+The shell widget returned by
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+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 <xref linkend='Pop_Up_Widgets' />),
+this widget tree instance defines the associated X Window tree.
+</para>
+
+<para>
+Widgets can be either composite or primitive.
+Both kinds of widgets can contain children,
+but the Intrinsics provide a set of management mechanisms for constructing
+and interfacing between composite widgets, their children, and
+other clients.
+</para>
+
+<para>
+Composite widgets, that is, members of the class
+<function>compositeWidgetClass</function>,
+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.
+</para>
+
+<para>
+In addition,
+the Intrinsics 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.
+</para>
+
+<para>
+A widget tree is manipulated by several Intrinsics functions.
+For example,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+traverses the tree downward and recursively realizes all
+pop-up widgets and children of composite widgets.
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+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.
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+traverses the tree up one level and calls the geometry manager
+that is responsible for a widget child's geometry.
+</para>
+
+<para>
+To facilitate upward traversal of the widget tree,
+each widget has a pointer to its parent widget.
+The
+Shell
+widget that
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+returns has a <emphasis remap='I'>parent</emphasis> pointer of NULL.
+</para>
+
+<para>
+To facilitate downward traversal of the widget tree,
+the <emphasis remap='I'>children</emphasis> 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.
+</para>
+
+<sect1 id="Initializing_the_tk">
+<title>Initializing the X Toolkit</title>
+<para>
+Before an application can call any Intrinsics function
+other than
+<function>XtSetLanguageProc</function>
+and
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>,
+it must initialize the Intrinsics by using
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
+which initializes the Intrinsics internals
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+which initializes the per-application state
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+or
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
+which initializes the per-display state
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+which creates the root of a widget tree
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Or an application can call the convenience procedure
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+which combines the functions of the preceding procedures.
+An application wishing to use the ANSI C locale mechanism should call
+<function>XtSetLanguageProc</function>
+prior to calling
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+or
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Multiple instances of X Toolkit 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.
+To accommodate both requirements,
+the Intrinsics 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
+<function>Display</function>
+pointers for that application.
+The Intrinsics handle all display connections within a single application
+context simultaneously, handling input in a round-robin fashion.
+The application context type
+<function>XtAppContext</function>
+is opaque to clients.
+</para>
+
+<para>
+To initialize the Intrinsics internals, use
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtToolkitInitialize'>
+<funcprototype>
+ <funcdef>void <function>XtToolkitInitialize</function></funcdef>
+ <paramdef> <parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+was previously called, it returns immediately.
+When
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
+is called before
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
+the latter is protected against
+simultaneous activation by multiple threads.
+</para>
+
+<para>
+To create an application context, use
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateApplicationContext'>
+<funcprototype>
+ <funcdef>XtAppContext <function>XtCreateApplicationContext</function></funcdef>
+ <paramdef> <parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para>
+The
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>
+function returns an application context,
+which is an opaque type.
+Every application must have at least one application context.
+</para>
+
+<para>
+To destroy an application context and close any
+remaining display connections in it, use
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDestroyApplicationContext'>
+<funcprototype>
+ <funcdef>void <function>XtDestroyApplicationContext</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+function destroys the specified application context.
+If called from within an event dispatch (for example, in a callback procedure),
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+does not destroy the application context until the dispatch is complete.
+</para>
+
+<para>
+To get the application context in which a given widget was created, use
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWidgetToApplicationContext'>
+<funcprototype>
+ <funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
+function returns the application context for the specified widget.
+</para>
+
+<para>
+To initialize a display and add it to an application context, use
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDisplayInitialize'>
+<funcprototype>
+ <funcdef>void <function>XtDisplayInitialize</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>application_name</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc</parameter></paramdef>
+ <paramdef>String * <parameter>argv</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a previously opened display connection. Note that a single
+display connection can be in at most one application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the application instance.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to parse the command line for any application-specific resources.
+The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to
+<function>XrmParseCommand</function>.
+For further information,
+see <olink targetdoc='libX11' targetptr='Parsing_Command_Line_Options'>Parsing Command Line Options</olink> in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink> and <xref linkend='Parsing_the_Command_Line' /> of this specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the options list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+function retrieves the language string to be
+used for the specified display (see <xref linkend='Finding_File_Names' />),
+calls the language procedure (if set) with that language string,
+builds the resource database for the default screen, calls the Xlib
+<function>XrmParseCommand</function>
+function to parse the command line,
+and performs other per-display initialization.
+After
+<function>XrmParseCommand</function>
+has been called,
+<emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> contain only those parameters that
+were not in the standard option table or in the table specified by the
+<emphasis remap='I'>options</emphasis> argument.
+If the modified <emphasis remap='I'>argc</emphasis> is not zero,
+most applications simply print out the modified <emphasis remap='I'>argv</emphasis> along with a message
+listing the allowable options.
+On POSIX-based systems,
+the application name is usually the final component of <emphasis remap='I'>argv</emphasis>[0].
+If the synchronous resource is
+<function>True</function>,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+calls the Xlib
+<function>XSynchronize</function>
+function to put Xlib into synchronous mode for this display connection
+and any others currently open in the application context.
+See <xref linkend='Loading_the_Resource_Database' />
+and <xref linkend='Parsing_the_Command_Line' />
+for details on the <emphasis remap='I'>application_name</emphasis>,
+<emphasis remap='I'>application_class</emphasis>, <emphasis remap='I'>options</emphasis>, and <emphasis remap='I'>num_options</emphasis> arguments.
+</para>
+
+<para>
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+calls
+<function>XrmSetDatabase</function>
+to associate the resource database of the default screen with the
+display before returning.
+</para>
+
+<para>
+To open a display, initialize it, and then
+add it to an application context, use
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOpenDisplay'>
+<funcprototype>
+ <funcdef>Display <function>*XtOpenDisplay</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>display_string</parameter></paramdef>
+ <paramdef>String <parameter>application_name</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc</parameter></paramdef>
+ <paramdef>String * <parameter>argv</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display string, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the application instance, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to parse the command line for any application-specific resources.
+The options argument is passed as a parameter to
+<function>XrmParseCommand</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the options list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+function calls
+<function>XOpenDisplay</function>
+with the specified <emphasis remap='I'>display_string</emphasis>.
+If <emphasis remap='I'>display_string</emphasis> is NULL,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+uses the current value of the \-display option specified in <emphasis remap='I'>argv</emphasis>.
+If no display is specified in <emphasis remap='I'>argv</emphasis>,
+the user's default display is retrieved from the environment.
+On POSIX-based systems,
+this is the value of the
+<emphasis role='strong'>DISPLAY</emphasis>
+environment variable.
+</para>
+
+<para>
+If this succeeds,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+then calls
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+and passes it the opened display and
+the value of the \-name option specified in <emphasis remap='I'>argv</emphasis> as the application name.
+If no \-name option is specified
+and <emphasis remap='I'>application_name</emphasis> is
+non-NULL, <emphasis remap='I'>application_name</emphasis> is passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+If <emphasis remap='I'>application_name</emphasis> is NULL and if the environment variable
+<emphasis role='strong'>RESOURCE_NAME</emphasis>
+is set, the value of
+<emphasis role='strong'>RESOURCE_NAME</emphasis>
+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 <emphasis remap='I'>argv</emphasis>[0] less any directory and file type components, that is, the
+final component of <emphasis remap='I'>argv</emphasis>[0], if specified. If <emphasis remap='I'>argv</emphasis>[0] does not exist or
+is the empty string, the application name is ``main''.
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+returns the newly opened display or NULL if it failed.
+</para>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+
+<para>
+To close a display and remove it from an application context, use
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCloseDisplay'>
+<funcprototype>
+ <funcdef>void <function>XtCloseDisplay</function></funcdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+function calls
+<function>XCloseDisplay</function>
+with the specified <emphasis remap='I'>display</emphasis> as soon as it is safe to do so.
+If called from within an event dispatch (for example, a callback procedure),
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+does not close the display until the dispatch is complete.
+Note that applications need only call
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+if they are to continue executing after closing the display;
+otherwise, they should call
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+</sect1>
+
+<sect1 id="Establishing_the_Locale">
+<title>Establishing the Locale</title>
+<para>
+Resource databases are specified to be created in the current process
+locale. During display initialization prior to creating the
+per-screen resource database, the Intrinsics 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.
+</para>
+
+<para>
+The callout procedure provided by the application is of type
+<function>XtLanguageProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef String <function>(*XtLanguageProc)</function></funcdef>
+ <paramdef>Display <parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>language</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>language</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the initial language value obtained from the command line
+or server per-display resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the additional client data specified in the call to
+<function>XtSetLanguageProc</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+The language procedure allows an application to set the locale to
+the value of the language resource determined by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+The function returns a new language string that
+will be subsequently used by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+to establish the path for loading resource files. The returned
+string will be copied by the Intrinsics into new memory.
+</para>
+
+<para>
+Initially, no language procedure is set by the Intrinsics.
+To set the language procedure for use by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+use
+<function>XtSetLanguageProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XtLanguageProc <function>XtSetLanguageProc</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtLanguageProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context in which the language procedure is
+to be used, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the language procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional client data to be passed to the language
+procedure when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XtSetLanguageProc</function>
+sets the language procedure that will be called from
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for all subsequent Displays initialized in the specified application
+context. If <emphasis remap='I'>app_context</emphasis> 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 <emphasis remap='I'>proc</emphasis> is NULL, a default language procedure is
+registered.
+<function>XtSetLanguageProc</function>
+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
+<function>XtSetLanguageProc</function>,
+it will cause the default language procedure to be registered.
+</para>
+
+<para>
+The default language procedure does the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Sets the locale according to the environment. On ANSI C-based
+systems this is done by calling
+<function>setlocale</function>(
+<function>LC_ALL</function>,
+<emphasis remap='I'>language</emphasis> ).
+If an error is encountered, a warning message is issued with
+<xref linkend='XtWarning' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XSupportsLocale</function>
+to verify that the current locale is supported.
+If the locale is not supported, a warning message is issued with
+<xref linkend='XtWarning' xrefstyle='select: title'/>
+and the locale is set to ``C''.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XSetLocaleModifiers</function>
+specifying the empty string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Returns the value of the current locale. On ANSI C-based systems this
+is the return value from a final call to
+<function>setlocale</function>(
+<function>LC_ALL</function>,
+NULL ).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+A client wishing to use this mechanism to establish locale can do so
+by calling
+<function>XtSetLanguageProc</function>
+prior to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+as in the following example.
+</para>
+<literallayout>
+ Widget top;
+ XtSetLanguageProc(NULL, NULL, NULL);
+ top = XtOpenApplication(...);
+ ...
+</literallayout>
+</sect1>
+
+<sect1 id="Loading_the_Resource_Database">
+<title>Loading the Resource Database</title>
+<para>
+The
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+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:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Application command line (<emphasis remap='I'>argc</emphasis>, <emphasis remap='I'>argv</emphasis>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Per-host user environment resource file on the local host.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Per-screen resource specifications from the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Per-display resource specifications from the server or from
+the user preference file on the local host.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Application-specific user resource file on the local host.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Application-specific class resource file on the local host.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+When the resource database for a particular screen on the display
+is needed (either internally, or when
+<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
+is called),
+it is created in the following manner using the sources listed
+above in the same order:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A temporary database, the ``server resource database'', is
+created from the string returned by
+<function>XResourceManagerString</function>
+or, if
+<function>XResourceManagerString</function>
+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/<function>.Xdefaults</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a language procedure has been set,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+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,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+queries the server resource database (which is assumed to be entirely
+in XPCS) for the resource
+<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
+where <emphasis remap='I'>name</emphasis>
+and <emphasis remap='I'>Class</emphasis> are the <emphasis remap='I'>application_name</emphasis> and
+<emphasis remap='I'>application_class</emphasis> specified to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+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 Intrinsics that require the per-display language string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The screen resource database is initialized by parsing the command
+line in the manner specified by Section 2.4.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a language procedure has not been set,
+the initial database is then queried for the resource
+<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
+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
+<emphasis role='strong'>LANG</emphasis>
+environment variable. If no language string is
+found, the empty string is used.
+This language string is saved for all future references in the Intrinsics
+that require the per-display language string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<emphasis role='strong'>XENVIRONMENT</emphasis>
+environment variable.
+If this environment variable does not exist, the user's home directory
+is searched for a file named
+<function>.Xdefaults-</function><emphasis>host</emphasis>,
+where <emphasis remap='I'>host</emphasis> is the host name of the machine on which the
+application is running.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The per-screen resource specifications are then merged into the screen
+resource database, if they exist. These specifications are the string
+returned by
+<function>XScreenResourceString</function>
+for the respective screen and are owned entirely by the user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<function>XrmSetDatabase</function>
+with the current screen resource database, after preserving the
+original display-associated database, then calling
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+with the parameters
+(<emphasis remap='I'>display</emphasis>, NULL, NULL, NULL, <emphasis remap='I'>path</emphasis>, NULL, 0, NULL),
+where <emphasis remap='I'>path</emphasis> is defined in an operating-system-specific way.
+On POSIX-based systems, <emphasis remap='I'>path</emphasis> is defined to be the value
+of the environment variable
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+if this is defined. If
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+is not defined, an implementation-dependent default value is used.
+This default value is constrained in the following manner:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the environment variable
+<emphasis role='strong'>XAPPLRESDIR</emphasis>
+is not defined, the default
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+must contain at least six entries. These entries must contain
+$HOME as the directory prefix, plus the following substitutions:
+ </para>
+<literallayout>
+ 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
+</literallayout>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para> If
+<emphasis role='strong'>XAPPLRESDIR</emphasis>
+is defined, the default
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+must contain at least seven entries. These entries must contain the
+following directory prefixes and substitutions:
+ </para>
+<literallayout>
+ 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
+</literallayout>
+ <para>
+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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+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
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+with the parameters
+(<emphasis remap='I'>display</emphasis>, ``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
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
+Note that the customization substitution string is retrieved
+dynamically by
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+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
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>,
+the original display-associated database is restored.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+To obtain the resource database for a particular screen, use
+<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtScreenDatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XtScreenDatabase</function></funcdef>
+ <paramdef>Screen * <parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen whose resource database is to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
+function returns the fully merged resource database as specified above,
+associated with the specified screen. If the specified <emphasis remap='I'>screen</emphasis>
+does not belong to a
+<function>Display</function>
+initialized by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+the results are undefined.
+</para>
+
+<para>
+To obtain the default resource database associated with a particular display, use
+<xref linkend='XtDatabase' xrefstyle='select: title'/>.
+</para>
+
+
+<funcsynopsis id='XtDatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XtDatabase</function></funcdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDatabase' xrefstyle='select: title'/>
+function is equivalent to
+<function>XrmGetDatabase</function>.
+It returns the database associated with the specified display, or
+NULL if a database has not been set.
+</para>
+
+<para>
+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
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetFallbackResources'>
+<funcprototype>
+ <funcdef>void <function>XtAppSetFallbackResources</function></funcdef>
+ <paramdef>XtAppContext * <parameter>app_context</parameter></paramdef>
+ <paramdef>String * <parameter>specification_list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context in which
+the fallback specifications will be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>specification_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a NULL-terminated list of
+resource specifications to preload
+the database, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Each entry in <emphasis remap='I'>specification_list</emphasis> points to a string in the format of
+<function>XrmPutLineResource</function>.
+Following a call to
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>,
+when a resource database is being created for a particular screen and
+the Intrinsics are not able
+to find or read an application-specific class resource file according to the
+rules given above and if <emphasis remap='I'>specification_list</emphasis> is not NULL, the
+resource specifications in <emphasis remap='I'>specification_list</emphasis> will be merged
+into the screen resource database in place of the application-specific
+class resource file.
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is not
+required to copy <emphasis remap='I'>specification_list</emphasis>; 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
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is called again. The value NULL for
+<emphasis remap='I'>specification_list</emphasis> 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.
+</para>
+</sect1>
+
+<sect1 id="Parsing_the_Command_Line">
+<title>Parsing the Command Line</title>
+<para>
+The
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+function first parses the command line for the following options:
+<variablelist>
+ <varlistentry>
+ <term>-display</term>
+ <listitem>
+ <para>
+Specifies the display name for
+<function>XOpenDisplay</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-name</term>
+ <listitem>
+ <para>
+Sets the resource name prefix,
+which overrides the application name passed to
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-xnllanguage</term>
+ <listitem>
+ <para>
+Specifies the initial language string for establishing locale
+and for finding application class resource files.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+has a table of standard command line options that are passed to
+<function>XrmParseCommand</function>
+for adding resources to the resource database,
+and it takes as a parameter additional
+application-specific resource abbreviations.
+The format of this table is described in Section 15.9 in <emphasis remap='I'>Xlib — C Language X Interface</emphasis>.
+</para>
+<literallayout>
+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;
+</literallayout>
+<para>The standard table contains the following entries:</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='4' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <colspec colwidth='1.0*' colname='c4'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Option String</entry>
+ <entry>Resource Name</entry>
+ <entry>Argument Kind</entry>
+ <entry>Resource Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>−background</entry>
+ <entry>*background</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−bd</entry>
+ <entry>*borderColor</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−bg</entry>
+ <entry>*background</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−borderwidth</entry>
+ <entry>.borderWidth</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−bordercolor</entry>
+ <entry>*borderColor</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−bw</entry>
+ <entry>.borderWidth</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−display</entry>
+ <entry>.display</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−fg</entry>
+ <entry>*foreground</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−fn</entry>
+ <entry>*font</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−font</entry>
+ <entry>*font</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−foreground</entry>
+ <entry>*foreground</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−geometry</entry>
+ <entry>.geometry</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−iconic</entry>
+ <entry>.iconic</entry>
+ <entry>NoArg</entry>
+ <entry>"true"</entry>
+ </row>
+ <row>
+ <entry>−name</entry>
+ <entry>.name</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−reverse</entry>
+ <entry>.reverseVideo</entry>
+ <entry>NoArg</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>−rv</entry>
+ <entry>.reverseVideo</entry>
+ <entry>NoArg</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>+rv</entry>
+ <entry>.reverseVideo</entry>
+ <entry>NoArg</entry>
+ <entry>"off"</entry>
+ </row>
+ <row>
+ <entry>−selectionTimeout</entry>
+ <entry>.selectionTimeout</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−synchronous</entry>
+ <entry>.synchronous</entry>
+ <entry>NoArg</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>+synchronous</entry>
+ <entry>.synchronous</entry>
+ <entry>NoArg</entry>
+ <entry>"off"</entry>
+ </row>
+ <row>
+ <entry>−title</entry>
+ <entry>.title</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−xnllanguage</entry>
+ <entry>.xnlLanguage</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−xrm</entry>
+ <entry>next argument</entry>
+ <entry>ResArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>−xtsessionID</entry>
+ <entry>.sessionID</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+Note that any unique abbreviation for an option name in the standard table
+or in the application table is accepted.
+</para>
+
+<para>
+If reverseVideo is
+<function>True</function>,
+the values of
+<function>XtDefaultForeground</function>
+and
+<function>XtDefaultBackground</function>
+are exchanged for all screens on the Display.
+</para>
+
+<para>
+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,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+makes a call to
+<function>XSynchronize</function>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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
+<function>xmh</function>,
+you can start it up as
+</para>
+<literallayout>
+xmh -xrm 'xmh*Command.background: red'
+</literallayout>
+<para>
+When it parses the command line,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+merges the application option table with the standard option table
+before calling the Xlib
+<function>XrmParseCommand</function>
+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 Intrinsics reserve all option names
+beginning with the characters ``-xt'' for future standard uses.
+</para>
+</sect1>
+
+<sect1 id="Creating_Widgets">
+<title>Creating Widgets</title>
+<para>
+The creation of widget instances is a three-phase process:
+</para>
+
+<orderedlist>
+ <listitem>
+ <para>
+The widgets are allocated and initialized with resources
+and are optionally added to the managed subset of their parent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All composite widgets are notified of their managed children
+in a bottom-up traversal of the widget tree.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The widgets create X windows, which then are mapped.
+ </para>
+ </listitem>
+</orderedlist>
+<para>
+To start the first phase,
+the application calls
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+for all its widgets and adds some (usually, most or all) of its widgets
+to their respective parents' managed set by calling
+<xref linkend='XtManageChild' xrefstyle='select: title'/>.
+To avoid an O(n<superscript>2</superscript>) 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.
+</para>
+
+<para>
+After all widgets have been created,
+the application calls
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+with the top-level widget to execute the second and third phases.
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+Finally,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<sect2 id="Creating_and_Merging_Argument_Lists">
+<title>Creating and Merging Argument Lists</title>
+<para>
+Many Intrinsics functions may be passed pairs of resource names and
+values.
+These are passed as an arglist, a pointer to an array of
+<function>Arg</function>
+structures, which contains
+</para>
+<literallayout>
+typedef struct {
+ String name;
+ XtArgVal value;
+} Arg, *ArgList;
+</literallayout>
+<para>
+where
+<function>XtArgVal</function>
+is as defined in Section 1.5.
+</para>
+
+<para>
+If the size of the resource is less than or equal to the size of an
+<function>XtArgVal</function>,
+the resource value is stored directly in <emphasis remap='I'>value</emphasis>;
+otherwise, a pointer to it is stored in <emphasis remap='I'>value</emphasis>.
+</para>
+
+<para>
+To set values in an
+<function>ArgList</function>,
+use
+<xref linkend='XtSetArg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetArg'>
+<funcprototype>
+ <funcdef>void <function>XtSetArg</function></funcdef>
+ <paramdef>Arg <parameter>arg</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>XtArgVal <parameter>value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <emphasis remap='I'>name/value</emphasis> pair to set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource if it will fit in an
+<function>XtArgVal</function>,
+else the address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetArg' xrefstyle='select: title'/>
+function is usually used in a highly stylized manner to
+minimize the probability of making a mistake; for example:
+</para>
+<literallayout>
+Arg args[20];
+int n;
+n = 0;
+XtSetArg(args[n], XtNheight, 100); n++;
+XtSetArg(args[n], XtNwidth, 200); n++;
+XtSetValues(widget, args, n);
+</literallayout>
+<para>
+Alternatively, an application can statically declare the argument list
+and use
+<xref linkend='XtNumber' xrefstyle='select: title'/>:
+</para>
+<literallayout>
+static Args args[] = {
+ {XtNheight, (XtArgVal) 100},
+ {XtNwidth, (XtArgVal) 200},
+};
+XtSetValues(Widget, args, XtNumber(args));
+</literallayout>
+<para>
+Note that you should not use expressions with side effects such as
+auto-increment or auto-decrement
+within the first argument to
+<xref linkend='XtSetArg' xrefstyle='select: title'/>.
+<xref linkend='XtSetArg' xrefstyle='select: title'/>
+can be implemented as a macro that evaluates the first argument twice.
+</para>
+
+<para>
+To merge two
+arglist arrays, use
+<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMergeArgLists'>
+<funcprototype>
+ <funcdef>ArgList <function>XtMergeArgLists</function></funcdef>
+ <paramdef>ArgList <parameter>args1</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args1</parameter></paramdef>
+ <paramdef>ArgList <parameter>args2</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the first argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the second argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the second argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>
+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
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<para>
+All Intrinsics interfaces that require
+<function>ArgList</function>
+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
+<function>ArgList</function>
+procedure; e.g.,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
+Each procedure named <function>XtVa</function><emphasis remap='I'>something</emphasis> takes as its
+last arguments, in place of the corresponding
+<function>ArgList</function>/
+<function>Cardinal</function>
+parameters, a variable parameter list of resource name and
+value pairs where each name is of type
+<function>String</function>
+and each value is of type
+<function>XtArgVal</function>.
+The end of the list is identified by a <emphasis remap='I'>name</emphasis> 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
+<function>ArgList</function>
+and varargs forms interchangeably.
+</para>
+
+<para>
+Two special names are defined for use only in varargs lists:
+<function>XtVaTypedArg</function>
+and
+<function>XtVaNestedList</function>.
+</para>
+<literallayout>
+#define XtVaTypedArg "XtVaTypedArg"
+</literallayout>
+<para>
+If the name
+<function>XtVaTypedArg</function>
+is specified in place of a resource
+name, then the following four arguments are interpreted as a
+<emphasis remap='I'>name/type/value/size</emphasis> tuple <emphasis remap='I'>where</emphasis> name is of type
+<function>String</function>,
+<emphasis remap='I'>type</emphasis> is of type
+<function>String</function>,
+<emphasis remap='I'>value</emphasis> is of type
+<function>XtArgVal</function>,
+and <emphasis remap='I'>size</emphasis> is of type int. When a varargs list containing
+<function>XtVaTypedArg</function>
+is processed, a resource type
+conversion (see <xref linkend='Resource_Conversions' />) is performed if necessary to convert the
+value into the format required by the associated resource. If <emphasis remap='I'>type</emphasis> is
+XtRString, then <emphasis remap='I'>value</emphasis> contains a pointer to the string and <emphasis remap='I'>size</emphasis>
+contains the number of bytes allocated, including the trailing null
+byte. If <emphasis remap='I'>type</emphasis> is not XtRString, then <emphasis remap='I'>if</emphasis> size is
+less than or equal to
+<function>sizeof</function>(<function>XtArgVal</function>), the value should be the data cast to the type
+<function>XtArgVal</function>,
+otherwise <emphasis remap='I'>value</emphasis> 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.
+</para>
+<literallayout>
+#define XtVaNestedList "XtVaNestedList"
+</literallayout>
+<para>
+If the name
+<function>XtVaNestedList</function>
+is specified in place of a resource name,
+then the following argument is interpreted as an
+<function>XtVarArgsList</function>
+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.
+</para>
+
+<para>
+To dynamically allocate a varargs list for use with
+<function>XtVaNestedList</function>
+in multiple calls, use
+<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>.
+</para>
+<literallayout>
+typedef XtPointer XtVarArgsList;
+</literallayout>
+
+<funcsynopsis id='XtVaCreateArgsList'>
+<funcprototype>
+ <funcdef>XtVarArgsList <function>XtVaCreateArgsList</function></funcdef>
+ <paramdef>XtPointer <parameter>unused</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>unused</emphasis>
+ </term>
+ <listitem>
+ <para>
+This argument is not currently used and must be specified as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies a variable parameter list of resource
+name and value pairs.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>
+function allocates memory and copies its arguments into a
+single list pointer, which may be used with
+<function>XtVaNestedList</function>.
+The end of
+both lists is identified by a <emphasis remap='I'>name</emphasis> entry containing NULL. Any entries
+of type
+<function>XtVaTypedArg</function>
+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
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when no longer needed.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Creating_a_Widget_Instance">
+<title>Creating a Widget Instance</title>
+<para>
+To create an instance of a widget, use
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateWidget'>
+<funcprototype>
+ <funcdef>Widget <function>XtCreateWidget</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created object. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+function performs all the boilerplate operations of widget
+creation, doing the following in order:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified class is not
+<function>coreWidgetClass</function>
+or a subclass thereof,
+and the parent's class is a subclass of
+<function>compositeWidgetClass</function>
+and either no extension record in
+the parent's composite class part extension field exists with the
+<emphasis remap='I'>record_type</emphasis>
+<emphasis role='strong'>NULLQUARK</emphasis>
+or the <emphasis remap='I'>accepts_objects</emphasis> field in the extension
+record is
+<function>False</function>,
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+issues a fatal error; see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' /> and <xref linkend='Nonwidget_Objects' />.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified class contains an extension record in the object class
+part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>record_type</emphasis>
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>allocate</emphasis> field is not NULL,
+the procedure is invoked to allocate memory
+for the widget instance. If the parent is a member of the class
+<function>constraintWidgetClass</function>,
+the procedure also allocates memory for the
+parent's constraints and stores the address of this memory into the
+<emphasis remap='I'>constraints</emphasis> field. If no allocate procedure is found, the Intrinsics
+allocate memory for the widget and, when applicable, the constraints,
+and initializes the <emphasis remap='I'>constraints</emphasis> field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Initializes the Core nonresource data fields
+<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>being_destroyed</emphasis>,
+<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>managed</emphasis>, <emphasis remap='I'>window</emphasis>, <emphasis remap='I'>visible</emphasis>,
+<emphasis remap='I'>popup_list</emphasis>, and <emphasis remap='I'>num_popups</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Initializes the resource fields (for example, <emphasis remap='I'>background_pixel</emphasis>)
+by using the
+<function>CoreClassPart</function>
+resource lists specified for this class and all superclasses.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is a member of the class
+<function>constraintWidgetClass</function>,
+initializes the resource fields of the constraints record
+by using the
+<function>ConstraintClassPart</function>
+resource lists specified for the parent's class
+and all superclasses up to
+<function>constraintWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the initialize procedures for the widget starting at the
+Object
+initialize procedure on down to the widget's initialize procedure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is a member of the class
+<function>constraintWidgetClass</function>,
+calls the
+<function>ConstraintClassPart</function>
+initialize procedures,
+starting at
+<function>constraintWidgetClass</function>
+on down to the parent's
+<function>ConstraintClassPart</function>
+initialize procedure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is a member of the class
+<function>compositeWidgetClass</function>,
+puts the widget into its parent's children list by calling its parent's
+insert_child procedure.
+For further information,
+see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' />.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To create an instance of a widget using varargs lists, use
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaCreateWidget'>
+<funcprototype>
+ <funcdef>Widget <function>XtVaCreateWidget</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name for the created widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created object. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Creating_an_Application_Shell_Instance">
+<title>Creating an Application Shell Instance</title>
+<para>
+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
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+to create independent widget trees.
+</para>
+
+<funcsynopsis id='XtAppCreateShell'>
+<funcprototype>
+ <funcdef>Widget <function>XtAppCreateShell</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name of the shell widget.
+If <emphasis remap='I'>name</emphasis> is NULL,
+the application name passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class string to be used in
+place of the widget <emphasis remap='I'>class_name</emphasis> string when
+<emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class for the top-level widget (e.g.,
+<function>applicationShellWidgetClass ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+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
+<emphasis remap='I'>args</emphasis> 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 <emphasis remap='I'>name</emphasis>.screen,
+class <emphasis remap='I'>Class</emphasis>.Screen where <emphasis remap='I'>Class</emphasis> is the specified
+<emphasis remap='I'>application_class</emphasis> if <emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof. If <emphasis remap='I'>widget_class</emphasis> is not
+<function>application\%Shell\%Widget\%Class</function>
+or a subclass, <emphasis remap='I'>Class</emphasis> is the <emphasis remap='I'>class_name</emphasis>
+field from the
+<function>CoreClassPart</function>
+of the specified <emphasis remap='I'>widget_class</emphasis>.
+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
+<emphasis remap='I'>args</emphasis>. The widget name and <emphasis remap='I'>Class</emphasis> as determined above are
+used as the leftmost (i.e., root) components in all fully qualified
+resource names for objects within this widget tree.
+</para>
+
+<para>
+If the specified widget class is a subclass of WMShell, the name and
+<emphasis remap='I'>Class</emphasis> as determined above will be stored into the
+<emphasis role='strong'>WM_CLASS</emphasis>
+property on the widget's window when it becomes realized.
+If the specified <emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof, the
+<emphasis role='strong'>WM_COMMAND</emphasis>
+property will also be set from the values of the XtNargv and
+XtNargc resources.
+</para>
+
+<para>
+To create multiple top-level shells within a single (logical)
+application,
+you can use one of two methods:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Designate one shell as the real top-level shell and
+create the others as pop-up children of it by using
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Have all shells as pop-up children of an unrealized top-level shell.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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:
+</para>
+<literallayout>
+xmail.geometry:... (the main window)
+xmail.read.geometry:... (the read window)
+xmail.compose.geometry:... (the compose window)
+</literallayout>
+<para>
+The second method,
+which is best if there is no main window,
+leads to resource specifications like the following:
+</para>
+<literallayout>
+xmail.headers.geometry:... (the headers window)
+xmail.read.geometry:... (the read window)
+xmail.compose.geometry:... (the compose window)
+</literallayout>
+<para>
+To create a top-level widget that is the root of a widget tree using
+varargs lists, use
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaAppCreateShell'>
+<funcprototype>
+ <funcdef>Widget <function>XtVaAppCreateShell</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name of the shell widget.
+If <emphasis remap='I'>name</emphasis> is NULL,
+the application name passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class string to be used in
+place of the widget <emphasis remap='I'>class_name</emphasis> string when
+<emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class for the top-level widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Convenience_Procedure_to_Initialize_an_Application">
+<title>Convenience Procedure to Initialize an Application</title>
+<para>
+To initialize the Intrinsics internals, create an application context,
+open and initialize a display, and create the initial root shell
+instance, an application may use
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+or
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOpenApplication'>
+<funcprototype>
+ <funcdef>Widget <function>XtOpenApplication</function></funcdef>
+ <paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc_in_out</parameter></paramdef>
+ <paramdef>String * <parameter>argv_in_out</parameter></paramdef>
+ <paramdef>String * <parameter>fallback_resources</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line options table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the application class resource
+file cannot be opened or read, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the widget to be created. Must be shellWidgetClass
+or a subclass.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any
+other resource specifications for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+function calls
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+followed by
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+then calls
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+with <emphasis remap='I'>display_string</emphasis> NULL and
+<emphasis remap='I'>application_name</emphasis> NULL, and finally calls
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with <emphasis remap='I'>name</emphasis> NULL, the specified <emphasis remap='I'>widget_class</emphasis>,
+an argument list and count,
+and returns the created shell.
+The recommended <emphasis remap='I'>widget_class</emphasis> is
+<function>sessionShellWidgetClass</function>.
+The argument list and count are created by merging
+the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> with a list
+containing the specified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis>.
+The modified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> returned by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+are returned in <emphasis remap='I'>argc_in_out</emphasis> and <emphasis remap='I'>argv_in_out</emphasis>. If
+<emphasis remap='I'>app_context_return</emphasis> 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
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+terminates the application. If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL,
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is called with the value prior to calling
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaOpenApplication'>
+<funcprototype>
+ <funcdef>Widget <function>XtVaOpenApplication</function></funcdef>
+ <paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc_in_out</parameter></paramdef>
+ <paramdef>String * <parameter>argv_in_out</parameter></paramdef>
+ <paramdef>String * <parameter>fallback_resources</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line options table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line arguments array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the application class
+resource file cannot be opened, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the widget to be created. Must be shellWidgetClass
+or a subclass.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Widget_Instance_Allocation_The_allocate_Procedure">
+<title>Widget Instance Allocation: The allocate Procedure</title>
+<para>
+A widget class may optionally provide an instance allocation procedure
+in the
+<function>ObjectClassExtension</function>
+record.
+</para>
+
+<para>
+When the call to create a widget includes a varargs list containing
+<function>XtVaTypedArg</function>,
+these arguments will be passed to the allocation procedure in an
+<function>XtTypedArgList</function>.
+</para>
+<literallayout>
+typedef struct {
+ String name;
+ String type;
+ XtArgVal value;
+ int size;
+} XtTypedArg, *XtTypedArgList;
+</literallayout>
+<para>
+The allocate procedure pointer in the
+<function>ObjectClassExtension</function>
+record is of type
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAllocateProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*AllocateProc)</function></funcdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>constraint_size</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>more_bytes</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>num_args</parameter></paramdef>
+ <paramdef>XtTypedArgList <parameter>typed_args</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>num_typed_args</parameter></paramdef>
+ <paramdef>Widget* <parameter>new_return</parameter></paramdef>
+ <paramdef>XtPointer* <parameter>more_bytes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class of the instance to allocate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>constraint_size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the constraint record to allocate, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>more_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of auxiliary bytes of memory to allocate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list as given in the call to create the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>typed_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of typed arguments given in the call to create the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_typed_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of typed arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a pointer to the newly allocated instance, or NULL in case of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>more_bytes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the auxiliary memory if it was requested, or NULL
+if requested and an error occurred; otherwise, unchanged.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+At widget allocation time, if an extension record with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>
+is located through the object class part <emphasis remap='I'>extension</emphasis> field
+and the <emphasis remap='I'>allocate</emphasis> field is not NULL, the
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
+will be invoked to allocate memory for the widget. If no ObjectClassPart
+extension record is declared with <emphasis remap='I'>record_type equal</emphasis> to
+<emphasis role='strong'>NULLQUARK</emphasis>,
+then
+<function>XtInheritAllocate</function>
+and
+<function>XtInheritDeallocate</function>
+are assumed.
+If no
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
+is found, the Intrinsics will allocate memory for the widget.
+</para>
+
+<para>
+An
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
+must perform the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Allocate memory for the widget instance and return it in <emphasis remap='I'>new_return</emphasis>.
+The memory must be at least <emphasis remap='I'>wc-&gt;core_class.widget_size</emphasis> bytes in length,
+double-word aligned.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Initialize the <emphasis remap='I'>core.constraints</emphasis> field in the instance record to NULL
+or to point to a constraint record. If <emphasis remap='I'>constraint_size</emphasis>
+is not 0, the procedure must allocate memory for the constraint record.
+The memory must be double-word aligned.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If <emphasis remap='I'>more_bytes</emphasis> is not 0, then the address of a block of memory
+at least <emphasis remap='I'>more_bytes</emphasis> in size, double-word aligned, must be
+returned in the <emphasis remap='I'>more_bytes_return</emphasis> parameter,
+or NULL to indicate an error.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Widget_Instance_Initialization_The_initialize_Procedure">
+<title>Widget Instance Initialization: The initialize Procedure</title>
+<para>
+The initialize procedure pointer in a widget class is of type
+<xref linkend='XtInitProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInitProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtInitProc)</function></funcdef>
+ <paramdef>Widget <parameter>request</parameter></paramdef>
+ <paramdef>Widget <parameter>new</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the widget with resource values as requested by the
+argument list, the resource database, and the widget defaults.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget with the new values, both resource and nonresource,
+that are actually allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>XtVaTypedArg</function>
+are converted to the widget representation and the list is transformed
+into the
+<function>ArgList</function>
+format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+An initialization procedure performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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
+<function>String</function>,
+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.
+<note><para>
+It is not necessary to allocate space for or to copy callback lists.
+</para></note>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Computes values for unspecified resource fields.
+For example, if <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> are zero,
+the widget should compute an appropriate width and height
+based on its other resources.
+<note><para>
+A widget may directly assign only
+its own <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> within the initialize, initialize_hook,
+set_values, and
+set_values_hook procedures; see <xref linkend='Geometry_Management' />.
+</para></note>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+
+<para>
+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
+<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
+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.
+</para>
+
+<para>
+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 <emphasis remap='I'>initialize</emphasis> field in the class record.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> 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 <emphasis remap='I'>request</emphasis> widget is a copy of the widget as initialized by the
+arglist and resource database.
+The <emphasis remap='I'>new</emphasis> 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.
+</para>
+
+<para>
+In the above example,
+the subclass with the visual surround can see
+if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero.
+If so,
+it adds its surround size to the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis>
+fields in the <emphasis remap='I'>new</emphasis> widget.
+If not, it must make do with the size originally specified.
+</para>
+
+<para>
+The <emphasis remap='I'>new</emphasis> widget will become the actual widget instance record.
+Therefore,
+the initialization procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget;
+the <emphasis remap='I'>request</emphasis> widget should never be modified.
+If the initialize procedure
+needs to call any routines that operate on a widget,
+it should specify <emphasis remap='I'>new</emphasis> as the widget instance.
+</para>
+</sect2>
+
+<sect2 id="Constraint_Instance_Initialization_The_ConstraintClassPart_initialize_Procedure">
+<title>Constraint Instance Initialization: The ConstraintClassPart initialize Procedure</title>
+<para>
+The constraint initialization procedure pointer, found in the
+<function>ConstraintClassPart</function>
+<emphasis remap='I'>initialize</emphasis> field of the widget class record, is of type
+<xref linkend='XtInitProc' xrefstyle='select: title'/>.
+The values passed to the parent constraint initialization procedures
+are the same as those passed to the child's class widget initialization
+procedures.
+</para>
+
+<para>
+The <emphasis remap='I'>constraints</emphasis> field of the <emphasis remap='I'>request</emphasis> widget points to a copy of the
+constraints record as initialized by the arglist and resource database.
+</para>
+
+<para>
+The constraint initialization procedure should compute any constraint fields
+derived from constraint resources.
+It can make further changes to the <emphasis remap='I'>new</emphasis> widget to make the widget
+and any other constraint fields
+conform to the specified constraints, for example,
+changing the widget's size or position.
+</para>
+
+<para>
+If a constraint class does not need a constraint initialization procedure,
+it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field of the
+<function>ConstraintClassPart</function>
+in the class record.
+</para>
+</sect2>
+
+<sect2 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure">
+<title>Nonwidget Data Initialization: The initialize_hook Procedure</title>
+<note>
+<para>
+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.
+</para>
+</note>
+
+<para>
+The initialize_hook procedure pointer is of type
+<xref linkend='XtArgsProc' xrefstyle='select: title'/>:
+</para>
+
+<funcsynopsis id='XtArgsProc'>
+<funcprototype>
+ <funcdef>typedef void<function>(*XtArgsProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list passed by the client.
+If the client created the widget using a varargs form, any resources
+specified via
+<function>XtVaTypedArg</function>
+are converted to the widget representation and the list is transformed
+into the
+<function>ArgList</function>
+format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If this procedure is not NULL,
+it is called immediately after the corresponding initialize
+procedure or in its place if the <emphasis remap='I'>initialize</emphasis> field is NULL.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Realizing_Widgets">
+<title>Realizing Widgets</title>
+<para>
+To realize a widget instance, use
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRealizeWidget'>
+<funcprototype>
+ <funcdef>void <function>XtRealizeWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the widget is already realized,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+simply returns.
+Otherwise it performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Binds all action names in the widget's
+translation table to procedures (see <xref linkend='Action_Names_to_Procedure_Translations' />).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Constructs an
+<function>XSetWindowAttributes</function>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget is
+not a subclass of
+<function>compositeWidgetClass</function>,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+returns; otherwise it continues and performs the following:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Maps all of the managed children windows that have <emphasis remap='I'>mapped_when_managed</emphasis>
+<function>True</function>.
+If a widget is managed but <emphasis remap='I'>mapped_when_managed</emphasis> is
+<function>False</function>,
+the widget is allocated visual space but is not displayed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+If the widget is a top-level shell widget (that is, it has no parent), and
+<emphasis remap='I'>mapped_when_managed</emphasis> is
+<function>True</function>,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+maps the widget window.
+</para>
+
+<para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<function>XtUnmanage\%Children</function>,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
+and
+<function>XtDestroy\%Widget</function>
+maintain the following invariants:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If a composite widget is realized, then all its managed children are realized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a composite widget is realized, then all its managed children that have
+<emphasis remap='I'>mapped_when_managed</emphasis>
+<function>True</function>
+are mapped.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+All Intrinsics 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,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+calls the procedures in reverse order of
+appearance in the
+<function>CompositePart</function>
+<emphasis remap='I'>children</emphasis> 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.
+</para>
+
+<para>
+To check whether or not a widget has been realized, use
+<xref linkend='XtIsRealized' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtIsRealized'>
+<funcprototype>
+ <funcdef>Boolean <function>XtIsRealized</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtIsRealized' xrefstyle='select: title'/>
+function returns
+<function>True</function>
+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.
+</para>
+
+<para>
+Some widget procedures (for example, set_values) might wish to
+operate differently
+after the widget has been realized.
+</para>
+<sect2 id="Widget_Instance_Window_Creation_The_realize_Procedure">
+<title>Widget Instance Window Creation: The realize Procedure</title>
+<para>
+The realize procedure pointer in a widget class is of type
+<xref linkend='XtRealizeProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRealizeProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtRealizeProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XSetWindowAttributes <parameter>attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>attributes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window attributes to use in the
+<function>XCreateWindow</function>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The realize procedure must create the widget's window.
+</para>
+
+<para>
+Before calling the class realize procedure, the generic
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+function fills in a mask and a corresponding
+<function>XSetWindowAttributes</function>
+structure.
+It sets the following fields in <emphasis remap='I'>attributes</emphasis> and
+corresponding bits in <emphasis remap='I'>value_mask</emphasis>
+based on information in the widget
+core
+structure:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+The <emphasis remap='I'>background_pixmap</emphasis> (or <emphasis remap='I'>background_pixel</emphasis> if <emphasis remap='I'>background_pixmap</emphasis> is
+<function>XtUnspecifiedPixmap</function>)
+is filled in from the corresponding field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>border_pixmap</emphasis> (or <emphasis remap='I'>border_pixel</emphasis> if <emphasis remap='I'>border_pixmap</emphasis> is
+<function>XtUnspecifiedPixmap</function>)
+is filled in from the corresponding field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>colormap</emphasis> is filled in from the corresponding field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>event_mask</emphasis> is filled in based on the event handlers registered,
+the event translations specified, whether the <emphasis remap='I'>expose</emphasis> field is non-NULL,
+and whether <emphasis remap='I'>visible_interest</emphasis> is
+<function>True</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>bit_gravity</emphasis> is set to
+<function>NorthWestGravity</function>
+if the <emphasis remap='I'>expose</emphasis> field is NULL.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+These or any other fields in attributes and the corresponding bits in
+<emphasis remap='I'>value_mask</emphasis> can be set by the realize procedure.
+</para>
+
+<para>
+Note that because realize is not a chained operation,
+the widget class realize procedure must update the
+<function>XSetWindowAttributes</function>
+structure with all the appropriate fields from
+non-Core
+superclasses.
+</para>
+
+<para>
+A widget class can inherit its realize procedure from its superclass
+during class initialization.
+The realize procedure defined for
+<function>coreWidgetClass</function>
+calls
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+with the passed <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>attributes</emphasis>
+and with <emphasis remap='I'>window_class</emphasis> and <emphasis remap='I'>visual</emphasis> set to
+<function>CopyFromParent</function>.
+Both
+<function>compositeWidgetClass</function>
+and
+<function>constraintWidgetClass</function>
+inherit this realize procedure, and most new widget subclasses
+can do the same (see <xref linkend='Inheritance_of_Superclass_Operations' />).
+</para>
+
+<para>
+The most common noninherited realize procedures set <emphasis remap='I'>bit_gravity</emphasis> in the mask
+and attributes to the appropriate value and then create the window.
+For example, depending on its justification, Label might set <emphasis remap='I'>bit_gravity</emphasis> to
+<function>WestGravity</function>,
+<function>CenterGravity</function>,
+or
+<function>EastGravity</function>.
+Consequently, shrinking it would just move the bits appropriately,
+and no
+exposure
+event is needed for repainting.
+</para>
+
+<para>
+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
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on its children itself in the appropriate order from within its own
+realize procedure.
+</para>
+
+<para>
+Widgets that have children and whose class is not a subclass of
+<function>compositeWidgetClass</function>
+are responsible for calling
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on their children, usually from within the realize procedure.
+</para>
+
+<para>
+Realize procedures cannot manage or unmanage their descendants.
+</para>
+</sect2>
+
+<sect2 id="Window_Creation_Convenience_Routine">
+<title>Window Creation Convenience Routine</title>
+<para>
+Rather than call the Xlib
+<function>XCreateWindow</function>
+function explicitly, a realize procedure should normally call the Intrinsics analog
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>,
+which simplifies the creation of windows for widgets.
+</para>
+
+<funcsynopsis id='XtCreateWindow'>
+<funcprototype>
+ <funcdef>void <function>XtCreateWindow</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>unsigned int <parameter>window_class</parameter></paramdef>
+ <paramdef>Visual * <parameter>visual</parameter></paramdef>
+ <paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XSetWindowAttributes <parameter>attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that defines the additional window attributed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Xlib window class (for example,
+<function>InputOutput</function>,
+<function>InputOnly</function>,
+or
+<function>CopyFromParent ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual type (usually
+<function>CopyFromParent ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>attributes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window attributes to use in the
+<function>XCreateWindow</function>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+function calls the Xlib
+<function>XCreateWindow</function>
+function with values from the widget structure and the passed parameters.
+Then, it assigns the created window to the widget's <emphasis remap='I'>window</emphasis> field.
+</para>
+
+<para>
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+evaluates the following fields of the widget core
+structure: <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>screen</emphasis>, <emphasis remap='I'>parent-&gt;core.window</emphasis>, <emphasis remap='I'>x</emphasis>,
+<emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and
+<emphasis remap='I'>border_width</emphasis>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Obtaining_Window_Information_from_a_Widget">
+<title>Obtaining Window Information from a Widget</title>
+<para>
+The
+Core
+widget class definition contains the screen and window ids.
+The <emphasis remap='I'>window</emphasis> field may be NULL for a while
+(see <xref linkend='Creating_Widgets' /> and <xref linkend='Realizing_Widgets' />).
+</para>
+
+<para>
+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.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display <function>XtDisplay</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XtDisplay</function>
+returns the display pointer for the specified widget.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget <function>XtParent</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XtParent</function>
+returns the parent object for the specified widget. The returned object
+will be of class Object or a subclass.
+</para>
+
+<funcsynopsis id='XtScreen'>
+<funcprototype>
+ <funcdef>Screen <function>*XtScreen</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtScreen' xrefstyle='select: title'/>
+returns the screen pointer for the specified widget.
+</para>
+
+<funcsynopsis id='XtWindow'>
+<funcprototype>
+ <funcdef>Window <function>XtWindow</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtWindow' xrefstyle='select: title'/>
+returns the window of the specified widget.
+</para>
+
+<para>
+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
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>,
+and
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDisplayOfObject'>
+<funcprototype>
+ <funcdef>Display <function>*XtDisplayOfObject</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
+is identical in function to
+<function>XtDisplay</function>
+if the object is a widget; otherwise
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
+returns the display
+pointer for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
+Widget or a subclass thereof.
+</para>
+
+<funcsynopsis id='XtScreenOfObject'>
+<funcprototype>
+ <funcdef>Screen <function>*XtScreenOfObject</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtScreen' xrefstyle='select: title'/>
+if the object is a widget; otherwise
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
+returns the screen pointer
+for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
+Widget or a subclass thereof.
+</para>
+
+<funcsynopsis id='XtWindowOfObject'>
+<funcprototype>
+ <funcdef>Window <function>XtWindowOfObject</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtWindow' xrefstyle='select: title'/>
+if the object is a widget; otherwise
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
+returns the window for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
+Widget or a subclass thereof.
+</para>
+
+<para>
+To retrieve the instance name of an object, use
+<xref linkend='XtName' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtName'>
+<funcprototype>
+ <funcdef>String <function>XtName</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose name is desired. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtName' xrefstyle='select: title'/>
+returns a pointer to the instance name of the specified object.
+The storage is owned by the Intrinsics and must not be modified. The
+name is not qualified by the names of any of the object's ancestors.
+</para>
+
+<para>
+Several window attributes are locally cached in the widget instance.
+Thus, they can be set by the resource manager and
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+as well as used by routines that derive structures from these values
+(for example, <emphasis remap='I'>depth</emphasis> for deriving pixmaps,
+<emphasis remap='I'>background_pixel</emphasis> for deriving GCs, and so on) or in the
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+call.
+</para>
+
+<para>
+The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>
+window attributes are available to
+geometry managers.
+These fields are maintained synchronously inside the Intrinsics.
+When an
+<function>XConfigureWindow</function>
+is issued by the Intrinsics 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
+<function>ConfigureNotify</function>
+event.
+(In fact, most widgets do not select
+<function>SubstructureNotify</function>
+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
+<function>ConfigureNotify</function>
+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 <xref linkend='Geometry_Management' />).
+</para>
+<sect2 id="Unrealizing_Widgets">
+<title>Unrealizing Widgets</title>
+<para>
+To destroy the windows associated with a widget and its
+non-pop-up descendants, use
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnrealizeWidget'>
+<funcprototype>
+ <funcdef>void <function>XtUnrealizeWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the widget is currently unrealized,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+simply returns. Otherwise it performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Unmanages the widget if the widget is managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+XtNunrealizeCallback
+list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Destroys the widget's window and any subwindows by calling
+<function>XDestroyWindow</function>
+with the specified widget's <emphasis remap='I'>window</emphasis> field.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Any events in the queue or which arrive following a call to
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+will be dispatched as if the window(s) of the
+unrealized widget(s) had never existed.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Destroying_Widgets">
+<title>Destroying Widgets</title>
+<para>
+The Intrinsics provide support
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+To destroy all the pop-up children of the widget being destroyed
+and destroy all children of composite widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To remove (and unmap) the widget from its parent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To call the callback procedures that have been registered to trigger
+when the widget is destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To minimize the number of things a widget has to deallocate when destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To minimize the number of
+<function>XDestroyWindow</function>
+calls when destroying a widget tree.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To destroy a widget instance, use
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>.
+</para>
+
+
+<funcsynopsis id='XtDestroyWidget'>
+<funcprototype>
+ <funcdef>void <function>XtDestroyWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+In phase 1,
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the <emphasis remap='I'>being_destroyed</emphasis> field of the widget is
+<function>True</function>,
+it returns immediately.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Recursively descends the widget tree and
+sets the <emphasis remap='I'>being_destroyed</emphasis> field to
+<function>True</function>
+for the widget and all normal and pop-up children.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Adds the widget to a list of widgets (the destroy list) that should be
+destroyed when it is safe to do so.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+
+<para>
+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
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is about to return, or immediately if not in
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+</para>
+
+<para>
+In phase 2,
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+performs the following on each entry in the destroy list in the order
+specified:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the widget is not a pop-up child and the widget's parent is a subclass of
+<function>composite\%WidgetClass</function>,
+and if the parent is not being destroyed,
+it calls
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
+on the widget and then calls the widget's parent's delete_child procedure
+(see <xref linkend='Deletion_of_Children_The_delete_child_Procedure' />).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+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:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the widget is not a pop-up child and the widget's parent is a subclass of
+<function>constraint\%WidgetClass</function>,
+it calls the
+<function>ConstraintClassPart</function>
+destroy procedure for the parent,
+then for the parent's superclass,
+until finally it calls the
+<function>ConstraintClassPart</function>
+destroy procedure for
+<function>constraintWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the
+<function>CoreClassPart</function>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget class object class part contains an
+<function>ObjectClassExtension</function>
+record with the record_type
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>deallocate</emphasis> field is not NULL,
+calls the deallocate procedure to deallocate the instance and if one
+exists, the constraint record. Otherwise, the Intrinsics will deallocate
+the widget instance record and if one exists, the constraint record.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XDestroyWindow</function>
+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.)
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Adding_and_Removing_Destroy_Callbacks">
+<title>Adding and Removing Destroy Callbacks</title>
+<para>
+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
+<xref linkend='Callbacks' />.
+The destroy callback list is identified by the resource name
+XtNdestroyCallback.
+</para>
+
+<para>
+For example, the following adds an application-supplied destroy callback
+procedure <emphasis remap='I'>ClientDestroy</emphasis> with client data to a widget by calling
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>.
+</para>
+
+<literallayout>
+XtAddCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
+</literallayout>
+
+<para>
+Similarly, the following removes the application-supplied destroy callback
+procedure <emphasis remap='I'>ClientDestroy</emphasis> by calling
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>.
+</para>
+
+<literallayout>
+XtRemoveCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
+</literallayout>
+<para>
+The <emphasis remap='I'>ClientDestroy</emphasis> argument is of type
+<xref linkend='XtCallbackProc' xrefstyle='select: title'/>;
+see <xref linkend='Using_Callback_Procedure_and_Callback_List_Definitions' />.
+</para>
+</sect2>
+
+<sect2 id="Dynamic_Data_Deallocation_The_destroy_Procedure">
+<title>Dynamic Data Deallocation: The destroy Procedure</title>
+<para>
+The destroy procedure pointers in the
+<function>ObjectClassPart</function>,
+<function>RectObjClassPart</function>,
+and
+<function>CoreClassPart</function>
+structures are of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWidgetProc'>
+<funcprototype>
+ <funcdef>typedef void <function>XtWidgetProc</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget being destroyed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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.
+</para>
+
+<para>
+Deallocating storage includes, but is not limited to,
+the following steps:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtFree' xrefstyle='select: title'/>
+on dynamic storage allocated with
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and so on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<function>XFreePixmap</function>
+on pixmaps created with direct X calls.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
+on GCs allocated with
+<xref linkend='XtGetGC' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<function>XFreeGC</function>
+on GCs allocated with direct X calls.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+on event handlers added to other widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
+on timers created with
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+for each child if the widget has children
+and is not a subclass of
+<function>compositeWidgetClass</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+During destroy phase 2 for each widget, the Intrinsics 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.
+</para>
+</sect2>
+
+<sect2 id="Dynamic_Constraint_Data_Deallocation_The_ConstraintClassPart_destroy_Procedure">
+<title>Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure</title>
+<para>
+The constraint destroy procedure identified in the
+<function>ConstraintClassPart</function>
+<function>constraintWidgetClass</function>.
+This constraint destroy procedure pointer is of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+The constraint destroy procedures are called in subclass-to-superclass order,
+starting at the class of the widget's parent and ending at
+<function>constraint\%WidgetClass</function>.
+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.
+</para>
+
+<para>
+If a parent does not need to deallocate any constraint storage,
+the constraint destroy procedure entry
+in its class record can be NULL.
+</para>
+</sect2>
+
+<sect2 id="Widget_Instance_Deallocation_The_deallocate_Procedure">
+<title>Widget Instance Deallocation: The deallocate Procedure</title>
+<para>
+The deallocate procedure pointer in the
+<function>ObjectClassExtension</function>
+record is of type
+<function>XtDeallocateProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtDeallocateProc)</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>XtPointer <parameter>more_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget being destroyed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>more_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the auxiliary memory received from the corresponding allocator
+along with the widget, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When a widget is destroyed, if an
+<function>ObjectClassExtension</function>
+record exists in the object class part <emphasis remap='I'>extension</emphasis> field
+with <emphasis remap='I'>record_type</emphasis>
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, the
+<function>XtDeallocateProc</function>
+will be called.
+If no ObjectClassPart extension record is declared with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>,
+then
+<function>XtInheritAllocate</function>
+and
+<function>XtInheritDeallocate</function>
+are assumed.
+The responsibilities of the deallocate procedure are to deallocate the
+memory specified by <emphasis remap='I'>more_bytes</emphasis> if it is not NULL,
+to deallocate the constraints record as specified by the
+widget's <emphasis remap='I'>core.constraints</emphasis> field if it is
+not NULL, and to deallocate the widget instance itself.
+</para>
+
+<para>
+If no
+<function>XtDeallocateProc</function>
+is found, it is assumed that the Intrinsics
+originally allocated the memory and is responsible for freeing it.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Exiting_from_an_Application">
+<title>Exiting from an Application</title>
+<para>
+All X Toolkit applications should terminate
+by calling
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+and then exiting
+using the
+standard method for their operating system (typically, by calling
+<function>exit</function>
+for POSIX-based systems).
+The quickest way to make the windows disappear while exiting is to call
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+on each top-level shell widget.
+The Intrinsics 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.
+</para>
+
+<para>
+Depending upon the widget set in use, it may be necessary to explicitly
+destroy individual widgets or widget trees with
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+before calling
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+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 <xref linkend='Session_Participation' />), then the client may wish to resign from the session
+before exiting. See <xref linkend='Resigning_from_a_Session' /> for details.
+</para>
+</sect1>
+</chapter>
diff --git a/specs/CH03.xml b/specs/CH03.xml
new file mode 100644
index 0000000..2b2e1d7
--- /dev/null
+++ b/specs/CH03.xml
@@ -0,0 +1,1406 @@
+<chapter id='Composite_Widgets_and_Their_Children'>
+<title>Composite Widgets and Their Children</title>
+<para>
+Composite widgets (widgets whose class is a subclass of
+<function>compositeWidgetClass</function>)
+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 Intrinsics functions) include:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Overall management of children from creation to destruction.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Destruction of descendants when the composite widget is destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Physical arrangement (geometry management) of a displayable subset of
+children (that is, the managed children).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Mapping and unmapping of a subset of the managed children.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Overall management is handled by the generic procedures
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+and
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>.
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+adds children to their parent by calling the parent's insert_child
+procedure.
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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 Intrinsics.
+</para>
+
+<para>
+Children are added to and removed from their parent's managed set by using
+<xref linkend='XtManageChild' xrefstyle='select: title'/>,
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>,
+and
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>,
+which notify the parent to recalculate the physical layout of its children
+by calling the parent's change_managed procedure.
+The
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
+convenience function calls
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+and
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+on the result.
+</para>
+
+<para>
+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 <emphasis remap='I'>map_when_managed</emphasis> field is
+<function>False</function>.
+The default is
+<function>True</function>
+and is changed by using
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>.
+</para>
+
+<para>
+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:
+<variablelist>
+ <varlistentry>
+ <term>Fixed boxes</term>
+ <listitem>
+ <para>
+Fixed boxes have a fixed number of children created by the parent.
+All these children are managed,
+and none ever makes geometry manager requests.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Homogeneous boxes</term>
+ <listitem>
+ <para>
+Homogeneous boxes treat all children equally and apply the same geometry
+constraints to each child.
+Many clients insert and delete widgets freely.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Heterogeneous boxes</term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Shell boxes</term>
+ <listitem>
+ <para>
+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
+<function>ConfigureNotify</function>
+events when the window size is changed by the window manager.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<sect1 id="Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure">
+<title>Addition of Children to a Composite Widget: The insert_child Procedure</title>
+<para>
+To add a child to
+the parent's list of children, the
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+function calls the parent's class routine insert_child.
+The insert_child procedure pointer in a composite widget is of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWidgetProc_2'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtWidgetProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the newly created child.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most composite widgets inherit their superclass's operation.
+The insert_child routine in
+<function>CompositeWidgetClass calls the insert_position procedure</function>
+and inserts the child at the specified position
+in the <emphasis remap='I'>children</emphasis> list, expanding it if necessary.
+</para>
+
+<para>
+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 <xref linkend='Nonwidget_Objects' />) must specify a
+<function>CompositeClassExtension</function>
+extension record as described
+in <xref linkend='CompositeClassPart_Structure' />
+and set the <emphasis remap='I'>accepts_objects</emphasis> field in this record to
+<function>True</function>.
+If the
+<function>CompositeClassExtension</function>
+record is not specified or the
+<emphasis remap='I'>accepts_objects</emphasis> field is
+<function>False</function>,
+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.
+</para>
+
+<para>
+If there is not enough room to insert a new child in the <emphasis remap='I'>children</emphasis> array
+(that is, <emphasis remap='I'>num_children</emphasis> is equal to <emphasis remap='I'>num_slots</emphasis>),
+the insert_child procedure must first reallocate the array
+and update <emphasis remap='I'>num_slots</emphasis>.
+The insert_child procedure then places the child at the appropriate position
+in the array and increments the <emphasis remap='I'>num_children</emphasis> field.
+</para>
+</sect1>
+
+<sect1 id="Insertion_Order_of_Children_The_insert_position_Procedure">
+<title>Insertion Order of Children: The insert_position Procedure</title>
+<para>
+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.
+</para>
+
+<para>
+An application controls the presentation order of a set of children by
+supplying an
+XtNinsertPosition
+resource.
+The insert_position procedure pointer in a composite widget instance is of type
+<xref linkend='XtOrderProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOrderProc'>
+<funcprototype>
+<funcdef>typedef Cardinal <function>(*XtOrderProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the newly created widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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 <emphasis remap='I'>children</emphasis> 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.
+</para>
+
+<para>
+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 <emphasis remap='I'>num_children</emphasis> indicates that it should go after all other children.
+The default insert_position function returns <emphasis remap='I'>num_children</emphasis>
+and can be overridden by a specific composite widget's resource list
+or by the argument list provided when the composite widget is created.
+</para>
+</sect1>
+
+<sect1 id="Deletion_of_Children_The_delete_child_Procedure">
+<title>Deletion of Children: The delete_child Procedure</title>
+
+<para>
+To remove the child from the parent's <emphasis remap='I'>children</emphasis> list, the
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+function eventually causes a call to the Composite parent's class delete_child
+procedure.
+The delete_child procedure pointer is of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='_XtWidgetProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtWidgetProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the child being deleted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Adding_and_Removing_Children_from_the_Managed_Set">
+<title>Adding and Removing Children from the Managed Set</title>
+<para>
+The Intrinsics 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.
+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
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+The widget argument specifies the composite widget whose managed child
+set has been modified.
+</para>
+
+<sect2 id="Managing_Children">
+<title>Managing Children</title>
+<para>
+To add a list of widgets to the geometry-managed (and hence displayable)
+subset of their Composite parent, use
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>.
+</para>
+
+<para>typedef Widget *WidgetList;</para>
+
+<funcsynopsis id='XtManageChildren'>
+<funcprototype>
+<funcdef>void <function>XtManageChildren</function></funcdef>
+ <paramdef>WidgetList <parameter>children</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_children</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of child widgets. Each child must be of class
+RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of children in the list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>
+function performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Issues an error if the children do not all have the same parent or
+if the parent's class is not a subclass of
+<function>compositeWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Returns immediately if the common parent is being destroyed;
+otherwise, for each unique child on the list,
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>
+ignores the child if it already is managed or is being destroyed,
+and marks it if not.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is realized and after all children have been marked,
+it makes some of the newly managed children viewable:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Calls the change_managed routine of the widgets' parent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on each previously unmanaged child that is unrealized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Maps each previously unmanaged child that has <emphasis remap='I'>map_when_managed</emphasis>
+<function>True</function>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+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 <emphasis remap='I'>managed</emphasis> field is
+<function>True</function>
+and should ignore all other children.
+Note that some composite widgets, especially fixed boxes, call
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+from their insert_child procedure.
+</para>
+
+<para>
+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
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>,
+which first updates the <emphasis remap='I'>x</emphasis> and <emphasis remap='I'>y</emphasis> fields and which then calls
+<function>XMoveWindow</function>.
+</para>
+
+<para>
+If the composite widget wishes to change the size or border width of any of
+its children, it calls
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>,
+which first updates the
+<emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>
+fields and then calls
+<function>XConfigureWindow</function>.
+Simultaneous repositioning and resizing may be done with
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>;
+see <xref linkend='Widget_Placement_and_Sizing' />.
+</para>
+
+<para>
+To add a single child to its parent widget's set of managed children, use
+<xref linkend='XtManageChild' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtManageChild'>
+<funcprototype>
+<funcdef>void <function>XtManageChild</function></funcdef>
+ <paramdef>Widget <parameter>child</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>child</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the child. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+function constructs a
+<function>WidgetList</function>
+of length 1 and calls
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To create and manage a child widget in a single procedure, use
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateManagedWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtCreateManagedWidget</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource instance name for the created widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created widget. (rC
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Composite or any
+subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
+function is a convenience routine that calls
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+and
+<xref linkend='XtManageChild' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaCreateManagedWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtVaCreateManagedWidget</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource instance name for the created widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created widget. (rC
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Composite or any
+subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced
+by a varargs list, as described in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Unmanaging_Children">
+<title>Unmanaging Children</title>
+<para>
+To remove a list of children from a parent widget's managed list, use
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnmanageChildren'>
+<funcprototype>
+<funcdef>void <function>XtUnmanageChildren</function></funcdef>
+ <paramdef>WidgetList <parameter>children</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_children</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of child widgets. Each child must be of class
+RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of children.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+function performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Returns immediately if the common parent is being destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Issues an error if the children do not all have the same parent
+or if the parent is not a subclass of
+<function>compositeWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For each unique child on the list,
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+ignores the child if it is unmanaged; otherwise it performs the following:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Marks the child as unmanaged.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the child is realized and the <emphasis remap='I'>map_when_managed</emphasis> field is
+<function>True</function>,
+it is unmapped.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is realized and if any children have become unmanaged,
+calls the change_managed routine of the widgets' parent.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+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,
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+should be called instead;
+see <xref linkend='Exiting_from_an_Application' />.
+</para>
+
+<para>
+To remove a single child from its parent widget's managed set, use
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnmanageChild'>
+<funcprototype>
+<funcdef>void <function>XtUnmanageChild</function></funcdef>
+ <paramdef>Widget <parameter>child</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>child</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the child. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
+function constructs a widget list
+of length 1 and calls
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Bundling_Changes_to_the_Managed_Set">
+<title>Bundling Changes to the Managed Set</title>
+<para>
+A client may simultaneously unmanage and manage children
+with a single call to the Intrinsics. 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.
+</para>
+
+<para>
+To simultaneously remove from and add to the geometry-managed
+set of children of a composite parent, use
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtChangeManagedSet'>
+<funcprototype>
+<funcdef>void <function>XtChangeManagedSet</function></funcdef>
+ <paramdef>WidgetList <parameter>unmanage_children</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_unmanage_children</parameter></paramdef>
+ <paramdef>XtDoChangeProc <parameter>do_change_proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>WidgetList <parameter>manage_children</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_manage_children</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>unmanage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of widget children to initially remove from the managed set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_unmanage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the <emphasis remap='I'>unmanage_children</emphasis> list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>do_change_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a procedure to invoke between unmanaging
+and managing the children, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client data to be passed to the do_change_proc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>manage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of widget children to finally add to the managed set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_manage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the <emphasis remap='I'>manage_children</emphasis> list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
+function performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Returns immediately if <emphasis remap='I'>num_unmanage_children</emphasis> and
+<emphasis remap='I'>num_manage_children</emphasis> are both 0.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Issues a warning and returns if the widgets specified in the
+<emphasis remap='I'>manage_children</emphasis> and
+the <emphasis remap='I'>unmanage_children</emphasis> lists do not all have the same parent or if
+that parent is not a subclass of
+<function>compositeWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Returns immediately if the common parent is being destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If <emphasis remap='I'>do_change_proc</emphasis> is not NULL and the parent's
+<function>CompositeClassExtension</function>
+<emphasis remap='I'>allows_change_managed_set</emphasis> field is
+<function>False</function>,
+then
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
+performs the following:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Calls
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+(<emphasis remap='I'>unmanage_children</emphasis>, <emphasis remap='I'>num_unmanage_children</emphasis>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the <emphasis remap='I'>do_change_proc</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>
+(<emphasis remap='I'>manage_children</emphasis>, <emphasis remap='I'>num_manage_children</emphasis>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Otherwise, the following is performed:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+For each child on the <emphasis remap='I'>unmanage_children</emphasis> list; if the child is
+already unmanaged it is ignored, otherwise it is marked as unmanaged,
+and if it is realized and its <emphasis remap='I'>map_when_managed</emphasis> field is
+<function>True</function>,
+it is unmapped.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If <emphasis remap='I'>do_change_proc</emphasis> is non-NULL, the procedure is invoked.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For each child on the <emphasis remap='I'>manage_children</emphasis> list; if the child is already
+managed or is being destroyed, it is ignored; otherwise it is
+marked as managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on each previously unmanaged child that is unrealized and
+mapping each previously unmanaged child that has <emphasis remap='I'>map_when_managed</emphasis>
+<function>True</function>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+If no
+<function>CompositeClassExtension</function>
+record is found in the parent's composite class part <emphasis remap='I'>extension</emphasis> field
+with record type
+<emphasis role='strong'>NULLQUARK</emphasis>
+and version greater than 1, and if
+<function>XtInheritChangeManaged</function>
+was specified in the parent's class record during class initialization,
+the value of the <emphasis remap='I'>allows_change_managed_set</emphasis>
+field is inherited from the superclass. The value inherited from
+<function>compositeWidgetClass</function>
+for the <emphasis remap='I'>allows_change_managed_set</emphasis> field is
+<function>False</function>.
+</para>
+
+<para>
+It is not an error to include a child in both the <emphasis remap='I'>unmanage_children</emphasis>
+and the <emphasis remap='I'>manage_children</emphasis> lists. The effect of such a call is that
+the child remains managed following the call, but the <emphasis remap='I'>do_change_proc</emphasis> is
+able to affect the child while it is in an unmanaged state.
+</para>
+
+<para>
+The <emphasis remap='I'>do_change_proc</emphasis> is of type
+<xref linkend='XtDoChangeProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDoChangeProc'>
+<funcprototype>
+<funcdef>typedef void <function>*XtDoChangeProc</function></funcdef>
+
+ <paramdef>Widget <parameter>composite_parent</parameter></paramdef>
+ <paramdef>WidgetList <parameter>unmange_children</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_unmanage_children</parameter></paramdef>
+ <paramdef>WidgetList <parameter>manage_children</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_manage_children</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>composite_parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the composite parent whose managed set is being altered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>unmanage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the list of children just removed from the managed set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_unmanage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the number of entries in the <emphasis remap='I'>unmanage_children</emphasis> list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>manage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the list of children about to be added to the managed set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_manage_children</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the number of entries in the <emphasis remap='I'>manage_children</emphasis> list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data passed to
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>do_change_proc</emphasis> procedure is used by the caller of
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
+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
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
+may take advantage of the fact that the Intrinsics internally grant
+geometry requests made by unmanaged children without invoking
+the parent's geometry manager. To achieve this advantage, if
+the <emphasis remap='I'>do_change_proc</emphasis> procedure
+changes the geometry of a child or of a descendant of a child, then
+that child should be included in the <emphasis remap='I'>unmanage_children</emphasis> and
+<emphasis remap='I'>manage_children</emphasis> lists.
+</para>
+</sect2>
+
+<sect2 id="Determining_if_a_Widget_Is_Managed">
+<title>Determining if a Widget Is Managed</title>
+<para>
+To determine the managed state of a given child widget, use
+<xref linkend='XtIsManaged' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtIsManaged'>
+<funcprototype>
+<funcdef>Boolean <function>XtIsManaged</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtIsManaged' xrefstyle='select: title'/>
+function returns
+<function>True</function>
+if the specified widget is of class RectObj or any subclass thereof
+and is managed, or
+<function>False</function>
+otherwise.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Controlling_When_Widgets_Get_Mapped">
+<title>Controlling When Widgets Get Mapped</title>
+<para>
+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 <emphasis remap='I'>map_when_managed</emphasis> field to
+<function>False</function>.
+</para>
+
+<para>
+To change the value of a given widget's <emphasis remap='I'>map_when_managed</emphasis> field, use
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetMappedWhenManaged'>
+<funcprototype>
+<funcdef>void <function>XtSetMappedWhenManaged</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Boolean <parameter>map_when_managed</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>map_when_managed</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates the new value
+that is stored into the widget's <emphasis remap='I'>map_when_managed</emphasis>
+field.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the widget is realized and managed,
+and if <emphasis remap='I'>map_when_managed</emphasis> is
+<function>True</function>,
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
+maps the window.
+If the widget is realized and managed,
+and if <emphasis remap='I'>map_when_managed</emphasis> is
+<function>False</function>,
+it unmaps the window.
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
+is a convenience function that is equivalent to (but slightly faster than)
+calling
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+and setting the new value for the XtNmappedWhenManaged resource
+then mapping the widget as appropriate.
+As an alternative to using
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
+to control mapping,
+a client may set <emphasis remap='I'>mapped_when_managed</emphasis> to
+<function>False</function>
+and use
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>
+and
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+explicitly.
+</para>
+
+<para>
+To map a widget explicitly, use
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMapWidget'>
+<funcprototype>
+<funcdef> <function>XtMapWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To unmap a widget explicitly, use
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnmapWidget'>
+<funcprototype>
+<funcdef> <function>XtUnmapWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+</sect1>
+
+<sect1 id="Constrained_Composite_Widgets">
+<title>Constrained Composite Widgets</title>
+<para>
+The Constraint
+widget class is a subclass of
+<function>compositeWidgetClass</function>.
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+To make it easy for widgets and the Intrinsics to keep track of the
+constraints associated with a child,
+every widget has a <emphasis remap='I'>constraints</emphasis> 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
+<function>constraintWidgetClass</function>,
+then the child's <emphasis remap='I'>constraints</emphasis> field is NULL.
+</para>
+
+<para>
+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:
+</para>
+<literallayout >
+typedef struct {
+ Dimension max_width, max_height;
+} MaxConstraintPart;
+typedef struct {
+ MaxConstraintPart max;
+} MaxConstraintRecord, *MaxConstraint;
+</literallayout>
+<para>
+A subclass of this widget class that also needs to maintain a minimum size would
+define its constraint record as follows:
+</para>
+<literallayout >
+typedef struct {
+ Dimension min_width, min_height;
+} MinConstraintPart;
+typedef struct {
+ MaxConstraintPart max;
+ MinConstraintPart min;
+} MaxMinConstraintRecord, *MaxMinConstraint;
+</literallayout>
+<para>
+Constraints are allocated, initialized, deallocated, and otherwise maintained
+insofar as possible by the Intrinsics.
+The Constraint class record part has several entries that facilitate this.
+All entries in
+<function>ConstraintClassPart</function>
+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.
+</para>
+
+<para>
+The
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+function uses the <emphasis remap='I'>constraint_size</emphasis> field in the parent's class record
+to allocate a constraint record when a child is created.
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+When the
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+and
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+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.
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+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
+<function>ConstraintClassExtension</function>
+record in the
+<function>ConstraintClassPart</function>
+<emphasis remap='I'>extension</emphasis>
+fields with a record type of
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>get_values_hook</emphasis> field in
+the extension record is non-NULL,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+calls the get_values_hook
+procedure(s) to allow the parent to return derived constraint fields.
+</para>
+
+<para>
+The
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+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;
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+does this automatically.
+</para>
+</sect1>
+</chapter>
diff --git a/specs/CH04.xml b/specs/CH04.xml
new file mode 100644
index 0000000..d01fe6e
--- /dev/null
+++ b/specs/CH04.xml
@@ -0,0 +1,2498 @@
+<chapter id='Shell_Widgets'>
+<title>Shell Widgets</title>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>The five types of public shells are:</para>
+<variablelist>
+ <varlistentry>
+ <term>OverrideShell</term>
+ <listitem>
+ <para>
+ Used for shell windows that completely bypass the window manager
+ (for example, pop-up menu shells).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TransientShell</term>
+ <listitem>
+ <para>Used for shell windows that have the
+ <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+ property set. The effect of this property is dependent upon the
+ window manager being used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TopLevelShell</term>
+ <listitem>
+ <para>Used for normal top-level windows
+ (for example, any additional top-level widgets an application needs).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ApplicationShell</term>
+ <listitem>
+ <para>Formerly used for the single main top-level window that
+ the window manager identifies as an application instance and
+ made obsolete by SessionShell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SessionShell</term>
+ <listitem>
+ <para>
+ Used for the single main top-level window that
+ the window manager identifies as an application instance and
+ that interacts with the session manager.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<sect1 id="Shell_Widget_Definitions">
+<title>Shell Widget Definitions</title>
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>The eight different types of shells are:</para>
+<variablelist>
+ <varlistentry>
+ <term>Shell</term>
+ <listitem>
+ <para>The base class for shell widgets; provides the
+ fields needed for all types of shells. Shell
+ is a direct subclass of
+ <emphasis role='strong'>compositeWidgetClass</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OverrideShell</term>
+ <listitem>
+ <para>A subclass of Shell; used for shell windows that completely
+ bypass the window manager.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>WMShell</term>
+ <listitem>
+ <para>A subclass of Shell; contains fields needed by the
+ common window manager protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>VendorShell</term>
+ <listitem>
+ <para>A subclass of WMShell; contains fields used by
+ vendor-specific window managers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TransientShell</term>
+ <listitem>
+ <para>A subclass of VendorShell; used for shell windows that
+ desire the <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+ property.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TopLevelShell</term>
+ <listitem>
+ <para>A subclass of VendorShell; used for normal top-level windows.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ApplicationShell</term>
+ <listitem>
+ <para>A subclass of TopLevelShell; may be used for an application's additional
+ root windows.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SessionShell</term>
+ <listitem>
+ <para>A subclass of ApplicationShell; used for an application's
+ main root window.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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.
+</para>
+
+<sect2 id="ShellClassPart_Definitions">
+<title>ShellClassPart Definitions</title>
+<para>
+Only the Shell
+class has additional class fields, which are all contained in the
+<function>ShellClassExtensionRec</function>.
+None of the other Shell classes have any additional class fields:
+</para>
+
+<literallayout >
+typedef struct {
+ XtPointer extension;
+} ShellClassPart, OverrideShellClassPart,
+WMShellClassPart, VendorShellClassPart, TransientShellClassPart,
+TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart;
+</literallayout>
+
+<para>The full Shell class record definitions are:</para>
+
+<literallayout >
+typedef struct _ShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+} ShellClassRec;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ XtPointer next_extension; See <xref linkend='Class_Extension_Records' />
+ XrmQuark record_type; See <xref linkend='Class_Extension_Records' />
+ long version; See <xref linkend='Class_Extension_Records' />
+ Cardinal record_size; See <xref linkend='Class_Extension_Records' />
+ XtGeometryHandler root_geometry_manager; See below
+} ShellClassExtensionRec, *ShellClassExtension;
+</literallayout>
+
+<literallayout >
+typedef struct _OverrideShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ OverrideShellClassPart override_shell_class;
+} OverrideShellClassRec;
+</literallayout>
+
+<literallayout >
+typedef struct _WMShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+} WMShellClassRec;
+</literallayout>
+
+<literallayout >
+typedef struct _VendorShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+ VendorShellClassPart vendor_shell_class;
+} VendorShellClassRec;
+</literallayout>
+
+<literallayout >
+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;
+</literallayout>
+
+<literallayout >
+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;
+</literallayout>
+
+<literallayout >
+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;
+</literallayout>
+
+<literallayout >
+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;
+</literallayout>
+
+<para>
+The single occurrences of the class records and pointers for creating
+instances of shells are:
+</para>
+
+<literallayout >
+extern ShellClassRec shellClassRec;
+extern OverrideShellClassRec overrideShellClassRec;
+extern WMShellClassRec wmShellClassRec;
+extern VendorShellClassRec vendorShellClassRec;
+extern TransientShellClassRec transientShellClassRec;
+extern TopLevelShellClassRec topLevelShellClassRec;
+extern ApplicationShellClassRec applicationShellClassRec;
+extern SessionShellClassRec sessionShellClassRec;
+extern WidgetClass shellWidgetClass;
+extern WidgetClass overrideShellWidgetClass;
+extern WidgetClass wmShellWidgetClass;
+extern WidgetClass vendorShellWidgetClass;
+extern WidgetClass transientShellWidgetClass;
+extern WidgetClass topLevelShellWidgetClass;
+extern WidgetClass applicationShellWidgetClass;
+extern WidgetClass sessionShellWidgetClass;
+</literallayout>
+
+<para>
+The following opaque types and opaque variables are defined
+for generic operations on widgets whose class is a subclass of
+Shell.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Types</entry>
+ <entry>Variables</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><emphasis role='strong'>ShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>shellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>OverrideShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>overrideShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>WMShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>wmShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>VendorShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>vendorShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TransientShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>transientShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TopLevelShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>topLevelShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>ApplicationShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>applicationShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>SessionShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>sessionShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>ShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>OverrideShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>WMShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>VendorShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TransientShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TopLevelShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>ApplicationShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>SessionShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The declarations for all Intrinsics-defined shells except
+VendorShell appear in
+<function>Shell.h</function>
+and
+<function>ShellP.h</function>.
+VendorShell has separate public and private .h files which are included by
+<function>Shell.h</function>
+and
+<function>ShellP.h</function>.
+</para>
+
+<para>
+<function>Shell.h</function>
+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.
+</para>
+
+<para>
+The symbolic constant for the
+<function>ShellClassExtension</function>
+version identifier is
+<function>XtShellExtensionVersion</function>
+(see <xref linkend='Class_Extension_Records' />).
+</para>
+
+<para>
+The root_geometry_manager procedure acts as
+the parent geometry manager for geometry requests made by shell
+widgets. When a shell widget calls either
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>,
+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
+<function>XtGeometryYes</function>;
+if the window manager denies the geometry
+request or does not change the window geometry within some timeout
+interval (equal to <emphasis remap='I'>wm_timeout</emphasis> in the case of WMShells), the
+root_geometry_manager procedure should return
+<function>XtGeometryNo</function>.
+If the window manager makes some alternative geometry change, the
+root_geometry_manager procedure may return either
+<function>XtGeometryNo</function>
+and handle the new geometry as a resize or
+<function>XtGeometryAlmost</function>
+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.
+</para>
+
+<para>
+If no
+<function>ShellClassPart</function>
+extension record is declared with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>,
+then
+<function>XtInheritRootGeometryManager</function>
+is assumed.
+</para>
+</sect2>
+
+<sect2 id="ShellPart_Definition">
+<title>ShellPart Definition</title>
+<para>
+The various shell widgets have the following additional instance
+fields defined in
+their widget records:
+</para>
+
+<literallayout >
+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;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ int empty;
+} OverrideShellPart;
+</literallayout>
+
+<literallayout >
+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;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ int vendor_specific;
+} VendorShellPart;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ Widget transient_for;
+} TransientShellPart;
+typedef struct {
+ String icon_name;
+ Boolean iconic;
+ Atom icon_name_encoding;
+} TopLevelShellPart;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ char * class;
+ XrmClass xrm_class;
+ int argc;
+ char ** argv;
+} ApplicationShellPart;
+</literallayout>
+
+<literallayout >
+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;
+</literallayout>
+
+<para>
+The full shell widget instance record definitions are:
+</para>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+} ShellRec, *ShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ OverrideShellPart override;
+} OverrideShellRec, *OverrideShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+} WMShellRec, *WMShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+} VendorShellRec, *VendorShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TransientShellPart transient;
+} TransientShellRec, *TransientShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TopLevelShellPart topLevel;
+} TopLevelShellRec, *TopLevelShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TopLevelShellPart topLevel;
+ ApplicationShellPart application;
+} ApplicationShellRec, *ApplicationShellWidget;
+</literallayout>
+
+<literallayout >
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TopLevelShellPart topLevel;
+ ApplicationShellPart application;
+ SessionShellPart session;
+} SessionShellRec, *SessionShellWidget;
+</literallayout>
+
+</sect2>
+
+<sect2 id="Shell_Resources">
+<title>Shell Resources</title>
+<para>
+The resource names, classes, and representation types specified in
+the
+<function>shellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNallowShellResize</entry>
+ <entry>XtCAllowShellResize</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNcreatePopupChildProc</entry>
+ <entry>XtCCreatePopupChildProc</entry>
+ <entry>XtRFunction</entry>
+ </row>
+ <row>
+ <entry>XtNgeometry</entry>
+ <entry>XtCGeometry</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNoverrideRedirect</entry>
+ <entry>XtCOverrideRedirect</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNpopdownCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNpopupCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNsaveUnder</entry>
+ <entry>XtCSaveUnder</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNvisual</entry>
+ <entry>XtCVisual</entry>
+ <entry>XtRVisual</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+OverrideShell
+declares no additional resources beyond those defined by
+Shell.
+</para>
+
+<para>
+The resource names, classes, and representation types specified in
+the
+<function>wmShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNbaseHeight</entry>
+ <entry>XtCBaseHeight</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNbaseWidth</entry>
+ <entry>XtCBaseWidth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNclientLeader</entry>
+ <entry>XtCClientLeader</entry>
+ <entry>XtRWidget</entry>
+ </row>
+ <row>
+ <entry>XtNheightInc</entry>
+ <entry>XtCHeightInc</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNiconMask</entry>
+ <entry>XtCIconMask</entry>
+ <entry>XtRBitmap</entry>
+ </row>
+ <row>
+ <entry>XtNiconPixmap</entry>
+ <entry>XtCIconPixmap</entry>
+ <entry>XtRBitmap</entry>
+ </row>
+ <row>
+ <entry>XtNiconWindow</entry>
+ <entry>XtCIconWindow</entry>
+ <entry>XtRWindow</entry>
+ </row>
+ <row>
+ <entry>XtNiconX</entry>
+ <entry>XtCIconX</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNiconY</entry>
+ <entry>XtCIconY</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNinitialState</entry>
+ <entry>XtCInitialState</entry>
+ <entry>XtRInitialState</entry>
+ </row>
+ <row>
+ <entry>XtNinput</entry>
+ <entry>XtCInput</entry>
+ <entry>XtRBool</entry>
+ </row>
+ <row>
+ <entry>XtNmaxAspectX</entry>
+ <entry>XtCMaxAspectX</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmaxAspectY</entry>
+ <entry>XtCMaxAspectY</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmaxHeight</entry>
+ <entry>XtCMaxHeight</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmaxWidth</entry>
+ <entry>XtCMaxWidth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminAspectX</entry>
+ <entry>XtCMinAspectX</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminAspectY</entry>
+ <entry>XtCMinAspectY</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminHeight</entry>
+ <entry>XtCMinHeight</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminWidth</entry>
+ <entry>XtCMinWidth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNtitle</entry>
+ <entry>XtCTitle</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNtitleEncoding</entry>
+ <entry>XtCTitleEncoding</entry>
+ <entry>XtRAtom</entry>
+ </row>
+ <row>
+ <entry>XtNtransient</entry>
+ <entry>XtCTransient</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNwaitforwm, XtNwaitForWm</entry>
+ <entry>XtCWaitforwm, XtCWaitForWm</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNwidthInc</entry>
+ <entry>XtCWidthInc</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNwindowRole</entry>
+ <entry>XtCWindowRole</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNwinGravity</entry>
+ <entry>XtCWinGravity</entry>
+ <entry>XtRGravity</entry>
+ </row>
+ <row>
+ <entry>XtNwindowGroup</entry>
+ <entry>XtCWindowGroup</entry>
+ <entry>XtRWindow</entry>
+ </row>
+ <row>
+ <entry>XtNwmTimeout</entry>
+ <entry>XtCWmTimeout</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNurgency</entry>
+ <entry>XtCUrgency</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>_</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The class resource list for
+VendorShell
+is implementation-defined.
+</para>
+
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>transient\%ShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNtransientFor</entry>
+ <entry>XtCTransientFor</entry>
+ <entry>XtRWidget</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>topLevelShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNiconName</entry>
+ <entry>XtCIconName</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNiconNameEncoding</entry>
+ <entry>XtCIconNameEncoding</entry>
+ <entry>XtRAtom</entry>
+ </row>
+ <row>
+ <entry>XtNiconic</entry>
+ <entry>XtCIconic</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>application\%ShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNargc</entry>
+ <entry>XtCArgc</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNargv</entry>
+ <entry>XtCArgv</entry>
+ <entry>XtRStringArray</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The resource names, classes, and representation types that are specified
+in the
+<function>sessionShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNcancelCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNcloneCommand</entry>
+ <entry>XtCCloneCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNconnection</entry>
+ <entry>XtCConnection</entry>
+ <entry>XtRSmcConn</entry>
+ </row>
+ <row>
+ <entry>XtNcurrentDirectory</entry>
+ <entry>XtCCurrentDirectory</entry>
+ <entry>XtRDirectoryString</entry>
+ </row>
+ <row>
+ <entry>XtNdieCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNdiscardCommand</entry>
+ <entry>XtCDiscardCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNenvironment</entry>
+ <entry>XtCEnvironment</entry>
+ <entry>XtREnvironmentArray</entry>
+ </row>
+ <row>
+ <entry>XtNerrorCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNinteractCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNjoinSession</entry>
+ <entry>XtCJoinSession</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNprogramPath</entry>
+ <entry>XtCProgramPath</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNresignCommand</entry>
+ <entry>XtCResignCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNrestartCommand</entry>
+ <entry>XtCRestartCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNrestartStyle</entry>
+ <entry>XtCRestartStyle</entry>
+ <entry>XtRRestartStyle</entry>
+ </row>
+ <row>
+ <entry>XtNsaveCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNsaveCompleteCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNsessionID</entry>
+ <entry>XtCSessionID</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNshutdownCommand</entry>
+ <entry>XtCShutdownCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect2>
+
+<sect2 id="ShellPart_Default_Values">
+<title>ShellPart Default Values</title>
+<para>
+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:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>geometry</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>create_popup_child_proc</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>grab_kind</entry>
+ <entry>(none)</entry>
+ </row>
+ <row>
+ <entry>spring_loaded</entry>
+ <entry>(none)</entry>
+ </row>
+ <row>
+ <entry>popped_up</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>allow_shell_resize</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>client_specified</entry>
+ <entry>(internal)</entry>
+ </row>
+ <row>
+ <entry>save_under</entry>
+ <entry><function>True</function>
+ for OverrideShell and TransientShell,
+ <emphasis role='strong'>False</emphasis>
+ otherwise</entry>
+ </row>
+ <row>
+ <entry>override_redirect</entry>
+ <entry><function>True</function>
+ for OverrideShell,
+ <function>False</function>
+ otherwise</entry>
+ </row>
+ <row>
+ <entry>popup_callback</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>popdown_callback</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>visual</entry>
+ <entry><function>CopyFromParent</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>geometry</emphasis> field specifies the size and position
+and is usually given only on a command line or in a defaults file.
+If the <emphasis remap='I'>geometry</emphasis> field is non-NULL when
+a widget of class WMShell
+is realized, the geometry specification is parsed using
+<function>XWMGeometry</function>
+with a default geometry
+string constructed from the values of <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>,
+<emphasis remap='I'>height</emphasis>, <emphasis remap='I'>width_inc</emphasis>,
+and <emphasis remap='I'>height_inc</emphasis> and the size and position flags in the window manager
+size hints are set. If the geometry specifies an x or y position,
+then
+<function>USPosition</function>
+is set. If the geometry specifies a width or height, then
+<function>USSize</function>
+is set. Any fields in the geometry specification
+override the corresponding values in the
+Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields.
+If <emphasis remap='I'>geometry</emphasis> is NULL or contains only a partial specification, then the
+Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields are used and
+<function>PPosition</function>
+and
+<function>PSize</function>
+are set as appropriate.
+The geometry string is not copied by any of the Intrinsics
+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
+<olink targetdoc='libX11' targetptr='Parsing_the_Window_Geometry' />
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+</para>
+
+<para>
+The <emphasis remap='I'>create_popup_child_proc</emphasis> procedure is called by the
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+procedure and may remain NULL.
+The <emphasis remap='I'>grab_kind</emphasis>, <emphasis remap='I'>spring_loaded</emphasis>,
+and <emphasis remap='I'>popped_up</emphasis> fields maintain widget
+state information as described under
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>,
+<xref linkend='XtPopdown' xrefstyle='select: title'/>,
+and
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>.
+The <emphasis remap='I'>allow_shell_resize</emphasis> field controls whether the widget contained
+by the shell is allowed to try to resize itself.
+If allow_shell_resize is
+<function>False</function>,
+any geometry requests made by the child will always return
+<function>XtGeometryNo</function>
+without interacting with the window manager.
+Setting <emphasis remap='I'>save_under</emphasis>
+<function>True</function>
+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 <emphasis remap='I'>override_redirect</emphasis>
+<function>True</function>
+determines
+whether the window manager can intercede when the shell window
+is mapped.
+For further information on override_redirect,
+see <olink targetdoc='libX11' targetptr='Window_Attributes' /> in
+<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>
+and
+<olink targetdoc='icccm' targetptr='Pop_up_Windows' /> and
+<olink targetdoc='icccm' targetptr='Redirection_of_Operations' /> in the
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>.
+The pop-up and pop-down callbacks are called during
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+and
+<xref linkend='XtPopdown' xrefstyle='select: title'/>.
+The default value of the <emphasis remap='I'>visual</emphasis> resource is the symbolic value
+<function>CopyFromParent</function>.
+The Intrinsics do not need to query the parent's visual type when the
+default value is used; if a client using
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+to examine the visual type receives the value
+<function>CopyFromParent</function>,
+it must then use
+<function>XGetWindowAttributes</function>
+if it needs the actual visual type.
+</para>
+
+<para>
+The default values for Shell fields in
+WMShell
+and its subclasses are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>title</entry>
+ <entry>Icon name, if specified, otherwise the application's name</entry>
+ </row>
+ <row>
+ <entry>wm_timeout</entry>
+ <entry>Five seconds, in units of milliseconds</entry>
+ </row>
+ <row>
+ <entry>wait_for_wm</entry>
+ <entry><function>True</function></entry>
+ </row>
+ <row>
+ <entry>transient</entry>
+ <entry><function>True</function>
+ for TransientShell,
+ <function>False</function>
+ otherwise</entry>
+ </row>
+ <row>
+ <entry>urgency</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>client_leader</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>window_role</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>min_width</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>min_height</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_width</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_height</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>width_inc</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>height_inc</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>min_aspect_x</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>min_aspect_y</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_aspect_x</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_aspect_y</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>input</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>initial_state</entry>
+ <entry>Normal</entry>
+ </row>
+ <row>
+ <entry>icon_pixmap</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>icon_window</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>icon_x</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>icon_y</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>icon_mask</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>window_group</entry>
+ <entry><function>XtUnspecifiedWindow</function></entry>
+ </row>
+ <row>
+ <entry>base_width</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>base_height</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>win_gravity</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>title_encoding</entry>
+ <entry>See text</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>title</emphasis> and
+<emphasis remap='I'>title_encoding</emphasis> fields are stored in the
+<emphasis role='strong'>WM_NAME</emphasis>
+property on the shell's window by the WMShell realize procedure.
+If the <emphasis remap='I'>title_encoding</emphasis> field is
+<function>None</function>,
+the <emphasis remap='I'>title</emphasis> string is assumed to be in the encoding of the current
+locale and the encoding of the
+<emphasis role='strong'>WM_NAME</emphasis>
+property is set to
+<function>XStdICCTextStyle</function>.
+If a language procedure has not been set
+the default value of <emphasis remap='I'>title_encoding</emphasis> is
+<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is
+<function>None</function>.
+The <emphasis remap='I'>wm_timeout</emphasis> 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 <emphasis remap='I'>wait_for_wm</emphasis> to
+<function>False</function>
+(later events may reset this value).
+When <emphasis remap='I'>wait_for_wm</emphasis> is
+<function>False</function>,
+the shell does not wait for a response, but relies on asynchronous
+notification.
+If <emphasis remap='I'>transient</emphasis> is
+<function>True</function>,
+the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+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
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>
+for more details.
+</para>
+
+<para>
+The realize and set_values procedures of WMShell store the
+<emphasis role='strong'>WM_CLIENT_LEADER</emphasis>
+property on the shell window.
+When <emphasis remap='I'>client_leader</emphasis> 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 <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a NULL parent,
+the widget's window is used as the value of the
+property.
+When <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a non-NULL parent,
+a search is made for the closest shell ancestor
+with a non-NULL <emphasis remap='I'>client_leader</emphasis>,
+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.
+</para>
+
+<para>
+When the value of <emphasis remap='I'>window_role</emphasis> is not NULL, the
+realize and set_values procedures store the
+<emphasis role='strong'>WM_WINDOW_ROLE</emphasis>
+property on the shell's window with the value of the resource.
+</para>
+
+<para>
+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
+<function>XtUnspecifiedShellInt</function>,
+the value of the field is modified as follows:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Replacement</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>base_width, base_height</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>width_inc, height_inc</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>max_width, max_height</entry>
+ <entry>32767</entry>
+ </row>
+ <row>
+ <entry>min_width, min_height</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>min_aspect_x, min_aspect_y</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry>max_aspect_x, max_aspect_y</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry>icon_x, icon_y</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry>win_gravity</entry>
+ <entry>Value returned by
+ <function>XWMGeometry</function>
+ if called,
+ else <function>NorthWestGravity</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+If the shell widget has a non-NULL parent, then the
+realize and set_values procedures replace the value
+<function>XtUnspecifiedWindow</function>
+in the <emphasis remap='I'>window_group</emphasis> field with the window id of the root widget
+of the widget tree if the
+root widget is realized. The symbolic constant
+<function>XtUnspecifiedWindowGroup</function>
+may be used to indicate that the <emphasis remap='I'>window_group</emphasis> hint flag bit is not
+to be set. If <emphasis remap='I'>transient</emphasis> is
+<function>True</function>,
+the shell's class is not a subclass of
+TransientShell,
+and <emphasis remap='I'>window_group</emphasis> is not
+<function>XtUnspecifiedWindowGroup</function>,
+the WMShell realize and set_values procedures then store the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property with the value of <emphasis remap='I'>window_group</emphasis>.
+</para>
+
+<para>
+Transient
+shells have the following additional resource:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Replacement</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>transient_for</entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The realize and set_values procedures of
+TransientShell
+store the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property on the shell window if <emphasis remap='I'>transient</emphasis> is
+<function>True</function>.
+If <emphasis remap='I'>transient_for</emphasis> is non-NULL and the widget specified by
+<emphasis remap='I'>transient_for</emphasis> is realized, then its window is used as the value of the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property; otherwise, the value of <emphasis remap='I'>window_group</emphasis> is used.
+</para>
+
+<para>
+<function>TopLevel</function>
+shells have the the following additional resources:
+</para>
+
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>icon_name</entry>
+ <entry>Shell widget's name</entry>
+ </row>
+ <row>
+ <entry>iconic</entry>
+ <entry><emphasis role='strong'>False</emphasis></entry>
+ </row>
+ <row>
+ <entry>icon_name_encoding</entry>
+ <entry>See text</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>icon_name</emphasis>
+and <emphasis remap='I'>icon_name_encoding</emphasis> fields are stored in the
+<emphasis role='strong'>WM_ICON_NAME</emphasis>
+property on the shell's window by the TopLevelShell realize
+procedure.
+If the <emphasis remap='I'>icon_name_encoding</emphasis> field is
+<function>None</function>,
+the <emphasis remap='I'>icon_name</emphasis> string is assumed to be in the encoding of the
+current locale and the encoding of the
+<emphasis role='strong'>WM_ICON_NAME</emphasis>
+property is set to
+<function>XStdICCTextStyle</function>.
+If a language procedure has not been set,
+the default value of <emphasis remap='I'>icon_name_encoding</emphasis> is
+<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is
+<function>None</function>.
+The <emphasis remap='I'>iconic</emphasis> 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
+<emphasis role='strong'>WM_CHANGE_STATE</emphasis>
+message (as specified by the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)
+if this resource is changed from
+<function>False</function>
+to
+<function>True</function>
+and will call
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+specifying <emphasis remap='I'>grab_kind</emphasis> as
+<function>XtGrabNone</function>
+if <emphasis remap='I'>iconic</emphasis> is changed from
+<function>True</function>
+to
+<function>False</function>.
+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 <emphasis remap='I'>initial_state</emphasis> to
+<function>IconicState</function>
+if <emphasis remap='I'>iconic</emphasis> is
+<function>True</function>.
+</para>
+
+<para>
+Application
+shells have the following additional resources:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>argc</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>argv</entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> fields are used to initialize
+the standard property
+<emphasis role='strong'>WM_COMMAND</emphasis>. See the
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>
+for more information.
+</para>
+
+<para>
+The default values for the SessionShell instance fields,
+which are filled in from the resource lists and by the
+initialize procedure, are
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>cancel_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>clone_command</entry>
+ <entry>See text</entry>
+ </row>
+ <row>
+ <entry>connection</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>current_dir</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>die_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>discard_command</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>environment</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>error_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>interact_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>join_session</entry>
+ <entry><emphasis role='strong'>True</emphasis></entry>
+ </row>
+ <row>
+ <entry>program_path</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>resign_command</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>restart_command</entry>
+ <entry>See text</entry>
+ </row>
+ <row>
+ <entry>restart_style</entry>
+ <entry><emphasis role='strong'>SmRestartIfRunning</emphasis></entry>
+ </row>
+ <row>
+ <entry>save_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>save_complete_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>session_id</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>shutdown_command</entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>connection</emphasis> field contains the session connection object or NULL
+if a session connection is not being managed by this widget.
+</para>
+
+<para>
+The <emphasis remap='I'>session_id</emphasis> is an identification assigned to the session
+participant by the session manager.
+The <emphasis remap='I'>session_id</emphasis> 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 <emphasis remap='I'>session_id</emphasis> field.
+When not NULL, the <emphasis remap='I'>session_id</emphasis> 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
+<emphasis role='strong'>SM_CLIENT_ID</emphasis>
+property on the client leader's window.
+</para>
+
+<para>
+If <emphasis remap='I'>join_session</emphasis> is
+<function>False</function>,
+the widget will not attempt to establish a
+connection to the session manager at shell creation time.
+See <xref linkend='Joining_a_Session' /> and
+<xref linkend='Resigning_from_a_Session' />
+for more information on the functionality of this resource.
+</para>
+
+<para>
+The <emphasis remap='I'>restart_command</emphasis>, <emphasis remap='I'>clone_command</emphasis>, <emphasis remap='I'>discard_command</emphasis>,
+<emphasis remap='I'>resign_command</emphasis>, <emphasis remap='I'>shutdown_command</emphasis>, <emphasis remap='I'>environment</emphasis>,
+<emphasis remap='I'>current_dir</emphasis>, <emphasis remap='I'>program_path</emphasis>, and
+<emphasis remap='I'>restart_style</emphasis> fields contain standard session properties.
+</para>
+
+<para>
+When a session connection is established or newly managed by the shell,
+the shell initialize and set_values methods check the values of the
+<emphasis remap='I'>restart_command</emphasis>,
+<emphasis remap='I'>clone_command</emphasis>,
+and <emphasis remap='I'>program_path</emphasis>
+resources. At that time, if <emphasis remap='I'>restart_command</emphasis> is NULL, the value
+of the <emphasis remap='I'>argv</emphasis> resource will be copied to <emphasis remap='I'>restart_command</emphasis>.
+Whether or not <emphasis remap='I'>restart_command</emphasis> was NULL,
+if "<emphasis>-xtsessionID</emphasis>" "<emphasis>&lt;session id&gt;</emphasis>" does not
+already appear in the <emphasis remap='I'>restart_command</emphasis>, it will be added by the
+initialize and set_values methods at the beginning of the command arguments;
+if the "<emphasis>-xtsessionID</emphasis>" argument already appears with an incorrect
+<emphasis>session id</emphasis> in the following argument, that argument
+will be replaced with the current <emphasis>session id</emphasis>.
+</para>
+
+<para>
+After this, the shell initialize and set_values procedures check the
+<emphasis remap='I'>clone_command</emphasis>. If <emphasis remap='I'>clone_command</emphasis> is NULL,
+<emphasis remap='I'>restart_command</emphasis> will be copied to <emphasis remap='I'>clone_command</emphasis>,
+except the "<emphasis>-xtsessionID</emphasis>" and following argument will not be copied.
+</para>
+
+<para>
+Finally, the shell initialize and set_values procedures check the
+<emphasis remap='I'>program_path</emphasis>. If <emphasis remap='I'>program_path</emphasis> is NULL, the
+first element of <emphasis remap='I'>restart_command</emphasis> is copied to <emphasis remap='I'>program_path</emphasis>.
+</para>
+
+<para>
+The possible values of <emphasis remap='I'>restart_style</emphasis> are
+<function>SmRestartIfRunning</function>,
+<function>SmRestartAnyway</function>,
+<function>SmRestartImmediately</function>,
+and
+<function>SmRestartNever</function>.
+A resource converter is registered for this resource;
+for the strings that it recognizes,
+see <xref linkend='Predefined_Resource_Converters' />.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Session_Participation">
+<title>Session Participation</title>
+<para>
+Applications can participate in a user's session, exchanging messages
+with the session manager as described in the
+<emphasis>X Session Management Protocol</emphasis> and the
+<emphasis remap='I'>X Session Management Library</emphasis>.
+</para>
+
+<para>
+When a widget of
+<function>sessionShellWidgetClass</function>
+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.
+</para>
+
+<sect2 id="Joining_a_Session">
+<title>Joining a Session</title>
+<para>
+When a Session shell is created,
+if <emphasis remap='I'>connection</emphasis> is NULL,
+and if <emphasis remap='I'>join_session</emphasis> is
+<function>True</function>,
+and if <emphasis remap='I'>argv</emphasis> or <emphasis remap='I'>restart_command</emphasis> is not NULL,
+and if in POSIX environments the
+<emphasis role='strong'>SESSION_MANAGER</emphasis>
+environment variable is defined,
+the shell will attempt to establish a new connection with the session manager.
+</para>
+
+<para>
+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 <emphasis remap='I'>connection</emphasis> 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.
+</para>
+
+<para>
+In the Session shell set_values procedure,
+if <emphasis remap='I'>join_session</emphasis> changes from
+<function>False</function>
+to
+<function>True</function>
+and <emphasis remap='I'>connection</emphasis> is NULL and when in POSIX environments the
+<emphasis role='strong'>SESSION_MANAGER</emphasis>
+environment variable is defined,
+the shell will attempt to open a connection to the session manager.
+If <emphasis remap='I'>connection</emphasis> changes from NULL to non-NULL, the
+Session shell
+will take over management of that session connection and will set
+<emphasis remap='I'>join_session</emphasis> to
+<function>True</function>.
+If <emphasis remap='I'>join_session</emphasis> changes from
+<function>False</function>
+to
+<function>True</function>
+and <emphasis remap='I'>connection</emphasis> is not NULL, the
+Session shell will take over management of the session connection.
+</para>
+
+<para>
+When a successful connection has been established, <emphasis remap='I'>connection</emphasis>
+contains the session connection ID for the session participant.
+When the shell begins to manage the connection, it will call
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+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 <emphasis remap='I'>connection</emphasis> is set to NULL.
+</para>
+
+<para>
+While the connection is being managed, if a
+<function>SaveYourself</function>,
+<function>SaveYourselfPhase2</function>,
+<function>Interact</function>,
+<function>ShutdownCancelled</function>,
+<function>SaveComplete</function>,
+or
+<function>Die</function>
+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
+<function>SaveYourselfPhase2Request</function>,
+<function>InteractRequest</function>,
+<function>InteractDone</function>,
+<function>SaveYourselfDone</function>,
+and
+<function>ConnectionClosed</function>
+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
+<function>SetProperties</function>
+or a
+<function>DeleteProperties</function>
+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.
+</para>
+</sect2>
+
+<sect2 id="Saving_Application_State">
+<title>Saving Application State</title>
+<para>
+The session manager instigates an application checkpoint by sending a
+<function>SaveYourself</function>
+request.
+Applications are responsible for saving their state in response to the
+request.
+</para>
+
+<para>
+When the
+<function>SaveYourself</function>
+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 <emphasis remap='I'>call_data</emphasis> parameter.
+</para>
+
+<para>
+The checkpoint token in the <emphasis remap='I'>call_data</emphasis> parameter is of type
+<function>XtCheckpointToken</function>.
+</para>
+
+<literallayout >
+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;
+</literallayout>
+
+<para>
+The <emphasis remap='I'>save_type</emphasis>, <emphasis remap='I'>interact_style</emphasis>, <emphasis remap='I'>shutdown</emphasis>, and <emphasis remap='I'>fast</emphasis>
+fields of the token contain the parameters of the
+<function>SaveYourself</function>
+message.
+The possible values of <emphasis remap='I'>save_type</emphasis> are
+<function>SmSaveLocal</function>,
+<function>SmSaveGlobal</function>,
+and
+<function>SmSaveBoth</function>;
+these indicate the type of information to be saved.
+The possible values of <emphasis remap='I'>interact_style</emphasis> are
+<function>SmInteractStyleNone</function>,
+<function>SmInteractStyleErrors</function>,
+and
+<function>SmInteractStyleAny</function>;
+these indicate whether user interaction would be permitted
+and, if so, what kind of interaction.
+If <emphasis remap='I'>shutdown</emphasis> is
+<function>True</function>,
+the checkpoint is being performed in preparation for the end of the session.
+If <emphasis remap='I'>fast</emphasis> is
+<function>True</function>,
+the client should perform the checkpoint as quickly as possible.
+If <emphasis remap='I'>cancel_shutdown</emphasis> is
+<function>True</function>,
+a
+<function>ShutdownCancelled</function>
+message has been received for the current save operation.
+(See <xref linkend='Resigning_from_a_Session' />.)
+The <emphasis remap='I'>phase</emphasis> is used by manager clients, such as a window manager,
+to distinguish between the first and second phase of a save operation.
+The <emphasis remap='I'>phase</emphasis> will be either 1 or 2.
+The remaining fields in the checkpoint token structure are provided for
+the application to communicate with the shell.
+</para>
+
+<para>
+Upon entry to the first application save callback procedure, the return
+fields in the token have the following initial values:
+<emphasis remap='I'>interact_dialog_type</emphasis> is
+<function>SmDialogNormal</function>;
+<emphasis remap='I'>request_cancel</emphasis> is
+<function>False</function>;
+<emphasis remap='I'>request_next_phase</emphasis> is
+<function>False</function>;
+and <emphasis remap='I'>save_success</emphasis> is
+<function>True</function>.
+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.
+</para>
+
+<para>
+The purpose of the token's <emphasis remap='I'>save_success</emphasis> field is to
+indicate the outcome of the entire operation to the
+session manager and ultimately, to the user.
+Returning
+<function>False</function>
+indicates some portion of the application state
+could not be successfully saved. If any token is returned
+to the shell with <emphasis remap='I'>save_success</emphasis>
+<function>False</function>,
+tokens subsequently received
+by the application for the current save operation will show
+<emphasis remap='I'>save_success</emphasis> as
+<function>False</function>.
+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 <emphasis remap='I'>save_success</emphasis>
+<function>False</function>.
+</para>
+
+<para>
+Session participants that manage and save the state of other clients
+should structure their save or interact callbacks to
+set <emphasis remap='I'>request_next_phase</emphasis> to
+<function>True</function>
+when phase is 1, which will cause the shell to send the
+<function>SaveYourselfPhase2Request</function>
+when the first phase is complete. When the
+<function>SaveYourselfPhase2</function>
+message is received, the shell will invoke the save callbacks a
+second time with <emphasis remap='I'>phase</emphasis> equal to 2.
+Manager clients should save the state of other clients
+when the callbacks are invoked the second time and <emphasis remap='I'>phase</emphasis> equal to 2.
+</para>
+
+<para>
+The application may request additional tokens while a checkpoint is under way,
+and these additional tokens must be returned by an explicit call.
+</para>
+
+<para>
+To request an additional token for a save callback response that has a
+deferred outcome, use
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSessionGetToken'>
+<funcprototype>
+<funcdef>XtCheckpointToken <function>XtSessionGetToken</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Session shell widget which manages session participation.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+function will return NULL if no checkpoint operation is currently under way.
+</para>
+
+<para>
+To indicate the completion of checkpoint processing including user
+interaction, the application must signal the Session shell
+by returning all tokens.
+(See <xref linkend='Interacting_with_the_User_during_a_Checkpoint' /> and
+<xref linkend='Completing_a_Save' />).
+To return a token, use
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSessionReturnToken'>
+<funcprototype>
+<funcdef>void <function>XtSessionReturnToken</function></funcdef>
+ <paramdef>XtCheckpointToken <parameter>token</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>token</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a token that was received as the <emphasis remap='I'>call_data</emphasis> by a procedure
+on the interact callback list or a token that was received by a call to
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+Tokens passed as <emphasis remap='I'>call_data</emphasis> to save callbacks are implicitly
+returned when the save callback procedure returns.
+A save callback procedure should not call
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>
+on the token passed in its <emphasis remap='I'>call_data</emphasis>.
+</para>
+
+<sect3 id="Requesting_Interaction">
+<title>Requesting Interaction</title>
+<para>
+When the token <emphasis remap='I'>interact_style</emphasis> 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
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+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
+<function>InteractRequest</function>
+to the session manager when an interact request is not already outstanding
+for the application.
+</para>
+
+<para>
+The type of interaction dialog that will be requested is specified by
+the <emphasis remap='I'>interact_dialog_type</emphasis> field in the checkpoint token.
+The possible values for <emphasis remap='I'>interact_dialog_type</emphasis> are
+<function>SmDialogError</function>
+and
+<function>SmDialogNormal</function>.
+If a token is returned with <emphasis remap='I'>interact_dialog_type</emphasis> containing
+<function>SmDialogError</function>,
+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.
+</para>
+
+<para>
+When a token is returned with <emphasis remap='I'>save_success</emphasis>
+<function>False</function>
+or <emphasis remap='I'>interact_dialog_type</emphasis>
+<function>SmDialogError</function>,
+tokens subsequently passed to callbacks during the same active
+<function>SaveYourself</function>
+response will reflect these changed values, indicating that
+an error condition has occurred during the checkpoint.
+</para>
+
+<para>
+The <emphasis remap='I'>request_cancel</emphasis> 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 <emphasis remap='I'>request_cancel</emphasis> field is not examined by the shell.
+This is also true of tokens received through a call to
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
+</para>
+</sect3>
+
+<sect3 id="Interacting_with_the_User_during_a_Checkpoint">
+<title>Interacting with the User during a Checkpoint</title>
+<para>
+When the session manager grants the application's request for user interaction,
+the Session shell receives an
+<function>Interact</function>
+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 <emphasis remap='I'>call_data</emphasis>.
+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
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+Returning the token completes the current step and triggers the next step
+in the sequence.
+</para>
+
+<para>
+During interaction the client may request cancellation of a shutdown.
+When a token passed as <emphasis remap='I'>call_data</emphasis> to an interact procedure is returned,
+if <emphasis remap='I'>shutdown</emphasis> is
+<function>True</function>
+and <emphasis remap='I'>cancel_shutdown</emphasis> is
+<function>False</function>,
+<emphasis remap='I'>request_cancel</emphasis> indicates whether the
+application requests that the pending shutdown be cancelled.
+If <emphasis remap='I'>request_cancel</emphasis> is
+<function>True</function>,
+the field will also be
+<function>True</function>
+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
+<function>InteractDone</function>
+message is sent to the session manager, indicating whether
+a pending session shutdown is requested to be cancelled.
+</para>
+</sect3>
+
+<sect3 id="Responding_to_a_Shutdown_Cancellation">
+<title>Responding to a Shutdown Cancellation</title>
+<para>
+Callbacks registered on the cancel callback list are invoked when the
+Session shell processes a
+<function>ShutdownCancelled</function>
+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
+<function>SaveComplete</function>
+or a
+<function>Die</function>
+message.
+The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+
+<para>
+When the shell notices that a pending shutdown has been cancelled,
+the token <emphasis remap='I'>cancel_shutdown</emphasis> field will be
+<function>True</function>
+in tokens subsequently given to the application.
+</para>
+
+<para>
+Receiving notice of a shutdown cancellation does not cancel the
+pending execution of save callbacks or interact callbacks.
+After the cancel callbacks execute, if <emphasis remap='I'>interact_style</emphasis> is not
+<function>SmInteractStyleNone</function>
+and the interact list is not empty,
+the procedures on the interact callback list will be executed
+and passed a token with <emphasis remap='I'>interact_style</emphasis>
+<function>SmInteractStyleNone</function>.
+The application should not interact with the user, and the Session shell
+will not send an
+<function>InteractDone</function>
+message.
+</para>
+</sect3>
+
+<sect3 id="Completing_a_Save">
+<title>Completing a Save</title>
+<para>
+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
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+have been returned by corresponding calls to
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+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
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+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.
+</para>
+
+<para>
+When the application has finished saving state,
+the Session shell will report the result to the session manager by
+sending the
+<function>SaveYourselfDone</function>
+message.
+If the session is continuing, the shell will receive the
+<function>SaveComplete</function>
+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 <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Responding_to_a_Shutdown">
+<title>Responding to a Shutdown</title>
+<para>
+Callbacks registered on the die callback list are invoked when the
+session manager sends a
+<function>Die</function>
+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 <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+</sect2>
+
+<sect2 id="Resigning_from_a_Session">
+<title>Resigning from a Session</title>
+<para>
+When the Session shell widget is destroyed, the destroy method will
+close the connection to the session manager by sending a
+<function>ConnectionClosed</function>
+protocol message and will remove the input callback
+that was watching for session protocol messages.
+</para>
+
+<para>
+When
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+is used to set <emphasis remap='I'>join_session</emphasis> to
+<function>False</function>,
+the set_values method of the Session shell will close the
+connection to the session manager if one exists by sending a
+<function>ConnectionClosed</function>
+message, and <emphasis remap='I'>connection</emphasis> will be set to NULL.
+</para>
+
+<para>
+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 <emphasis remap='I'>join_session</emphasis> to
+<function>False</function>
+before exiting.
+</para>
+
+<para>
+When
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+is used to set <emphasis remap='I'>connection</emphasis> to NULL,
+the Session shell will stop managing the connection, if one exists.
+However, that session connection will not be closed.
+</para>
+
+<para>
+Applications that wish to ensure continuation of a session connection
+beyond the destruction of the shell should first retrieve the
+<emphasis remap='I'>connection</emphasis> resource value,
+then set the <emphasis remap='I'>connection</emphasis> resource to NULL,
+and then they may safely destroy the widget without losing control
+of the session connection.
+</para>
+
+<para>
+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 <emphasis remap='I'>connection</emphasis> to NULL,
+remove the input callback, and
+call the procedures registered on the error callback list.
+The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/specs/CH05.xml b/specs/CH05.xml
new file mode 100644
index 0000000..2c09455
--- /dev/null
+++ b/specs/CH05.xml
@@ -0,0 +1,1063 @@
+<chapter id='Pop_Up_Widgets'>
+<title>Pop-Up Widgets</title>
+<para>
+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.
+Therefore, pop-ups are created and attached differently to their widget parent
+than normal widget children.
+</para>
+
+<para>
+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 <emphasis remap='I'>popup_list</emphasis> field in the
+<function>CorePart</function>
+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
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+to look for all extant children.
+</para>
+
+<para>
+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 <emphasis remap='I'>child</emphasis> always refers to a normal, geometry-managed widget
+on the composite widget's list of children, and the term
+<emphasis remap='I'>pop-up child</emphasis> always refers to a
+widget on the pop-up list.
+</para>
+
+<sect1 id="Pop_Up_Widget_Types">
+<title>Pop-Up Widget Types</title>
+<para>
+There are three kinds of pop-up widgets:
+</para>
+
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Modeless pop-ups
+ </para>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Modal pop-ups
+ </para>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Spring-loaded pop-ups
+ </para>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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 Intrinsics.
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Creating_a_Pop_Up_Shell">
+<title>Creating a Pop-Up Shell</title>
+<para>
+For a widget to be popped up,
+it must be the child of a pop-up shell widget.
+None of the Intrinsics-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.
+</para>
+
+<para>
+To create a pop-up shell, use
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreatePopupShell'>
+<funcprototype>
+<funcdef>Widget <function>XtCreatePopupShell</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>
+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
+<emphasis remap='I'>children</emphasis> list,
+attaches the shell to the parent's <emphasis remap='I'>popup_list</emphasis> directly.
+</para>
+
+<para>
+The screen resource for this widget is determined by first scanning
+<emphasis remap='I'>args</emphasis> for the XtNscreen argument. If no XtNscreen argument is
+found, the resource database associated with the parent's screen
+is queried for the resource <emphasis remap='I'>name</emphasis>.screen, class
+<emphasis remap='I'>Class</emphasis>.Screen where <emphasis remap='I'>Class</emphasis> is the <emphasis remap='I'>class_name</emphasis>
+field from the
+<function>CoreClassPart</function>
+of the specified <emphasis remap='I'>widget_class</emphasis>.
+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
+<emphasis remap='I'>args</emphasis>.
+</para>
+
+<para>
+A spring-loaded pop-up invoked from a translation table via
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To create a pop-up shell using varargs lists, use
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaCreatePopupShell'>
+<funcprototype>
+<funcdef>Widget <function>XtVaCreatePopupShell</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef><parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>...</term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>
+with <emphasis remap='I'>the</emphasis> args and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list as
+described in Section 2.5.1.
+</para>
+</sect1>
+
+<sect1 id="Creating_Pop_Up_Children">
+<title>Creating Pop-Up Children</title>
+<para>
+Once a pop-up shell is created,
+the single child of the pop-up shell can be created
+either statically or dynamically.
+</para>
+
+<para>
+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
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+(or, in general,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>)
+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
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+Pop-up child creation does not map the pop-up,
+even if you create the child and call
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on the pop-up shell.
+</para>
+
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Mapping_a_Pop_Up_Widget">
+<title>Mapping a Pop-Up Widget</title>
+<para>
+Pop-ups can be popped up through several mechanisms:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A call to
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+or
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+One of the supplied callback procedures
+<xref linkend='XtCallbackNone' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>,
+or
+<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The standard translation action
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+Some of these routines take an argument of type
+<function>XtGrabKind</function>,
+which is defined as
+</para>
+<literallayout >
+typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind;
+</literallayout>
+
+<para>
+The create_popup_child_proc procedure pointer
+in the shell widget instance record is of type
+<xref linkend='XtCreatePopupChildProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreatePopupChildProc'>
+<funcprototype>
+<funcdef>void <function>*XtCreatePopupChildProc</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shell widget being popped up.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+To map a pop-up from within an application, use
+<xref linkend='XtPopup' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtPopup'>
+<funcprototype>
+<funcdef>void <function>XtPopup</function></funcdef>
+ <paramdef>Widget <parameter>popup_shell</parameter></paramdef>
+ <paramdef>XtGrabKind <parameter>grab_kind</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>popup_shell</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>grab_kind</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the way in which user events should be constrained.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+function performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Calls
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
+to ensure <emphasis remap='I'>popup_shell</emphasis>'s class is a subclass of
+<function>shellWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Raises the window and returns if the shell's <emphasis remap='I'>popped_up</emphasis> field is already
+<function>True</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the callback procedures on the shell's <emphasis remap='I'>popup_callback</emphasis> list,
+specifying a pointer to the value of <emphasis remap='I'>grab_kind</emphasis> as the <emphasis remap='I'>call_data</emphasis>
+argument.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Sets the shell <emphasis remap='I'>popped_up</emphasis> field to
+<function>True</function>,
+the shell <emphasis remap='I'>spring_loaded</emphasis> field to
+<function>False</function>,
+and the shell <emphasis remap='I'>grab_kind</emphasis> field from <emphasis remap='I'>grab_kind</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the shell's <emphasis remap='I'>create_popup_child_proc</emphasis> field is non-NULL,
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+calls it with <emphasis remap='I'>popup_shell</emphasis> as the parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If <emphasis remap='I'>grab_kind</emphasis> is either
+<function>XtGrabNonexclusive</function>
+or
+<function>XtGrabExclusive</function>,
+it calls
+ </para>
+<literallayout >
+XtAddGrab(<emphasis remap='I'>popup_shell</emphasis>, (<emphasis remap='I'>grab_kind</emphasis> == XtGrabExclusive), False)
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+with <emphasis remap='I'>popup_shell</emphasis> specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XMapRaised</function>
+with the window of <emphasis remap='I'>popup_shell</emphasis>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To map a spring-loaded pop-up from within an application, use
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtPopupSpringLoaded'>
+<funcprototype>
+<funcdef>void <function>XtPopupSpringLoaded</function></funcdef>
+ <paramdef>Widget <parameter>popup_shell</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>popup_shell</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shell widget to be popped up.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>
+function performs exactly as
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+except that it sets the shell <emphasis remap='I'>spring_loaded</emphasis> field to
+<function>True</function>
+and always calls
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+with <emphasis remap='I'>exclusive</emphasis>
+<function>True</function>
+and <emphasis remap='I'>spring-loaded</emphasis>
+<function>True</function>.
+</para>
+
+<para>
+To map a pop-up from a given widget's callback list,
+you also can register one of the
+<xref linkend='XtCallbackNone' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>,
+or
+<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>
+convenience routines as callbacks, using the pop-up shell widget as the
+client data.
+</para>
+
+<funcsynopsis id='XtCallbackNone'>
+<funcprototype>
+<funcdef>void <function>XtCallbackNone</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pop-up shell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback data argument,
+which is not used by this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<funcsynopsis id='XtCallbackNonexclusive'>
+<funcprototype>
+<funcdef>void <function>XtCallbackNonexclusive</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pop-up shell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback data argument,
+which is not used by this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<funcsynopsis id='XtCallbackExclusive'>
+<funcprototype>
+<funcdef>void <function>XtCallbackExclusive</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pop-up shell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback data argument,
+which is not used by this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCallbackNone' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>,
+and
+<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>
+functions call
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+with the shell specified by the <emphasis remap='I'>client_data</emphasis> argument
+and <emphasis remap='I'>grab_kind</emphasis> set as the name specifies.
+<xref linkend='XtCallbackNone' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>,
+and
+<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>
+specify
+<function>XtGrabNone</function>,
+<function>XtGrabNonexclusive</function>,
+and
+<function>XtGrabExclusive</function>,
+respectively.
+Each function then sets the widget that executed the callback list
+to be insensitive by calling
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>.
+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.
+</para>
+
+<para>
+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
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>,
+or its synonym,
+<function>MenuPopup</function>.
+From a translation writer's point of view,
+the definition for this translation action is
+</para>
+
+<funcsynopsis id='XtMenuPopup'>
+<funcprototype>
+<funcdef>void <function>XtMenuPopup</function></funcdef>
+ <paramdef>String <parameter>shell_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>shell_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the shell widget to pop up.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+is known to the translation manager,
+which registers the corresponding built-in action procedure
+<function>XtMenuPopupAction</function>
+using
+<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>
+specifying <emphasis remap='I'>owner_events</emphasis>
+<function>True</function>,
+<emphasis remap='I'>event_mask</emphasis>
+<function>ButtonPressMask</function>
+<function>|</function>
+<function>ButtonReleaseMask</function>,
+and <emphasis remap='I'>pointer_mode</emphasis> and <emphasis remap='I'>keyboard_mode</emphasis>
+<function>GrabModeAsync</function>.
+</para>
+
+<para>
+If
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+is invoked on
+<function>ButtonPress</function>,
+it calls
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>
+on the specified shell widget.
+If
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+is invoked on
+<function>KeyPress</function>
+or
+<function>EnterWindow</function>,
+it calls
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+on the specified shell widget with <emphasis remap='I'>grab_kind</emphasis> set to
+<function>XtGrabNonexclusive</function>.
+Otherwise, the translation manager generates a
+warning message and ignores the action.
+</para>
+
+<para>
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+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
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+gets to the application top-level shell widget and has not
+found a matching shell, it generates a warning and returns immediately.
+</para>
+</sect1>
+
+<sect1 id="Unmapping_a_Pop_Up_Widget">
+<title>Unmapping a Pop-Up Widget</title>
+<para>
+Pop-ups can be popped down through several mechanisms:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A call to
+<xref linkend='XtPopdown' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The supplied callback procedure
+<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The standard translation action
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To unmap a pop-up from within an application, use
+<xref linkend='XtPopdown' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtPopdown'>
+<funcprototype>
+<funcdef>void <function>XtPopdown</function></funcdef>
+ <paramdef>Widget <parameter>popup_shell</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>popup_shell</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shell widget to pop down.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtPopdown' xrefstyle='select: title'/>
+function performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Calls
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
+to ensure <emphasis remap='I'>popup_shell</emphasis>'s class is a subclass of
+<function>shellWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Checks that the <emphasis remap='I'>popped_up</emphasis> field of <emphasis remap='I'>popup_shell</emphasis> is
+<function>True</function>;
+otherwise, it returns immediately.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unmaps <emphasis remap='I'>popup_shell</emphasis>'s window and, if <emphasis remap='I'>override_redirect</emphasis> is
+<function>False</function>,
+sends a synthetic
+<function>UnmapNotify</function>
+event as specified by the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If <emphasis remap='I'>popup_shell</emphasis>'s <emphasis remap='I'>grab_kind</emphasis> is either
+<function>XtGrabNonexclusive</function>
+or
+<function>XtGrabExclusive</function>,
+it calls
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Sets <emphasis remap='I'>popup_shell</emphasis>'s <emphasis remap='I'>popped_up</emphasis> field to
+<function>False</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the callback procedures on the shell's <emphasis remap='I'>popdown_callback</emphasis> list,
+specifying a pointer to the value of the shell's <emphasis remap='I'>grab_kind</emphasis> field
+as the <emphasis remap='I'>call_data</emphasis> argument.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To pop down a pop-up from a callback list, you may use the callback
+<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallbackPopdown'>
+<funcprototype>
+<funcdef>void <function>XtCallbackPopdown</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the
+<function>XtPopdownID</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback data argument,
+which is not used by this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>
+function casts the <emphasis remap='I'>client_data</emphasis> parameter to a pointer of type
+<function>XtPopdownID</function>.
+</para>
+<literallayout >
+typedef struct {
+ Widget shell_widget;
+ Widget enable_widget;
+} XtPopdownIDRec, *XtPopdownID;
+</literallayout>
+<para>
+The <emphasis remap='I'>shell_widget</emphasis> is the pop-up shell to pop down,
+and the <emphasis remap='I'>enable_widget</emphasis> is usually the widget that was used to pop it up
+in one of the pop-up callback convenience procedures.
+</para>
+
+<para>
+<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>
+calls
+<xref linkend='XtPopdown' xrefstyle='select: title'/>
+with the specified <emphasis remap='I'>shell_widget</emphasis>
+and then calls
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+to resensitize <emphasis remap='I'>enable_widget</emphasis>.
+</para>
+
+<para>
+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
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+or its synonym,
+<function>MenuPopdown</function>.
+From a translation writer's point of view,
+the definition for this translation action is
+</para>
+
+<funcsynopsis id='XtMenuPopdown'>
+<funcprototype>
+<funcdef>void <function>XtMenuPopdown</function></funcdef>
+ <paramdef>String <parameter>shell_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>shell_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the shell widget to pop down.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If a shell name is not given,
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+calls
+<xref linkend='XtPopdown' xrefstyle='select: title'/>
+with the widget for which the translation is specified.
+If <emphasis remap='I'>shell_name</emphasis> is specified in the translation table,
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+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
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+gets to the application top-level shell widget
+and cannot find a matching shell,
+it generates a warning and returns immediately.
+</para>
+</sect1>
+</chapter>
diff --git a/specs/CH06.xml b/specs/CH06.xml
new file mode 100644
index 0000000..7ff51bf
--- /dev/null
+++ b/specs/CH06.xml
@@ -0,0 +1,1369 @@
+<chapter id='Geometry_Management'>
+<title>Geometry Management</title>
+
+<para>
+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.
+</para>
+
+<para>
+To resolve physical layout conflicts between sibling widgets and between
+a widget and its parent, the Intrinsics provide the geometry management mechanism.
+Almost all
+composite
+widgets have a geometry manager specified in the <emphasis remap='I'>geometry_manager</emphasis> 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.
+</para>
+
+<sect1 id="Initiating_Geometry_Changes">
+<title>Initiating Geometry Changes</title>
+
+<para>
+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
+<function>XtMove\%Widget</function>,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>,
+or
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+A child must ask its parent for a geometry change by calling
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>.
+An application or other client code initiates a geometry change by calling
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>.
+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
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>.
+The requesting child may be given special treatment; see
+<xref linkend='Child_Geometry_Management_The_geometry_manager_Procedure' />.
+It can simultaneously move and resize a child with a single call to
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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 <xref linkend='Creating_Widgets' /> and
+<xref linkend='Realizing_Widgets' />.
+</para>
+
+<note>
+<orderedlist>
+ <listitem>
+ <para>
+The Intrinsics 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
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+that will generate a stacking geometry request.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+After a successful geometry request (one that returned
+<function>XtGeometryYes</function>),
+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.
+ </para>
+ </listitem>
+</orderedlist>
+</note>
+</sect1>
+
+<sect1 id="General_Geometry_Manager_Requests">
+<title>General Geometry Manager Requests</title>
+<para>
+When making a geometry request, the child specifies an
+<function>XtWidgetGeometry</function>
+structure.
+</para>
+
+<literallayout >
+typedef unsigned long XtGeometryMask;
+typedef struct {
+ XtGeometryMask request_mode;
+ Position x, y;
+ Dimension width, height;
+ Dimension border_width;
+ Widget sibling;
+ int stack_mode;
+} XtWidgetGeometry;
+</literallayout>
+
+<para>
+To make a general geometry manager request from a widget, use
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMakeGeometryRequest'>
+<funcprototype>
+<funcdef>XtGeometryResult <function>XtMakeGeometryRequest</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>reply_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the desired widget geometry (size, position, border width,
+and stacking order).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>reply_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the allowed widget size, or may be NULL
+if the requesting widget is not interested in handling
+<function>XtGeometryAlmost</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+Depending on the condition,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+performs the following:
+</para>
+
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the widget is unmanaged or the widget's parent is not realized,
+it makes the changes and returns
+<function>XtGeometryYes</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent's class is not a subclass of
+<function>compositeWidgetClass</function>
+or the parent's <emphasis remap='I'>geometry_manager</emphasis> field is NULL,
+it issues an error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget's <emphasis remap='I'>being_destroyed</emphasis> field is
+<function>True</function>,
+it returns
+<function>XtGeometryNo</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and
+<emphasis remap='I'>border_width</emphasis> fields are
+all equal to the requested values,
+it returns
+<function>XtGeometryYes</function>;
+otherwise, it calls the parent's geometry_manager procedure
+with the given parameters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent's geometry manager returns
+<function>XtGeometryYes</function>
+and if
+<function>XtCWQueryOnly</function>
+is not set in <emphasis remap='I'>request-&gt;request_mode</emphasis>
+and if the widget is realized,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+calls the
+<function>XConfigureWindow</function>
+Xlib function to reconfigure the widget's window (set its size, location,
+and stacking order as appropriate).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the geometry manager returns
+<function>XtGeometryDone</function>,
+the change has been approved and actually has been done.
+In this case,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+does no configuring and returns
+<function>XtGeometryYes</function>.
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+never returns
+<function>XtGeometryDone</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Otherwise,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+just returns the resulting value from the parent's geometry manager.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+Children of primitive widgets are always unmanaged; therefore,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+always returns
+<function>XtGeometryYes</function>
+when called by a child of a primitive widget.
+</para>
+
+<para>
+The return codes from geometry managers are
+</para>
+
+<literallayout >
+typedef enum {
+ XtGeometryYes,
+ XtGeometryNo,
+ XtGeometryAlmost,
+ XtGeometryDone
+} XtGeometryResult;
+</literallayout>
+
+<para>
+The <emphasis remap='I'>request_mode</emphasis> definitions are from
+<function>&lt;X11/X.h&gt;</function>.
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWX</function></entry>
+ <entry>(1&lt;&lt;0)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWY</function></entry>
+ <entry>(1&lt;&lt;1)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWWidth</function></entry>
+ <entry>(1&lt;&lt;2)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWHeight</function></entry>
+ <entry>(1&lt;&lt;3)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWBorderWidth</function></entry>
+ <entry>(1&lt;&lt;4)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWSibling</function></entry>
+ <entry>(1&lt;&lt;5)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWStackMode</function></entry>
+ <entry>(1&lt;&lt;6)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics also support the following value.
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>XtCWQueryOnly</function></entry>
+ <entry>(1&lt;&lt;7)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<function>XtCWQueryOnly</function>
+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.
+</para>
+
+<para>
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>,
+like the
+<function>XConfigureWindow</function>
+Xlib function, uses <emphasis remap='I'>request_mode</emphasis> to determine which fields in the
+<function>XtWidgetGeometry</function>
+structure the caller wants to specify.
+</para>
+
+<para>
+The <emphasis remap='I'>stack_mode</emphasis> definitions are from
+<function>&lt;X11/X.h&gt;</function>:
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>Above</function></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>Below</function></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>TopIf</function></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>BottomIf</function></entry>
+ <entry>3</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>Opposite</function></entry>
+ <entry>4</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics also support the following value.
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>XtSMDontChange</function></entry>
+ <entry>5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+For definition and behavior of
+<function>Above</function>,
+<function>Below</function>,
+<function>TopIf</function>,
+<function>BottomIf</function>,
+and
+<function>Opposite</function>,
+<olink targetdoc='libX11' targetptr='Configuring_Windows' >BLAH</olink>
+in <olink targetptr='libX11' targetdoc='libX11'>Xlib — C Language X Interface.</olink>.
+<function>XtSMDontChange</function>
+indicates that the widget wants its current stacking order preserved.
+</para>
+</sect1>
+
+<sect1 id="Resize_Requests">
+<title>Resize Requests</title>
+<para>
+To make a simple resize request from a widget, you can use
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+as an alternative to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMakeResizeRequest'>
+<funcprototype>
+<funcdef>typedef XtGeometryResult <function>XtMakeResizeRequest</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Dimension <parameter>width</parameter></paramdef>
+ <paramdef>Dimension *<parameter>width_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the desired widget width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the allowed widget width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+function, a simple interface to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>,
+creates an
+<function>XtWidgetGeometry</function>
+structure and specifies that width and height should change
+by setting <emphasis remap='I'>request_mode</emphasis> to
+<function>CWWidth</function>
+<function>|</function>
+<function>CWHeight</function>.
+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
+<function>XtGeometryAlmost</function>,
+<emphasis remap='I'>width_return</emphasis> and <emphasis remap='I'>height_return</emphasis> contain a compromise width and height.
+If these are acceptable,
+the widget should immediately call
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+again and request that the compromise width and height be applied.
+If the widget is not interested in
+<function>XtGeometryAlmost</function>
+replies,
+it can pass NULL for <emphasis remap='I'>width_return</emphasis> and <emphasis remap='I'>height_return</emphasis>.
+</para>
+</sect1>
+
+<sect1 id="Potential_Geometry_Changes">
+<title>Potential Geometry Changes</title>
+<para>
+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
+<function>XtCWQueryOnly</function>
+in the intermediate request.
+</para>
+
+<para>
+When
+<function>XtCWQueryOnly</function>
+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
+<function>XtGeometryAlmost</function>,
+the geometry manager needs to cache the entire
+reply geometry in the event the child accepts the parent's compromise.
+</para>
+
+<para>
+If the grandparent's response was
+<function>XtGeometryAlmost</function>,
+it may also be necessary to cache the entire reply geometry from
+the grandparent when
+<function>XtCWQueryOnly</function>
+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.
+</para>
+
+<para>
+Note that a compromise geometry returned with
+<function>XtGeometryAlmost</function>
+is guaranteed only for the next call to the same widget;
+therefore, a cache of size 1 is sufficient.
+</para>
+</sect1>
+
+<sect1 id="Child_Geometry_Management_The_geometry_manager_Procedure">
+<title>Child Geometry Management: The geometry_manager Procedure</title>
+<para>
+The geometry_manager procedure pointer in a composite widget class is of type
+<xref linkend='XtGeometryHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGeometryHandler'>
+<funcprototype>
+<funcdef>XtGeometryResult <function>*XtGeometryHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>geometry_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the widget making the request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the new geometry the child desires.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>geometry_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes a geometry structure in which the geometry manager may store a
+compromise.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+A class can inherit its superclass's geometry manager during class
+initialization.
+</para>
+
+<para>
+A bit set to zero in the request's <emphasis remap='I'>request_mode</emphasis>
+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.
+</para>
+
+<para>
+If the geometry manager can satisfy all changes requested
+and if
+<function>XtCWQueryOnly</function>
+is not specified,
+it updates the widget's <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> fields
+appropriately.
+Then, it returns
+<function>XtGeometryYes</function>,
+and the values pointed to by the <emphasis remap='I'>geometry_return</emphasis> argument are undefined.
+The widget's window is moved and resized automatically by
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Homogeneous composite widgets often find it convenient to treat the widget
+making the request the same as any other widget, including reconfiguring
+it using
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+as part of its layout process, unless
+<function>XtCWQueryOnly</function>
+is specified.
+If it does this,
+it should return
+<function>XtGeometryDone</function>
+to inform
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+that it does not need to do the configuration itself.
+</para>
+
+<note>
+<para>
+To remain
+compatible with layout techniques used in older widgets (before
+<function>XtGeometryDone</function>
+was added to the Intrinsics), a geometry manager should avoid using
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+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.
+</para>
+</note>
+
+<para>
+Although
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+resizes the widget's window
+(if the geometry
+manager returns
+<function>XtGeometryYes ),</function>
+it does not call the widget class's resize procedure.
+The requesting widget must perform whatever
+resizing calculations are needed explicitly.
+</para>
+
+<para>
+If the geometry manager disallows the request,
+the widget cannot change its geometry.
+The values pointed to by <emphasis remap='I'>geometry_return</emphasis> are undefined,
+and the geometry manager returns
+<function>XtGeometryNo</function>.
+</para>
+
+<para>
+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
+<emphasis remap='I'>geometry_return</emphasis> with the actual changes
+it is willing to make, including an appropriate <emphasis remap='I'>request_mode</emphasis> mask, and returns
+<function>XtGeometryAlmost</function>.
+If a bit in <emphasis remap='I'>geometry_return-&gt;request_mode</emphasis> is zero,
+the geometry manager agrees not to change the corresponding value
+if <emphasis remap='I'>geometry_return</emphasis> is used immediately
+in a new request.
+If a bit is 1,
+the geometry manager does change that element to the corresponding
+value in <emphasis remap='I'>geometry_return</emphasis>.
+More bits may be set in <emphasis remap='I'>geometry_return-&gt;request_mode</emphasis>
+than in the original request if
+the geometry manager intends to change other fields should the
+child accept the compromise.
+</para>
+
+<para>
+When
+<function>XtGeometryAlmost</function>
+is returned,
+the widget must decide if the compromise suggested in <emphasis remap='I'>geometry_return</emphasis>
+is acceptable.
+If it is, the widget must not change its geometry directly;
+rather, it must make another call to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<para>
+If the next geometry request from this child uses the
+<emphasis remap='I'>geometry_return</emphasis> values filled in by the geometry manager with an
+<function>XtGeometryAlmost</function>
+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
+<function>XtGeometryYes</function>.
+However,
+dynamic behavior in
+the user's window manager may affect the final outcome.
+</para>
+
+<para>
+To return
+<function>XtGeometryYes</function>,
+the geometry manager frequently rearranges the position of other managed
+children by calling
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>.
+However, a few geometry managers may sometimes change the
+size of other managed children by calling
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+If
+<function>XtCWQueryOnly</function>
+is specified,
+the geometry manager must return data describing
+how it would react to this geometry
+request without actually moving or resizing any widgets.
+</para>
+
+<para>
+Geometry managers must not assume that the <emphasis remap='I'>request</emphasis>
+and <emphasis remap='I'>geometry_return</emphasis> 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.
+</para>
+</sect1>
+
+<sect1 id="Widget_Placement_and_Sizing">
+<title>Widget Placement and Sizing</title>
+<para>
+To move a sibling widget of the child making the geometry request,
+the parent uses
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMoveWidget'>
+<funcprototype>
+<funcdef>void <function>XtMoveWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Position <parameter>x</parameter></paramdef>
+ <paramdef>Position <parameter>y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>
+writes the new <emphasis remap='I'>x</emphasis> and <emphasis remap='I'>y</emphasis> values into the object
+and, if the object is a widget and is realized, issues an Xlib
+<function>XMoveWindow</function>
+call on the widget's window.
+</para>
+
+<para>
+To resize a sibling widget of the child making the geometry request,
+the parent uses
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResizeWidget'>
+<funcprototype>
+<funcdef>void <function>XtResizeWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Dimension <parameter>width</parameter></paramdef>
+ <paramdef>Dimension <parameter>height</parameter></paramdef>
+ <paramdef>Dimension <parameter>border_width</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget size.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+writes the new <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis> values into
+the object and, if the object is a widget and is realized, issues an
+<function>XConfigureWindow</function>
+call on the widget's window.
+</para>
+
+<para>
+If the new width or height is different from the old values,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+calls the object's resize procedure to notify it of the size change.
+</para>
+
+<para>
+To move and resize the sibling widget of the child making the geometry request,
+the parent uses
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConfigureWidget'>
+<funcprototype>
+<funcdef>void <function>XtConfigureWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Position <parameter>x</parameter></paramdef>
+ <paramdef>Position <parameter>y</parameter></paramdef>
+ <paramdef>Dimension <parameter>width</parameter></paramdef>
+ <paramdef>Dimension <parameter>height</parameter></paramdef>
+ <paramdef>Dimension <parameter>border_width</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget size.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+function returns immediately if the specified new geometry fields
+are all equal to the current values.
+Otherwise,
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+writes the new <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> values
+into the object and, if the object is a widget and is realized, makes an Xlib
+<function>XConfigureWindow</function>
+call on the widget's window.
+</para>
+
+<para>
+If the new width or height is different from its old value,
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+calls the object's resize procedure to notify it of the size change;
+otherwise, it simply returns.
+</para>
+
+<para>
+To resize a child widget that already has the new values of its width,
+height, and border width, the parent uses
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResizeWindow'>
+<funcprototype>
+<funcdef>void <function>XtResizeWindow</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>
+function calls the
+<function>XConfigureWindow</function>
+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.
+</para>
+
+<para>
+There are very few times to use
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>;
+instead, the parent should use
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Preferred_Geometry">
+<title>Preferred Geometry</title>
+<para>
+Some parents may be willing to adjust their layouts to accommodate the
+preferred geometries of their children.
+They can use
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+to obtain the preferred geometry
+and, as they see fit, can use or ignore any portion of the response.
+</para>
+
+<para>
+To query a child widget's preferred geometry, use
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtQueryGeometry'>
+<funcprototype>
+<funcdef>XtGeometryResult <function>XtQueryGeometry</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>intended</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>preferred_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>intended</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new geometry the parent plans to give to the child, or
+NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>preferred_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the child widget's preferred geometry.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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 <emphasis remap='I'>intended.request_mode</emphasis>,
+and calls
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>.
+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.
+</para>
+
+<para>
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+clears all bits in the <emphasis remap='I'>preferred_return-&gt;request_mode</emphasis>
+field and checks the
+<emphasis remap='I'>query_geometry</emphasis> field of the specified widget's class record.
+If <emphasis remap='I'>query_geometry</emphasis> is not NULL,
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+calls the query_geometry procedure and passes as arguments the
+specified widget, <emphasis remap='I'>intended</emphasis>, and <emphasis remap='I'>preferred_return</emphasis> structures.
+If the <emphasis remap='I'>intended</emphasis> argument is NULL,
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+replaces it with a pointer to an
+<function>XtWidgetGeometry</function>
+structure with <emphasis remap='I'>request_mode</emphasis> equal to zero before calling the
+query_geometry procedure.
+</para>
+
+<note>
+<para>
+If
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+is called from within a geometry_manager
+procedure for the widget that issued
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>,
+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.
+</para>
+</note>
+
+<para>
+The query_geometry procedure pointer is of type
+<xref linkend='XtGeometryHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='_XtGeometryHandler'>
+<funcprototype>
+<funcdef>typedef XtGeometryResult <function>(*XtGeometryHandler)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>preferred_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the child widget whose preferred geometry is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the geometry changes that the parent plans to make.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>preferred_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes a structure in which the child returns its preferred geometry.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The query_geometry procedure is expected to examine the bits set in
+<emphasis remap='I'>request-&gt;request_mode</emphasis>, evaluate the preferred geometry of the widget,
+and store the result in <emphasis remap='I'>preferred_return</emphasis>
+(setting the bits in <emphasis remap='I'>preferred_return-&gt;request_mode</emphasis> corresponding
+to those geometry fields that it cares about).
+If the proposed geometry change is acceptable without modification,
+the query_geometry procedure should return
+<function>XtGeometryYes</function>.
+If at least one field in <emphasis remap='I'>preferred_return</emphasis>
+with a bit set in <emphasis remap='I'>preferred_return-&gt;request_mode</emphasis>
+is different
+from the corresponding field in <emphasis remap='I'>request</emphasis>
+or if a bit was set in <emphasis remap='I'>preferred_return-&gt;request_mode</emphasis>
+that was not set in the request,
+the query_geometry procedure should return
+<function>XtGeometryAlmost</function>.
+If the preferred geometry is identical to the current geometry,
+the query_geometry procedure should return
+<function>XtGeometryNo</function>.
+</para>
+
+<note><para>
+The query_geometry procedure may assume
+that no
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+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.
+</para></note>
+
+<para>
+After calling the query_geometry procedure
+or if the <emphasis remap='I'>query_geometry</emphasis> field is NULL,
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+examines all the unset bits in <emphasis remap='I'>preferred_return-&gt;request_mode</emphasis>
+and sets the corresponding fields in <emphasis remap='I'>preferred_return</emphasis>
+to the current values from the widget instance.
+If
+<function>CWStackMode</function>
+is not set,
+the <emphasis remap='I'>stack_mode</emphasis> field is set to
+<function>XtSMDontChange</function>.
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+returns the value returned by the query_geometry procedure or
+<function>XtGeometryYes</function>
+if the <emphasis remap='I'>query_geometry</emphasis> field is NULL.
+</para>
+
+<para>
+Therefore, the caller can interpret a return of
+<function>XtGeometryYes</function>
+as not needing to evaluate the contents of the reply and, more important,
+not needing to modify its layout plans.
+A return of
+<function>XtGeometryAlmost</function>
+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
+<function>XtGeometryNo</function>
+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 <emphasis remap='I'>preferred_return</emphasis> structure contains complete
+geometry information for the child.
+</para>
+
+<para>
+Parents are expected to call
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+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.
+</para>
+</sect1>
+
+<sect1 id="Size_Change_Management_The_resize_Procedure">
+<title>Size Change Management: The resize Procedure</title>
+<para>
+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
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>,
+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
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+</para>
+
+<para>
+If a class need not recalculate anything when a widget is resized,
+it can specify NULL for the <emphasis remap='I'>resize</emphasis> 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 <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> 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
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+call from its resize procedure.
+</para>
+</sect1>
+</chapter>
diff --git a/specs/CH07.xml b/specs/CH07.xml
new file mode 100644
index 0000000..7ea7259
--- /dev/null
+++ b/specs/CH07.xml
@@ -0,0 +1,4989 @@
+<chapter id='Event_Management'>
+<title>Event Management</title>
+<para>
+While Xlib allows the reading and processing of events anywhere in an application,
+widgets in the X Toolkit 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.
+</para>
+
+<para>
+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 Intrinsics is
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The event manager is a collection of functions to perform the following tasks:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Add or remove event sources other than X server events (in particular,
+timer interrupts, file input, or POSIX signals).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Query the status of event sources.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Add or remove procedures to be called when an event occurs for a particular
+widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Enable and
+disable the dispatching of user-initiated events (keyboard and pointer events)
+for a particular widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Constrain the dispatching of events to a cascade of pop-up widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Register procedures to be called when specific events arrive.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Register procedures to be called when the Intrinsics will block.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Enable safe operation in a multi-threaded environment.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+<sect1 id="Adding_and_Deleting_Additional_Event_Sources">
+<title>Adding and Deleting Additional Event Sources</title>
+<para>
+While most applications are driven only by X events,
+some applications need to incorporate other sources of input
+into the Intrinsics event-handling mechanism.
+The event manager provides routines to integrate notification of timer events
+and file data pending into this mechanism.
+</para>
+
+<para>
+The next section describes functions that provide input gathering from files.
+The application registers the files with the Intrinsics read routine.
+When input is pending on one of the files,
+the registered callback procedures are invoked.
+</para>
+<sect2 id="Adding_and_Removing_Input_Sources">
+<title>Adding and Removing Input Sources</title>
+<para>
+To register a new file as an input source for a given application context, use
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddInput'>
+<funcprototype>
+<funcdef>XtInputId <function>XtAppAddInput</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>int <parameter>source</parameter></paramdef>
+ <paramdef>XtPointer <parameter>condition</parameter></paramdef>
+ <paramdef>XtInputCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source file descriptor on a POSIX-based system
+or other operating-system-dependent device specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>condition</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mask that indicates a read, write, or exception condition
+or some other operating-system-dependent condition.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the condition is found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+function registers with the Intrinsics read routine a new source of events,
+which is usually file input but can also be file output.
+Note that <emphasis remap='I'>file</emphasis> should be loosely interpreted to mean any sink
+or source of data.
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+also specifies the conditions under which the source can generate events.
+When an event is pending on this source,
+the callback procedure is called.
+</para>
+
+<para>
+The legal values for the <emphasis remap='I'>condition</emphasis> argument are operating-system-dependent.
+On a POSIX-based system,
+<emphasis remap='I'>source</emphasis> is a file number and the condition is some union of the following:
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtInputReadMask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies that <emphasis remap='I'>proc</emphasis> is to be called when <emphasis remap='I'>source</emphasis> has data to be read.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtInputWriteMask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies that <emphasis remap='I'>proc</emphasis> is to be called when <emphasis remap='I'>source</emphasis> is ready
+for writing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtInputExceptMask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies that <emphasis remap='I'>proc</emphasis> is to be called when <emphasis remap='I'>source</emphasis> has
+exception data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+Callback procedure pointers used to handle file events are of
+type
+<xref linkend='XtInputCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInputCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtInputCallbackProc)</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>int *<parameter>source</parameter></paramdef>
+ <paramdef>XtInputId *<parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<function>XtApp\%AddInput</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the source file descriptor generating the event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the id returned from the corresponding
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+
+<para>
+To discontinue a source of input, use
+<xref linkend='XtRemoveInput' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveInput'>
+<funcprototype>
+<funcdef>void <function>XtRemoveInput</function></funcdef>
+ <paramdef>XtInputId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id returned from the corresponding
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveInput' xrefstyle='select: title'/>
+function causes the Intrinsics read routine to stop watching for events
+from the file source specified by <emphasis remap='I'>id</emphasis>.
+</para>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtRemoveInput' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+</sect2>
+
+<sect2 id="Adding_and_Removing_Blocking_Notifications">
+<title>Adding and Removing Blocking Notifications</title>
+<para>
+Occasionally it is desirable for an application to receive notification
+when the Intrinsics 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.
+</para>
+
+<para>
+To register a hook that is called immediately prior to event blocking, use
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddBlockHook'>
+<funcprototype>
+<funcdef>XtBlockHookId <function>XtAppAddBlockHook</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtBlockHookProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called before blocking.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>
+function registers the specified procedure and returns an identifier for it.
+The hook procedure <emphasis remap='I'>proc</emphasis> is called at any time in the future when
+the Intrinsics are about to block pending some input.
+</para>
+
+<para>
+The procedure pointers used to provide notification of event blocking
+are of type
+<xref linkend='XtBlockHookProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtBlockHookProc'>
+<funcprototype>
+<funcdef>void <function>*XtBlockHookProc</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<function>XtApp\%AddBlockHook</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To discontinue the use of a procedure for blocking notification, use
+<xref linkend='XtRemoveBlockHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveBlockHook'>
+<funcprototype>
+<funcdef>void <function>XtRemoveBlockHook</function></funcdef>
+ <paramdef>XtBlockHookId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the identifier returned from the corresponding call to
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveBlockHook' xrefstyle='select: title'/>
+function removes the specified procedure from the list of procedures
+that are called by the Intrinsics read routine before blocking on event sources.
+</para>
+</sect2>
+
+<sect2 id="Adding_and_Removing_Timeouts">
+<title>Adding and Removing Timeouts</title>
+<para>
+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.
+</para>
+
+<para>
+To register a timeout callback, use
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddTimeOut'>
+<funcprototype>
+<funcdef>XtIntervalId <function>XtAppAddTimeOut</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>unsigned long <parameter>interval</parameter></paramdef>
+ <paramdef>XtTimerCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context for which the timer is to be set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>interval</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time interval in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the time expires.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>
+function creates a timeout and returns an identifier for it.
+The timeout value is set to <emphasis remap='I'>interval</emphasis>.
+The callback procedure <emphasis remap='I'>proc</emphasis> is called when
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+is next called after the time interval elapses,
+and then the timeout is removed.
+</para>
+
+<para>
+Callback procedure pointers used with timeouts are of
+type
+<xref linkend='XtTimerCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTimerCallbackProc'>
+<funcprototype>
+<funcdef>void <function>*XtTimerCallbackProc</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtIntervalId *<parameter>timer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<function>XtApp\%AddTimeOut</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the id returned from the corresponding
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+
+<para>
+To clear a timeout value, use
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveTimeOut'>
+<funcprototype>
+<funcdef>void <function>XtRemoveTimeOut</function></funcdef>
+ <paramdef>XtIntervalId <parameter>timer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id for the timeout request to be cleared.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
+function removes the pending timeout.
+Note that timeouts are automatically removed once they trigger.
+</para>
+
+<para>
+Please refer to Section 7.12 for information regarding the use of
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+</sect2>
+
+<sect2 id="Adding_and_Removing_Signal_Callbacks">
+<title>Adding and Removing Signal Callbacks</title>
+<para>
+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.
+</para>
+
+<para>
+Prior to establishing a signal handler, the application or widget should
+call
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>
+and store the resulting identifier in a place accessible to the signal
+handler. When a signal arrives, the signal handler should call
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>
+to notify the Intrinsics that a signal has occured. To register a signal
+callback use
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddSignal'>
+<funcprototype>
+<funcdef>XtSignalId <function>XtAppAddSignal</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtSignalCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the signal is noticed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The callback procedure pointers used to handle signal events are of type
+<xref linkend='XtSignalCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSignalCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSignalCallbackProc)</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtSignalId *<parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the id returned from the corresponding
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To notify the Intrinsics that a signal has occured, use
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNoticeSignal'>
+<funcprototype>
+<funcdef>void <function>XtNoticeSignal</function></funcdef>
+ <paramdef>XtSignalId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id returned from the corresponding
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+On a POSIX-based system,
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>
+is the only Intrinsics function that can safely be called from a signal handler.
+If
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>
+is invoked multiple times before the Intrinsics are able to invoke the
+registered callback, the callback is only called once.
+Logically, the Intrinsics maintain ``pending'' flag for each registered callback.
+This flag is initially
+<function>False</function>
+and is set to
+<function>True</function>
+by
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>.
+When
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+(with a mask including
+<function>XtIMSignal</function>)
+is called, all registered callbacks with ``pending''
+<function>True</function>
+are invoked and the flags are reset to
+<function>False</function>.
+</para>
+
+<para>
+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 Intrinsics never block signals from being raised, so if a given
+signal can be raised multiple times before the Intrinsics 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 Intrinsics
+sets the pending flag to
+<function>False</function>
+but before the callback can get control, in which case the pending flag
+will still be
+<function>True</function>
+after the callback returns, and the Intrinsics 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.
+</para>
+
+<para>
+To remove a registered signal callback, call
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveSignal'>
+<funcprototype>
+<funcdef>void <function>XtRemoveSignal</function></funcdef>
+ <paramdef>XtSignalId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id returned by the corresponding call to
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The client should typically disable the source of the signal before calling
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>.
+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
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>
+the client can test for signals with
+<xref linkend='XtAppPending' xrefstyle='select: title'/>
+and process them by calling
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+with the mask
+<function>XtIMSignal</function>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Constraining_Events_to_a_Cascade_of_Widgets">
+<title>Constraining Events to a Cascade of Widgets</title>
+<para>
+Modal widgets are widgets that, except for the input directed to them,
+lock out user input to the application.
+</para>
+
+<para>
+When a modal menu or modal dialog box is popped up using
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+and
+<function>ButtonRelease</function>.
+The user events ignored when they occur outside the cascade are
+<function>MotionNotify</function>
+and
+<function>EnterNotify</function>.
+All other events are delivered normally.
+In particular, note that this is one
+way in which widgets can receive
+<function>LeaveNotify</function>
+events without first receiving
+<function>EnterNotify</function>
+events; they should be prepared to deal with
+this, typically by ignoring any unmatched
+<function>LeaveNotify</function>
+events.
+</para>
+
+<para>
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+uses the
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+and
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>
+functions to constrain user events to a modal cascade
+and subsequently to remove a grab when the modal widget is popped down.
+</para>
+
+<para>
+To constrain or redirect user input to a modal widget, use
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddGrab'>
+<funcprototype>
+<funcdef>void <function>XtAddGrab</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Boolean <parameter>exclusive</parameter></paramdef>
+ <paramdef>Boolean <parameter>spring_loaded</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to add to the modal cascade. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>exclusive</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether user events should be dispatched exclusively to this widget
+or also to previous widgets in the cascade.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>spring_loaded</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this widget was popped up because the user pressed
+a pointer button.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+function appends the widget to the modal cascade
+and checks that <emphasis remap='I'>exclusive</emphasis> is
+<function>True</function>
+if <emphasis remap='I'>spring_loaded</emphasis> is
+<function>True</function>.
+If this condition is not met,
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+generates a warning message.
+</para>
+
+<para>
+The modal cascade is used by
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+when it tries to dispatch a user event.
+When at least one modal widget is in the widget cascade,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+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 <emphasis remap='I'>exclusive</emphasis> parameter
+<function>True</function>.
+</para>
+
+<para>
+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 <emphasis remap='I'>exclusive</emphasis>
+<function>False</function>.
+Modal dialog boxes that need to restrict user input to the most deeply nested
+dialog box add a subdialog widget to the cascade with <emphasis remap='I'>exclusive</emphasis>
+<function>True</function>.
+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.
+</para>
+
+<para>
+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 <emphasis remap='I'>spring_loaded</emphasis>
+<function>True</function>,
+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 Intrinsics do not modify
+the contents of the event.
+</para>
+
+<para>
+To remove the redirection of user input to a modal widget, use
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveGrab'>
+<funcprototype>
+<funcdef>void <function>XtRemoveGrab</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to remove from the modal cascade.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>
+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.
+</para>
+<sect2 id="Requesting_Key_and_Button_Grabs">
+<title>Requesting Key and Button Grabs</title>
+<para>
+The Intrinsics provide a set of key and button grab interfaces that
+are parallel to those provided by Xlib and that allow the Intrinsics
+to modify event dispatching when necessary. X Toolkit applications and
+widgets that need to passively grab keys or buttons or actively grab
+the keyboard or pointer should use the
+following Intrinsics routines rather than the corresponding Xlib
+routines.
+</para>
+
+<para>
+To passively grab a single key of the keyboard, use
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabKey'>
+<funcprototype>
+<funcdef>void <function>XtGrabKey</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabKey</function>;
+see <olink targetdoc='libX11' targetptr='Keyboard_Grabbing'>Section 12.2</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+calls
+<function>XGrabKey</function>
+specifying the widget's window as the grab
+window if the widget is realized. The remaining arguments are exactly
+as for
+<function>XGrabKey</function>.
+If the widget is not realized, or is later unrealized, the call to
+<function>XGrabKey</function>
+is performed (again) when
+the widget is realized and its window becomes mapped. In the future,
+if
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is called with a
+<function>KeyPress</function>
+event matching the specified keycode and modifiers (which may be
+<function>AnyKey</function>
+or
+<function>AnyModifier</function>,
+respectively) for the
+widget's window, the Intrinsics will call
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+with the timestamp from the
+<function>KeyPress</function>
+event if either of the following conditions is true:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XFilterEvent</function>
+returns
+<function>True</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To cancel a passive key grab, use
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabKey'>
+<funcprototype>
+<funcdef>void <function>XtUngrabKey</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the key was grabbed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XUngrabKey</function>;
+see <olink targetdoc='libX11' targetptr='Keyboard_Grabbing'>Section 12.2</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>
+procedure calls
+<function>XUngrabKey</function>
+specifying the widget's
+window as the ungrab window if the widget is realized. The remaining
+arguments are exactly as for
+<function>XUngrabKey</function>.
+If the widget is not realized,
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>
+removes a deferred
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+request, if any, for the specified widget, keycode, and modifiers.
+</para>
+
+<para>
+To actively grab the keyboard, use
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabKeyboard'>
+<funcprototype>
+<funcdef>int <function>XtGrabKeyboard</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for whose window the keyboard is to be grabbed.
+Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabKeyboard</function>;
+see <olink targetdoc='libX11' targetptr='Keyboard_Grabbing'>Section 12.2</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the specified widget is realized,
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+calls
+<function>XGrabKeyboard</function>
+specifying the widget's window as the grab window. The remaining
+arguments and return value are exactly as for
+<function>XGrabKeyboard</function>.
+If the widget is not realized,
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+immediately returns
+<function>GrabNotViewable</function>.
+No future automatic ungrab is implied by
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To cancel an active keyboard grab, use
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabKeyboard'>
+<funcprototype>
+<funcdef>void <function>XtUngrabKeyboard</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has the active keyboard grab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional argument to
+<function>XUngrabKeyboard</function>;
+see <olink targetdoc='libX11' targetptr='Keyboard_Grabbing'>Section 12.2</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+calls
+<function>XUngrabKeyboard</function>
+with the specified time.
+</para>
+
+<para>
+To passively grab a single pointer button, use
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabButton'>
+<funcprototype>
+<funcdef>void <function>XtGrabButton</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int <parameter>button</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>Window <parameter>confine_to</parameter></paramdef>
+ <paramdef>Cursor <parameter>cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabButton</function>;
+see <olink targetdoc='libX11' targetptr='Pointer_Grabbing'>Section 12.1</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+calls
+<function>XGrabButton</function>
+specifying the widget's window as the
+grab window if the widget is realized. The remaining arguments are
+exactly as for
+<function>XGrabButton</function>.
+If the widget is not realized, or is later unrealized, the call to
+<function>XGrabButton</function>
+is performed (again)
+when the widget is realized and its window becomes mapped. In the
+future, if
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is called with a
+<function>ButtonPress</function>
+event matching the specified button and modifiers (which may be
+<function>AnyButton</function>
+or
+<function>AnyModifier</function>,
+respectively)
+for the widget's window, the Intrinsics will call
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+with the timestamp from the
+<function>ButtonPress</function>
+event if either of the following conditions is true:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XFilterEvent</function>
+returns
+<function>True</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To cancel a passive button grab, use
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabButton'>
+<funcprototype>
+<funcdef>void <function>XtUngrabButton</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>unsigned int <parameter>button</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the button was grabbed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XUngrabButton</function>;
+see <olink targetdoc='libX11' targetptr='Pointer_Grabbing'>Section 12.1</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>
+procedure calls
+<function>XUngrabButton</function>
+specifying the
+widget's window as the ungrab window if the widget is realized. The
+remaining arguments are exactly as for
+<function>XUngrabButton</function>.
+If the widget is not realized,
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>
+removes a deferred
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+request, if any, for the specified widget, button, and modifiers.
+</para>
+
+<para>
+To actively grab the pointer, use
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabPointer'>
+<funcprototype>
+<funcdef>int <function>XtGrabPointer</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>Window <parameter>confine_to</parameter></paramdef>
+ <paramdef>Cursor <parameter>cursor</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for whose window the pointer is to be grabbed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabPointer</function>;
+see <olink targetdoc='libX11' targetptr='Pointer_Grabbing'>Section 12.1</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the specified widget is realized,
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>
+calls
+<function>XGrabPointer</function>,
+specifying the widget's window as the grab window. The remaining
+arguments and return value are exactly as for
+<function>XGrabPointer</function>.
+If the widget is not realized,
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>
+immediately returns
+<function>GrabNotViewable</function>.
+No future automatic ungrab is implied by
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To cancel an active pointer grab, use
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabPointer'>
+<funcprototype>
+<funcdef>void <function>XtUngrabPointer</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has the active pointer grab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time argument to
+<function>XUngrabPointer</function>;
+see <olink targetdoc='libX11' targetptr='Pointer_Grabbing'>Section 12.1</olink>
+in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+calls
+<function>XUngrabPointer</function>
+with the specified time.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Focusing_Events_on_a_Child">
+<title>Focusing Events on a Child</title>
+<para>
+To redirect keyboard input to a normal descendant of a
+widget without calling
+<function>XSetInputFocus</function>,
+use
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetKeyboardFocus'>
+<funcprototype>
+<funcdef>void <function>XtSetKeyboardFocus</function></funcdef>
+ <paramdef>Widget <parameter>subtree</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>subtree</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subtree of the hierarchy for which the keyboard focus is
+to be set. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>descendant</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies either the normal (non-pop-up) descendant of <emphasis remap='I'>subtree</emphasis> to which
+keyboard events are logically directed, or
+<function>None</function>.
+It is not an error to specify
+<function>None</function>
+when no input focus was previously set. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>
+causes
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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).
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+with any value of <emphasis remap='I'>owner_events</emphasis>, or
+if the keyboard is actively grabbed by E with <emphasis remap='I'>owner_events</emphasis>
+<function>False</function>
+via
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+on a previous key press, the event is dispatched to E.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If E is the final focus target widget F or a descendant of F, the
+event is dispatched to E.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+for E,
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+is called.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If E is an ancestor of F, and the event is a key press, and either
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+E has grabbed the key with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+and <emphasis remap='I'>owner_events</emphasis>
+<function>False</function>,
+or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+E has grabbed the key with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+and <emphasis remap='I'>owner_events</emphasis>
+<function>True</function>,
+and the coordinates of the event are outside the rectangle specified
+by E's geometry,
+then the event is dispatched to E.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Otherwise, define A as the closest common ancestor of E and F:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If there is an active keyboard grab for any widget via either
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+on a previous key press, or
+if no widget between F and A (noninclusive) has grabbed
+the key and modifier combination with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+and any value of <emphasis remap='I'>owner_events</emphasis>, the event is dispatched to F.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Else, the event is dispatched to the ancestor of F closest to A
+that has grabbed the key and modifier combination with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+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 Intrinsics do not modify
+the contents of the event.
+</para>
+
+<para>
+When <emphasis remap='I'>subtree</emphasis> 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
+<function>FocusIn</function>
+event is generated for the descendant if
+<function>FocusChange</function>
+events have been selected by the descendant.
+Similarly, when <emphasis remap='I'>subtree</emphasis> loses the X input focus
+or the keyboard focus for one of its ancestors, a
+<function>FocusOut</function>
+event is generated for descendant if
+<function>FocusChange</function>
+events have been selected by the descendant.
+</para>
+
+<para>
+A widget tree may also actively manage the X server input focus. To
+do so, a widget class specifies an accept_focus procedure.
+</para>
+
+<para>
+The accept_focus procedure pointer is of type
+<xref linkend='XtAcceptFocusProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAcceptFocusProc'>
+<funcprototype>
+<funcdef>Boolean <function>*XtAcceptFocusProc</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Time *<parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X time of the event causing the accept focus.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Widgets that need the input focus can call
+<function>XSetInputFocus</function>
+explicitly, pursuant to the restrictions of the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>.
+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
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events).
+Widgets classes that never want the input focus should set the
+<emphasis remap='I'>accept_focus</emphasis> field to NULL.
+</para>
+
+<para>
+To call a widget's accept_focus procedure, use
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallAcceptFocus'>
+<funcprototype>
+<funcdef>Boolean <function>XtCallAcceptFocus</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Time *<parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X time of the event that is causing the focus change.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>
+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 <emphasis remap='I'>accept_focus</emphasis> is NULL,
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>
+returns
+<function>False</function>.
+</para>
+<sect2 id="Events_for_Drawables_That_Are_Not_a_Widget_s_Window">
+<title>Events for Drawables That Are Not a Widget's Window</title>
+<para>
+Sometimes an application must handle events for drawables that are not
+associated with widgets in its widget tree. Examples include handling
+<function>GraphicsExpose</function>
+and
+<function>NoExpose</function>
+events on Pixmaps, and handling
+<function>PropertyNotify</function>
+events on the root window.
+</para>
+
+<para>
+To register a drawable with the Intrinsics event dispatching, use
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterDrawable'>
+<funcprototype>
+<funcdef>void <function>XtRegisterDrawable</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable's display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>drawable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to register the drawable for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+associates the specified drawable with the specified widget
+so that future calls to
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+are undefined.
+</para>
+
+<para>
+To unregister a drawable with the Intrinsics event dispatching, use
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnregisterDrawable'>
+<funcprototype>
+<funcdef>void <function>XtUnregisterDrawable</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable's display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>drawable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable to unregister.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>
+removes an association created with
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>.
+If the drawable is the window of a widget in the client's widget tree
+the results of calling
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>
+are undefined.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Querying_Event_Sources">
+<title>Querying Event Sources</title>
+<para>
+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 Intrinsics equivalents of the
+<function>XPending</function>,
+<function>XPeekEvent</function>,
+and
+<function>XNextEvent</function>
+Xlib calls.
+</para>
+
+<para>
+To determine if there are any events on the input queue for a given application,
+use
+<xref linkend='XtAppPending' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppPending'>
+<funcprototype>
+<funcdef>XtInputMask <function>XtAppPending</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application to check.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppPending' xrefstyle='select: title'/>
+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
+<function>XtIMXEvent</function>,
+<function>XtIMTimer</function>,
+<function>XtIMAlternateInput</function>,
+and
+<function>XtIMSignal</function>
+(see
+<function>XtAppProcessEvent ).</function>
+If there are no events pending,
+<xref linkend='XtAppPending' xrefstyle='select: title'/>
+flushes the output buffers of each Display in the application context
+and returns zero.
+</para>
+
+<para>
+To return the event from the head of a given application's input queue
+without removing input from the queue, use
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppPeekEvent'>
+<funcprototype>
+<funcdef>Boolean <function>XtAppPeekEvent</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the event information to the specified event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is an X event in the queue,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+copies it into <emphasis remap='I'>event_return</emphasis> and returns
+<function>True</function>.
+If no X input is on the queue,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+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,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+fills in <emphasis remap='I'>event_return</emphasis> and returns
+<function>True</function>.
+Otherwise, the input is for an input source
+registered with
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>,
+and
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+returns
+<function>False</function>.
+The sample implementations provides XtAppPeekEvent as described. Timeout callbacks
+are called while blocking for input. If some input for an input source is
+available,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+will return
+<function>True</function>
+without returning an event.
+</para>
+
+<para>
+To remove and return the event
+from the head of a given application's X event queue,
+use
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppNextEvent'>
+<funcprototype>
+<funcdef>void <function>XtAppNextEvent</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the event information to the specified event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the X event queue is empty,
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+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 <xref linkend='Adding_Background_Work_Procedures' />.
+</para>
+</sect1>
+
+<sect1 id="Dispatching_Events">
+<title>Dispatching Events</title>
+<para>
+The Intrinsics provide functions that dispatch events
+to widgets or other application code.
+Every client interested in X events on a widget uses
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+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 <xref linkend='Translation_Management' />.
+</para>
+
+<para>
+Applications that need direct control of the processing of different types
+of input should use
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppProcessEvent'>
+<funcprototype>
+<funcdef>void <function>XtAppProcessEvent</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtInputMask <parameter>mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the
+application for which to process input.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies what types of events to process.
+The mask is the bitwise inclusive OR of any combination of
+<function>XtIMXEvent</function>,
+<function>XtIMTimer</function>,
+<function>XtIMAlternateInput</function>,
+and
+<function>XtIMSignal</function>.
+As a convenience,
+<function>Intrinsic.h</function>
+defines the symbolic name
+<function>XtIMAll</function>
+to be the bitwise inclusive OR of these four event types.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+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
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+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
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+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
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When an X event is received,
+it is passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>,
+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.
+</para>
+
+<para>
+To dispatch an event returned by
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+retrieved directly from the Xlib queue, or synthetically constructed,
+to any registered event filters or event handlers, call
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDispatchEvent'>
+<funcprototype>
+<funcdef>Boolean <function>XtDispatchEvent</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the event structure to be dispatched
+to the appropriate event handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+function first calls
+<function>XFilterEvent</function>
+with the <emphasis remap='I'>event</emphasis> and the window of the widget to which the
+Intrinsics intend to dispatch the event, or the event window if
+the Intrinsics would not dispatch the event to any handlers.
+If
+<function>XFilterEvent</function>
+returns
+<function>True</function>
+and the event activated a server grab as identified
+by a previous call to
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+calls
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+with the timestamp from the event and immediately returns
+<function>True</function>.
+If
+<function>XFilterEvent</function>
+returns
+<function>True</function>
+and a grab was not activated,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+just immediately returns
+<function>True</function>.
+Otherwise,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+sends the event to the event handler functions that
+have been previously registered with the dispatch routine.
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+returns
+<function>True</function>
+if
+<function>XFilterEvent</function>
+returned
+<function>True</function>,
+or if the event was dispatched to some handler, and
+<function>False</function>
+if it found no handler to which to dispatch the event.
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+records the last timestamp in any event that
+contains a timestamp (see
+<function>XtLastTimestampProcessed ),</function>
+regardless of whether it was filtered or dispatched.
+If a modal cascade is active with <emphasis remap='I'>spring_loaded</emphasis>
+<function>True</function>,
+and if the event is a remap event as defined by
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+may dispatch the event a second time. If it does so,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+will call
+<function>XFilterEvent</function>
+again with the window of the spring-loaded widget prior to the second
+dispatch, and if
+<function>XFilterEvent</function>
+returns
+<function>True</function>,
+the second dispatch will not be performed.
+</para>
+</sect1>
+
+<sect1 id="The_Application_Input_Loop">
+<title>The Application Input Loop</title>
+<para>
+To process all input from a given application in a continuous loop,
+use the convenience procedure
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppMainLoop'>
+<funcprototype>
+<funcdef>void <function>XtAppMainLoop</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>
+function first reads the next incoming X event by calling
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+and then dispatches the event to the appropriate registered procedure
+by calling
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+This constitutes the main loop of X Toolkit applications.
+There is nothing special about
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>;
+it simply calls
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+and then
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+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
+<xref linkend='XtAppLock' xrefstyle='select: title'/>
+and
+<xref linkend='XtAppUnlock' xrefstyle='select: title'/>.
+</para>
+
+<para>
+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
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Setting_and_Checking_the_Sensitivity_State_of_a_Widget">
+<title>Setting and Checking the Sensitivity State of a Widget</title>
+<para>
+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.
+</para>
+
+<para>
+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
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+<function>MotionNotify</function>,
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+<function>FocusIn</function>,
+or
+<function>FocusOut</function>.
+</para>
+
+<para>
+A widget can be insensitive because its <emphasis remap='I'>sensitive</emphasis> field is
+<function>False</function>
+or because one of its ancestors is insensitive and thus the widget's
+<emphasis remap='I'>ancestor_sensitive</emphasis> field also is
+<function>False</function>.
+A widget can but does not need to distinguish these two cases visually.
+</para>
+
+<note>
+<para>
+Pop-up shells will have
+<emphasis remap='I'>ancestor_sensitive</emphasis>
+<function>False</function>
+if the parent was insensitive when the shell
+was created. Since
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+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.
+</para>
+</note>
+
+<para>
+To set the sensitivity state of a widget, use
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetSensitive'>
+<funcprototype>
+<funcdef>void <function>XtSetSensitive</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Boolean <parameter>sensitive</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sensitive</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the widget should receive
+keyboard, pointer, and focus events.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+function first calls
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on the current widget with an argument list specifying the
+XtNsensitive resource and the new value.
+If <emphasis remap='I'>sensitive</emphasis> is
+<function>False</function>
+and the widget's class is a subclass of
+Composite,
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+recursively propagates the new value
+down the child tree by calling
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on each child to set <emphasis remap='I'>ancestor_sensitive</emphasis> to
+<function>False</function>.
+If <emphasis remap='I'>sensitive</emphasis> is
+<function>True</function>
+and the widget's class is a subclass of
+Composite
+and the widget's <emphasis remap='I'>ancestor_sensitive</emphasis> field is
+<function>True</function>,
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+sets the <emphasis remap='I'>ancestor_sensitive</emphasis> of each child to
+<function>True</function>
+and then recursively calls
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on each normal descendant that is now sensitive to set
+<emphasis remap='I'>ancestor_sensitive</emphasis> to
+<function>True</function>.
+</para>
+
+<para>
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+calls
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+to change the <emphasis remap='I'>sensitive</emphasis> and <emphasis remap='I'>ancestor_sensitive</emphasis> 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).
+</para>
+
+<para>
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+maintains the invariant that, if the parent has either <emphasis remap='I'>sensitive</emphasis>
+or <emphasis remap='I'>ancestor_sensitive</emphasis>
+<function>False</function>,
+then all children have <emphasis remap='I'>ancestor_sensitive</emphasis>
+<function>False</function>.
+</para>
+
+<para>
+To check the current sensitivity state of a widget,
+use
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtIsSensitive'>
+<funcprototype>
+<funcdef>Boolean <function>XtIsSensitive</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>
+function returns
+<function>True</function>
+or
+<function>False</function>
+to indicate whether user input events are being dispatched.
+If object's class is a subclass of RectObj and
+both <emphasis remap='I'>sensitive</emphasis> and <emphasis remap='I'>ancestor_sensitive</emphasis> are
+<function>True</function>,
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>
+returns
+<function>True</function>;
+otherwise, it returns
+<function>False</function>.
+</para>
+</sect1>
+
+<sect1 id="Adding_Background_Work_Procedures">
+<title>Adding Background Work Procedures</title>
+<para>
+The Intrinsics 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
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>.
+Work procedure pointers are of type
+<xref linkend='XtWorkProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWorkProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtWorkProc)</function></funcdef>
+
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data specified when the work procedure was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure should return
+<function>True</function>
+when it is done to indicate that it
+should be removed.
+If the procedure returns
+<function>False</function>,
+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.
+</para>
+
+<para>
+To register a work procedure for a given application, use
+<xref linkend='XtAppAddWorkProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddWorkProc'>
+<funcprototype>
+<funcdef>XtWorkProcId <function>XtAppAddWorkProc</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtWorkProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the application is idle.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddWorkProc' xrefstyle='select: title'/>
+function adds the specified work procedure for the application identified
+by <emphasis remap='I'>app_context</emphasis>
+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.
+</para>
+
+<para>
+To remove a work procedure, either return
+<function>True</function>
+from the procedure when it is called or use
+<xref linkend='XtRemoveWorkProc' xrefstyle='select: title'/>
+outside of the procedure.
+</para>
+
+<funcsynopsis id='XtRemoveWorkProc'>
+<funcprototype>
+<funcdef>void <function>XtRemoveWorkProc</function></funcdef>
+ <paramdef>XtWorkProcId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which work procedure to remove.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveWorkProc' xrefstyle='select: title'/>
+function explicitly removes the specified background work procedure.
+</para>
+</sect1>
+
+<sect1 id="X_Event_Filters">
+<title>X Event Filters</title>
+<para>
+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.
+</para>
+<sect2 id="Pointer_Motion_Compression">
+<title>Pointer Motion Compression</title>
+<para>
+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 <emphasis remap='I'>compress_motion</emphasis> should be
+<function>True</function>.
+When a request for an event would return a motion event,
+the Intrinsics 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.
+</para>
+</sect2>
+
+<sect2 id="Enter_Leave_Compression">
+<title>Enter/Leave Compression</title>
+<para>
+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 <emphasis remap='I'>compress_enterleave</emphasis> should be
+<function>True</function>.
+These enter and leave events are not delivered to the client
+if they are found together in the input queue.
+</para>
+</sect2>
+
+<sect2 id="Exposure_Compression">
+<title>Exposure Compression</title>
+<para>
+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.
+</para>
+
+<para>
+In either case, these widgets do not care about getting partial exposure events.
+The <emphasis remap='I'>compress_exposure</emphasis> 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:
+</para>
+
+<literallayout >
+#define XtExposeNoCompress ((XtEnum)False)
+#define XtExposeCompressSeries ((XtEnum)True)
+#define XtExposeCompressMultiple &lt;implementation-defined&gt;
+#define XtExposeCompressMaximal &lt;implementation-defined&gt;
+</literallayout>
+
+<para>
+optionally ORed with any combination of the following flags (all with
+implementation-defined values):
+<function>XtExposeGraphicsExpose</function>,
+<function>XtExposeGraphicsExposeMerged</function>,
+<function>XtExposeNoExpose</function>,
+and
+<function>XtExposeNoRegion</function>.
+</para>
+
+<para>
+If the <emphasis remap='I'>compress_exposure</emphasis> field in the widget class structure does not
+specify
+<function>XtExposeNoCompress</function>,
+the event manager calls the widget's expose procedure only
+once for a series of exposure events.
+In this case, all
+<function>Expose</function>
+or
+<function>GraphicsExpose</function>
+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
+<function>XtExposeNoRegion</function>
+is specified) the region.
+For more information on regions, see
+<olink targetdoc='libX11' targetptr='Manipulating_Regions'>Section 16.5</olink> in
+<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface.</olink>.)
+</para>
+
+<para>
+The values have the following interpretation:
+</para>
+
+<para>
+<function>XtExposeNoCompress</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+No exposure compression is performed; every selected event is
+individually dispatched to the expose procedure with a <emphasis remap='I'>region</emphasis>
+argument of NULL.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeCompressSeries</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeCompressMultiple</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeCompressMaximal</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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 Intrinsics will
+block until the end of the series is received.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The additional flags have the following meaning:
+</para>
+
+<para>
+<function>XtExposeGraphicsExpose</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that
+<function>GraphicsExpose</function>
+events are also to be dispatched to
+the expose procedure.
+<function>GraphicsExpose</function>
+events are compressed, if specified, in the same manner as
+<function>Expose</function>
+events.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeGraphicsExposeMerged</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies in the case of
+<function>XtExposeCompressMultiple</function>
+and
+<function>XtExposeCompressMaximal</function>
+that series of
+<function>GraphicsExpose</function>
+and
+<function>Expose</function>
+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
+<function>XtExposeGraphicsExpose</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeNoExpose</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that
+<function>NoExpose</function>
+events are also to be dispatched to the expose procedure.
+<function>NoExpose</function>
+events are never coalesced with
+other exposure events or with each other.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeNoRegion</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+<sect1 id="Widget_Exposure_and_Visibility">
+<title>Widget Exposure and Visibility</title>
+<para>
+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.
+</para>
+
+<sect2 id="Redisplay_of_a_Widget_The_expose_Procedure">
+<title>Redisplay of a Widget: The expose Procedure</title>
+<para>
+The expose procedure pointer in a widget class is of type
+<xref linkend='XtExposeProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtExposeProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtExposeProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Region <parameter>region</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget instance requiring redisplay.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the exposure event giving the rectangle requiring redisplay.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>region</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the union of all rectangles in this exposure sequence.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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 <emphasis remap='I'>expose</emphasis> field.
+Many composite widgets serve only as containers for their children
+and have no expose procedure.
+</para>
+
+<note>
+<para>
+If the <emphasis remap='I'>expose</emphasis> procedure is NULL,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+fills in a default bit gravity of
+<function>NorthWestGravity</function>
+before it calls the widget's realize procedure.
+</para>
+</note>
+
+<para>
+If the widget's <emphasis remap='I'>compress_exposure</emphasis> class field specifies
+<function>XtExposeNoCompress</function>
+or
+<function>XtExposeNoRegion</function>,
+or if the event type is
+<function>NoExpose</function>
+(see <xref linkend='Exposure_Compression' />),
+<emphasis remap='I'>region</emphasis> is NULL. If
+<function>XtExposeNoCompress</function>
+is not specified and the event type is not
+<function>NoExpose</function>,
+the event is the final event in the compressed series
+but <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> contain
+the bounding box for all the compressed events.
+The region is created and destroyed by the Intrinsics, but
+the widget is permitted to modify the region contents.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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
+</para>
+<literallayout >
+Boolean invert;
+Boolean highlight;
+Dimension highlight_width;
+</literallayout>
+<para>
+Label would have <emphasis remap='I'>invert</emphasis> and <emphasis remap='I'>highlight</emphasis> always
+<function>False</function>
+and <emphasis remap='I'>highlight_width</emphasis> zero.
+Pushbutton would dynamically set <emphasis remap='I'>highlight</emphasis> and <emphasis remap='I'>highlight_width</emphasis>,
+but it would leave <emphasis remap='I'>invert</emphasis> always
+<function>False</function>.
+Finally, Toggle would dynamically set all three.
+In this case,
+the expose procedures for Pushbutton and Toggle inherit
+their superclass's expose procedure;
+see <xref linkend='Inheritance_of_Superclass_Operations' />.
+</para>
+</sect2>
+
+<sect2 id="Widget_Visibility">
+<title>Widget Visibility</title>
+<para>
+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.
+</para>
+
+<para>
+The <emphasis remap='I'>visible</emphasis> 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
+<function>True</function>
+by the time an
+exposure
+event is processed if any part of the widget is visible,
+but is
+<function>False</function>
+if the widget is fully obscured.
+</para>
+
+<para>
+Widgets can use or ignore the <emphasis remap='I'>visible</emphasis> hint.
+If they ignore it,
+they should have <emphasis remap='I'>visible_interest</emphasis> in their widget class record set
+<function>False</function>.
+In such cases,
+the <emphasis remap='I'>visible</emphasis> field is initialized
+<function>True</function>
+and never changes.
+If <emphasis remap='I'>visible_interest</emphasis> is
+<function>True</function>,
+the event manager asks for
+<function>VisibilityNotify</function>
+events for the widget and sets <emphasis remap='I'>visible</emphasis> to
+<function>True</function>
+on
+<function>VisibilityUnobscured</function>
+or
+<function>VisibilityPartiallyObscured</function>
+events and
+<function>False</function>
+on
+<function>VisibilityFullyObscured</function>
+events.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="X_Event_Handlers">
+<title>X Event Handlers</title>
+<para>
+Event handlers are procedures called when specified events
+occur in a widget.
+Most widgets need not use event handlers explicitly.
+Instead, they use the Intrinsics translation manager.
+Event handler procedure pointers are of the type
+<xref linkend='XtEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtEventHandler'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtEventHandler)</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Boolean *<parameter>continue_to_dispatch</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which the event arrived.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any client-specific information registered with the event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the triggering event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>continue_to_dispatch</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the remaining event
+handlers registered for the current event
+should be called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+After receiving an event and before calling any event handlers, the
+Boolean pointed to by <emphasis remap='I'>continue_to_dispatch</emphasis> is initialized to
+<function>True</function>.
+When an event handler is called, it may decide that further processing
+of the event is not desirable and may store
+<function>False</function>
+in this Boolean, in
+which case any handlers remaining to be called for the event are
+ignored.
+</para>
+
+<para>
+The circumstances under which the Intrinsics may add event handlers
+to a widget are currently implementation-dependent. Clients must
+therefore be aware that storing
+<function>False</function>
+into the <emphasis remap='I'>continue_to_dispatch</emphasis> argument can lead to portability problems.
+</para>
+<sect2 id="Event_Handlers_That_Select_Events">
+<title>Event Handlers That Select Events</title>
+<para>
+To register an event handler procedure with the dispatch mechanism, use
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtAddEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+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 <emphasis remap='I'>client_data</emphasis>
+value,
+the specified mask augments the existing mask.
+If the widget is realized,
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>,
+if necessary.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+</para>
+
+<para>
+To remove a previously registered event handler, use
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtRemoveEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to unregister this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+removed on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the registered client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+function unregisters an event handler registered with
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+for the specified events.
+The request is ignored if <emphasis remap='I'>client_data</emphasis> does not match the value given
+when the handler was registered.
+If the widget is realized and no other event handler requires the event,
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>.
+If the specified procedure has not been registered
+or if it has been registered with a different value of <emphasis remap='I'>client_data</emphasis>,
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+returns without reporting an error.
+</para>
+
+<para>
+To stop a procedure registered with
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+from receiving all selected events, call
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+with an <emphasis remap='I'>event_mask</emphasis> of
+<function>XtAllEvents</function>
+and <emphasis remap='I'>nonmaskable</emphasis>
+<function>True</function>.
+The procedure will continue to receive any events
+that have been specified in calls to
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register an event handler procedure that receives events before or
+after all previously registered event handlers, use
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>.
+</para>
+<literallayout >
+typedef enum {XtListHead, XtListTail} XtListPosition;
+</literallayout>
+
+<funcsynopsis id='XtInsertEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtInsertEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtListPosition <parameter>position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the client's event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+is identical to
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+with the additional <emphasis remap='I'>position</emphasis> argument. If <emphasis remap='I'>position</emphasis> is
+<function>XtListHead</function>,
+the event
+handler is registered so that it is called before any event
+handlers that were previously registered for the same widget. If
+<emphasis remap='I'>position</emphasis> is
+<function>XtListTail</function>,
+the event handler is registered to be called
+after any previously registered event handlers. If the procedure is
+already registered with the same <emphasis remap='I'>client_data</emphasis> value, the specified mask
+augments the existing mask and the procedure is repositioned in
+the list.
+</para>
+</sect2>
+
+<sect2 id="Event_Handlers_That_Do_Not_Select_Events">
+<title>Event Handlers That Do Not Select Events</title>
+<para>
+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
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddRawEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtAddRawEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the client's event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+except that it does not affect the widget's event mask and never causes an
+<function>XSelectInput</function>
+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 <emphasis remap='I'>client_data</emphasis>,
+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.
+</para>
+
+<para>
+To remove a previously registered raw event handler, use
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveRawEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtRemoveRawEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to unregister this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+removed on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the registered client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+function unregisters an event handler registered with
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+for the specified events without changing
+the window event mask.
+The request is ignored if <emphasis remap='I'>client_data</emphasis> 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 <emphasis remap='I'>client_data</emphasis>,
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+returns without reporting an error.
+</para>
+
+<para>
+To stop a procedure
+registered with
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+from receiving all nonselected events, call
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+with an <emphasis remap='I'>event_mask</emphasis> of
+<function>XtAllEvents</function>
+and <emphasis remap='I'>nonmaskable</emphasis>
+<function>True</function>.
+The procedure
+will continue to receive any events that have been specified in calls to
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register an event handler procedure that receives events before or
+after all previously registered event handlers without selecting for
+the events, use
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInsertRawEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtInsertRawEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtListPosition <parameter>position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the client's event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+except that it does not modify the widget's event
+mask and never causes an
+<function>XSelectInput</function>
+for the specified events. If
+the procedure is already registered with the same <emphasis remap='I'>client_data</emphasis>
+value, the
+specified mask augments the existing mask and the procedure is
+repositioned in the list.
+</para>
+</sect2>
+
+<sect2 id="Current_Event_Mask">
+<title>Current Event Mask</title>
+<para>
+To retrieve the event mask for a given widget, use
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtBuildEventMask'>
+<funcprototype>
+<funcdef>EventMask <function>XtBuildEventMask</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>
+function returns the event mask representing the logical OR
+of all event masks for event handlers registered on the widget with
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+and
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+and all event translations, including accelerators,
+installed on the widget.
+This is the same event mask stored into the
+<function>XSetWindowAttributes</function>
+structure by
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+and sent to the server when event handlers and translations are installed or
+removed on the realized widget.
+</para>
+</sect2>
+
+<sect2 id="Event_Handlers_for_X_Protocol_Extensions">
+<title>Event Handlers for X11 Protocol Extensions</title>
+<para>
+To register an event handler procedure with the Intrinsics dispatch
+mechanism according to an event type, use
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInsertEventTypeHandler'>
+<funcprototype>
+<funcdef>void <function>XtInsertEventTypeHandler</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int <parameter>event_type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>select_data</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtListPosition <parameter>position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type for which to call this event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>select_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies data used to request events of the specified type from the server,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event handler to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies when the event handler is to be called relative to other
+previously registered handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+registers a procedure with the
+dispatch mechanism that is to be called when an event that matches the
+specified <emphasis remap='I'>event_type</emphasis> is dispatched to the specified <emphasis remap='I'>widget</emphasis>.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies one of the core X protocol events, then
+<emphasis remap='I'>select_data</emphasis> must be a pointer to a value of type
+<function>EventMask</function>,
+indicating
+the event mask to be used to select for the desired event. This event
+mask is included in the value returned by
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>.
+If the widget is realized,
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>
+if necessary. Specifying NULL for <emphasis remap='I'>select_data</emphasis> is equivalent to
+specifying a pointer to an event mask containing 0. This is similar
+to the
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+function.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies an extension event type, then the semantics of
+the data pointed to by <emphasis remap='I'>select_data</emphasis> are defined by the extension
+selector registered for the specified event type.
+</para>
+
+<para>
+In either case the Intrinsics are not required to copy the data
+pointed to by <emphasis remap='I'>select_data</emphasis>, so the caller must ensure that it remains
+valid as long as the event handler remains registered with this value
+of <emphasis remap='I'>select_data</emphasis>.
+</para>
+
+<para>
+The <emphasis remap='I'>position</emphasis> 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
+<function>XtListTail</function>,
+which registers this event handler after any previously
+registered handlers for this event type.
+</para>
+
+<para>
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once if it is
+registered with
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>,
+regardless of the manner
+in which it is registered and regardless of the value(s)
+of <emphasis remap='I'>select_data</emphasis>. If the procedure is already registered with the
+same <emphasis remap='I'>client_data</emphasis> value, the specified mask augments the existing
+mask and the procedure is repositioned in the list.
+</para>
+
+<para>
+To remove an event handler registered with
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>,
+use
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveEventTypeHandler'>
+<funcprototype>
+<funcdef>void <function>XtRemoveEventTypeHandler</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int <parameter>event_type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>select_data</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which the event handler was registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type for which the handler was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>select_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies data used to deselect events of the specified type
+from the server, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event handler to be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data with which the procedure was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>
+function unregisters an event handler
+registered with
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+for the specified event type.
+The request is ignored if <emphasis remap='I'>client_data</emphasis> does not match the value given
+when the handler was registered.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies one of the core X protocol events,
+<emphasis remap='I'>select_data</emphasis> must be a pointer to a value of type
+<function>EventMask, indicating the event</function>
+mask to be used to deselect for the appropriate event. If the widget
+is realized,
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>
+if necessary.
+Specifying NULL for <emphasis remap='I'>select_data</emphasis> is equivalent to specifying a pointer
+to an event mask containing 0. This is similar to the
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+function.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies an extension event type, then the semantics of
+the data pointed to by <emphasis remap='I'>select_data</emphasis> are defined by the extension
+selector registered for the specified event type.
+</para>
+
+<para>
+To register a procedure to select extension events for a widget, use
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterExtensionSelector'>
+<funcprototype>
+<funcdef>void <function>XtRegisterExtensionSelector</function></funcdef>
+ <paramdef>Display <parameter>*display</parameter></paramdef>
+ <paramdef>int <parameter>min_event_type</parameter></paramdef>
+ <paramdef>int <parameter>max_event_type</parameter></paramdef>
+ <paramdef>XtExtensionSelectProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for which the extension selector is to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_event_type</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the range of event types for the extension.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension selector procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the extension selector.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>
+function registers a procedure to arrange
+for the delivery of extension events to widgets.
+</para>
+
+<para>
+If <emphasis remap='I'>min_event_type</emphasis> and <emphasis remap='I'>max_event_type</emphasis> match the parameters
+to a previous call to
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>
+for the same <emphasis remap='I'>display</emphasis>, then <emphasis remap='I'>proc</emphasis> and <emphasis remap='I'>client_data</emphasis>
+replace the previously
+registered values. If the range specified by <emphasis remap='I'>min_event_type</emphasis>
+and <emphasis remap='I'>max_event_type</emphasis> overlaps the range of the parameters to a
+previous call for the same display in any other way, an error results.
+</para>
+
+<para>
+When a widget is realized,
+after the <emphasis remap='I'>core.realize</emphasis> method is called,
+the Intrinsics check to see if any event
+handler specifies an event type within the range of a registered
+extension selector. If so, the Intrinsics call each such selector.
+If an event type handler is added or removed, the Intrinsics 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 Intrinsics
+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.
+</para>
+
+<para>
+An extension selector is of type
+<xref linkend='XtExtensionSelectProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtExtensionSelectProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtExtensionSelectProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int *<parameter>event_types</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>select_data</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that is being realized or is having
+an event handler added or removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_types</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of event types that the widget has
+registered event handlers for.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>select_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of the select_data parameters specified in
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the <emphasis remap='I'>event_types</emphasis> and <emphasis remap='I'>select_data</emphasis>
+lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data with which the procedure was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>event_types</emphasis> and <emphasis remap='I'>select_data</emphasis> lists will always have the
+same number of elements, specified by <emphasis remap='I'>count</emphasis>.
+Each event type/select data pair represents one call to
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register a procedure to dispatch events of a specific type within
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>,
+use
+<xref linkend='XtSetEventDispatcher' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetEventDispatcher'>
+<funcprototype>
+<funcdef>XtEventDispatchProc <function>XtSetEventDispatcher</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>event_type</parameter></paramdef>
+ <paramdef>XtEventDispatchProc <parameter>proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for which the event dispatcher is to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type for which the dispatcher should be invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event dispatcher procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetEventDispatcher' xrefstyle='select: title'/>
+function registers the event dispatcher procedure specified by <emphasis remap='I'>proc</emphasis>
+for events with the type <emphasis remap='I'>event_type</emphasis>. The previously registered
+dispatcher (or the default dispatcher if there was no previously registered
+dispatcher) is returned. If <emphasis remap='I'>proc</emphasis> is NULL, the default procedure is
+restored for the specified type.
+</para>
+
+<para>
+In the future, when
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is called with an event type of <emphasis remap='I'>event_type</emphasis>, the specified <emphasis remap='I'>proc</emphasis>
+(or the default dispatcher) is invoked to determine a widget
+to which to dispatch the event.
+</para>
+
+<para>
+The default dispatcher handles the Intrinsics modal cascade and keyboard
+focus mechanisms, handles the semantics of <emphasis remap='I'>compress_enterleave</emphasis>
+and <emphasis remap='I'>compress_motion</emphasis>, and discards all extension events.
+</para>
+
+<para>
+An event dispatcher procedure pointer is of type
+<xref linkend='XtEventDispatchProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtEventDispatchProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtEventDispatchProc)</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the event to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The event dispatcher procedure should determine whether this event is of
+a type that should be dispatched to a widget.
+</para>
+
+<para>
+If the event should be dispatched to a widget, the event dispatcher
+procedure should determine the appropriate widget to receive the
+event, call
+<function>XFilterEvent</function>
+with the window of this widget, or
+<function>None</function>
+if the event is to be discarded, and if
+<function>XFilterEvent</function>
+returns
+<function>False</function>,
+dispatch the event to the widget using
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>.
+The procedure should return
+<function>True</function>
+if either
+<function>XFilterEvent</function>
+or
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+returned
+<function>True</function>
+and
+<function>False</function>
+otherwise.
+</para>
+
+<para>
+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
+<function>True</function>
+if it successfully dispatched the event and
+<function>False</function>
+otherwise.
+</para>
+
+<para>
+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
+<xref linkend='XtGetKeyboardFocusWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetKeyboardFocusWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtGetKeyboardFocusWidget</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to get forwarding information for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetKeyboardFocusWidget' xrefstyle='select: title'/>
+function returns the widget that would be the end result of keyboard
+event forwarding for a keyboard event for the specified widget.
+</para>
+
+<para>
+To dispatch an event to a specified widget, use
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDispatchEventToWidget'>
+<funcprototype>
+<funcdef>Boolean <function>XtDispatchEventToWidget</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to which to dispatch the event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the event to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+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 <emphasis remap='I'>continue_to_dispatch</emphasis>
+value returned by each handler.
+The Intrinsics behave as if event handlers were registered at the head
+of the list for
+<function>Expose</function>,
+<function>NoExpose</function>,
+<function>GraphicsExpose</function>,
+and
+<function>VisibilityNotify</function>
+events to invoke the widget's expose procedure according to the exposure
+compression rules and to update the widget's <emphasis remap='I'>visible</emphasis> field
+if <emphasis remap='I'>visible_interest</emphasis> is
+<function>True</function>.
+These internal event handlers never set <emphasis remap='I'>continue_to_dispatch</emphasis> to
+<function>False</function>.
+</para>
+
+<para>
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+returns
+<function>True</function>
+if any event handler was called and
+<function>False</function>
+otherwise.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Using_the_Intrinsics_in_a_Multi_Threaded_Environment">
+<title>Using the Intrinsics in a Multi-Threaded Environment</title>
+<para>
+The Intrinsics may be used in environments that offer multiple threads
+of execution within the context of a single process. A multi-threaded
+application using the Intrinsics must explicitly initialize the toolkit
+for mutually exclusive access by calling
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>.
+</para>
+<sect2 id="Initializing_a_Multi_Threaded_Intrinsics_Application">
+<title>Initializing a Multi-Threaded Intrinsics Application</title>
+<para>
+To test and initialize Intrinsics support for mutually exclusive thread
+access, call
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtToolkitThreadInitialize'>
+<funcprototype>
+<funcdef>Boolean <function>XtToolkitThreadInitialize</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
+returns <function>True</function> if the Intrinsics support mutually exclusive thread
+access, otherwise it returns <function>False</function>. <xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
+must be called before
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+or
+<function>XtSetLanguageProc</function>
+is called. <xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/> may be called more than once;
+however, the application writer must ensure that it is not called
+simultaneously by two or more threads.
+</para>
+</sect2>
+
+<sect2 id="Locking_tk_Data_Structures">
+<title>Locking X Toolkit Data Structures</title>
+<para>
+The Intrinsics 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 Intrinsics process
+global data.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+Most application writers will have little need to use locking as the
+Intrinsics 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:
+</para>
+<literallayout >
+ ...
+ XtAppLock(app_context);
+ XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
+ XtAppUnlock(app_context);
+ ...
+</literallayout>
+<para>
+When the application relies upon
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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:
+</para>
+<literallayout >
+#include &lt;X11/CoreP.h&gt;
+Boolean BeingDestroyed (widget)
+ Widget widget;
+{
+ Boolean ret;
+ XtAppLock(XtWidgetToApplicationContext(widget));
+ ret = widget-&gt;core.being_destroyed;
+ XtAppUnlock(XtWidgetToApplicationContext(widget));
+ return ret;
+}
+</literallayout>
+<para>
+A client that wishes to atomically call two or more Intrinsics functions
+must lock the application context. For example:
+</para>
+<literallayout >
+ ...
+ XtAppLock(XtWidgetToApplicationContext(widget));
+ XtUnmanageChild (widget1);
+ XtManageChild (widget2);
+ XtAppUnlock(XtWidgetToApplicationContext(widget));
+ ...
+</literallayout>
+<sect3 id="Locking_the_Application_Context">
+<title>Locking the Application Context</title>
+<para>
+To ensure mutual exclusion of application context, display, or
+widget internal state, use
+<function>XtAppLock.</function>
+</para>
+
+<funcsynopsis id='XtAppLock'>
+<funcprototype>
+<funcdef>void <function>XtAppLock</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context to lock.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppLock' xrefstyle='select: title'/> 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.
+</para>
+
+<para>
+To unlock a locked application context, use
+<function>XtAppUnlock.</function>
+</para>
+
+<funcsynopsis id='XtAppUnlock'>
+<funcprototype>
+<funcdef>void <function>XtAppUnlock</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that was previously locked.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+</sect3>
+<sect3 id="Locking_the_Process">
+<title>Locking the Process</title>
+<para>
+To ensure mutual exclusion of X Toolkit process global data, a
+widget writer must use
+<function>XtProcessLock.</function>
+</para>
+
+<funcsynopsis id='XtProcessLock'>
+<funcprototype>
+<funcdef>void <function>XtProcessLock</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<xref linkend='XtProcessLock' xrefstyle='select: title'/> blocks until it is able to acquire the lock.
+Widget writers may use XtProcessLock to guarantee mutually exclusive
+access to widget static data.
+</para>
+
+<para>
+To unlock a locked process, use
+<xref linkend='XtProcessUnlock' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtProcessUnlock'>
+<funcprototype>
+<funcdef>void <function>XtProcessUnlock</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+To lock both an application context and the process at the same
+time, call
+<xref linkend='XtAppLock' xrefstyle='select: title'/>
+first and then
+<xref linkend='XtProcessLock' xrefstyle='select: title'/>.
+To release both locks, call
+<xref linkend='XtProcessUnlock' xrefstyle='select: title'/>
+first and then
+<xref linkend='XtAppUnlock' xrefstyle='select: title'/>.
+The order is important to avoid deadlock.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Event_Management_in_a_Multi_Threaded_Environment">
+<title>Event Management in a Multi-Threaded Environment</title>
+<para>
+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.
+</para>
+
+<para>
+To indicate that the event loop should terminate after the current
+event dispatch has completed, use
+<xref linkend='XtAppSetExitFlag' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetExitFlag'>
+<funcprototype>
+<funcdef>void <function>XtAppSetExitFlag</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>
+tests the value of the flag and will return if the flag is <function>True</function>.
+</para>
+
+<para>
+Application writers who implement their own main loop may test the
+value of the exit flag with
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetExitFlag'>
+<funcprototype>
+<funcdef>Boolean <function>XtAppGetExitFlag</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>
+will normally return <function>False</function>, indicating that event processing
+may continue. When
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>
+returns <function>True</function>, the loop must terminate and return to the caller,
+which might then destroy the application context.
+</para>
+
+<para>
+Application writers should be aware that, if a thread is blocked in
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>,
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+The Intrinsics manage access to events on a last-in, first-out basis. If
+multiple threads in the same application context block in
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>,
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>,
+the last thread to call one of these functions is the first
+thread to return.
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/specs/CH08.xml b/specs/CH08.xml
new file mode 100644
index 0000000..2f24e65
--- /dev/null
+++ b/specs/CH08.xml
@@ -0,0 +1,613 @@
+<chapter id='Callbacks'>
+<title>Callbacks</title>
+<para>
+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 <emphasis remap='I'>destroy_callbacks</emphasis>
+list is called to notify clients of the widget's impending doom.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+<sect1 id="Using_Callback_Procedure_and_Callback_List_Definitions">
+<title>Using Callback Procedure and Callback List Definitions</title>
+<para>
+Callback procedure pointers for use in callback lists are of type
+<xref linkend='XtCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtCallbackProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget owning the list in which the callback is registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data supplied by the client when the procedure
+was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>client_data</emphasis> 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 <emphasis remap='I'>client_data</emphasis> value may be NULL
+if all necessary information is in the widget.
+The <emphasis remap='I'>call_data</emphasis> argument is a convenience to avoid having simple
+cases where the client could otherwise always call
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+or a widget-specific function to retrieve data from the widget.
+Widgets should generally avoid putting complex state information
+in <emphasis remap='I'>call_data</emphasis>.
+The client can use the more general data retrieval methods, if necessary.
+</para>
+
+<para>
+Whenever a client wants to pass a callback list as an argument in an
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+or
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+call, it should specify the address
+of a NULL-terminated array of type
+<function>XtCallbackList</function>.
+</para>
+<literallayout >
+typedef struct {
+ XtCallbackProc callback;
+ XtPointer closure;
+} XtCallbackRec, *XtCallbackList;
+</literallayout>
+<para>
+For example, the callback list for procedures A and B with client data
+clientDataA and clientDataB, respectively, is
+</para>
+<literallayout >
+static XtCallbackRec callbacks[] = {
+ {A, (XtPointer) clientDataA},
+ {B, (XtPointer) clientDataB},
+ {(XtCallbackProc) NULL, (XtPointer) NULL}
+};
+</literallayout>
+<para>
+Although callback lists are passed by address in arglists
+and varargs lists,
+the Intrinsics 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 Intrinsics automatically do this,
+potentially using a different structure for their
+internal representation.
+</para>
+</sect1>
+
+<sect1 id="Identifying_Callback_Lists">
+<title>Identifying Callback Lists</title>
+<para>
+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
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
+check
+to see that the requested callback list is indeed implemented by the widget.
+</para>
+
+<para>
+For the Intrinsics to find and correctly handle callback lists,
+they must be declared with a resource type of
+<function>XtRCallback</function>.
+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
+<function>XtCallbackStatus</function>
+<function>XtCallbackHasNone ),</function>
+access to callback list resources must be made
+through other Intrinsics procedures.
+</para>
+</sect1>
+
+<sect1 id="Adding_Callback_Procedures">
+<title>Adding Callback Procedures</title>
+<para>
+To add a callback procedure to a widget's callback list, use
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddCallback'>
+<funcprototype>
+<funcdef>void <function>XtAddCallback</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+ <paramdef>XtCallbackProc <parameter>callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list to which the procedure is to be appended.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the specified procedure
+when it is invoked,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+A callback will be invoked as many times as it occurs in the callback list.
+</para>
+
+<para>
+To add a list of callback procedures to a given widget's callback list, use
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddCallbacks'>
+<funcprototype>
+<funcdef>void <function>XtAddCallbacks</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+ <paramdef>XtCallbackList <parameter>callbacks</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list to which the procedures are to be appended.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callbacks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the null-terminated list of callback procedures and corresponding
+client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+</sect1>
+
+<sect1 id="Removing_Callback_Procedures">
+<title>Removing Callback Procedures</title>
+<para>
+To delete a callback procedure from a widget's callback list, use
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveCallback'>
+<funcprototype>
+<funcdef>void <function>XtRemoveCallback</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+ <paramdef>XtCallbackProc <parameter>callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list from which the procedure is to be deleted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client data to match with the registered callback entry.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>
+function removes a callback only if both the procedure and the client
+data match.
+</para>
+
+<para>
+To delete a list of callback procedures from a given widget's callback list, use
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveCallbacks'>
+<funcprototype>
+<funcdef>void <function>XtRemoveCallbacks</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+ <paramdef>XtCallbackList <parameter>callbacks</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list from which the procedures are to be deleted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callbacks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the null-terminated list of callback procedures and corresponding
+client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To delete all callback procedures from a given widget's callback list
+and free all storage associated with the callback list, use
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveAllCallbacks'>
+<funcprototype>
+<funcdef>void <function>XtRemoveAllCallbacks</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list to be cleared.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+</sect1>
+
+<sect1 id="Executing_Callback_Procedures">
+<title>Executing Callback Procedures</title>
+<para>
+To execute the procedures in a given widget's callback list,
+specifying the callback list by resource name, use
+<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallCallbacks'>
+<funcprototype>
+<funcdef>void <function>XtCallCallbacks</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list to be executed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a callback-list-specific data value to pass to each of the callback
+procedure in the list, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>
+calls each of the callback procedures in the list
+named by <emphasis remap='I'>callback_name</emphasis> in the specified widget, passing the client
+data registered with the procedure and <emphasis remap='I'>call-data</emphasis>.
+</para>
+
+<para>
+To execute the procedures in a callback list, specifying the callback
+list by address, use
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallCallbackList'>
+<funcprototype>
+<funcdef>void <function>XtCallCallbackList</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>XtCallbackList <parameter>callbacks</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget instance that contains the callback list. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callbacks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list to be executed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a callback-list-specific data value to pass
+to each of the callback procedures in the list, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>callbacks</emphasis> parameter must specify the contents of a widget or
+object resource declared with representation type
+<function>XtRCallback</function>.
+If <emphasis remap='I'>callbacks</emphasis> is NULL,
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
+returns immediately; otherwise it calls each of the callback
+procedures in the list, passing the client data and <emphasis remap='I'>call_data</emphasis>.
+</para>
+</sect1>
+
+<sect1 id="Checking_the_Status_of_a_Callback_List">
+<title>Checking the Status of a Callback List</title>
+<para>
+To find out the status of a given widget's callback list, use
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>.
+</para>
+
+<para>
+typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus;
+</para>
+
+<funcsynopsis id='XtHasCallbacks'>
+<funcprototype>
+<funcdef>XtCallbackStatus <function>XtHasCallbacks</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>callback_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback list to be checked.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>
+function first checks to see if the widget has a callback list identified
+by <emphasis remap='I'>callback_name</emphasis>.
+If the callback list does not exist,
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>
+returns
+<function>XtCallbackNoList</function>.
+If the callback list exists but is empty,
+it returns
+<function>XtCallbackHasNone</function>.
+If the callback list exists and has at least one callback registered,
+it returns
+<function>XtCallbackHasSome</function>.
+</para>
+</sect1>
+</chapter>
diff --git a/specs/CH09.xml b/specs/CH09.xml
new file mode 100644
index 0000000..324fd2c
--- /dev/null
+++ b/specs/CH09.xml
@@ -0,0 +1,4326 @@
+<chapter id='Resource_Management'>
+<title>Resource Management</title>
+<para>
+A resource is a field in the widget record with a corresponding
+resource entry in the <emphasis remap='I'>resources</emphasis> list of the widget or any of its
+superclasses.
+This means that the field is
+settable by
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+(by naming the field in the argument list), by an
+entry in a resource file (by using either the name or class), and by
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+In addition, it is readable by
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+Not all fields in a widget record are resources.
+Some are for bookkeeping use by the
+generic routines (like <emphasis remap='I'>managed</emphasis> and <emphasis remap='I'>being_destroyed</emphasis>).
+Others can be for local bookkeeping,
+and still others are derived from resources
+(many graphics contexts and pixmaps).
+</para>
+
+<para>
+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
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+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.
+</para>
+<sect1 id="Resource_Lists">
+<title>Resource Lists</title>
+<para>
+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
+<function>XtResource</function>
+structure is
+</para>
+<literallayout >
+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;
+</literallayout>
+<para>
+When the resource list is specified as the
+<function>CoreClassPart</function>,
+<function>ObjectClassPart</function>,
+<function>RectObjClassPart</function>,
+or
+<function>ConstraintClassPart</function>
+<emphasis remap='I'>resources</emphasis> field, the strings pointed to by <emphasis remap='I'>resource_name</emphasis>,
+<emphasis remap='I'>resource_class</emphasis>, <emphasis remap='I'>resource_type</emphasis>, and <emphasis remap='I'>default_type</emphasis> must
+be permanently allocated prior to or during the execution of the class
+initialization procedure and must not be subsequently deallocated.
+</para>
+
+<para>
+The <emphasis remap='I'>resource_name</emphasis> 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 Intrinsics 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 Intrinsics are named in
+<function>&lt;X11/StringDefs.h&gt;</function>.
+The Intrinsics's symbolic resource names begin with
+``XtN''
+and are followed by the string name (for example, XtNbackgroundPixel
+for backgroundPixel).
+</para>
+
+<para>
+The <emphasis remap='I'>resource_class</emphasis> field contains the class string used in resource
+specification files to identify the field.
+A resource class provides two functions:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+It isolates an application from different representations that widgets
+can use for a similar resource.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+
+<para>
+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:
+</para>
+<literallayout >
+*Background: ivory
+*Foreground: darkblue
+</literallayout>
+<para>
+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:
+</para>
+<literallayout >
+*Font: 6x13
+</literallayout>
+<para>
+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).
+</para>
+
+<para>
+The <emphasis remap='I'>resource_type</emphasis> 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
+<function>String</function>)
+or the format of the resource default value
+(almost anything, but often
+<function>String</function>)
+to the desired
+physical representation (see <xref linkend='Resource_Conversions' />).
+The Intrinsics define the following resource types:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Resource Type</entry>
+ <entry>Structure or Field Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRAcceleratorTable</function></entry>
+ <entry>XtAccelerators</entry>
+ </row>
+ <row>
+ <entry><function>XtRAtom</function></entry>
+ <entry>Atom</entry>
+ </row>
+ <row>
+ <entry><function>XtRBitmap</function></entry>
+ <entry>Pixmap, depth=1</entry>
+ </row>
+ <row>
+ <entry><function>XtRBoolean</function></entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry><function>XtRBool</function></entry>
+ <entry>Bool</entry>
+ </row>
+ <row>
+ <entry><function>XtRCallback</function></entry>
+ <entry>XtCallbackList</entry>
+ </row>
+ <row>
+ <entry><function>XtRCardinal</function></entry>
+ <entry>Cardinal</entry>
+ </row>
+ <row>
+ <entry><function>XtRColor</function></entry>
+ <entry>XColor</entry>
+ </row>
+ <row>
+ <entry><function>XtRColormap</function></entry>
+ <entry>Colormap</entry>
+ </row>
+ <row>
+ <entry><function>XtRCommandArgArray</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRCursor</function></entry>
+ <entry>Cursor</entry>
+ </row>
+ <row>
+ <entry><function>XtRDimension</function></entry>
+ <entry>Dimension</entry>
+ </row>
+ <row>
+ <entry><function>XtRDirectoryString</function></entry>
+ <entry>String</entry>
+ </row>
+ <row>
+ <entry><function>XtRDisplay</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtREnum</function></entry>
+ <entry>XtEnum</entry>
+ </row>
+ <row>
+ <entry><function>XtREnvironmentArray</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFile</function></entry>
+ <entry>FILE*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFloat</function></entry>
+ <entry>float</entry>
+ </row>
+ <row>
+ <entry><function>XtRFont</function></entry>
+ <entry>Font</entry>
+ </row>
+ <row>
+ <entry><function>XtRFontSet</function></entry>
+ <entry>XFontSet</entry>
+ </row>
+ <row>
+ <entry><function>XtRFontStruct</function></entry>
+ <entry>XFontStruct*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFunction</function></entry>
+ <entry>(*)()</entry>
+ </row>
+ <row>
+ <entry><function>XtRGeometry</function></entry>
+ <entry>char*, format as defined by
+ <function>XParseGeometry</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRGravity</function></entry>
+ <entry>int</entry>
+ </row>
+ <row>
+ <entry><function>XtRInitialState</function></entry>
+ <entry>int</entry>
+ </row>
+ <row>
+ <entry><function>XtRInt</function></entry>
+ <entry>int</entry>
+ </row>
+ <row>
+ <entry><function>XtRLongBoolean</function></entry>
+ <entry>long</entry>
+ </row>
+ <row>
+ <entry><function>XtRObject</function></entry>
+ <entry>Object</entry>
+ </row>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry>Pixel</entry>
+ </row>
+ <row>
+ <entry><function>XtRPixmap</function></entry>
+ <entry>Pixmap</entry>
+ </row>
+ <row>
+ <entry><function>XtRPointer</function></entry>
+ <entry>XtPointer</entry>
+ </row>
+ <row>
+ <entry><function>XtRPosition</function></entry>
+ <entry>Position</entry>
+ </row>
+ <row>
+ <entry><function>XtRRestartStyle</function></entry>
+ <entry>unsigned char</entry>
+ </row>
+ <row>
+ <entry><function>XtRScreen</function></entry>
+ <entry>Screen*</entry>
+ </row>
+ <row>
+ <entry><function>XtRShort</function></entry>
+ <entry>short</entry>
+ </row>
+ <row>
+ <entry><function>XtRSmcConn</function></entry>
+ <entry>XtPointer</entry>
+ </row>
+ <row>
+ <entry><function>XtRString</function></entry>
+ <entry>String</entry>
+ </row>
+ <row>
+ <entry><function>XtRStringArray</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRStringTable</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRTranslationTable</function></entry>
+ <entry>XtTranslations</entry>
+ </row>
+ <row>
+ <entry><function>XtRUnsignedChar</function></entry>
+ <entry>unsigned char</entry>
+ </row>
+ <row>
+ <entry><function>XtRVisual</function></entry>
+ <entry>Visual*</entry>
+ </row>
+ <row>
+ <entry><function>XtRWidget</function></entry>
+ <entry>Widget</entry>
+ </row>
+ <row>
+ <entry><function>XtRWidgetClass</function></entry>
+ <entry>WidgetClass</entry>
+ </row>
+ <row>
+ <entry><function>XtRWidgetList</function></entry>
+ <entry>WidgetList</entry>
+ </row>
+ <row>
+ <entry><function>XtRWindow</function></entry>
+ <entry>Window</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<function>&lt;X11/StringDefs.h&gt;</function>
+also defines the following resource types as a
+convenience for widgets, although they do not have any corresponding
+data type assigned:
+<function>XtREditMode</function>,
+<function>XtRJustify</function>,
+and
+<function>XtROrientation</function>.
+</para>
+
+<para>
+The <emphasis remap='I'>resource_size</emphasis> field is the size of the physical representation in bytes;
+you should specify it as
+<function>sizeof</function>(type) so that the
+compiler fills in the value.
+The <emphasis remap='I'>resource_offset</emphasis> field is the offset in bytes of the field
+within the widget.
+You should use the
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>
+macro to retrieve this value.
+The <emphasis remap='I'>default_type</emphasis> field is the representation type of the default
+resource value.
+If <emphasis remap='I'>default_type</emphasis> is different from <emphasis remap='I'>resource_type</emphasis> and the default value
+is needed,
+the resource manager invokes a conversion procedure from <emphasis remap='I'>default_type</emphasis>
+to <emphasis remap='I'>resource_type</emphasis>.
+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,
+<function>XtDefaultForeground</function>
+for a pixel resource).
+The <emphasis remap='I'>default_addr</emphasis> field specifies the address of the default resource value.
+As a special case, if <emphasis remap='I'>default_type</emphasis> is
+<function>XtRString</function>,
+then the value in the <emphasis remap='I'>default_addr</emphasis> 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).
+</para>
+
+<para>
+Two special representation types
+(XtRImmediate
+and
+XtRCallProc)
+are usable only as default resource types.
+XtRImmediate
+indicates that the value in the <emphasis remap='I'>default_addr</emphasis> 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
+<function>XtPointer</function>.
+No conversion is possible, since there is no source representation type.
+XtRCallProc
+indicates that the value in the <emphasis remap='I'>default_addr</emphasis> field is a procedure
+pointer.
+This procedure is automatically invoked with the widget,
+<emphasis remap='I'>resource_offset</emphasis>, and a pointer to an
+<function>XrmValue</function>
+in which to store the result.
+XtRCallProc
+procedure pointers are of type
+<xref linkend='XtResourceDefaultProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResourceDefaultProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtResourceDefaultProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>int <parameter>offset</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose resource value is to be obtained.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset of the field in the widget record.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource value descriptor to return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtResourceDefaultProc' xrefstyle='select: title'/>
+procedure should fill in the <emphasis remap='I'>value-&gt;addr</emphasis> field with a pointer
+to the resource value in its correct representation type.
+</para>
+
+<para>
+To get the resource list structure for a particular class, use
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetResourceList'>
+<funcprototype>
+<funcdef>void <function>XtGetResourceList</function></funcdef>
+
+ <paramdef>WidgetClass <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList *<parameter>resources_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_resources_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object class to be queried. It must be
+<function>objectClass</function>
+or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>
+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,
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>
+returns a merged resource list that includes the resources
+for all superclasses.
+The list returned by
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+<para>
+To get the constraint resource list structure for a particular widget
+class, use
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetConstraintResourceList'>
+<funcprototype>
+<funcdef>void <function>XtGetConstraintResourceList</function></funcdef>
+ <paramdef>WidgetClass <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList *<parameter>resources_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_resources_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object class to be queried. It must be
+<function>objectClass</function>
+or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the constraint resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of entries in the constraint resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
+is called before the widget class is
+initialized, the resource list as specified in the widget
+class Constraint part is returned. If
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
+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
+<function>constraintWidgetClass</function>,
+*<emphasis remap='I'>resources_return</emphasis> is set to NULL
+and *<emphasis remap='I'>num_resources_return</emphasis> is set to zero.
+The list returned by
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+<para>
+The routines
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+and
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+also use the resource list to set and get widget state;
+see <xref linkend='Obtaining_Widget_State' /> and
+<xref linkend='Setting_Widget_State' />.
+</para>
+
+<para>
+Here is an abbreviated version of a possible resource list for a Label widget:
+</para>
+<literallayout >
+/* 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},
+ .
+ .
+ .
+}
+</literallayout>
+<para>
+The complete resource name for a field of a widget instance is the
+concatenation of the application shell name (from
+<function>XtAppCreateShell ),</function>
+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
+<function>XtAppCreateShell ),</function>
+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.
+</para>
+</sect1>
+
+<sect1 id="Byte_Offset_Calculations">
+<title>Byte Offset Calculations</title>
+<para>
+To determine the byte offset of a field within a structure type, use
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOffsetOf'>
+<funcprototype>
+<funcdef>Cardinal <function>XtOffsetOf</function></funcdef>
+ <paramdef>Type <parameter>structure_type</parameter></paramdef>
+ <paramdef>Field <parameter>field_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>structure_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a type that is declared as a structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>field_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of a member within the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>
+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
+<xref linkend='XtOffset' xrefstyle='select: title'/>,
+which serves the same function.
+</para>
+
+<para>
+To determine the byte offset of a field within a structure pointer type, use
+<xref linkend='XtOffset' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOffset'>
+<funcprototype>
+<funcdef>Cardinal <function>XtOffset</function></funcdef>
+ <paramdef>Type <parameter> pointer_type</parameter></paramdef>
+ <paramdef>Field <parameter> field_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a type that is declared as a pointer to a structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>field_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of a member within the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOffset' xrefstyle='select: title'/>
+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.
+<xref linkend='XtOffset' xrefstyle='select: title'/>
+is less portable than
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Superclass_to_Subclass_Chaining_of_Resource_Lists">
+<title>Superclass-to-Subclass Chaining of Resource Lists</title>
+<para>
+The
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+function gets resources as a superclass-to-subclass chained operation.
+That is, the resources specified in the
+<function>objectClass</function>
+resource list are fetched,
+then those in
+<function>rectObjClass</function>,
+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.
+</para>
+
+<para>
+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 <emphasis remap='I'>background_pixel</emphasis>.
+Consequently,
+the implementation of Label need not also have a resource entry
+for <emphasis remap='I'>background_pixel</emphasis>.
+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.
+</para>
+
+<para>
+Also at class initialization time, the Intrinsics produce an
+internal representation of the resource list to optimize access time
+when creating widgets. In order to save memory, the Intrinsics 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.
+</para>
+</sect1>
+
+<sect1 id="Subresources">
+<title>Subresources</title>
+<para>
+A widget does not do anything to retrieve its own resources;
+instead,
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+does this automatically before calling the class initialize procedure.
+</para>
+
+<para>
+Some widgets have subparts that are not widgets but for which the widget
+would like to fetch resources.
+Such widgets call
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+to accomplish this.
+</para>
+
+<funcsynopsis id='XtGetSubresources'>
+<funcprototype>
+<funcdef>void <function>XtGetSubresources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object used to qualify the subpart resource name and
+class. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list for the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+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 <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>class</emphasis> 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 <emphasis remap='I'>args</emphasis> is NULL,
+<emphasis remap='I'>num_args</emphasis> must be zero.
+However, if <emphasis remap='I'>num_args</emphasis> is zero,
+the argument list is not referenced.
+</para>
+
+<para>
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+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
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To fetch resources for widget subparts using varargs lists, use
+<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetSubresources'>
+<funcprototype>
+<funcdef>void <function>XtVaGetSubresources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object used to qualify the subpart resource name and
+class. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list for the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+</para>
+</sect1>
+
+<sect1 id="Obtaining_Application_Resources">
+<title>Obtaining Application Resources</title>
+<para>
+To retrieve resources that are not specific to a widget
+but apply to the overall application, use
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetApplicationResources'>
+<funcprototype>
+<funcdef>void <function>XtGetApplicationResources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object that identifies the resource database to search
+(the database is that associated with the display for this object). Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address into which
+the resource values will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+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,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+copies the resources into the addresses
+obtained by adding <emphasis remap='I'>base</emphasis> to each <emphasis remap='I'>offset</emphasis> in the resource list.
+If <emphasis remap='I'>args</emphasis> is NULL,
+<emphasis remap='I'>num_args</emphasis> must be zero.
+However, if <emphasis remap='I'>num_args</emphasis> 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 <emphasis remap='I'>base</emphasis> argument.
+</para>
+
+<para>
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+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
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+will not be freed from the resource cache until the display is closed.
+</para>
+
+<para>
+To retrieve resources for the overall application using varargs lists, use
+<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetApplicationResources'>
+<funcprototype>
+<funcdef>void <function>XtVaGetApplicationResources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object that identifies the resource database to search
+(the database is that associated with the display for this object). Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address into which
+the resource values will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list for the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters
+replaced by a varargs list, as described in Section 2.5.1.
+</para>
+</sect1>
+
+<sect1 id="Resource_Conversions">
+<title>Resource Conversions</title>
+<para>
+The Intrinsics provide a mechanism for registering representation converters that
+are automatically invoked by the resource-fetching routines.
+The Intrinsics additionally provide and register several commonly used converters.
+This resource conversion mechanism serves several purposes:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+It permits user and application resource files to contain textual
+representations of nontextual values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Predefined_Resource_Converters">
+<title>Predefined Resource Converters</title>
+<para>
+The Intrinsics define all the representations used in the
+Object,
+RectObj,
+Core,
+Composite,
+Constraint,
+and
+Shell
+widget classes.
+The Intrinsics register the following resource converters that accept
+input values of representation type
+<function>XtRString</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='0.8*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='0.6*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRAcceleratorTable</function></entry>
+ <entry><function>XtCvtStringToAcceleratorTable</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRAtom</function></entry>
+ <entry><function>XtCvtStringToAtom</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRBoolean</function></entry>
+ <entry><function>XtCvtStringToBoolean</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRBool</function></entry>
+ <entry><function>XtCvtStringToBool</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRCommandArgArray</function></entry>
+ <entry><function>XtCvtStringToCommandArgArray</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRCursor</function></entry>
+ <entry><function>XtCvtStringToCursor</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRDimension</function></entry>
+ <entry><function>XtCvtStringToDimension</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRDirectoryString</function></entry>
+ <entry><function>XtCvtStringToDirectoryString</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRDisplay</function></entry>
+ <entry><function>XtCvtStringToDisplay</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFile</function></entry>
+ <entry><function>XtCvtStringToFile</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFloat</function></entry>
+ <entry><function>XtCvtStringToFloat</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFont</function></entry>
+ <entry><function>XtCvtStringToFont</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFontSet</function></entry>
+ <entry><function>XtCvtStringToFontSet</function></entry>
+ <entry>Display*, String <emphasis remap='I'>locale</emphasis></entry>
+ </row>
+ <row>
+ <entry><function>XtRFontStruct</function></entry>
+ <entry><function>XtCvtStringToFontStruct</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRGravity</function></entry>
+ <entry><function>XtCvtStringToGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRInitialState</function></entry>
+ <entry><function>XtCvtStringToInitialState</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRInt</function></entry>
+ <entry><function>XtCvtStringToInt</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry><function>XtCvtStringToPixel</function></entry>
+ <entry><function>colorConvertArgs</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPosition</function></entry>
+ <entry><function>XtCvtStringToPosition</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRRestartStyle</function></entry>
+ <entry><function>XtCvtStringToRestartStyle</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRShort</function></entry>
+ <entry><function>XtCvtStringToShort</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRTranslationTable</function></entry>
+ <entry><function>XtCvtStringToTranslationTable</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRUnsignedChar</function></entry>
+ <entry><function>XtCvtStringToUnsignedChar</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRVisual</function></entry>
+ <entry><function>XtCvtStringToVisual</function></entry>
+ <entry>Screen*, Cardinal <emphasis remap='I'>depth</emphasis></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The String-to-Pixel conversion has two predefined constants that are
+guaranteed to work and contrast with each other:
+<function>XtDefaultForeground</function>
+and
+<function>XtDefaultBackground</function>.
+They evaluate to the black and white pixel values of the widget's screen,
+respectively.
+If the application resource reverseVideo is
+<function>True</function>,
+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
+<function>XtDefaultFont</function>
+and evaluate this in the following manner:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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
+<function>XtRString</function>
+value returned as the font name or a type
+<function>XtRFont</function>
+or
+<function>XtRFontStruct</function>
+value directly as the resource value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<function>XListFonts</function>
+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".)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no suitable ISO8859-1 font can be found, issue a warning message
+and return
+<function>False</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The String-to-FontSet converter recognizes the constant
+<function>XtDefaultFontSet</function>
+and evaluate this in the following manner:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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
+<function>XtRString</function>
+value returned as the base font name list or a type
+<function>XtRFontSet</function>
+value directly as the resource value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+<function>XCreateFontSet</function>
+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-*-*-*-*".)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no suitable font set can be created, issue a warning message
+and return
+<function>False</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+If a font set is created but <emphasis remap='I'>missing_charset_list</emphasis> is not
+empty, a warning is issued and the partial font set is returned.
+The Intrinsics 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.
+</para>
+
+<para>
+The String-to-Gravity conversion accepts string values that are the
+names of window and bit gravities and their numerical equivalents,
+as defined in <emphasis remap='I'>Xlib — C Language X Interface.</emphasis>:
+<function>ForgetGravity</function>,
+<function>UnmapGravity</function>,
+<function>NorthWestGravity</function>,
+<function>NorthGravity</function>,
+<function>NorthEastGravity</function>,
+<function>WestGravity</function>,
+<function>CenterGravity</function>,
+<function>EastGravity</function>,
+<function>SouthWestGravity</function>,
+<function>SouthGravity</function>,
+<function>SouthEastGravity</function>,
+and
+<function>StaticGravity</function>.
+Alphabetic case is not significant in the conversion.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+The String-to-RestartStyle conversion accepts the values
+<function>RestartIfRunning</function>,
+<function>RestartAnyway</function>,
+<function>RestartImmediately</function>,
+and
+<function>RestartNever</function>
+as defined by the <emphasis remap='I'>X Session Management Protocol</emphasis>.
+</para>
+
+<para>
+The String-to-InitialState conversion accepts the values
+<function>NormalState</function>
+or
+<function>IconicState</function>
+as defined by the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>.
+</para>
+
+<para>
+The String-to-Visual conversion calls
+<function>XMatchVisualInfo</function>
+using the
+<emphasis remap='I'>screen</emphasis> and <emphasis remap='I'>depth</emphasis> 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
+<function>XtRVisual</function>
+after the depth resource.
+The allowed string values are the visual class names defined in <emphasis remap='I'>X Window System Protocol</emphasis>,
+Section 8;
+<function>StaticGray</function>,
+<function>StaticColor</function>,
+<function>TrueColor</function>,
+<function>GrayScale</function>,
+<function>PseudoColor</function>,
+and
+<function>DirectColor</function>.
+</para>
+
+<para>
+The Intrinsics register the following resource converter that accepts
+an input value of representation type
+<function>XtRColor</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry><function>XtCvtColorToPixel</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics register the following resource converters that accept
+input values of representation type
+<function>XtRInt</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRBoolean</function></entry>
+ <entry><function>XtCvtIntToBoolean</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRBool</function></entry>
+ <entry><function>XtCvtIntToBool</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRColor</function></entry>
+ <entry><function>XtCvtIntToColor</function></entry>
+ <entry><function>colorConvertArgs</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRDimension</function></entry>
+ <entry><function>XtCvtIntToDimension</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFloat</function></entry>
+ <entry><function>XtCvtIntToFloat</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFont</function></entry>
+ <entry><function>XtCvtIntToFont</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry><function>XtCvtIntToPixel</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPixmap</function></entry>
+ <entry><function>XtCvtIntToPixmap</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPosition</function></entry>
+ <entry><function>XtCvtIntToPosition</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRShort</function></entry>
+ <entry><function>XtCvtIntToShort</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRUnsignedChar</function></entry>
+ <entry><function>XtCvtIntToUnsignedChar</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics register the following resource converter that accepts
+an input value of representation type
+<function>XtRPixel</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRColor</function></entry>
+ <entry><function>XtCvtPixelToColor</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</sect2>
+
+<sect2 id="New_Resource_Converters">
+<title>New Resource Converters</title>
+<para>
+Type converters use pointers to
+<function>XrmValue</function>
+structures (defined in
+<function>&lt;X11/Xresource.h&gt;;</function>
+see <olink targetdoc='libX11' targetptr='Creating_and_Storing_Databases'>Section 15.4</olink> in
+<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface.</olink>)
+for input and output values.
+</para>
+<literallayout >
+typedef struct {
+ unsigned int size;
+ XPointer addr;
+} XrmValue, *XrmValuePtr;
+</literallayout>
+<para>
+The <emphasis remap='I'>addr</emphasis> field specifies the address of the data, and the <emphasis remap='I'>size</emphasis>
+field gives the total number of significant bytes in the data.
+For values of type
+<function>String</function>,
+<emphasis remap='I'>addr</emphasis> is the address of the first character and <emphasis remap='I'>size</emphasis>
+includes the NULL-terminating byte.
+</para>
+
+<para>
+A resource converter procedure pointer is of type
+<xref linkend='XtTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTypeConverter'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtTypeConverter)</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>from</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>to</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>converter_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection with which this conversion is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of additional
+<function>XrmValue</function>
+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 <emphasis remap='I'>display</emphasis>,
+and the String-to-Pixel converter needs the widget's <emphasis remap='I'>screen</emphasis> and <emphasis remap='I'>colormap</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for a location into which to store the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location into which the converter may
+store converter-specific data associated
+with this conversion.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>display</emphasis> argument is normally used only when generating error
+messages, to identify the application context (with the function
+<function>XtDisplayToApplicationContext ).</function>
+</para>
+
+<para>
+The <emphasis remap='I'>to</emphasis> argument specifies the size and location into which the
+converter should store the converted value. If the <emphasis remap='I'>addr</emphasis> field is NULL,
+the converter should allocate appropriate storage and store the size
+and location into the <emphasis remap='I'>to</emphasis> 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
+<emphasis remap='I'>addr</emphasis> field is not NULL, the converter must check the <emphasis remap='I'>size</emphasis> field to
+ensure that sufficient space has been allocated before storing the
+converted value. If insufficient space is specified, the converter
+should update the <emphasis remap='I'>size</emphasis> field with the number of bytes required and
+return
+<function>False</function>
+without modifying the data at the specified location.
+If sufficient space was allocated by the caller, the converter should
+update the <emphasis remap='I'>size</emphasis> field with the number of bytes actually occupied by the
+converted value. For converted values of type
+<function>XtRString</function>,
+the size should
+include the NULL-terminating byte, if any.
+The converter may store any value in the location specified
+in <emphasis remap='I'>converter_data</emphasis>; this value will be passed to the destructor, if any,
+when the resource is freed by the Intrinsics.
+</para>
+
+<para>
+The converter must return
+<function>True</function>
+if the conversion was successful and
+<function>False</function>
+otherwise. If the conversion cannot be performed because of an
+improper source value, a warning message should also be issued with
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Most type converters just take the data described by the specified <emphasis remap='I'>from</emphasis>
+argument and return data by writing into the location specified in
+the <emphasis remap='I'>to</emphasis> argument.
+A few need other information, which is available in <emphasis remap='I'>args</emphasis>.
+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.
+</para>
+
+<para>
+Note that if an address is written into <emphasis remap='I'>to-&gt;addr</emphasis>, 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,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+or
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+in an implementation-defined manner; however, insertion of new entries
+or changes to existing entries is allowed and will not directly cause
+an error.
+</para>
+
+<para>
+The following is an example of a converter that takes a
+<function>string</function>
+and converts it to a
+<function>Pixel</function>.
+Note that the <emphasis remap='I'>display</emphasis> parameter is
+used only to generate error messages; the
+<function>Screen</function>
+conversion argument is
+still required to inform the Intrinsics that the converted value is
+a function of the particular display (and colormap).
+</para>
+
+<literallayout >
+#define done(type, value) \\
+ { \\
+ if (toVal-&gt;addr != NULL) { \\
+ if (toVal-&gt;size &lt; sizeof(type)) { \\
+ toVal-&gt;size = sizeof(type); \\
+ return False; \\
+ } \\
+ *(type*)(toVal-&gt;addr) = (value); \\
+ } \\
+ else { \\
+ static type static_val; \\
+ static_val = (value); \\
+ toVal-&gt;addr = (XPointer)&amp;static_val; \\
+ } \\
+ toVal-&gt;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-&gt;addr,
+ &amp;screenColor, &amp;exactColor);
+ if (status == 0) {
+ String params[1];
+ Cardinal num_params = 1;
+ params[0] = (String)fromVal-&gt;addr;
+ XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
+ "noColormap", "cvtStringToPixel", "XtToolkitError",
+ "Cannot allocate colormap entry for \\"%s\\"", params,\
+ &amp;num_params);
+ *converter_data = (char *) False;
+ return False;
+ } else {
+ *converter_data = (char *) True;
+ done(Pixel, &amp;screenColor.pixel);
+ }
+}
+</literallayout>
+
+<para>
+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
+<function>XtDefaultForeground</function>,
+<function>XtDefaultBackground</function>,
+and
+<function>XtDefaultFont</function>.
+</para>
+
+<para>
+To allow the Intrinsics to deallocate resources produced by type
+converters, a resource destructor procedure may also be provided.
+</para>
+
+<para>
+A resource destructor procedure pointer is of type
+<xref linkend='XtDestructor' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDestructor'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtDestructor)</function></funcdef>
+ <paramdef>XtAppContext <parameter>app</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>to</parameter></paramdef>
+ <paramdef>XtPointer <parameter>converter_data</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an application context in which the resource is being freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for the resource produced by the type converter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the converter-specific data returned by the type converter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional converter arguments as passed
+to the type converter when the conversion was performed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The destructor procedure is responsible for freeing the resource
+specified by the <emphasis remap='I'>to</emphasis> argument, including any auxiliary storage
+associated with that resource, but not the memory directly addressed
+by the size and location in the <emphasis remap='I'>to</emphasis> argument or the memory specified
+by <emphasis remap='I'>args</emphasis>.
+</para>
+</sect2>
+
+<sect2 id="Issuing_Conversion_Warnings">
+<title>Issuing Conversion Warnings</title>
+<para>
+The
+<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/>
+procedure is a convenience routine for resource type converters
+that convert from string values.
+</para>
+
+<funcsynopsis id='XtDisplayStringConversionWarning'>
+<funcprototype>
+<funcdef>void <function>XtDisplayStringConversionWarning</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>from_value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection with which the conversion is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string that could not be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target representation type requested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/>
+procedure issues a warning message using
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>
+with <emphasis remap='I'>name</emphasis> ``conversionError'',
+<emphasis remap='I'>type</emphasis> ``string'', <emphasis remap='I'>class</emphasis> ``XtToolkitError'', and the default message
+``Cannot convert "<emphasis remap='I'>from_value</emphasis>" to type <emphasis remap='I'>to_type</emphasis>''.
+</para>
+
+<para>
+To issue other types of warning or error messages, the type converter
+should use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To retrieve the application context associated with a given
+display connection, use
+<xref linkend='XtDisplayToApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDisplayToApplicationContext'>
+<funcprototype>
+<funcdef>XtAppContext <function>XtDisplayToApplicationContext</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an open and initialized display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisplayToApplicationContext' xrefstyle='select: title'/>
+function returns the application
+context in which the specified <emphasis remap='I'>display</emphasis> was initialized. If the
+display is not known to the Intrinsics, an error message is issued.
+</para>
+</sect2>
+
+<sect2 id="Registering_a_New_Resource_Converter">
+<title>Registering a New Resource Converter</title>
+<para>
+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 <function>XtCacheType</function>
+argument. </para>
+
+<literallayout >
+typedef int XtCacheType;
+</literallayout>
+
+<para>
+An <function>XtCacheType</function>
+field may contain one of the following values:
+</para>
+
+<para>
+<function>XtCacheNone</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtCacheAll</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtCacheByDisplay</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that the results of a previous conversion
+should be used as for
+<function>XtCacheAll</function>
+but the destructor will be called, if specified, if
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+is called
+for the display connection associated with the converted value, and
+the value will be removed from the conversion cache.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The qualifier
+<function>XtCacheRefCount</function>
+may be ORed with any of the above values. If
+<function>XtCacheRefCount</function>
+is specified, calls to
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To register a type converter for all application contexts in a
+process, use
+<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>,
+and to register a type converter in a single application context, use
+<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetTypeConverter'>
+<funcprototype>
+<funcdef>void <function>XtSetTypeConverter</function></funcdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XtCacheType <parameter>cache_type</parameter></paramdef>
+ <paramdef>XtDestructor <parameter>destructor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource type converter procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional conversion arguments, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cache_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not resources produced by this
+converter are sharable or display-specific and when
+they should be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destructor</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<funcsynopsis id='XtAppSetTypeConverter'>
+<funcprototype>
+<funcdef> <function>XtAppSetTypeConverter</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XtCacheType <parameter>cache_type</parameter></paramdef>
+ <paramdef>XtDestructor <parameter>destructor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource type converter procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional conversion arguments, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cache_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not resources produced by this
+converter are sharable or display-specific and when
+they should be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destructor</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>
+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.
+<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>
+registers the specified type converter in the
+single application context specified. If the same <emphasis remap='I'>from_type</emphasis> and
+<emphasis remap='I'>to_type</emphasis> are specified in multiple calls to either function, the most
+recent overrides the previous ones.
+</para>
+
+<para>
+For the few type converters that need additional arguments,
+the Intrinsics conversion mechanism provides a method of specifying
+how these arguments should be computed.
+The enumerated type
+<function>XtAddressMode</function>
+and the structure
+<function>XtConvertArgRec</function>
+specify how each argument is derived.
+These are defined in
+<function>&lt;X11/Intrinsic.h&gt;</function>.
+</para>
+<literallayout >
+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;
+
+typedef struct {
+ XtAddressMode address_mode;
+ XtPointer address_id;
+ Cardinal size;
+} XtConvertArgRec, *XtConvertArgList;
+</literallayout>
+<para>
+The <emphasis remap='I'>size</emphasis> field specifies the length of the data in bytes.
+The <emphasis remap='I'>address_mode</emphasis> field specifies how the <emphasis remap='I'>address_id</emphasis> field should be
+interpreted.
+<function>XtAddress</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the address of the data.
+<function>XtBaseOffset</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the offset from the widget base.
+<function>XtImmediate</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as a constant.
+<function>XtResourceString</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the name of a resource
+that is to be converted into an offset from the widget base.
+<function>XtResourceQuark</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the result of an
+<function>XrmStringToQuark</function>
+conversion on the name of a resource,
+which is to be converted into an offset from the widget base.
+<function>XtWidgetBaseOffset</function>
+is similar to
+<function>XtBaseOffset</function>
+except that it
+searches for the closest windowed ancestor if the object is not
+of a subclass of
+Core
+(see <xref linkend='Nonwidget_Objects' />).
+<function>XtProcedureArg</function>
+specifies that <emphasis remap='I'>address_id</emphasis> is a pointer to a procedure to
+be invoked to return the conversion argument. If
+<function>XtProcedureArg</function>
+is specified, <emphasis remap='I'>address_id</emphasis> must contain
+the address of a function of type
+<xref linkend='XtConvertArgProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertArgProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtConvertArgProc)</function></funcdef>
+ <paramdef>XtAppContext <parameter>app</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>to</parameter></paramdef>
+ <paramdef>XtPointer <parameter>converter_data</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an application context in which the resource is being freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for the resource produced by the type converter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the converter-specific data returned by the type converter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional converter arguments as passed
+to the type converter when the conversion was performed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The destructor procedure is responsible for freeing the resource
+specified by the <emphasis remap='I'>to</emphasis> argument, including any auxiliary storage
+associated with that resource, but not the memory directly addressed
+by the size and location in the <emphasis remap='I'>to</emphasis> argument or the memory specified
+by <emphasis remap='I'>args</emphasis>.
+</para>
+</sect2>
+
+<sect2 id="Resource_Converter_Invocation">
+<title>Resource Converter Invocation</title>
+<para>
+All resource-fetching routines (for example,
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+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.
+</para>
+
+<para>
+To invoke explicit resource conversions, use
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+or
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>.
+</para>
+<literallayout >
+typedef XtPointer XtCacheRef;
+</literallayout>
+
+<funcsynopsis id='XtCallConverter'>
+<funcprototype>
+<funcdef>Boolean <function>XtCallConverter</function></funcdef>
+ <paramdef>Display* <parameter>display</parameter></paramdef>
+ <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>conversion_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef>
+ <paramdef>XtCacheRef *<parameter>cache_ref_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display with which the conversion is to be associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>conversion_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional conversion arguments needed
+to perform the conversion, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>conversion_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for the source value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cache_ref_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a conversion cache id.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+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
+<function>XtCacheAll</function>
+or
+<function>XtCacheByDisplay</function>,
+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,
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+returns
+<function>False</function>
+immediately;
+otherwise it checks the size specified in the <emphasis remap='I'>to</emphasis> 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
+<emphasis remap='I'>to-&gt;addr</emphasis>, stores the cache size into <emphasis remap='I'>to-&gt;size</emphasis>, and returns
+<function>True</function>.
+If the size specified in the <emphasis remap='I'>to</emphasis> argument is smaller than the size stored
+in the cache,
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+copies the cache size into <emphasis remap='I'>to-&gt;size</emphasis> and returns
+<function>False</function>.
+If the converter was registered with cache type
+<function>XtCacheNone</function>
+or no value was found in the conversion cache,
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+calls the converter, and if it was not registered with cache type
+<function>XtCacheNone</function>,
+enters the result in the cache.
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+then returns what the converter returned.
+</para>
+
+<para>
+The <emphasis remap='I'>cache_ref_return</emphasis> field specifies storage allocated by the caller in which
+an opaque value will be stored. If the type converter has been
+registered with the
+<function>XtCacheRefCount</function>
+modifier and if the value returned
+in <emphasis remap='I'>cache_ref_return</emphasis> is non-NULL, then the caller should store the
+<emphasis remap='I'>cache_ref_return</emphasis> value in order to decrement the reference count when
+the converted value is no longer required. The <emphasis remap='I'>cache_ref_return</emphasis>
+argument should be
+NULL if the caller is unwilling or unable to store the
+value.
+</para>
+
+<para>
+To explicitly decrement the reference counts for resources obtained
+from
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>,
+use
+<xref linkend='XtAppReleaseCacheRefs' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppReleaseCacheRefs'>
+<funcprototype>
+<funcdef>void <function>XtAppReleaseCacheRefs</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtCacheRef *<parameter>refs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>refs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of cache references to be released.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppReleaseCacheRefs' xrefstyle='select: title'/>
+decrements the reference count for the
+conversion entries identified by the <emphasis remap='I'>refs</emphasis> argument.
+This argument is a
+pointer to a NULL-terminated list of
+<function>XtCacheRef</function>
+values. If any reference
+count reaches zero, the destructor, if any, will be called and
+the resource removed from the conversion cache.
+</para>
+
+<para>
+As a convenience to clients needing to explicitly decrement reference
+counts via a callback function, the Intrinsics define two callback
+procedures,
+<xref linkend='XtCallbackReleaseCacheRef' xrefstyle='select: title'/>
+and
+<xref linkend='XtCallbackReleaseCacheRefList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallbackReleaseCacheRef'>
+<funcprototype>
+<funcdef>void <function>XtCallbackReleaseCacheRef</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object with which the resource is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion cache entry to be released.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This callback procedure may be added to a callback list to release a
+previously returned
+<function>XtCacheRef</function>
+value. When adding the callback, the
+callback <emphasis remap='I'>client_data</emphasis> argument must be specified as the value of the
+<function>XtCacheRef</function>
+data cast to type
+<function>XtPointer</function>.
+</para>
+
+<funcsynopsis id='XtCallbackReleaseCacheRefList'>
+<funcprototype>
+<funcdef>void <function>XtCallbackReleaseCacheRefList</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object with which the resources are associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion cache entries to be released.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This callback procedure may be added to a callback list to release a
+list of previously returned
+<function>XtCacheRef</function>
+values. When adding the
+callback, the callback <emphasis remap='I'>client_data</emphasis> argument must be specified as a
+pointer to a NULL-terminated list of
+<function>XtCacheRef</function>
+values.
+</para>
+
+<para>
+To lookup and call a resource converter, copy the resulting value,
+and free a cached resource when a widget is destroyed, use
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertAndStore'>
+<funcprototype>
+<funcdef>Boolean <function>XtConvertAndStore</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object to use for additional arguments, if any are needed,
+and the destroy callback list. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for storage into which the converted value
+will be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+function looks up the type converter registered
+to convert <emphasis remap='I'>from_type</emphasis> to <emphasis remap='I'>to_type</emphasis>, computes any additional arguments
+needed, and then calls
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+(or
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>
+if an old-style converter was registered with
+<xref linkend='XtAddConverter' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppAddConverter' xrefstyle='select: title'/>;
+see Appendix C) with the <emphasis remap='I'>from</emphasis> and <emphasis remap='I'>to_in_out</emphasis> arguments. The
+<emphasis remap='I'>to_in_out</emphasis> 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 <emphasis remap='I'>size</emphasis> field will be modified on return to indicate the actual
+size of the converted data.
+If the conversion succeeds,
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+returns
+<function>True</function>;
+otherwise, it returns
+<function>False</function>.
+</para>
+
+<para>
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+adds
+<xref linkend='XtCallbackReleaseCacheRef' xrefstyle='select: title'/>
+to the destroyCallback list of the specified object if the conversion
+returns an
+<function>XtCacheRef</function>
+value. The resulting resource should not be referenced
+after the object has been destroyed.
+</para>
+
+<para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+performs processing equivalent to
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+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
+<function>Boolean</function>
+resource
+XtNinitialResourcesPersistent,
+class
+XtCInitialResourcesPersistent.
+</para>
+
+<para>
+When
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+is called, if this resource is not specified as
+<function>False</function>
+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
+<function>True</function>;
+thus clients that expect to destroy one or
+more objects and want resources deallocated must explicitly specify
+<function>False</function>
+for
+XtNinitialResourcesPersistent.
+</para>
+
+<para>
+The resources are still freed and destructors called when
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+is called if the conversion was registered as
+<function>XtCacheByDisplay</function>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Reading_and_Writing_Widget_State">
+<title>Reading and Writing Widget State</title>
+<para>
+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.
+</para>
+<sect2 id="Obtaining_Widget_State">
+<title>Obtaining Widget State</title>
+<para>
+To retrieve the current values of resources associated with a
+widget instance, use
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetValues'>
+<funcprototype>
+<funcdef>void <function>XtGetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+function starts with the resources specified for the Object class
+and proceeds down the subclass chain to the class of the object.
+The <emphasis remap='I'>value</emphasis> 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
+Intrinsics-defined resources, the following lifetimes apply:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Not valid following any operation that modifies the resource:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+XtNchildren resource of composite widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All resources of representation type XtRCallback.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Remain valid at least until the widget is destroyed:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+XtNaccelerators, XtNtranslations.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Remain valid until the Display is closed:
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+XtNscreen.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+
+<para>
+If the class of the object's parent is a subclass of
+<function>constraintWidgetClass</function>,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+then fetches the values for any constraint resources requested.
+It starts with the constraint resources specified for
+<function>constraintWidgetClass</function>
+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.
+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
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+Finally, if the object's parent is a
+subclass of
+<function>constraintWidgetClass</function>,
+and if any of the parent's class or
+superclass records have declared
+<function>ConstraintClassExtension</function>
+records in
+the Constraint class part <emphasis remap='I'>extension</emphasis> field with a record type of
+<emphasis role='strong'>NULLQUARK</emphasis>,
+and if the <emphasis remap='I'>get_values_hook</emphasis> field in the extension record is non-NULL,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+calls the get_values_hook procedures in superclass-to-subclass order.
+This permits a Constraint parent to provide
+nonresource data via
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Get_values_hook procedures may modify the data stored at the
+location addressed by the <emphasis remap='I'>value</emphasis> field, including (but not
+limited to) making a copy of data whose resource representation is a
+pointer. None of the Intrinsics-defined object classes copy
+data in this manner. Any operation that modifies the queried
+object resource may invalidate the pointed-to data.
+</para>
+
+<para>
+To retrieve the current values of resources associated with a widget
+instance using varargs lists, use
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetValues'>
+<funcprototype>
+<funcdef>void <function>XtVaGetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef><parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list for the resources to
+be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis>
+and <emphasis remap='I'>num_args</emphasis> 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
+<function>XtVaTypedArg</function>
+is specified, the <emphasis remap='I'>type</emphasis> argument
+specifies the representation desired by the caller and <emphasis remap='I'>the</emphasis> 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.
+</para>
+<sect3 id="Widget_Subpart_Resource_Data_The_get_values_hook_Procedure">
+<title>Widget Subpart Resource Data: The get_values_hook Procedure</title>
+<para>
+Widgets that have subparts can return resource values from them through
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+by supplying a get_values_hook procedure.
+The get_values_hook procedure pointer is of type
+<xref linkend='XtArgsProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='_XtArgsProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtArgsProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose subpart resource values are to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list that was passed to
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+or the transformed varargs list passed to
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The widget with subpart resources should call
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>
+in the get_values_hook procedure
+and pass in its subresource list and the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters.
+</para>
+</sect3>
+<sect3 id="Widget_Subpart_State">
+<title>Widget Subpart State</title>
+<para>
+To retrieve the current values of subpart resource data associated with a
+widget instance, use
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>.
+For a discussion of subpart resources,
+see <xref linkend='Subresources' />.
+</para>
+
+<funcsynopsis id='XtGetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtGetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure for which the
+resources should be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>
+function obtains resource values from the structure identified by <emphasis remap='I'>base</emphasis>.
+The <emphasis remap='I'>value</emphasis> 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.
+</para>
+
+<para>
+To retrieve the current values of subpart resources associated with
+a widget instance using varargs lists, use
+<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtVaGetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure for which the
+resources should be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>
+with the
+<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described
+in Section 2.5.1.
+<function>XtVaTypedArg</function>
+is not supported for
+<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>.
+If
+<function>XtVaTypedArg</function>
+is specified in the list, a warning message is issued
+and the entry is then ignored.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Setting_Widget_State">
+<title>Setting Widget State</title>
+<para>
+To modify the current values of resources associated with a widget
+instance, use
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetValues'>
+<funcprototype>
+<funcdef>void <function>XtSetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list of name/value pairs that contain the
+resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+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 <emphasis remap='I'>object</emphasis> resource fields with any values
+specified in the argument list.
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+then calls the set_values procedures for the object in superclass-to-subclass
+order.
+If the object has any non-NULL <emphasis remap='I'>set_values_hook</emphasis> fields,
+these are called immediately after the
+corresponding set_values procedure.
+This procedure permits subclasses to set subpart data via
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+</para>
+
+<para>
+If the class of the object's parent is a subclass of
+<function>constraintWidgetClass</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+also updates the object's constraints.
+It starts with the constraint resources specified for
+<function>constraintWidgetClass</function>
+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
+<function>constraintWidgetClass</function>
+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.
+</para>
+
+<para>
+If the object is of a subclass of
+RectObj,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+determines if a geometry request is needed by comparing the old object to
+the new object.
+If any geometry changes are required,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+restores the original geometry and makes the request on behalf of the widget.
+If the geometry manager returns
+<function>XtGeometryYes</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+calls the object's resize procedure.
+If the geometry manager returns
+<function>XtGeometryDone</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+continues, as the object's resize procedure should have been called
+by the geometry manager.
+If the geometry manager returns
+<function>XtGeometryNo</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+ignores the geometry request and continues.
+If the geometry manager returns
+<function>XtGeometryAlmost</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+calls the set_values_almost procedure,
+which determines what should be done.
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+then repeats this process,
+deciding once more whether the geometry manager should be called.
+</para>
+
+<para>
+Finally, if any of the set_values procedures returned
+<function>True</function>,
+and the widget is realized,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+causes the widget's expose procedure to be invoked by calling
+<function>XClearArea</function>
+on the widget's window.
+</para>
+
+<para>
+To modify the current values of resources associated with a widget
+instance using varargs lists, use
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaSetValues'>
+<funcprototype>
+<funcdef>void <function>XtVaSetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list of name/value pairs that
+contain the resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+</para>
+<sect3 id="Widget_State_The_set_values_Procedure">
+<title>Widget State: The set_values Procedure</title>
+<para>
+The set_values procedure pointer in a widget class is of type
+<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetValuesFunc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtSetValuesFunc)</function></funcdef>
+
+ <paramdef>Widget <parameter>current</parameter></paramdef>
+ <paramdef>Widget <parameter>request</parameter></paramdef>
+ <paramdef>Widget <parameter>new</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>current</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the widget as it was before the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the widget with all values changed as asked for by the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call before any class set_values procedures have been called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget with the new values that are actually allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list passed to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+or the transformed argument list passed to
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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 <emphasis remap='I'>set_values</emphasis> field in the class record.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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?
+</para>
+
+<para>
+The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> parameters provide the necessary information.
+The <emphasis remap='I'>request</emphasis> widget is a copy of the widget, updated as originally requested.
+The <emphasis remap='I'>new</emphasis> 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 <emphasis remap='I'>request</emphasis> widget
+unless it must resolve conflicts between the <emphasis remap='I'>current</emphasis> and <emphasis remap='I'>new</emphasis> widgets.
+Any changes the widget needs to make, including geometry changes,
+should be made in the <emphasis remap='I'>new</emphasis> widget.
+</para>
+
+<para>
+In the above example,
+the subclass with the visual surround can see
+if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero.
+If so,
+it adds its surround size to the <emphasis remap='I'>width</emphasis> and
+<emphasis remap='I'>height</emphasis> fields in the <emphasis remap='I'>new</emphasis> 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.
+</para>
+
+<para>
+The <emphasis remap='I'>new</emphasis> widget is the actual widget instance record.
+Therefore,
+the set_values procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget;
+the <emphasis remap='I'>request</emphasis> widget should never be modified.
+If the set_values procedure needs to call any routines that operate on
+a widget, it should specify <emphasis remap='I'>new</emphasis> as the widget instance.
+</para>
+
+<para>
+Before calling the set_values procedures, the Intrinsics modify the
+resources of the <emphasis remap='I'>request</emphasis> 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 <emphasis remap='I'>args</emphasis>.
+</para>
+
+<para>
+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
+<function>True</function>;
+the X server will eventually generate an
+<function>Expose</function>
+event, if necessary.
+After calling all the set_values procedures,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+forces a redisplay by calling
+<function>XClearArea</function>
+if any of the set_values procedures returned
+<function>True</function>.
+Therefore, a set_values procedure should not try to do its own redisplaying.
+</para>
+
+<para>
+Set_values procedures should not do any work in response to changes in
+geometry because
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+eventually will perform a geometry request, and that request might be denied.
+If the widget actually changes size in response to a
+call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+its resize procedure is called.
+Widgets should do any geometry-related work in their resize procedure.
+</para>
+
+<para>
+Note that it is permissible to call
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+before a widget is realized.
+Therefore, the set_values procedure must not assume that the widget is realized.
+</para>
+</sect3>
+<sect3 id="Widget_State_The_set_values_almost_Procedure">
+<title>Widget State: The set_values_almost Procedure</title>
+<para>
+The set_values_almost procedure pointer in the widget class record is of type
+<xref linkend='XtAlmostProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAlmostProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtAlmostProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>old</parameter></paramdef>
+ <paramdef>Widget <parameter>new</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>reply</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>old</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the object as it was before the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object instance record.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the original geometry request that was sent to the geometry
+manager that caused
+<function>XtGeometryAlmost</function>
+to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>reply</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the compromise geometry that was returned by the geometry
+manager with
+<function>XtGeometryAlmost</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most classes inherit the set_values_almost procedure from their superclass by
+specifying
+<function>XtInheritSetValuesAlmost</function>
+in the class initialization.
+The
+set_values_almost procedure in
+<function>rectObjClass</function>
+accepts the compromise suggested.
+</para>
+
+<para>
+The set_values_almost procedure is called when a client tries to set a widget's
+geometry by means of a call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+and the geometry manager cannot
+satisfy the request but instead returns
+<function>XtGeometryNo</function>
+or
+<function>XtGeometryAlmost</function>
+and a compromise geometry.
+The <emphasis remap='I'>new</emphasis> object is the actual instance record. The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>,
+<emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> fields contain the original values as they were
+before the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call, and all other fields contain the new
+values. The <emphasis remap='I'>request</emphasis> parameter contains the new geometry request that
+was made to the parent. The <emphasis remap='I'>reply</emphasis> parameter contains
+<emphasis remap='I'>reply-&gt;request_mode</emphasis> equal to zero if the parent returned
+<function>XtGeometryNo</function>
+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 <emphasis remap='I'>request</emphasis> 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 <emphasis remap='I'>reply</emphasis> geometry into the <emphasis remap='I'>request</emphasis> geometry; to attempt an
+alternative geometry, the procedure may modify any part of the <emphasis remap='I'>request</emphasis>
+argument; to terminate the geometry negotiation and retain the
+original geometry, the procedure must set <emphasis remap='I'>request-&gt;request_mode</emphasis> to
+zero. The geometry fields of the <emphasis remap='I'>old</emphasis> and <emphasis remap='I'>new</emphasis> instances must not be modified
+directly.
+</para>
+</sect3>
+<sect3 id="Widget_State_The_ConstraintClassPart_set_values_Procedure">
+<title>Widget State: The ConstraintClassPart set_values Procedure</title>
+<para>
+The constraint set_values procedure pointer is of type
+<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>.
+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 <emphasis remap='I'>set_values</emphasis> field of the
+<function>ConstraintPart</function>
+if it need not compute anything.
+</para>
+
+<para>
+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 <emphasis remap='I'>height</emphasis> field in the
+widget.
+</para>
+</sect3>
+<sect3 id='Widget_Subpart_State_2'>
+<title>Widget Subpart State</title>
+<para>
+To set the current values of subpart resources associated with a
+widget instance, use
+<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>.
+For a discussion of subpart resources,
+see <xref linkend='Subresources' />.
+</para>
+
+<funcsynopsis id='XtSetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtSetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources should be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list of name/value pairs that contain the
+resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>
+function updates the resource fields of the structure identified by
+<emphasis remap='I'>base</emphasis>. Any specified arguments that do not match an entry in the
+resource list are silently ignored.
+</para>
+
+<para>
+To set the current values of subpart resources associated with
+a widget instance using varargs lists, use
+<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaSetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtVaSetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources should be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list of name/value pairs that
+contain the resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+<function>XtVaTypedArg</function>
+is not supported for
+<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>.
+If an entry containing
+<function>XtVaTypedArg</function>
+is specified in the list, a warning message is issued
+and the entry is ignored.
+</para>
+</sect3>
+
+<sect3 id='Widget_Subpart_Resource_Data_The_set_values_hook_Procedure'>
+<title>Widget Subpart Resource Data: The set_values_hook Procedure</title>
+<note><para>
+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.
+</para>
+</note>
+<para>
+Widgets that have a subpart can set the subpart resource values through
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+by supplying a set_values_hook procedure.
+The set_values_hook procedure pointer in a widget class is of type
+<xref linkend='XtArgsFunc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtArgsFunc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtArgsFunc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Arglist <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose subpart resource values are to be changed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list that was passed to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+or the transformed varargs list passed to
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The widget with subpart resources may call
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+from the set_values_hook procedure
+and pass in its subresource list and the
+<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters.
+</para>
+</sect3>
+</sect2>
+</sect1>
+</chapter>
diff --git a/specs/CH10.xml b/specs/CH10.xml
new file mode 100644
index 0000000..a96d2c4
--- /dev/null
+++ b/specs/CH10.xml
@@ -0,0 +1,2211 @@
+<chapter id='Translation_Management'>
+<title>Translation Management</title>
+<para>
+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.
+</para>
+
+<para>
+The translation manager provides an interface to specify and manage the
+mapping of X event sequences into widget-supplied functionality,
+for example, calling procedure <emphasis remap='I'>Abc</emphasis> when the <emphasis remap='I'>y</emphasis> key
+is pressed.
+</para>
+
+<para>
+The translation manager uses two kinds of tables to perform translations:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A translation table, which is in the widget class structure,
+specifies the mapping of event sequences to procedure name strings.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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 <xref linkend='Translation_Table_Management' />.
+</para>
+<sect1 id="Action_Tables">
+<title>Action Tables</title>
+<para>
+All widget class records contain an action table,
+an array of
+<function>XtActionsRec</function>
+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
+<xref linkend='XtActionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtActionProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtActionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that caused the action to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the list of strings that were specified
+in the translation table as arguments to the action, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<literallayout >
+typedef struct _XtActionsRec {
+ String string;
+ XtActionProc proc;
+} XtActionsRec, *XtActionList;
+</literallayout>
+<para>
+The <emphasis remap='I'>string</emphasis> field is the name used in translation tables to access
+the procedure.
+The <emphasis remap='I'>proc</emphasis> field is a pointer to a procedure that implements
+the functionality.
+</para>
+
+<para>
+When the action list is specified as the
+<function>CoreClassPart</function>
+<emphasis remap='I'>actions</emphasis> field, the string pointed to by <emphasis remap='I'>string</emphasis> must be
+permanently allocated prior to or during the execution of the class
+initialization procedure and must not be subsequently deallocated.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+For example, a Pushbutton widget has procedures to take the following actions:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Set the button to indicate it is activated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unset the button back to its normal mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Highlight the button borders.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unhighlight the button borders.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Notify any callbacks that the button has been activated.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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:
+</para>
+<literallayout >
+XtActionsRec actionTable[] = {
+ {"Set", Set},
+ {"Unset", Unset},
+ {"Highlight", Highlight},
+ {"Unhighlight", Unhighlight}
+ {"Notify", Notify},
+};
+</literallayout>
+<para>
+The Intrinsics 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 Intrinsics functions.
+</para>
+<sect2 id="Action_Table_Registration">
+<title>Action Table Registration</title>
+<para>
+The <emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis> fields of
+<function>CoreClassPart</function>
+specify the actions implemented by a widget class. These are
+automatically registered with the Intrinsics 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 Intrinsics may overwrite the storage in order to compile the
+list into an internal representation.
+</para>
+
+<para>
+To declare an action table within an application
+and register it with the translation manager, use
+<xref linkend='XtAppAddActions' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddActions'>
+<funcprototype>
+<funcdef>void <function>XtAppAddActions</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtActionList <parameter>actions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_actions</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action table to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_actions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in this action table.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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 Intrinsics register an action table containing
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+and
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+as part of
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
+</para>
+</sect2>
+
+<sect2 id="Action_Names_to_Procedure_Translations">
+<title>Action Names to Procedure Translations</title>
+<para>
+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:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+The widget's class and all superclass action tables, in subclass-to-superclass
+order.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The parent's class and all superclass action tables, in subclass-to-superclass
+order, then on up the ancestor tree.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The action tables registered with
+<xref linkend='XtAppAddActions' xrefstyle='select: title'/>
+and
+<xref linkend='XtAddActions' xrefstyle='select: title'/>
+from the most recently added table to the oldest table.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Action_Hook_Registration">
+<title>Action Hook Registration</title>
+<para>
+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
+<xref linkend='XtActionHookProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtActionHookProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtActionHookProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>String <parameter>action_name</parameter></paramdef>
+ <paramdef>XEvent* <parameter>event</parameter></paramdef>
+ <paramdef>String* <parameter>params</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose action is about to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application-specific closure that was passed to
+<function>XtAppAddActionHook.</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>action_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the action to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event argument that will be passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action parameters that will be passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Action hooks should not modify any of the data pointed to by the
+arguments other than the <emphasis remap='I'>client_data</emphasis> argument.
+</para>
+
+<para>
+To add an action hook, use
+<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddActionHook'>
+<funcprototype>
+<funcdef>XtActionHookId <function>XtAppAddActionHook</function></funcdef>
+ <paramdef>XtAppContext <parameter>app</parameter></paramdef>
+ <paramdef>XtActionHookProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action hook procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies application-specific data to be passed to the action hook.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>
+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
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
+the action hook procedures will be called in reverse
+order of registration just prior to invoking the action routine.
+</para>
+
+<para>
+Action hook procedures are removed automatically and the
+<function>XtActionHookId is</function>
+destroyed when the application context in which
+they were added is destroyed.
+</para>
+
+<para>
+To remove an action hook procedure without destroying the application
+context, use
+<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveActionHook'>
+<funcprototype>
+<funcdef>void <function>XtRemoveActionHook</function></funcdef>
+ <paramdef>XtActionHookId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action hook id returned by
+<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>
+removes the specified action hook procedure from
+the list in which it was registered.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Translation_Tables">
+<title>Translation Tables</title>
+<para>
+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.
+</para>
+
+<para>
+As an example, the default behavior of Pushbutton is
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Highlight on enter window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unhighlight on exit window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Invert on left button down.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Call callbacks and reinvert on left button up.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The following illustrates Pushbutton's default translation table:
+</para>
+<literallayout >
+static String defaultTranslations =
+ "&lt;EnterWindow&gt;: Highlight()\\n\\
+ &lt;LeaveWindow&gt;: Unhighlight()\\n\\
+ &lt;Btn1Down&gt;: Set()\\n\\
+ &lt;Btn1Up&gt;: Notify() Unset()";
+</literallayout>
+<para>
+The <emphasis remap='I'>tm_table</emphasis> field of the
+<function>CoreClassPart</function>
+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
+<function>XtInheritTranslations</function>
+into <emphasis remap='I'>tm_table</emphasis>.
+In Core's class part initialization procedure,
+the Intrinsics 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
+<xref linkend='Translation_Table_Management' />.
+</para>
+
+<para>
+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
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The Intrinsics 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.
+</para>
+<sect2 id="Event_Sequences">
+<title>Event Sequences</title>
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Action_Sequences">
+<title>Action Sequences</title>
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Multi_Click_Time">
+<title>Multi-Click Time</title>
+<para>
+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
+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
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+If no value is specified, the initial value is 200 milliseconds.
+</para>
+
+<para>
+To set the multi-click time dynamically, use
+<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetMultiClickTime'>
+<funcprototype>
+<funcdef>void <function>XtSetMultiClickTime</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the multi-click time in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>
+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
+<function>ButtonPress</function>
+events) must be less than the
+multi-click time in order for the translation actions to be taken.
+</para>
+
+<para>
+To read the multi-click time, use
+<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetMultiClickTime'>
+<funcprototype>
+<funcdef>int <function>XtGetMultiClickTime</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Translation_Table_Management">
+<title>Translation Table Management</title>
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+Three Intrinsics functions support this merging:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>XtParseTranslationTable</emphasis>
+ </term>
+ <listitem>
+ <para>Compiles a translation table.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>XtAugmentTranslations</emphasis>
+ </term>
+ <listitem>
+ <para>Merges a compiled translation table into a widget's
+ compiled translation table, ignoring any new translations that
+ conflict with existing translations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>XtOverrideTranslations</emphasis>
+ </term>
+ <listitem>
+ <para>Merges a compiled translation table into a widget's
+ compiled translation table, replacing any existing translations that
+ conflict with new translations.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To compile a translation table, use
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtParseTranslationTable'>
+<funcprototype>
+<funcdef>XtTranslations <function>XtParseTranslationTable</function></funcdef>
+ <paramdef>String <parameter>table</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the translation table to compile.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
+function compiles the translation table, provided in the format given
+in Appendix B, into an opaque internal representation
+of type
+<function>XtTranslations</function>.
+Note that if an empty translation table is required for any purpose,
+one can be obtained by calling
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
+and passing an empty string.
+</para>
+
+<para>
+To merge additional translations into an existing translation table, use
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAugmentTranslations'>
+<funcprototype>
+<funcdef>void <function>XtAugmentTranslations</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtTranslations <parameter>translations</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>translations</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the compiled translation table to merge in.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
+function merges the new translations into the existing widget
+translations, ignoring any
+<function>#replace</function>,
+<function>#augment</function>,
+or
+<function>#override</function>
+directive that may have been specified
+in the translation string. The translation table specified by
+<emphasis remap='I'>translations</emphasis> is not altered by this process.
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To overwrite existing translations with new translations, use
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOverrideTranslations'>
+<funcprototype>
+<funcdef>void <function>XtOverrideTranslations</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtTranslations <parameter>translations</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>translations</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the compiled translation table to merge in.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
+function merges the new translations into the existing widget
+translations, ignoring any
+<function>#replace</function>,
+<function>#augment</function>,
+or
+<function>#override</function>
+directive that may have been
+specified in the translation string. The translation table
+specified by <emphasis remap='I'>translations</emphasis> is not altered by this process.
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To replace a widget's translations completely, use
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on the XtNtranslations resource and specify a compiled translation table
+as the value.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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 <emphasis remap='I'>translations</emphasis> 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 <emphasis remap='I'>translations</emphasis> 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.
+</para>
+
+<para>
+To completely remove existing translations, use
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUninstallTranslations'>
+<funcprototype>
+<funcdef>void <function>XtUninstallTranslations</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>
+function causes the entire translation table for the widget to be removed.
+</para>
+</sect1>
+
+<sect1 id="Using_Accelerators">
+<title>Using Accelerators</title>
+<para>
+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 Intrinsics provide a facility, called accelerators, that lets you
+accomplish this.
+An accelerator table is a translation table that is bound with its
+actions in the context of a particular widget, the <emphasis remap='I'>source</emphasis> widget.
+The accelerator table can then be installed on one or more <emphasis remap='I'>destination</emphasis> 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.
+</para>
+
+<para>
+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
+<xref linkend='XtStringProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtStringProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtStringProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source widget that supplied the accelerators.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string representation of the accelerators for this widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Accelerators can be specified in resource files,
+and the string representation is the same as for a translation table.
+However,
+the interpretation of the
+<function>#augment</function>
+and
+<function>#override</function>
+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
+<function>#augment</function>,
+which means that the accelerator translations have lower priority
+than the destination translations.
+The
+<function>#replace</function>
+directive is ignored for accelerator tables.
+</para>
+
+<para>
+To parse an accelerator table, use
+<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtParseAcceleratorTable'>
+<funcprototype>
+<funcdef>XtAccelerators <function>XtParseAcceleratorTable</function></funcdef>
+ <paramdef>String <parameter>source</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the accelerator table to compile.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To install accelerators from a widget on another widget, use
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInstallAccelerators'>
+<funcprototype>
+<funcdef>void <function>XtInstallAccelerators</function></funcdef>
+ <paramdef>Widget <parameter>destination</parameter></paramdef>
+ <paramdef>Widget <parameter>source</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destination</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget from which the accelerators are to come. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
+function installs the <emphasis remap='I'>accelerators</emphasis> resource value from
+<emphasis remap='I'>source</emphasis> onto <emphasis remap='I'>destination</emphasis>
+by merging the source accelerators into the destination translations.
+If the source <emphasis remap='I'>display_accelerator</emphasis> field is non-NULL,
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+As a convenience for installing all accelerators from a widget and all its
+descendants onto one destination, use
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInstallAllAccelerators'>
+<funcprototype>
+<funcdef>void <function>XtInstallAllAccelerators</function></funcdef>
+ <paramdef>Widget <parameter>destination</parameter></paramdef>
+ <paramdef>Widget <parameter>source</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destination</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the root widget of the widget tree
+from which the accelerators are to come. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
+function recursively descends the widget tree rooted at <emphasis remap='I'>source</emphasis>
+and installs the accelerators resource value
+of each widget encountered onto <emphasis remap='I'>destination</emphasis>.
+A common use is to call
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
+and pass the application main window as the source.
+</para>
+</sect1>
+
+<sect1 id="KeyCode_to_KeySym_Conversions">
+<title>KeyCode-to-KeySym Conversions</title>
+<para>
+The translation manager provides support for automatically translating
+KeyCodes in incoming key events into KeySyms.
+KeyCode-to-KeySym translator procedure pointers are of type
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtKeyProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtKeyProc)</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display that the KeyCode is from.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode to translate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifiers to the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location in which to store the resulting KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure takes a KeyCode and modifiers and produces a KeySym.
+For any given key translator function and keyboard encoding,
+<emphasis remap='I'>modifiers_return</emphasis> will be a constant per KeyCode that indicates
+the subset of all modifiers that are examined by the key translator
+for that KeyCode.
+</para>
+
+<para>
+The KeyCode-to-KeySym translator procedure
+must be implemented such that multiple calls with the same
+<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keycode</emphasis>, and <emphasis remap='I'>modifiers</emphasis> return the same
+result until either a new case converter, an
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>,
+is installed or a
+<function>MappingNotify</function>
+event is received.
+</para>
+
+<para>
+The Intrinsics 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.
+</para>
+
+<para>
+To return a pointer to the KeySym-to-KeyCode mapping table for a
+particular display, use
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetKeysymTable'>
+<funcprototype>
+<funcdef>KeySym *<function>XtGetKeysymTable</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeyCode *<parameter>min_keycode_return</parameter></paramdef>
+ <paramdef>int *<parameter>keysyms_per_keycode_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display whose table is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_keycode_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the minimum KeyCode valid for the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms_per_keycode_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of KeySyms stored for each KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
+returns a pointer to the Intrinsics' copy of the
+server's KeyCode-to-KeySym table. This table must not be modified.
+There are <emphasis remap='I'>keysyms_per_keycode_return</emphasis> KeySyms associated with each
+KeyCode, located in the table with indices starting at index
+</para>
+<literallayout>
+ (test_keycode - min_keycode_return) * keysyms_per_keycode_return
+</literallayout>
+<para>
+for KeyCode <emphasis remap='I'>test_keycode</emphasis>. Any entries that have no KeySyms associated
+with them contain the value
+<function>NoSymbol</function>.
+Clients should not cache the KeySym table but should call
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
+each time the value is
+needed, as the table may change prior to dispatching each event.
+</para>
+
+<para>
+For more information on this table, see
+<olink targetdoc='libX11' targetptr='Manipulating_the_Keyboard_Encoding'>Section 12.7</olink> in
+<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface.</olink>.
+</para>
+
+<para>
+To register a key translator, use
+<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetKeyTranslator'>
+<funcprototype>
+<funcdef>void <function>XtSetKeyTranslator</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XtKeyProc <parameter>proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display from which to translate the events.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to perform key translations.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>
+function sets the specified procedure as the current key translator.
+The default translator is
+<function>XtTranslateKey</function>,
+an
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>
+that uses the Shift, Lock, numlock, and group modifiers
+with the interpretations defined in <emphasis remap='I'>X Window System Protocol</emphasis>, 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.
+</para>
+
+<para>
+To invoke the currently registered KeyCode-to-KeySym translator,
+use
+<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTranslateKeycode'>
+<funcprototype>
+<funcdef>void <function>XtTranslateKeycode</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display that the KeyCode is from.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode to translate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifiers to the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a mask that indicates the modifiers actually used
+to generate the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the resulting KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
+function passes the specified arguments
+directly to the currently registered KeyCode-to-KeySym translator.
+</para>
+
+<para>
+To handle capitalization of nonstandard KeySyms, the Intrinsics allow
+clients to register case conversion routines.
+Case converter procedure pointers are of type
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCaseProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtCaseProc)</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeySym <parameter>keysym</parameter></paramdef>
+ <paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection for which the conversion is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lower_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location into which to store the lowercase equivalent for
+the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>upper_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location into which to store the uppercase equivalent for
+the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is no case distinction,
+this procedure should store the KeySym into both return values.
+</para>
+
+<para>
+To register a case converter, use
+<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterCaseConverter'>
+<funcprototype>
+<funcdef>void <function>XtRegisterCaseConverter</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XtCaseProc <parameter>proc</parameter></paramdef>
+ <paramdef>KeySym <parameter>start</parameter></paramdef>
+ <paramdef>KeySym <parameter>stop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display from which the key events are to come.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>
+to do the conversions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>start</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeySym for which this converter is valid.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the last KeySym for which this converter is valid.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>
+registers the specified case converter.
+The <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>stop</emphasis> 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 Intrinsics refresh the keyboard state if necessary.
+The default converter understands case conversion for all
+Latin KeySyms defined in <emphasis remap='I'>X Window System Protocol</emphasis>, Appendix A.
+</para>
+
+<para>
+To determine uppercase and lowercase equivalents for a KeySym, use
+<xref linkend='XtConvertCase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertCase'>
+<funcprototype>
+<funcdef>void <function>XtConvertCase</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeySym <parameter>keysym</parameter></paramdef>
+ <paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display that the KeySym came from.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lower_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the lowercase equivalent of the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>upper_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the uppercase equivalent of the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConvertCase' xrefstyle='select: title'/>
+function calls the appropriate converter and returns the results.
+A user-supplied
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>
+may need to use this function.
+</para>
+</sect1>
+
+<sect1 id="Obtaining_a_KeySym_in_an_Action_Procedure">
+<title>Obtaining a KeySym in an Action Procedure</title>
+<para>
+When an action procedure is invoked on a
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+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
+Intrinsics 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.
+</para>
+
+<para>
+To retrieve the KeySym and modifiers that matched the final event
+specification in the translation table entry, use
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetActionKeysym'>
+<funcprototype>
+<funcdef>KeySym <function>XtGetActionKeysym</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event pointer passed to the action procedure by the Intrinsics.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the modifiers that caused the match, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+is called after an action procedure has been
+invoked by the Intrinsics 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
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+event, then
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+returns the KeySym that matched the final
+event specification in the translation table and, if <emphasis remap='I'>modifiers_return</emphasis>
+is non-NULL, the modifier state actually used to generate this KeySym;
+otherwise, if the event is a
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+event, then
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+calls
+<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
+and returns the results;
+else it returns
+<function>NoSymbol</function>
+and does not examine <emphasis remap='I'>modifiers_return</emphasis>.
+</para>
+
+<para>
+Note that if an action procedure invoked by the Intrinsics
+invokes a subsequent action procedure (and so on) via
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
+the nested action procedure may also call
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+to retrieve the Intrinsics' KeySym and modifiers.
+</para>
+</sect1>
+
+<sect1 id="KeySym_to_KeyCode_Conversions">
+<title>KeySym-to-KeyCode Conversions</title>
+<para>
+To return the list of KeyCodes that map to a particular KeySym in
+the keyboard mapping table maintained by the Intrinsics, use
+<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtKeysymToKeycodeList'>
+<funcprototype>
+<funcdef>void <function>XtKeysymToKeycodeList</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeySym <parameter>keysym</parameter></paramdef>
+ <paramdef>KeyCode **<parameter>keycodes_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>keycount_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display whose table is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym for which to search.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycodes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of KeyCodes that have <emphasis remap='I'>keysym</emphasis>
+associated with them, or NULL if <emphasis remap='I'>keycount_return</emphasis> is 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycount_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of KeyCodes in the keycode list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>
+procedure returns all the KeyCodes that have <emphasis remap='I'>keysym</emphasis>
+in their entry for the keyboard mapping table associated with <emphasis remap='I'>display</emphasis>.
+For each entry in the
+table, the first four KeySyms (groups 1 and 2) are interpreted as
+specified by <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5. If no KeyCodes map to the
+specified KeySym, <emphasis remap='I'>keycount_return</emphasis> is zero and *<emphasis remap='I'>keycodes_return</emphasis> is NULL.
+</para>
+
+<para>
+The caller should free the storage pointed to by <emphasis remap='I'>keycodes_return</emphasis> using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer useful. If the caller needs to examine
+the KeyCode-to-KeySym table for a particular KeyCode, it should call
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Registering_Button_and_Key_Grabs_for_Actions">
+<title>Registering Button and Key Grabs for Actions</title>
+<para>
+To register button and key grabs for a widget's window according to the
+event bindings in the widget's translation table, use
+<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterGrabAction'>
+<funcprototype>
+<funcdef>void <function>XtRegisterGrabAction</function></funcdef>
+ <paramdef>XtActionProc <parameter>action_proc</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>action_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action procedure to search for in translation tables.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>
+adds the specified <emphasis remap='I'>action_proc</emphasis> 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
+<function>ButtonPress</function>
+or
+<function>KeyPress</function>
+events as the only or final event
+in a sequence, the Intrinsics will call
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+for the widget with every button or KeyCode which maps to the
+event detail field, passing the specified <emphasis remap='I'>owner_events</emphasis>, <emphasis remap='I'>event_mask</emphasis>,
+<emphasis remap='I'>pointer_mode</emphasis>, and <emphasis remap='I'>keyboard_mode</emphasis>. For
+<function>ButtonPress</function>
+events, the modifiers
+specified in the grab are determined directly from the translation
+specification and <emphasis remap='I'>confine_to</emphasis> and <emphasis remap='I'>cursor</emphasis> are specified as
+<function>None</function>.
+For
+<function>KeyPress</function>
+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
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+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 <emphasis remap='I'>event_mask</emphasis> 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
+<function>ButtonPress</function>
+and
+<function>KeyPress</function>
+events, don't-care modifiers are ignored unless the translation entry
+explicitly specifies ``Any'' in the <emphasis remap='I'>modifiers</emphasis> field.
+</para>
+
+<para>
+If the specified <emphasis remap='I'>action_proc</emphasis> 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.
+</para>
+
+<para>
+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
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Invoking_Actions_Directly">
+<title>Invoking Actions Directly</title>
+<para>
+Normally action procedures are invoked by the Intrinsics when an
+event or event sequence arrives for a widget. To
+invoke an action procedure directly, without generating
+(or synthesizing) events, use
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallActionProc'>
+<funcprototype>
+<funcdef>void <function>XtCallActionProc</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>String <parameter>action</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>action</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the contents of the <emphasis remap='I'>event</emphasis> passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the contents of the <emphasis remap='I'>params</emphasis> passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
+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
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
+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 <emphasis remap='I'>event</emphasis>, <emphasis remap='I'>params</emphasis>, and <emphasis remap='I'>num_params</emphasis> 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,
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
+generates a warning message and returns.
+</para>
+</sect1>
+
+<sect1 id="Obtaining_a_Widget_s_Action_List">
+<title>Obtaining a Widget's Action List</title>
+<para>
+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
+<emphasis remap='I'>actions</emphasis> field, use
+<xref linkend='XtGetActionList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetActionList'>
+<funcprototype>
+<funcdef>void <function>XtGetActionList</function></funcdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>XtActionList *<parameter>actions_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_actions_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class whose actions are to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actions_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the action list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_actions_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of action procedures declared by the class.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetActionList' xrefstyle='select: title'/>
+returns the action table defined by the specified
+widget class. This table does not include actions defined by the
+superclasses. If <emphasis remap='I'>widget_class</emphasis> is not initialized, or is not
+<function>coreWidgetClass</function>
+or a subclass thereof, or if the class does not define any actions,
+*<emphasis remap='I'>actions_return</emphasis> will be NULL and *<emphasis remap='I'>num_actions_return</emphasis>
+will be zero.
+If *<emphasis remap='I'>actions_return</emphasis> is non-NULL the client is responsible for freeing
+the table using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+</sect1>
+</chapter>
diff --git a/specs/CH11.xml b/specs/CH11.xml
new file mode 100644
index 0000000..92e46dc
--- /dev/null
+++ b/specs/CH11.xml
@@ -0,0 +1,5538 @@
+<chapter id='Utility_Functions'>
+<title>Utility Functions</title>
+<para>
+The Intrinsics provide a number of utility functions that you can use to
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Determine the number of elements in an array.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Translate strings to widget instances.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manage memory usage.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Share graphics contexts.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manipulate selections.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Merge exposure events into a region.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Translate widget coordinates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate a widget given a window id.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Handle errors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set the WM_COLORMAP_WINDOWS property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate files by name with string substitutions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Register callback functions for external agents.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate all the displays of an application context.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<sect1 id="Determining_the_Number_of_Elements_in_an_Array">
+<title>Determining the Number of Elements in an Array</title>
+<para>
+To determine the number of elements in a fixed-size array, use
+<xref linkend='XtNumber' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNumber'>
+<funcprototype>
+<funcdef>Cardinal <function>XtNumber</function></funcdef>
+ <paramdef>ArrayType <parameter>array</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>array</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a fixed-size array of arbitrary type.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtNumber' xrefstyle='select: title'/>
+macro returns the number of elements allocated to the array.
+</para>
+</sect1>
+
+<sect1 id="Translating_Strings_to_Widget_Instances">
+<title>Translating Strings to Widget Instances</title>
+<para>
+To translate a widget name to a widget instance, use
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNameToWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtNameToWidget</function></funcdef>
+ <paramdef>Widget <parameter>reference</parameter></paramdef>
+ <paramdef>String <parameter>names</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>reference</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the partially qualified name of the desired widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+function searches for a descendant of the <emphasis remap='I'>reference</emphasis>
+widget whose name matches the specified names. The <emphasis remap='I'>names</emphasis> parameter
+specifies a simple object name or a series of simple object name
+components separated by periods or asterisks.
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+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 :
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Return the first object in the enumeration that matches the
+specified name, where each component of <emphasis remap='I'>names</emphasis> matches exactly the
+corresponding component of the qualified object name and asterisk
+matches any series of components, including none.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no match is found, return NULL.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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 Intrinsics do not require that all
+children of a widget have unique names,
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+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.
+</para>
+</sect1>
+
+<sect1 id="Managing_Memory_Usage">
+<title>Managing Memory Usage</title>
+<para>
+The Intrinsics 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
+<function>malloc</function>,
+<function>calloc</function>,
+<function>realloc</function>,
+and
+<function>free</function>
+with the following added functionality:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+give an error if there is not enough memory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtFree' xrefstyle='select: title'/>
+simply returns if passed a NULL pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+simply allocates new storage if passed a NULL pointer.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+See the standard C library documentation on
+<function>malloc</function>,
+<function>calloc</function>,
+<function>realloc</function>,
+and
+<function>free</function>
+for more information.
+</para>
+
+<para>
+To allocate storage, use
+<xref linkend='XtMalloc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMalloc'>
+<funcprototype>
+<funcdef>char * <function>XtMalloc</function></funcdef>
+ <paramdef>Cardinal <parameter>size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+function returns a pointer to a block of storage of at least
+the specified <emphasis remap='I'>size</emphasis> bytes.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To allocate and initialize an array, use
+<xref linkend='XtCalloc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCalloc'>
+<funcprototype>
+<funcdef>char * <function>XtCalloc</function></funcdef>
+ <paramdef>Cardinal <parameter>num</parameter></paramdef>
+ <paramdef>Cardinal <parameter>size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of array elements to allocate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of each array element in bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCalloc' xrefstyle='select: title'/>
+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,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtCalloc' xrefstyle='select: title'/>
+returns the address of the allocated storage.
+</para>
+
+<para>
+To change the size of an allocated block of storage, use
+<xref linkend='XtRealloc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRealloc'>
+<funcprototype>
+<funcdef>char *<function>XtRealloc</function></funcdef>
+ <paramdef>char *<parameter>ptr</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ptr</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the old storage allocated with
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies number of bytes desired in new storage.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+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,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+If <emphasis remap='I'>ptr</emphasis> is NULL,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+simply calls
+<xref linkend='XtMalloc' xrefstyle='select: title'/>.
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+then returns the address of the new block.
+</para>
+
+<para>
+To free an allocated block of storage, use
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtFree'>
+<funcprototype>
+<funcdef>void <function>XtFree</function></funcdef>
+ <paramdef>char *<parameter>ptr</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ptr</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a block of storage allocated with
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtFree' xrefstyle='select: title'/>
+function returns storage, allowing it to be reused.
+If <emphasis remap='I'>ptr</emphasis> is NULL,
+<xref linkend='XtFree' xrefstyle='select: title'/>
+returns immediately.
+</para>
+
+<para>
+To allocate storage for a new instance of a type, use
+<xref linkend='XtNew' xrefstyle='select: title'/>.
+</para>
+
+
+<funcsynopsis id='XtNew'>
+<funcprototype>
+<funcdef>type <function>XtNew</function></funcdef>
+ <paramdef>type <parameter>t</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a previously declared type.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtNew' xrefstyle='select: title'/>
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtNew' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtNew' xrefstyle='select: title'/>
+is a convenience macro that calls
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+with the following arguments specified:
+</para>
+<literallayout >
+((type *) XtMalloc((unsigned) sizeof(type)))
+</literallayout>
+<para>
+The storage allocated by
+<xref linkend='XtNew' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To copy an instance of a string, use
+<xref linkend='XtNewString' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNewString'>
+<funcprototype>
+<funcdef>String <function>XtNewString</function></funcdef>
+ <paramdef>String <parameter>string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a previously declared string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+is a convenience macro that calls
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+with the following arguments specified:
+</para>
+<literallayout >
+(strcpy(XtMalloc((unsigned)strlen(str) + 1), str))
+</literallayout>
+<para>
+The storage allocated by
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Sharing_Graphics_Contexts">
+<title>Sharing Graphics Contexts</title>
+<para>
+The Intrinsics 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.
+</para>
+
+<para>
+To obtain a shareable GC with modifiable fields, use
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAllocateGC'>
+<funcprototype>
+<funcdef>GC <function>XtAllocateGC</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>Cardinal <parameter>depth</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XGCValues *<parameter>values</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>dynamic_mask</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>unused_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an object, giving the screen for which the
+returned GC is valid. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the depth for which the returned GC is valid, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies fields of the GC that are initialized from <emphasis remap='I'>values</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the values for the initialized fields.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dynamic_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies fields of the GC that will be modified by the caller.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>unused_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies fields of the GC that will not be needed by the caller.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+function returns a shareable GC that may be
+modified by the client. The <emphasis remap='I'>screen</emphasis> field of the specified
+widget or of the nearest widget ancestor of the specified
+object and the specified <emphasis remap='I'>depth</emphasis> argument supply
+the root and drawable depths for which the GC is to be
+valid. If <emphasis remap='I'>depth</emphasis> is zero, the depth is taken from the
+<emphasis remap='I'>depth</emphasis> field of the specified widget or of the nearest
+widget ancestor of the specified object.
+</para>
+
+<para>
+The <emphasis remap='I'>value_mask</emphasis> argument specifies fields of the GC
+that are initialized with the respective member of the
+<emphasis remap='I'>values</emphasis> structure. The <emphasis remap='I'>dynamic_mask</emphasis> 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 <emphasis remap='I'>unused_mask</emphasis> 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 <emphasis remap='I'>unused_mask</emphasis>. The caller may assume
+that at all times all fields not specified in either
+<emphasis remap='I'>dynamic_mask</emphasis> or <emphasis remap='I'>unused_mask</emphasis> have their default value if not
+specified in <emphasis remap='I'>value_mask</emphasis> or the value specified by <emphasis remap='I'>values</emphasis>.
+If a field is specified in both <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>dynamic_mask</emphasis>,
+the effect is as if it were specified only in <emphasis remap='I'>dynamic_mask</emphasis>
+and then immediately set to the value in <emphasis remap='I'>values</emphasis>. If a field
+is set in <emphasis remap='I'>unused_mask</emphasis> and also in either <emphasis remap='I'>value_mask</emphasis> or
+<emphasis remap='I'>dynamic_mask</emphasis>, the specification in <emphasis remap='I'>unused_mask</emphasis> is ignored.
+</para>
+
+<para>
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+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.
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+may modify and return an existing GC if it was allocated with a
+nonzero <emphasis remap='I'>unused_mask</emphasis>.
+</para>
+
+<para>
+To obtain a shareable GC with no modifiable fields, use
+<xref linkend='XtGetGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetGC'>
+<funcprototype>
+<funcdef>GC <function>XtGetGC</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XGCValues *<parameter>values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an object, giving the screen and depth for which the
+returned GC is valid. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which fields of the <emphasis remap='I'>values</emphasis> structure are specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the actual values for this GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetGC' xrefstyle='select: title'/>
+function returns a shareable, read-only GC.
+The parameters to this function are the same as those for
+<function>XCreateGC</function>
+except that an Object is passed instead of a Display.
+<xref linkend='XtGetGC' xrefstyle='select: title'/>
+is equivalent to
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+with <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>dynamic_mask</emphasis>, and <emphasis remap='I'>unused_mask</emphasis> all zero.
+</para>
+
+<para>
+<xref linkend='XtGetGC' xrefstyle='select: title'/>
+shares only GCs in which all values in the GC returned by
+<function>XCreateGC</function>
+are the same.
+In particular, it does not use the <emphasis remap='I'>value_mask</emphasis> provided to
+determine which fields of the GC a widget considers relevant.
+The <emphasis remap='I'>value_mask</emphasis> is used only to tell the server which fields should be
+filled in from <emphasis remap='I'>values</emphasis> and which it should fill in with default values.
+</para>
+
+<para>
+To deallocate a shared GC when it is no longer needed, use
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtReleaseGC'>
+<funcprototype>
+<funcdef>void <function>XtReleaseGC</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>GC <parameter>gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shared GC obtained with either
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+or
+<xref linkend='XtGetGC' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Managing_Selections">
+<title>Managing Selections</title>
+<para>
+Arbitrary widgets in multiple applications can communicate
+with each other by means of the Intrinsics global selection mechanism,
+which conforms to the specifications in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>.
+The Intrinsics supply functions for providing and receiving selection data in
+one logical piece (atomic transfers)
+or in smaller logical segments (incremental transfers).
+</para>
+
+<para>
+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 Intrinsics 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 Intrinsics is not
+required to match the underlying
+transport protocol between the application and the X server;
+the Intrinsics 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.
+</para>
+
+<sect2 id='Setting_and_Getting_the_Selection_Timeout_Value'>
+<title>Setting and Getting the Selection Timeout Value</title>
+<para>
+To set the Intrinsics selection timeout, use
+<xref linkend='XtAppSetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetSelectionTimeout'>
+<funcprototype>
+<funcdef>void <function>XtAppSetSelectionTimeout</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timeout</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection timeout in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To get the current selection timeout value, use
+<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetSelectionTimeout'>
+<funcprototype>
+<funcdef>unsigned long <function>XtAppGetSelectionTimeout</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>
+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
+application resource as retrieved by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+If
+selectionTimeout
+is not specified,
+the default is five seconds.
+</para>
+</sect2>
+
+<sect2 id="Using_Atomic_Transfers">
+<title>Using Atomic Transfers</title>
+<para>
+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.
+</para>
+
+<sect3 id="Atomic_Transfer_Procedures">
+<title>Atomic Transfer Procedures</title>
+<para>
+The following procedures are used by the selection owner when
+providing selection data in a single unit.
+</para>
+
+<para>
+The procedure pointer specified by the owner to supply the selection
+data to the Intrinsics is of type
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertSelectionProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtConvertSelectionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>Atom *<parameter>type_return</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>value_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length_return</parameter></paramdef>
+ <paramdef>int *<parameter>format_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that currently owns this selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection requested
+(for example,
+<function>XA_PRIMARY</function>
+or
+<function>XA_SECONDARY ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+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).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>XA_STRING</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>
+for the selection,
+this storage is owned by the selection owner;
+otherwise, it is owned by the Intrinsics selection mechanism,
+which frees it by calling
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is done with it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the number of elements in <emphasis remap='I'>value_return</emphasis>,
+each of size indicated by <emphasis remap='I'>format_return</emphasis>, is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the size in bits of the data elements
+of the selection value is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism
+to get the value of a selection as a given type
+from the current selection owner.
+It returns
+<function>True</function>
+if the owner successfully converted the selection to the target type or
+<function>False</function>
+otherwise.
+If the procedure returns
+<function>False</function>,
+the values of the return arguments are undefined.
+Each
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+should respond to target value
+<function>TARGETS</function>
+by returning a value containing the list of the targets
+into which it is
+prepared to convert the selection.
+The value returned in
+<emphasis remap='I'>format_return</emphasis> must be one of 8, 16, or 32 to allow the server to
+byte-swap the data if necessary.
+</para>
+
+<para>
+This procedure does not need to worry about responding to the
+MULTIPLE or the TIMESTAMP target values (see
+<xref linkend='Window_Creation_Convenience_Routine' />
+in the <olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>).
+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 Intrinsics using the time specified in the
+call to
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>
+or
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To retrieve the
+<function>SelectionRequest</function>
+event that triggered the
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+procedure, use
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionRequest'>
+<funcprototype>
+<funcdef>XSelectionRequestEvent *<function>XtGetSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>XtRequestId <parameter>request_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection being processed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the requestor id in the case of incremental
+selections, or NULL in the case of atomic transfers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>
+may be called only from within an
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+procedure and returns a pointer to the
+<function>SelectionRequest</function>
+event that caused the conversion procedure to be invoked.
+<emphasis remap='I'>Request_id</emphasis> specifies a unique id for the individual request in the
+case that multiple incremental transfers are outstanding. For atomic
+transfers, <emphasis remap='I'>request_id</emphasis> must be specified as NULL. If no
+<function>SelectionRequest</function>
+event is being processed for the specified
+<emphasis remap='I'>widget</emphasis>, <emphasis remap='I'>selection</emphasis>, and <emphasis remap='I'>request_id</emphasis>,
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>
+returns NULL.
+</para>
+
+<para>
+The procedure pointer specified by the owner when it desires
+notification upon losing ownership is of type
+<xref linkend='XtLoseSelectionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLoseSelectionProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtLoseSelectionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has lost selection ownership.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics 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.
+</para>
+
+<para>
+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
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSelectionDoneProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSelectionDoneProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the converted selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection that was converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type to which the conversion was done.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism
+to inform the selection owner that a selection requestor has successfully
+retrieved a selection value.
+If the selection owner has registered an
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>,
+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
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>,
+it also owns the storage containing the converted
+selection value.
+</para>
+</sect3>
+<sect3 id="Getting_the_Selection_Value">
+<title>Getting the Selection Value</title>
+<para>
+The procedure pointer specified by the requestor to receive the
+selection data from the Intrinsics is of type
+<xref linkend='XtSelectionCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSelectionCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSelectionCallbackPro)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>value</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length</parameter></paramdef>
+ <paramdef>int *<parameter>format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that requested the selection value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a value passed in by the widget when it requested the
+selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the selection that was requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the representation type of the selection value (for example,
+<function>XA_STRING ).</function>
+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
+<function>XT_CONVERT_FAIL</function>
+is used to indicate that the selection conversion failed because the
+selection owner did not respond within the Intrinsics selection timeout
+interval.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the selection value.
+The requesting client owns this storage and is responsible for freeing it
+by calling
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is done with it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements in <emphasis remap='I'>value</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size in bits of the data in each element of <emphasis remap='I'>value</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism to deliver the
+requested selection to the requestor.
+</para>
+
+<para>
+If the
+<function>SelectionNotify</function>
+event returns a property of
+<function>None</function>,
+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.
+</para>
+
+<para>
+To obtain the selection value in a single logical unit, use
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+or
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionValue'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValue</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>target</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired; for example,
+<function>XA_PRIMARY</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of information needed about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+function requests the value of the selection converted to
+the target type.
+The specified callback is called at some time after
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+is called, when the selection value is received from the X server.
+It may be called before or after
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+returns.
+For more information about <emphasis remap='I'>selection</emphasis>,
+<emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>.
+</para>
+
+<funcsynopsis id='XtGetSelectionValues'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValues</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>targets</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired (that is, primary or secondary).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>targets</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the types of information needed about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>
+function is similar to multiple calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+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 <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>section 2.6</olink>
+in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>.
+</para>
+</sect3>
+<sect3 id="Setting_the_Selection_Owner">
+<title>Setting the Selection Owner</title>
+<para>
+To set the selection owner and indicate that the selection value will
+be provided in one piece, use
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOwnSelection'>
+<funcprototype>
+<funcdef>Boolean <function>XtOwnSelection</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+ <paramdef>XtConvertSelectionProc <parameter>convert_proc</parameter></paramdef>
+ <paramdef>XtLoseSelectionProc <parameter>lose_selection</parameter></paramdef>
+ <paramdef>XtSelectionDoneProc <parameter>done_proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the selection (for example,
+<function>XA_PRIMARY ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the ownership request was
+initiated.
+This should be the timestamp of the event that triggered ownership;
+the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever a client requests the
+current value of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lose_selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>done_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure called
+after the requestor has received the selection value, or NULL if the
+owner is not
+interested in being called back.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>
+function informs the Intrinsics selection mechanism that a
+widget wishes to own a selection.
+It returns
+<function>True</function>
+if the widget successfully becomes the owner and
+<function>False</function>
+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.
+</para>
+
+<para>
+If a done_proc is specified, the client owns the storage allocated
+for passing the value to the Intrinsics. If <emphasis remap='I'>done_proc</emphasis> is NULL,
+the convert_proc must allocate storage using
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and the value specified is freed by the
+Intrinsics when the transfer is complete.
+</para>
+
+<para>
+Usually, a selection owner maintains ownership indefinitely until some
+other widget requests ownership, at which time
+the Intrinsics 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 Intrinsics
+by using
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+that it no longer is to be the selection owner.
+</para>
+
+<funcsynopsis id='XtDisownSelection'>
+<funcprototype>
+<funcdef>void <function>XtDisownSelection</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that wishes to relinquish ownership.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection being given up.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the request to
+relinquish selection ownership was initiated.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+function informs the Intrinsics 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,
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+does nothing.
+</para>
+
+<para>
+After a widget has called
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>,
+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
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+finishes after the call to
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Using_Incremental_Transfers">
+<title>Using Incremental Transfers</title>
+<para>
+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
+<emphasis remap='I'>request_id</emphasis> argument, which is an identifier that is guaranteed to be
+unique among all incremental requests that are active concurrently.
+</para>
+
+<para>
+For example, consider the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Upon receiving a request for the selection value, the owner sends
+the first segment.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+<sect3 id="Incremental_Transfer_Procedures">
+<title>Incremental Transfer Procedures</title>
+<para>
+The following procedures are used by selection owners who wish to
+provide the selection data in multiple segments.
+</para>
+
+<para>
+The procedure pointer specified by the incremental owner to supply the
+selection data to the Intrinsics is of type
+<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/>.
+</para>
+<literallayout >
+typedef XtPointer XtRequestId;
+</literallayout>
+
+<funcsynopsis id='XtConvertSelectionIncrProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtConvertSelectionIncrProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>Atom *<parameter>type_return</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>value_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length_return</parameter></paramdef>
+ <paramdef>int *<parameter>format_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>max_length</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that currently owns this selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of information required about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to an atom into which the property
+type of the converted value of the selection is to be
+stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the number of elements
+in <emphasis remap='I'>value_return</emphasis>, each of size indicated by
+<emphasis remap='I'>format_return</emphasis>, is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the maximum number of bytes which may be
+transferred at any one time.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an opaque identification for a specific request.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called repeatedly by the Intrinsics selection mechanism to get
+the next incremental chunk of data from a selection owner who has
+called
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>.
+It must return
+<function>True</function>
+if the procedure has succeeded in converting the selection data or
+<function>False</function>
+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 Intrinsics;
+that is, a fixed transfer area may be allocated and returned in <emphasis remap='I'>value_return</emphasis>
+for each segment to be transferred. This procedure should store a
+non-NULL value in <emphasis remap='I'>value_return</emphasis> and zero in <emphasis remap='I'>length_return</emphasis> to indicate that the
+entire selection has been delivered. After returning this final
+segment, the request id may be reused by the Intrinsics to begin a
+new transfer.
+</para>
+
+<para>
+To retrieve the
+<function>SelectionRequest</function>
+event that triggered the selection conversion procedure, use
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>,
+described in Section 11.5.2.1.
+</para>
+
+<para>
+The procedure pointer specified by the incremental selection owner
+when it desires notification upon no longer having ownership is of
+type
+<xref linkend='XtLoseSelectionIncrProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLoseSelectionIncrProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtLoseSelectionIncrProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has lost the selection ownership.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure, which is optional, is called by the Intrinsics to
+inform the selection owner that it no longer owns the selection.
+</para>
+
+<para>
+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
+<xref linkend='XtSelectionDoneIncrProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSelectionDoneIncrProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSelectionDoneIncrProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection being transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type to which the conversion was done.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an opaque identification for a specific request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specified the value passed in by the widget when it
+took ownership of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure, which is optional, is called by the Intrinsics 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 Intrinsics will free only the
+final value returned by the selection owner using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The procedure pointer specified by the incremental selection owner to
+notify it if a transfer should be terminated prematurely is of type
+<xref linkend='XtCancelConvertSelectionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCancelConvertSelectionProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtCancelConvertSelectionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection being transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type to which the conversion was done.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an opaque identification for a specific request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value passed in by the widget when it took ownership of
+the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics 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.
+</para>
+</sect3>
+<sect3 id="Getting_the_Selection_Value_Incrementally">
+<title>Getting the Selection Value Incrementally</title>
+<para>
+To obtain the value of the selection using incremental transfers, use
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+or
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionValueIncremental'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValueIncremental</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>target</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of information needed
+about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure to be
+called to receive each data segment.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client-specific data to be passed to
+the specified callback procedure when it is invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+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
+<emphasis remap='I'>selection_callback</emphasis> 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
+<function>XT_CONVERT_FAIL</function>
+so that the requestor can dispose
+of the partial selection value it has collected up until that point.
+Upon receiving
+<function>XT_CONVERT_FAIL</function>,
+the requesting client must determine
+for itself whether or not a partially completed data transfer is meaningful.
+For more information about <emphasis remap='I'>selection</emphasis>,
+<emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms' /> in the
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>
+</para>
+
+<funcsynopsis id='XtGetSelectionValuesIncremental'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValuesIncremental</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>targets</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>targets</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the types of information needed about
+the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure to be called
+to receive each selection value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+except that it takes a list of targets and client data.
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+is equivalent to calling
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+successively for each <emphasis remap='I'>target/client_data</emphasis> pair except that
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+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
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+repeatedly.
+For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>
+</para>
+</sect3>
+<sect3 id="Setting_the_Selection_Owner_for_Incremental_Transfers">
+<title>Setting the Selection Owner for Incremental Transfers</title>
+<para>
+To set the selection owner when using incremental transfers, use
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOwnSelectionIncremental'>
+<funcprototype>
+<funcdef>Boolean <function>XtOwnSelectionIncremental</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+ <paramdef>XtConvertSelectionIncrProc <parameter>convert_callback</parameter></paramdef>
+ <paramdef>XtLoseSelectionIncrProc <parameter>lose_callback</parameter></paramdef>
+ <paramdef>XtSelectionDoneIncrProc <parameter>done_callback</parameter></paramdef>
+ <paramdef>XtCancelConvertSelectionProc <parameter>cancel_callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever
+the current value of the selection is requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lose_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever
+the widget has lost selection ownership, or NULL if the
+owner is not interested in being notified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>done_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure called after the
+requestor has received the entire selection, or NULL if
+the owner is not interested in being notified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cancel_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument to be passed to each of
+the callback procedures when they are called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>
+procedure informs the Intrinsics
+incremental selection mechanism that the specified widget wishes to
+own the selection. It returns
+<function>True</function>
+if the specified widget successfully becomes the selection owner or
+<function>False</function>
+otherwise.
+For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the
+<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>
+</para>
+
+<para>
+If a done_callback procedure is specified, the client owns the storage allocated
+for passing the value to the Intrinsics. If <emphasis remap='I'>done_callback</emphasis> is NULL,
+the convert_callback procedure must allocate storage using
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and the final value specified is freed by the
+Intrinsics 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.
+</para>
+
+<para>
+The lose_callback procedure does not indicate completion of any in-progress
+transfers; it is invoked at the time a
+<function>SelectionClear</function>
+event is dispatched regardless of any active transfers, which are still
+expected to continue.
+</para>
+
+<para>
+A widget that becomes the selection owner using
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>
+may use
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+to relinquish selection ownership.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Setting_and_Retrieving_Selection_Target_Parameters">
+<title>Setting and Retrieving Selection Target Parameters</title>
+<para>
+To specify target parameters for a selection request with a single target,
+use
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetSelectionParameters'>
+<funcprototype>
+<funcdef>void <function>XtSetSelectionParameters</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>value</parameter></paramdef>
+ <paramdef>unsigned long <parameter>length</parameter></paramdef>
+ <paramdef>int <parameter>format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the property in which the parameters are passed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements containing data in <emphasis remap='I'>value</emphasis>,
+each element of a size indicated by <emphasis remap='I'>format</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size in bits of the data in the elements of <emphasis remap='I'>value</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+or to
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+specifying the same requestor widget and selection atom will generate a
+<function>ConvertSelection</function>
+request referring to the property containing the parameters. If
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+The possible values of <emphasis remap='I'>format</emphasis> are 8, 16, or 32. If the format is 8,
+the elements of <emphasis remap='I'>value</emphasis> are assumed to be sizeof(char);
+if 16, sizeof(short); if 32, sizeof(long).
+</para>
+
+<para>
+To generate a MULTIPLE
+target request with parameters for any of the multiple targets of the
+selection request, precede individual calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+and
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+with corresponding individual calls to
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>,
+and enclose these all within
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+and
+<function>XtSendSelectionRequest.</function>
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>
+and
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+cannot be used to make selection requests with parameterized targets.
+</para>
+
+<para>
+To retrieve any target parameters needed to perform a selection conversion,
+the selection owner calls
+<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionParameters'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionParameters</function></funcdef>
+ <paramdef>Widget <parameter>owner</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>XtRequestId <parameter>request_id</parameter></paramdef>
+ <paramdef>Atom *<parameter>type_return</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>value_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length_return</parameter></paramdef>
+ <paramdef>int *<parameter>format_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the specified selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection being processed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the requestor id in the case of incremental selections,
+or NULL in the case of atomic transfers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to an atom in which the property type
+of the parameters is stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which a pointer to the parameters is to be stored.
+A NULL is stored if no parameters accompany the request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the number of data elements
+in <emphasis remap='I'>value_return</emphasis> of size indicated by <emphasis remap='I'>format_return</emphasis> are stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the size in bits of the parameter data
+in the elements of <emphasis remap='I'>value</emphasis> is stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>
+may be called only from within an
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+or from within the first call to an
+<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/>
+with a new request_id.
+</para>
+
+<para>
+It is the responsibility of the caller to free the returned parameters using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when the parameters are no longer needed.
+</para>
+</sect2>
+
+<sect2 id="Generating_MULTIPLE_Requests">
+<title>Generating MULTIPLE Requests</title>
+<para>
+To have the Intrinsics bundle multiple calls to make selection requests into
+a single request using a <emphasis role='strong'>MULTIPLE</emphasis> target, use
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+and
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateSelectionRequest'>
+<funcprototype>
+<funcdef>void <function>XtCreateSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+is called, subsequent calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>,
+with the requestor and selection as specified to
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>,
+are bundled into a single selection request with
+multiple targets. The request is made by calling
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSendSelectionRequest'>
+<funcprototype>
+<funcdef>void <function>XtSendSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the selection request was
+initiated. The value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+is called with a value of <emphasis remap='I'>requestor</emphasis> and <emphasis remap='I'>selection</emphasis> matching
+a previous call to
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>,
+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
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+are invoked.
+</para>
+
+<para>
+Multi-threaded applications should lock the application context before
+calling
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+and release the lock after calling
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To relinquish the composition of a MULTIPLE request without sending it, use
+<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCancelSelectionRequest'>
+<funcprototype>
+<funcdef>void <function>XtCancelSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When
+<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>
+is called, any requests queued since the last call to
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+for the same widget and selection are discarded
+and any resources reserved are released.
+A subsequent call to
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+will not result in any request being made.
+Subsequent calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+or
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+will not be deferred.
+</para>
+</sect2>
+
+<sect2 id="Auxiliary_Selection_Properties">
+<title>Auxiliary Selection Properties</title>
+<para>
+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 Intrinsics provides two interfaces for acquiring temporary property names.
+</para>
+
+<para>
+To acquire a temporary property name atom for use in a selection
+request, the client may call
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtReservePropertyAtom'>
+<funcprototype>
+<funcdef>Atom <function>XtReservePropertyAtom</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making a selection request.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+To return a temporary property name atom for reuse and to delete
+the property named by that atom, use
+<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtReleasePropertyAtom'>
+<funcprototype>
+<funcdef>void <function>XtReleasePropertyAtom</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>atom</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget used to reserve the property name atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atom</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name atom returned by
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+that is to be released for reuse.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>
+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 <emphasis remap='I'>atom</emphasis> does not
+specify a value returned by
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+for the specified widget, the results are undefined.
+</para>
+</sect2>
+
+<sect2 id="Retrieving_the_Most_Recent_Timestamp">
+<title>Retrieving the Most Recent Timestamp</title>
+<para>
+To retrieve the timestamp from the most recent call to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+that contained a timestamp, use
+<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLastTimestampProcessed'>
+<funcprototype>
+<funcdef>Time <function>XtLastTimestampProcessed</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an open display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If no
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+<function>MotionNotify</function>,
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+<function>PropertyNotify</function>,
+or
+<function>SelectionClear</function>
+event has yet been passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for the specified display,
+<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/>
+returns zero.
+</para>
+</sect2>
+
+<sect2 id="Retrieving_the_Most_Recent_Event">
+<title>Retrieving the Most Recent Event</title>
+<para>
+To retrieve the event from the most recent call to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for a specific display, use
+<xref linkend='XtLastEventProcessed' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLastEventProcessed'>
+<funcprototype>
+<funcdef>XEvent *<function>XtLastEventProcessed</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection from which to retrieve the event.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Returns the last event passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for the specified display. Returns NULL if there is no such event.
+The client must not modify the contents of the returned event.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Merging_Exposure_Events_into_a_Region">
+<title>Merging Exposure Events into a Region</title>
+<para>
+The Intrinsics provide an
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>
+utility function that merges
+<function>Expose</function>
+and
+<function>GraphicsExpose</function>
+events into a region for clients to process at once
+rather than processing individual rectangles.
+For further information about regions,
+see <olink targetdoc='libX11' targetptr='Manipulating_Regions' />
+in <olink targetdoc='libX11' targetptr='libX11'>
+Xlib — C Language X Interface.</olink>.
+</para>
+
+<para>
+To merge
+<function>Expose</function>
+and
+<function>GraphicsExpose</function>
+events into a region, use
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddExposureToRegion'>
+<funcprototype>
+<funcdef>void <function>XtAddExposureToRegion</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Region <parameter>region</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the
+<function>Expose</function>
+or
+<function>GraphicsExpose</function>
+event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>region</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region object (as defined in
+<function>&lt;X11/Xutil.h&gt;</function>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>
+function computes the union of the rectangle defined by the exposure
+event and the specified region.
+Then it stores the results back in <emphasis remap='I'>region</emphasis>.
+If the event argument is not an
+<function>Expose</function>
+or
+<function>GraphicsExpose</function>
+event,
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>
+returns without an error and without modifying <emphasis remap='I'>region</emphasis>.
+</para>
+
+<para>
+This function is used by the exposure compression mechanism;
+see <xref linkend='Exposure_Compression' />
+</para>
+</sect1>
+
+<sect1 id="Translating_Widget_Coordinates">
+<title>Translating Widget Coordinates</title>
+<para>
+To translate an x-y coordinate pair from widget coordinates to root
+window absolute coordinates, use
+<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTranslateCoords'>
+<funcprototype>
+<funcdef>void <function>XtTranslateCoords</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Position <parameter>x</parameter></paramdef>
+ <paramdef>Position *<parameter>rootx_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the widget-relative x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rootx_return</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rooty_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the root-relative x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+While
+<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>
+is similar to the Xlib
+<function>XTranslateCoordinates</function>
+function, it does not generate a server request because all the required
+information already is in the widget's data structures.
+</para>
+</sect1>
+
+<sect1 id="Translating_a_Window_to_a_Widget">
+<title>Translating a Window to a Widget</title>
+<para>
+To translate a given window and display pointer into a widget instance, use
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWindowToWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtWindowToWidget</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display on which the window is defined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable for which you want the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is a realized widget whose window is the specified drawable on
+the specified <emphasis remap='I'>display</emphasis>,
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+returns that widget.
+If not and if the drawable has been associated with a widget through
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>,
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+returns the widget associated with the drawable. In other cases it
+returns NULL.
+</para>
+</sect1>
+
+<sect1 id="Handling_Errors">
+<title>Handling Errors</title>
+<para>
+The Intrinsics 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.
+</para>
+
+<para>
+Two levels of interface are provided:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A high-level interface that takes an error
+name and class and retrieves the error message text from
+an error resource database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A low-level interface that takes a simple string to display.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+<note>
+<para>
+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.
+</para>
+</note>
+
+<para>
+To obtain the error database (for example, to merge with
+an application- or widget-specific database), use
+<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetErrorDatabase'>
+<funcprototype> <funcdef>XrmDatabase *<function>XtAppGetErrorDatabase</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>
+function returns the address of the error database.
+The Intrinsics do a lazy binding of the error database and do not merge in the
+database file until the first call to
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>.
+</para>
+
+<para>
+For a complete listing of all errors and warnings
+that can be generated by the Intrinsics, see <xref linkend='Intrinsics_Error_Messages' />
+</para>
+
+<para>
+The high-level error and warning handler procedure pointers are of type
+<xref linkend='XtErrorMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtErrorMsgHandler'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtErrorMsgHandler)</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>String <parameter>defaultp</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name to be concatenated with the specified type to form
+the resource name of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type to be concatenated with the name to form the
+resource name of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>defaultp</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if no error database entry is found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of parameters to be substituted in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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
+<function>printf</function>
+notation is used to substitute the parameters into the message.
+</para>
+
+<para>
+An error message handler can obtain the error database text for an
+error or a warning by calling
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetErrorDatabaseText'>
+<funcprototype>
+<funcdef>void <function>XtAppGetErrorDatabaseText</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>default</parameter></paramdef>
+ <paramdef>String <parameter>buffer_return</parameter></paramdef>
+ <paramdef>int <parameter>nbytes</parameter></paramdef>
+ <paramdef>XrmDatabase <parameter>database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the name and type concatenated to form the resource name
+of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer into which the error message is to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer in bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the alternative database to be used,
+or NULL if the application context's error database is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>
+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 <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>type</emphasis> are concatenated with a single "."
+between them and the <emphasis remap='I'>class</emphasis> is concatenated with itself with a
+single "." if it does not already contain a ".".
+</para>
+
+<para>
+To return the application name and class as passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for a particular Display, use
+<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetApplicationNameAndClass'>
+<funcprototype>
+<funcdef>void <function>XtGetApplicationNameAndClass</function></funcdef>
+ <paramdef>Display* <parameter>display</parameter></paramdef>
+ <paramdef>String* <parameter>name_return</parameter></paramdef>
+ <paramdef>String* <parameter>class_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an open display connection that has been initialized with
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application class.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>
+returns the application name and class passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+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 Intrinsics and must not be modified
+or freed by the caller.
+</para>
+
+<para>
+To register a procedure to be called on fatal error conditions, use
+<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetErrorMsgHandler'>
+<funcprototype>
+<funcdef>XtErrorMsgHandler <function>XtAppSetErrorMsgHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>msg_handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new fatal error procedure, which should not return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>
+returns a pointer to the previously
+installed high-level fatal error handler.
+The default high-level fatal error handler provided by the Intrinsics is named
+<function>_XtDefaultErrorMsg</function>
+and constructs a string from the error resource database and calls
+<xref linkend='XtError' xrefstyle='select: title'/>.
+Fatal error message handlers should not return.
+If one does,
+subsequent Intrinsics behavior is undefined.
+</para>
+
+<para>
+To call the high-level error handler, use
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppErrorMsg'>
+<funcprototype>
+<funcdef>void <function>XtAppErrorMsg</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>String <parameter>default</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the general kind of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the detailed name of the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of values to be stored in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The Intrinsics internal errors all have class
+"XtToolkitError".
+</para>
+
+<para>
+To register a procedure to be called on nonfatal error conditions, use
+<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetWarningMsgHandler'>
+<funcprototype>
+<funcdef>XtErrorMsgHandler <function>XtAppSetWarningMsgHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>msg_handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new nonfatal error procedure, which usually returns.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>
+returns a pointer to the previously
+installed high-level warning handler.
+The default high-level warning handler provided by the Intrinsics is named
+<function>_XtDefaultWarningMsg</function>
+and constructs a string
+from the error resource database and calls
+<xref linkend='XtWarning' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To call the installed high-level warning handler, use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppWarningMsg'>
+<funcprototype>
+<funcdef>void <function>XtAppWarningMsg</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>String <parameter>default</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the general kind of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the detailed name of the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of values to be stored in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The Intrinsics internal warnings all have class
+"XtToolkitError".
+</para>
+
+<para>
+The low-level error and warning handler procedure pointers are of type
+<xref linkend='XtErrorHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtErrorHandler'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtErrorHandler)</function></funcdef>
+ <paramdef>String <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The error handler should display the message string in some appropriate fashion.
+</para>
+
+<para>
+To register a procedure to be called on fatal error conditions, use
+<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetErrorHandler'>
+<funcprototype>
+<funcdef>XtErrorHandler <function>XtAppSetErrorHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new fatal error procedure, which should not return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>
+returns a pointer to the previously installed
+low-level fatal error handler.
+The default low-level error handler provided by the Intrinsics is
+<function>_XtDefaultError</function>.
+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 Intrinsics behavior is undefined.
+</para>
+
+<para>
+To call the installed fatal error procedure, use
+<xref linkend='XtAppError' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppError'>
+<funcprototype>
+<funcdef>void <function>XtAppError</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the message to be reported.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most programs should use
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>,
+not
+<xref linkend='XtAppError' xrefstyle='select: title'/>,
+to provide for customization and internationalization of error messages.
+</para>
+
+<para>
+To register a procedure to be called on nonfatal error conditions, use
+<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetWarningHandler'>
+<funcprototype>
+<funcdef>XtErrorHandler <function>XtAppSetWarningHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new nonfatal error procedure, which usually returns.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>
+returns a pointer to the previously installed
+low-level warning handler.
+The default low-level warning handler provided by the Intrinsics is
+<function>_XtDefaultWarning</function>.
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+</para>
+
+<para>
+To call the installed nonfatal error procedure, use
+<xref linkend='XtAppWarning' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppWarning'>
+<funcprototype>
+<funcdef>void <function>XtAppWarning</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the nonfatal error message to be reported.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most programs should use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>,
+not
+<xref linkend='XtAppWarning' xrefstyle='select: title'/>,
+to provide for customization and internationalization of warning messages.
+</para>
+</sect1>
+
+<sect1 id="Setting_WM_COLORMAP_WINDOWS">
+<title>Setting WM_COLORMAP_WINDOWS</title>
+<para>
+A client may set the value of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis>
+property on a widget's window by calling
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetWMColormapWindows'>
+<funcprototype>
+<funcdef>void <function>XtSetWMColormapWindows</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Widget* <parameter>list</parameter></paramdef>
+ <paramdef>Cardinal <parameter>count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget on whose window the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis>
+property is stored. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of widgets whose windows are potentially to be
+listed in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of widgets in <emphasis remap='I'>list</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+returns immediately if <emphasis remap='I'>widget</emphasis> is not realized or if <emphasis remap='I'>count</emphasis> is 0.
+Otherwise,
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+constructs an ordered list of windows
+by examining each widget in <emphasis remap='I'>list</emphasis> 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.
+</para>
+
+<para>
+Finally,
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+stores the resulting window list in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis>
+property on the specified widget's window.
+Refer to Section 4.1.8 in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis> for details of
+the semantics of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property.
+</para>
+</sect1>
+<!-- FIXME: -->
+<sect1 id="Finding_File_Names">
+<title>Finding File Names</title>
+<para>
+The Intrinsics provide procedures to look for a file by name, allowing
+string substitutions in a list of file specifications. Two
+routines are provided for this:
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+and
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+uses an arbitrary set of client-specified substitutions, and
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+uses a set of standard substitutions corresponding
+to the <emphasis remap='I'>X/Open Portability Guide</emphasis> language localization conventions.
+Most applications should use
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+</para>
+
+<para>
+A string substitution is defined by a list of
+<function>Substitution</function>
+entries.
+</para>
+<literallayout >
+typedef struct {
+ char match;
+ String substitution;
+} SubstitutionRec, *Substitution;
+</literallayout>
+<para>
+File name evaluation is handled in an operating-system-dependent
+fashion by an
+<xref linkend='XtFilePredicate' xrefstyle='select: title'/>
+procedure.
+</para>
+
+<funcsynopsis id='XtFilePredicate'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtFilePredicate)</function></funcdef>
+ <paramdef>String <parameter>filename</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a potential filename.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+A file predicate procedure is called with a string that is
+potentially a file name. It should return
+<function>True</function>
+if this string specifies a file that is appropriate for the intended use and
+<function>False</function>
+otherwise.
+</para>
+
+<para>
+To search for a file using substitutions in a path list, use
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtFindFile'>
+<funcprototype>
+<funcdef>String <function>XtFindFile</function></funcdef>
+ <paramdef>String <parameter>path</parameter></paramdef>
+ <paramdef>Substitution <parameter>substitutions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef>
+ <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>path</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a path of file names, including substitution characters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of substitutions to make into the path.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of substitutions passed in.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a procedure called to judge each potential file name, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>path</emphasis> 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,
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+looks through the
+specified <emphasis remap='I'>substitutions</emphasis> for that character in the <emphasis remap='I'>match</emphasis> field
+and, if found,
+replaces the percent and match characters with the string in the
+corresponding <emphasis remap='I'>substitution</emphasis> field. A <emphasis remap='I'>substitution</emphasis> 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,
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+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
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+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
+<function>True</function>;
+this string is the return value for
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+If no string yields a
+<function>True</function>
+return from the predicate,
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+returns NULL.
+</para>
+
+<para>
+If the <emphasis remap='I'>predicate</emphasis> parameter is NULL, an internal procedure that checks
+if the file exists, is readable, and is not a directory is used.
+</para>
+
+<para>
+It is the responsibility of the caller to free the returned string using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+<para>
+To search for a file using standard substitutions in a path list, use
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResolvePathname'>
+<funcprototype>
+<funcdef>String <function>XtResolvePathname</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>Substitution <parameter>substitutions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef>
+ <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display to use to find the language for language substitutions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>suffix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify values to substitute into the path.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>path</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of file specifications, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of additional substitutions to make into the path, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>substitutions</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a procedure called to judge each potential file name, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The substitutions specified by
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+are determined from the value of the language string retrieved by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for the specified display.
+To set the
+language for all applications specify "*xnlLanguage: <emphasis remap='I'>lang</emphasis>" in the
+resource database.
+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 Intrinsics make no interpretation of the parts other
+than to use them in substitutions as described below.
+</para>
+
+
+<para>
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+calls
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+with the following substitutions
+in addition to any passed by the caller and returns the value returned by
+<xref linkend='XtFindFile' xrefstyle='select: title'/>:
+</para>
+<!-- PROBLEM BELOW HERE -->
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+%N
+ </term>
+ <listitem>
+ <para>
+The value of the <emphasis remap='I'>filename</emphasis> parameter, or the application's
+class name if <emphasis remap='I'>filename</emphasis> is NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%T
+ </term>
+ <listitem>
+ <para>
+The value of the <emphasis remap='I'>type</emphasis> parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%S
+ </term>
+ <listitem>
+ <para>
+The value of the <emphasis remap='I'>suffix</emphasis> parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%L
+ </term>
+ <listitem>
+ <para>
+The language string associated with the specified display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%l
+ </term>
+ <listitem>
+ <para>
+The language part of the display's language string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%t
+ </term>
+ <listitem>
+ <para>
+The territory part of the display's language string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%c
+ </term>
+ <listitem>
+ <para>
+The codeset part of the display's language string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%C
+ </term>
+ <listitem>
+ <para>
+The customization string retrieved from the resource
+database associated with <emphasis remap='I'>display</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%D
+ </term>
+ <listitem>
+ <para>
+The value of the implementation-specific default path.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<!-- PROBLEM ABOVE HERE -->
+<para>
+If a path is passed to
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>,
+it is passed along to
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+If the <emphasis remap='I'>path</emphasis> argument is NULL, the value of the
+<emphasis role='strong'>XFILESEARCHPATH</emphasis>
+environment variable is passed to
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+If <emphasis role='strong'>XFILESEARCHPATH</emphasis>
+is not defined, an implementation-specific default path is used
+that contains at least six entries. These entries
+must contain the following substitutions:
+</para>
+
+
+<!-- OK PAST HERE -->
+
+<literallayout>
+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
+</literallayout>
+
+<para>
+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, <function>%N%S</function> is inserted between them.
+</para>
+
+<para>
+The <emphasis remap='I'>type</emphasis> 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".
+</para>
+
+<para>
+The <emphasis remap='I'>suffix</emphasis> parameter is intended to be appended to the file name.
+Possible values might include ".txt", ".dat", and ".bm".
+</para>
+
+<para>
+A suggested value for the default path on POSIX-based systems is
+</para>
+<literallayout>
+ /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\
+ /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\
+ /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
+</literallayout>
+
+
+<para>
+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 <emphasis remap='I'>type</emphasis>
+parameter is used as a subdirectory of the language directory or of
+/usr/lib/X11, and <emphasis remap='I'>suffix</emphasis> is appended to the file name.
+</para>
+
+<para>
+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
+<emphasis role='strong'>XFILESEARCHPATH</emphasis>
+to
+</para>
+<literallayout>
+ %D:ourdir/%T/%N%C:ourdir/%T/%N
+</literallayout>
+
+<para>
+The customization string is obtained by querying the resource database
+currently associated with the display (the database returned by
+<function>XrmGetDatabase</function>)
+for the resource <emphasis remap='I'>application_name</emphasis>.customization, class
+<emphasis remap='I'>application_class</emphasis>.Customization, where <emphasis remap='I'>application_name</emphasis>
+and <emphasis remap='I'>application_class</emphasis> are the values returned by
+<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>.
+If no value is specified in the database, the empty string is used.
+</para>
+
+<para>
+It is the responsibility of the caller to free the returned string using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+
+</sect1>
+<!-- END OF FIXME -->
+<sect1 id="Hooks_for_External_Agents">
+<title>Hooks for External Agents</title>
+<para>
+Applications may register
+functions that are called at a particular control points in the Intrinsics.
+These functions are intended to be used to provide notification
+of an "X Toolkit event", 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 "hook registration" object.
+</para>
+
+<para>
+To retrieve the hook registration widget, use
+<xref linkend='XtHooksOfDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtHooksOfDisplay'>
+<funcprototype>
+<funcdef>Widget <function>XtHooksOfDisplay</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the desired display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The class of this object is a private, implementation-dependent
+subclass of
+<function>Object</function>.
+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.
+</para>
+
+<para>
+The following procedures can be called with the hook registration object
+as an argument:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtClass' xrefstyle='select: title'/>,
+<function>XtSuperclass</function>,
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>,
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
+<function>XtIsObject</function>,
+<function>XtIsRectObj</function>,
+<function>XtIsWidget</function>,
+<function>XtIsComposite</function>,
+<function>XtIsConstraint</function>,
+<function>XtIsShell</function>,
+<function>XtIsOverrideShell</function>,
+<function>XtIsWMShell</function>,
+<function>XtIsVendorShell</function>,
+<function>XtIsTransientShell</function>,
+<function>XtIsToplevelShell</function>,
+<function>XtIsApplicationShell</function>,
+<function>XtIsSessionShell</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtName' xrefstyle='select: title'/>,
+<function>XtParent</function>,
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+
+<sect2 id="Hook_Object_Resources">
+<title>Hook Object Resources</title>
+<para>
+The resource names, classes, and representation types that are specified
+in the hook object resource list are:
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNcreateHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNchangeHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNconfigureHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNgeometryHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNdestroyHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNshells</entry>
+ <entry>XtCReadOnly</entry>
+ <entry>XtRWidgetList</entry>
+ </row>
+ <row>
+ <entry>XtNnumShells</entry>
+ <entry>XtCReadOnly</entry>
+ <entry>XtRCardinal</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+
+<para>
+Descriptions of each of these resources:
+</para>
+
+<para>
+The XtNcreateHook callback list is called from:
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+and their corresponding varargs versions.
+</para>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter in a createHook callback may be
+cast to type
+<function>XtCreateHookData</function>.
+</para>
+<literallayout >
+typedef struct {
+ String type;
+ Widget widget;
+ ArgList args;
+ Cardinal num_args;
+} XtCreateHookDataRec, *XtCreateHookData;
+</literallayout>
+<para>
+The <emphasis remap='I'>type</emphasis> is set to
+<function>XtHcreate</function>,
+<emphasis remap='I'>widget</emphasis> is the newly created widget, and <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
+are the arguments passed to the create function. The callbacks are
+called before returning from the create function.
+</para>
+
+<para>
+The XtNchangeHook callback list is called from:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtManageChild' xrefstyle='select: title'/>,
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+<function>XtAddCallbacks,</function>
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>,
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>,
+<xref linkend='XtPopdown' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter in a changeHook callback may
+be cast to type
+<function>XtChangeHookData</function>.
+</para>
+<literallayout >
+typedef struct {
+ String type;
+ Widget widget;
+ XtPointer event_data;
+ Cardinal num_event_data;
+} XtChangeHookDataRec, *XtChangeHookData;
+</literallayout>
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+or
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetValues</function>,
+<emphasis remap='I'>widget</emphasis> is the new widget passed to the set_values procedure, and
+<emphasis remap='I'>event_data</emphasis> may be cast to type
+<function>XtChangeHookSetValuesData</function>.
+</para>
+<literallayout >
+typedef struct {
+ Widget old, req;
+ ArgList args;
+ Cardinal num_args;
+} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData;
+</literallayout>
+<para>
+The <emphasis remap='I'>old</emphasis>, <emphasis remap='I'>req</emphasis>, <emphasis remap='I'>args</emphasis>, and <emphasis remap='I'>num_args</emphasis> 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.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+or
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHmanageChildren</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is the list of children being managed, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+The callbacks are called after the children have been managed.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
+or
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHunmanageChildren</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is a list of the children being unmanaged, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+The callbacks are called after the children have been unmanaged.
+</para>
+
+<para>
+The changeHook callbacks are called twice as a result of a call to
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>,
+once after unmanaging and again after managing.
+When the callbacks are called the first time, <emphasis remap='I'>type</emphasis> is set to
+<function>XtHunmanageSet</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is a list of the children being unmanaged, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+When the callbacks are called the second time, the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHmanageSet</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is a list of the children being managed, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHrealizeWidget</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being realized.
+The callbacks are called after the widget has been realized.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHunrealizeWidget</function>,
+and <emphasis remap='I'>widget</emphasis> is the widget being unrealized.
+The callbacks are called after the widget has been unrealized.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHaddCallback</function>,
+<emphasis remap='I'>widget</emphasis> is the widget to which the callback is being added, and
+<emphasis remap='I'>event_data</emphasis> 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.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHaddCallbacks</function>,
+<emphasis remap='I'>widget</emphasis> is the widget to which the callbacks are being added, and
+<emphasis remap='I'>event_data</emphasis> 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.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHremoveCallback</function>,
+<emphasis remap='I'>widget</emphasis> is the widget from which the callback is being removed, and
+<emphasis remap='I'>event_data</emphasis> 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.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHremoveCallbacks</function>,
+<emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed, and
+<emphasis remap='I'>event_data</emphasis> 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.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHremoveAllCallbacks</function>
+and <emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed.
+The callbacks are called after the callbacks have been removed from the
+widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHaugmentTranslations</function>
+and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been
+modified.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHoverrideTranslations</function>
+and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been
+modified.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>,
+The <emphasis remap='I'>type</emphasis> is
+<function>XtHuninstallTranslations</function>
+and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being uninstalled.
+The callbacks are called after the widget's translations have been
+uninstalled.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetKeyboardFocus</function>
+and <emphasis remap='I'>event_data</emphasis> may be cast to type Widget and is the value of
+the descendant argument passed to <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>. The
+callbacks are called before returning from <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetWMColormapWindows</function>,
+<emphasis remap='I'>event_data</emphasis> may be cast to type WidgetList and is the value of
+the list argument passed to <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the list. The callbacks are
+called before returning from <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetMappedWhenManaged</function>
+and <emphasis remap='I'>event_data</emphasis> may be cast to type Boolean and is the value of
+the mapped_when_managed argument passed to <xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>.
+The callbacks are called after setting the widget's mapped_when_managed
+field and before realizing or unrealizing the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type </emphasis> is set to
+<function>XtHmapWidget</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being mapped.
+The callbacks are called after mapping the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type </emphasis> is set to
+<function>XtHunmapWidget</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being unmapped.
+The callbacks are called after unmapping the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHpopup</function>,
+<emphasis remap='I'>widget</emphasis> is the widget being popped up, and <emphasis remap='I'>event_data</emphasis> may
+be cast to type XtGrabKind and is the value of the grab_kind argument
+passed to <xref linkend='XtPopup' xrefstyle='select: title'/>.
+The callbacks are called before returning from <xref linkend='XtPopup' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHpopupSpringLoaded</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being popped up.
+The callbacks are called
+before returning from <xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtPopdown' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHpopdown</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being popped down.
+The callbacks are called
+before returning from <xref linkend='XtPopdown' xrefstyle='select: title'/>.
+</para>
+
+<para>
+A widget set that exports interfaces that change application state
+without employing the Intrinsics library should invoke the change hook
+itself. This is done by:
+</para>
+
+<literallayout >
+ XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data);
+</literallayout>
+<para>
+The XtNconfigureHook callback list is called any time the Intrinsics
+move, resize, or configure a widget and when
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>
+is called.
+</para>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type
+<function>XtConfigureHookData.</function>
+</para>
+<literallayout >
+typedef struct {
+ String type;
+ Widget widget;
+ XtGeometryMask changeMask;
+ XWindowChanges changes;
+} XtConfigureHookDataRec, *XtConfigureHookData;
+</literallayout>
+<para>
+When the configureHook callbacks are called, the <emphasis remap='I'>type</emphasis> is
+<function>XtHconfigure</function>,
+<emphasis remap='I'>widget</emphasis> is the widget being configured, and <emphasis remap='I'>changeMask</emphasis> and
+<emphasis remap='I'>changes</emphasis> reflect the changes made to the widget. The callbacks
+are called after changes have been made to the widget.
+</para>
+
+<para>
+The XtNgeometryHook callback list is called from
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+and
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+once before and once after geometry negotiation occurs.
+</para>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type
+<function>XtGeometryHookData</function>.
+</para>
+
+<literallayout >
+typedef struct {
+ String type;
+ Widget widget;
+ XtWidgetGeometry* request;
+ XtWidgetGeometry* reply;
+ XtGeometryResult result;
+} XtGeometryHookDataRec, *XtGeometryHookData;
+</literallayout>
+<para>
+When the geometryHook callbacks are called prior to geometry negotiation,
+the <emphasis remap='I'>type</emphasis> is
+<function>XtHpreGeometry</function>,
+<emphasis remap='I'>widget</emphasis> is the widget for which the request is being made, and
+<emphasis remap='I'>request</emphasis> is the requested geometry.
+When the geometryHook callbacks
+are called after geometry negotiation, the <emphasis remap='I'>type</emphasis> is
+<function>XtHpostGeometry</function>,
+<emphasis remap='I'>widget</emphasis> is the widget for which the request was made, <emphasis remap='I'>request</emphasis>
+is the requested geometry, <emphasis remap='I'>reply</emphasis> is the resulting geometry granted,
+and <emphasis remap='I'>result</emphasis> is the value returned from the geometry negotiation.
+</para>
+
+<para>
+The XtNdestroyHook callback list is called when a widget is destroyed.
+The <emphasis remap='I'>call_data parameter</emphasis> may be cast to type
+<function>XtDestroyHookData</function>.
+</para>
+<literallayout >
+typedef struct {
+ String type;
+ Widget widget;
+} XtDestroyHookDataRec, *XtDestroyHookData;
+</literallayout>
+<para>
+When the destroyHook callbacks are called as a result of a call to
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is
+<function>XtHdestroy</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being destroyed. The callbacks are
+called upon completion of phase one destroy for a widget.
+</para>
+
+<para>
+The XtNshells and XtnumShells are read-only resources that report a
+list of all parentless shell widgets associated with a display.
+</para>
+
+<para>
+Clients who use these hooks must exercise caution in calling Intrinsics
+functions in order to avoid recursion.
+</para>
+</sect2>
+
+<sect2 id="Querying_Open_Displays">
+<title>Querying Open Displays</title>
+<para>
+To retrieve a list of the Displays associated with an application context,
+use
+<xref linkend='XtGetDisplays' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetDisplays'>
+<funcprototype>
+<funcdef>void <function>XtGetDisplays</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>Display ***<parameter>dpy_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_dpy_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dpy_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of open Display connections in the specified application
+context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_dpy_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the count of open Display connections in <emphasis remap='I'>dpy_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetDisplays' xrefstyle='select: title'/> 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
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/specs/CH12.xml b/specs/CH12.xml
new file mode 100644
index 0000000..3ae6542
--- /dev/null
+++ b/specs/CH12.xml
@@ -0,0 +1,1166 @@
+<chapter id='Nonwidget_Objects'>
+<title>Nonwidget Objects</title>
+
+<para>
+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 (unnamed),
+and members of these classes
+are referred to generically as <emphasis remap='I'>objects</emphasis>. By convention, the term
+<emphasis remap='I'>widget</emphasis> refers only to objects that are a subclass of
+Core,
+and the term <emphasis remap='I'>nonwidget</emphasis> 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 <emphasis remap='I'>widget</emphasis> 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 Intrinsics routines.
+</para>
+<sect1 id="Data_Structures">
+<title>Data Structures</title>
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Object_Objects">
+<title>Object Objects</title>
+<para>
+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
+<function>ObjectClassPart</function>
+and
+<function>ObjectPart</function>
+structures.
+</para>
+<sect2 id="ObjectClassPart_Structure">
+<title>ObjectClassPart Structure</title>
+<para>
+The common fields for all object classes are defined in the
+<function>ObjectClassPart</function>
+structure. All fields have the same purpose,
+function, and restrictions as the corresponding fields in
+<function>CoreClassPart</function>;
+fields whose
+names are obj<emphasis remap='I'>n</emphasis> for some integer <emphasis remap='I'>n</emphasis> 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<emphasis remap='I'>n</emphasis> fields with NULL or zero as appropriate to the type.
+</para>
+<literallayout >
+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;
+</literallayout>
+<para>
+The extension record defined for
+<function>ObjectClassPart</function>
+with a <emphasis remap='I'>record_type</emphasis> equal to
+<emphasis role='strong'>NULLQUARK</emphasis>
+is
+<function>ObjectClassExtensionRec</function>.
+</para>
+<literallayout >
+typedef struct {
+ XtPointer next_extension; See <xref linkend='Class_Extension_Records' />
+ XrmQuark record_type; See <xref linkend='Class_Extension_Records' />
+ long version; See <xref linkend='Class_Extension_Records' />
+ Cardinal record_size; See <xref linkend='Class_Extension_Records' />
+ XtAllocateProc allocate; See <xref linkend='Widget_Instance_Allocation_The_allocate_Procedure' />.
+ XtDeallocateProc deallocate; See <xref linkend='Widget_Instance_Deallocation_The_deallocate_Procedure' />.
+} ObjectClassExtensionRec, *ObjectClassExtension;
+</literallayout>
+<para>
+The prototypical
+<function>ObjectClass</function>
+consists of just the
+<function>ObjectClassPart</function>.
+</para>
+<literallayout >
+typedef struct _ObjectClassRec {
+ ObjectClassPart object_class;
+} ObjectClassRec, *ObjectClass;
+</literallayout>
+<para>
+The predefined class record and pointer for
+<function>ObjectClassRec</function>
+are
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout >
+extern ObjectClassRec objectClassRec;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+extern WidgetClass objectClass;
+</literallayout>
+<para>
+The opaque types
+<function>Object</function>
+and
+<function>ObjectClass</function>
+and the opaque variable
+<function>objectClass</function>
+are defined for generic actions on objects.
+The symbolic constant for the
+<function>ObjectClassExtension</function>
+version identifier is
+<function>XtObjectExtensionVersion</function>
+(see <xref linkend='Class_Extension_Records' />).
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data:
+</para>
+<literallayout >
+typedef struct _ObjectClassRec* ObjectClass;
+</literallayout>
+
+</sect2>
+
+<sect2 id="ObjectPart_Structure">
+<title>ObjectPart Structure</title>
+<para>
+The common fields for all object instances are defined in the
+<function>ObjectPart</function>
+structure. All fields have the same meaning as the
+corresponding fields in
+<function>CorePart</function>.
+</para>
+<literallayout >
+typedef struct _ObjectPart {
+ Widget self;
+ WidgetClass widget_class;
+ Widget parent;
+ Boolean being_destroyed;
+ XtCallbackList destroy_callbacks;
+ XtPointer constraints;
+} ObjectPart;
+</literallayout>
+<para>
+All object instances have the
+Object
+fields as their first component. The prototypical type
+<function>Object</function>
+is defined with only this set of fields.
+Various routines can cast object pointers, as needed, to specific
+object types.
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout >
+typedef struct _ObjectRec {
+ ObjectPart object;
+} ObjectRec, *Object;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+typedef struct _ObjectRec *Object;
+</literallayout>
+
+</sect2>
+
+<sect2 id="Object_Resources">
+<title>Object Resources</title>
+<para>
+The resource names, classes, and representation types specified in the
+<function>objectClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNdestroyCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</sect2>
+
+<sect2 id="ObjectPart_Default_Values">
+<title>ObjectPart Default Values</title>
+<para>
+All fields in
+<function>ObjectPart</function>
+have the same default values as the corresponding fields in
+<function>CorePart</function>.
+</para>
+</sect2>
+
+<sect2 id="Object_Arguments_to_xI_Routines">
+<title>Object Arguments to Intrinsics Routines</title>
+<para>
+The WidgetClass arguments to the following procedures may be
+<function>objectClass</function>
+or any subclass:
+</para>
+
+<para>
+<emphasis role='strong'>XtInitializeWidgetClass</emphasis>,
+<emphasis role='strong'>XtCreateWidget</emphasis>,
+<emphasis role='strong'>XtVaCreateWidget</emphasis>
+<emphasis role='strong'>XtIsSubclass</emphasis>,
+<emphasis role='strong'>XtCheckSubclass</emphasis>
+<emphasis role='strong'>XtGetResourceList</emphasis>,
+<emphasis role='strong'>XtGetConstraintResourceList</emphasis>
+</para>
+
+<para>
+The Widget arguments to the following procedures may be of class
+Object
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtClass' xrefstyle='select: title'/>,
+<function>XtSuperclass</function>,
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>,
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
+<function>XtIsObject</function>,
+<function>XtIsRectObj</function>,
+<function>XtIsWidget</function>,
+<function>XtIsComposite</function>,
+<function>XtIsConstraint</function>,
+<function>XtIsShell</function>,
+<function>XtIsOverrideShell</function>,
+<function>XtIsWMShell</function>,
+<function>XtIsVendorShell</function>,
+<function>XtIsTransientShell</function>,
+<function>XtIsToplevelShell</function>,
+<function>XtIsApplicationShell</function>,
+<function>XtIsSessionShell</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtIsManaged' xrefstyle='select: title'/>,
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>
+(both will return
+<function>False</function>
+if argument is not a subclass of
+RectObj)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtIsRealized' xrefstyle='select: title'/>
+(returns the state of the nearest windowed ancestor
+if class of argument is not a subclass of
+Core)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtParent</function>,
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>
+(descendant)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtGetGC' xrefstyle='select: title'/>,
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtName' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtConvert' xrefstyle='select: title'/>,
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be of class
+Object
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XtParent</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be
+<function>objectClass</function>
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtClass' xrefstyle='select: title'/>,
+<function>XtSuperclass</function>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="Use_of_Objects">
+<title>Use of Objects</title>
+<para>
+The
+Object
+class exists to enable programmers to use the Intrinsics'
+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.
+</para>
+
+<para>
+Composite
+widget classes that wish to accept nonwidget children must
+set the <emphasis remap='I'>accepts_objects</emphasis> field in the
+<function>CompositeClassExtension</function>
+structure to
+<function>True</function>.
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+will otherwise generate an error message on an attempt to create a
+nonwidget child.
+</para>
+
+<para>
+Of the classes defined by the Intrinsics,
+ApplicationShell
+and
+SessionShell
+accept nonwidget children, and the class of any nonwidget child
+must not be
+<function>rectObjClass</function>
+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.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Rectangle_Objects">
+<title>Rectangle Objects</title>
+<para>
+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
+to avoid conflict with the Xlib
+<function>Rectangle</function>
+data type.
+</para>
+<sect2 id="RectObjClassPart_Structure">
+<title>RectObjClassPart Structure</title>
+<para>
+As with the
+<function>ObjectClassPart</function>
+structure, all fields in the
+<function>RectObjClassPart</function>
+structure have the same
+purpose and function as the corresponding fields in
+<function>CoreClassPart</function>;
+fields whose names are rect<emphasis remap='I'>n</emphasis> for some integer
+<emphasis remap='I'>n</emphasis> 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<emphasis remap='I'>n</emphasis> fields with NULL or zero as appropriate to the type.
+</para>
+<literallayout >
+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;
+</literallayout>
+<para>
+The
+RectObj
+class record consists of just the
+<function>RectObjClassPart</function>.
+</para>
+<literallayout >
+typedef struct _RectObjClassRec {
+ RectObjClassPart rect_class;
+} RectObjClassRec, *RectObjClass;
+</literallayout>
+<para>
+The predefined class record and pointer for
+<function>RectObjClassRec</function>
+are
+</para>
+
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+extern RectObjClassRec rectObjClassRec;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+extern WidgetClass rectObjClass;
+</literallayout>
+<para>
+The opaque types
+<function>RectObj</function>
+and
+<function>RectObjClass</function>
+and the opaque variable
+<function>rectObjClass</function>
+are defined for generic actions on objects
+whose class is RectObj or a subclass of
+RectObj.
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the compiler
+catches attempts to access private data:
+</para>
+<literallayout >
+typedef struct _RectObjClassRec* RectObjClass;
+</literallayout>
+
+</sect2>
+
+<sect2 id="RectObjPart_Structure">
+<title>RectObjPart Structure</title>
+<para>
+In addition to the
+<function>ObjectPart</function>
+fields,
+RectObj
+objects have the following fields defined in the
+<function>RectObjPart</function>
+structure. All fields have the same meaning as the corresponding field in
+<function>CorePart</function>.
+</para>
+<literallayout >
+typedef struct _RectObjPart {
+ Position x, y;
+ Dimension width, height;
+ Dimension border_width;
+ Boolean managed;
+ Boolean sensitive;
+ Boolean ancestor_sensitive;
+} RectObjPart;
+</literallayout>
+<para>
+RectObj
+objects have the RectObj fields immediately following the Object fields.
+</para>
+<literallayout >
+typedef struct _RectObjRec {
+ ObjectPart object;
+ RectObjPart rectangle;
+} RectObjRec, *RectObj;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+typedef struct _RectObjRec* RectObj;
+</literallayout>
+
+</sect2>
+
+<sect2 id="RectObj_Resources">
+<title>RectObj Resources</title>
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>rectObjClassRec</function>
+resource list are:
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNancestorSensitive</entry>
+ <entry>XtCSensitive</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNborderWidth</entry>
+ <entry>XtCBorderWidth</entry>
+ <entry>XtRDimension</entry>
+ </row>
+ <row>
+ <entry>XtNheight</entry>
+ <entry>XtCHeight</entry>
+ <entry>XtRDimension</entry>
+ </row>
+ <row>
+ <entry>XtNsensitive</entry>
+ <entry>XtCSensitive</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNwidth</entry>
+ <entry>XtCWidth</entry>
+ <entry>XtRDimension</entry>
+ </row>
+ <row>
+ <entry>XtNx</entry>
+ <entry>XtCPosition</entry>
+ <entry>XtRPosition</entry>
+ </row>
+ <row>
+ <entry>XtNy</entry>
+ <entry>XtCPosition</entry>
+ <entry>XtRPosition</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+</sect2>
+
+<sect2 id="RectObjPart_Default_Values">
+<title>RectObjPart Default Values</title>
+<para>
+All fields in
+<function>RectObjPart</function>
+have the same default values as the corresponding fields in
+<function>CorePart</function>.
+</para>
+</sect2>
+
+<sect2 id="Widget_Arguments_to_xI_Routines">
+<title>Widget Arguments to Intrinsics Routines</title>
+<para>
+The WidgetClass arguments to the following procedures may be
+<function>rectObjClass</function>
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures may be of class
+RectObj
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>,
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>,
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtManageChild' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>,
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be of class
+RectObj
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="Use_of_Rectangle_Objects">
+<title>Use of Rectangle Objects</title>
+<para>
+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, <emphasis remap='I'>rectobj</emphasis> refers only to objects
+whose class is RectObj or a subclass of
+RectObj,
+but not Core or a subclass of
+Core.
+</para>
+
+<para>
+Composite
+widget classes that wish to accept rectobj children must set
+the <emphasis remap='I'>accepts_objects</emphasis> field in the
+<function>CompositeClassExtension</function>
+extension structure to
+<function>True</function>.
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
+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
+Intrinsics accept rectobj children.
+</para>
+
+<para>
+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 Intrinsics; 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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+The Intrinsics will clear areas of a parent window obscured by
+rectobj children, causing exposure events, under the following
+circumstances:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A rectobj child is managed or unmanaged.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+In a call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on a rectobj child, one or more of the set_values procedures returns
+<function>True</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+In a call to
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+In a call to
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+In a call to
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+In a call to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+(or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>)
+on a rectobj child with
+<function>XtQueryOnly</function>
+not set, if the manager returns
+<function>XtGeometryYes</function>,
+two rectangles will be cleared corresponding to both the old and
+the new child geometries.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Undeclared_Class">
+<title>Undeclared Class</title>
+<para>
+The Intrinsics 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
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+The <emphasis remap='I'>core_class.superclass</emphasis> field of
+<function>coreWidgetClassRec</function>
+contains a pointer to the unnamed class record.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A pointer to the unnamed class record when dereferenced as an
+<function>ObjectClass</function>
+will contain a pointer to
+<function>rectObjClassRec</function>
+in its <emphasis remap='I'>object_class.superclass</emphasis> field.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Widget_Arguments_to_Intrinsics_Routines">
+<title>Widget Arguments to Intrinsics Routines</title>
+<para>
+The WidgetClass arguments to the following procedures must be of class
+Shell
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures must be of class
+Core
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>,
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>,
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>,
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>,
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>,
+<function>XtDisplay</function>,
+<xref linkend='XtScreen' xrefstyle='select: title'/>,
+<xref linkend='XtWindow' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>,
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>,
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>,
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
+(both destination and source)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>,
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>
+(subtree)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures must be of class
+Composite
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures must be of a subclass of
+Shell:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtPopdown' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>,
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNone' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>,
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedure will be of class
+Core
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be of a subclass of
+Shell:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+</sect1>
+</chapter>
diff --git a/specs/CH13.xml b/specs/CH13.xml
new file mode 100644
index 0000000..0216b34
--- /dev/null
+++ b/specs/CH13.xml
@@ -0,0 +1,770 @@
+<chapter id='Evolution_of_the_Intrinsics'>
+<title>Evolution of the Intrinsics</title>
+
+<para>
+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.
+</para>
+
+<para>
+The Intrinsics 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.
+</para>
+
+<para>
+In particular, widget programmers may wish to conform to the convention
+described in <xref linkend='Class_Extension_Records' /> when defining class extension records.
+</para>
+<sect1 id="Determining_Specification_Revision_Level">
+<title>Determining Specification Revision Level</title>
+<para>
+Widget and application developers who wish to maintain a common source
+pool that will build properly with implementations of the Intrinsics
+at different revision levels of these specifications but that take
+advantage of newer features added in later revisions may use the
+symbolic macro
+<function>XtSpecificationRelease</function>.
+</para>
+<literallayout >
+#define XtSpecificationRelease 6
+</literallayout>
+<para>
+As the symbol
+<function>XtSpecificationRelease</function>
+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.
+</para>
+</sect1>
+
+<sect1 id="Release_to_Release_Compatibility">
+<title>Release 3 to Release 4 Compatibility</title>
+<para>
+At the data structure level, Release 4 retains binary compatibility
+with Release 3 (the first X Consortium standard release) for all data
+structures except
+<function>WMShellPart,</function>
+<function>TopLevelShellPart</function>,
+and
+<function>TransientShellPart</function>.
+Release 4 changed the argument type to most procedures that now take
+arguments of type
+<function>XtPointer</function>
+and structure members that are now of type
+<function>XtPointer</function>
+in order to avoid potential ANSI C conformance problems. It is
+expected that most implementations will be binary compatible with the
+previous definition.
+</para>
+
+<para>
+Two fields in
+<function>CoreClassPart</function>
+were changed from
+<function>Boolean</function>
+to
+<function>XtEnum</function>
+to allow implementations additional freedom in specifying the
+representations of each. This change should require no source
+modification.
+</para>
+<sect2 id="Additional_Arguments">
+<title>Additional Arguments</title>
+<para>
+Arguments were added to the procedure definitions for
+<xref linkend='XtInitProc' xrefstyle='select: title'/>,
+<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>,
+and
+<xref linkend='XtEventHandler' xrefstyle='select: title'/>
+to provide more information and to
+allow event handlers to abort further dispatching of the current event
+(caution is advised!). The added arguments to
+<xref linkend='XtInitProc' xrefstyle='select: title'/>
+and
+<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+
+<sect2 id="set_values_almost_Procedures">
+<title>set_values_almost Procedures</title>
+<para>
+The use of the arguments by a set_values_almost procedure was poorly
+described in Release 3 and was inconsistent with other conventions.
+</para>
+
+<para>
+The current specification for the manner in which a set_values_almost
+procedure returns information to the Intrinsics 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.
+</para>
+
+<para>
+No known implementation of the Intrinsics correctly implemented the
+Release 3 interface, so it is expected that the impact of this
+specification change is small.
+</para>
+</sect2>
+
+<sect2 id="Query_Geometry">
+<title>Query Geometry</title>
+<para>
+A composite widget layout routine that calls
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+
+<sect2 id="unrealizeCallback_Callback_List">
+<title>unrealizeCallback Callback List</title>
+<para>
+In order to provide a mechanism for widgets to be notified when they
+become unrealized through a call to
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
+the callback
+list name ``unrealizeCallback'' has been defined by the Intrinsics. 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.
+</para>
+</sect2>
+
+<sect2 id="Subclasses_of_WMShell">
+<title>Subclasses of WMShell</title>
+<para>
+The formal adoption of the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis> as
+an X Consortium standard has meant the addition of four fields to
+<function>WMShellPart</function>
+and one field to
+<function>TopLevelShellPart</function>.
+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.
+</para>
+
+<para>
+To provide more convenience for TransientShells, a field was added
+to the previously empty
+<function>TransientShellPart</function>.
+On some architectures the size of the part structure will not
+have changed as a result of this.
+</para>
+
+<para>
+Any widget implementation whose class is a subclass of
+TopLevelShell
+or
+TransientShell
+must at minimum be
+recompiled with the new data structure declarations. Because
+<function>WMShellPart</function>
+no longer contains a contiguous
+<function>XSizeHints</function>
+data structure,
+a subclass that expected to do a single structure assignment of an
+<function>XSizeHints</function>
+structure to the <emphasis remap='I'>size_hints</emphasis> field of
+<function>WMShellPart</function>
+must be revised, though the old fields remain at the same positions within
+<function>WMShellPart</function>.
+</para>
+</sect2>
+
+<sect2 id="Resource_Type_Converters">
+<title>Resource Type Converters</title>
+<para>
+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.
+</para>
+
+<para>
+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
+<xref linkend='XtConverter' xrefstyle='select: title'/>
+was incomplete.
+</para>
+</sect2>
+
+<sect2 id="KeySym_Case_Conversion_Procedure">
+<title>KeySym Case Conversion Procedure</title>
+<para>
+The specification for the
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>
+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 Intrinsics
+implemented the previously documented interface.
+</para>
+</sect2>
+
+<sect2 id="Nonwidget_Objects_2">
+<title>Nonwidget Objects</title>
+<para>
+Formal support for nonwidget objects is new to Release 4. A
+prototype implementation was latent in at least one Release 3
+implementation of the Intrinsics, but the specification has changed
+somewhat. The most significant change is the requirement for a
+composite widget to declare the
+<function>CompositeClassExtension</function>
+record with the <emphasis remap='I'>accepts_objects</emphasis> field set to
+<function>True</function>
+in order to permit a client to create a nonwidget child.
+</para>
+
+<para>
+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
+<emphasis remap='I'>accepts_objects</emphasis> field allows a composite widget to declare that it
+is not prepared to do so.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Release_to_Release_Compatibility_2">
+<title>Release 4 to Release 5 Compatibility</title>
+<para>
+At the data structure level, Release 5 retains complete binary
+compatibility with Release 4. The specification of the
+<function>ObjectPart</function>,
+<function>RectObjPart</function>,
+<function>CorePart</function>,
+<function>CompositePart</function>,
+<function>ShellPart</function>,
+<function>WMShellPart</function>,
+<function>TopLevelShellPart</function>,
+and
+<function>ApplicationShellPart</function>
+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
+<function>XrmValue</function>
+and
+<function>XrmOptionDescRec</function>
+was updated to use a new type,
+<function>XPointer</function>,
+for the <emphasis remap='I'>addr</emphasis> and <emphasis remap='I'>value</emphasis> fields, respectively, to avoid
+ANSI C conformance problems. The definition of
+<function>XPointer</function>
+is binary compatible with the previous implementation.
+</para>
+<sect2 id="baseTranslations_Resource">
+<title>baseTranslations Resource</title>
+<para>
+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''.
+</para>
+
+<para>
+Applications wishing to take advantage of the new functionality
+would change their application defaults file, e.g., from
+<literallayout >
+ app.widget.translations: <emphasis remap='I'>value</emphasis>
+to
+ app.widget.baseTranslations: <emphasis remap='I'>value</emphasis>
+</literallayout>
+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.
+</para>
+</sect2>
+
+<sect2 id="Resource_File_Search_Path">
+<title>Resource File Search Path</title>
+<para>
+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
+<emphasis role='strong'>XFILESEARCHPATH</emphasis>
+and
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+values when overriding the system defaults.
+</para>
+</sect2>
+
+<sect2 id="Customization_Resource">
+<title>Customization Resource</title>
+<para>
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+
+<sect2 id="Per_Screen_Resource_Database">
+<title>Per-Screen Resource Database</title>
+<para>
+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 Intrinsics
+database initialization. Such applications will need to be aware
+of the particular screen on which each shell widget is to be created.
+</para>
+
+<para>
+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
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+</para>
+</sect2>
+
+<sect2 id="Internationalization_of_Applications">
+<title>Internationalization of Applications</title>
+<para>
+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 Intrinsics
+the restrictions of this model have been followed.
+In particular, the new Intrinsics interfaces are designed not to
+preclude an application from using other alternatives.
+For this reason, no Intrinsics 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.
+</para>
+
+<para>
+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
+<function>XtSetLanguageProc</function>
+to do so.
+</para>
+
+<para>
+The internationalization additions also define event filters
+as a part of the Xlib Input Method specifications. The
+Intrinsics enable the use of event filters through additions to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+Applications that may not be dispatching all events through
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+should be reviewed in the context of this new input method mechanism.
+</para>
+
+<para>
+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 Intrinsics to locate the database from localization information
+supplied by the client.
+</para>
+
+<para>
+The previous specification for the syntax of the language string
+specified by
+<function>xnlLanguage</function>
+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.
+</para>
+</sect2>
+
+<sect2 id="Permanently_Allocated_Strings">
+<title>Permanently Allocated Strings</title>
+<para>
+In order to permit additional memory savings, an Xlib interface was
+added to allow the resource manager to avoid copying certain string
+constants. The Intrinsics specification was updated to explicitly require
+the Object <emphasis remap='I'>class_name</emphasis>, <emphasis remap='I'>resource_name</emphasis>, <emphasis remap='I'>resource_class</emphasis>,
+<emphasis remap='I'>resource_type</emphasis>, <emphasis remap='I'>default_type</emphasis> in resource tables, Core <emphasis remap='I'>actions</emphasis>
+<emphasis remap='I'>string</emphasis> field, and Constraint <emphasis remap='I'>resource_name</emphasis>, <emphasis remap='I'>resource_class</emphasis>,
+<emphasis remap='I'>resource_type</emphasis>, and <emphasis remap='I'>default_type</emphasis> resource fields to be
+permanently allocated. This explicit requirement is expected to
+affect only applications that may create and destroy classes
+on the fly.
+</para>
+</sect2>
+
+<sect2 id="Arguments_to_Existing_Functions">
+<title>Arguments to Existing Functions</title>
+<para>
+The <emphasis remap='I'>args</emphasis> argument to
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+and
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+were changed from
+<function>Cardinal</function>*
+to int* to conform to pre-existing convention and avoid otherwise
+annoying typecasting in ANSI C environments.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Release_to_Release_Compatibility_3">
+<title>Release 5 to Release 6 Compatibility</title>
+<para>
+At the data structure level, Release 6 retains binary compatibility
+with Release 5 for all data structures except
+<function>WMShellPart</function>.
+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.
+</para>
+<sect2 id="Widget_Internals">
+<title>Widget Internals</title>
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+As a convenience, an interface to locate a widget class extension
+record on a linked list,
+<xref linkend='XtGetClassExtension' xrefstyle='select: title'/>,
+has been added.
+</para>
+
+<para>
+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 <function>True</function> in the
+extension record.
+</para>
+
+<para>
+The wording of the process followed by
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+has changed slightly to better handle changes to the managed set
+during phase 2 destroy processing.
+</para>
+
+<para>
+A new exposure event compression flag,
+<function>XtExposeNoRegion</function>,
+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 Intrinsics need not
+compute the region.
+</para>
+</sect2>
+
+<sect2 id="General_Application_Development">
+<title>General Application Development</title>
+<para>
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+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,
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>,
+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.
+</para>
+
+<para>
+The toolkit initialization function
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+may be called multiple times without penalty.
+</para>
+
+<para>
+In order to optimize changes in geometry to a set of geometry-managed
+children, a new interface,
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>,
+has been added.
+</para>
+</sect2>
+
+<sect2 id="Communication_with_Window_and_Session_Managers">
+<title>Communication with Window and Session Managers</title>
+<para>
+The revision of the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis> as an X Consortium standard has resulted
+in the addition of three fields to the specification of
+<function>WMShellPart</function>.
+These are <emphasis remap='I'>urgency</emphasis>, <emphasis remap='I'>client_leader</emphasis>, and <emphasis remap='I'>window_role</emphasis>.
+</para>
+
+<para>
+The adoption of the <emphasis remap='I'>X Session Management Protocol</emphasis> as an X Consortium
+standard has resulted in the addition of a new shell widget,
+<function>SessionShell</function>,
+and an accompanying subclass verification interface,
+<function>XtIsSessionShell</function>.
+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
+<function>ApplicationShell</function>,
+the
+<function>ApplicationShell</function>
+was subclassed to create the new widget class.
+The session protocol requires a modal response to certain checkpointing
+operations by participating applications. The
+<function>SessionShell</function>
+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
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+and
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+There is also a new command line argument, -xtsessionID, which facilitates
+the session manager in restarting applications based on the Intrinsics.
+</para>
+
+<para>
+The resource name and class strings defined by the Intrinsics shell
+widgets in
+<function>&lt;X11/Shell.h&gt;</function>
+are now listed in Appendix E. The addition of a new symbol
+for the
+<function>WMShell</function>
+<emphasis remap='I'>wait_for_wm</emphasis> resource was made to bring the external symbol
+and the string it represents into agreement. The actual resource name
+string in
+<function>WMShell</function>
+has not changed.
+The resource representation type of the XtNwinGravity resource of the
+<function>WMShell</function>
+was changed to XtRGravity in order to register a type
+converter so that window gravity resource values could be specified by name.
+</para>
+</sect2>
+
+<sect2 id="Geometry_Management_2">
+<title>Geometry Management</title>
+<para>
+A clarification to the specification was made to indicate that geometry
+requests may include current values along with the requested changes.
+</para>
+</sect2>
+
+<sect2 id="Event_Management_2">
+<title>Event Management</title>
+<para>
+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
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+and
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>.
+Since the mechanism to indicate selection of extension events is specific
+to the extension being used, the Intrinsics introduces
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>,
+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 Intrinsics event dispatcher may now be replaced or enveloped
+by the application with
+<xref linkend='XtSetEventDispatcher' xrefstyle='select: title'/>.
+The dispatcher may wish to call
+<xref linkend='XtGetKeyboardFocusWidget' xrefstyle='select: title'/>
+to determine the widget with the current Intrinsics keyboard focus.
+A dispatcher, after determining the destination widget, may use
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+to cause the event to be dispatched to the event handlers registered
+by a specific widget.
+</para>
+
+<para>
+To permit the dispatching of events
+for nonwidget drawables, such as pixmaps that are not associated
+with a widget's window,
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+and
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>
+have been added to the library. A related update was made to
+the description of
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>.
+</para>
+
+<para>
+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
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtAppLock' xrefstyle='select: title'/>,
+<xref linkend='XtAppUnlock' xrefstyle='select: title'/>,
+<xref linkend='XtAppSetExitFlag' xrefstyle='select: title'/>,
+and
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>.
+Widget writers may also use
+<xref linkend='XtProcessLock' xrefstyle='select: title'/>
+and
+<xref linkend='XtProcessUnlock' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Safe handling of POSIX signals and other asynchronous notifications
+is now provided by use of
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>,
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>,
+and
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The application can receive notification of an impending block
+in the Intrinsics event manager by registering interest through
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>
+and
+<xref linkend='XtRemoveBlockHook' xrefstyle='select: title'/>.
+</para>
+
+<para>
+<xref linkend='XtLastEventProcessed' xrefstyle='select: title'/>
+returns the most recent event passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for a specified display.
+</para>
+</sect2>
+
+<sect2 id="Resource_Management_2">
+<title>Resource Management</title>
+<para>
+Resource converters are registered by the Intrinsics for window gravity
+and for three new resource types associated with session participation:
+RestartStyle, CommandArgArray and DirectoryString.
+</para>
+
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Translation_Management_2">
+<title>Translation Management</title>
+<para>
+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.
+</para>
+</sect2>
+
+<sect2 id="Selections">
+<title>Selections</title>
+<para>
+The targets of selection requests may be parameterized, as described
+by the revised <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>.
+When such requests are made,
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>
+is used by the requestor to specify the target parameters and
+<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>
+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,
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>,
+<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>,
+and
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+are used to envelop the assembly of the request.
+When the parameters themselves are the names of properties,
+the Intrinsics provides support for the economical use of property atom names;
+see
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+and
+<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>.
+</para>
+</sect2>
+
+<sect2 id="External_Agent_Hooks">
+<title>External Agent Hooks</title>
+<para>
+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
+<xref linkend='XtHooksOfDisplay' xrefstyle='select: title'/>,
+which returns the hook registration widget, and
+<xref linkend='XtGetDisplays' xrefstyle='select: title'/>,
+which returns a list of the X displays associated with an application context.
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/specs/Makefile.am b/specs/Makefile.am
index 887eb7e..c922dbb 100644
--- a/specs/Makefile.am
+++ b/specs/Makefile.am
@@ -1,24 +1,37 @@
-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
+
+if ENABLE_SPECS
+
+# Main DocBook/XML files (DOCTYPE book)
+docbook = intrinsics.xml
+
+# Included chapters, appendix, images
+chapters = \
+ acknowledgement.xml \
+ preface.xml \
+ CH01.xml \
+ CH02.xml \
+ CH03.xml \
+ CH04.xml \
+ CH05.xml \
+ CH06.xml \
+ CH07.xml \
+ CH08.xml \
+ CH09.xml \
+ CH10.xml \
+ CH11.xml \
+ CH12.xml \
+ CH13.xml \
+ appA.xml \
+ appB.xml \
+ appC.xml \
+ appD.xml \
+ appE.xml \
+ appF.xml
+
+# The location where the DocBook/XML files and their generated formats are installed
+shelfdir = $(docdir)
+
+# Generate DocBook/XML output formats with or without stylesheets
+include $(top_srcdir)/docbook.am
+
+endif ENABLE_SPECS
diff --git a/specs/acknowledgement.xml b/specs/acknowledgement.xml
new file mode 100644
index 0000000..ea25a5a
--- /dev/null
+++ b/specs/acknowledgement.xml
@@ -0,0 +1,323 @@
+<!-- <acknowledgements> -->
+<dedication>
+<title>Acknowledgments</title>
+
+<para>
+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:
+</para>
+
+<!-- <sidebar> -->
+<para>
+<informaltable frame='none'>
+<?dbfo keep-together="always" ?>
+ <tgroup cols='2' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' />
+ <colspec colwidth='1.0*' />
+ <tbody>
+ <row><?dbfo row-height="0.2cm"?>
+ <entry>Loretta Guarino-Reid (Digital WSL)</entry>
+ <entry>Rich Hyde (Digital WSL)</entry>
+ </row>
+ <row><?dbfo row-height="0.2cm"?>
+ <entry>Susan Angebranndt (Digital WSL)</entry>
+ <entry>Terry Weissman (Digital WSL)</entry>
+ </row>
+ <row><?dbfo row-height="0.2cm"?>
+ <entry>Mary Larson (Digital UEG)</entry>
+ <entry>Mark Manasse (Digital SRC)</entry>
+ </row>
+ <row><?dbfo row-height="0.5cm"?>
+ <entry>Jim Gettys (Digital SRC)</entry>
+ <entry>Leo Treggiari (Digital SDT)</entry>
+ </row>
+ <row><?dbfo row-height="0.5cm"?>
+ <entry>Ralph Swick (Project Athena and Digital ERP)</entry>
+ <entry>Mark Ackerman (Project Athena)</entry>
+ </row>
+ <row><?dbfo row-height="0.5cm"?>
+ <entry>Ron Newman (Project Athena)</entry>
+ <entry>Bob Scheifler (MIT LCS)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- </sidebar> -->
+
+<para>
+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.
+</para>
+
+<para>
+The design and implementation of the X10 Intrinsics were done by:
+</para>
+
+<!-- <sidebar> -->
+<para>
+<informaltable frame='none'>
+<?dbfo keep-together="always" ?>
+ <tgroup cols='1' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' />
+ <tbody>
+ <row>
+ <entry>Terry Weissman (Digital WSL)</entry>
+ </row>
+ <row>
+ <entry>Smokey Wallace (Digital WSL)</entry>
+ </row>
+ <row>
+ <entry>Phil Karlton (Digital WSL)</entry>
+ </row>
+ <row>
+ <entry>Charles Haynes (Digital WSL)</entry>
+ </row>
+ <row>
+ <entry>Frank Hall (HP)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- </sidebar> -->
+
+<para>
+The design and implementation of the X10 toolkit’s sample widgets were by
+the above, as well as by:
+</para>
+
+<!-- <sidebar> -->
+<para>
+<informaltable frame='none'>
+<?dbfo keep-together="always" ?>
+ <tgroup cols='1' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' />
+ <tbody>
+ <row>
+ <entry>Ram Rao (Digital UEG)</entry>
+ </row>
+ <row>
+ <entry>Mary Larson (Digital UEG)</entry>
+ </row>
+ <row>
+ <entry>Mike Gancarz (Digital UEG)</entry>
+ </row>
+ <row>
+ <entry>Kathleen Langone (Digital UEG)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- </sidebar> -->
+
+<para>
+These widgets provided a checklist of requirements that we had to address in the X11 Intrinsics.
+</para>
+<para>
+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.
+</para>
+<para>
+Finally, a special thanks to Mike Chow, whose extensive performance analysis of the X10 toolkit
+provided the justification to redesign it entirely for X11.
+</para>
+
+<literallayout>
+Joel McCormack
+Western Software Laboratory
+Digital Equipment Corporation
+March 1988
+</literallayout>
+
+
+<para>
+The current design of the Intrinsics 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 Intrinsics:
+</para>
+
+<!-- <sidebar> -->
+<para>
+<informaltable frame='none'>
+<?dbfo keep-together="always" ?>
+ <tgroup cols='2' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' />
+ <colspec colwidth='1.0*' />
+ <tbody>
+ <row>
+ <entry>Steve Pitschke (Stellar)</entry>
+ <entry>C.Doug Blewett (AT&amp;T)</entry>
+ </row>
+ <row>
+ <entry>Bob Miller (HP)</entry>
+ <entry>David Schiferl (Tektronix)</entry>
+ </row>
+ <row>
+ <entry>Fred Taft (HP)</entry>
+ <entry>Michael Squires (Sequent)</entry>
+ </row>
+ <row>
+ <entry>Marcel Meth (AT&amp;T)</entry>
+ <entry>JimFulton (MIT)</entry>
+ </row>
+ <row>
+ <entry>Mike Collins (Digital)</entry>
+ <entry>Kerry Kimbrough (Texas Instruments)</entry>
+ </row>
+ <row>
+ <entry>Scott McGregor (Digital)</entry>
+ <entry>Phil Karlton (Digital)</entry>
+ </row>
+ <row>
+ <entry>Julian Payne (ESS)</entry>
+ <entry>Jacques Davy (Bull)</entry>
+ </row>
+ <row>
+ <entry>Gabriel Beged-Dov (HP)</entry>
+ <entry>GlennWidener (Tektronix)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- </sidebar> -->
+
+<para>
+Thanks go to each of them for the countless hours spent reviewing drafts and code.
+</para>
+
+<literallayout>
+Ralph R. Swick
+External Research Group
+Digital Equipment Corporation
+MIT Project Athena
+June 1988
+</literallayout>
+
+
+<para>
+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:
+</para>
+
+<!-- <sidebar> -->
+<para>
+<informaltable frame='none'>
+<?dbfo keep-together="always" ?>
+ <tgroup cols='2' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' />
+ <colspec colwidth='1.0*' />
+ <tbody>
+ <row>
+ <entry>Don Alecci (AT&amp;T)</entry>
+ <entry>EllisCohen (OSF)</entry>
+ </row>
+ <row>
+ <entry>Donna Converse (MIT)</entry>
+ <entry>Clive Feather (IXI)</entry>
+ </row>
+ <row>
+ <entry>Nayeem Islam (Sun)</entry>
+ <entry>Dana Laursen (HP)</entry>
+ </row>
+ <row>
+ <entry>Keith Packard (MIT)</entry>
+ <entry>Chris Peterson (MIT)</entry>
+ </row>
+ <row>
+ <entry>Richard Probst (Sun)</entry>
+ <entry>Larry Cable (Sun)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- </sidebar> -->
+
+<para>
+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.
+</para>
+
+<literallayout>
+Ralph R. Swick
+December 1989
+and
+July 1991
+</literallayout>
+
+<para>
+The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consortium’s
+intrinsics 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:
+</para>
+
+<!-- <sidebar> -->
+<para>
+<informaltable frame='none'>
+<?dbfo keep-together="always" ?>
+ <tgroup cols='2' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' />
+ <colspec colwidth='1.0*' />
+ <tbody>
+ <row>
+ <entry>Paul Asente (Adobe)</entry>
+ <entry>Larry Cable (SunSoft)</entry>
+ </row>
+ <row>
+ <entry>Ellis Cohen (OSF)</entry>
+ <entry>Daniel Dardailler (OSF)</entry>
+ </row>
+ <row>
+ <entry>Vania Joloboff (OSF)</entry>
+ <entry>KalebKeithley (X Consortium)</entry>
+ </row>
+ <row>
+ <entry>Courtney Loomis (HP)</entry>
+ <entry>Douglas Rand (OSF)</entry>
+ </row>
+ <row>
+ <entry>Bob Scheifler (X Consortium)</entry>
+ <entry>Ajay Vohra (SunSoft)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+<!-- </sidebar> -->
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<literallayout>
+Donna Converse
+X Consortium
+April 1994
+</literallayout>
+</dedication>
+<!-- </acknowledgements> -->
diff --git a/specs/appA.xml b/specs/appA.xml
new file mode 100644
index 0000000..daf40eb
--- /dev/null
+++ b/specs/appA.xml
@@ -0,0 +1,112 @@
+<appendix id='Resource_File_Format'>
+<title>Resource File Format</title>
+<para>
+A resource file contains text representing the default resource values for an
+application or set of applications.
+</para>
+
+<para>
+The format of resource files is defined by
+<emphasis remap='I'>Xlib — C Language X Interface.</emphasis> and is reproduced here
+for convenience only.
+</para>
+
+<para>The format of a resource specification is</para>
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='0.3*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <tbody>
+ <row>
+ <entry>ResourceLine</entry>
+ <entry>= Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;</entry>
+ </row>
+ <row>
+ <entry>Comment</entry>
+ <entry>="!" {&lt;any character except null or newline&gt;}</entry>
+ </row>
+ <row>
+ <entry>IncludeFile</entry>
+ <entry>= "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace</entry>
+ </row>
+ <row>
+ <entry>FileName</entry>
+ <entry>= &lt;valid filename for operating system&gt;</entry>
+ </row>
+ <row>
+ <entry>ResourceSpec</entry>
+ <entry>= WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value</entry>
+ </row>
+ <row>
+ <entry>ResourceName</entry>
+ <entry>= [Binding] {Component Binding} ComponentName</entry>
+ </row>
+ <row>
+ <entry>Binding</entry>
+ <entry>="." | "*"</entry>
+ </row>
+ <row>
+ <entry>WhiteSpace</entry>
+ <entry>= {&lt;space> | &lt;horizontal tab&gt;}</entry>
+ </row>
+ <row>
+ <entry>Component</entry>
+ <entry>= "?" | ComponentName</entry>
+ </row>
+ <row>
+ <entry>ComponentName</entry>
+ <entry>= NameChar {NameChar}</entry>
+ </row>
+ <row>
+ <entry>NameChar</entry>
+ <entry>= "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"</entry>
+ </row>
+ <row>
+ <entry>Value</entry>
+ <entry>={&lt;any character except null or unescaped newline&gt;}</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+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.
+</para>
+
+<para>
+If the last character on a line is a backslash (\),
+that line is assumed to continue on the next line.
+</para>
+
+<para>
+To allow a Value to begin with whitespace,
+the two-character sequence "\<emphasis remap='I'>space</emphasis>" (backslash followed by space)
+is recognized and replaced by a space character,
+and the two-character sequence "\<emphasis remap='I'>tab</emphasis>"
+(backslash followed by horizontal tab)
+is recognized and replaced by a horizontal tab character.
+</para>
+<para>
+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 "\<emphasis remap='I'>newline</emphasis>"
+(backslash followed by newline) is
+recognized and removed from the value.
+</para>
+<para>
+To allow a Value to contain arbitrary character codes,
+the four-character sequence "\<emphasis remap='I'>nnn</emphasis>",
+where each <emphasis remap='I'>n</emphasis> 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.
+</para>
+</appendix>
diff --git a/specs/appB.xml b/specs/appB.xml
new file mode 100644
index 0000000..0afac11
--- /dev/null
+++ b/specs/appB.xml
@@ -0,0 +1,1181 @@
+<appendix id='Translation_Table_Syntax'>
+<title>Translation Table Syntax</title>
+<para><emphasis role='strong'>Notation</emphasis></para>
+
+<para>
+Syntax is specified in EBNF notation with the following conventions:
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='0.1*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <tbody>
+ <row>
+ <entry>[ a ]</entry>
+ <entry>Means either nothing or "a"</entry>
+ </row>
+ <row>
+ <entry>{ a }</entry>
+ <entry>Means zero or more occurrences of "a"</entry>
+ </row>
+ <row>
+ <entry>( a | b )</entry>
+ <entry>Means either "a" or "b"</entry>
+ </row>
+ <row>
+ <entry>\\n</entry>
+ <entry>Is the newline character</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+All terminals are enclosed in double quotation marks (" ").
+Informal descriptions are enclosed in angle brackets (&lt; &gt;).
+Syntax
+</para>
+
+<para>The syntax of a translation table is</para>
+<informaltable frame='none'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='0.2*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <tbody>
+ <row>
+ <entry>translationTable</entry>
+ <entry>= [ directive ] { production }</entry>
+ </row>
+ <row>
+ <entry>directive</entry>
+ <entry>= ( "#replace" | "#override" | "#augment" ) "\\\\n"</entry>
+ </row>
+ <row>
+ <entry>production</entry>
+ <entry>= lhs ":" rhs "\\\\n"</entry>
+ </row>
+ <row>
+ <entry>lhs</entry>
+ <entry>= ( event | keyseq ) { "," (event | keyseq) }</entry>
+ </row>
+ <row>
+ <entry>keyseq</entry>
+ <entry>= """ keychar {keychar} """</entry>
+ </row>
+ <row>
+ <entry>keychar</entry>
+ <entry>= [ "^" | "$" | "\\\\" ] &lt;ISO Latin 1 character&gt;</entry>
+ </row>
+ <row>
+ <entry>event</entry>
+ <entry>= [modifier_list] "&lt;"event_type"&gt;" [ "(" count["+"] ")" ] {detail}</entry>
+ </row>
+ <row>
+ <entry>modifier_list</entry>
+ <entry>= ( ["!"] [":"] {modifier} ) | "None"</entry>
+ </row>
+ <row>
+ <entry>modifier</entry>
+ <entry>= ["~"] modifier_name</entry>
+ </row>
+ <row>
+ <entry>count</entry>
+ <entry>= ("1" | "2" | "3" | "4" | ...)</entry>
+ </row>
+ <row>
+ <entry>modifier_name</entry>
+ <entry>= "@" &lt;keysym&gt; | &lt;see ModifierNames table below&gt;</entry>
+ </row>
+ <row>
+ <entry>event_type</entry>
+ <entry>= &lt;see Event Types table below&gt;</entry>
+ </row>
+ <row>
+ <entry>detail</entry>
+ <entry>= &lt;event specific details&gt;</entry>
+ </row>
+ <row>
+ <entry>rhs</entry>
+ <entry>= { name "(" [params] ")" }</entry>
+ </row>
+ <row>
+ <entry>name</entry>
+ <entry>= namechar { namechar }</entry>
+ </row>
+ <row>
+ <entry>namechar</entry>
+ <entry>= { "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-" }</entry>
+ </row>
+ <row>
+ <entry>params</entry>
+ <entry>= string {"," string}</entry>
+ </row>
+ <row>
+ <entry>string</entry>
+ <entry>= quoted_string | unquoted_string</entry>
+ </row>
+ <row>
+ <entry>quoted_string</entry>
+ <entry>= <quote>"</quote> {&lt;Latin 1 character&gt; | escape_char} ["\\\\" ] <quote>"</quote></entry>
+ </row>
+ <row>
+ <entry>escape_char</entry>
+ <entry>= "\\""</entry>
+ </row>
+ <row>
+ <entry>unquoted_string</entry>
+ <entry>= {&lt;Latin 1 character except space, tab, ",", "\\n", ")"&gt;}</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>params</emphasis> field is parsed into a list of
+<function>String</function>
+values that will be passed to the named action procedure. A
+<emphasis remap='I'>quoted string</emphasis> 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".
+</para>
+<para><emphasis role='strong'>Modifier Names</emphasis></para>
+
+<para>
+The modifier field is used to specify standard X keyboard and button
+modifier mask bits.
+Modifiers are legal on event types
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+<function>MotionNotify</function>,
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+and their abbreviations.
+An error is generated when a translation table
+that contains modifiers for any other events is parsed.
+</para>
+
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the modifier list has no entries and is not "None",
+it means "don't care" on all modifiers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a modifier is preceded by a tilde (~),
+it means that that modifier must not be asserted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If "None" is specified, it means no modifiers can be asserted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a colon (:) is specified at the beginning of the modifier list,
+it directs the Intrinsics 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 <emphasis remap='I'>X Window
+System Protocol</emphasis>, 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, ":&lt;Key&gt;a" is distinct from ":&lt;Key&gt;A",
+and ":Shift&lt;Key&gt;A" is distinct from ":&lt;Key&gt;A".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a colon (:) is not specified,
+no standard modifiers are applied.
+Then, for example, "&lt;Key&gt;A" and "&lt;Key&gt;a" are equivalent.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+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:
+</para>
+
+<literallayout >
+No modifiers: None &lt;event&gt; detail
+Any modifiers: &lt;event&gt; detail
+Only these modifiers: ! mod1 mod2 &lt;event&gt; detail
+These modifiers and any others: mod1 mod2 &lt;event&gt; detail
+</literallayout>
+
+<para>
+The use of "None" for a modifier list is identical to the use
+of an exclamation point with no modifers.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Modifier</entry>
+ <entry>Abbreviation</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Ctrl</entry>
+ <entry>c</entry>
+ <entry>Control modifier bit</entry>
+ </row>
+ <row>
+ <entry>Shift</entry>
+ <entry>s</entry>
+ <entry>Shift modifier bit</entry>
+ </row>
+ <row>
+ <entry>Lock</entry>
+ <entry>l</entry>
+ <entry>Lock modifier bit</entry>
+ </row>
+ <row>
+ <entry>Meta</entry>
+ <entry>m</entry>
+ <entry>Meta key modifier</entry>
+ </row>
+ <row>
+ <entry>Hyper</entry>
+ <entry>h</entry>
+ <entry>Hyper key modifier</entry>
+ </row>
+ <row>
+ <entry>Super</entry>
+ <entry>su</entry>
+ <entry>Super key modifier</entry>
+ </row>
+ <row>
+ <entry>Alt</entry>
+ <entry>a</entry>
+ <entry>Alt key modifier</entry>
+ </row>
+ <row>
+ <entry>Mod1</entry>
+ <entry></entry>
+ <entry>Mod1 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Mod2</entry>
+ <entry></entry>
+ <entry>Mod2 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Mod3</entry>
+ <entry></entry>
+ <entry>Mod3 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Mod4</entry>
+ <entry></entry>
+ <entry>Mod4 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Mod5</entry>
+ <entry></entry>
+ <entry>Mod5 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Button1</entry>
+ <entry></entry>
+ <entry>Button1 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Button2</entry>
+ <entry></entry>
+ <entry>Button2 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Button3</entry>
+ <entry></entry>
+ <entry>Button3 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Button4</entry>
+ <entry></entry>
+ <entry>Button4 modifier bit</entry>
+ </row>
+ <row>
+ <entry>Button5</entry>
+ <entry></entry>
+ <entry>Button5 modifier bit</entry>
+ </row>
+ <row>
+ <entry>None</entry>
+ <entry></entry>
+ <entry>No modifiers</entry>
+ </row>
+ <row>
+ <entry>Any</entry>
+ <entry></entry>
+ <entry>Any modifier combination</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+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.
+</para>
+
+<para>
+Because it is possible to associate arbitrary KeySyms with modifiers, the set of
+key modifiers is extensible. The "@" &lt;keysym&gt; syntax means any
+modifier bit whose corresponding KeyCode contains the specified KeySym name.
+</para>
+
+<para>
+A modifier_list/KeySym combination in a translation matches a
+modifiers/KeyCode combination in an event in the following ways:
+</para>
+
+<orderedlist>
+ <listitem>
+ <para>
+If a colon (:) is used, the Intrinsics call the display's
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>
+with the KeyCode and modifiers.
+To match, (<emphasis remap='I'>modifiers</emphasis> &amp; ~<emphasis remap='I'>modifiers_return</emphasis>) must equal <emphasis remap='I'>modifier_list</emphasis>, and
+<emphasis remap='I'>keysym_return</emphasis> must equal the given KeySym.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If (:) is not used, the Intrinsics mask off all don't-care bits from the
+modifiers.
+This value must be equal to <emphasis remap='I'>modifier_list</emphasis>.
+Then, for each possible combination of
+don't-care modifiers in the modifier list, the Intrinsics call the display's
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>
+with the KeyCode and that combination ORed with the cared-about modifier bits
+from the event.
+<emphasis remap='I'>Keysym_return</emphasis> must match the KeySym in the translation.
+ </para>
+ </listitem>
+</orderedlist>
+
+<para><emphasis role='strong'>Event Types</emphasis></para>
+
+<para>
+The event-type field describes XEvent types.
+In addition to the standard
+Xlib symbolic event type names, the following event type synonyms
+are defined:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Type</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Key</entry>
+ <entry><function>KeyPress</function></entry>
+ </row>
+ <row>
+ <entry>KeyDown</entry>
+ <entry><function>KeyPress</function></entry>
+ </row>
+ <row>
+ <entry>KeyUp</entry>
+ <entry><function>KeyRelease</function></entry>
+ </row>
+ <row>
+ <entry>BtnDown</entry>
+ <entry><function>ButtonPress</function></entry>
+ </row>
+ <row>
+ <entry>BtnUp</entry>
+ <entry><function>ButtonRelease</function></entry>
+ </row>
+ <row>
+ <entry>Motion</entry>
+ <entry><function>MotionNotify</function></entry>
+ </row>
+ <row>
+ <entry>PtrMoved</entry>
+ <entry><function>MotionNotify</function></entry>
+ </row>
+ <row>
+ <entry>MouseMoved</entry>
+ <entry><function>MotionNotify</function></entry>
+ </row>
+ <row>
+ <entry>Enter</entry>
+ <entry><function>EnterNotify</function></entry>
+ </row>
+ <row>
+ <entry>EnterWindow</entry>
+ <entry><function>EnterNotify</function></entry>
+ </row>
+ <row>
+ <entry>Leave</entry>
+ <entry><function>LeaveNotify</function></entry>
+ </row>
+ <row>
+ <entry>LeaveWindow</entry>
+ <entry><function>LeaveNotify</function></entry>
+ </row>
+ <row>
+ <entry>FocusIn</entry>
+ <entry><function>FocusIn</function></entry>
+ </row>
+ <row>
+ <entry>FocusOut</entry>
+ <entry><function>FocusOut</function></entry>
+ </row>
+ <row>
+ <entry>Keymap</entry>
+ <entry><function>KeymapNotify</function></entry>
+ </row>
+ <row>
+ <entry>Expose</entry>
+ <entry><function>Expose</function></entry>
+ </row>
+ <row>
+ <entry>GrExp</entry>
+ <entry><function>GraphicsExpose</function></entry>
+ </row>
+ <row>
+ <entry>NoExp</entry>
+ <entry><function>NoExpose</function></entry>
+ </row>
+ <row>
+ <entry>Visible</entry>
+ <entry><function>VisibilityNotify</function></entry>
+ </row>
+ <row>
+ <entry>Create</entry>
+ <entry><function>CreateNotify</function></entry>
+ </row>
+ <row>
+ <entry>Destroy</entry>
+ <entry><function>DestroyNotify</function></entry>
+ </row>
+ <row>
+ <entry>Unmap</entry>
+ <entry><function>UnmapNotify</function></entry>
+ </row>
+ <row>
+ <entry>Map</entry>
+ <entry><function>MapNotify</function></entry>
+ </row>
+ <row>
+ <entry>MapReq</entry>
+ <entry><function>MapRequest</function></entry>
+ </row>
+ <row>
+ <entry>Reparent</entry>
+ <entry><function>ReparentNotify</function></entry>
+ </row>
+ <row>
+ <entry>Configure</entry>
+ <entry><function>ConfigureNotify</function></entry>
+ </row>
+ <row>
+ <entry>ConfigureReq</entry>
+ <entry><function>ConfigureRequest</function></entry>
+ </row>
+ <row>
+ <entry>Grav</entry>
+ <entry><function>GravityNotify</function></entry>
+ </row>
+ <row>
+ <entry>ResReq</entry>
+ <entry><function>ResizeRequest</function></entry>
+ </row>
+ <row>
+ <entry>Circ</entry>
+ <entry><function>CirculateNotify</function></entry>
+ </row>
+ <row>
+ <entry>CircReq</entry>
+ <entry><function>CirculateRequest</function></entry>
+ </row>
+ <row>
+ <entry>Prop</entry>
+ <entry><function>PropertyNotify</function></entry>
+ </row>
+ <row>
+ <entry>SelClr</entry>
+ <entry><function>SelectionClear</function></entry>
+ </row>
+ <row>
+ <entry>SelReq</entry>
+ <entry><function>SelectionRequest</function></entry>
+ </row>
+ <row>
+ <entry>Select</entry>
+ <entry><function>SelectionNotify</function></entry>
+ </row>
+ <row>
+ <entry>Clrmap</entry>
+ <entry><function>ColormapNotify</function></entry>
+ </row>
+ <row>
+ <entry>Message</entry>
+ <entry><function>ClientMessage</function></entry>
+ </row>
+ <row>
+ <entry>Mapping</entry>
+ <entry><function>MappingNotify</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>The supported abbreviations are:</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Abbreviation</entry>
+ <entry>Event Type</entry>
+ <entry>Including</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Ctrl</entry>
+ <entry><function>KeyPress</function></entry>
+ <entry>with Control modifier</entry>
+ </row>
+ <row>
+ <entry>Meta</entry>
+ <entry><function>KeyPress</function></entry>
+ <entry>with Meta modifier</entry>
+ </row>
+ <row>
+ <entry>Shift</entry>
+ <entry><function>KeyPress</function></entry>
+ <entry>with Shift modifier</entry>
+ </row>
+ <row>
+ <entry>Btn1Down</entry>
+ <entry><function>ButtonPress</function></entry>
+ <entry>with Button1 detail</entry>
+ </row>
+ <row>
+ <entry>Btn1Up</entry>
+ <entry><function>ButtonRelease</function></entry>
+ <entry>with Button1 detail</entry>
+ </row>
+ <row>
+ <entry>Btn2Down</entry>
+ <entry><function>ButtonPress</function></entry>
+ <entry>with Button2 detail</entry>
+ </row>
+ <row>
+ <entry>Btn2Up</entry>
+ <entry><function>ButtonRelease</function></entry>
+ <entry>with Button2 detail</entry>
+ </row>
+ <row>
+ <entry>Btn3Down</entry>
+ <entry><function>ButtonPress</function></entry>
+ <entry>with Button3 detail</entry>
+ </row>
+ <row>
+ <entry>Btn3Up</entry>
+ <entry><function>ButtonRelease</function></entry>
+ <entry>with Button3 detail</entry>
+ </row>
+ <row>
+ <entry>Btn4Down</entry>
+ <entry><function>ButtonPress</function></entry>
+ <entry>with Button4 detail</entry>
+ </row>
+ <row>
+ <entry>Btn4Up</entry>
+ <entry><function>ButtonRelease</function></entry>
+ <entry>with Button4 detail</entry>
+ </row>
+ <row>
+ <entry>Btn5Down</entry>
+ <entry><function>ButtonPress</function></entry>
+ <entry>with Button5 detail</entry>
+ </row>
+ <row>
+ <entry>Btn5Up</entry>
+ <entry><function>ButtonRelease</function></entry>
+ <entry>with Button5 detail</entry>
+ </row>
+ <row>
+ <entry>BtnMotion</entry>
+ <entry><function>MotionNotify</function></entry>
+ <entry>with any button modifier</entry>
+ </row>
+ <row>
+ <entry>Btn1Motion</entry>
+ <entry><function>MotionNotify</function></entry>
+ <entry>with Button1 modifier</entry>
+ </row>
+ <row>
+ <entry>Btn2Motion</entry>
+ <entry><function>MotionNotify</function></entry>
+ <entry>with Button2 modifier</entry>
+ </row>
+ <row>
+ <entry>Btn3Motion</entry>
+ <entry><function>MotionNotify</function></entry>
+ <entry>with Button3 modifier</entry>
+ </row>
+ <row>
+ <entry>Btn4Motion</entry>
+ <entry><function>MotionNotify</function></entry>
+ <entry>with Button4 modifier</entry>
+ </row>
+ <row>
+ <entry>Btn5Motion</entry>
+ <entry><function>MotionNotify</function></entry>
+ <entry>with Button5 modifier</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The detail field is event-specific and normally corresponds to the
+detail field of the corresponding event as described
+by <emphasis remap='I'>X Window System Protocol</emphasis>, Section 11.
+The detail field is supported for the following event types:
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='0.5*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <tbody>
+ <row>
+ <entry>KeyPress</entry>
+ <entry>KeySym from event <emphasis>detail</emphasis> (keycode)</entry>
+ </row>
+ <row>
+ <entry>KeyRelease</entry>
+ <entry>KeySym from event <emphasis>detail</emphasis> (keycode)</entry>
+ </row>
+ <row>
+ <entry>ButtonPress</entry>
+ <entry>button from event <emphasis>detail</emphasis></entry>
+ </row>
+ <row>
+ <entry>ButtonRelease</entry>
+ <entry>button from event <emphasis>detail</emphasis></entry>
+ </row>
+ <row>
+ <entry>MotionNotify</entry>
+ <entry>event <emphasis>detail</emphasis></entry>
+ </row>
+ <row>
+ <entry>EnterNotify</entry>
+ <entry>event <emphasis>mode</emphasis></entry>
+ </row>
+ <row>
+ <entry>LeaveNotify</entry>
+ <entry>event <emphasis>mode</emphasis></entry>
+ </row>
+ <row>
+ <entry>FocusIn</entry>
+ <entry>event <emphasis>mode</emphasis></entry>
+ </row>
+ <row>
+ <entry>FocusOut</entry>
+ <entry>event <emphasis>mode</emphasis></entry>
+ </row>
+ <row>
+ <entry>PropertyNotify</entry>
+ <entry><emphasis>atom</emphasis></entry>
+ </row>
+ <row>
+ <entry>SelectionClear</entry>
+ <entry><emphasis>selection</emphasis></entry>
+ </row>
+ <row>
+ <entry>SelectionRequest</entry>
+ <entry><emphasis>selection</emphasis></entry>
+ </row>
+ <row>
+ <entry>SelectionNotify</entry>
+ <entry><emphasis>selection</emphasis></entry>
+ </row>
+ <row>
+ <entry>ClientMessage</entry>
+ <entry><emphasis>type</emphasis></entry>
+ </row>
+ <row>
+ <entry>MappingNotify</entry>
+ <entry><emphasis>request</emphasis></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+If the event type is
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>,
+the detail field
+specifies a KeySym name in standard format which is matched against
+the event as described above, for example, &lt;Key&gt;A.
+</para>
+
+<para>
+For the
+<function>PropertyNotify</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+and
+<function>ClientMessage</function>
+events the detail field is specified
+as an atom name; for example, &lt;Message&gt;WM_PROTOCOLS. For the
+<function>MotionNotify</function>,
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+<function>FocusIn</function>,
+<function>FocusOut</function>,
+and
+<function>MappingNotify</function>
+events, either the symbolic constants as defined by
+<emphasis remap='I'>X Window
+System Protocol</emphasis>, Section 11,
+or the numeric values may be specified.
+</para>
+
+<para>
+If no detail field is specified, then any value in the event detail is
+accepted as a match.
+</para>
+
+<para>
+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
+<function>&lt;X11/keysymdef.h&gt;</function>
+with the "XK_" prefix removed.
+</para>
+
+<para><emphasis role='strong'>Canonical Representation</emphasis></para>
+
+<para>
+Every translation table has a unique, canonical text representation. This
+representation is passed to a widget's
+<function>display_accelerator</function>
+procedure to describe the accelerators installed on that widget.
+The canonical representation of a translation table is (see also
+"Syntax")
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='0.2*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <tbody>
+ <row>
+ <entry>translationTable</entry>
+ <entry>= { production }
+ </entry>
+ </row>
+ <row>
+ <entry>production</entry>
+ <entry>= lhs ":" rhs "\\n"
+ </entry>
+ </row>
+ <row>
+ <entry>lhs</entry>
+ <entry>=event { "," event }
+ </entry>
+ </row>
+ <row>
+ <entry>event</entry>
+ <entry>=[modifier_list] "&lt;"event_type"&gt;" [ "(" count["+"] ")" ] {detail}
+ </entry>
+ </row>
+ <row>
+ <entry>modifier_list</entry>
+ <entry>= ["!"] [":"] {modifier}
+ </entry>
+ </row>
+ <row>
+ <entry>modifier</entry>
+ <entry>= ["˜"] modifier_name
+ </entry>
+ </row>
+ <row>
+ <entry>count</entry>
+ <entry>=("1" | "2" | "3" | "4" | ...)
+ </entry>
+ </row>
+ <row>
+ <entry>modifier_name</entry>
+ <entry>= "@" &lt;keysym&gt; | &lt;see canonical modifier names below&gt;
+ </entry>
+ </row>
+ <row>
+ <entry>event_type</entry>
+ <entry>= &lt;see canonical event types below&gt;
+ </entry>
+ </row>
+ <row>
+ <entry>detail</entry>
+ <entry>=&lt;event-specific details&gt;
+ </entry>
+ </row>
+ <row>
+ <entry>rhs</entry>
+ <entry>={ name "(" [params] ")" }
+ </entry>
+ </row>
+ <row>
+ <entry>name</entry>
+ <entry>=namechar { namechar }
+ </entry>
+ </row>
+ <row>
+ <entry>namechar</entry>
+ <entry>= { "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-" }
+ </entry>
+ </row>
+ <row>
+ <entry>params</entry>
+ <entry>=string {"," string}
+ </entry>
+ </row>
+ <row>
+ <entry>string</entry>
+ <entry>=quoted_string
+ </entry>
+ </row>
+ <row>
+ <entry>quoted_string</entry>
+ <entry>= <quote>"</quote> {&lt;Latin 1 character&gt; | escape_char} ["\\\\" ] <quote>"</quote>
+ </entry>
+ </row>
+ <row>
+ <entry>escape_char</entry>
+ <entry>= "\\""
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>The canonical modifier names are</para>
+
+<literallayout >
+ Ctrl Mod1 Button1
+ Shift Mod2 Button2
+ Lock Mod3 Button3
+ Mod4 Button4
+ Mod5 Button5
+</literallayout>
+
+<para>The canonical event types are</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <tbody>
+ <row>
+ <entry>KeyPress</entry>
+ <entry>KeyRelease</entry>
+ </row>
+ <row>
+ <entry>ButtonPress</entry>
+ <entry>ButtonRelease</entry>
+ </row>
+ <row>
+ <entry>MotionNotify</entry>
+ <entry>EnterNotify</entry>
+ </row>
+ <row>
+ <entry>LeaveNotify</entry>
+ <entry>FocusIn</entry>
+ </row>
+ <row>
+ <entry>FocusOut</entry>
+ <entry>KeymapNotify</entry>
+ </row>
+ <row>
+ <entry>Expose</entry>
+ <entry>GraphicsExpose,</entry>
+ </row>
+ <row>
+ <entry>NoExpose</entry>
+ <entry>VisibilityNotify</entry>
+ </row>
+ <row>
+ <entry>CreateNotify</entry>
+ <entry>DestroyNotify</entry>
+ </row>
+ <row>
+ <entry>UnmapNotify</entry>
+ <entry>MapNotify</entry>
+ </row>
+ <row>
+ <entry>MapRequest</entry>
+ <entry>ReparentNotify</entry>
+ </row>
+ <row>
+ <entry>ConfigureNotify</entry>
+ <entry>ConfigureRequest</entry>
+ </row>
+ <row>
+ <entry>GravityNotify</entry>
+ <entry>ResizeRequest</entry>
+ </row>
+ <row>
+ <entry>CirculateNotify</entry>
+ <entry>CirculateRequest</entry>
+ </row>
+ <row>
+ <entry>PropertyNotify</entry>
+ <entry>SelectionClear</entry>
+ </row>
+ <row>
+ <entry>SelectionRequest</entry>
+ <entry>SelectionNotify</entry>
+ </row>
+ <row>
+ <entry>ColormapNotify</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Examples</emphasis></para>
+
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Always put more specific events in the table before more general ones:
+ </para>
+<literallayout >
+ Shift &lt;Btn1Down&gt; : twas()\n\
+ &lt;Btn1Down&gt; : brillig()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+For double-click on Button1 Up with Shift, use this specification:
+ </para>
+ <literallayout >
+Shift&lt;Btn1Up&gt;(2) : and()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+This is equivalent to the following line with appropriate timers set
+between events:
+ </para>
+ <literallayout >
+Shift&lt;Btn1Down&gt;,Shift&lt;Btn1Up&gt;,Shift&lt;Btn1Down&gt;,Shift&lt;Btn1Up&gt; : and()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+For double-click on Button1 Down with Shift, use this specification:
+ </para>
+ <literallayout >
+Shift&lt;Btn1Down&gt;(2) : the()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+This is equivalent to the following line with appropriate timers set
+between events:
+ </para>
+ <literallayout >
+Shift&lt;Btn1Down&gt;,Shift&lt;Btn1Up&gt;,Shift&lt;Btn1Down&gt; : the()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+Mouse motion is always discarded when it occurs between events in a table
+where no motion event is specified:
+ </para>
+ <literallayout >
+&lt;Btn1Down&gt;,&lt;Btn1Up&gt; : slithy()
+</literallayout>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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:
+ </para>
+ <literallayout >
+&lt;Btn1Down&gt;,&lt;Btn1Up&gt; : toves()\n\
+&lt;Btn1Up&gt; : did()
+</literallayout>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+For single click on Button1 Up with Shift and Meta, use this specification:
+ </para>
+ </listitem>
+ <listitem>
+ <literallayout >
+Shift Meta &lt;Btn1Down&gt;, Shift Meta&lt;Btn1Up&gt;: gyre()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+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 <emphasis remap='I'>count</emphasis>-th click and each subsequent one arriving
+within the multi-click time interval. For example:
+ </para>
+ <literallayout >
+Shift &lt;Btn1Up&gt;(2+) : and()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+To indicate
+<function>EnterNotify</function>
+with any modifiers, use this specification:
+ </para>
+ <literallayout >
+&lt;Enter&gt; : gimble()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+To indicate
+<function>EnterNotify</function>
+with no modifiers, use this specification:
+ </para>
+ <literallayout >
+None &lt;Enter&gt; : in()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+To indicate
+<function>EnterNotify</function>
+with Button1 Down and Button2 Up and "don't care" about
+the other modifiers, use this specification:
+ </para>
+ <literallayout >
+Button1 ~Button2 &lt;Enter&gt; : the()
+</literallayout>
+ </listitem>
+ <listitem>
+ <para>
+To indicate
+<function>EnterNotify</function>
+with Button1 down and Button2 down exclusively, use this specification:
+ </para>
+ <literallayout >
+! Button1 Button2 &lt;Enter&gt; : wabe()
+</literallayout>
+ <para>
+You do not need to use a tilde (~) with an exclamation point (!).
+ </para>
+ </listitem>
+</itemizedlist>
+</appendix>
diff --git a/specs/appC.xml b/specs/appC.xml
new file mode 100644
index 0000000..4598ac9
--- /dev/null
+++ b/specs/appC.xml
@@ -0,0 +1,1970 @@
+<appendix id='Compability_Functions'>
+<title>Compatibility Functions
+<footnote>
+<para>
+This appendix is part of the formal Intrinsics Specification.
+</para>
+</footnote>
+</title>
+<para>
+In prototype versions of the X Toolkit
+each widget class
+implemented an Xt&lt;<emphasis remap='I'>Widget</emphasis>&gt;Create (for example,
+<function>XtLabelCreate</function>)
+function, in which most of the code was identical from widget to widget.
+In the Intrinsics, a single generic
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+performs most of the common work and then calls the initialize procedure
+implemented for the particular widget class.
+</para>
+
+<para>
+Each Composite class also implemented the procedures
+Xt&lt;<emphasis remap='I'>Widget</emphasis>&gt;Add and an Xt&lt;<emphasis remap='I'>Widget</emphasis>&gt;Delete (for example,
+<function>XtButtonBoxAddButton</function>
+and
+<function>XtButtonBoxDeleteButton</function>).
+In the Intrinsics, the Composite generic procedures
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>
+and
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+Old-style calls can be implemented in the X Toolkit by defining
+one-line procedures or macros that invoke a generic routine. For example,
+you could define the macro
+<function>XtLabelCreate</function>
+as:
+</para>
+
+<literallayout>
+#define XtLabelCreate(name, parent, args, num_args) \
+ ((LabelWidget) XtCreateWidget(name, labelWidgetClass, parent, args, num_args))
+</literallayout>
+
+<para>
+Pop-up shells in some of the prototypes automatically performed an
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+on their child within their insert_child procedure.
+Creators of pop-up children need to call
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+themselves.
+</para>
+
+<para>
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
+and
+<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>
+have been replaced by
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+and
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To initialize the Intrinsics internals, create an application context,
+open and initialize a display, and create the initial application shell
+instance, an application may use
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
+or
+<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppInitialize'>
+<funcprototype>
+<funcdef>Widget <function>XtAppInitialize</function></funcdef>
+ <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int *<parameter>argc_in_out</parameter></paramdef>
+ <paramdef>String *<parameter>argv_in_out</parameter></paramdef>
+ <paramdef>String *<parameter>fallback_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line options table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the application class resource
+file cannot be opened or read, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any
+other resource specifications for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
+function calls
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+followed by
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+then calls
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+with <emphasis remap='I'>display_string</emphasis> NULL and
+<emphasis remap='I'>application_name</emphasis> NULL, and finally calls
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with <emphasis remap='I'>application_name</emphasis> NULL, <emphasis remap='I'>widget_class</emphasis>
+<function>application\%Shell\%Widget\%Class</function>,
+and the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
+and returns the created shell. The modified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> returned by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+are returned in <emphasis remap='I'>argc_in_out</emphasis> and <emphasis remap='I'>argv_in_out</emphasis>. If
+<emphasis remap='I'>app_context_return</emphasis> 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
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
+terminates the application. If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL,
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is called with the value prior to calling
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaAppInitialize'>
+<funcprototype>
+<funcdef>Widget <function>XtVaAppInitialize</function></funcdef>
+ <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int *<parameter>argc_in_out</parameter></paramdef>
+ <paramdef>String *<parameter>argv_in_out</parameter></paramdef>
+ <paramdef>String *<parameter>fallback_resources</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line options table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line arguments array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the application class
+resource file cannot be opened, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+</para>
+
+<para>
+As a convenience to people converting from earlier versions of the toolkit
+without application contexts, the following routines exist:
+<xref linkend='XtInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtMainLoop' xrefstyle='select: title'/>,
+<xref linkend='XtNextEvent' xrefstyle='select: title'/>,
+<xref linkend='XtProcessEvent' xrefstyle='select: title'/>,
+<xref linkend='XtPeekEvent' xrefstyle='select: title'/>,
+<xref linkend='XtPending' xrefstyle='select: title'/>,
+<xref linkend='XtAddInput' xrefstyle='select: title'/>,
+<xref linkend='XtAddTimeOut' xrefstyle='select: title'/>,
+<xref linkend='XtAddWorkProc' xrefstyle='select: title'/>,
+<xref linkend='XtCreateApplicationShell' xrefstyle='select: title'/>,
+<xref linkend='XtAddActions' xrefstyle='select: title'/>,
+<xref linkend='XtSetSelectionTimeout' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInitialize'>
+<funcprototype>
+<funcdef>Widget <function>XtInitialize</function></funcdef>
+ <paramdef>String <parameter>shell_name</parameter></paramdef>
+ <paramdef>String <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescRec <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int *<parameter>argc</parameter></paramdef>
+ <paramdef>String <parameter>argv</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>shell_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+This parameter is ignored; therefore, you can specify NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of this application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to parse the command line for any application-specific resources.
+The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to
+<function>XrmParseCommand</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the options list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+calls
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+to initialize the toolkit internals,
+creates a default application context for use by the other convenience
+routines, calls
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+with <emphasis remap='I'>display_string</emphasis> NULL and <emphasis remap='I'>application_name</emphasis> NULL, and
+finally calls
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with <emphasis remap='I'>application_name</emphasis> NULL and
+returns the created shell.
+The semantics of calling
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+more than once are undefined.
+This routine has been replaced by
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMainLoop'>
+<funcprototype>
+<funcdef>void <function>XtMainLoop</function></funcdef>
+ <paramdef><parameter>void</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<xref linkend='XtMainLoop' xrefstyle='select: title'/>
+first reads the next alternate input, timer, or X event by calling
+<xref linkend='XtNextEvent' xrefstyle='select: title'/>.
+Then it dispatches this to the appropriate registered procedure by calling
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+This routine has been replaced by
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNextEvent'>
+<funcprototype>
+<funcdef>void <function>XtNextEvent</function></funcdef>
+ <paramdef>XEvent *<parameter>event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the event information to the specified event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If no input is on the X input queue for the default application context,
+<xref linkend='XtNextEvent' xrefstyle='select: title'/>
+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
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<funcsynopsis id='XtProcessEvent'>
+<funcprototype>
+<funcdef>void <function>XtProcessEvent</function></funcdef>
+ <paramdef>XtInputMask <parameter>mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of input to process.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtProcessEvent' xrefstyle='select: title'/>
+processes one X event, timeout, or alternate input source
+(depending on the value of <emphasis remap='I'>mask</emphasis>), blocking if necessary.
+It has been replaced by
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this function.
+</para>
+
+<funcsynopsis id='XtPeekEvent'>
+<funcprototype>
+<funcdef>Boolean <function>XtPeekEvent</function></funcdef>
+ <paramdef>XEvent *<parameter>event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the event information to the specified event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is an event in the queue for the default application context,
+<xref linkend='XtPeekEvent' xrefstyle='select: title'/>
+fills in the event and returns a nonzero value.
+If no X input is on the queue,
+<xref linkend='XtPeekEvent' xrefstyle='select: title'/>
+flushes the output buffer and blocks until input is available, possibly
+calling some timeout callbacks in the process.
+If the input is an event,
+<xref linkend='XtPeekEvent' xrefstyle='select: title'/>
+fills in the event and returns a nonzero value.
+Otherwise, the input is for an alternate input source, and
+<xref linkend='XtPeekEvent' xrefstyle='select: title'/>
+returns zero.
+This routine has been replaced by
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<funcsynopsis id='XtPending'>
+<funcprototype>
+<funcdef>Boolean <function>XtPending</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<xref linkend='XtPending' xrefstyle='select: title'/>
+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
+<xref linkend='XtAppPending' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<funcsynopsis id='XtAddInput'>
+<funcprototype>
+<funcdef>XtInputId <function>XtAddInput</function></funcdef>
+ <paramdef>int <parameter>source</parameter></paramdef>
+ <paramdef>XtPointer <parameter>condition</parameter></paramdef>
+ <paramdef>XtInputCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source file descriptor on a POSIX-based system
+or other operating-system-dependent device specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>condition</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mask that indicates either a read, write, or exception condition
+or some operating-system-dependent condition.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure called when input is available.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parameter to be passed to <emphasis remap='I'>proc</emphasis> when input is available.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddInput' xrefstyle='select: title'/>
+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 <emphasis remap='I'>file</emphasis> should be loosely interpreted to mean any sink
+or source of data.)
+<xref linkend='XtAddInput' xrefstyle='select: title'/>
+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
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<funcsynopsis id='XtAddTimeOut'>
+<funcprototype>
+<funcdef>XtIntervalId <function>XtAddTimeOut</function></funcdef>
+ <paramdef>unsigned long <parameter>interval</parameter></paramdef>
+ <paramdef>XtTimerCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>interval</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time interval in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when time expires.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parameter to be passed to <emphasis remap='I'>proc</emphasis> when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddTimeOut' xrefstyle='select: title'/>
+function creates a timeout in the default application context
+and returns an identifier for it.
+The timeout value is set to <emphasis remap='I'>interval</emphasis>.
+The callback procedure will be called after
+the time interval elapses, after which the timeout is removed.
+This routine has been replaced by
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<funcsynopsis id='XtAddWorkProc'>
+<funcprototype>
+<funcdef>XtWorkProcId <function>XtAddWorkProc</function></funcdef>
+ <paramdef>XtWorkProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Procedure to call to do the work.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Client data to pass to <emphasis remap='I'>proc</emphasis> when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This routine registers a work procedure in the default application context. It has
+been replaced by
+<xref linkend='XtAppAddWorkProc' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<funcsynopsis id='XtCreateApplicationShell'>
+<funcprototype>
+<funcdef>Widget <function>XtCreateApplicationShell</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+This parameter is ignored; therefore, you can specify NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created application shell widget.
+This will usually be
+<function>topLevelShellWidgetClass</function>
+or a subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The procedure
+<xref linkend='XtCreateApplicationShell' xrefstyle='select: title'/>
+calls
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with <emphasis remap='I'>application_name</emphasis> NULL, the application class passed to
+<xref linkend='XtInitialize' xrefstyle='select: title'/>,
+and the default application context created by
+<xref linkend='XtInitialize' xrefstyle='select: title'/>.
+This routine has been replaced by
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>.
+</para>
+
+<para>
+An old-format resource type converter procedure pointer is of type
+<xref linkend='XtConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConverter'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtConverter)</function></funcdef>
+
+ <paramdef>XrmValue *<parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>from</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>to</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of additional
+<function>XrmValue</function>
+arguments to the converter if additional context is needed
+to perform the conversion, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the descriptor to use to return the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Type converters should perform the following actions:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Check to see that the number of arguments passed is correct.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Attempt the type conversion.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If successful, return the size and pointer to the data in the <emphasis remap='I'>to</emphasis> argument;
+otherwise, call
+<xref linkend='XtWarningMsg' xrefstyle='select: title'/>
+and return without modifying the <emphasis remap='I'>to</emphasis> argument.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Most type converters just take the data described by the specified <emphasis remap='I'>from</emphasis>
+argument and return data by writing into the specified <emphasis remap='I'>to</emphasis> 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.
+</para>
+
+<para>
+Note that the address returned in <emphasis remap='I'>to-&gt;addr</emphasis> 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.
+</para>
+
+<para>
+The procedure type
+<xref linkend='XtConverter' xrefstyle='select: title'/>
+has been replaced by
+<xref linkend='XtTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The
+<xref linkend='XtStringConversionWarning' xrefstyle='select: title'/>
+function is a convenience routine for old-format resource converters
+that convert from strings.
+</para>
+
+<funcsynopsis id='XtStringConversionWarning'>
+<funcprototype>
+<funcdef>void <function>XtStringConversionWarning</function></funcdef>
+ <paramdef>String <parameter>src</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>src</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string that could not be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dst_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the type to which the string could not be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtStringConversionWarning' xrefstyle='select: title'/>
+function issues a warning message with name "conversionError",
+type "string", class "XtToolkitError, and the default message string
+"Cannot convert "<emphasis remap='I'>src</emphasis>" to type <emphasis remap='I'>dst_type</emphasis>". This routine
+has been superseded by
+<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register an old-format converter, use
+<xref linkend='XtAddConverter' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppAddConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddConverter'>
+<funcprototype>
+<funcdef>void <function>XtAddConverter</function></funcdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XtConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type converter procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to compute the additional arguments to the converter, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAddConverter' xrefstyle='select: title'/>
+is equivalent in function to
+<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>
+with <emphasis remap='I'>cache_type</emphasis> equal to
+<function>XtCacheAll</function>
+for old-format type converters. It has been superseded by
+<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddConverter'>
+<funcprototype>
+<funcdef>void <function>XtAppAddConverter</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XtConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type converter procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to compute the additional arguments to the converter, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppAddConverter' xrefstyle='select: title'/>
+is equivalent in function to
+<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>
+with <emphasis remap='I'>cache_type</emphasis> equal to
+<function>XtCacheAll</function>
+for old-format type converters. It has been superseded by
+<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To invoke resource conversions, a client may use
+<xref linkend='XtConvert' xrefstyle='select: title'/>
+or, for old-format converters only,
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvert'>
+<funcprototype>
+<funcdef>void <function>XtConvert</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to use for additional arguments, if any are
+needed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<funcsynopsis id='XtDirectConvert'>
+<funcprototype>
+<funcdef>void <function>XtDirectConvert</function></funcdef>
+ <paramdef>XtConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list that contains the additional arguments
+needed to perform the conversion (often NULL).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConvert' xrefstyle='select: title'/>
+function looks up the type converter registered to convert <emphasis remap='I'>from_type</emphasis>
+to <emphasis remap='I'>to_type</emphasis>, computes any additional arguments needed, and then calls
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>
+or
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>.
+The
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>
+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.
+</para>
+
+<para>
+Before calling the specified converter,
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>
+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 <emphasis remap='I'>to_return.addr</emphasis> for non-NULL.
+The data returned by
+<xref linkend='XtConvert' xrefstyle='select: title'/>
+must be copied immediately by the caller,
+as it may point to static data in the type converter.
+</para>
+
+<para>
+<xref linkend='XtConvert' xrefstyle='select: title'/>
+has been replaced by
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>,
+and
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>
+has been superseded by
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To deallocate a shared GC when it is no longer needed, use
+<xref linkend='XtDestroyGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDestroyGC'>
+<funcprototype>
+<funcdef>void <function>XtDestroyGC</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>GC <parameter>gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any object on the display for which the shared GC was
+created. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shared GC to be deallocated.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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
+<xref linkend='XtDestroyGC' xrefstyle='select: title'/>
+had only a <emphasis remap='I'>gc</emphasis> argument.
+Therefore, this function is not very portable,
+and you are encouraged to use
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
+instead.
+</para>
+
+<para>
+To declare an action table in the default application context
+and register it with the translation manager, use
+<xref linkend='XtAddActions' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddActions'>
+<funcprototype>
+<funcdef>void <function>XtAddActions</function></funcdef>
+ <paramdef>XtActionList <parameter>actions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_actions</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action table to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_actions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>actions</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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 Intrinsics register an action table for
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+and
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+as part of X Toolkit initialization.
+This routine has been replaced by
+<xref linkend='XtAppAddActions' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<para>
+To set the Intrinsics selection timeout in the default application context, use
+<xref linkend='XtSetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetSelectionTimeout'>
+<funcprototype>
+<funcdef>void <function>XtSetSelectionTimeout</function></funcdef>
+ <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timeout</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection timeout in milliseconds.
+This routine has been replaced by
+<xref linkend='XtAppSetSelectionTimeout' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+To get the current selection timeout value in the default application
+context, use
+<xref linkend='XtGetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionTimeout'>
+<funcprototype>
+<funcdef>unsigned long <function>XtGetSelectionTimeout</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+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 Intrinsics abort the selection request.
+</para>
+
+<para>
+This routine has been replaced by
+<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>.
+<xref linkend='XtInitialize' xrefstyle='select: title'/>
+must be called before using this routine.
+</para>
+
+<para>
+To obtain the global error database (for example, to merge with
+an application- or widget-specific database), use
+<xref linkend='XtGetErrorDatabase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetErrorDatabase'>
+<funcprototype>
+<funcdef>XrmDatabase <function>*XtGetErrorDatabase</function></funcdef>
+ <paramdef><parameter></parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+The
+<xref linkend='XtGetErrorDatabase' xrefstyle='select: title'/>
+function returns the address of the error database.
+The Intrinsics do a lazy binding of the error database and do not merge in the
+database file until the first call to
+<function>XtGetErrorDatbaseText</function>.
+This routine has been replaced by
+<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>.
+</para>
+
+<para>
+An error message handler can obtain the error database text for an
+error or a warning by calling
+<xref linkend='XtGetErrorDatabaseText' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetErrorDatabaseText'>
+<funcprototype>
+<funcdef>void <function>XtGetErrorDatabaseText</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>default</parameter></paramdef>
+ <paramdef>String <parameter>buffer_return</parameter></paramdef>
+ <paramdef>int <parameter>nbytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the name and type that are concatenated to form the resource name
+of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer into which the error message is to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer in bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetErrorDatabaseText' xrefstyle='select: title'/>
+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 <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>type</emphasis> are concatenated with a single "."
+between them and the <emphasis remap='I'>class</emphasis> is concatenated with itself with a
+single "." if it does not already contain a ".".
+This routine has been superseded by
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register a procedure to be called on fatal error conditions, use
+<xref linkend='XtSetErrorMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetErrorMsgHandler'>
+<funcprototype>
+<funcdef>void <function>XtSetErrorMsgHandler</function></funcdef>
+ <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>msg_handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new fatal error procedure, which should not return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The default error handler provided by the Intrinsics constructs a
+string from the error resource database and calls
+<xref linkend='XtError' xrefstyle='select: title'/>.
+Fatal error message handlers should not return.
+If one does,
+subsequent Intrinsics behavior is undefined.
+This routine has been superseded by
+<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To call the high-level error handler, use
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtErrorMsg'>
+<funcprototype>
+<funcdef>void <function>XtErrorMsg</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>String <parameter>default</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the general kind of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the detailed name of the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of values to be stored in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This routine has been superseded by
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register a procedure to be called on nonfatal error conditions, use
+<xref linkend='XtSetWarningMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetWarningMsgHandler'>
+<funcprototype>
+<funcdef>void <function>XtSetWarningMsgHandler</function></funcdef>
+ <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>msg_handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new nonfatal error procedure, which usually returns.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The default warning handler provided by the Intrinsics constructs a string
+from the error resource database and calls
+<xref linkend='XtWarning' xrefstyle='select: title'/>.
+This routine has been superseded by
+<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To call the installed high-level warning handler, use
+<xref linkend='XtWarningMsg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWarningMsg'>
+<funcprototype>
+<funcdef>void <function>XtWarningMsg</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>String <parameter>default</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the general kind of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the detailed name of the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of values to be stored in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This routine has been superseded by
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register a procedure to be called on fatal error conditions, use
+<xref linkend='XtSetErrorHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetErrorHandler'>
+<funcprototype>
+<funcdef>void <function>XtSetErrorHandler</function></funcdef>
+ <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new fatal error procedure, which should not return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The default error handler provided by the Intrinsics is
+<function>_XtError</function>.
+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 X Toolkit behavior is undefined.
+This routine has been superseded by
+<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To call the installed fatal error procedure, use
+<xref linkend='XtError' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtError'>
+<funcprototype>
+<funcdef>void <function>XtError</function></funcdef>
+ <paramdef>String <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the message to be reported.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most programs should use
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>,
+not
+<xref linkend='XtError' xrefstyle='select: title'/>,
+to provide for customization and internationalization of error
+messages. This routine has been superseded by
+<xref linkend='XtAppError' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register a procedure to be called on nonfatal error conditions, use
+<xref linkend='XtSetWarningHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetWarningHandler'>
+<funcprototype>
+<funcdef>void <function>XtSetWarningHandler</function></funcdef>
+ <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new nonfatal error procedure, which usually returns.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The default warning handler provided by the Intrinsics is
+<function>_XtWarning</function>.
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+This routine has been superseded by
+<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To call the installed nonfatal error procedure, use
+<xref linkend='XtWarning' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWarning'>
+<funcprototype>
+<funcdef>void <function>XtWarning</function></funcdef>
+ <paramdef>String <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the nonfatal error message to be reported.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most programs should use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>,
+not
+<xref linkend='XtWarning' xrefstyle='select: title'/>,
+to provide for customization and internationalization of warning messages.
+This routine has been superseded by
+<xref linkend='XtAppWarning' xrefstyle='select: title'/>.
+</para>
+</appendix>
diff --git a/specs/appD.xml b/specs/appD.xml
new file mode 100644
index 0000000..00acbe7
--- /dev/null
+++ b/specs/appD.xml
@@ -0,0 +1,880 @@
+<appendix id='Intrinsics_Error_Messages'>
+<title>Intrinsics Error Messages</title>
+
+<para>
+All Intrinsics errors and warnings have class
+``XtToolkitError''.
+The following two tables summarize the common errors and warnings that can be
+generated by the Intrinsics.
+Additional implementation-dependent messages are permitted.
+Error Messages
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Default Message</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>allocError</entry>
+ <entry>calloc</entry>
+ <entry>Cannot perform calloc</entry>
+ </row>
+ <row>
+ <entry>allocError</entry>
+ <entry>malloc</entry>
+ <entry>Cannot perform malloc</entry>
+ </row>
+ <row>
+ <entry>allocError</entry>
+ <entry>realloc</entry>
+ <entry>Cannot perform realloc</entry>
+ </row>
+ <row>
+ <entry>internalError</entry>
+ <entry>xtMakeGeometryRequest</entry>
+ <entry>internal error; ShellClassExtension is NULL</entry>
+ </row>
+ <row>
+ <entry>invalidArgCount</entry>
+ <entry>xtGetValues</entry>
+ <entry>Argument count &gt; 0 on NULL argument list in XtGetValues</entry>
+ </row>
+ <row>
+ <entry>invalidArgCount</entry>
+ <entry>xtSetValues</entry>
+ <entry>Argument count &gt; 0 on NULL argument list in XtSetValues</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>applicationShellInsertChild</entry>
+ <entry>ApplicationShell does not accept RectObj children; ignored</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>constraintSetValue</entry>
+ <entry>Subclass of Constraint required in CallConstraintSetValues</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>xtAppCreateShell</entry>
+ <entry>XtAppCreateShell requires non-NULL widget class</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>xtCreatePopupShell</entry>
+ <entry>XtCreatePopupShell requires non-NULL widget class</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>xtCreateWidget</entry>
+ <entry>XtCreateWidget requires non-NULL widget class</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>xtPopdown</entry>
+ <entry>XtPopdown requires a subclass of shellWidgetClass</entry>
+ </row>
+ <row>
+ <entry>invalidClass</entry>
+ <entry>xtPopup</entry>
+ <entry>XtPopup requires a subclass of shellWidgetClass</entry>
+ </row>
+ <row>
+ <entry>invalidDimension</entry>
+ <entry>xtCreateWindow</entry>
+ <entry>Widget %s has zero width and/or height</entry>
+ </row>
+ <row>
+ <entry>invalidDimension</entry>
+ <entry>shellRealize</entry>
+ <entry>Shell widget %s has zero width and/or height</entry>
+ </row>
+ <row>
+ <entry>invalidDisplay</entry>
+ <entry>xtInitialize</entry>
+ <entry>Can't open display: %s</entry>
+ </row>
+ <row>
+ <entry>invalidGetValues</entry>
+ <entry>xtGetValues</entry>
+ <entry>NULL ArgVal in XtGetValues</entry>
+ </row>
+ <row>
+ <entry>invalidExtension</entry>
+ <entry>shellClassPartInitialize</entry>
+ <entry>widget class %s has invalid ShellClassExtension record</entry>
+ </row>
+ <row>
+ <entry>invalidExtension</entry>
+ <entry>xtMakeGeometryRequest</entry>
+ <entry>widget class %s has invalid ShellClassExtension record</entry>
+ </row>
+ <row>
+ <entry>invalidGeometryManager</entry>
+ <entry>xtMakeGeometryRequest</entry>
+ <entry>XtMakeGeometryRequest - parent has no geometry manager</entry>
+ </row>
+ <row>
+ <entry>invalidParameter</entry>
+ <entry>xtAddInput</entry>
+ <entry>invalid condition passed to XtAddInput</entry>
+ </row>
+ <row>
+ <entry>invalidParameter</entry>
+ <entry>xtAddInput</entry>
+ <entry>invalid condition passed to XtAppAddInput</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtChangeManagedSet</entry>
+ <entry>Attempt to manage a child when parent is not Composite</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtChangeManagedSet</entry>
+ <entry>Attempt to unmanage a child when parent is not Composite</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtCreatePopupShell</entry>
+ <entry>XtCreatePopupShell requires non-NULL parent</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtCreateWidget</entry>
+ <entry>XtCreateWidget requires non-NULL parent</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtMakeGeometryRequest</entry>
+ <entry>non-shell has no parent in XtMakeGeometryRequest</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtMakeGeometryRequest</entry>
+ <entry>XtMakeGeometryRequest - parent not composite</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtManageChildren</entry>
+ <entry>Attempt to manage a child when parent is not Composite</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtUnmanageChildren</entry>
+ <entry>Attempt to unmanage a child when parent is not Composite</entry>
+ </row>
+ <row>
+ <entry>invalidProcedure</entry>
+ <entry>inheritanceProc</entry>
+ <entry>Unresolved inheritance operation</entry>
+ </row>
+ <row>
+ <entry>invalidProcedure</entry>
+ <entry>realizeProc</entry>
+ <entry>No realize class procedure defined</entry>
+ </row>
+ <row>
+ <entry>invalidWindow</entry>
+ <entry>eventHandler</entry>
+ <entry>Event with wrong window</entry>
+ </row>
+ <row>
+ <entry>missingWidget</entry>
+ <entry>fetchDisplayArg</entry>
+ <entry>FetchDisplayArg called without a widget to reference</entry>
+ </row>
+ <row>
+ <entry>nonWidget</entry>
+ <entry>xtCreateWidget</entry>
+ <entry>attempt to add non-widget child "%s" to parent "%s" which supports only widgets</entry>
+ </row>
+ <row>
+ <entry>noPerDisplay</entry>
+ <entry>closeDisplay</entry>
+ <entry>Couldn't find per display information</entry>
+ </row>
+ <row>
+ <entry>noPerDisplay</entry>
+ <entry>getPerDisplay</entry>
+ <entry>Couldn't find per display information</entry>
+ </row>
+ <row>
+ <entry>noSelectionProperties</entry>
+ <entry>freeSelectionProperty</entry>
+ <entry>internal error: no selection property context for display</entry>
+ </row>
+ <row>
+ <entry>noWidgetAncestor</entry>
+ <entry>windowedAncestor</entry>
+ <entry>Object "%s" does not have windowed ancestor</entry>
+ </row>
+ <row>
+ <entry>nullDisplay</entry>
+ <entry>xtRegisterExtensionSelector</entry>
+ <entry>XtRegisterExtensionSelector requires a non-NULL display</entry>
+ </row>
+ <row>
+ <entry>nullProc</entry>
+ <entry>insertChild</entry>
+ <entry>"%s" parent has NULL insert_child method</entry>
+ </row>
+ <row>
+ <entry>r2versionMismatch</entry>
+ <entry>widget</entry>
+ <entry>Widget class %s must be re-compiled.</entry>
+ </row>
+ <row>
+ <entry>R3versionMismatch</entry>
+ <entry>widget</entry>
+ <entry>Widget class %s must be re-compiled.</entry>
+ </row>
+ <row>
+ <entry>R4orR5versionMismatch</entry>
+ <entry>widget</entry>
+ <entry>Widget class %s must be re-compiled.</entry>
+ </row>
+ <row>
+ <entry>rangeError</entry>
+ <entry>xtRegisterExtensionSelector</entry>
+ <entry>Attempt to register multiple selectors for one extension event type</entry>
+ </row>
+ <row>
+ <entry>sessionManagement</entry>
+ <entry>SmcOpenConnection</entry>
+ <entry>Tried to connect to session manager, %s</entry>
+ </row>
+ <row>
+ <entry>subclassMismatch</entry>
+ <entry>xtCheckSubclass</entry>
+ <entry>Widget class %s found when subclass of %s expected: %s</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Warning Messages</emphasis></para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Default Message</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ambiguousParent</entry>
+ <entry>xtChangeManagedSet</entry>
+ <entry>Not all children have same parent</entry>
+ </row>
+ <row>
+ <entry>ambiguousParent</entry>
+ <entry>xtManageChildren</entry>
+ <entry>Not all children have same parent in XtManageChildren</entry>
+ </row>
+ <row>
+ <entry>ambiguousParent</entry>
+ <entry>xtUnmanageChildren</entry>
+ <entry>Not all children have same parent in XtUnmanageChildren</entry>
+ </row>
+ <row>
+ <entry>badFormat</entry>
+ <entry>xtGetSelectionValue</entry>
+ <entry>Selection owner returned type INCR property with format != 32</entry>
+ </row>
+ <row>
+ <entry>badGeometry</entry>
+ <entry>shellRealize</entry>
+ <entry>Shell widget "%s" has an invalid geometry specification: "%s"</entry>
+ </row>
+ <row>
+ <entry>badValue</entry>
+ <entry>cvtStringToPixel</entry>
+ <entry>Color name "%s" is not defined</entry>
+ </row>
+ <row>
+ <entry>communicationError</entry>
+ <entry>select</entry>
+ <entry>Select failed; error code %s</entry>
+ </row>
+ <row>
+ <entry>conversionError</entry>
+ <entry>string</entry>
+ <entry>Cannot convert string "%s" to type %s</entry>
+ </row>
+ <row>
+ <entry>conversionError</entry>
+ <entry>stringToVisual</entry>
+ <entry>Cannot find Visual of class %s for display %s</entry>
+ </row>
+ <row>
+ <entry>conversionFailed</entry>
+ <entry>xtConvertVarToArgList</entry>
+ <entry>Type conversion failed</entry>
+ </row>
+ <row>
+ <entry>conversionFailed</entry>
+ <entry>xtGetTypedArg</entry>
+ <entry>Type conversion (%s to %s) failed for widget '%s'</entry>
+ </row>
+ <row>
+ <entry>displayError</entry>
+ <entry>invalidDisplay</entry>
+ <entry>Can't find display structure</entry>
+ </row>
+ <row>
+ <entry>grabError</entry>
+ <entry>xtAddGrab</entry>
+ <entry>XtAddGrab requires exclusive grab if spring_loaded is TRUE</entry>
+ </row>
+ <row>
+ <entry>grabError</entry>
+ <entry>xtRemoveGrab</entry>
+ <entry>XtRemoveGrab asked to remove a widget not on the list</entry>
+ </row>
+ <row>
+ <entry>initializationError</entry>
+ <entry>xtInitialize</entry>
+ <entry>Initializing Resource Lists twice</entry>
+ </row>
+ <row>
+ <entry>insufficientSpace</entry>
+ <entry>xtGetTypedArg</entry>
+ <entry>Insufficient space for converted type '%s' in widget '%s'</entry>
+ </row>
+ <row>
+ <entry>internalError</entry>
+ <entry>shell</entry>
+ <entry>Shell's window manager interaction is broken</entry>
+ </row>
+ <row>
+ <entry>invalidAddressMode</entry>
+ <entry>computeArgs</entry>
+ <entry>Conversion arguments for widget '%s' contain an unsupported address mode</entry>
+ </row>
+ <row>
+ <entry>invalidArgCount</entry>
+ <entry>getResources</entry>
+ <entry>argument count &gt; 0 on NULL argument list</entry>
+ </row>
+ <row>
+ <entry>invalidCallbackList</entry>
+ <entry>xtAddCallback</entry>
+ <entry>Cannot find callback list in XtAddCallback</entry>
+ </row>
+ <row>
+ <entry>invalidCallbackList</entry>
+ <entry>xtAddCallback</entry>
+ <entry>Cannot find callback list in XtAddCallbacks</entry>
+ </row>
+ <row>
+ <entry>invalidCallbackList</entry>
+ <entry>xtCallCallback</entry>
+ <entry>Cannot find callback list in XtCallCallbacks</entry>
+ </row>
+ <row>
+ <entry>invalidCallbackList</entry>
+ <entry>xtRemoveAllCallback</entry>
+ <entry>Cannot find callback list in XtRemoveAllCallbacks</entry>
+ </row>
+ <row>
+ <entry>invalidCallbackList</entry>
+ <entry>xtRemoveCallback</entry>
+ <entry>Cannot find callback list in XtRemoveCallbacks</entry>
+ </row>
+ <row>
+ <entry>invalidChild</entry>
+ <entry>xtChangeManagedSet</entry>
+ <entry>Null child passed to UnmanageChildren</entry>
+ </row>
+ <row>
+ <entry>invalidChild</entry>
+ <entry>xtManageChildren</entry>
+ <entry>null child passed to ManageChildren</entry>
+ </row>
+ <row>
+ <entry>invalidChild</entry>
+ <entry>xtManageChildren</entry>
+ <entry>null child passed to XtManageChildren</entry>
+ </row>
+ <row>
+ <entry>invalidChild</entry>
+ <entry>xtUnmanageChildren</entry>
+ <entry>Null child passed to XtUnmanageChildren</entry>
+ </row>
+ <row>
+ <entry>invalidChild</entry>
+ <entry>xtUnmanageChildren</entry>
+ <entry>Null child found in argument list to unmanage</entry>
+ </row>
+ <row>
+ <entry>invalidDepth</entry>
+ <entry>setValues</entry>
+ <entry>Can't change widget depth</entry>
+ </row>
+ <row>
+ <entry>invalidExtension</entry>
+ <entry>xtCreateWidget</entry>
+ <entry>widget "%s" class %s has invalid CompositeClassExtension record</entry>
+ </row>
+ <row>
+ <entry>invalidExtension</entry>
+ <entry>xtCreateWidget</entry>
+ <entry>widget class %s has invalid ConstraintClassExtension record</entry>
+ </row>
+ <row>
+ <entry>invalidGrab</entry>
+ <entry>ungrabKeyOrButton</entry>
+ <entry>Attempt to remove nonexistent passive grab</entry>
+ </row>
+ <row>
+ <entry>invalidGrabKind</entry>
+ <entry>xtPopup</entry>
+ <entry>grab kind argument has invalid value; XtGrabNone assumed</entry>
+ </row>
+ <row>
+ <entry>invalidParameters</entry>
+ <entry>freeTranslations</entry>
+ <entry>Freeing XtTranslations requires no extra arguments</entry>
+ </row>
+ <row>
+ <entry>invalidParameters</entry>
+ <entry>mergeTranslations</entry>
+ <entry>MergeTM to TranslationTable needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>invalidParameters</entry>
+ <entry>xtMenuPopdown</entry>
+ <entry>XtMenuPopdown called with num_params != 0 or 1</entry>
+ </row>
+ <row>
+ <entry>invalidParameters</entry>
+ <entry>xtMenuPopupAction</entry>
+ <entry>MenuPopup wants exactly one argument</entry>
+ </row>
+ <row>
+ <entry>invalidParent</entry>
+ <entry>xtCopyFromParent</entry>
+ <entry>CopyFromParent must have non-NULL parent</entry>
+ </row>
+ <row>
+ <entry>invalidPopup</entry>
+ <entry>xtMenuPopup</entry>
+ <entry>Can't find popup widget "%s" in XtMenuPopup</entry>
+ </row>
+ <row>
+ <entry>invalidPopup</entry>
+ <entry>xtMenuPopdown</entry>
+ <entry>Can't find popup in widget "%s" in XtMenuPopdown</entry>
+ </row>
+ <row>
+ <entry>invalidPopup</entry>
+ <entry>unsupportedOperation</entry>
+ <entry>Pop-up menu creation is only supported on ButtonPress, KeyPress or EnterNotify events.</entry>
+ </row>
+ <row>
+ <entry>invalidPopup</entry>
+ <entry>unsupportedOperation</entry>
+ <entry>Pop-up menu creation is only supported on Button, Key or EnterNotify events.</entry>
+ </row>
+ <row>
+ <entry>invalidProcedure</entry>
+ <entry>deleteChild</entry>
+ <entry>null delete_child procedure for class %s in XtDestroy</entry>
+ </row>
+ <row>
+ <entry>invalidProcedure</entry>
+ <entry>inputHandler</entry>
+ <entry>XtRemoveInput: Input handler not found</entry>
+ </row>
+ <row>
+ <entry>invalidProcedure</entry>
+ <entry>set_values_almost</entry>
+ <entry>set_values_almost procedure shouldn't be NULL</entry>
+ </row>
+ <row>
+ <entry>invalidResourceCount</entry>
+ <entry>getResources</entry>
+ <entry>resource count &gt; 0 on NULL resource list</entry>
+ </row>
+ <row>
+ <entry>invalidResourceName</entry>
+ <entry>computeArgs</entry>
+ <entry>Cannot find resource name %s as argument to conversion</entry>
+ </row>
+ <row>
+ <entry>invalidShell</entry>
+ <entry>xtTranslateCoords</entry>
+ <entry>Widget has no shell ancestor</entry>
+ </row>
+ <row>
+ <entry>invalidSizeOverride</entry>
+ <entry>xtDependencies</entry>
+ <entry>Representation size %d must match superclass's to override %s</entry>
+ </row>
+ <row>
+ <entry>missingCharsetList</entry>
+ <entry>cvtStringToFontSet</entry>
+ <entry>Missing charsets in String to FontSet conversion</entry>
+ </row>
+ <row>
+ <entry>noActionProc</entry>
+ <entry>xtCallActionProc</entry>
+ <entry>No action proc named "%s" is registered for widget "%s"</entry>
+ </row>
+ <row>
+ <entry>noColormap</entry>
+ <entry>cvtStringToPixel</entry>
+ <entry>Cannot allocate colormap entry for "%s"</entry>
+ </row>
+ <row>
+ <entry>noFont</entry>
+ <entry>cvtStringToFont</entry>
+ <entry>Unable to load any usable ISO8859-1 font</entry>
+ </row>
+ <row>
+ <entry>noFont</entry>
+ <entry>cvtStringToFontSet</entry>
+ <entry>Unable to load any usable fontset</entry>
+ </row>
+ <row>
+ <entry>noFont</entry>
+ <entry>cvtStringToFontStruct</entry>
+ <entry>Unable to load any usable ISO8859-1 font</entry>
+ </row>
+ <row>
+ <entry>notInConvertSelection</entry>
+ <entry>xtGetSelectionRequest</entry>
+ <entry>XtGetSelectionRequest or XtGetSelectionParameters called for widget "%s" outside of ConvertSelection proc</entry>
+ </row>
+ <row>
+ <entry>notRectObj</entry>
+ <entry>xtChangeManagedSet</entry>
+ <entry>child "%s", class %s is not a RectObj</entry>
+ </row>
+ <row>
+ <entry>notRectObj</entry>
+ <entry>xtManageChildren</entry>
+ <entry>child "%s", class %s is not a RectObj</entry>
+ </row>
+ <row>
+ <entry>nullWidget</entry>
+ <entry>xtConvertVarToArgList</entry>
+ <entry>XtVaTypedArg conversion needs non-NULL widget handle</entry>
+ </row>
+ <row>
+ <entry>r3versionMismatch</entry>
+ <entry>widget</entry>
+ <entry>Shell Widget class %s binary compiled for R3</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>nullTable</entry>
+ <entry>Can't remove accelerators from NULL table</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>nullTable</entry>
+ <entry>Tried to remove nonexistent accelerators</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>ambiguousActions</entry>
+ <entry>Overriding earlier translation manager actions.</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>newActions</entry>
+ <entry>New actions are:%s</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>nullTable</entry>
+ <entry>table to (un)merge must not be null</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>nullTable</entry>
+ <entry>Can't translate event through NULL table</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>oldActions</entry>
+ <entry>Previous entry was: %s %s</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>unboundActions</entry>
+ <entry>Actions not found: %s</entry>
+ </row>
+ <row>
+ <entry>translationError</entry>
+ <entry>xtTranslateInitialize</entry>
+ <entry>Initializing Translation manager twice.</entry>
+ </row>
+ <row>
+ <entry>translationParseError</entry>
+ <entry>missingComma</entry>
+ <entry> ... possibly due to missing ',' in event sequence.</entry>
+ </row>
+ <row>
+ <entry>translationParseError</entry>
+ <entry>nonLatin1</entry>
+ <entry> ... probably due to non-Latin1 character in quoted string</entry>
+ </row>
+ <row>
+ <entry>translationParseError</entry>
+ <entry>parseError</entry>
+ <entry>translation table syntax error: %s</entry>
+ </row>
+ <row>
+ <entry>translationParseError</entry>
+ <entry>parseString</entry>
+ <entry>Missing '"'.</entry>
+ </row>
+ <row>
+ <entry>translationParseError</entry>
+ <entry>showLine</entry>
+ <entry> ... found while parsing '%s'</entry>
+ </row>
+ <row>
+ <entry>typeConversionError</entry>
+ <entry>noConverter</entry>
+ <entry>No type converter registered for '%s' to '%s' conversion.</entry>
+ </row>
+ <row>
+ <entry>unknownType</entry>
+ <entry>xtConvertVarToArgList</entry>
+ <entry>Unable to find type of resource for conversion</entry>
+ </row>
+ <row>
+ <entry>unknownType</entry>
+ <entry>xtGetTypedArg</entry>
+ <entry>Unable to find type of resource for conversion</entry>
+ </row>
+ <row>
+ <entry>versionMismatch</entry>
+ <entry>widget</entry>
+ <entry>Widget class %s version mismatch (recompilation needed):\\n widget %d vs. intrinsics %d.</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntOrPixelToXColor</entry>
+ <entry>Pixel to color conversion needs screen and colormap arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToBool</entry>
+ <entry>Integer to Bool conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToBoolean</entry>
+ <entry>Integer to Boolean conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToFloat</entry>
+ <entry>Integer to Float conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToFont</entry>
+ <entry>Integer to Font conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToPixel</entry>
+ <entry>Integer to Pixel conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToPixmap</entry>
+ <entry>Integer to Pixmap conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToShort</entry>
+ <entry>Integer to Short conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtIntToUnsignedChar</entry>
+ <entry>Integer to UnsignedChar conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToAcceleratorTable</entry>
+ <entry>String to AcceleratorTable conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToAtom</entry>
+ <entry>String to Atom conversion needs Display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToBool</entry>
+ <entry>String to Bool conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToBoolean</entry>
+ <entry>String to Boolean conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToCommandArgArray</entry>
+ <entry>String to CommandArgArray conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToCursor</entry>
+ <entry>String to cursor conversion needs display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToDimension</entry>
+ <entry>String to Dimension conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToDirectoryString</entry>
+ <entry>String to DirectoryString conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToDisplay</entry>
+ <entry>String to Display conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToFile</entry>
+ <entry>String to File conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToFloat</entry>
+ <entry>String to Float conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToFont</entry>
+ <entry>String to font conversion needs display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToFontSet</entry>
+ <entry>String to FontSet conversion needs display and locale arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToFontStruct</entry>
+ <entry>String to font conversion needs display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToGravity</entry>
+ <entry>String to Gravity conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToInitialState</entry>
+ <entry>String to InitialState conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToInt</entry>
+ <entry>String to Integer conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToPixel</entry>
+ <entry>String to pixel conversion needs screen and colormap arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToRestartStyle</entry>
+ <entry>String to RestartStyle conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToShort</entry>
+ <entry>String to Integer conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToTranslationTable</entry>
+ <entry>String to TranslationTable conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToUnsignedChar</entry>
+ <entry>String to Integer conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtStringToVisual</entry>
+ <entry>String to Visual conversion needs screen and depth arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>cvtXColorToPixel</entry>
+ <entry>Color to Pixel conversion needs no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freeCursor</entry>
+ <entry>Free Cursor requires display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freeDirectoryString</entry>
+ <entry>Free Directory String requires no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freeFile</entry>
+ <entry>Free File requires no extra arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freeFont</entry>
+ <entry>Free Font needs display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freeFontSet</entry>
+ <entry>FreeFontSet needs display and locale arguments</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freeFontStruct</entry>
+ <entry>Free FontStruct requires display argument</entry>
+ </row>
+ <row>
+ <entry>wrongParameters</entry>
+ <entry>freePixel</entry>
+ <entry>Freeing a pixel requires screen and colormap arguments</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</appendix>
diff --git a/specs/appE.xml b/specs/appE.xml
new file mode 100644
index 0000000..fca8ca8
--- /dev/null
+++ b/specs/appE.xml
@@ -0,0 +1,1703 @@
+<appendix id='Defined_Strings'>
+<title>Defined Strings</title>
+
+<para>
+The <function>StringDefs.h</function>
+header file contains definitions for the following resource name,
+class, and representation type symbolic constants.
+</para>
+
+<para><emphasis role='strong'>Resource names:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNaccelerators</entry>
+ <entry>"accelerators"</entry>
+ </row>
+ <row>
+ <entry>XtNallowHoriz</entry>
+ <entry>"allowHoriz"</entry>
+ </row>
+ <row>
+ <entry>XtNallowVert</entry>
+ <entry>"allowVert"</entry>
+ </row>
+ <row>
+ <entry>XtNancestorSensitive</entry>
+ <entry>"ancestorSensitive"</entry>
+ </row>
+ <row>
+ <entry>XtNbackground</entry>
+ <entry>"background"</entry>
+ </row>
+ <row>
+ <entry>XtNbackgroundPixmap</entry>
+ <entry>"backgroundPixmap"</entry>
+ </row>
+ <row>
+ <entry>XtNbitmap</entry>
+ <entry>"bitmap"</entry>
+ </row>
+ <row>
+ <entry>XtNborder</entry>
+ <entry>"borderColor"</entry>
+ </row>
+ <row>
+ <entry>XtNborderColor</entry>
+ <entry>"borderColor"</entry>
+ </row>
+ <row>
+ <entry>XtNborderPixmap</entry>
+ <entry>"borderPixmap"</entry>
+ </row>
+ <row>
+ <entry>XtNborderWidth</entry>
+ <entry>"borderWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNcallback</entry>
+ <entry>"callback"</entry>
+ </row>
+ <row>
+ <entry>XtNchangeHook</entry>
+ <entry>"changeHook"</entry>
+ </row>
+ <row>
+ <entry>XtNchildren</entry>
+ <entry>"children"</entry>
+ </row>
+ <row>
+ <entry>XtNcolormap</entry>
+ <entry>"colormap"</entry>
+ </row>
+ <row>
+ <entry>XtNconfigureHook</entry>
+ <entry>"configureHook"</entry>
+ </row>
+ <row>
+ <entry>XtNcreateHook</entry>
+ <entry>"createHook"</entry>
+ </row>
+ <row>
+ <entry>XtNdepth</entry>
+ <entry>"depth"</entry>
+ </row>
+ <row>
+ <entry>XtNdestroyCallback</entry>
+ <entry>"destroyCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNdestroyHook</entry>
+ <entry>"destroyHook"</entry>
+ </row>
+ <row>
+ <entry>XtNeditType</entry>
+ <entry>"editType"</entry>
+ </row>
+ <row>
+ <entry>XtNfile</entry>
+ <entry>"file"</entry>
+ </row>
+ <row>
+ <entry>XtNfont</entry>
+ <entry>"font"</entry>
+ </row>
+ <row>
+ <entry>XtNfontSet</entry>
+ <entry>"fontSet"</entry>
+ </row>
+ <row>
+ <entry>XtNforceBars</entry>
+ <entry>"forceBars"</entry>
+ </row>
+ <row>
+ <entry>XtNforeground</entry>
+ <entry>"foreground"</entry>
+ </row>
+ <row>
+ <entry>XtNfunction</entry>
+ <entry>"function"</entry>
+ </row>
+ <row>
+ <entry>XtNgeometryHook</entry>
+ <entry>"geometryHook"</entry>
+ </row>
+ <row>
+ <entry>XtNheight</entry>
+ <entry>"height"</entry>
+ </row>
+ <row>
+ <entry>XtNhighlight</entry>
+ <entry>"highlight"</entry>
+ </row>
+ <row>
+ <entry>XtNhSpace</entry>
+ <entry>"hSpace"</entry>
+ </row>
+ <row>
+ <entry>XtNindex</entry>
+ <entry>"index"</entry>
+ </row>
+ <row>
+ <entry>XtNinitialResourcesPersistent</entry>
+ <entry>"initialResourcesPersistent"</entry>
+ </row>
+ <row>
+ <entry>XtNinnerHeight</entry>
+ <entry>"innerHeight"</entry>
+ </row>
+ <row>
+ <entry>XtNinnerWidth</entry>
+ <entry>"innerWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNinnerWindow</entry>
+ <entry>"innerWindow"</entry>
+ </row>
+ <row>
+ <entry>XtNinsertPosition</entry>
+ <entry>"insertPosition"</entry>
+ </row>
+ <row>
+ <entry>XtNinternalHeight</entry>
+ <entry>"internalHeight"</entry>
+ </row>
+ <row>
+ <entry>XtNinternalWidth</entry>
+ <entry>"internalWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNjumpProc</entry>
+ <entry>"jumpProc"</entry>
+ </row>
+ <row>
+ <entry>XtNjustify</entry>
+ <entry>"justify"</entry>
+ </row>
+ <row>
+ <entry>XtNknobHeight</entry>
+ <entry>"knobHeight"</entry>
+ </row>
+ <row>
+ <entry>XtNknobIndent</entry>
+ <entry>"knobIndent"</entry>
+ </row>
+ <row>
+ <entry>XtNknobPixel</entry>
+ <entry>"knobPixel"</entry>
+ </row>
+ <row>
+ <entry>XtNknobWidth</entry>
+ <entry>"knobWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNlabel</entry>
+ <entry>"label"</entry>
+ </row>
+ <row>
+ <entry>XtNlength</entry>
+ <entry>"length"</entry>
+ </row>
+ <row>
+ <entry>XtNlowerRight</entry>
+ <entry>"lowerRight"</entry>
+ </row>
+ <row>
+ <entry>XtNmappedWhenManaged</entry>
+ <entry>"mappedWhenManaged"</entry>
+ </row>
+ <row>
+ <entry>XtNmenuEntry</entry>
+ <entry>"menuEntry"</entry>
+ </row>
+ <row>
+ <entry>XtNname</entry>
+ <entry>"name"</entry>
+ </row>
+ <row>
+ <entry>XtNnotify</entry>
+ <entry>"notify"</entry>
+ </row>
+ <row>
+ <entry>XtNnumChildren</entry>
+ <entry>"numChildren"</entry>
+ </row>
+ <row>
+ <entry>XtNnumShells</entry>
+ <entry>"numShells"</entry>
+ </row>
+ <row>
+ <entry>XtNorientation</entry>
+ <entry>"orientation"</entry>
+ </row>
+ <row>
+ <entry>XtNparameter</entry>
+ <entry>"parameter"</entry>
+ </row>
+ <row>
+ <entry>XtNpixmap</entry>
+ <entry>"pixmap"</entry>
+ </row>
+ <row>
+ <entry>XtNpopupCallback</entry>
+ <entry>"popupCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNpopdownCallback</entry>
+ <entry>"popdownCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNresize</entry>
+ <entry>"resize"</entry>
+ </row>
+ <row>
+ <entry>XtNreverseVideo</entry>
+ <entry>"reverseVideo"</entry>
+ </row>
+ <row>
+ <entry>XtNscreen</entry>
+ <entry>"screen"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollProc</entry>
+ <entry>"scrollProc"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollDCursor</entry>
+ <entry>"scrollDCursor"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollHCursor</entry>
+ <entry>"scrollHCursor"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollLCursor</entry>
+ <entry>"scrollLCursor"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollRCursor</entry>
+ <entry>"scrollRCursor"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollUCursor</entry>
+ <entry>"scrollUCursor"</entry>
+ </row>
+ <row>
+ <entry>XtNscrollVCursor</entry>
+ <entry>"scrollVCursor"</entry>
+ </row>
+ <row>
+ <entry>XtNselection</entry>
+ <entry>"selection"</entry>
+ </row>
+ <row>
+ <entry>XtNselectionArray</entry>
+ <entry>"selectionArray"</entry>
+ </row>
+ <row>
+ <entry>XtNsensitive</entry>
+ <entry>"sensitive"</entry>
+ </row>
+ <row>
+ <entry>XtNsession</entry>
+ <entry>"session"</entry>
+ </row>
+ <row>
+ <entry>XtNshells</entry>
+ <entry>"shells"</entry>
+ </row>
+ <row>
+ <entry>XtNshown</entry>
+ <entry>"shown"</entry>
+ </row>
+ <row>
+ <entry>XtNspace</entry>
+ <entry>"space"</entry>
+ </row>
+ <row>
+ <entry>XtNstring</entry>
+ <entry>"string"</entry>
+ </row>
+ <row>
+ <entry>XtNtextOptions</entry>
+ <entry>"textOptions"</entry>
+ </row>
+ <row>
+ <entry>XtNtextSink</entry>
+ <entry>"textSink"</entry>
+ </row>
+ <row>
+ <entry>XtNtextSource</entry>
+ <entry>"textSource"</entry>
+ </row>
+ <row>
+ <entry>XtNthickness</entry>
+ <entry>"thickness"</entry>
+ </row>
+ <row>
+ <entry>XtNthumb</entry>
+ <entry>"thumb"</entry>
+ </row>
+ <row>
+ <entry>XtNthumbProc</entry>
+ <entry>"thumbProc"</entry>
+ </row>
+ <row>
+ <entry>XtNtop</entry>
+ <entry>"top"</entry>
+ </row>
+ <row>
+ <entry>XtNtranslations</entry>
+ <entry>"translations"</entry>
+ </row>
+ <row>
+ <entry>XtNunrealizeCallback</entry>
+ <entry>"unrealizeCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNupdate</entry>
+ <entry>"update"</entry>
+ </row>
+ <row>
+ <entry>XtNuseBottom</entry>
+ <entry>"useBottom"</entry>
+ </row>
+ <row>
+ <entry>XtNuseRight</entry>
+ <entry>"useRight"</entry>
+ </row>
+ <row>
+ <entry>XtNvalue</entry>
+ <entry>"value"</entry>
+ </row>
+ <row>
+ <entry>XtNvSpace</entry>
+ <entry>"vSpace"</entry>
+ </row>
+ <row>
+ <entry>XtNwidth</entry>
+ <entry>"width"</entry>
+ </row>
+ <row>
+ <entry>XtNwindow</entry>
+ <entry>"window"</entry>
+ </row>
+ <row>
+ <entry>XtNx</entry>
+ <entry>"x"</entry>
+ </row>
+ <row>
+ <entry>XtNy</entry>
+ <entry>"y"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Resource classes:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtCAccelerators</entry>
+ <entry>"Accelerators"</entry>
+ </row>
+ <row>
+ <entry>XtCBackground</entry>
+ <entry>"Background"</entry>
+ </row>
+ <row>
+ <entry>XtCBitmap</entry>
+ <entry>"Bitmap"</entry>
+ </row>
+ <row>
+ <entry>XtCBoolean</entry>
+ <entry>"Boolean"</entry>
+ </row>
+ <row>
+ <entry>XtCBorderColor</entry>
+ <entry>"BorderColor"</entry>
+ </row>
+ <row>
+ <entry>XtCBorderWidth</entry>
+ <entry>"BorderWidth"</entry>
+ </row>
+ <row>
+ <entry>XtCCallback</entry>
+ <entry>"Callback"</entry>
+ </row>
+ <row>
+ <entry>XtCColormap</entry>
+ <entry>"Colormap"</entry>
+ </row>
+ <row>
+ <entry>XtCColor</entry>
+ <entry>"Color"</entry>
+ </row>
+ <row>
+ <entry>XtCCursor</entry>
+ <entry>"Cursor"</entry>
+ </row>
+ <row>
+ <entry>XtCDepth</entry>
+ <entry>"Depth"</entry>
+ </row>
+ <row>
+ <entry>XtCEditType</entry>
+ <entry>"EditType"</entry>
+ </row>
+ <row>
+ <entry>XtCEventBindings</entry>
+ <entry>"EventBindings"</entry>
+ </row>
+ <row>
+ <entry>XtCFile</entry>
+ <entry>"File"</entry>
+ </row>
+ <row>
+ <entry>XtCFont</entry>
+ <entry>"Font"</entry>
+ </row>
+ <row>
+ <entry>XtCFontSet</entry>
+ <entry>"FontSet"</entry>
+ </row>
+ <row>
+ <entry>XtCForeground</entry>
+ <entry>"Foreground"</entry>
+ </row>
+ <row>
+ <entry>XtCFraction</entry>
+ <entry>"Fraction"</entry>
+ </row>
+ <row>
+ <entry>XtCFunction</entry>
+ <entry>"Function"</entry>
+ </row>
+ <row>
+ <entry>XtCHeight</entry>
+ <entry>"Height"</entry>
+ </row>
+ <row>
+ <entry>XtCHSpace</entry>
+ <entry>"HSpace"</entry>
+ </row>
+ <row>
+ <entry>XtCIndex</entry>
+ <entry>"Index"</entry>
+ </row>
+ <row>
+ <entry>XtCInitialResourcesPersistent</entry>
+ <entry>"InitialResourcesPersistent"</entry>
+ </row>
+ <row>
+ <entry>XtCInsertPosition</entry>
+ <entry>"InsertPosition"</entry>
+ </row>
+ <row>
+ <entry>XtCInterval</entry>
+ <entry>"Interval"</entry>
+ </row>
+ <row>
+ <entry>XtCJustify</entry>
+ <entry>"Justify"</entry>
+ </row>
+ <row>
+ <entry>XtCKnobIndent</entry>
+ <entry>"KnobIndent"</entry>
+ </row>
+ <row>
+ <entry>XtCKnobPixel</entry>
+ <entry>"KnobPixel"</entry>
+ </row>
+ <row>
+ <entry>XtCLabel</entry>
+ <entry>"Label"</entry>
+ </row>
+ <row>
+ <entry>XtCLength</entry>
+ <entry>"Length"</entry>
+ </row>
+ <row>
+ <entry>XtCMappedWhenManaged</entry>
+ <entry>"MappedWhenManaged"</entry>
+ </row>
+ <row>
+ <entry>XtCMargin</entry>
+ <entry>"Margin"</entry>
+ </row>
+ <row>
+ <entry>XtCMenuEntry</entry>
+ <entry>"MenuEntry"</entry>
+ </row>
+ <row>
+ <entry>XtCNotify</entry>
+ <entry>"Notify"</entry>
+ </row>
+ <row>
+ <entry>XtCOrientation</entry>
+ <entry>"Orientation"</entry>
+ </row>
+ <row>
+ <entry>XtCParameter</entry>
+ <entry>"Parameter"</entry>
+ </row>
+ <row>
+ <entry>XtCPixmap</entry>
+ <entry>"Pixmap"</entry>
+ </row>
+ <row>
+ <entry>XtCPosition</entry>
+ <entry>"Position"</entry>
+ </row>
+ <row>
+ <entry>XtCReadOnly</entry>
+ <entry>"ReadOnly"</entry>
+ </row>
+ <row>
+ <entry>XtCResize</entry>
+ <entry>"Resize"</entry>
+ </row>
+ <row>
+ <entry>XtCReverseVideo</entry>
+ <entry>"ReverseVideo"</entry>
+ </row>
+ <row>
+ <entry>XtCScreen</entry>
+ <entry>"Screen"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollProc</entry>
+ <entry>"ScrollProc"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollDCursor</entry>
+ <entry>"ScrollDCursor"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollHCursor</entry>
+ <entry>"ScrollHCursor"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollLCursor</entry>
+ <entry>"ScrollLCursor"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollRCursor</entry>
+ <entry>"ScrollRCursor"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollUCursor</entry>
+ <entry>"ScrollUCursor"</entry>
+ </row>
+ <row>
+ <entry>XtCScrollVCursor</entry>
+ <entry>"ScrollVCursor"</entry>
+ </row>
+ <row>
+ <entry>XtCSelection</entry>
+ <entry>"Selection"</entry>
+ </row>
+ <row>
+ <entry>XtCSelectionArray</entry>
+ <entry>"SelectionArray"</entry>
+ </row>
+ <row>
+ <entry>XtCSensitive</entry>
+ <entry>"Sensitive"</entry>
+ </row>
+ <row>
+ <entry>XtCSession</entry>
+ <entry>"Session"</entry>
+ </row>
+ <row>
+ <entry>XtCSpace</entry>
+ <entry>"Space"</entry>
+ </row>
+ <row>
+ <entry>XtCString</entry>
+ <entry>"String"</entry>
+ </row>
+ <row>
+ <entry>XtCTextOptions</entry>
+ <entry>"TextOptions"</entry>
+ </row>
+ <row>
+ <entry>XtCTextPosition</entry>
+ <entry>"TextPosition"</entry>
+ </row>
+ <row>
+ <entry>XtCTextSink</entry>
+ <entry>"TextSink"</entry>
+ </row>
+ <row>
+ <entry>XtCTextSource</entry>
+ <entry>"TextSource"</entry>
+ </row>
+ <row>
+ <entry>XtCThickness</entry>
+ <entry>"Thickness"</entry>
+ </row>
+ <row>
+ <entry>XtCThumb</entry>
+ <entry>"Thumb"</entry>
+ </row>
+ <row>
+ <entry>XtCTranslations</entry>
+ <entry>"Translations"</entry>
+ </row>
+ <row>
+ <entry>XtCValue</entry>
+ <entry>"Value"</entry>
+ </row>
+ <row>
+ <entry>XtCVSpace</entry>
+ <entry>"VSpace"</entry>
+ </row>
+ <row>
+ <entry>XtCWidth</entry>
+ <entry>"Width"</entry>
+ </row>
+ <row>
+ <entry>XtCWindow</entry>
+ <entry>"Window"</entry>
+ </row>
+ <row>
+ <entry>XtCX</entry>
+ <entry>"X"</entry>
+ </row>
+ <row>
+ <entry>XtCY</entry>
+ <entry>"Y"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Resource representation types:</emphasis></para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='0'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtRAcceleratorTable</entry>
+ <entry>"AcceleratorTable"</entry>
+ </row>
+ <row>
+ <entry>XtRAtom</entry>
+ <entry>"Atom"</entry>
+ </row>
+ <row>
+ <entry>XtRBitmap</entry>
+ <entry>"Bitmap"</entry>
+ </row>
+ <row>
+ <entry>XtRBool</entry>
+ <entry>"Bool"</entry>
+ </row>
+ <row>
+ <entry>XtRBoolean</entry>
+ <entry>"Boolean"</entry>
+ </row>
+ <row>
+ <entry>XtRCallback</entry>
+ <entry>"Callback"</entry>
+ </row>
+ <row>
+ <entry>XtRCallProc</entry>
+ <entry>"CallProc"</entry>
+ </row>
+ <row>
+ <entry>XtRCardinal</entry>
+ <entry>"Cardinal"</entry>
+ </row>
+ <row>
+ <entry>XtRColor</entry>
+ <entry>"Color"</entry>
+ </row>
+ <row>
+ <entry>XtRColormap</entry>
+ <entry>"Colormap"</entry>
+ </row>
+ <row>
+ <entry>XtRCommandArgArray</entry>
+ <entry>"CommandArgArray"</entry>
+ </row>
+ <row>
+ <entry>XtRCursor</entry>
+ <entry>"Cursor"</entry>
+ </row>
+ <row>
+ <entry>XtRDimension</entry>
+ <entry>"Dimension"</entry>
+ </row>
+ <row>
+ <entry>XtRDirectoryString</entry>
+ <entry>"DirectoryString"</entry>
+ </row>
+ <row>
+ <entry>XtRDisplay</entry>
+ <entry>"Display"</entry>
+ </row>
+ <row>
+ <entry>XtREditMode</entry>
+ <entry>"EditMode"</entry>
+ </row>
+ <row>
+ <entry>XtREnum</entry>
+ <entry>"Enum"</entry>
+ </row>
+ <row>
+ <entry>XtREnvironmentArray</entry>
+ <entry>"EnvironmentArray"</entry>
+ </row>
+ <row>
+ <entry>XtRFile</entry>
+ <entry>"File"</entry>
+ </row>
+ <row>
+ <entry>XtRFloat</entry>
+ <entry>"Float"</entry>
+ </row>
+ <row>
+ <entry>XtRFont</entry>
+ <entry>"Font"</entry>
+ </row>
+ <row>
+ <entry>XtRFontSet</entry>
+ <entry>"FontSet"</entry>
+ </row>
+ <row>
+ <entry>XtRFontStruct</entry>
+ <entry>"FontStruct"</entry>
+ </row>
+ <row>
+ <entry>XtRFunction</entry>
+ <entry>"Function"</entry>
+ </row>
+ <row>
+ <entry>XtRGeometry</entry>
+ <entry>"Geometry"</entry>
+ </row>
+ <row>
+ <entry>XtRGravity</entry>
+ <entry>"Gravity"</entry>
+ </row>
+ <row>
+ <entry>XtRImmediate</entry>
+ <entry>"Immediate"</entry>
+ </row>
+ <row>
+ <entry>XtRInitialState</entry>
+ <entry>"InitialState"</entry>
+ </row>
+ <row>
+ <entry>XtRInt</entry>
+ <entry>"Int"</entry>
+ </row>
+ <row>
+ <entry>XtRJustify</entry>
+ <entry>"Justify"</entry>
+ </row>
+ <row>
+ <entry>XtRLongBoolean</entry>
+ <entry>XtRBool</entry>
+ </row>
+ <row>
+ <entry>XtRObject</entry>
+ <entry>"Object"</entry>
+ </row>
+ <row>
+ <entry>XtROrientation</entry>
+ <entry>"Orientation"</entry>
+ </row>
+ <row>
+ <entry>XtRPixel</entry>
+ <entry>"Pixel"</entry>
+ </row>
+ <row>
+ <entry>XtRPixmap</entry>
+ <entry>"Pixmap"</entry>
+ </row>
+ <row>
+ <entry>XtRPointer</entry>
+ <entry>"Pointer"</entry>
+ </row>
+ <row>
+ <entry>XtRPosition</entry>
+ <entry>"Position"</entry>
+ </row>
+ <row>
+ <entry>XtRRestartStyle</entry>
+ <entry>"RestartStyle"</entry>
+ </row>
+ <row>
+ <entry>XtRScreen</entry>
+ <entry>"Screen"</entry>
+ </row>
+ <row>
+ <entry>XtRShort</entry>
+ <entry>"Short"</entry>
+ </row>
+ <row>
+ <entry>XtRSmcConn</entry>
+ <entry>"SmcConn"</entry>
+ </row>
+ <row>
+ <entry>XtRString</entry>
+ <entry>"String"</entry>
+ </row>
+ <row>
+ <entry>XtRStringArray</entry>
+ <entry>"StringArray"</entry>
+ </row>
+ <row>
+ <entry>XtRStringTable</entry>
+ <entry>"StringTable"</entry>
+ </row>
+ <row>
+ <entry>XtRUnsignedChar</entry>
+ <entry>"UnsignedChar"</entry>
+ </row>
+ <row>
+ <entry>XtRTranslationTable</entry>
+ <entry>"TranslationTable"</entry>
+ </row>
+ <row>
+ <entry>XtRVisual</entry>
+ <entry>"Visual"</entry>
+ </row>
+ <row>
+ <entry>XtRWidget</entry>
+ <entry>"Widget"</entry>
+ </row>
+ <row>
+ <entry>XtRWidgetClass</entry>
+ <entry>"WidgetClass"</entry>
+ </row>
+ <row>
+ <entry>XtRWidgetList</entry>
+ <entry>"WidgetList"</entry>
+ </row>
+ <row>
+ <entry>XtRWindow</entry>
+ <entry>"Window"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Boolean enumeration constants:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtEoff</entry>
+ <entry>"off"</entry>
+ </row>
+ <row>
+ <entry>XtEfalse</entry>
+ <entry>"false"</entry>
+ </row>
+ <row>
+ <entry>XtEno</entry>
+ <entry>"no"</entry>
+ </row>
+ <row>
+ <entry>XtEon</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>XtEtrue</entry>
+ <entry>"true"</entry>
+ </row>
+ <row>
+ <entry>XtEyes</entry>
+ <entry>"yes"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Orientation enumeration constants:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtEvertical</entry>
+ <entry>"vertical"</entry>
+ </row>
+ <row>
+ <entry>XtEhorizontal</entry>
+ <entry>"horizontal"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Text edit enumeration constants:</emphasis></para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtEtextRead</entry>
+ <entry>"read"</entry>
+ </row>
+ <row>
+ <entry>XtEtextAppend</entry>
+ <entry>"append"</entry>
+ </row>
+ <row>
+ <entry>XtEtextEdit</entry>
+ <entry>"edit"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Color enumeration constants:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtExtdefaultbackground</entry>
+ <entry>"xtdefaultbackground"</entry>
+ </row>
+ <row>
+ <entry>XtExtdefaultforeground</entry>
+ <entry>"xtdefaultforeground"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Font constant:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtExtdefaultfont</entry>
+ <entry>"xtdefaultfont"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Hooks for External Agents constants:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtHcreate</entry>
+ <entry>"Xtcreate"</entry>
+ </row>
+ <row>
+ <entry>XtHsetValues</entry>
+ <entry>"Xtsetvalues"</entry>
+ </row>
+ <row>
+ <entry>XtHmanageChildren</entry>
+ <entry>"XtmanageChildren"</entry>
+ </row>
+ <row>
+ <entry>XtHunmanageChildren</entry>
+ <entry>"XtunmanageChildren"</entry>
+ </row>
+ <row>
+ <entry>XtHmanageSet</entry>
+ <entry>"XtmanageSet"</entry>
+ </row>
+ <row>
+ <entry>XtHunmanageSet</entry>
+ <entry>"XtunmanageSet"</entry>
+ </row>
+ <row>
+ <entry>XtHrealizeWidget</entry>
+ <entry>"XtrealizeWidget"</entry>
+ </row>
+ <row>
+ <entry>XtHunrealizeWidget</entry>
+ <entry>"XtunrealizeWidget"</entry>
+ </row>
+ <row>
+ <entry>XtHaddCallback</entry>
+ <entry>"XtaddCallback"</entry>
+ </row>
+ <row>
+ <entry>XtHaddCallbacks</entry>
+ <entry>"XtaddCallbacks"</entry>
+ </row>
+ <row>
+ <entry>XtHremoveCallback</entry>
+ <entry>"XtremoveCallback"</entry>
+ </row>
+ <row>
+ <entry>XtHremoveCallbacks</entry>
+ <entry>"XtremoveCallbacks"</entry>
+ </row>
+ <row>
+ <entry>XtHremoveAllCallbacks</entry>
+ <entry>"XtremoveAllCallbacks"</entry>
+ </row>
+ <row>
+ <entry>XtHaugmentTranslations</entry>
+ <entry>"XtaugmentTranslations"</entry>
+ </row>
+ <row>
+ <entry>XtHoverrideTranslations</entry>
+ <entry>"XtoverrideTranslations"</entry>
+ </row>
+ <row>
+ <entry>XtHuninstallTranslations</entry>
+ <entry>"XtuninstallTranslations"</entry>
+ </row>
+ <row>
+ <entry>XtHsetKeyboardFocus</entry>
+ <entry>"XtsetKeyboardFocus"</entry>
+ </row>
+ <row>
+ <entry>XtHsetWMColormapWindows</entry>
+ <entry>"XtsetWMColormapWindows"</entry>
+ </row>
+ <row>
+ <entry>XtHmapWidget</entry>
+ <entry>"XtmapWidget"</entry>
+ </row>
+ <row>
+ <entry>XtHunmapWidget</entry>
+ <entry>"XtunmapWidget"</entry>
+ </row>
+ <row>
+ <entry>XtHpopup</entry>
+ <entry>"Xtpopup"</entry>
+ </row>
+ <row>
+ <entry>XtHpopupSpringLoaded</entry>
+ <entry>"XtpopupSpringLoaded"</entry>
+ </row>
+ <row>
+ <entry>XtHpopdown</entry>
+ <entry>"Xtpopdown"</entry>
+ </row>
+ <row>
+ <entry>XtHconfigure</entry>
+ <entry>"Xtconfigure"</entry>
+ </row>
+ <row>
+ <entry>XtHpreGeometry</entry>
+ <entry>"XtpreGeometry"</entry>
+ </row>
+ <row>
+ <entry>XtHpostGeometry</entry>
+ <entry>"XtpostGeometry"</entry>
+ </row>
+ <row>
+ <entry>XtHdestroy</entry>
+ <entry>"Xtdestroy"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The
+<function>Shell.h</function>
+header file contains definitions for the following resource name,
+class, and representation type symbolic constants.
+</para>
+
+<para><emphasis role='strong'>Resource names:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNallowShellResize</entry>
+ <entry>"allowShellResize"</entry>
+ </row>
+ <row>
+ <entry>XtNargc</entry>
+ <entry>"argc"</entry>
+ </row>
+ <row>
+ <entry>XtNargv</entry>
+ <entry>"argv"</entry>
+ </row>
+ <row>
+ <entry>XtNbaseHeight</entry>
+ <entry>"baseHeight"</entry>
+ </row>
+ <row>
+ <entry>XtNbaseWidth</entry>
+ <entry>"baseWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNcancelCallback</entry>
+ <entry>"cancelCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNclientLeader</entry>
+ <entry>"clientLeader"</entry>
+ </row>
+ <row>
+ <entry>XtNcloneCommand</entry>
+ <entry>"cloneCommand"</entry>
+ </row>
+ <row>
+ <entry>XtNconnection</entry>
+ <entry>"connection"</entry>
+ </row>
+ <row>
+ <entry>XtNcreatePopupChildProc</entry>
+ <entry>"createPopupChildProc"</entry>
+ </row>
+ <row>
+ <entry>XtNcurrentDirectory</entry>
+ <entry>"currentDirectory"</entry>
+ </row>
+ <row>
+ <entry>XtNdieCallback</entry>
+ <entry>"dieCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNdiscardCommand</entry>
+ <entry>"discardCommand"</entry>
+ </row>
+ <row>
+ <entry>XtNenvironment</entry>
+ <entry>"environment"</entry>
+ </row>
+ <row>
+ <entry>XtNerrorCallback</entry>
+ <entry>"errorCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNgeometry</entry>
+ <entry>"geometry"</entry>
+ </row>
+ <row>
+ <entry>XtNheightInc</entry>
+ <entry>"heightInc"</entry>
+ </row>
+ <row>
+ <entry>XtNiconMask</entry>
+ <entry>"iconMask"</entry>
+ </row>
+ <row>
+ <entry>XtNiconName</entry>
+ <entry>"iconName"</entry>
+ </row>
+ <row>
+ <entry>XtNiconNameEncoding</entry>
+ <entry>"iconNameEncoding"</entry>
+ </row>
+ <row>
+ <entry>XtNiconPixmap</entry>
+ <entry>"iconPixmap"</entry>
+ </row>
+ <row>
+ <entry>XtNiconWindow</entry>
+ <entry>"iconWindow"</entry>
+ </row>
+ <row>
+ <entry>XtNiconX</entry>
+ <entry>"iconX"</entry>
+ </row>
+ <row>
+ <entry>XtNiconY</entry>
+ <entry>"iconY"</entry>
+ </row>
+ <row>
+ <entry>XtNiconic</entry>
+ <entry>"iconic"</entry>
+ </row>
+ <row>
+ <entry>XtNinitialState</entry>
+ <entry>"initialState"</entry>
+ </row>
+ <row>
+ <entry>XtNinput</entry>
+ <entry>"input"</entry>
+ </row>
+ <row>
+ <entry>XtNinteractCallback</entry>
+ <entry>"interactCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNjoinSession</entry>
+ <entry>"joinSession"</entry>
+ </row>
+ <row>
+ <entry>XtNmaxAspectX</entry>
+ <entry>"maxAspectX"</entry>
+ </row>
+ <row>
+ <entry>XtNmaxAspectY</entry>
+ <entry>"maxAspectY"</entry>
+ </row>
+ <row>
+ <entry>XtNmaxHeight</entry>
+ <entry>"maxHeight"</entry>
+ </row>
+ <row>
+ <entry>XtNmaxWidth</entry>
+ <entry>"maxWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNminAspectX</entry>
+ <entry>"minAspectX"</entry>
+ </row>
+ <row>
+ <entry>XtNminAspectY</entry>
+ <entry>"minAspectY"</entry>
+ </row>
+ <row>
+ <entry>XtNminHeight</entry>
+ <entry>"minHeight"</entry>
+ </row>
+ <row>
+ <entry>XtNminWidth</entry>
+ <entry>"minWidth"</entry>
+ </row>
+ <row>
+ <entry>XtNoverrideRedirect</entry>
+ <entry>"overrideRedirect"</entry>
+ </row>
+ <row>
+ <entry>XtNprogramPath</entry>
+ <entry>"programPath"</entry>
+ </row>
+ <row>
+ <entry>XtNresignCommand</entry>
+ <entry>"resignCommand"</entry>
+ </row>
+ <row>
+ <entry>XtNrestartCommand</entry>
+ <entry>"restartCommand"</entry>
+ </row>
+ <row>
+ <entry>XtNrestartStyle</entry>
+ <entry>"restartStyle"</entry>
+ </row>
+ <row>
+ <entry>XtNsaveCallback</entry>
+ <entry>"saveCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNsaveCompleteCallback</entry>
+ <entry>"saveCompleteCallback"</entry>
+ </row>
+ <row>
+ <entry>XtNsaveUnder</entry>
+ <entry>"saveUnder"</entry>
+ </row>
+ <row>
+ <entry>XtNsessionID</entry>
+ <entry>"sessionID"</entry>
+ </row>
+ <row>
+ <entry>XtNshutdownCommand</entry>
+ <entry>"shutdownCommand"</entry>
+ </row>
+ <row>
+ <entry>XtNtitle</entry>
+ <entry>"title"</entry>
+ </row>
+ <row>
+ <entry>XtNtitleEncoding</entry>
+ <entry>"titleEncoding"</entry>
+ </row>
+ <row>
+ <entry>XtNtransient</entry>
+ <entry>"transient"</entry>
+ </row>
+ <row>
+ <entry>XtNtransientFor</entry>
+ <entry>"transientFor"</entry>
+ </row>
+ <row>
+ <entry>XtNurgency</entry>
+ <entry>"urgency"</entry>
+ </row>
+ <row>
+ <entry>XtNvisual</entry>
+ <entry>"visual"</entry>
+ </row>
+ <row>
+ <entry>XtNwaitForWm</entry>
+ <entry>"waitforwm"</entry>
+ </row>
+ <row>
+ <entry>XtNwaitforwm</entry>
+ <entry>"waitforwm"</entry>
+ </row>
+ <row>
+ <entry>XtNwidthInc</entry>
+ <entry>"widthInc"</entry>
+ </row>
+ <row>
+ <entry>XtNwindowGroup</entry>
+ <entry>"windowGroup"</entry>
+ </row>
+ <row>
+ <entry>XtNwindowRole</entry>
+ <entry>"windowRole"</entry>
+ </row>
+ <row>
+ <entry>XtNwinGravity</entry>
+ <entry>"winGravity"</entry>
+ </row>
+ <row>
+ <entry>XtNwmTimeout</entry>
+ <entry>"wmTimeout"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Resource classes:</emphasis></para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtCAllowShellResize</entry>
+ <entry>"allowShellResize"</entry>
+ </row>
+ <row>
+ <entry>XtCArgc</entry>
+ <entry>"Argc"</entry>
+ </row>
+ <row>
+ <entry>XtCArgv</entry>
+ <entry>"Argv"</entry>
+ </row>
+ <row>
+ <entry>XtCBaseHeight</entry>
+ <entry>"BaseHeight"</entry>
+ </row>
+ <row>
+ <entry>XtCBaseWidth</entry>
+ <entry>"BaseWidth"</entry>
+ </row>
+ <row>
+ <entry>XtCClientLeader</entry>
+ <entry>"ClientLeader"</entry>
+ </row>
+ <row>
+ <entry>XtCCloneCommand</entry>
+ <entry>"CloneCommand"</entry>
+ </row>
+ <row>
+ <entry>XtCConnection</entry>
+ <entry>"Connection"</entry>
+ </row>
+ <row>
+ <entry>XtCCreatePopupChildProc</entry>
+ <entry>"CreatePopupChildProc"</entry>
+ </row>
+ <row>
+ <entry>XtCCurrentDirectory</entry>
+ <entry>"CurrentDirectory"</entry>
+ </row>
+ <row>
+ <entry>XtCDiscardCommand</entry>
+ <entry>"DiscardCommand"</entry>
+ </row>
+ <row>
+ <entry>XtCEnvironment</entry>
+ <entry>"Environment"</entry>
+ </row>
+ <row>
+ <entry>XtCGeometry</entry>
+ <entry>"Geometry"</entry>
+ </row>
+ <row>
+ <entry>XtCHeightInc</entry>
+ <entry>"HeightInc"</entry>
+ </row>
+ <row>
+ <entry>XtCIconMask</entry>
+ <entry>"IconMask"</entry>
+ </row>
+ <row>
+ <entry>XtCIconName</entry>
+ <entry>"IconName"</entry>
+ </row>
+ <row>
+ <entry>XtCIconNameEncoding</entry>
+ <entry>"IconNameEncoding"</entry>
+ </row>
+ <row>
+ <entry>XtCIconPixmap</entry>
+ <entry>"IconPixmap"</entry>
+ </row>
+ <row>
+ <entry>XtCIconWindow</entry>
+ <entry>"IconWindow"</entry>
+ </row>
+ <row>
+ <entry>XtCIconX</entry>
+ <entry>"IconX"</entry>
+ </row>
+ <row>
+ <entry>XtCIconY</entry>
+ <entry>"IconY"</entry>
+ </row>
+ <row>
+ <entry>XtCIconic</entry>
+ <entry>"Iconic"</entry>
+ </row>
+ <row>
+ <entry>XtCInitialState</entry>
+ <entry>"InitialState"</entry>
+ </row>
+ <row>
+ <entry>XtCInput</entry>
+ <entry>"Input"</entry>
+ </row>
+ <row>
+ <entry>XtCJoinSession</entry>
+ <entry>"JoinSession"</entry>
+ </row>
+ <row>
+ <entry>XtCMaxAspectX</entry>
+ <entry>"MaxAspectX"</entry>
+ </row>
+ <row>
+ <entry>XtCMaxAspectY</entry>
+ <entry>"MaxAspectY"</entry>
+ </row>
+ <row>
+ <entry>XtCMaxHeight</entry>
+ <entry>"MaxHeight"</entry>
+ </row>
+ <row>
+ <entry>XtCMaxWidth</entry>
+ <entry>"MaxWidth"</entry>
+ </row>
+ <row>
+ <entry>XtCMinAspectX</entry>
+ <entry>"MinAspectX"</entry>
+ </row>
+ <row>
+ <entry>XtCMinAspectY</entry>
+ <entry>"MinAspectY"</entry>
+ </row>
+ <row>
+ <entry>XtCMinHeight</entry>
+ <entry>"MinHeight"</entry>
+ </row>
+ <row>
+ <entry>XtCMinWidth</entry>
+ <entry>"MinWidth"</entry>
+ </row>
+ <row>
+ <entry>XtCOverrideRedirect</entry>
+ <entry>"OverrideRedirect"</entry>
+ </row>
+ <row>
+ <entry>XtCProgramPath</entry>
+ <entry>"ProgramPath"</entry>
+ </row>
+ <row>
+ <entry>XtCResignCommand</entry>
+ <entry>"ResignCommand"</entry>
+ </row>
+ <row>
+ <entry>XtCRestartCommand</entry>
+ <entry>"RestartCommand"</entry>
+ </row>
+ <row>
+ <entry>XtCRestartStyle</entry>
+ <entry>"RestartStyle"</entry>
+ </row>
+ <row>
+ <entry>XtCSaveUnder</entry>
+ <entry>"SaveUnder"</entry>
+ </row>
+ <row>
+ <entry>XtCSessionID</entry>
+ <entry>"SessionID"</entry>
+ </row>
+ <row>
+ <entry>XtCShutdownCommand</entry>
+ <entry>"ShutdownCommand"</entry>
+ </row>
+ <row>
+ <entry>XtCTitle</entry>
+ <entry>"Title"</entry>
+ </row>
+ <row>
+ <entry>XtCTitleEncoding</entry>
+ <entry>"TitleEncoding"</entry>
+ </row>
+ <row>
+ <entry>XtCTransient</entry>
+ <entry>"Transient"</entry>
+ </row>
+ <row>
+ <entry>XtCTransientFor</entry>
+ <entry>"TransientFor"</entry>
+ </row>
+ <row>
+ <entry>XtCUrgency</entry>
+ <entry>"Urgency"</entry>
+ </row>
+ <row>
+ <entry>XtCVisual</entry>
+ <entry>"Visual"</entry>
+ </row>
+ <row>
+ <entry>XtCWaitForWm</entry>
+ <entry>"Waitforwm"</entry>
+ </row>
+ <row>
+ <entry>XtCWaitforwm</entry>
+ <entry>"Waitforwm"</entry>
+ </row>
+ <row>
+ <entry>XtCWidthInc</entry>
+ <entry>"WidthInc"</entry>
+ </row>
+ <row>
+ <entry>XtCWindowGroup</entry>
+ <entry>"WindowGroup"</entry>
+ </row>
+ <row>
+ <entry>XtCWindowRole</entry>
+ <entry>"WindowRole"</entry>
+ </row>
+ <row>
+ <entry>XtCWinGravity</entry>
+ <entry>"WinGravity"</entry>
+ </row>
+ <row>
+ <entry>XtCWmTimeout</entry>
+ <entry>"WmTimeout"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para><emphasis role='strong'>Resource representation types:</emphasis></para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Definition</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtRAtom</entry>
+ <entry>"Atom"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</appendix>
diff --git a/specs/appF.xml b/specs/appF.xml
new file mode 100644
index 0000000..49f054b
--- /dev/null
+++ b/specs/appF.xml
@@ -0,0 +1,103 @@
+<appendix id='Resource_Configuration_Management'>
+<title>Resource Configuration Management</title>
+<para>
+Setting and changing resources in X applications can be difficult for
+both the application programmer and the end user. <emphasis role='strong'>Resource
+Configuration Management (RCM)</emphasis> addresses this problem by changing
+the <function>X Intrinsics</function> 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.
+</para>
+
+<para>
+The main difference between <function>RCM</function> and the <function>Editres</function>
+protocol is that the <function>RCM</function>
+customizing hooks reside in the <function>Intrinsics</function> and thus are linked with
+other toolkits such as Motif and the Athena widgets. However, the
+<function>EditRes</function> protocol requires the application to link with the
+<function>EditRes</function>
+routines in the Xmu library and Xmu is not used by all applications that
+use Motif. Also, the <function>EditRes</function> protocol uses ClientMessage,
+whereas the
+<function>RCM</function> <function>Intrinsics</function> hooks use <function>PropertyNotify</function> events.
+</para>
+
+<para>
+X Properties and the <function>PropertyNotify</function> events are used
+to implement <function>RCM</function> and
+allow on-the-fly resource customization. When the X Toolkit is
+initialized, two atoms are interned with the strings
+<emphasis remap='I'>Custom Init</emphasis> and
+<emphasis remap='I'>Custom Data</emphasis>. Both
+<function>_XtCreatePopupShell</function>
+and
+<function>_XtAppCreateShell</function>
+register a <function>PropertyNotify</function> event handler to handle these properties.
+</para>
+
+<para>
+A customization tool uses the <emphasis remap='I'>Custom Init</emphasis> property to <emphasis remap='I'>ping</emphasis> 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.
+</para>
+
+<para>
+A customization tool uses the <emphasis remap='I'>Custom Data</emphasis> 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 <function>XA_STRING</function> and
+the format of the string is:
+</para>
+<orderedlist>
+ <listitem>
+ <para>
+The length of the resource name (the number of bytes in
+the resource name)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+One space character
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The resource name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+One space character
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The resource value
+ </para>
+ </listitem>
+</orderedlist>
+<para>
+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
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+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.
+</para>
+
+<para>
+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.
+</para>
+</appendix>
diff --git a/specs/intrinsics.xml b/specs/intrinsics.xml
new file mode 100644
index 0000000..4c41695
--- /dev/null
+++ b/specs/intrinsics.xml
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[ <!ENTITY % defs SYSTEM "defs.ent"> %defs;
+]>
+
+<book id="intrinsics" lang="en">
+
+<bookinfo>
+ <title>X Toolkit Intrinsics - C Language Interface</title>
+ <subtitle>X Window System</subtitle>
+ <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
+ <printhistory><para>First Revision - April, 1994</para></printhistory>
+ <authorgroup>
+ <author>
+ <firstname>Joel</firstname><surname>McCormack</surname>
+ <affiliation>
+ <orgname>Digital Equipment Corporation</orgname>
+ <orgdiv>Western Software Laboratory</orgdiv>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Paul</firstname><surname>Asente</surname>
+ <affiliation>
+ <orgname>Digital Equipment Corporation</orgname>
+ <orgdiv>Western Software Laboratory</orgdiv>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Ralph</firstname><othername>R.</othername>
+ <surname>Swick</surname>
+ <affiliation>
+ <orgname>Digital Equipment Corporation</orgname>
+ <orgdiv>External Research Group</orgdiv>
+ </affiliation>
+ </author>
+ </authorgroup>
+ <printhistory><para>version 6 edited by Donna Converse X Consortium, Inc.</para></printhistory>
+
+<legalnotice>
+<para>XWindow System is a trademark of X Consortium, Inc.</para>
+
+<para role="multiLicensing">
+Copyright © 1985, 1986, 1987, 1988, 1991, 1994 X Consortium
+</para>
+
+<para>
+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:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+</para>
+
+<para> 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.
+</para>
+
+<para>
+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.
+</para>
+</legalnotice>
+
+<legalnotice>
+<para role="multiLicensing">
+Copyright © 1985, 1986, 1987, 1988, 1991, 1994
+Digital Equipment Corporation, Maynard, Massachusetts.
+</para>
+
+<para>
+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.
+</para>
+
+</legalnotice>
+</bookinfo>
+
+
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="acknowledgement.xml"/>
+
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="preface.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH01.xml"/>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH02.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH03.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH04.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH05.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH06.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH07.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH08.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH09.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH10.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH11.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH12.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH13.xml"/>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appA.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appB.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appC.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appD.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appE.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appF.xml"/>
+
+</book>
+
diff --git a/specs/preface.xml b/specs/preface.xml
new file mode 100644
index 0000000..c5ac3cd
--- /dev/null
+++ b/specs/preface.xml
@@ -0,0 +1,51 @@
+<preface id='About_This_Manual'>
+<title>About This Manual</title>
+
+<para>
+X Toolkit Intrinsics — C Language Interface is intended to be read by both application programmers
+who will use one or more of the many widget sets built with the Intrinsics and by widget
+programmers who will use the Intrinsics 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 Intrinsics functions in writing an application and
+because the widget programmer is likely to use many more, if not all, of the Intrinsics 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 <emphasis role='strong'>bold</emphasis> indicate the information that
+should be of special interest to an application programmer.
+</para>
+<para>
+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.
+</para>
+
+<bridgehead><emphasis role='strong'>Conventions Used in this Manual</emphasis></bridgehead>
+<para>This document uses the following conventions:</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Global symbols are printed in <function>this special font</function>. 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 italics.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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
+specifies or, in the case of multiple arguments, the word specify. The explanations for all
+arguments that are returned to you start with the word <emphasis>returns</emphasis> or, in
+the case of multiple arguments, the word <emphasis>return</emphasis>.
+ </para>
+ </listitem>
+</itemizedlist>
+</preface>