Toolbars
Prev | Chapter 10. Menus and Toolbars | Next

## Toolbars

Applications often use `Toolbar`s to provide shortcuts to commonly-used menu items, such as File|Open or File|Save. They contain a row of buttons, usually with an icon. Each toolbar item can have an icon, text, and a tooltip. You will often be able to reuse standard gtkmm stock items such as `Gtk::Stock::SAVE`.

Elements are inserted by using classes from the

- `Element` - used for inserting arbitrary widgets

- `Space` - a blank spot, used to separate groups of elements

- `ButtonElem` - a regular button element

- `ToggleElem` - a toggle-button element

- `RadioElem` - a radio-button element

`Gtk::Toolbar_Helpers` namespace. The various helper objects are:

Here's the constructor for `Element`:

    Element(Widget& w,
            const Glib::ustring& tooltip_text=0,
            const Glib::ustring& tooltip_private_text=0);

`w` is the widget to insert, and `tooltip_text` is the text for the element's tooltip. You can ignore `tooltip_private_text`.

The constructors for `ButtonElem` and `ToggleElem` are exactly alike; each has three forms. Here are the `ButtonElem` constructors:

    // text + icon
    ButtonElem(const Glib::ustring& text,
               Widget        & content,
               SigC::Slot0<void>        callback,
               const Glib::ustring& tooltip_text=0,
               const Glib::ustring& tooltip_private_text=0);

    // icon only
    ButtonElem(Widget        & content,
               SigC::Slot0<void>        callback,
               const Glib::ustring& tooltip_text=0,
               const Glib::ustring& tooltip_private_text=0);

    // text only
    ButtonElem(const Glib::ustring& text,
               SigC::Slot0<void>        callback,
               const Glib::ustring& tooltip_text=0,
               const Glib::ustring& tooltip_private_text=0);

The only difference between these is whether they take an icon, text, or both as arguments. `text` is the text to display below the icon. `content` is the icon; note that any widget can be inserted here, but generally this will be a pixmap or other display widget. `callback` is the signal handler to use for the button. `tooltip_text` will be displayed in the button's tooltip, and you can safely ignore `tooltip_private_text`.

The `RadioElem` constructors are the same as those for `ButtonElem` and `RadioElem`, but they take an additional argument specifying the group for the radio button. Here they are:

    // text + icon
    RadioElem(Gtk::RadioButton_Helpers::Group& group,
              const Glib::ustring&      text,
              Widget&             content,
              SigC::Slot0<void>   callback=0,
              const Glib::ustring&      tooltip_text=0,
              const Glib::ustring&      tooltip_private_text=0);

    // icon only
    RadioElem(Gtk::RadioButton_Helpers::Group& group,
              Widget&             content,
              SigC::Slot0<void>   callback=0,
              const Glib::ustring&      tooltip_text=0,
              const Glib::ustring&      tooltip_private_text=0);

    // text only
    RadioElem(Gtk::RadioButton_Helpers::Group& group,
              const Glib::ustring&      text,
              SigC::Slot0<void>   callback=0,
              const Glib::ustring&      tooltip_text=0,
              const Glib::ustring&      tooltip_private_text=0);

The `group` argument is the only addition here; it works exactly like the `group` argument for normal radio buttons. See the Radio Buttons section for details.

The toolbar's contents are manipulated through an STL-like list, which you can obtain using the `tools()` method:

    ToolList& tools();

For example, to add a text-only button tool to the toolbar, we could write

    toolbar.tools().push_back(Gtk::Toolbar_Helpers::ButtonElem(
            "Crash",slot(&crash_cb),"Causes the program to dump core");

Since it's inconvenient to have to type `Gtk::Toolbar_Helpers` all the time, you might want to add a `using` declaration. However, don't add a global `using namespace Gtk::Toolbar_Helpers` declaration; place this only in some localised scope, to avoid clashes with other `Helpers` namespaces.

### Example

Figure 10.3. Toolbar

Source Code

Prev | Up | Next
Chapter 10. Menus and Toolbars | Home | Chapter 11. Adjustments