GNOME.org

Multiple-item widgets

Multiple-item widgets inherit from Gtk::Container; just as with Gtk::Bin, you use the add() and remove() methods to add and remove contained widgets. Unlike Gtk::Bin::remove(), however, the remove() method for Gtk::Container takes an argument, specifiying which widget to remove.

7.2.1. Packing

You've probably noticed that gtkmm windows seem "elastic" - they can usually be stretched in many different ways. This is due to the widget packing system.

Many GUI toolkits require you to precisely place widgets in a window, using absolute positioning, often using a visual editor. This leads to several problems:

  • The widgets don't rearrange themselves when the window is resized. Some widgets are hidden when the window is made smaller, and lots of useless space appears when the window is made larger.
  • It's impossible to predict the amount of space necessary for text after it has been translated to other languages, or displayed in a different font. On Unix it is also impossible to anticipate the effects of every theme and window manager.
  • Changing the layout of a window "on the fly", to make some extra widgets appear, for instance, is complex. It requires tedious recalculation of every widget's position.

gtkmm uses the packing system to solve these problems. Rather than specifying the position and size of each widget in the window, you can arrange your widgets in rows, columns, and/or tables. gtkmm can size your window automatically, based on the sizes of the widgets it contains. And the sizes of the widgets are, in turn, determined by the amount of text they contain, or the minimum and maximum sizes that you specify, and/or how you have requested that the available space should be shared between sets of widgets. You can perfect your layout by specifying padding distance and centering values for each of your widgets. gtkmm then uses all this information to resize and reposition everything sensibly and smoothly when the user manipulates the window.

gtkmm arranges widgets hierarchically, using containers. A Container widget contains other widgets. Most gtkmm widgets are containers. Windows, Notebook tabs, and Buttons are all container widgets. There are two flavours of containers: single-child containers, which are all descendants of Gtk::Bin, and multiple-child containers, which are descendants of Gtk::Container. Most widgets in gtkmm are descendants of Gtk::Bin, including Gtk::Window.

Yes, that's correct: a Window can contain at most one widget. How, then, can we use a window for anything useful? By placing a multiple-child container in the window. The most useful container widgets are Gtk:VBox, Gtk::HBox, and Gtk::Table.

  • Gtk::VBox and Gtk::HBox arrange their child widgets vertically and horizontally, respectively. Use pack_start() and pack_end() to insert child widgets.
  • Gtk::Table arranges its widgets in a grid. Use attach() to insert widgets.

There are several other containers, which we will also discuss.

If you've never used a packing toolkit before, it can take some getting used to. You'll probably find, however, that you don't need to rely on visual form editors quite as much as you might with other toolkits.

7.2.2. An improved Hello World

Let's take a look at a slightly improved helloworld, showing what we've learnt.

Figure 7-6 Hello World 2

Source Code

File: helloworld.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLE_HELLOWORLD_H
#define GTKMM_EXAMPLE_HELLOWORLD_H

#include <gtkmm/box.h>
#include <gtkmm/button.h>
#include <gtkmm/window.h>

class HelloWorld : public Gtk::Window
{
public:
  HelloWorld();
  virtual ~HelloWorld();

protected:

  // Signal handlers:
  // Our new improved on_button_clicked(). (see below)
  void on_button_clicked(Glib::ustring data);

  // Child widgets:
  Gtk::HBox m_box1;
  Gtk::Button m_button1, m_button2;
};

#endif // GTKMM_EXAMPLE_HELLOWORLD_H

File: main.cc (For use with gtkmm 2, not gtkmm 3) 

#include "helloworld.h"
#include <gtkmm/main.h>

int main (int argc, char *argv[])
{
  Gtk::Main kit(argc, argv);

  HelloWorld helloworld;
  //Shows the window and returns when it is closed.
  Gtk::Main::run(helloworld);

  return 0;
}

File: helloworld.cc (For use with gtkmm 2, not gtkmm 3) 

#include "helloworld.h"
#include <iostream>

HelloWorld::HelloWorld()
: m_button1("Button 1"),
  m_button2("Button 2")
{
  // This just sets the title of our new window.
  set_title("Hello Buttons!");

  // sets the border width of the window.
  set_border_width(10);

  // put the box into the main window.
  add(m_box1);

  // Now when the button is clicked, we call the "on_button_clicked" function
  // with a pointer to "button 1" as it's argument
  m_button1.signal_clicked().connect(sigc::bind<Glib::ustring>(
              sigc::mem_fun(*this, &HelloWorld::on_button_clicked), "button 1"));

  // instead of gtk_container_add, we pack this button into the invisible
  // box, which has been packed into the window.
  // note that the pack_start default arguments are Gtk::EXPAND | Gtk::FILL, 0
  m_box1.pack_start(m_button1);

  // always remember this step, this tells GTK that our preparation
  // for this button is complete, and it can be displayed now.
  m_button1.show();

  // call the same signal handler with a different argument,
  // passing a pointer to "button 2" instead.
  m_button2.signal_clicked().connect(sigc::bind<-1, Glib::ustring>(
              sigc::mem_fun(*this, &HelloWorld::on_button_clicked), "button 2"));

  m_box1.pack_start(m_button2);

  // Show the widgets.
  // They will not really be shown until this Window is shown.
  m_button2.show();
  m_box1.show();
}

