1 .\" $Xorg: CH03,v 1.3 2000/08/17 19:42:44 cpqbld Exp $
2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
5 .\" Permission is hereby granted, free of charge, to any person obtaining
6 .\" a copy of this software and associated documentation files (the
7 .\" "Software"), to deal in the Software without restriction, including
8 .\" without limitation the rights to use, copy, modify, merge, publish,
9 .\" distribute, sublicense, and/or sell copies of the Software, and to
10 .\" permit persons to whom the Software is furnished to do so, subject to
11 .\" the following conditions:
13 .\" The above copyright notice and this permission notice shall be included
14 .\" in all copies or substantial portions of the Software.
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
20 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 .\" OTHER DEALINGS IN THE SOFTWARE.
24 .\" Except as contained in this notice, the name of the X Consortium shall
25 .\" not be used in advertising or otherwise to promote the sale, use or
26 .\" other dealings in this Software without prior written authorization
27 .\" from the X Consortium.
29 .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
30 .\" Digital Equipment Corporation, Maynard, Massachusetts.
32 .\" Permission to use, copy, modify and distribute this documentation for any
33 .\" purpose and without fee is hereby granted, provided that the above copyright
34 .\" notice appears in all copies and that both that copyright notice and this
35 .\" permission notice appear in supporting documentation, and that the name of
36 .\" Digital not be used in in advertising or publicity pertaining
37 .\" to distribution of the software without specific, written prior permission.
38 .\" Digital makes no representations about the suitability of the
39 .\" software described herein for any purpose.
40 .\" It is provided ``as is'' without express or implied warranty.
45 \s+1\fBChapter 3\fP\s-1
47 \s+1\fBComposite Widgets and Their Children\fP\s-1
56 Chapter 3 \(em Composite Widgets and Their Children
58 .IN "Composite widgets"
59 Composite widgets (widgets whose class is a subclass of
60 .PN compositeWidgetClass )
61 can have an arbitrary number of children.
62 Consequently, they are responsible for much more than primitive widgets.
63 Their responsibilities (either implemented directly by the widget class
64 or indirectly by \*(xI functions) include:
66 Overall management of children from creation to destruction.
68 Destruction of descendants when the composite widget is destroyed.
70 Physical arrangement (geometry management) of a displayable subset of
71 children (that is, the managed children).
73 Mapping and unmapping of a subset of the managed children.
75 Overall management is handled by the generic procedures
80 adds children to their parent by calling the parent's insert_child
83 removes children from their parent by calling the parent's delete_child
84 procedure and ensures that all children of a destroyed composite widget
87 Only a subset of the total number of children is actually managed by
88 the geometry manager and hence possibly visible.
89 For example, a composite editor widget
90 supporting multiple editing buffers might allocate one child
91 widget for each file buffer,
92 but it might display only a small number of the existing buffers.
93 Widgets that are in this displayable subset are called managed widgets
94 and enter into geometry manager calculations.
95 The other children are called unmanaged widgets
96 and, by definition, are not mapped by the \*(xI.
98 Children are added to and removed from their parent's managed set by using
100 .PN XtManageChildren ,
101 .PN XtUnmanageChild ,
102 .PN XtUnmanageChildren ,
104 .PN XtChangeManagedSet ,
105 which notify the parent to recalculate the physical layout of its children
106 by calling the parent's change_managed procedure.
108 .PN XtCreateManagedWidget
109 convenience function calls
115 Most managed children are mapped,
116 but some widgets can be in a state where they take up physical space
117 but do not show anything.
118 Managed widgets are not mapped automatically
119 if their \fImap_when_managed\fP field is
123 and is changed by using
124 .PN XtSetMappedWhenManaged .
126 Each composite widget class declares a geometry manager,
127 which is responsible for figuring out where the managed children
128 should appear within the composite widget's window.
129 Geometry management techniques fall into four classes:
130 .IP "Fixed boxes" 1.6i
131 Fixed boxes have a fixed number of children created by the parent.
132 All these children are managed,
133 and none ever makes geometry manager requests.
134 .IP "Homogeneous boxes" 1.6i
135 Homogeneous boxes treat all children equally and apply the same geometry
136 constraints to each child.
137 Many clients insert and delete widgets freely.
138 .IP "Heterogeneous boxes" 1.6i
139 Heterogeneous boxes have a specific location where each child is placed.
140 This location usually is not specified in pixels,
141 because the window may be resized, but is expressed rather
142 in terms of the relationship between a child
143 and the parent or between the child and other specific children.
144 The class of heterogeneous boxes is usually a subclass of
146 .IP "Shell boxes" 1.6i
147 Shell boxes typically have only one child,
148 and the child's size is usually
149 exactly the size of the shell.
150 The geometry manager must communicate with the window manager, if it exists,
151 and the box must also accept
153 events when the window size is changed by the window manager.
156 Addition of Children to a Composite Widget: The insert_child Procedure
158 \*(SN Addition of Children to a Composite Widget: The insert_child Procedure
161 .IN "insert_child procedure"
163 the parent's list of children, the
165 function calls the parent's class routine insert_child.
166 The insert_child procedure pointer in a composite widget is of type
169 .IN "insert_child procedure" "" "@DEF@"
172 typedef void (*XtWidgetProc)(Widget);
177 Passes the newly created child.
180 Most composite widgets inherit their superclass's operation.
181 The insert_child routine in
182 .PN CompositeWidgetClass calls the insert_position procedure
183 and inserts the child at the specified position
184 in the \fIchildren\fP list, expanding it if necessary.
186 Some composite widgets define their own insert_child routine
187 so that they can order their children in some convenient way,
188 create companion controller widgets for a new widget,
189 or limit the number or class of their child widgets.
190 A composite widget class that wishes
191 to allow nonwidget children (see Chapter 12) must specify a
192 .PN CompositeClassExtension
193 extension record as described
194 in Section 1.4.2.1 and set the \fIaccepts_objects\fP field in this record to
197 .PN CompositeClassExtension
198 record is not specified or the
199 \fIaccepts_objects\fP field is
201 the composite widget can assume that all its children are of a subclass of Core
202 without an explicit subclass test in the insert_child procedure.
204 If there is not enough room to insert a new child in the \fIchildren\fP array
205 (that is, \fInum_children\fP is equal to \fInum_slots\fP),
206 the insert_child procedure must first reallocate the array
207 and update \fInum_slots\fP.
208 The insert_child procedure then places the child at the appropriate position
209 in the array and increments the \fInum_children\fP field.
212 Insertion Order of Children: The insert_position Procedure
214 \fB\*(SN Insertion Order of Children: The insert_position Procedure\fP
217 Instances of composite widgets sometimes need to specify more about the order in which
218 their children are kept.
220 an application may want a set of command buttons in some logical order
222 and it may want buttons that represent file names to be kept
223 in alphabetical order without constraining the order in which the
226 An application controls the presentation order of a set of children by
228 .IN XtNinsertPosition
231 The insert_position procedure pointer in a composite widget instance is of type
234 .IN "XtOrderProc" "" "@DEF@"
237 typedef Cardinal (*XtOrderProc)(Widget);
242 Passes the newly created widget.
245 Composite widgets that allow clients to order their children (usually
246 homogeneous boxes) can call their widget instance's insert_position
247 procedure from the class's insert_child procedure to determine where a new
248 child should go in its \fIchildren\fP array.
249 Thus, a client using a composite class can apply different sorting criteria
250 to widget instances of the class, passing in a different insert_position
251 procedure resource when it creates each composite widget instance.
253 The return value of the insert_position procedure
254 indicates how many children should go before the widget.
255 Returning zero indicates that the widget should go before all other children,
256 and returning \fInum_children\fP indicates that it should go after all other children.
257 The default insert_position function returns \fInum_children\fP
258 and can be overridden by a specific composite widget's resource list
259 or by the argument list provided when the composite widget is created.
262 Deletion of Children: The delete_child Procedure
264 \*(SN Deletion of Children: The delete_child Procedure
267 .IN "delete_child procedure"
269 To remove the child from the parent's \fIchildren\fP list, the
271 function eventually causes a call to the Composite parent's class delete_child
273 The delete_child procedure pointer is of type
276 .IN "delete_child procedure" "" "@DEF@"
279 typedef void (*XtWidgetProc)(Widget);
284 Passes the child being deleted.
287 Most widgets inherit the delete_child procedure from their superclass.
288 Composite widgets that create companion widgets define their own
289 delete_child procedure to remove these companion widgets.
292 Adding and Removing Children from the Managed Set
294 \fB\*(SN Adding and Removing Children from the Managed Set\fP
297 The \*(xI provide a set of generic routines to permit the addition of
298 widgets to or the removal of widgets from a composite widget's managed set.
299 .IN "change_managed procedure"
300 These generic routines eventually call the composite widget's change_managed
301 procedure if the procedure pointer is non-NULL.
302 The change_managed procedure pointer is of type
304 The widget argument specifies the composite widget whose managed child
305 set has been modified.
310 \fB\*(SN Managing Children\fP
313 To add a list of widgets to the geometry-managed (and hence displayable)
314 subset of their Composite parent, use
315 .PN XtManageChildren .
317 .IN "XtManageChildren" "" "@DEF@"
320 typedef Widget *WidgetList;
322 void XtManageChildren(\fIchildren\fP, \fInum_children\fP)
324 WidgetList \fIchildren\fP;
326 Cardinal \fInum_children\fP;
328 .IP \fIchildren\fP 1i
329 Specifies a list of child widgets. Each child must be of class
330 RectObj or any subclass thereof.
331 .IP \fInum_children\fP 1i
332 Specifies the number of children in the list.
337 function performs the following:
339 Issues an error if the children do not all have the same parent or
340 if the parent's class is not a subclass of
341 .PN compositeWidgetClass .
343 Returns immediately if the common parent is being destroyed;
344 otherwise, for each unique child on the list,
346 ignores the child if it already is managed or is being destroyed,
349 If the parent is realized and after all children have been marked,
350 it makes some of the newly managed children viewable:
353 Calls the change_managed routine of the widgets' parent.
357 on each previously unmanaged child that is unrealized.
359 Maps each previously unmanaged child that has \fImap_when_managed\fP
363 Managing children is independent of the ordering of children and
364 independent of creating and deleting children.
365 The layout routine of the parent
366 should consider children whose \fImanaged\fP field is
368 and should ignore all other children.
369 Note that some composite widgets, especially fixed boxes, call
371 from their insert_child procedure.
373 If the parent widget is realized,
374 its change_managed procedure is called to notify it
375 that its set of managed children has changed.
376 The parent can reposition and resize any of its children.
377 It moves each child as needed by calling
379 which first updates the \fIx\fP and \fIy\fP fields and which then calls
382 If the composite widget wishes to change the size or border width of any of
383 its children, it calls
385 which first updates the
386 \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
387 fields and then calls
388 .PN XConfigureWindow .
389 Simultaneous repositioning and resizing may be done with
390 .PN XtConfigureWidget ;
394 To add a single child to its parent widget's set of managed children, use
397 .IN "XtManageChild" "" "@DEF@"
400 void XtManageChild(\fIchild\fP)
405 Specifies the child. \*(rI
410 function constructs a
412 of length 1 and calls
413 .PN XtManageChildren .
416 To create and manage a child widget in a single procedure, use
417 .PN XtCreateManagedWidget
419 .PN XtVaCreateManagedWidget .
421 .IN "XtCreateManagedWidget" "" "@DEF@"
424 Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
425 \fIargs\fP, \fInum_args\fP)
429 WidgetClass \fIwidget_class\fP;
435 Cardinal \fInum_args\fP;
438 Specifies the resource instance name for the created widget.
439 .IP \fIwidget_class\fP 1i
440 Specifies the widget class pointer for the created widget. \*(rC
442 Specifies the parent widget. Must be of class Composite or any
445 Specifies the argument list to override any other resource specifications.
446 .IP \fInum_args\fP 1i
447 Specifies the number of entries in the argument list.
451 .PN XtCreateManagedWidget
452 function is a convenience routine that calls
458 .IN "XtVaCreateManagedWidget" "" "@DEF@"
461 Widget XtVaCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
465 WidgetClass \fIwidget_class\fP;
470 Specifies the resource instance name for the created widget.
471 .IP \fIwidget_class\fP 1i
472 Specifies the widget class pointer for the created widget. \*(rC
474 Specifies the parent widget. Must be of class Composite or any
477 Specifies the variable argument list to override any other
478 resource specifications.
481 .PN XtVaCreateManagedWidget
482 is identical in function to
483 .PN XtCreateManagedWidget
484 with the \fIargs\fP and \fInum_args\fP parameters replaced
485 by a varargs list, as described in Section 2.5.1.
490 \fB\*(SN Unmanaging Children\fP
493 To remove a list of children from a parent widget's managed list, use
494 .PN XtUnmanageChildren .
496 .IN "XtUnmanageChildren" "" "@DEF@"
499 void XtUnmanageChildren(\fIchildren\fP, \fInum_children\fP)
501 WidgetList \fIchildren\fP;
503 Cardinal \fInum_children\fP;
505 .IP \fIchildren\fP 1i
506 Specifies a list of child widgets. Each child must be of class
507 RectObj or any subclass thereof.
508 .IP \fInum_children\fP 1i
509 Specifies the number of children.
513 .PN XtUnmanageChildren
514 function performs the following:
516 Returns immediately if the common parent is being destroyed.
518 Issues an error if the children do not all have the same parent
519 or if the parent is not a subclass of
520 .PN compositeWidgetClass .
522 For each unique child on the list,
523 .PN XtUnmanageChildren
524 ignores the child if it is unmanaged; otherwise it performs the following:
527 Marks the child as unmanaged.
529 If the child is realized and the \fImap_when_managed\fP field is
534 If the parent is realized and if any children have become unmanaged,
535 calls the change_managed routine of the widgets' parent.
537 .PN XtUnmanageChildren
538 does not destroy the child widgets.
539 Removing widgets from a parent's managed set is often a temporary banishment,
540 and some time later the client may manage the children again.
541 To destroy widgets entirely,
543 should be called instead;
547 To remove a single child from its parent widget's managed set, use
548 .PN XtUnmanageChild .
550 .IN "XtUnmanageChild" "" "@DEF@"
553 void XtUnmanageChild(\fIchild\fP)
558 Specifies the child. \*(rI
563 function constructs a widget list
564 of length 1 and calls
565 .PN XtUnmanageChildren .
567 These functions are low-level routines that are used by generic
568 composite widget building routines.
569 In addition, composite widgets can provide widget-specific,
570 high-level convenience procedures.
573 Bundling Changes to the Managed Set
575 \fB\*(SN Bundling Changes to the Managed Set\fP
578 A client may simultaneously unmanage and manage children
579 with a single call to the \*(xI. In this same call the
580 client may provide a callback procedure that can modify the
581 geometries of one or more children. The composite widget class
582 defines whether this single client call results in separate invocations
583 of the change_managed method, one to unmanage and the other to
584 manage, or in just a single invocation.
586 .\" The composite widget class specifies how its change_managed method
587 .\" should be invoked by declaring a
588 .\" .PN CompositeClassExtension
589 .\" structure as described in section 1.4.2.1. If the
590 .\" \fIallows_change_managed_set\fP field in the
591 .\" .PN CompositeClassExtension
594 .\" the change_managed method will be invoked twice; once before any
595 .\" geometry changes are requested by the client callback and once
596 .\" after. If the \fIallows_change_managed_set\fP field is
598 .\" the change_managed method will be invoked just once after the
599 .\" specified children have been marked as unmanaged or managed and
600 .\" the client's callback has been invoked.
602 .\" .PN CompositeClassExtension
603 .\" record is found in the extension field of the
604 .\" composite class part with record type
605 .\" .PN \s-1NULLQUARK\s+1
606 .\" and version greater
608 .\" .PN XtInheritChangeManaged
609 .\" was specified in the class record during class initialization, the
610 .\" value of the \fIallows_change_managed_set\fP
611 .\" field will be inherited from the superclass.
613 To simultaneously remove from and add to the geometry-managed
614 set of children of a composite parent, use
615 .PN XtChangeManagedSet .
617 .IN "XtChangeManagedSet" "" "@DEF@"
620 void XtChangeManagedSet(\fIunmanage_children\fP, \fInum_unmanage_children\fP,
621 \fIdo_change_proc\fP, \fIclient_data\fP,
622 \fImanage_children\fP, \fInum_manage_children\fP)
624 WidgetList \fIunmanage_children\fP;
626 Cardinal \fInum_unmanage_children\fP;
628 XtDoChangeProc \fIdo_change_proc\fP;
630 XtPointer \fIclient_data\fP;
632 WidgetList \fImanage_children\fP;
634 Cardinal \fInum_manage_children\fP;
636 .IP \fIunmanage_children\fP 1.8i
637 Specifies the list of widget children to initially remove from the managed set.
638 .IP \fInum_unmanage_children\fP 1.8i
639 Specifies the number of entries in the \fIunmanage_children\fP list.
640 .IP \fIdo_change_proc\fP 1.8i
641 Specifies a procedure to invoke between unmanaging
642 and managing the children, or NULL.
643 .IP \fIclient_data\fP 1.8i
644 Specifies client data to be passed to the do_change_proc.
645 .IP \fImanage_children\fP 1.8i
646 Specifies the list of widget children to finally add to the managed set.
647 .IP \fInum_manage_children\fP 1.8i
648 Specifies the number of entries in the \fImanage_children\fP list.
652 .PN XtChangeManagedSet
653 function performs the following:
655 Returns immediately if \fInum_unmanage_children\fP and
656 \fInum_manage_children\fP are both 0.
658 Issues a warning and returns if the widgets specified in the
659 \fImanage_children\fP and
660 the \fIunmanage_children\fP lists do not all have the same parent or if
661 that parent is not a subclass of
662 .PN compositeWidgetClass .
664 Returns immediately if the common parent is being destroyed.
666 If \fIdo_change_proc\fP is not NULL and the parent's
667 .PN CompositeClassExtension
668 \fIallows_change_managed_set\fP field is
671 .PN XtChangeManagedSet
672 performs the following:
676 .PN XtUnmanageChildren
677 (\fIunmanage_children\fP, \fInum_unmanage_children\fP).
679 Calls the \fIdo_change_proc\fP.
683 (\fImanage_children\fP, \fInum_manage_children\fP).
686 Otherwise, the following is performed:
689 For each child on the \fIunmanage_children\fP list; if the child is
690 already unmanaged it is ignored, otherwise it is marked as unmanaged,
691 and if it is realized and its \fImap_when_managed\fP field is
695 If \fIdo_change_proc\fP is non-NULL, the procedure is invoked.
697 For each child on the \fImanage_children\fP list; if the child is already
698 managed or is being destroyed, it is ignored; otherwise it is
701 If the parent is realized and after all children have been marked,
702 the change_managed method of the parent is invoked, and subsequently
703 some of the newly managed children are made viewable by calling
705 on each previously unmanaged child that is unrealized and
706 mapping each previously unmanaged child that has \fImap_when_managed\fP
711 .PN CompositeClassExtension
712 record is found in the parent's composite class part \fIextension\fP field
714 .PN \s-1NULLQUARK\s+1
715 and version greater than 1, and if
716 .PN XtInheritChangeManaged
717 was specified in the parent's class record during class initialization,
718 the value of the \fIallows_change_managed_set\fP
719 field is inherited from the superclass. The value inherited from
720 .PN compositeWidgetClass
721 for the \fIallows_change_managed_set\fP field is
724 It is not an error to include a child in both the \fIunmanage_children\fP
725 and the \fImanage_children\fP lists. The effect of such a call is that
726 the child remains managed following the call, but the \fIdo_change_proc\fP is
727 able to affect the child while it is in an unmanaged state.
730 The \fIdo_change_proc\fP is of type
733 .IN "XtDoChangeProc" "" "@DEF"
736 typedef void (*XtDoChangeProc)(Widget, WidgetList, Cardinal*, WidgetList, Cardinal*, XtPointer);
738 Widget \fIcomposite_parent\fP;
740 WidgetList \fIunmange_children\fP;
742 Cardinal *\fInum_unmanage_children\fP;
744 WidgetList \fImanage_children\fP;
746 Cardinal *\fInum_manage_children\fP;
748 XtPointer \fIclient_data\fP;
750 .IP \fIcomposite_parent\fP 1.8i
751 Passes the composite parent whose managed set is being altered.
752 .IP \fIunmanage_children\fP 1.8i
753 Passes the list of children just removed from the managed set.
754 .IP \fInum_unmanage_children\fP 1.8i
755 Passes the number of entries in the \fIunmanage_children\fP list.
756 .IP \fImanage_children\fP 1.8i
757 Passes the list of children about to be added to the managed set.
758 .IP \fInum_manage_children\fP 1.8i
759 Passes the number of entries in the \fImanage_children\fP list.
760 .IP \fIclient_data\fP 1.8i
761 Passes the client data passed to
762 .PN XtChangeManagedSet .
765 The \fIdo_change_proc\fP procedure is used by the caller of
766 .PN XtChangeManagedSet
767 to make changes to one or more children at the point when the
768 managed set contains the fewest entries. These changes may
769 involve geometry requests, and in this case the caller of
770 .PN XtChangeManagedSet
771 may take advantage of the fact that the \*(xI internally grant
772 geometry requests made by unmanaged children without invoking
773 the parent's geometry manager. To achieve this advantage, if
774 the \fIdo_change_proc\fP procedure
775 changes the geometry of a child or of a descendant of a child, then
776 that child should be included in the \fIunmanage_children\fP and
777 \fImanage_children\fP lists.
780 Determining if a Widget Is Managed
782 \fB\*(SN Determining if a Widget Is Managed\fP
785 To determine the managed state of a given child widget, use
788 .IN "XtIsManaged" "" "@DEF@"
791 Boolean XtIsManaged(\fIw\fP)
796 Specifies the widget. \*(oI
803 if the specified widget is of class RectObj or any subclass thereof
809 Controlling When Widgets Get Mapped
811 \fB\*(SN Controlling When Widgets Get Mapped\fP
814 A widget is normally mapped if it is managed.
816 this behavior can be overridden by setting the XtNmappedWhenManaged resource
817 for the widget when it is created
818 or by setting the \fImap_when_managed\fP field to
822 To change the value of a given widget's \fImap_when_managed\fP field, use
823 .PN XtSetMappedWhenManaged .
825 .IN "XtSetMappedWhenManaged" "" "@DEF@"
828 void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP)
832 Boolean \fImap_when_managed\fP;
835 Specifies the widget. \*(cI
836 .IP \fImap_when_managed\fP 1i
837 Specifies a Boolean value that indicates the new value
838 that is stored into the widget's \fImap_when_managed\fP
842 If the widget is realized and managed,
843 and if \fImap_when_managed\fP is
845 .PN XtSetMappedWhenManaged
847 If the widget is realized and managed,
848 and if \fImap_when_managed\fP is
850 it unmaps the window.
851 .PN XtSetMappedWhenManaged
852 is a convenience function that is equivalent to (but slightly faster than)
855 and setting the new value for the XtNmappedWhenManaged resource
856 then mapping the widget as appropriate.
857 As an alternative to using
858 .PN XtSetMappedWhenManaged
860 a client may set \fImapped_when_managed\fP to
869 To map a widget explicitly, use
872 .IN "XtMapWidget" "" "@DEF@"
880 Specifies the widget. \*(cI
883 To unmap a widget explicitly, use
886 .IN "XtUnmapWidget" "" "@DEF@"
889 XtUnmapWidget(\fIw\fP)
894 Specifies the widget. \*(cI
899 Constrained Composite Widgets
901 \*(SN Constrained Composite Widgets
905 widget class is a subclass of
906 .PN compositeWidgetClass .
907 The name is derived from the fact that constraint widgets
908 may manage the geometry
909 of their children based on constraints associated with each child.
910 These constraints can be as simple as the maximum width and height
911 the parent will allow the child to occupy or can be as complicated as
912 how other children should change if this child is moved or resized.
914 widgets let a parent define constraints as resources that are supplied for their children.
917 parent defines the maximum sizes for its children,
918 these new size resources are retrieved for each child as if they were
919 resources that were defined by the child widget's class.
921 constraint resources may be included in the argument list or resource file just
922 like any other resource for the child.
925 widgets have all the responsibilities of normal composite widgets
926 and, in addition, must process and act upon the constraint information
927 associated with each of their children.
929 To make it easy for widgets and the \*(xI to keep track of the
930 constraints associated with a child,
931 every widget has a \fIconstraints\fP field,
932 which is the address of a parent-specific structure that contains
933 constraint information about the child.
934 If a child's parent does not belong to a subclass of
935 .PN constraintWidgetClass ,
936 then the child's \fIconstraints\fP field is NULL.
940 can add constraint data to the constraint record defined by their superclass.
941 To allow this, widget writers should define the constraint
942 records in their private .h file by using the same conventions as used for
944 For example, a widget class that needs to maintain a maximum
945 width and height for each child might define its constraint record as
952 Dimension max_width, max_height;
956 MaxConstraintPart max;
957 } MaxConstraintRecord, *MaxConstraint;
960 A subclass of this widget class that also needs to maintain a minimum size would
961 define its constraint record as follows:
967 Dimension min_width, min_height;
971 MaxConstraintPart max;
972 MinConstraintPart min;
973 } MaxMinConstraintRecord, *MaxMinConstraint;
976 Constraints are allocated, initialized, deallocated, and otherwise maintained
977 insofar as possible by the \*(xI.
978 The Constraint class record part has several entries that facilitate this.
980 .PN ConstraintClassPart
981 are fields and procedures that are defined and implemented by the parent,
982 but they are called whenever actions are performed on the parent's children.
986 function uses the \fIconstraint_size\fP field in the parent's class record
987 to allocate a constraint record when a child is created.
989 also uses the constraint resources to fill in resource fields in the
990 constraint record associated with a child.
991 It then calls the constraint initialize procedure so that the parent
992 can compute constraint fields that are derived from constraint resources
993 and can possibly move or resize the child to conform to the given constraints.
999 functions are executed
1000 on a child, they use the constraint resources to get the values or
1001 set the values of constraints associated with that child.
1003 then calls the constraint set_values procedures so that the parent can
1004 recompute derived constraint fields and move or resize the child
1008 widget class or any of its superclasses have declared a
1009 .PN ConstraintClassExtension
1011 .PN ConstraintClassPart
1013 fields with a record type of
1014 .PN \s-1NULLQUARK\s+1
1015 and the \fIget_values_hook\fP field in
1016 .IN "get_values_hook procedure"
1017 .IN "Constraint" "get_values_hook"
1018 the extension record is non-NULL,
1020 calls the get_values_hook
1021 procedure(s) to allow the parent to return derived constraint fields.
1025 function calls the constraint destroy procedure to deallocate any
1026 dynamic storage associated with a constraint record.
1027 The constraint record itself must not be deallocated by the constraint
1030 does this automatically.
projects / framework / uifw / xorg / lib / libxt.git / blob