Next Previous Contents

11. Packing widgets

When creating an application, you'll want to put more than one widget inside a window. Our first helloworld example only used one widget, so we could simply use a Gtk::Container::add() call to "pack" the widget into the window. But when you want to put more than one widget into a window, how do you control where the widgets are positioned? This is where packing comes in.

11.1 Theory of Packing Boxes

Most packing is done by creating boxes as in the example above. These are invisible widget containers that we can pack our widgets into which 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 box, we use a Gtk::HBox, and for vertical boxes, a Gtk::VBox. The Gtk::Box::pack_start() and Gtk::Box::pack_end() methods are used to place objects inside these containers. The Gtk::Box::pack_start() method will start at the top and work its way down in a vbox, and pack left to right in an hbox. Gtk::Box::pack_end() will do the opposite, packing from bottom to top in a vbox, and right to left in an hbox. Using these methods allows us to right justify or left justify our widgets; the methods may be mixed in any way to achieve the desired effect. We will use Gtk::Box::pack_start() in most of our examples. An object may be another container or a widget. In fact, many widgets are actually containers themselves, including the button, but we usually only place a label inside a button.

By using these calls, GTK-- knows where you want to place your widgets so it can do automatic resizing and other nifty things. There are also a number of options covering how your widgets should be packed. As you can imagine, this gives us a quite a bit of flexibility when placing and creating widgets.

11.2 Details of Boxes

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, as shown in this picture:

Box Packing Example Image

Each line contains one horizontal box (hbox) with several buttons. Each of the buttons is packed into the hbox the same way (i.e. same arguments to the Gtk::Box::pack_start() method).

This is the declaration of Gtk::Box::pack_start() method:

void Gtk::Box::pack_start(const Gtk::Widget &child,
                          bool              expand = FALSE,
                          bool              fill = FALSE,
                          gint              padding = 0);

The first argument is the object you're packing. The objects will all be buttons for now, so we'll be packing buttons into boxes.

If expand is set, the packed widgets will be spaced out evenly across the width/length of the hbox/vbox, but their sizes won't change (there will be empty space between the widgets). fill has an effect only if expand is set; if it's true, then the packed widgets will be resized so that there will be no space between them. padding specifies the width of a border-area to leave around the packed widget.

Here's the constructor for the box widgets:

Gtk::Box(bool homogeneous,
         gint spacing);

Passing true for homogeneous will force all of the contained widgets to be the same size. spacing is a (minimum) number of pixels to leave between each widget.

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

Box Packing Example Image

Here is the code used to create the above images:

Source location: examples/packbox/packbox.cc

#include <iostream>
#include <cstdio>
#include <gtk--/box.h>
#include <gtk--/button.h>
#include <gtk--/main.h>
#include <gtk--/label.h>
#include <gtk--/separator.h>
#include <gtk--/window.h>

using std::cerr;
using std::endl;

// Gtk-- version of the "packbox" example from the gtk+ tutorial


class PackBox : public Gtk::HBox
{
public:
  PackBox(bool homogeneous, gint spacing, bool expand, bool fill, gint padding);
  ~PackBox() { delete m_button6; }

  Gtk::Button m_button1, m_button2, m_button3, m_button4, m_button5,
    *m_button6;
  char padstr[80];
};

PackBox::PackBox(bool homogeneous, gint spacing, bool expand, bool fill, gint padding) :
  Gtk::HBox(homogeneous, spacing),
  m_button1("gtk_box_pack"),
  m_button2("(box,"),
  m_button3("button,"),
  m_button4(expand ? "true," : "false,"),
  m_button5(fill ? "true," : "false,")
{
  pack_start(m_button1, expand, fill,padding);
  pack_start(m_button2, expand, fill,padding);
  pack_start(m_button3, expand, fill,padding);
  pack_start(m_button4, expand, fill,padding);
  pack_start(m_button5, expand, fill,padding);

  sprintf(padstr, "%d);", padding);
  
  m_button6 = new Gtk::Button(padstr);
  pack_start(*m_button6, expand, fill,padding);
}

  

class PackBoxDemo : public Gtk::Window
{
public:
  Gtk::Button m_button;
  Gtk::VBox m_box1;
  Gtk::HBox m_boxQuit;
  Gtk::Button m_buttonQuit;
  
  Gtk::HSeparator m_seperator1, m_seperator2, m_seperator3, m_seperator4, m_seperator5;
  
  PackBoxDemo(int which);
  ~PackBoxDemo();
  
  // You should always remember to connect the destroy signal to the
  // main window.  This is very important for proper intuitive
  // behavior 
  gint delete_event_impl(GdkEventAny*) { 
    Gtk::Main::quit(); return 0; 
  }
  
};