HelloWorld::~HelloWorld()
{
}

// Our new improved signal handler.  The data passed to this method is
// printed to stdout.
void HelloWorld::on_button_clicked(Glib::ustring data)
{
  std::cout << "Hello World - " << data << " was pressed" << std::endl;
}

After building and running this program, try resizing the window to see the behaviour. Also, try playing with the options to pack_start() while reading the Boxes section.

7.2.3. C++ Standard Library-style APIs

If you're an accomplished C++ programmer, you'll be happy to hear that most of the gtkmm Container widgets provide C++ Standard Library-style APIs, available via accessor methods, such as Gtk::Box::children() or Gtk::Notebook::pages(). They don't use actual C++ Standard Library containers (there are good reasons for this), but they look, feel, and act much like regular container classes.

These APIs are so similar to C++ Standard Library container APIs that, rather than explaining them in detail, we can refer you to the C++ documentation for most of their methods. This is all part of gtkmm's policy of reusing existing standards.

However, C++ Standard Library-style APIs can require awkward or lengthy code in some situations, so some people prefer not to use them, while other people use them religiously. Therefore, you are not forced to use them - most container widgets have a simpler API, with methods such as append() and prepend().

At a minimum, gtkmm container lists support iterators and the usual insertion, deletion, and addition methods. You can always expect the following methods to be available for gtkmm C++ Standard Library-style APIs:

  • begin() returns a begin iterator
  • end() returns an end iterator
  • rbegin() returns a reverse begin iterator
  • rend() returns a reverse end iterator
  • size()
  • max_size()
  • empty()
  • insert()
  • push_front()
  • push_back()
  • pop_front()
  • pop_back()
  • clear()
  • erase()
  • remove()
  • find()
  • front()
  • back()

Also, the [] operator is overloaded, but that is usually order N, so if performance is a consideration, or the list has a large number of elements, think carefully before using it.

The element objects and list objects are defined, for each container, in a namespace whose name ends in _Helpers. For example, the helper namespace for the notebook widget is Gtk::Notebook_Helpers.

7.2.3.1. Adding items

There is a major difference between gtkmm APIs and real C++ Standard Library containers. Normally, when you use a std::vector, for example, you expect that whatever you put in, you'll get out, unmodified. You wouldn't make a std::vector<int> and expect to get doubles out of it. But, gtkmm APIs don't always work like that - you will often put one kind of object in, and later get a different kind out. Why this odd behaviour?

Consider a menu widget, which must maintain a hierarchical list of menus and menu items. Menus can only contain certain objects, such as menu items, separators, and submenus. To ensure consistency, a "filter" is needed to keep out illegal objects. Also, since only a few types of objects are allowed, convenience methods can be provided to make it easy to build up menus.

gtkmm takes care of both requirements using special helper elements. Helper elements are temporary - they're typically constructed and passed to an insertion method in the same call. The list insertion method uses the information in the helper element to construct the real object, which is then inserted into the container.

As an example, let's look at the Notebook widget (explained in the section on Notebooks). Notebook widgets contain a series of "pages".

Each page in a notebook requires, at minimum, the following information:

  • A child widget (zero or one), to be placed in the page
  • A label for the page's tab

(The gtkmm notebook widget keeps other data for each page as well.)

To insert a new page in a notebook, we can use one of the notebook helper classes, like this: 

notebook->pages().push_back(
          Gtk::Notebook_Helpers::TabElem(*frame, bufferl));

Let's see what's going on here. Assume we have a pointer to a Notebook widget called notebook; we go from that to a member method called pages(), which returns a list object. On this we call the method push_back() (this should be familiar to those who know C++).

The object that the pages() method returns is called a Notebook_Helpers::PageList. It's one of the containers that we keep referring to. Let's take a look at this class (this has been heavily edited for clarity; see <gtkmm/notebook.h> for the actual definition): 

namespace Notebook_Helpers
{
    class PageList
    {
    public:
             . . .
        void push_back(const Element& e);
             . . .
        Page* operator[](size_type l);
    };
};

There are two important things to notice here:

  • The push_back() method takes as argument an Element object (helper);
  • The overloaded [] operator returns a pointer to a Page.

This scheme has some important advantages:

  • We can provide as many different Helper objects as desired, making it simple to construct complex widgets like Menus.
  • Construction of the actual objects can be delayed until an appropriate time. Sometimes we don't have enough information until later with GTK+.
  • The definitions of the objects contained in the list can change; their interfaces need not concern the programmer. For example, even if the Page object changes drastically, the programmer need not be concerned; the Elements need not change, and will continue to work as expected.
  • New Element objects can be added at any time to support new features, without breaking existing code.

