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.
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.
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:
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:
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;
}
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:
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;
}