PackBoxDemo::PackBoxDemo(int which) :
  m_box1(false, 0),
  m_boxQuit(false, 0),
  m_buttonQuit("Quit")
{
  Gtk::Label *m_label1, *m_label2;
  PackBox *m_packbox1, *m_packbox2, *m_packbox3,
    *m_packbox4, *m_packbox5;

  switch(which) {
  case 1:
    // create a new label.
    m_label1 = manage(new Gtk::Label("hbox(false, 0);"));

    // Align the label to the left side.  We'll discuss this function and 
    // others in the section on Widget Attributes. 
    m_label1->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. 
    m_box1.pack_start(*m_label1, false, false, 0);

    // Create a PackBox - homogeneous = false, spacing = 0,
    // expand = false, fill = false, padding = 0 
    m_packbox1 = manage(new PackBox(false, 0, false, false, 0));
    m_box1.pack_start(*m_packbox1, false, false, 0);

    // Create a PackBox - homogeneous = false, spacing = 0,
    // expand = true, fill = false, padding = 0 
    m_packbox2 = manage(new PackBox(false, 0, false, true, 0));
    m_box1.pack_start(*m_packbox2, false, false, 0);

    // Create a PackBox - homogeneous = false, spacing = 0,
    // expand = true, fill = true, padding = 0 
    m_packbox3 = manage(new PackBox(false, 0, true, true, 0));
    m_box1.pack_start(*m_packbox3, false, false, 0);
    
    // pack the separator into the vbox.  Remember each of these
    // widgets are being packed into a vbox, so they'll be stacked
    // vertically. 
    m_box1.pack_start(m_seperator1, false, true, 5);
    
    // create another new label, and show it.
    m_label2 = manage(new Gtk::Label("hbox(true, 0);"));
    m_label2->set_alignment(0, 0);
    m_box1.pack_start(*m_label2, false, false, 0);
    
    // Args are: homogeneous, spacing, expand, fill, padding
    m_packbox4 = manage(new PackBox(true, 0, true, false, 0));
    m_box1.pack_start(*m_packbox4, false, false, 0);

    // Args are: homogeneous, spacing, expand, fill, padding
    m_packbox5 = manage(new PackBox(true, 0, true, false, 0));
    m_box1.pack_start(*m_packbox5, false, false, 0);

    m_box1.pack_start(m_seperator2, false, true, 5);
    
    break;
    
  case 2:

    m_label1 = manage(new Gtk::Label("hbox(false, 10);"));
    m_label1->set_alignment(0, 0);
    m_box1.pack_start(*m_label1, false, false, 0);

    m_packbox1 = manage(new PackBox(false, 10, true, false, 0));
    m_box1.pack_start(*m_packbox1, false, false, 0);
    
    m_packbox2 = manage(new PackBox(false, 10, true, true, 0));
    m_box1.pack_start(*m_packbox2, false, false, 0);

    m_box1.pack_start(m_seperator1, false, true, 5);


    m_label2 = manage(new Gtk::Label("hbox(false, 10);"));
    m_label2->set_alignment(0, 0);
    m_box1.pack_start(*m_label2, false, false, 0);

    m_packbox3 = manage(new PackBox(false, 0, true, false, 10));
    m_box1.pack_start(*m_packbox3, false, false, 0);
    
    m_packbox4 = manage(new PackBox(false, 0, true, true, 10));
    m_box1.pack_start(*m_packbox4, false, false, 0);

    m_box1.pack_start(m_seperator2, false, true, 5);

    break;
    
  case 3:

    // This demonstrates the ability to use Gtk::Box::pack_end() to
    // right justify widgets.  First, we create a new box as before. 
    m_packbox1 = manage(new PackBox(false, 0, false, false, 0));
    // create the label that will be put at the end. 
    m_label1 = manage(new Gtk::Label("end"));
    // pack it using pack_end(), so it is put on the right side
    // of the PackBox. 
    m_packbox1->pack_end(*m_label1, false, false, 0);
    
    m_box1.pack_start(*m_packbox1, false, false, 0);
    
    // 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. 
    m_seperator1.set_usize(400, 5);
    
    // pack the separator into ourselves 
    m_box1.pack_start(m_seperator1, false, true, 5);
  }
  
  // setup the signal to destroy the window.  Remember that this will send
  // the "destroy" signal to the window which will be caught by our signal
  // handler as defined above. 
  m_buttonQuit.clicked.connect(Gtk::Main::quit.slot());

  // pack the button into the quitbox.
  // The last 3 arguments to gtk_box_pack_start are: expand, fill, padding. 
  m_boxQuit.pack_start(m_buttonQuit, true, false, 0);
  m_box1.pack_start(m_boxQuit, false, false, 0);
  
  // pack the vbox (box1) which now contains all our widgets, into the
  // main window. 
  add(m_box1);

  show_all();
  
}

