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  wid‐
  get,	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 super‐
  class 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  meth‐
  ods,	then  your  methods  are  responsible for adding and removing the
  child widget 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  super‐
  class	 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:

  ·  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  proce‐
     dure specified for this resource, it inserts the child at the end of
     the array.

  ·  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.

  ·  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.  There‐
  fore, 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()

Vote for polarhome