All multi-item containers have an Element object in their helper namespaces, and usually there are additional classes available (like TabElem and MenuElem) which derive from Element. Element classes vary from container to container, since each contains different kinds of objects.

It's very important to remember that Elements are not "real" objects. They exist only temporarily, and they are never stored in the container. They are used only as temporary "parameter-holders". Therefore, the following segment of code is illegal: 

MenuElem* m = new MenuElem("hello");
m->right_justify();
items().push_back(*m);

We constructed a new MenuElem helper object, and then tried to invoke right_justify() on it before adding it to the menu. The trouble is that there is no right_justify() method in the MenuElem class. The correct way to accomplish this would be: 

items().push_back(MenuElem("hello"));
items().back()->right_justify();

Here, we've constructed a MenuElem and inserted it into the menu by passing it to push_back(), causing the real menu item to be created. We've then called right_justify() on the object retrieved from the list. This is correct - the object retrieved from the list is not a MenuElem, but a real MenuItem, and therefore supports the right_justify() method as expected.

7.2.4. Boxes

Most packing uses boxes as in the above example. These are invisible containers into which we can pack our widgets. When packing widgets into a horizontal box, the objects are inserted horizontally from left to right or right to left depending on whether pack_start() or pack_end() is 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.

7.2.4.1. Adding widgets

7.2.4.1.1. Per-child packing options

The pack_start() and pack_end() methods place widgets inside these containers. The pack_start() method will start at the top and work its way down in a VBox, or pack left to right in an HBox. pack_end() will do the opposite, packing from bottom to top in a VBox, or right to left in an HBox. Using these methods allows us to right justify or left justify our widgets. We will use pack_start() in most of our examples.

There are several options governing how widgets are to be packed, and this can be confusing at first. If you have difficulties then it is sometimes a good idea to play with the glade GUI designer to see what is possible. You might even decide to use the Gtk::Builder API to load your GUI at runtime.

There are basically five different styles, as shown in this picture:

Figure 7-7 Box Packing 1

Each line contains one horizontal box (HBox) with several buttons. Each of the buttons on a line is packed into the HBox with the same arguments to the pack_start() method).

This is the declaration of the pack_start() method: 

void pack_start(Gtk::Widget& child,
                PackOptions options = PACK_EXPAND_WIDGET,
                guint padding = 0);

The first argument is the widget you're packing. In our example these are all Buttons.

The options argument can take one of these three options:

  • PACK_SHRINK: Space is contracted to the child widget size. The widget will take up just-enough space and never expand.
  • PACK_EXPAND_PADDING: Extra space is filled with padding. The widgets will be spaced out evenly, but their sizes won't change - there will be empty space between the widgets instead.
  • PACK_EXPAND_WIDGET: Extra space is taken up by increasing the child widget size, without changing the amount of space between widgets.

The padding argument specifies the width of an extra border area to leave around the packed widget.

Instead of the pack_start() and pack_end() methods, you might prefer to use the C++ Standard Library-style API, available via the children method. See the C++ Standard Library-style APIs section for more details.

Reference

7.2.4.1.2. Per-container packing options

Here's the constructor for the box widgets: 

Gtk::Box(bool homogeneous = false, int spacing = 0);
Passing true for homogeneous will cause 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, and padding is added on either side of a widget. The following figure should make it clearer:

Figure 7-8 Box Packing 2

7.2.4.2. Example

Here is the source code for the example that produced the screenshots above. When you run this example, provide a number between 1 and 3 as a command-line option, to see different packing options in use.

Source Code

File: packbox.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLE_PACKBOX_H
#define GTKMM_EXAMPLE_PACKBOX_H

#include <gtkmm.h>

class PackBox : public Gtk::HBox
{
public:
  PackBox(bool homogeneous, int spacing, Gtk::PackOptions, int padding = 0);
  virtual ~PackBox();

protected:
  Gtk::Button m_button1, m_button2, m_button3;
  Gtk::Button* m_pbutton4;

  char padstr[80];
};

#endif //GTKMM_EXAMPLE_PACKBOX_H

File: examplewindow.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include <gtkmm.h>
#include "packbox.h"

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow(int which);
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_button_quit_clicked();

  //Child widgets:
  Gtk::Button m_button;
  Gtk::VBox m_box1;
  Gtk::HBox m_boxQuit;
  Gtk::Button m_buttonQuit;

  Gtk::Label m_Label1, m_Label2;

  Gtk::HSeparator m_seperator1, m_seperator2, m_seperator3, m_seperator4, m_seperator5;
};

#endif //GTKMM_EXAMPLEWINDOW_H

File: examplewindow.cc (For use with gtkmm 2, not gtkmm 3) 

#include <iostream>
#include "examplewindow.h"

