svn merge ^/branches/released .

1 files changed, 1031 insertions, 0 deletions

diff --git a/libXt/specs/CH03 b/libXt/specs/CH03
new file mode 100644
index 000000000..f96a79781
--- /dev/null
+++ b/libXt/specs/CH03
@@ -0,0 +1,1031 @@
+.\" $Xorg: CH03,v 1.3 2000/08/17 19:42:44 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\" 
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\" 
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\" 
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 3\fP\s-1
+
+\s+1\fBComposite Widgets and Their Children\fP\s-1
+.sp 2
+.nr H1 3
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 3 \(em Composite Widgets and Their Children
+.XE
+.IN "Composite widgets"
+Composite widgets (widgets whose class is a subclass of 
+.PN compositeWidgetClass )
+can have an arbitrary number of children.
+Consequently, they are responsible for much more than primitive widgets.
+Their responsibilities (either implemented directly by the widget class
+or indirectly by \*(xI functions) include:
+.IP \(bu 5
+Overall management of children from creation to destruction.
+.IP \(bu 5
+Destruction of descendants when the composite widget is destroyed.
+.IP \(bu 5
+Physical arrangement (geometry management) of a displayable subset of
+children (that is, the managed children).
+.IP \(bu 5
+Mapping and unmapping of a subset of the managed children.
+.LP
+Overall management is handled by the generic procedures
+.PN XtCreateWidget
+and
+.PN XtDestroyWidget .
+.PN XtCreateWidget
+adds children to their parent by calling the parent's insert_child
+procedure.
+.PN XtDestroyWidget
+removes children from their parent by calling the parent's delete_child
+procedure and ensures that all children of a destroyed composite widget
+also get destroyed.
+.LP
+Only a subset of the total number of children is actually managed by
+the geometry manager and hence possibly visible.
+For example, a composite editor widget
+supporting multiple editing buffers might allocate one child
+widget for each file buffer,
+but it might display only a small number of the existing buffers.
+Widgets that are in this displayable subset are called managed widgets
+and enter into geometry manager calculations.
+The other children are called unmanaged widgets
+and, by definition, are not mapped by the \*(xI.
+.LP
+Children are added to and removed from their parent's managed set by using
+.PN XtManageChild ,
+.PN XtManageChildren ,
+.PN XtUnmanageChild ,
+.PN XtUnmanageChildren ,
+and
+.PN XtChangeManagedSet ,
+which notify the parent to recalculate the physical layout of its children
+by calling the parent's change_managed procedure.
+The 
+.PN XtCreateManagedWidget
+convenience function calls
+.PN XtCreateWidget
+and
+.PN XtManageChild
+on the result.
+.LP
+Most managed children are mapped,
+but some widgets can be in a state where they take up physical space
+but do not show anything.
+Managed widgets are not mapped automatically
+if their \fImap_when_managed\fP field is 
+.PN False .
+The default is 
+.PN True 
+and is changed by using
+.PN XtSetMappedWhenManaged .
+.LP
+Each composite widget class declares a geometry manager,
+which is responsible for figuring out where the managed children
+should appear within the composite widget's window.
+Geometry management techniques fall into four classes:
+.IP "Fixed boxes" 1.6i
+Fixed boxes have a fixed number of children created by the parent.
+All these children are managed,
+and none ever makes geometry manager requests.
+.IP "Homogeneous boxes" 1.6i
+Homogeneous boxes treat all children equally and apply the same geometry
+constraints to each child.
+Many clients insert and delete widgets freely.
+.IP "Heterogeneous boxes" 1.6i
+Heterogeneous boxes have a specific location where each child is placed.
+This location usually is not specified in pixels,
+because the window may be resized, but is expressed rather
+in terms of the relationship between a child
+and the parent or between the child and other specific children.
+The class of heterogeneous boxes is usually a subclass of
+Constraint.
+.IP "Shell boxes" 1.6i
+Shell boxes typically have only one child,
+and the child's size is usually
+exactly the size of the shell.
+The geometry manager must communicate with the window manager, if it exists,
+and the box must also accept
+.PN ConfigureNotify
+events when the window size is changed by the window manager.
+
+.NH 2
+Addition of Children to a Composite Widget: The insert_child Procedure
+.XS
+\*(SN Addition of Children to a Composite Widget: The insert_child Procedure
+.XE
+.LP
+.IN "insert_child procedure"
+To add a child to
+the parent's list of children, the
+.PN XtCreateWidget
+function calls the parent's class routine insert_child.
+The insert_child procedure pointer in a composite widget is of type
+.PN XtWidgetProc .
+.LP
+.IN "insert_child procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtWidgetProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Passes the newly created child.
+.LP
+.eM
+Most composite widgets inherit their superclass's operation.
+The insert_child routine in
+.PN CompositeWidgetClass calls the insert_position procedure
+and inserts the child at the specified position
+in the \fIchildren\fP list, expanding it if necessary.
+.LP
+Some composite widgets define their own insert_child routine
+so that they can order their children in some convenient way,
+create companion controller widgets for a new widget,
+or limit the number or class of their child widgets.
+A composite widget class that wishes
+to allow nonwidget children (see Chapter 12) must specify a
+.PN CompositeClassExtension
+extension record as described
+in Section 1.4.2.1 and set the \fIaccepts_objects\fP field in this record to
+.PN True .
+If the
+.PN CompositeClassExtension
+record is not specified or the
+\fIaccepts_objects\fP field is
+.PN False ,
+the composite widget can assume that all its children are of a subclass of Core
+without an explicit subclass test in the insert_child procedure.
+.LP
+If there is not enough room to insert a new child in the \fIchildren\fP array
+(that is, \fInum_children\fP is equal to \fInum_slots\fP),
+the insert_child procedure must first reallocate the array
+and update \fInum_slots\fP.
+The insert_child procedure then places the child at the appropriate position
+in the array and increments the \fInum_children\fP field.
+
+.NH 2
+Insertion Order of Children: The insert_position Procedure
+.XS
+\fB\*(SN Insertion Order of Children: The insert_position Procedure\fP
+.XE
+.LP
+Instances of composite widgets sometimes need to specify more about the order in which
+their children are kept.
+For example,
+an application may want a set of command buttons in some logical order
+grouped by function,
+and it may want buttons that represent file names to be kept
+in alphabetical order without constraining the order in which the
+buttons are created.
+.LP
+An application controls the presentation order of a set of children by
+supplying an
+.IN XtNinsertPosition
+XtNinsertPosition
+resource.
+The insert_position procedure pointer in a composite widget instance is of type
+.PN XtOrderProc .
+.LP
+.IN "XtOrderProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Cardinal (*XtOrderProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Passes the newly created widget.
+.LP
+.eM
+Composite widgets that allow clients to order their children (usually
+homogeneous boxes) can call their widget instance's insert_position
+procedure from the class's insert_child procedure to determine where a new
+child should go in its \fIchildren\fP array.
+Thus, a client using a composite class can apply different sorting criteria
+to widget instances of the class, passing in a different insert_position
+procedure resource when it creates each composite widget instance.
+.LP
+The return value of the insert_position procedure
+indicates how many children should go before the widget.
+Returning zero indicates that the widget should go before all other children,
+and returning \fInum_children\fP indicates that it should go after all other children.
+The default insert_position function returns \fInum_children\fP
+and can be overridden by a specific composite widget's resource list
+or by the argument list provided when the composite widget is created.
+
+.NH 2
+Deletion of Children: The delete_child Procedure
+.XS
+\*(SN Deletion of Children: The delete_child Procedure
+.XE
+.LP
+.IN "delete_child procedure"
+.LP
+To remove the child from the parent's \fIchildren\fP list, the
+.PN XtDestroyWidget
+function eventually causes a call to the Composite parent's class delete_child
+procedure.
+The delete_child procedure pointer is of type
+.PN XtWidgetProc .
+.LP
+.IN "delete_child procedure" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtWidgetProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP
+Passes the child being deleted.
+.LP
+.eM
+Most widgets inherit the delete_child procedure from their superclass.
+Composite widgets that create companion widgets define their own
+delete_child procedure to remove these companion widgets.
+
+.NH 2
+Adding and Removing Children from the Managed Set
+.XS
+\fB\*(SN Adding and Removing Children from the Managed Set\fP
+.XE
+.LP
+The \*(xI provide a set of generic routines to permit the addition of
+widgets to or the removal of widgets from a composite widget's managed set.
+.IN "change_managed procedure"
+These generic routines eventually call the composite widget's change_managed
+procedure if the procedure pointer is non-NULL.
+The change_managed procedure pointer is of type
+.PN XtWidgetProc .
+The widget argument specifies the composite widget whose managed child
+set has been modified.
+
+.NH 3
+Managing Children
+.XS
+\fB\*(SN Managing Children\fP
+.XE
+.LP
+To add a list of widgets to the geometry-managed (and hence displayable)
+subset of their Composite parent, use
+.PN XtManageChildren .
+.LP
+.IN "XtManageChildren" "" "@DEF@"
+.sM
+.FD 0
+typedef Widget *WidgetList;
+.sp
+void XtManageChildren(\fIchildren\fP, \fInum_children\fP)
+.br
+      WidgetList \fIchildren\fP;
+.br
+      Cardinal \fInum_children\fP;
+.FN
+.IP \fIchildren\fP 1i
+Specifies a list of child widgets.  Each child must be of class
+RectObj or any subclass thereof.
+.IP \fInum_children\fP 1i
+Specifies the number of children in the list.
+.LP
+.eM
+The
+.PN XtManageChildren
+function performs the following:
+.IP \(bu 5
+Issues an error if the children do not all have the same parent or
+if the parent's class is not a subclass of 
+.PN compositeWidgetClass .
+.IP \(bu 5
+Returns immediately if the common parent is being destroyed;
+otherwise, for each unique child on the list,
+.PN XtManageChildren
+ignores the child if it already is managed or is being destroyed,
+and marks it if not.
+.IP \(bu 5
+If the parent is realized and after all children have been marked,
+it makes some of the newly managed children viewable:
+.RS
+.IP \- 5
+Calls the change_managed routine of the widgets' parent.
+.IP \- 5
+Calls
+.PN XtRealizeWidget
+on each previously unmanaged child that is unrealized.
+.IP \- 5
+Maps each previously unmanaged child that has \fImap_when_managed\fP 
+.PN True .
+.RE
+.LP
+Managing children is independent of the ordering of children and
+independent of creating and deleting children.
+The layout routine of the parent
+should consider children whose \fImanaged\fP field is
+.PN True 
+and should ignore all other children.
+Note that some composite widgets, especially fixed boxes, call
+.PN XtManageChild
+from their insert_child procedure.
+.LP
+If the parent widget is realized,
+its change_managed procedure is called to notify it
+that its set of managed children has changed.
+The parent can reposition and resize any of its children.
+It moves each child as needed by calling 
+.PN XtMoveWidget ,
+which first updates the \fIx\fP and \fIy\fP fields and which then calls
+.PN XMoveWindow .
+.LP
+If the composite widget wishes to change the size or border width of any of
+its children, it calls 
+.PN XtResizeWidget ,
+which first updates the
+\fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
+fields and then calls
+.PN XConfigureWindow .
+Simultaneous repositioning and resizing may be done with
+.PN XtConfigureWidget ;
+see Section 6.6.
+.sp
+.LP
+To add a single child to its parent widget's set of managed children, use
+.PN XtManageChild .
+.LP
+.IN "XtManageChild" "" "@DEF@"
+.sM
+.FD 0
+void XtManageChild(\fIchild\fP)
+.br
+      Widget \fIchild\fP;
+.FN
+.IP \fIchild\fP 1i
+Specifies the child.  \*(rI
+.LP
+.eM
+The
+.PN XtManageChild
+function constructs a
+.PN WidgetList
+of length 1 and calls
+.PN XtManageChildren .
+.sp
+.LP
+To create and manage a child widget in a single procedure, use
+.PN XtCreateManagedWidget
+or
+.PN XtVaCreateManagedWidget .
+.LP
+.IN "XtCreateManagedWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Widget \fIparent\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the resource instance name for the created widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created widget.  \*(rC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  Must be of class Composite or any
+subclass thereof.
+.IP \fIargs\fP 1i
+Specifies the argument list to override any other resource specifications.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtCreateManagedWidget
+function is a convenience routine that calls
+.PN XtCreateWidget
+and
+.PN XtManageChild .
+.sp
+.LP
+.IN "XtVaCreateManagedWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Widget \fIparent\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the resource instance name for the created widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created widget.  \*(rC
+.IP \fIparent\fP 1i
+Specifies the parent widget.  Must be of class Composite or any
+subclass thereof.
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+.PN XtVaCreateManagedWidget
+is identical in function to
+.PN XtCreateManagedWidget
+with the \fIargs\fP and \fInum_args\fP parameters replaced
+by a varargs list, as described in Section 2.5.1.
+
+.NH 3
+Unmanaging Children
+.XS
+\fB\*(SN Unmanaging Children\fP
+.XE
+.LP
+To remove a list of children from a parent widget's managed list, use
+.PN XtUnmanageChildren .
+.LP
+.IN "XtUnmanageChildren" "" "@DEF@"
+.sM
+.FD 0
+void XtUnmanageChildren(\fIchildren\fP, \fInum_children\fP)
+.br
+      WidgetList \fIchildren\fP;
+.br
+      Cardinal \fInum_children\fP;
+.FN
+.IP \fIchildren\fP 1i
+Specifies a list of child widgets.  Each child must be of class
+RectObj or any subclass thereof.
+.IP \fInum_children\fP 1i
+Specifies the number of children.
+.LP
+.eM
+The
+.PN XtUnmanageChildren
+function performs the following:
+.IP \(bu 5
+Returns immediately if the common parent is being destroyed.
+.IP \(bu 5
+Issues an error if the children do not all have the same parent
+or if the parent is not a subclass of 
+.PN compositeWidgetClass .
+.IP \(bu 5
+For each unique child on the list, 
+.PN XtUnmanageChildren
+ignores the child if it is unmanaged; otherwise it performs the following:
+.RS
+.IP \- 5
+Marks the child as unmanaged.
+.IP \- 5
+If the child is realized and the \fImap_when_managed\fP field is
+.PN True ,
+it is unmapped.
+.RE
+.IP \(bu 5
+If the parent is realized and if any children have become unmanaged,
+calls the change_managed routine of the widgets' parent.
+.LP
+.PN XtUnmanageChildren
+does not destroy the child widgets.
+Removing widgets from a parent's managed set is often a temporary banishment,
+and some time later the client may manage the children again.
+To destroy widgets entirely,
+.PN XtDestroyWidget
+should be called instead;
+see Section 2.9.
+.sp
+.LP
+To remove a single child from its parent widget's managed set, use
+.PN XtUnmanageChild .
+.LP
+.IN "XtUnmanageChild" "" "@DEF@"
+.sM
+.FD 0
+void XtUnmanageChild(\fIchild\fP)
+.br
+      Widget \fIchild\fP;
+.FN
+.IP \fIchild\fP 1i
+Specifies the child.  \*(rI
+.LP
+.eM
+The
+.PN XtUnmanageChild
+function constructs a widget list
+of length 1 and calls
+.PN XtUnmanageChildren .
+.LP
+These functions are low-level routines that are used by generic
+composite widget building routines.
+In addition, composite widgets can provide widget-specific,
+high-level convenience procedures.
+
+.NH 3
+Bundling Changes to the Managed Set
+.XS
+\fB\*(SN Bundling Changes to the Managed Set\fP
+.XE
+.LP
+A client may simultaneously unmanage and manage children
+with a single call to the \*(xI.  In this same call the
+client may provide a callback procedure that can modify the
+geometries of one or more children.  The composite widget class
+defines whether this single client call results in separate invocations
+of the change_managed method, one to unmanage and the other to
+manage, or in just a single invocation.
+.\" .LP
+.\" The composite widget class specifies how its change_managed method
+.\" should be invoked by declaring a
+.\" .PN CompositeClassExtension
+.\" structure as described in section 1.4.2.1.  If the
+.\" \fIallows_change_managed_set\fP field in the
+.\" .PN CompositeClassExtension
+.\" record is
+.\" .PN False ,
+.\" the change_managed method will be invoked twice; once before any
+.\" geometry changes are requested by the client callback and once
+.\" after.  If the \fIallows_change_managed_set\fP field is
+.\" .PN True ,
+.\" the change_managed method will be invoked just once after the
+.\" specified children have been marked as unmanaged or managed and
+.\" the client's callback has been invoked.
+.\" If no
+.\" .PN CompositeClassExtension
+.\" record is found in the extension field of the
+.\" composite class part with record type
+.\" .PN \s-1NULLQUARK\s+1
+.\" and version greater
+.\" than 1 and if
+.\" .PN XtInheritChangeManaged
+.\" was specified in the class record during class initialization, the
+.\" value of the \fIallows_change_managed_set\fP
+.\" field will be inherited from the superclass.
+.LP
+To simultaneously remove from and add to the geometry-managed
+set of children of a composite parent, use
+.PN XtChangeManagedSet .
+.LP
+.IN "XtChangeManagedSet" "" "@DEF@"
+.sM
+.FD 0
+void XtChangeManagedSet(\fIunmanage_children\fP, \fInum_unmanage_children\fP,
+                                              \fIdo_change_proc\fP, \fIclient_data\fP,
+                                              \fImanage_children\fP, \fInum_manage_children\fP)
+.br
+      WidgetList \fIunmanage_children\fP;
+.br
+      Cardinal \fInum_unmanage_children\fP;
+.br
+      XtDoChangeProc \fIdo_change_proc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      WidgetList \fImanage_children\fP;
+.br
+      Cardinal \fInum_manage_children\fP;
+.FN
+.IP \fIunmanage_children\fP 1.8i
+Specifies the list of widget children to initially remove from the managed set.
+.IP \fInum_unmanage_children\fP 1.8i
+Specifies the number of entries in the \fIunmanage_children\fP list.
+.IP \fIdo_change_proc\fP 1.8i
+Specifies a procedure to invoke between unmanaging
+and managing the children, or NULL.
+.IP \fIclient_data\fP 1.8i
+Specifies client data to be passed to the do_change_proc.
+.IP \fImanage_children\fP 1.8i
+Specifies the list of widget children to finally add to the managed set.
+.IP \fInum_manage_children\fP 1.8i
+Specifies the number of entries in the \fImanage_children\fP list.
+.LP
+.eM
+The 
+.PN XtChangeManagedSet
+function performs the following:
+.IP \(bu 5
+Returns immediately if \fInum_unmanage_children\fP and
+\fInum_manage_children\fP are both 0.
+.IP \(bu 5
+Issues a warning and returns if the widgets specified in the
+\fImanage_children\fP and
+the \fIunmanage_children\fP lists do not all have the same parent or if
+that parent is not a subclass of
+.PN compositeWidgetClass .
+.IP \(bu 5
+Returns immediately if the common parent is being destroyed.
+.IP \(bu 5
+If \fIdo_change_proc\fP is not NULL and the parent's
+.PN CompositeClassExtension
+\fIallows_change_managed_set\fP field is
+.PN False ,
+then
+.PN XtChangeManagedSet
+performs the following:
+.RS
+.IP \- 5
+Calls
+.PN XtUnmanageChildren
+(\fIunmanage_children\fP, \fInum_unmanage_children\fP).
+.IP \- 5
+Calls the \fIdo_change_proc\fP.
+.IP \- 5
+Calls
+.PN XtManageChildren
+(\fImanage_children\fP, \fInum_manage_children\fP).
+.RE
+.IP \(bu 5
+Otherwise, the following is performed:
+.RS
+.IP \- 5
+For each child on the \fIunmanage_children\fP list; if the child is
+already unmanaged it is ignored, otherwise it is marked as unmanaged,
+and if it is realized and its \fImap_when_managed\fP field is
+.PN True ,
+it is unmapped.
+.IP \- 5
+If \fIdo_change_proc\fP is non-NULL, the procedure is invoked.
+.IP \- 5
+For each child on the \fImanage_children\fP list; if the child is already
+managed or is being destroyed, it is ignored; otherwise it is 
+marked as managed.
+.IP \- 5
+If the parent is realized and after all children have been marked,
+the change_managed method of the parent is invoked, and subsequently 
+some of the newly managed children are made viewable by calling
+.PN XtRealizeWidget
+on each previously unmanaged child that is unrealized and
+mapping each previously unmanaged child that has \fImap_when_managed\fP
+.PN True .
+.RE
+.LP
+If no
+.PN CompositeClassExtension
+record is found in the parent's composite class part \fIextension\fP field
+with record type
+.PN \s-1NULLQUARK\s+1
+and version greater than 1, and if
+.PN XtInheritChangeManaged
+was specified in the parent's class record during class initialization,
+the value of the \fIallows_change_managed_set\fP
+field is inherited from the superclass.  The value inherited from
+.PN compositeWidgetClass
+for the \fIallows_change_managed_set\fP field is
+.PN False .
+.LP
+It is not an error to include a child in both the \fIunmanage_children\fP
+and the \fImanage_children\fP lists.  The effect of such a call is that
+the child remains managed following the call, but the \fIdo_change_proc\fP is
+able to affect the child while it is in an unmanaged state.
+.sp
+.LP
+The \fIdo_change_proc\fP is of type
+.PN XtDoChangeProc .
+.LP
+.IN "XtDoChangeProc" "" "@DEF"
+.sM
+.FD 0
+typedef void (*XtDoChangeProc)(Widget, WidgetList, Cardinal*, WidgetList, Cardinal*, XtPointer);
+.br
+      Widget \fIcomposite_parent\fP;
+.br
+      WidgetList \fIunmange_children\fP;
+.br
+      Cardinal *\fInum_unmanage_children\fP;
+.br
+      WidgetList \fImanage_children\fP;
+.br
+      Cardinal *\fInum_manage_children\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIcomposite_parent\fP 1.8i
+Passes the composite parent whose managed set is being altered.
+.IP \fIunmanage_children\fP 1.8i
+Passes the list of children just removed from the managed set.
+.IP \fInum_unmanage_children\fP 1.8i
+Passes the number of entries in the \fIunmanage_children\fP list.
+.IP \fImanage_children\fP 1.8i
+Passes the list of children about to be added to the managed set.
+.IP \fInum_manage_children\fP 1.8i
+Passes the number of entries in the \fImanage_children\fP list.
+.IP \fIclient_data\fP 1.8i
+Passes the client data passed to
+.PN XtChangeManagedSet .
+.LP
+.eM
+The \fIdo_change_proc\fP procedure is used by the caller of
+.PN XtChangeManagedSet
+to make changes to one or more children at the point when the
+managed set contains the fewest entries.  These changes may
+involve geometry requests, and in this case the caller of
+.PN XtChangeManagedSet
+may take advantage of the fact that the \*(xI internally grant
+geometry requests made by unmanaged children without invoking
+the parent's geometry manager.  To achieve this advantage, if
+the \fIdo_change_proc\fP procedure
+changes the geometry of a child or of a descendant of a child, then
+that child should be included in the \fIunmanage_children\fP and
+\fImanage_children\fP lists.
+
+.NH 3
+Determining if a Widget Is Managed
+.XS
+\fB\*(SN Determining if a Widget Is Managed\fP
+.XE
+.LP
+To determine the managed state of a given child widget, use
+.PN XtIsManaged .
+.LP
+.IN "XtIsManaged" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtIsManaged(\fIw\fP)
+.br
+       Widget \fIw\fP\^;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(oI
+.LP
+.eM
+The
+.PN XtIsManaged
+function returns
+.PN True
+if the specified widget is of class RectObj or any subclass thereof
+and is managed, or
+.PN False
+otherwise.
+
+.NH 2
+Controlling When Widgets Get Mapped
+.XS
+\fB\*(SN Controlling When Widgets Get Mapped\fP
+.XE
+.LP
+A widget is normally mapped if it is managed.
+However,
+this behavior can be overridden by setting the XtNmappedWhenManaged resource
+for the widget when it is created
+or by setting the \fImap_when_managed\fP field to 
+.PN False .
+.sp
+.LP
+To change the value of a given widget's \fImap_when_managed\fP field, use
+.PN XtSetMappedWhenManaged .
+.LP
+.IN "XtSetMappedWhenManaged" "" "@DEF@"
+.sM
+.FD 0
+void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Boolean \fImap_when_managed\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.IP \fImap_when_managed\fP 1i
+Specifies a Boolean value that indicates the new value
+that is stored into the widget's \fImap_when_managed\fP 
+field.
+.LP
+.eM
+If the widget is realized and managed,
+and if \fImap_when_managed\fP is 
+.PN True ,
+.PN XtSetMappedWhenManaged
+maps the window.
+If the widget is realized and managed,
+and if \fImap_when_managed\fP is 
+.PN False ,
+it unmaps the window.
+.PN XtSetMappedWhenManaged
+is a convenience function that is equivalent to (but slightly faster than)
+calling
+.PN XtSetValues
+and setting the new value for the XtNmappedWhenManaged resource
+then mapping the widget as appropriate.
+As an alternative to using
+.PN XtSetMappedWhenManaged
+to control mapping,
+a client may set \fImapped_when_managed\fP to
+.PN False
+and use
+.PN XtMapWidget
+and
+.PN XtUnmapWidget
+explicitly.
+.sp
+.LP
+To map a widget explicitly, use
+.PN XtMapWidget .
+.LP
+.IN "XtMapWidget" "" "@DEF@"
+.sM
+.FD 0
+XtMapWidget(\fIw\fP)
+.br
+     Widget \fIw\fP\^;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+To unmap a widget explicitly, use
+.PN XtUnmapWidget .
+.LP
+.IN "XtUnmapWidget" "" "@DEF@"
+.sM
+.FD 0
+XtUnmapWidget(\fIw\fP)
+.br
+     Widget \fIw\fP\^;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(cI
+.LP
+.eM
+
+.NH 2
+Constrained Composite Widgets
+.XS
+\*(SN Constrained Composite Widgets
+.XE
+.LP
+The Constraint 
+widget class is a subclass of
+.PN compositeWidgetClass .
+The name is derived from the fact that constraint widgets
+may manage the geometry 
+of their children based on constraints associated with each child.
+These constraints can be as simple as the maximum width and height 
+the parent will allow the child to occupy or can be as complicated as
+how other children should change if this child is moved or resized.
+Constraint
+widgets let a parent define constraints as resources that are supplied for their children.
+For example, if the
+Constraint
+parent defines the maximum sizes for its children,
+these new size resources are retrieved for each child as if they were
+resources that were defined by the child widget's class.
+Accordingly,
+constraint resources may be included in the argument list or resource file just
+like any other resource for the child.
+.LP
+Constraint 
+widgets have all the responsibilities of normal composite widgets
+and, in addition, must process and act upon the constraint information
+associated with each of their children.
+.LP
+To make it easy for widgets and the \*(xI to keep track of the
+constraints associated with a child, 
+every widget has a \fIconstraints\fP field,
+which is the address of a parent-specific structure that contains
+constraint information about the child.
+If a child's parent does not belong to a subclass of
+.PN constraintWidgetClass ,
+then the child's \fIconstraints\fP field is NULL.
+.LP
+Subclasses of
+Constraint 
+can add constraint data to the constraint record defined by their superclass.
+To allow this, widget writers should define the constraint
+records in their private .h file by using the same conventions as used for
+widget records.
+For example, a widget class that needs to maintain a maximum
+width and height for each child might define its constraint record as
+follows:
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	Dimension max_width, max_height;
+} MaxConstraintPart;
+
+typedef struct {
+	MaxConstraintPart max;
+} MaxConstraintRecord, *MaxConstraint;
+.De
+.LP
+A subclass of this widget class that also needs to maintain a minimum size would
+define its constraint record as follows:
+.LP
+.Ds
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	Dimension min_width, min_height;
+} MinConstraintPart;
+
+typedef struct {
+	MaxConstraintPart max;
+	MinConstraintPart min;
+} MaxMinConstraintRecord, *MaxMinConstraint;
+.De
+.LP
+Constraints are allocated, initialized, deallocated, and otherwise maintained
+insofar as possible by the \*(xI.
+The Constraint class record part has several entries that facilitate this.
+All entries in
+.PN ConstraintClassPart
+are fields and procedures that are defined and implemented by the parent,
+but they are called whenever actions are performed on the parent's children.
+.LP
+The
+.PN XtCreateWidget
+function uses the \fIconstraint_size\fP field in the parent's class record
+to allocate a constraint record when a child is created.
+.PN XtCreateWidget
+also uses the constraint resources to fill in resource fields in the
+constraint record associated with a child.
+It then calls the constraint initialize procedure so that the parent
+can compute constraint fields that are derived from constraint resources
+and can possibly move or resize the child to conform to the given constraints.
+.LP
+When the
+.PN XtGetValues
+and
+.PN XtSetValues
+functions are executed
+on a child, they use the constraint resources to get the values or
+set the values of constraints associated with that child.
+.PN XtSetValues
+then calls the constraint set_values procedures so that the parent can
+recompute derived constraint fields and move or resize the child
+as appropriate.
+If a
+Constraint
+widget class or any of its superclasses have declared a
+.PN ConstraintClassExtension
+record in the
+.PN ConstraintClassPart
+\fIextension\fP
+fields with a record type of
+.PN \s-1NULLQUARK\s+1
+and the \fIget_values_hook\fP field in
+.IN "get_values_hook procedure"
+.IN "Constraint" "get_values_hook"
+the extension record is non-NULL,
+.PN XtGetValues
+calls the get_values_hook
+procedure(s) to allow the parent to return derived constraint fields.
+.LP
+The
+.PN XtDestroyWidget
+function calls the constraint destroy procedure to deallocate any
+dynamic storage associated with a constraint record.
+The constraint record itself must not be deallocated by the constraint
+destroy procedure;
+.PN XtDestroyWidget
+does this automatically.
+.bp