Gtk-Perl Tutorial
Prev		Next

Chapter 6. Packing Box

Table of Contents
6.1. Theory of Packing Boxes
6.2. Details of Boxex
6.3. Packing Demonstration Program

Inheritance Hierarchy

Object +--- Widget +--- Container +--- Box

When creating an application, you'll want to put more than one widget inside a window. Our first example only used one widget so we could simply use a $window->add() call to put the widget into the window. But when you want to put more than one widget into a window, how do you control where that widget is positioned? This is where packing boxes comes in.

6.1. Theory of Packing Boxes

Packing is done by creating boxes and packing widgets into them. Packing boxes are invisible widget containers that we can pack our widgets into. Packing boxes come in two forms: a horizontal box, and a vertical box. When packing widgets into a horizontal box, the objects are inserted horizontally from left to right or right to left depending on the call used. In a vertical box, widgets are packed from top to bottom or vice versa. You may use any combination of boxes inside or beside other boxes to create the desired effect.

To create a new horizontal or vertical box, we use one of these calls:

$hbox = new Gtk::HBox( $homogeneous, $spacing );

$vbox = new Gtk::VBox( $homogeneous, $spacing ); As might be obvious, an HBox is horizontal, and a VBox is vertical. If $homogeneous is a true value, then all the widgets packed in will have the same space available to them. The $spacing is the size in pixels between each spot available to widgets.

The following functions are used to place objects inside a box:

$box->pack_start( $child, $expand, $fill, $padding );

$box->pack_end( $child, $expand, $fill, $padding ); The pack_start() function will start at the top and work its way down in a VBox, and pack left to right in an HBox. pack_end() will do the opposite, packing from bottom to top in a VBox, and right to left in an HBox. Using these functions allows us to right justify or left justify our widgets and may be mixed in any way to achieve the desired effect. We will use pack_start() in most of our examples. The object added may be another container or a widget. In fact, many widgets are actually containers themselves, including the button, but we usually only use a label or a pixmap (or both) inside a button.

As you might have guessed, the $child argument is the widget to be packed into the box.

If the $expand argument is a true value, then the widgets are laid out in the box to fill in all the extra space in the box so the box is expanded to fill the area allotted to it; otherwise the box is shrunk to just fit the widgets. Setting expand to a false value will allow you to do right and left justification of your widgets. Note that setting $homogeneous to true on the Box is the same as setting $expand to true for each widget.

If the $fill argument is a true value, then extra space is allocated to the objects themselves. Otherwise, extra space is extra padding in the box around these objects. This only has an effect if the $expand argument is a true value.

By using these calls, GTK knows where you want to place your widgets so it can do automatic resizing and other nifty things. As you can imagine, this method gives us a quite a bit of flexibility when placing and creating widgets.

6.2. Details of Boxex

Because of this flexibility, packing boxes in GTK can be confusing at first. There are a lot of options, and it's not immediately obvious how they all fit together. In the end, however, there are basically five different styles. These five styles are illustrated below:

Packing Box Styles Screenshot

Each line of the example contains one horizontal box (hbox) with several buttons. The call to pack is shorthand for the call to pack each of the buttons into the hbox. Each of the buttons is packed into the hbox the same way (i.e., the same arguments are passed to each pack_start() function).

There is a shortcut form of pack_start() and pack_end(), which sets the expand value to true, the fill value to true, and the padding value to 0. These functions are:

$box->pack_start_defaults( $widget );

$box->pack_end_defaults( $widget );

The homogeneous value of a Box can be turned on and off using the following function:

$box->set_homogeneous( $homogeneous );

The spacing value of a Box can be turned on and off using the following function:

$box->set_spacing( $spacing );

If you want to move a child to a new position, use the following function:

$box->reorder_child( $child, $position );

The $child is the widget to move, and $position is the position to move it to, starting from 0. If you want to view the current order, view the list returned by a call to the children() function (inherited from Container).

If you want to change a child's packing, you can use the following function:

$box->set_child_packing( $widget, $expand, $fill, $padding, $pack_type );

The arguements are the same as in the pack_start() and pack_end(), functions, with the exception of $pack_type, which is either 'start' or 'end'.

