Gtk-Perl Tutorial
PrevNext

Chapter 7. Tables

Table of Contents
7.1. Creating a Table
7.2. Attaching Widgets to a Table
7.3. Table Size and Spacing
7.4. Table Example

Inheritance Hierarchy

Object
   +--- Widget
         +--- Container
               +--- Table
         

Let's take a look at another way of packing - Tables. These can be extremely useful in certain situations. Using tables, we create a grid that we can place widgets in. The widgets may take up as many spaces as we specify.

7.1. Creating a Table

The first thing to look at, of course, is the function for creating a new table:

$table = new Gtk::Table( $num_rows, $num_columns, $homogeneous );

The first argument is the number of rows to make in the table, while the second, obviously, is the number of columns. The $homogeneous argument has to do with how the table's boxes are sized. If homogeneous is a true value, the table boxes are resized to the size of the largest widget in the table. If homogeneous is a false value, the size of a table boxes is dictated by the tallest widget in its same row, and the widest widget in its column.

The rows and columns are laid out from 0 to n, where n was the number specified in the call to new Gtk::Table(). So, if you specify rows = 3 and columns = 2, the layout would look something like this:

         0          1          2
        0+----------+----------+
         |          |          |
        1+----------+----------+
         |          |          |
        2+----------+----------+
         |          |          |
        3+----------+----------+

Note that the coordinate system starts in the upper left hand corner.

7.2. Attaching Widgets to a Table

To place a widget into a box, use the following function:

$table->attach( $child, $left_attach, $right_attach,
                $top_attach, $bottom_attach, $xoptions,
                $yoptions, $xpadding, $ypadding );

To the left of the function call is the table you've created and the first argument is the widget you wish to place in the table. The left and right attach arguments specify where to place the widget, and how many boxes to use. If you want a button in the lower right table entry of our 2x2 table, and want it to fill that entry ONLY, $left_attach would be 1, $right_attach would be 2, $top_attach would be 1, and $bottom_attach would be 2.

Now, if you wanted a widget to take up the whole top row of our 2x2 table, you'd use $left_attach = 0, $right_attach = 2, $top_attach = 0, and $bottom_attach = 1.

The $xoptions and $yoptions are used to specify packing options and may be combined together to allow multiple options. These options are:

fill

If the table box is larger than the widget, and 'fill' is specified, the widget will expand to use all the room available.

shrink

If the table widget was allocated less space then was requested (usually by the user resizing the window), then the widgets would normally just be pushed off the bottom of the window and disappear. If 'shrink' is specified, the widgets will shrink with the table.

expand

This will cause the table to expand to use up any remaining space in the window.

If you only wish to specify one of these options, you enclose it in quotes like this: 'option'. But if you want to combine options you would put them into an anonymous list like this: ['option1', 'option2'].

Padding is just like in boxes, creating a clear area around the widget specified in pixels.

A variation of attach() is attach_defaults(), which allows you to leave out the X and Y options and padding. The X and Y options default to ['fill', 'expand'], and X and Y padding default to 0.

7.3. Table Size and Spacing

We also have the set_row_spacing() and set_col_spacing() functions. These place spacing between the rows/columns at the specified row or column:

$table->set_row_spacing( $row, $spacing );

$table->set_col_spacing( $column, $spacing );

Note that for columns, the space goes to the right of the column, and for rows, the space goes below the row.

You can also set a consistent spacing of all rows and/or columns with:

$table->set_row_spacings( $spacing );

$table->set_col_spacings( $spacing );

Note that with these calls, the last row and last column do not get any spacing.

If you want to resize a table after it has been created, you may do so with this funciton:

$table->resize( $rows, $columns );

If you want to set the homogeneous property of an existing table, you may do so using this function:

$table->set_homogeneous( $homogeneous );

The $homogeneous argument may be either a true or a false value.

7.4. Table Example

Here we make a window with three buttons in a 2x2 table. The first two buttons will be placed in the upper row. A third, the quit button, is placed in the lower row, spanning both columns. It should look something like this:

Table Example Screenshot

Here's the source code:

Table Example Source 

      
#!/usr/bin/perl -w

use Gtk;
use strict;

set_locale Gtk;
init Gtk;

my $false = 0;
my $true = 1;

my $window;
my $button;
my $table;

# Create the window
$window = new Gtk::Window( "toplevel" );
$window->signal_connect( "delete_event", sub { Gtk->exit( 0 ); } );
$window->title( "Table" );
$window->border_width( 20 );

# Create a 2x2 table
$table = new Gtk::Table( 2, 2, $true );
$window->add( $table );

# Create first button
$button = new Gtk::Button( "button 1" );
$button->signal_connect( "clicked", \&ButtonClicked, "button 1" );

# Insert button 1 into the upper left quadrant of the table
$table->attach_defaults( $button, 0, 1, 0, 1 );
$button->show();

# Create second button
$button = new Gtk::Button( "button 2" );
$button->signal_connect( "clicked", \&ButtonClicked, "button 2" );

# Insert button 2 into the upper right quadrant of the table
$table->attach_defaults( $button, 1, 2, 0, 1 );
$button->show();

# Create "Quit" button
$button = new Gtk::Button( "Quit" );
$button->signal_connect( "clicked", sub { Gtk->exit( 0 ); } );

# Insert the quit button into the both lower quadrants of the table
$table->attach_defaults( $button, 0, 2, 1, 2 );
$button->show();

$table->show();
$window->show();

main Gtk;
exit( 0 );



### Callbacks


# Callback that prints out a message when a button is clicked.

sub ButtonClicked
{
   my ( $button, $text ) = @_;
   print( "Hello again $text was pressed\n" );
}


# END EXAMPLE PROGRAM
PrevHomeNext
Packing BoxUpWindows