aboutsummaryrefslogtreecommitdiff
path: root/libXt/specs/CH03
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2012-04-10 15:05:45 +0200
committermarha <marha@users.sourceforge.net>2012-04-10 15:05:45 +0200
commit4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8 (patch)
tree3ddf28be6916dd5ea27837431b5be8c94017cd9a /libXt/specs/CH03
parent5564e91e3cf4ba5cb2fbebbc2d63d18f588016b8 (diff)
parent5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 (diff)
downloadvcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.tar.gz
vcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.tar.bz2
vcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.zip
Merge remote-tracking branch 'origin/released'
Diffstat (limited to 'libXt/specs/CH03')
-rw-r--r--libXt/specs/CH031031
1 files changed, 0 insertions, 1031 deletions
diff --git a/libXt/specs/CH03 b/libXt/specs/CH03
deleted file mode 100644
index f96a79781..000000000
--- a/libXt/specs/CH03
+++ /dev/null
@@ -1,1031 +0,0 @@
-.\" $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