What's the difference between spacing (set when the box is created) and padding (set when elements are packed)? Spacing is added between objects, and padding is added on either side of an object. The following figure should make the difference clearer:

Packing Box Spacing Screenshot

6.3. Packing Demonstration Program

Here is the code used to create the above images. I've commented it fairly heavily so I hope you won't have any problems following it, but be aware that the program is pretty large. Run it yourself and play with it.

Packing Box Source

      
#!/usr/bin/perl -w

use Gtk;
use strict;

set_locale Gtk;
init Gtk;

unless ( $ARGV[0] )
{
   print( "usage: packbox num, where num is 1, 2, or 3.\n" );
   Gtk->exit( 1 );
   exit( 1 );
}

my $false = 0;
my $true = 1;
my $which = $ARGV[0];

my $window;
my $box1;
my $box2;
my $label;
my $separator;
my $quitbox;
my $button;

# You should always remember to connect the delete_event signal
# to the main window. This is very important for proper intuitive
# behavior
$window = new Gtk::Window( "toplevel" );
$window->signal_connect( "delete_event", sub { Gtk->exit( 0 ); } );
$window->border_width( 10 );

# We create a vertical box (vbox) to pack the horizontal boxes
# into. This allows us to stack the horizontal boxes filled with
# buttons one on top of the other in this vbox.
$box1 = new Gtk::VBox( $false, 0 );

