box
box is again, another abstract type, which will give you
lots of functionality to pack widgets, derived from the
container model.

box instances can be created from hbox, and vbox respectively.
box has child widgets stored in a GList with data pointer
to the structure 'GtkBoxChild'.

We will see how to add elements to a box using this API.

Adding from the start, for a Hbox implies that the elements
get added from L-R. conversely for a adding from end, implies
a R-L addition order of widget.

Adding from the start for a Vbox implies  that the elements
get added from top-bottom. conversely for a adding from end, implies
a bottom-top addition order of widget.

void	   gtk_box_pack_start	       (GtkBox	     *box,
					GtkWidget    *child,
					gboolean      expand,
					gboolean      fill,
					guint	      padding);

void	   gtk_box_pack_start_defaults (GtkBox	     *box,
					GtkWidget    *widget);

void	   gtk_box_pack_end	       (GtkBox	     *box,
					GtkWidget    *child,
					gboolean      expand,
					gboolean      fill,
					guint	      padding);

void	   gtk_box_pack_end_defaults   (GtkBox	     *box,
					GtkWidget    *widget);


In all these functions shown above,the 'child' or the 'widget'
gets added to the 'box' in their respective order. The boolean
flags expand,  decides if the child widget will expand, if the
box expands, or remains of fixed size. This flag decides whether 
the child should receive extra space when the parent grows.
The fill flag decides if the child widget will fill the
remaining space of box widget, or occupy its original size.
Fill flag decides whether extra space given to the child should be 
allocated to the child or used as padding.

Padding decides the pixel spacing between the top, bottom,
left,right child widgets in the box.

gtk_box_pack_start/end_defaults are conveniece functions,
to lessen typing work. GTK+ defaults the boolean flags
expand=TRUE fill=TRUE, spacing = 0 as you can see in this
code

/* from GTK+ gtkbox.c */
void
gtk_box_pack_end_defaults (GtkBox    *box,
			   GtkWidget *child)
{
  gtk_box_pack_end (box, child, TRUE, TRUE, 0);
}

	

If you need to set all child widgeets of same size, then
turn on the homoggeneous flag to true.

void	   gtk_box_set_homogeneous     (GtkBox	     *box,
					gboolean      homogeneous);
gboolean   gtk_box_get_homogeneous     (GtkBox	     *box);


Spacing is the amount of space between children, requested. This is 
different from padding, in the sense that padding is the extra space
and how it ought to be allocated. spacing is you defnitely get
that amout of space while requesting for allocation. padding you
may or maynot get based on whats available.

void	   gtk_box_set_spacing	       (GtkBox	     *box,
					gint	      spacing);
gint       gtk_box_get_spacing         (GtkBox       *box);


Move the child to any position in range(0,g_list_length(box->children)-1).
This function changes the box->children structure, moving links in the
order you have given, the updates the GUI.
void	   gtk_box_reorder_child       (GtkBox	     *box,
					GtkWidget    *child,
					gint	      position);

If you want to find out parameters expand,fill,padding, pack_type
for a particular child widget, in a box, use this function.
void	   gtk_box_query_child_packing (GtkBox	     *box,
					GtkWidget    *child,
					gboolean     *expand,
					gboolean     *fill,
					guint	     *padding,
					GtkPackType  *pack_type);

Change the packing parameters of the child, associated with this 
box.
void	   gtk_box_set_child_packing   (GtkBox	     *box,
					GtkWidget    *child,
					gboolean      expand,
					gboolean      fill,
					guint	      padding,
					GtkPackType   pack_type);



Very often you will need to access the child widgets of  box, or a 
widget derived from box type. Here is how to do it:

/* This code does iterates through the list of children, and removes a
   all GTK_IMAGE widgets from this box.
 */
{
	GList *it=NULL;
	GtkBox *box=GTK_DIALOG(dialog)->vbox;

	gtk_widget_freeze_child_notify(box);
	for(it=box->children;it!=NULL;it=it->next) {	
	    GtkBoxChild *bc=(GtkBoxChild *)it->data;
	    
	    if(GTK_IS_IMAGE(bc->widget)) {
	      gtk_container_remove(GTK_CONTAINER(box),bc->widget);
	      box->children=g_list_remove(box->children,it);
	      break;
	    }
	 }
	gtk_widget_thaw_child_notify(boxc->widget);	  
}

You will see that accessing a list of children using GList interface
of the box->children  list, we can get a GtkBoxChild pointer from the
data member. Now you have a pointer to this child, you can do anything,
easiest remove it. Now if have done that you must restore the position
of the box->children, and remove the link pointing to this child
from the GList also, otherwise wierd memory errors can occur.


Searching for a child widget is done like this
/* This code does iterates through the list of children, and returns
   true if a widget lostchild is found.
 */
{
	GList *it=NULL;
	GtkBox *box=GTK_DIALOG(dialog)->vbox;

	for(it=box->children;it!=NULL;it=it->next) {
	    GtkBoxChild *bc=(GtkBoxChild *)it->data;

	    if(lostchild == bc->widget){
	      /* Match : found lostchild */
              return TRUE;
	    }
	 }
        return FALSE;
}

Also note, the position of child in the box->children member list,
and the position on screen are necessarily be same.

example code: box.c
see also: bbox, hbox, vbox