ExampleWindow::ExampleWindow(int which)
: m_buttonQuit("Quit")
{
  set_title("Gtk::Box example");

  PackBox *pPackBox1, *pPackBox2, *pPackBox3, *pPackBox4, *pPackBox5;

  switch(which)
  {
    case 1:
    {
      m_Label1.set_text("Gtk::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(Gtk::ALIGN_START, Gtk::ALIGN_START);

      // 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, Gtk::PACK_SHRINK);

      // Create a PackBox - homogeneous = false, spacing = 0,
      // options = Gtk::PACK_SHRINK, padding = 0
      pPackBox1 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_SHRINK));
      m_box1.pack_start(*pPackBox1, Gtk::PACK_SHRINK);

      // Create a PackBox - homogeneous = false, spacing = 0,
      // options = Gtk::PACK_EXPAND_PADDING, padding = 0
      pPackBox2 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_EXPAND_PADDING));
      m_box1.pack_start(*pPackBox2, Gtk::PACK_SHRINK);

      // Create a PackBox - homogeneous = false, spacing = 0,
      // options = Gtk::PACK_EXPAND_WIDGET, padding = 0
      pPackBox3 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_EXPAND_WIDGET));
      m_box1.pack_start(*pPackBox3, Gtk::PACK_SHRINK);

      // 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, Gtk::PACK_SHRINK, 5);

      // create another new label, and show it.
      m_Label2.set_text("Gtk::HBox(true, 0);");
      m_Label2.set_alignment(Gtk::ALIGN_START, Gtk::ALIGN_START);
      m_box1.pack_start(m_Label2, Gtk::PACK_SHRINK);

      // Args are: homogeneous, spacing, options, padding
      pPackBox4 = Gtk::manage(new PackBox(true, 0, Gtk::PACK_EXPAND_PADDING));
      m_box1.pack_start(*pPackBox4, Gtk::PACK_SHRINK);

      // Args are: homogeneous, spacing, options, padding
      pPackBox5 = Gtk::manage(new PackBox(true, 0, Gtk::PACK_EXPAND_WIDGET));
      m_box1.pack_start(*pPackBox5, Gtk::PACK_SHRINK);

      m_box1.pack_start(m_seperator2, Gtk::PACK_SHRINK, 5);

      break;
    }

    case 2:
    {

      m_Label1.set_text("Gtk::HBox(false, 10);");
      m_Label1.set_alignment(Gtk::ALIGN_START, Gtk::ALIGN_START);
      m_box1.pack_start(m_Label1, Gtk::PACK_SHRINK);

      pPackBox1 = Gtk::manage(new PackBox(false, 10, Gtk::PACK_EXPAND_PADDING));
      m_box1.pack_start(*pPackBox1, Gtk::PACK_SHRINK);

      pPackBox2 = Gtk::manage(new PackBox(false, 10, Gtk::PACK_EXPAND_WIDGET));
      m_box1.pack_start(*pPackBox2, Gtk::PACK_SHRINK);

      m_box1.pack_start(m_seperator1, Gtk::PACK_SHRINK, 5);


      m_Label2.set_text("Gtk::HBox(false, 0);");
      m_Label2.set_alignment(Gtk::ALIGN_START, Gtk::ALIGN_START);
      m_box1.pack_start(m_Label2, Gtk::PACK_SHRINK);

      pPackBox3 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_SHRINK, 10));
      m_box1.pack_start(*pPackBox3, Gtk::PACK_SHRINK);

      pPackBox4 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_EXPAND_WIDGET, 10));
      m_box1.pack_start(*pPackBox4, Gtk::PACK_SHRINK);

      m_box1.pack_start(m_seperator2, Gtk::PACK_SHRINK, 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.
      pPackBox1 = Gtk::manage(new PackBox(false, 0, Gtk::PACK_SHRINK));

      // create the label that will be put at the end.
      m_Label1.set_text("end");

      // pack it using pack_end(), so it is put on the right side
      // of the PackBox.
      pPackBox1->pack_end(m_Label1, Gtk::PACK_SHRINK);

      m_box1.pack_start(*pPackBox1, Gtk::PACK_SHRINK);

      // 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_size_request(400, 5);

      // pack the separator into ourselves
      m_box1.pack_start(m_seperator1, Gtk::PACK_SHRINK, 5);

      break;
    }

    default:
    {
      std::cerr << "Unexpected command-line option." << std::endl;
      break;
    }
  }

  // Connect the signal to hide the window:
  m_buttonQuit.signal_clicked().connect( sigc::mem_fun(*this,
              &ExampleWindow::on_button_quit_clicked) );

  // pack the button into the quitbox.
  // The last 2 arguments to Box::pack_start are: options, padding.
  m_boxQuit.pack_start(m_buttonQuit, Gtk::PACK_EXPAND_PADDING);
  m_box1.pack_start(m_boxQuit, Gtk::PACK_SHRINK);

  // pack the vbox (box1) which now contains all our widgets, into the
  // main window.
  add(m_box1);

  show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_quit_clicked()
{
  hide();
}

File: main.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include <gtkmm/main.h>
#include <iostream>
#include <cstdlib>

using std::atoi;

int main(int argc, char *argv[])
{
  Gtk::Main main_instance(argc, argv);

  if(argc != 2)
  {
    std::cerr << "usage: packbox num, where num is 1, 2, or 3." << std::endl;
    return 1;
  }

  ExampleWindow window( atoi(argv[1]) );
  Gtk::Main::run(window); //Shows the window and returns when it is closed.

  return 0;
}