# which example to show. These correspond to the pictures above.
if ( $which == 1 )
{
   # create a new label.
   $label = new Gtk::Label( 'new Gtk::HBox( $false, 0 );' );

   # Align the label to the left side.  We'll discuss this function
   # and others in the section on Widget Attributes.
   $label->set_alignment( 0, 0 );

   # Pack the label into the vertical box (vbox box1).  Remember
   # that widgets added to a vbox will be packed one on top of the
   # other in order.
   $box1->pack_start( $label, $false, $false, 0 );

   # Show the label
   $label->show();

   # Call our make box function - homogeneous = FALSE, spacing = 0, 
   # expand = FALSE, fill = FALSE, padding = 0
   $box2 = make_box( $false, 0, $false, $false, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Call our make box function - homogeneous = FALSE, spacing = 0,
   # expand = TRUE, fill = FALSE, padding = 0
   $box2 = make_box( $false, 0, $true, $false, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $false, 0, $true, $true, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Creates a separator, we'll learn more about these later, but
   # they are quite simple. 
   $separator = new Gtk::HSeparator();

   # Pack the separator into the vbox. Remember each of these
   # widgets is being packed into a vbox, so they'll be stacked
   # vertically.
   $box1->pack_start( $separator, $false, $true, 5 );
   $separator->show();

   # Create another new label, and show it.
   $label = new Gtk::Label( 'new Gtk::HBox( $true, 0 );' );
   $label->set_alignment( 0, 0 );
   $box1->pack_start( $label, $false, $false, 0 );
   $label->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $true, 0, $true, $false, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $true, 0, $true, $true, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Another new separator.
   $separator = new Gtk::HSeparator();

   # The last 3 arguments to gtk_box_pack_start are:
   # expand, fill, padding.
   $box1->pack_start( $separator, $false, $true, 5 );
   $separator->show();
}
elsif ( $which == 2 )
{
   # Create a new label, remember box1 is a vbox as created  near
   # the beginning of main()
   $label = new Gtk::Label( 'new Gtk::HBox( $false, 10 );' );
   $label->set_alignment( 0, 0 );
   $box1->pack_start( $label, $false, $false, 0 );
   $label->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $false, 10, $true, $false, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $false, 10, $true, $true, 0 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   $separator = new Gtk::HSeparator();
   # The last 3 arguments to gtk_box_pack_start are: expand, fill,
   # and padding.
   $box1->pack_start( $separator, $false, $true, 5 );
   $separator->show();

   $label = new Gtk::Label( 'new Gtk::HBox( $false, 0 );' );
   $label->set_alignment( 0, 0 );
   $box1->pack_start( $label, $false, $false, 0 );
   $label->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $false, 0, $true, $false, 10 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # Args are: homogeneous, spacing, expand, fill, padding
   $box2 = make_box( $false, 0, $true, $true, 10 );
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   $separator = new Gtk::HSeparator();
   # The last 3 arguments to pack_start are: expand, fill,
   # and padding.
   $box1->pack_start( $separator, $false, $true, 5);
   $separator->show();
}
elsif ( $which == 3 )
{
   # This demonstrates the ability to use pack_end() to right
   # justify widgets. First, we create a new box as before.
   $box2 = make_box( $false, 0, $false, $false, 0);

   # Create the label that will be put at the end.
   $label = new Gtk::Label( "end" );

   # Pack it using gtk_box_pack_end(), so it is put on the right
   # side of the hbox created in the make_box() call.
   $box2->pack_end( $label, $false, $false, 0 );

   # Show the label.
   $label->show();

   # Pack box2 into box1 (the vbox remember ? :)
   $box1->pack_start( $box2, $false, $false, 0 );
   $box2->show();

   # A separator for the bottom.
   $separator = new Gtk::HSeparator();

   # This explicitly sets the separator to 400 pixels wide by 5
   # pixels high. This is so the hbox we created will also be 400
   # pixels wide, and the "end" label will be separated from the
   # other labels in the hbox. Otherwise, all the widgets in the
   # hbox would be packed as close together as possible.
   $separator->set_usize( 400, 5 );

   # pack the separator into the vbox (box1) created near the start 
   # of main()
   $box1->pack_start( $separator, $false, $true, 5 );
   $separator->show();
}

# Create another new hbox.. remember we can use as many as we need!
$quitbox = new Gtk::HBox( $false, 0 );

# Our quit button.
$button = new Gtk::Button( "Quit" );

# Setup the signal to terminate the program when the button is
# clicked
$button->signal_connect( "clicked", sub { Gtk->exit( 0 ); } );

# Pack the button into the quitbox.
# The last 3 arguments to gtk_box_pack_start are:
# expand, fill, padding.
$quitbox->pack_start( $button, $true, $false, 0 );

# pack the quitbox into the vbox (box1)
$box1->pack_start( $quitbox, $false, $false, 0 );

# Pack the vbox (box1) which now contains all our widgets, into the
# main window.
$window->add( $box1 );

# And show everything left
$button->show();
$quitbox->show();

$box1->show();
# Showing the window last so everything pops up at once.
$window->show();

# And of course, our main function.
main Gtk;
exit( 0 );



### Subroutines

# Make a new hbox filled with button-labels. Arguments for the
# variables we're interested are passed in to this function. 
# We do not show the box, but do show everything inside.
sub make_box
{
   my ( $homogeneous, $spacing, $expand, $fill, $padding ) = @_;

   # Create a new hbox with the appropriate homogeneous
   # and spacing settings
   my $box = new Gtk::HBox( $homogeneous, $spacing );

   $button = new Gtk::Button( '$box->' );
   $box->pack_start( $button, $expand, $fill, $padding );
   $button->show();

   # Create a series of buttons with the appropriate settings
   $button = new Gtk::Button( "pack" );
   $box->pack_start( $button, $expand, $fill, $padding );
   $button->show();

   $button = new Gtk::Button( '( $button,' );
   $box->pack_start( $button, $expand, $fill, $padding );
   $button->show();

   # Create a button with the label depending on the value of
   # expand.
   if ( $expand )
   {
      $button = new Gtk::Button( '$true,' );
   }
   else
   {
      $button = new Gtk::Button( '$false,' );
   }

   $box->pack_start( $button, $expand, $fill, $padding );
   $button->show();

   # This is the same as the button creation for "expand"
   if ( $fill )
   {
      $button = new Gtk::Button( '$true,' );
   }
   else
   {
      $button = new Gtk::Button( '$false,' );
   }

   $box->pack_start( $button, $expand, $fill, $padding );
   $button->show();

   $button = new Gtk::Button( "$padding );" );
   $box->pack_start( $button, $expand, $fill, $padding );
   $button->show();

   return ( $box );
}


# END EXAMPLE PROGRAM

Prev	Home	Next
Basic Containers	Up	Tables