diff options
Diffstat (limited to 'libXt/specs/CH03')
| -rw-r--r-- | libXt/specs/CH03 | 1031 |
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 |