File: packbox.cc (For use with gtkmm 2, not gtkmm 3) 

#include "packbox.h"
#include <cstdio> //For sprintf().

PackBox::PackBox(bool homogeneous, int spacing, Gtk::PackOptions options,
        int padding) :
  Gtk::HBox(homogeneous, spacing),
  m_button1("box.pack_start("),
  m_button2("button,"),
  m_button3((options == Gtk::PACK_SHRINK) ? "Gtk::PACK_SHRINK" :
            ((options == Gtk::PACK_EXPAND_PADDING) ?
             "Gtk::PACK_EXPAND_PADDING" : "Gtk::PACK_EXPAND_WIDGET"))
{
  pack_start(m_button1, options, padding);
  pack_start(m_button2, options, padding);
  pack_start(m_button3, options, padding);

  sprintf(padstr, "%d);", padding);

  m_pbutton4 = new Gtk::Button(padstr);
  pack_start(*m_pbutton4, options, padding);
}

PackBox::~PackBox()
{
  delete m_pbutton4;
}

7.2.5. ButtonBoxes

Button boxes are a convenient way to quickly arrange a group of buttons. They come in both horizontal (Gtk::HButtonBox) and vertical (Gtk::VButtonBox) flavours. They are exactly alike, except in name and orientation.

ButtonBoxes help to make applications appear consistent because they use standard settings, such as inter-button spacing and packing.

Buttons are added to a ButtonBox with the add() method.

Button boxes support several layout styles. The style can be retrieved and changed using get_layout() and set_layout().

Reference

7.2.5.1. Example

Figure 7-9 ButtonBox

Source Code

File: examplebuttonbox.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLE_BUTTONBOX_H
#define GTKMM_EXAMPLE_BUTTONBOX_H

#include <gtkmm.h>

class ExampleButtonBox : public Gtk::Frame
{
public:
  ExampleButtonBox(bool horizontal,
       const Glib::ustring& title,
       gint spacing,
       Gtk::ButtonBoxStyle layout);

protected:
  Gtk::Button m_Button_OK, m_Button_Cancel, m_Button_Help;
};

#endif //GTKMM_EXAMPLE_BUTTONBOX_H

File: examplewindow.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include <gtkmm.h>

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_button_clicked();

  //Child widgets:
  Gtk::VBox m_VBox_Main, m_VBox;
  Gtk::HBox m_HBox;
  Gtk::Frame m_Frame_Horizontal, m_Frame_Vertical;
};

#endif //GTKMM_EXAMPLEWINDOW_H

File: examplebuttonbox.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplebuttonbox.h"

ExampleButtonBox::ExampleButtonBox(bool horizontal,
       const Glib::ustring& title,
       gint spacing,
       Gtk::ButtonBoxStyle layout)
: Gtk::Frame(title),
  m_Button_OK("OK"),
  m_Button_Cancel("Cancel"),
  m_Button_Help("Help")
{
  Gtk::ButtonBox* bbox = 0;

  if(horizontal)
    bbox = Gtk::manage( new Gtk::HButtonBox() );
  else
    bbox = Gtk::manage( new Gtk::VButtonBox() );

  bbox->set_border_width(5);

  add(*bbox);

  /* Set the appearance of the Button Box */
  bbox->set_layout(layout);
  bbox->set_spacing(spacing);

  bbox->add(m_Button_OK);
  bbox->add(m_Button_Cancel);
  bbox->add(m_Button_Help);
}

File: examplewindow.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include "examplebuttonbox.h"

ExampleWindow::ExampleWindow()
: m_Frame_Horizontal("Horizontal Button Boxes"),
  m_Frame_Vertical("Vertical Button Boxes")
{
  set_title("Gtk::ButtonBox");
  add(m_VBox_Main);

  m_VBox_Main.pack_start(m_Frame_Horizontal, Gtk::PACK_EXPAND_WIDGET, 10);

  //The horizontal ButtonBoxes:
  m_VBox.set_border_width(10);
  m_Frame_Horizontal.add(m_VBox);

  m_VBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(true, "Spread (spacing 40)", 40,
                  Gtk::BUTTONBOX_SPREAD)),
          Gtk::PACK_EXPAND_WIDGET, 0);

  m_VBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(true, "Edge (spacing 30)", 30,
                  Gtk::BUTTONBOX_EDGE)),
          Gtk::PACK_EXPAND_WIDGET, 5);

  m_VBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(true, "Start (spacing 20)", 20,
                  Gtk::BUTTONBOX_START)),
          Gtk::PACK_EXPAND_WIDGET, 5);

  m_VBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(true, "end (spacing 10)", 10,
                  Gtk::BUTTONBOX_END)),
          Gtk::PACK_EXPAND_WIDGET, 5);


  //The vertical ButtonBoxes:
  m_VBox_Main.pack_start(m_Frame_Vertical, Gtk::PACK_EXPAND_WIDGET, 10);

  m_HBox.set_border_width(10);
  m_Frame_Vertical.add(m_HBox);

  m_HBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(false, "Spread (spacing 5)", 5,
                  Gtk::BUTTONBOX_SPREAD)),
          Gtk::PACK_EXPAND_WIDGET, 0);

  m_HBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(false, "Edge (spacing 30)", 30,
                  Gtk::BUTTONBOX_EDGE)),
          Gtk::PACK_EXPAND_WIDGET, 5);

  m_HBox.pack_start(*Gtk::manage(
              new ExampleButtonBox(false, "Start (spacing 20)", 20,
                  Gtk::BUTTONBOX_START)),
          Gtk::PACK_EXPAND_WIDGET, 5);

  m_HBox.pack_start(*Gtk::manage(new ExampleButtonBox(false, "End (spacing 10)",
                  10, Gtk::BUTTONBOX_END)),
          Gtk::PACK_EXPAND_WIDGET, 5);

  show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_clicked()
{
  hide();
}

