insert_child() insert_child()
Name
insert_child - Composite class method called when a child is created.
Synopsis
typedef void (*XtWidgetProc)(Widget);
Widget w;
Inputs
w Specifies the widget which has been created and is to be added to its parent's children array.
Description
The insert_child() method is registered on the insert_child field of the Composite class part structure. It is called by XtCreateWidget()
to insert a newly created child into its parent's children array.
Note that the argument to the insert_child() method is the child widget, not the composite widget that defines the method. This method
must add the specified child to its parent's children array, and do anything else that the particular class uses to keep track of its chil-
dren.
The insert_child() method is not chained. If a class does not define an insert_child() method, it should inherit the method from its
superclass by specifying XtInheritInsertChild in the insert_child field of its Composite class part structure. This field should never be
NULL.
Usage
Most composite widgets inherit this method from their superclass. Some composite widget classes define their own insert_child() method so
that they can order their children in some convenient way, create companion widgets for each child, or limit the number or class of their
children. These classes commonly "envelop" their superclass's method by providing a procedure that does class-specific processing and
explicitly invokes the superclass method. This technique allows a kind of non-automatic inheritance, and is shown in the example below.
Note that the Composite insert_child() and delete_child() methods exploit internal common data structures, so you should inherit or envelop
both or neither. If you do not inherit or envelop these methods, then your methods are responsible for adding and removing the child wid-
get from the children array. The "Background" section below explains what the insert_child() method of the Composite class itself does.
Example
The following procedure is the insert_child() method of the Xaw Paned widget class. Note that it first calls the insert_child() method of
its superclass, and then creates a Grip widget for the new child. (Unless the child has constraint resource XtNshowGrip False.) See
delete_child(4) for the corresponding delete_child() method.
static void InsertChild(w)
register Widget w;
{
Pane pane = PaneInfo(w);
/* insert the child widget in the composite children list with the */
/* superclass insert_child routine. */
(*SuperClass->composite_class.insert_child)(w);
if (!IsPane(w)) return;
/* Panes will be added in the order they are created, temporarily */
if ( pane->show_grip == TRUE ) {
CreateGrip(w);
if (pane->min == PANED_GRIP_SIZE)
pane->min = PaneSize(pane->grip, IsVert((PanedWidget) XtParent(w)));
}
else {
if (pane->min == PANED_GRIP_SIZE)
pane->min = 1;
pane->grip = NULL;
}
pane->size = 0;
pane->paned_adjusted_me = FALSE;
} /* InsertChild */
In this example, SuperClass is a symbolic name for the superclass of the Paned widget class. Note that this method does not determine the
superclass as follows:
XtSuperclass(XtParent(w))
The parent of w may be a subclass of Paned, and therefore its superclass pointer will not always be the class whose method should be
invoked.
Background
The insert_child() method of the Composite class itself is commonly inherited by subclasses or explicitly invoked by them. It performs the
following:
o Calls the XtOrderProc registered on the XtNinsertPosition resource of the composite widget to determine the position in the children
array at which the child should be inserted. If there is no procedure specified for this resource, it inserts the child at the end of
the array.
o Inserts the child at the appropriate position in the array, moving other children if necessary. If there is not enough room to insert a
new child in the children array (that is, num_children = num_slots), it reallocates the array and updates num_slots.
o Increments num_children.
If a composite widget class does not have an CompositeClassExtension record or if the accepts_objects field of that record is False, the
Intrinsics will not allow non-widget children of that widget. Therefore, the insert_child() method of a widget class that does not accept
object children is guaranteed never to be passed a non-widget child.
See Also
XtCreateWidget(1),
Composite(3), Constraint(3),
delete_child(4).
Xt - Intrinsics Methods insert_child()