Tutorial
Inti Logo
« Button Boxes
 Notebooks »

Toolbar

Toolbars are usually used to group some number of widgets in order to simplify customization of their look and layout. Typically a toolbar consists of buttons with icons, labels and tooltips, but any other widget can also be put inside a toolbar. Finally, items can be arranged horizontally or vertically and buttons can be displayed with icons, labels, or both.

Creating a toolbar (as you may already suspect) is done with the following constructor:

explicit Toolbar(Gtk::Orientation orientation = Gtk::ORIENTATION_HORIZONTAL, Gtk::ToolbarStyle style = Gtk::TOOLBAR_ICONS);

The orientation argument specifies the whether to toolbar should be horizontal or vertical and can be one of the values in the Gtk::Orientation enumeration:
The style argument specifies whether the toolbar should display icons, text or both. It can be one of the values in the Gtk::ToolbarStyle enumeration:
After creating a toolbar you can append, prepend and insert items (that means simple text strings) or elements (that means any widget types) into the toolbar. To describe an item we need a label text, a tooltip text, a private tooltip text, an icon for the button and a signal handler for it. For example, to append or prepend a button you may use the following methods:

Gtk::Button* append_button
(
    const String& text,
    Gtk::Widget *icon,
    Slot0<void> *callback,
    const String& tooltip_text = 0,
    const String& tooltip_private_text = 0
);

Gtk::Button* prepend_button
(
    const String& text,
    Gtk::Widget *icon,
    Slot0<void> *callback,
    const String& tooltip_text = 0,
    const String& tooltip_private_text = 0
);

If you want to insert a button at a specific position, the only additional parameter which must be specified is the zero-based index at which the button should be inserted:

Gtk::Button* insert_button
(
    const String& text,
    Gtk::Widget *icon,
    Slot0<void> *callback,
    int position,
    const String& tooltip_text = 0,
    const String& tooltip_private_text = 0
);

There are several other sets of methods that can be used to append, prepend and insert various items. Since they are similar to the above methods I'll only show the insert method here. The append and prepend varieties are identical but without the position argument.

To insert a toggle button, use:

Gtk::ToggleButton* insert_toggle_button
(
    const String& text,
    Gtk::Widget *icon,
    Slot0<void> *callback,
    int position,
    const String& tooltip_text = 0,
    const String& tooltip_private_text = 0
);

As you can see the only difference between Gtk::Toolbar::insert_toggle_button() and Gtk::Toolbar::insert_button() are the method names and return values.

To insert a radio button, use:

Gtk::RadioButton* insert_radio_button
(
    const RadioButton *group,
    const String& text,
    Gtk::Widget *icon,
    Slot0<void> *callback,
    int position,
    const String& tooltip_text = 0,
    const String& tooltip_private_text = 0
);

Like regular radio buttons this method takes an extra argument, the group to which the radio button will belong and is specified as a radio button already in the group. On the first call to this method you pass null as the group argument and then pass the returned Gtk::RadioButton pointer to subsequent calls for the same group.

To insert a stock button, use:

Gtk::Button* insert_stock
(
    const char *stock_id,
    Slot0<void> *callback,
    int position,
    const String& tooltip_text = 0,
    const String& tooltip_private_text = 0
);

The stock_id is the stock identifier for the button you want to insert. Stock id's are defined in the GTK header file <gtk/gtkstock.h>.

The following method inserts a space:

void insert_space(int position);

There is one more method that can be used to insert any widget into the toolbar and like the above methods has append and prepend varieties.

void insert_widget(Gtk::Widget& widget, int position, const String& tooltip_text = 0, const String& tooltip_private_text =  0);

If it's required, the orientation of a toolbar and its style can be changed "on the fly" using the following methods:

void set_orientation(Gtk::Orientation orientation);

void set_style(Gtk::ToolbarStyle style);

void set_tooltips(bool enable);

To show some other things that can be done with a toolbar, let's take a look at the following program.

Toolbar Tutorial

The header file for Gtk::Toolbar Example is toolbar.h. Just to be different, the main window class derives from Gtk::Dialog. Also, this example depends on the gtk.xpm file in the "examples/toolbar" directory, so to ensure  it finds it, compile and run the example from a shell.

#include<inti/main.h>
#include <inti/core.h>
#include <inti/gtk/image.h>
#include <inti/gtk/radiobutton.h>
#include <inti/gtk/toolbar.h>