File: main.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include <gtkmm/main.h>

int main(int argc, char *argv[])
{
  Gtk::Main kit(argc, argv);

  ExampleWindow window;
  //Shows the window and returns when it is closed.
  Gtk::Main::run(window);

  return 0;
}

7.2.6. Table

Tables allows us to place widgets in a grid.

7.2.6.1. Constructor

The grid's dimensions need to be specified in the constructor: 

Gtk::Table(int rows = 1, int columns = 1, bool homogeneous = false);

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 cells will all be the same size (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.

7.2.6.2. Adding widgets

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

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 2 x 2 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 2 x 2 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 is allocated less space than it requested (because the user resized the window), then the widgets will normally just disappear off the bottom of the window. If Gtk::SHRINK is specified, the widgets will shrink with the table.

Gtk::EXPAND

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

The padding arguments work just as they do for pack_start().

7.2.6.3. Other methods

set_row_spacing() and set_col_spacing() set the spacing between the rows at the specified row or column. 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 for all rows and/or columns with set_row_spacings() and set_col_spacings(). Note that with these calls, the last row and last column do not get any spacing.

Reference

7.2.6.4. Example

In the following example, we make a window with three buttons in a 2 x 2 table. The first two buttons will be placed in the upper row. A third button is placed in the lower row, spanning both columns.

Figure 7-10 Table

Source Code

File: examplewindow.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include <gtkmm.h>

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_button_quit();
  void on_button_numbered(Glib::ustring data);

  //Child widgets:
  Gtk::Table m_Table;
  Gtk::Button m_Button_1, m_Button_2, m_Button_Quit;

};

#endif //GTKMM_EXAMPLEWINDOW_H

File: examplewindow.cc (For use with gtkmm 2, not gtkmm 3) 

#include <iostream>
#include "examplewindow.h"

ExampleWindow::ExampleWindow()
: m_Table(2, 2, true),
  m_Button_1("button 1"),
  m_Button_2("button 2"),
  m_Button_Quit("Quit")
{
  set_title("Gtk::Table");
  set_border_width(20);

  add(m_Table);

  m_Table.attach(m_Button_1, 0, 1, 0, 1);
  m_Table.attach(m_Button_2, 1, 2, 0, 1);
  m_Table.attach(m_Button_Quit, 0, 2, 1, 2);

  m_Button_1.signal_clicked().connect(
          sigc::bind<Glib::ustring>( sigc::mem_fun(*this,
                  &ExampleWindow::on_button_numbered), "button 1") );
  m_Button_2.signal_clicked().connect(
          sigc::bind<Glib::ustring>( sigc::mem_fun(*this,
                  &ExampleWindow::on_button_numbered), "button 2") );

  m_Button_Quit.signal_clicked().connect(sigc::mem_fun(*this,
              &ExampleWindow::on_button_quit) );

  show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_quit()
{
  hide();
}

void
ExampleWindow::on_button_numbered(Glib::ustring data)
{
  std::cout << "Hello again - " << data << " was pressed" << std::endl;
}

File: main.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include <gtkmm/main.h>

int main(int argc, char *argv[])
{
  Gtk::Main kit(argc, argv);

  ExampleWindow window;
  //Shows the window and returns when it is closed.
  Gtk::Main::run(window);

  return 0;
}

7.2.7. Notebook

A Notebook has a set of stacked pages, each of which contains widgets. Labelled tabs allow the user to select the pages. Notebooks allow several sets of widgets to be placed in a small space, by only showing one page at a time. For instance, they are often used in preferences dialogs.

Use the append_page(), prepend_page() and insert_page() methods to add tabbed pages to the Notebook, supplying the child widget and the name for the tab.

To discover the currently visible page, use the get_current_page() method. This returns the page number, and then calling get_nth_page() with that number will give you a pointer to the actual child widget.

To programmatically change the selected page, use the set_current_page() method.

There is also an C++ Standard Library-style API which you might find more obvious.

Reference

7.2.7.1. Example

Figure 7-11 Notebook

Source Code

File: examplewindow.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include <gtkmm.h>

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Signal handlers:
  void on_button_quit();
  void on_notebook_switch_page(GtkNotebookPage* page, guint page_num);

  //Child widgets:
  Gtk::VBox m_VBox;
  Gtk::Notebook m_Notebook;
  Gtk::Label m_Label1, m_Label2;

  Gtk::HButtonBox m_ButtonBox;
  Gtk::Button m_Button_Quit;
};