PackBoxDemo::~PackBoxDemo()
{}


int main (int argc, char *argv[])
{
          
  // all GTK applications must have a gtk_main(). Control ends here
  // and waits for an event to occur (like a key press or mouse event).
  Gtk::Main myapp(&argc, &argv);

  if (argc != 2) {
    cerr << "usage: packbox num, where num is 1, 2, or 3." << endl;
    // this just does cleanup in GTK, and exits with an exit status of 1. 
    gtk_exit (1);
  }

  PackBoxDemo packboxdemo(atoi(argv[1]));

  myapp.run();
  return 0;
}

11.3 Packing Using Tables

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.

Here is the constructor for Gtk::Table:

Gtk::Table(gint rows,
           gint columns,
           bool homogeneous);

The first argument is the number of rows to make in the table, while the second, obviously, is the number of columns. If homogeneous is true, the table boxes are forced to all be the same size (i.e. the size of the largest widget in the table).

The rows and columns are indexed starting at 0. If you specify rows = 2 and columns = 2, the layout would look something like this:

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

Note that the coordinate system starts in the upper left hand corner. To place a widget into a box, use the following function:

void Gtk::Table::attach(Gtk::Widget &child,
                        guint left_attach,
                        guint right_attach,
                        guint top_attach,
                        guint bottom_attach,
                        guint xoptions=(GTK_FILL|GTK_EXPAND),
                        guint yoptions=(GTK_FILL|GTK_EXPAND),
                        guint xpadding=0,
                        guint ypadding=0);

The first argument is the widget you wish to place in the table.

The left_attach and right_attach arguments specify where to place the widget, and how many boxes to use. For example, if you want a button in the lower-right cell of a 2x2 table, and want it to occupy that cell only, then left_attach would be 1, right_attach 2, top_attach 1, and bottom_attach 2. If, on the other hand, you wanted a widget to take up the entire top row of our 2x2 table, you'd set left_attach = 0, right_attach = 2, top_attach = 0, and bottom_attach = 1.

xoptions and yoptions are used to specify packing options and may be bitwise ORed together to allow multiple options. These options are:

GTK_FILL

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

GTK_SHRINK

If the table widget was allocated less space than 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 GTK_SHRINK is specified, the widgets will shrink with the table.

GTK_EXPAND

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

The padding arguments work just as they do for boxes.

Gtk::Table::set_row_spacing() and Gtk::Table::set_col_spacing() set the spacing between the rows at the specified row or column:

void Gtk::Table::set_row_spacing(gint row,
                                 gint spacing);
void Gtk::Table::set_col_spacing(gint column,
                                 gint 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:

void Gtk::Table::set_row_spacings(gint spacing );
void Gtk::Table::set_col_spacings(gint spacing );

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

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

Table Packing Example Image

Source location: examples/table/table.cc

#include <iostream>
#include <gtk--/button.h>
#include <gtk--/main.h>
#include <gtk--/table.h>
#include <gtk--/window.h>

// Gtk-- version of the table packing example from the gtk+ tutorial

using SigC::bind;
using SigC::slot;
using std::cout;
using std::endl;

class MyWin : public Gtk::Window
{
public:
  MyWin();
  
  Gtk::Table m_table;
  Gtk::Button m_b1, m_b2, m_bQuit;

  void callback(char* data);

  gint delete_event_impl(GdkEventAny*) { 
    Gtk::Main::quit(); return 0; 
  }

};

MyWin::MyWin() :
  m_table(2, 2, true),
  m_b1("button 1"),
  m_b2("button 2"),
  m_bQuit("Quit")
{
  set_title("Table");
  set_border_width(20);
  
  add(m_table);

  m_table.attach(m_b1, 0, 1, 0, 1);
  m_table.attach(m_b2, 1, 2, 0, 1);
  m_table.attach(m_bQuit, 0, 2, 1, 2);

  m_b1.clicked.connect(bind<char*>(slot(this, &MyWin::callback), "button 1"));
  m_b2.clicked.connect(bind<char*>(slot(this, &MyWin::callback), "button 2"));
  m_bQuit.clicked.connect(Gtk::Main::quit.slot());
  // the cast is needed to "help" template instantiation

  show_all();
}

void
MyWin::callback(char* data)
{
  cout << "Hello again - " << data << " was pressed" << endl;
}


int main(int argc, char *argv[])
{
  Gtk::Main myapp(&argc, &argv);
  MyWin mywin;

  myapp.run();
  return 0;
}



Next Previous Contents