Xfce Foundation Classes
 « Main Page | Index

Toolbars


Toolbars are containers that hold instances of Gtk::ToolItem. Typically tool items are buttons with icons, labels and tooltips, but any other widget can also be put inside a tool item. Available ToolItems include ToolButton, ToggleToolButton and RadioToolButton.

Toolbar items can be arranged horizontally or vertically and can be displayed with icons, labels, or both. Toolbar items can be visually grouped by adding instances of Gtk::SeparatorToolItem to the toolbar. If a separator tool item has its 'expand' property set to true and its 'draw' property set to false the effect is to force all following items to the end of the toolbar.

You can create a Toolbar with the following constructors:

Toolbar();
 
Toolbar(Gtk::Orientation orientation);

Toolbar(Gtk::Orientation orientation, Gtk::ToolbarStyle style);

The first constructor creates a default horizontal toolbar that will display both icons and text. The second constructor creates a toolbar with the specified orientation that will display both icons and text. The last constructor creates a toolbar with the specified orientation and style.

The 'orientation' argument specifies the whether to toolbar should be horizontal or vertical and can be one of the values from the Gtk::Orientation enum:
  • ORIENTATION_HORIZONTAL
  • ORIENTATION_VERTICAL
The 'style' argument specifies whether the toolbar should display icons, text or both and can be one of the values from the Gtk::ToolbarStyle enum:
  • TOOLBAR_ICONS - buttons display only icons in the toolbar.
  • TOOLBAR_TEXT - buttons display only text labels in the toolbar.
  • TOOLBAR_BOTH - buttons display text and icons in the toolbar.
  • TOOLBAR_BOTH_HORIZ - buttons display icons and text alongside each other, rather than vertically stacked.
After creating a toolbar you can append an items to the end, prepend an items at the start or insert items at a specified position with the following methods:

void append(ToolItem& item, const String& tooltip);
  
void prepend(ToolItem& item, const String& tooltip);
 
void insert(ToolItem& item, int pos, const String& tooltip);

The 'item' argument is the ToolItem to add and 'tooltip' is the text tooltip for that item. The 'pos' argument is the position in the toolbar to insert the tool item.

Separators can be placed between tool items with the following methods:

void append_separator();
  
void insert_separator(int pos);

The 'pos' argument is the position in the toolbar to insert the separator.

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);

You can set the text displayed as the tooltip for a tool item and the private text to be used, if any:

void set_tooltip(ToolItem& item, const String& tip_text, const String& tip_private = 0);

You can set and retrieve the show_arrow property with the following methods:

void set_show_arrow(bool show_arrow);

bool get_show_arrow() const;

If 'show_arrow' is true an overflow menu will be shown when the toolbar doesn't have enough room for all its tool items.

A context menu for the toolbar can be created by connecting to the 'popup-context-menu' signal. This signal in emitted when the user right-clicks inside the toolbar to display a context menu. You can connect to the 'popup-context-menu' signal using its proxy signal function:

const PopupContextMenuSignalProxy signal_popup_context_menu();

Your connected slot function should have the following signature:

bool function(int x, int y, int button);

The 'x' and 'y' arguments are the coordinates of the point where the menu should appear. The 'button' argument is the mouse button the user pressed, or -1. The return value should be true if the signal was handled and false if not.

Toolbar Example

Let's take a look at a simple Toolbar example that shows you how to build a toolbar without using  the Gtk::UIManager interface or stock items. It's an old example that
has been updated to use the new Gtk::TooItem API.

The header file for the Toolbar example is <toolbar.hh>:
 
#include <xfc/main.hh>
#include <xfc/gtk/dialog.hh>
#include <xfc/gtk/radiobutton.hh>
#include <xfc/gtk/toolbar.hh>

using namespace Xfc;

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

protected:
    void on_toggle_button();

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

and the source file is <toolbar.cc>:

#include "toolbar.hh"
#include <xfc/gtk/box.hh>
#include <xfc/gtk/entry.hh>
#include <xfc/gtk/image.hh>
#include <xfc/gtk/handlebox.hh>
#include <xfc/gtk/tooltips.hh>