#endif //GTKMM_EXAMPLEWINDOW_H

File: examplewindow.cc (For use with gtkmm 2, not gtkmm 3) 

#include <iostream>
#include "examplewindow.h"

ExampleWindow::ExampleWindow()
: m_Label1("Contents of tab 1"),
  m_Label2("Contents of tab 2"),
  m_Button_Quit("Quit")
{
  set_title("Gtk::Notebook example");
  set_border_width(10);
  set_default_size(400, 200);


  add(m_VBox);

  //Add the Notebook, with the button underneath:
  m_Notebook.set_border_width(10);
  m_VBox.pack_start(m_Notebook);
  m_VBox.pack_start(m_ButtonBox, Gtk::PACK_SHRINK);

  m_ButtonBox.pack_start(m_Button_Quit, Gtk::PACK_SHRINK);
  m_Button_Quit.signal_clicked().connect(sigc::mem_fun(*this,
              &ExampleWindow::on_button_quit) );

  //Add the Notebook pages:
  m_Notebook.append_page(m_Label1, "First");
  m_Notebook.append_page(m_Label2, "Second");

  m_Notebook.signal_switch_page().connect(sigc::mem_fun(*this,
              &ExampleWindow::on_notebook_switch_page) );

  show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_quit()
{
  hide();
}

void ExampleWindow::on_notebook_switch_page(GtkNotebookPage* /* page */, guint page_num)
{
  std::cout << "Switched to tab with index " << page_num << std::endl;

  //You can also use m_Notebook.get_current_page() to get this index.
}

File: main.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include <gtkmm/main.h>

int main(int argc, char *argv[])
{
  Gtk::Main kit(argc, argv);

  ExampleWindow window;
  //Shows the window and returns when it is closed.
  Gtk::Main::run(window);

  return 0;
}

7.2.7.2. C++ Standard Library-style API

The Gtk::Notebook widget has a C++ Standard Library-style API, available via the pages() method, which you might prefer to use to add and access pages. See the C++ Standard Library-style APIs section for generic information.

PageList Reference

To insert pages into a notebook, use the TabElem helper class, like so: 

m_Notebook.pages().push_back(
    Gtk::Notebook_Helpers::TabElem(m_ChildWidget, "tab 1") );

TabElem Reference.

To access an existing child widget, you can call get_child() on one of the Page elements of the PageList: 

Gtk::Widget* pWidget = m_Notebook.pages()[2].get_child();

7.2.8. Assistant

An Assistant splits a complex operation into steps. Each step is a page, containing a header, a child widget and an action area. The Assistant's action area has navigation buttons which update automatically depending on the type of the page, set with set_page_type().

Use the append_page(), prepend_page and insert_page() methods to add pages to the Assistant, supplying the child widget for each page.

To determine the currently-visible page, use the get_current_page() method, and pass the result to get_nth_page(), which returns a pointer to the actual widget. To programmatically change the current page, use the set_current_page() method.

To set the title of a page, use the set_page_title() method. The header and side images of a page can be set with the set_page_header_image() and set_page_side_image() methods.

To add widgets to the action area, use the add_action_widget() method. They will be packed alongside the default buttons. Use the remove_action_widget() method to remove widgets.

Reference

7.2.8.1. Example

Figure 7-12 Assistant

Source Code

File: exampleassistant.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLEASSISTANT_H
#define GTKMM_EXAMPLEASSISTANT_H

#include <gtkmm.h>

class ExampleAssistant : public Gtk::Assistant
{
public:
  ExampleAssistant();
  virtual ~ExampleAssistant();

  void get_result(bool& check_state, Glib::ustring& entry_text);

private:
  // Signal handlers:
  void on_assistant_apply();
  void on_assistant_cancel();
  void on_assistant_close();
  void on_assistant_prepare(Gtk::Widget* widget);
  void on_entry_changed();

  // Member functions:
  void print_status();

  // Child widgets:
  Gtk::HBox m_box;
  Gtk::Label m_label1, m_label2;
  Gtk::CheckButton m_check;
  Gtk::Entry m_entry;
};

#endif /* GTKMM_EXAMPLEASSISTANT_H */

File: examplewindow.h (For use with gtkmm 2, not gtkmm 3) 

#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include "exampleassistant.h"
#include <gtkmm.h>

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

private:
  // Signal handlers:
  void on_button_clicked();
  void on_assistant_apply();

  // Child widgets:
  Gtk::Table m_table;
  Gtk::Button m_button;
  Gtk::Label m_label1, m_label2;
  Gtk::CheckButton m_check;
  Gtk::Entry m_entry;
  ExampleAssistant m_assistant;
};

