From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH03.xml | 1406 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1406 insertions(+) create mode 100644 libXt/specs/CH03.xml (limited to 'libXt/specs/CH03.xml') diff --git a/libXt/specs/CH03.xml b/libXt/specs/CH03.xml new file mode 100644 index 000000000..2b2e1d730 --- /dev/null +++ b/libXt/specs/CH03.xml @@ -0,0 +1,1406 @@ + +Composite Widgets and Their Children + +Composite widgets (widgets whose class is a subclass of +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 Intrinsics functions) include: + + + + +Overall management of children from creation to destruction. + + + + +Destruction of descendants when the composite widget is destroyed. + + + + +Physical arrangement (geometry management) of a displayable subset of +children (that is, the managed children). + + + + +Mapping and unmapping of a subset of the managed children. + + + + +Overall management is handled by the generic procedures + +and +. + +adds children to their parent by calling the parent's insert_child +procedure. + +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. + + + +Only a subset of the total number of children is actually managed by +the geometry manager and hence possibly visible. +For example, a composite editor widget +supporting multiple editing buffers might allocate one child +widget for each file buffer, +but it might display only a small number of the existing buffers. +Widgets that are in this displayable subset are called managed widgets +and enter into geometry manager calculations. +The other children are called unmanaged widgets +and, by definition, are not mapped by the Intrinsics. + + + +Children are added to and removed from their parent's managed set by using +, +, +, +, +and +, +which notify the parent to recalculate the physical layout of its children +by calling the parent's change_managed procedure. +The + +convenience function calls + +and + +on the result. + + + +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 map_when_managed field is +False. +The default is +True +and is changed by using +. + + + +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: + + + Fixed boxes + + +Fixed boxes have a fixed number of children created by the parent. +All these children are managed, +and none ever makes geometry manager requests. + + + + + Homogeneous boxes + + +Homogeneous boxes treat all children equally and apply the same geometry +constraints to each child. +Many clients insert and delete widgets freely. + + + + + Heterogeneous boxes + + +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. + + + + + Shell boxes + + +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 +ConfigureNotify +events when the window size is changed by the window manager. + + + + + + +Addition of Children to a Composite Widget: The insert_child Procedure + +To add a child to +the parent's list of children, the + +function calls the parent's class routine insert_child. +The insert_child procedure pointer in a composite widget is of type +. + + + + +typedef void (*XtWidgetProc) + Widget w + + + + + + + w + + + +Passes the newly created child. + + + + + + +Most composite widgets inherit their superclass's operation. +The insert_child routine in +CompositeWidgetClass calls the insert_position procedure +and inserts the child at the specified position +in the children list, expanding it if necessary. + + + +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 ) must specify a +CompositeClassExtension +extension record as described +in +and set the accepts_objects field in this record to +True. +If the +CompositeClassExtension +record is not specified or the +accepts_objects field is +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. + + + +If there is not enough room to insert a new child in the children array +(that is, num_children is equal to num_slots), +the insert_child procedure must first reallocate the array +and update num_slots. +The insert_child procedure then places the child at the appropriate position +in the array and increments the num_children field. + + + + +Insertion Order of Children: The insert_position Procedure + +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. + + + +An application controls the presentation order of a set of children by +supplying an +XtNinsertPosition +resource. +The insert_position procedure pointer in a composite widget instance is of type +. + + + + +typedef Cardinal (*XtOrderProc) + + Widget w + + + + + + + w + + + +Passes the newly created widget. + + + + + + +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 children 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. + + + +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 num_children indicates that it should go after all other children. +The default insert_position function returns num_children +and can be overridden by a specific composite widget's resource list +or by the argument list provided when the composite widget is created. + + + + +Deletion of Children: The delete_child Procedure + + +To remove the child from the parent's children list, the + +function eventually causes a call to the Composite parent's class delete_child +procedure. +The delete_child procedure pointer is of type +. + + + + +typedef void (*XtWidgetProc) + Widget w + + + + + + + w + + + +Passes the child being deleted. + + + + + + + +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. + + + + +Adding and Removing Children from the Managed Set + +The Intrinsics provide a set of generic routines to permit the addition of +widgets to or the removal of widgets from a composite widget's managed set. +These generic routines eventually call the composite widget's change_managed +procedure if the procedure pointer is non-NULL. +The change_managed procedure pointer is of type +. +The widget argument specifies the composite widget whose managed child +set has been modified. + + + +Managing Children + +To add a list of widgets to the geometry-managed (and hence displayable) +subset of their Composite parent, use +. + + +typedef Widget *WidgetList; + + + +void XtManageChildren + WidgetList children + Cardinal num_children + + + + + + + children + + + +Specifies a list of child widgets. Each child must be of class +RectObj or any subclass thereof. + + + + + + num_children + + + +Specifies the number of children in the list. + + + + + + +The + +function performs the following: + + + + +Issues an error if the children do not all have the same parent or +if the parent's class is not a subclass of +compositeWidgetClass. + + + + +Returns immediately if the common parent is being destroyed; +otherwise, for each unique child on the list, + +ignores the child if it already is managed or is being destroyed, +and marks it if not. + + + + +If the parent is realized and after all children have been marked, +it makes some of the newly managed children viewable: + + + + + + +Calls the change_managed routine of the widgets' parent. + + + + +Calls + +on each previously unmanaged child that is unrealized. + + + + +Maps each previously unmanaged child that has map_when_managed +True. + + + + + + +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 managed field is +True +and should ignore all other children. +Note that some composite widgets, especially fixed boxes, call + +from their insert_child procedure. + + + +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 +, +which first updates the x and y fields and which then calls +XMoveWindow. + + + +If the composite widget wishes to change the size or border width of any of +its children, it calls +, +which first updates the +width, height, and border_width +fields and then calls +XConfigureWindow. +Simultaneous repositioning and resizing may be done with +; +see . + + + +To add a single child to its parent widget's set of managed children, use +. + + + + +void XtManageChild + Widget child + + + + + + + child + + + +Specifies the child. Must be of class RectObj or any subclass thereof. + + + + + + +The + +function constructs a +WidgetList +of length 1 and calls +. + + + +To create and manage a child widget in a single procedure, use + +or +. + + + + +Widget XtCreateManagedWidget + String name + WidgetClass widget_class + Widget parent + ArgList args + Cardinal num_args + + + + + + + name + + + +Specifies the resource instance name for the created widget. + + + + + + widget_class + + + +Specifies the widget class pointer for the created widget. (rC + + + + + + parent + + + +Specifies the parent widget. Must be of class Composite or any +subclass thereof. + + + + + + args + + + +Specifies the argument list to override any other resource specifications. + + + + + + num_args + + + +Specifies the number of entries in the argument list. + + + + + + +The + +function is a convenience routine that calls + +and +. + + + + +Widget XtVaCreateManagedWidget + String name + WidgetClass widget_class + Widget parent + + + + + + + name + + + +Specifies the resource instance name for the created widget. + + + + + + widget_class + + + +Specifies the widget class pointer for the created widget. (rC + + + + + + parent + + + +Specifies the parent widget. Must be of class Composite or any +subclass thereof. + + + + + + ... + + + +Specifies the variable argument list to override any other +resource specifications. + + + + + + + +is identical in function to + +with the args and num_args parameters replaced +by a varargs list, as described in Section 2.5.1. + + + + +Unmanaging Children + +To remove a list of children from a parent widget's managed list, use +. + + + + +void XtUnmanageChildren + WidgetList children + Cardinal num_children + + + + + + + children + + + +Specifies a list of child widgets. Each child must be of class +RectObj or any subclass thereof. + + + + + + num_children + + + +Specifies the number of children. + + + + + + +The + +function performs the following: + + + + +Returns immediately if the common parent is being destroyed. + + + + +Issues an error if the children do not all have the same parent +or if the parent is not a subclass of +compositeWidgetClass. + + + + +For each unique child on the list, + +ignores the child if it is unmanaged; otherwise it performs the following: + + + + + + +Marks the child as unmanaged. + + + + +If the child is realized and the map_when_managed field is +True, +it is unmapped. + + + + + + +If the parent is realized and if any children have become unmanaged, +calls the change_managed routine of the widgets' parent. + + + + + +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, + +should be called instead; +see . + + + +To remove a single child from its parent widget's managed set, use +. + + + + +void XtUnmanageChild + Widget child + + + + + + + child + + + +Specifies the child. Must be of class RectObj or any subclass thereof. + + + + + + +The + +function constructs a widget list +of length 1 and calls +. + + + +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. + + + + +Bundling Changes to the Managed Set + +A client may simultaneously unmanage and manage children +with a single call to the Intrinsics. In this same call the +client may provide a callback procedure that can modify the +geometries of one or more children. The composite widget class +defines whether this single client call results in separate invocations +of the change_managed method, one to unmanage and the other to +manage, or in just a single invocation. + + + +To simultaneously remove from and add to the geometry-managed +set of children of a composite parent, use +. + + + + +void XtChangeManagedSet + WidgetList unmanage_children + Cardinal num_unmanage_children + XtDoChangeProc do_change_proc + XtPointer client_data + WidgetList manage_children + Cardinal num_manage_children + + + + + + + unmanage_children + + + +Specifies the list of widget children to initially remove from the managed set. + + + + + + num_unmanage_children + + + +Specifies the number of entries in the unmanage_children list. + + + + + + do_change_proc + + + +Specifies a procedure to invoke between unmanaging +and managing the children, or NULL. + + + + + + client_data + + + +Specifies client data to be passed to the do_change_proc. + + + + + + manage_children + + + +Specifies the list of widget children to finally add to the managed set. + + + + + + num_manage_children + + + +Specifies the number of entries in the manage_children list. + + + + + + +The + +function performs the following: + + + + +Returns immediately if num_unmanage_children and +num_manage_children are both 0. + + + + +Issues a warning and returns if the widgets specified in the +manage_children and +the unmanage_children lists do not all have the same parent or if +that parent is not a subclass of +compositeWidgetClass. + + + + +Returns immediately if the common parent is being destroyed. + + + + +If do_change_proc is not NULL and the parent's +CompositeClassExtension +allows_change_managed_set field is +False, +then + +performs the following: + + + + + + +Calls + +(unmanage_children, num_unmanage_children). + + + + +Calls the do_change_proc. + + + + +Calls + +(manage_children, num_manage_children). + + + + + + +Otherwise, the following is performed: + + + + + + +For each child on the unmanage_children list; if the child is +already unmanaged it is ignored, otherwise it is marked as unmanaged, +and if it is realized and its map_when_managed field is +True, +it is unmapped. + + + + +If do_change_proc is non-NULL, the procedure is invoked. + + + + +For each child on the manage_children list; if the child is already +managed or is being destroyed, it is ignored; otherwise it is +marked as managed. + + + + +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 + +on each previously unmanaged child that is unrealized and +mapping each previously unmanaged child that has map_when_managed +True. + + + + + + +If no +CompositeClassExtension +record is found in the parent's composite class part extension field +with record type +NULLQUARK +and version greater than 1, and if +XtInheritChangeManaged +was specified in the parent's class record during class initialization, +the value of the allows_change_managed_set +field is inherited from the superclass. The value inherited from +compositeWidgetClass +for the allows_change_managed_set field is +False. + + + +It is not an error to include a child in both the unmanage_children +and the manage_children lists. The effect of such a call is that +the child remains managed following the call, but the do_change_proc is +able to affect the child while it is in an unmanaged state. + + + +The do_change_proc is of type +. + + + + +typedef void *XtDoChangeProc + + Widget composite_parent + WidgetList unmange_children + Cardinal *num_unmanage_children + WidgetList manage_children + Cardinal *num_manage_children + XtPointer client_data + + + + + + + composite_parent + + + +Passes the composite parent whose managed set is being altered. + + + + + + unmanage_children + + + +Passes the list of children just removed from the managed set. + + + + + + num_unmanage_children + + + +Passes the number of entries in the unmanage_children list. + + + + + + manage_children + + + +Passes the list of children about to be added to the managed set. + + + + + + num_manage_children + + + +Passes the number of entries in the manage_children list. + + + + + + client_data + + + +Passes the client data passed to +. + + + + + + +The do_change_proc procedure is used by the caller of + +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 + +may take advantage of the fact that the Intrinsics internally grant +geometry requests made by unmanaged children without invoking +the parent's geometry manager. To achieve this advantage, if +the do_change_proc procedure +changes the geometry of a child or of a descendant of a child, then +that child should be included in the unmanage_children and +manage_children lists. + + + + +Determining if a Widget Is Managed + +To determine the managed state of a given child widget, use +. + + + + +Boolean XtIsManaged + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + +The + +function returns +True +if the specified widget is of class RectObj or any subclass thereof +and is managed, or +False +otherwise. + + + + + +Controlling When Widgets Get Mapped + +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 map_when_managed field to +False. + + + +To change the value of a given widget's map_when_managed field, use +. + + + + +void XtSetMappedWhenManaged + Widget w + Boolean map_when_managed + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + map_when_managed + + + +Specifies a Boolean value that indicates the new value +that is stored into the widget's map_when_managed +field. + + + + + + +If the widget is realized and managed, +and if map_when_managed is +True, + +maps the window. +If the widget is realized and managed, +and if map_when_managed is +False, +it unmaps the window. + +is a convenience function that is equivalent to (but slightly faster than) +calling + +and setting the new value for the XtNmappedWhenManaged resource +then mapping the widget as appropriate. +As an alternative to using + +to control mapping, +a client may set mapped_when_managed to +False +and use + +and + +explicitly. + + + +To map a widget explicitly, use +. + + + + + XtMapWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +To unmap a widget explicitly, use +. + + + + + XtUnmapWidget + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + + + + +Constrained Composite Widgets + +The Constraint +widget class is a subclass of +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. + + + +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. + + + +To make it easy for widgets and the Intrinsics to keep track of the +constraints associated with a child, +every widget has a constraints 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 +constraintWidgetClass, +then the child's constraints field is NULL. + + + +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: + + +typedef struct { + Dimension max_width, max_height; +} MaxConstraintPart; +typedef struct { + MaxConstraintPart max; +} MaxConstraintRecord, *MaxConstraint; + + +A subclass of this widget class that also needs to maintain a minimum size would +define its constraint record as follows: + + +typedef struct { + Dimension min_width, min_height; +} MinConstraintPart; +typedef struct { + MaxConstraintPart max; + MinConstraintPart min; +} MaxMinConstraintRecord, *MaxMinConstraint; + + +Constraints are allocated, initialized, deallocated, and otherwise maintained +insofar as possible by the Intrinsics. +The Constraint class record part has several entries that facilitate this. +All entries in +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. + + + +The + +function uses the constraint_size field in the parent's class record +to allocate a constraint record when a child is created. + +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. + + + +When the + +and + +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. + +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 +ConstraintClassExtension +record in the +ConstraintClassPart +extension +fields with a record type of +NULLQUARK +and the get_values_hook field in +the extension record is non-NULL, + +calls the get_values_hook +procedure(s) to allow the parent to return derived constraint fields. + + + +The + +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; + +does this automatically. + + + -- cgit v1.2.3