hpux man page for insert_child

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()