Updated following packages:

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

1 files changed, 1406 insertions, 0 deletions

diff --git a/libXt/specs/CH03.xml b/libXt/specs/CH03.xml
new file mode 100644
index 000000000..2b2e1d730
--- /dev/null
+++ b/libXt/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>