ToolbarDialog::ToolbarDialog()
{
    set_title("Toolbar Example");
    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 by calling sigc::mem_fun() using the inherited
    // dispose method and connect it to the button.
    Gtk::ToolButton *tool_button = new Gtk::ToolButton(*image, "Close");
    tool_button->signal_clicked().connect(sigc::mem_fun(this, &ToolbarDialog::dispose));    
    toolbar->append(*tool_button, "Closes this app");
    tool_button->show();
           
    // Append a separator after the close button. append_separator() is a convenience method
    // that is equivalent to creating a new Gtk::SeparatorToolItem and adding to the toolbar
    // with a call to Gtk::Toolbar::append().
    toolbar->append_separator();

    // Now, let's make our radio button group. Note, rather than set up a separate method to change
    // the toolbar style we use "sigc::bind" to bind the toolbar style each radio button respresents directly
    // to Gtk::Toolbar::set_style() method.
    image = new Gtk::Image("gtk.xpm");
    Gtk::RadioToolButton *radio_button = 0;   
    radio_button = new Gtk::RadioToolButton(radio_button);
    radio_button->signal_clicked().connect(sigc::bind(sigc::mem_fun(toolbar, &Gtk::Toolbar::set_style), Gtk::TOOLBAR_ICONS));    
    radio_button->set_contents(*image, "Icon");
    toolbar->append(*radio_button, "Only icons in toolbar");
    radio_button->show_all();
   
    // The following radio buttons refer to previous radio button as the group
    image = new Gtk::Image("gtk.xpm");
    radio_button = new Gtk::RadioToolButton(radio_button);
    radio_button->signal_clicked().connect(sigc::bind(sigc::mem_fun(toolbar, &Gtk::Toolbar::set_style), Gtk::TOOLBAR_TEXT));    
    radio_button->set_contents(*image, "Text");
    toolbar->append(*radio_button, "Only texts in toolbar");
    radio_button->show_all();
   
    image = new Gtk::Image("gtk.xpm");
    radio_button = new Gtk::RadioToolButton(radio_button);
    radio_button->signal_clicked().connect(sigc::bind(sigc::mem_fun(toolbar, &Gtk::Toolbar::set_style), Gtk::TOOLBAR_BOTH));    
    radio_button->set_contents(*image, "Both");
    radio_button->set_active(true);
    toolbar->append(*radio_button, "Icons and texts in toolbar");
    radio_button->show_all();
   
    // Append a separator   
    toolbar->append_separator();

    // Here we have just a simple toggle button. The on_toggle_button() method just checks
    // the toggle button's active state and enabless/disables the tooltips accordingly.
    image = new Gtk::Image("gtk.xpm");
    toggle_button = new Gtk::ToggleToolButton;
    toggle_button->signal_clicked().connect(sigc::mem_fun(this, &ToolbarDialog::on_toggle_button));    
    toggle_button->set_contents(*image, "Tooltips");
    toggle_button->set_active(true);
    toolbar->append(*toggle_button, "Toolbar with or without tips");
    toggle_button->show();
       
    toolbar->append_separator();

    // 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;
    Gtk::ToolItem *tool_item = new Gtk::ToolItem(*entry);
    toolbar->append(*tool_item, "Only icons in toolbar");
    tool_item->show();

    // 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.signal_destroy().connect(sigc::ptr_fun(&Xfc::Main::quit));
    dialog.show();

    run();
    return 0;
}

Compiling Toolbar

If you compiled and installed XFC yourself, you will find the source code for Toolbar in the <examples/toolbar> source directory along with a Makefile. If XFC came pre-installed, or you installed it from an RPM package, you will find the source code in the </usr/share/doc/xfcui-X.X/examples/toolbar> subdirectory. In this case you will have to create the Makefile yourself (replace X.X with the version number of the libXFCui library you have installed).

To create a Makefile for Toolbar, add the following lines to a new text file and save it using the name "Makefile":

CC = g++

CFLAGS = -Wall -O2

toolbar: toolbar.cc toolbar.hh
    $(CC) toolbar.cc -o toolbar  $(CFLAGS) `pkg-config xfcui-X.X --cflags --libs`

clean:
    rm -f *.o toolbar

If you cut and paste these lines make sure the whitespace before $(CC) and rm is a tab character. When you compile and run this program you will see the following window appear:



Clicking on a toolbar button will set the corresponding toolbar property and update the toolbar appearance accordingly.

Copyright © 2004-2005 The XFC Development Team Top
 XFC 4.4