#endif /* GTKMM_EXAMPLEWINDOW_H */

File: examplewindow.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include "exampleassistant.h"

ExampleWindow::ExampleWindow()
: m_table(3, 2),
  m_button("Show the assistant"),
  m_label1("State of assistant checkbutton:"),
  m_label2("Contents of assistant entry:")
{
  set_title("Gtk::Assistant example");
  set_border_width(12);

  m_table.attach(m_button, 0, 2, 0, 1, Gtk::FILL, Gtk::EXPAND);
  m_table.attach(m_label1, 0, 1, 1, 2, Gtk::FILL, Gtk::EXPAND);
  m_table.attach(m_label2, 0, 1, 2, 3, Gtk::FILL, Gtk::EXPAND);
  m_table.attach(m_check, 1, 2, 1, 2);
  m_table.attach(m_entry, 1, 2, 2, 3);
  add(m_table);

  m_label1.set_alignment(0.0, 0.5);
  m_label2.set_alignment(0.0, 0.5);

  m_button.signal_clicked().connect(sigc::mem_fun(*this,
    &ExampleWindow::on_button_clicked));
  m_assistant.signal_apply().connect(sigc::mem_fun(*this,
    &ExampleWindow::on_assistant_apply));

  m_check.set_sensitive(false);
  m_entry.set_sensitive(false);

  show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_assistant_apply()
{
  bool check_state;
  Glib::ustring entry_text;

  m_assistant.get_result(check_state, entry_text);
  m_check.set_active(check_state);
  m_entry.set_text(entry_text);
}

void ExampleWindow::on_button_clicked()
{
  m_assistant.show();
}

File: main.cc (For use with gtkmm 2, not gtkmm 3) 

#include "examplewindow.h"
#include <gtkmm/main.h>

int main(int argc, char *argv[])
{
  Gtk::Main kit(argc, argv);

  ExampleWindow window;
  // Shows the window and returns when it is closed.
  Gtk::Main::run(window);

  return 0;
}

File: exampleassistant.cc (For use with gtkmm 2, not gtkmm 3) 

#include <iostream>
#include "exampleassistant.h"

ExampleAssistant::ExampleAssistant()
: m_box(false, 12),
  m_label1("Type text to allow the assistant to continue:"),
  m_label2("Confirmation page"),
  m_check("Optional extra information")
{
  set_title("Gtk::Assistant example");
  set_border_width(12);
  set_default_size(400, 300);

  m_box.pack_start(m_label1);
  m_box.pack_start(m_entry);

  append_page(m_box);
  append_page(m_check);
  append_page(m_label2);

  set_page_title(*get_nth_page(0), "Page 1");
  set_page_title(*get_nth_page(1), "Page 2");
  set_page_title(*get_nth_page(2), "Confirmation");

  set_page_complete(m_check, true);
  set_page_complete(m_label2, true);

  set_page_type(m_box, Gtk::ASSISTANT_PAGE_INTRO);
  set_page_type(m_label2, Gtk::ASSISTANT_PAGE_CONFIRM);

  signal_apply().connect(sigc::mem_fun(*this,
    &ExampleAssistant::on_assistant_apply));
  signal_cancel().connect(sigc::mem_fun(*this,
    &ExampleAssistant::on_assistant_cancel));
  signal_close().connect(sigc::mem_fun(*this,
    &ExampleAssistant::on_assistant_close));
  signal_prepare().connect(sigc::mem_fun(*this,
    &ExampleAssistant::on_assistant_prepare));

  m_entry.signal_changed().connect(sigc::mem_fun(*this,
    &ExampleAssistant::on_entry_changed));

  show_all_children();
}

ExampleAssistant::~ExampleAssistant()
{
}

void ExampleAssistant::get_result(bool& check_state, Glib::ustring& entry_text)
{
  check_state = m_check.get_active();
  entry_text = m_entry.get_text();
}

void ExampleAssistant::on_assistant_apply()
{
  std::cout << "Apply was clicked";
  print_status();
}

void ExampleAssistant::on_assistant_cancel()
{
  std::cout << "Cancel was clicked";
  print_status();
  hide();
}

void ExampleAssistant::on_assistant_close()
{
  std::cout << "Assistant was closed";
  print_status();
  hide();
}

void ExampleAssistant::on_assistant_prepare(Gtk::Widget* /* widget */)
{
  set_title(Glib::ustring::compose("Gtk::Assistant example (Page %1 of %2)",
    get_current_page() + 1, get_n_pages()));
}

void ExampleAssistant::on_entry_changed()
{
  // The page is only complete if the entry contains text.
  if(m_entry.get_text_length())
    set_page_complete(m_box, true);
  else
    set_page_complete(m_box, false);
}

void ExampleAssistant::print_status()
{
  std::cout << ", entry contents: \"" << m_entry.get_text()
    << "\", checkbutton status: " << m_check.get_active() << std::endl;
}
Single-item Containers The TreeView widget

About