using namespace Inti;

class ToolbarDialog : public Gtk::Dialog
{
    Gtk::Toolbar *toolbar;
    Gtk::ToggleButton *toggle_button;

protected:
    void on_toggle_button();

public:
    ToolbarDialog();
    virtual ~ToolbarDialog();
};

The source file for Gtk::Toolbar Example is toolbar.cc

#include"toolbar.h"
#include <inti/gtk/entry.h>
#include <inti/gtk/handlebox.h>
#include <inti/bind.h>

ToolbarDialog::ToolbarDialog()
{
    set_title("Gtk::Toolbar Tutorial");
    set_size_request(600, 300);
    set_resizable(true);

    // To make it nice we'll put the toolbar into the handle box so it can be detached from the main window.
     Gtk::HandleBox *handlebox = new Gtk::HandleBox;
    client_area()->pack_start(*handlebox, false, false, 5);

    // The toolbar will be horizontal, with both icons and text, and we'll also pack it into our handlebox.
     toolbar = new Gtk::Toolbar(Gtk::ORIENTATION_HORIZONTAL, Gtk::TOOLBAR_BOTH);
    handlebox->add(*toolbar);

    // We need an icon with a mask (one for each button) and an image widget to put the icon in,
    // so we'll create a separate image widget for each button).
     Gtk::Image *image = new Gtk::Image("gtk.xpm");

    // Create our first button, a "close" button. To destroy any widget/window in response to a button click
    // just create a slot using the inherited dispose method and connect it to the button. Here, Gtk::Toolbar
    // does the connection stuff for us, we just supply the slot.
     toolbar->append_button("Close", image, slot(this, &ToolbarDialog::dispose), "Closes this app");

    // Append a space after the close button.
     toolbar->append_space();

    // Now, let's make our radio button group. Note, rather than set up a separate method to change
    // the toolbar style we use "bind" to bind the toolbar style each radio button represents directly
    // to Gtk::Toolbar::set_style() method.
     image = new Gtk::Image("gtk.xpm");
    Gtk::RadioButton *group = toolbar->append_radio_button(0, "Icon", image,
                                                           bind(slot(toolbar, &Gtk::Toolbar::set_style), Gtk::TOOLBAR_ICONS),
                                                           "Only icons in toolbar");
    toolbar->append_space();

    // The following radio buttons refer to previous one as the group
     image = new Gtk::Image("gtk.xpm");
    toolbar->append_radio_button(group, "Text", image,
                                 bind(slot(toolbar, &Gtk::Toolbar::set_style), Gtk::TOOLBAR_TEXT),
                                 "Only texts in toolbar");
    toolbar->append_space();

    image = new Gtk::Image("gtk.xpm");
    group = toolbar->append_radio_button(group, "Both", image,
                                         bind(slot(toolbar, &Gtk::Toolbar::set_style), Gtk::TOOLBAR_BOTH),
                                         "Icons and texts in toolbar");
    group->set_active(true);
    toolbar->append_space();

    // Here we have just a simple toggle button. The on_toggle_button() method just checks
    // the toggle button's active state and enables/disables the tooltips accordingly.
     image = new Gtk::Image("gtk.xpm");
    toggle_button = toolbar->append_toggle_button("Tooltips", image, slot(this, &ToolbarDialog::on_toggle_button),
                                                  "Toolbar with or without tips");
    toolbar->append_space();
    toggle_button->set_active(true);

    // Now we pack a widget into toolbar, we only have to create it and append it with an appropriate tooltip.
     Gtk::Entry *entry = new Gtk::Entry;
    toolbar->append_widget(*entry, "This is just an entry");

    // The Entry isn't created within the toolbar, so we must still show it.
     entry->show();

    // That's it ! let's show everything.
     toolbar->show();
    handlebox->show();
}

ToolbarDialog::~ToolbarDialog()
{
}

void
ToolbarDialog::on_toggle_button()
{
    toolbar->set_tooltips(toggle_button->get_active());
}

int main (int argc, char *argv[])
{
    using namespace Main;

    init(&argc, &argv);

    ToolbarDialog dialog;
    dialog.sig_destroy().connect(slot(&Inti::Main::quit));
    dialog.show();

    run();
    return 0;
}


« Button Boxes Index
Container Widgets
Top 		Notebooks »