GTK+
The GIMP Toolkit
|
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 is (as one may already suspect) done with the
following function: GtkWidget *gtk_toolbar_new( GtkOrientation orientation,
GtkToolbarStyle style ); |
where orientation may be one of: GTK_ORIENTATION_HORIZONTAL
GTK_ORIENTATION_VERTICAL |
and style one of: GTK_TOOLBAR_TEXT
GTK_TOOLBAR_ICONS
GTK_TOOLBAR_BOTH |
The style applies to all the buttons created with the `item' functions
(not to buttons inserted into toolbar as separate widgets). After creating a toolbar one 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
callback function for it. For example, to append or prepend an item
you may use the following functions: GtkWidget *gtk_toolbar_append_item( GtkToolbar *toolbar,
const char *text,
const char *tooltip_text,
const char *tooltip_private_text,
GtkWidget *icon,
GtkSignalFunc callback,
gpointer user_data );
GtkWidget *gtk_toolbar_prepend_item( GtkToolbar *toolbar,
const char *text,
const char *tooltip_text,
const char *tooltip_private_text,
GtkWidget *icon,
GtkSignalFunc callback,
gpointer user_data ); |
If you want to use gtk_toolbar_insert_item, the only additional
parameter which must be specified is the position in which the item
should be inserted, thus: GtkWidget *gtk_toolbar_insert_item( GtkToolbar *toolbar,
const char *text,
const char *tooltip_text,
const char *tooltip_private_text,
GtkWidget *icon,
GtkSignalFunc callback,
gpointer user_data,
gint position ); |
To simplify adding spaces between toolbar items, you may use the
following functions: void gtk_toolbar_append_space( GtkToolbar *toolbar );
void gtk_toolbar_prepend_space( GtkToolbar *toolbar );
void gtk_toolbar_insert_space( GtkToolbar *toolbar,
gint position ); |
While the size of the added space can be set globally for a
whole toolbar with the function: void gtk_toolbar_set_space_size( GtkToolbar *toolbar,
gint space_size) ; |
If it's required, the orientation of a toolbar and its style can be
changed "on the fly" using the following functions: void gtk_toolbar_set_orientation( GtkToolbar *toolbar,
GtkOrientation orientation );
void gtk_toolbar_set_style( GtkToolbar *toolbar,
GtkToolbarStyle style );
void gtk_toolbar_set_tooltips( GtkToolbar *toolbar,
gint enable ); |
Where orientation is one of GTK_ORIENTATION_HORIZONTAL or
GTK_ORIENTATION_VERTICAL. The style is used to set
appearance of the toolbar items by using one of
GTK_TOOLBAR_ICONS, GTK_TOOLBAR_TEXT, or
GTK_TOOLBAR_BOTH. To show some other things that can be done with a toolbar, let's take
the following program (we'll interrupt the listing with some
additional explanations): #include <gtk/gtk.h>
#include "gtk.xpm"
/* This function is connected to the Close button or
* closing the window from the WM */
gint delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
{
gtk_main_quit ();
return(FALSE);
} |
The above beginning seems for sure familiar to you if it's not your first
GTK program. There is one additional thing though, we include a nice XPM
picture to serve as an icon for all of the buttons. GtkWidget* close_button; /* This button will emit signal to close
* application */
GtkWidget* tooltips_button; /* to enable/disable tooltips */
GtkWidget* text_button,
* icon_button,
* both_button; /* radio buttons for toolbar style */
GtkWidget* entry; /* a text entry to show packing any widget into
* toolbar */ |
In fact not all of the above widgets are needed here, but to make things
clearer I put them all together. /* that's easy... when one of the buttons is toggled, we just
* check which one is active and set the style of the toolbar
* accordingly
* ATTENTION: our toolbar is passed as data to callback ! */
void radio_event (GtkWidget *widget, gpointer data)
{
if (GTK_TOGGLE_BUTTON (text_button)->active)
gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_TEXT);
else if (GTK_TOGGLE_BUTTON (icon_button)->active)
gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_ICONS);
else if (GTK_TOGGLE_BUTTON (both_button)->active)
gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_BOTH);
}
/* even easier, just check given toggle button and enable/disable
* tooltips */
void toggle_event (GtkWidget *widget, gpointer data)
{
gtk_toolbar_set_tooltips (GTK_TOOLBAR ( data ),
GTK_TOGGLE_BUTTON (widget)->active );
} |
The above are just two callback functions that will be called when
one of the buttons on a toolbar is pressed. You should already be
familiar with things like this if you've already used toggle buttons (and
radio buttons). int main (int argc, char *argv[])
{
/* Here is our main window (a dialog) and a handle for the handlebox */
GtkWidget* dialog;
GtkWidget* handlebox;
/* Ok, we need a toolbar, an icon with a mask (one for all of
the buttons) and an icon widget to put this icon in (but
we'll create a separate widget for each button) */
GtkWidget * toolbar;
GdkPixmap * icon;
GdkBitmap * mask;
GtkWidget * iconw;
/* this is called in all GTK application. */
gtk_init (&argc, &argv);
/* create a new window with a given title, and nice size */
dialog = gtk_dialog_new ();
gtk_window_set_title ( GTK_WINDOW ( dialog ) , "GTKToolbar Tutorial");
gtk_widget_set_usize( GTK_WIDGET ( dialog ) , 600 , 300 );
GTK_WINDOW ( dialog ) ->allow_shrink = TRUE;
/* typically we quit if someone tries to close us */
gtk_signal_connect ( GTK_OBJECT ( dialog ), "delete_event",
GTK_SIGNAL_FUNC ( delete_event ), NULL);
/* we need to realize the window because we use pixmaps for
* items on the toolbar in the context of it */
gtk_widget_realize ( dialog );
/* to make it nice we'll put the toolbar into the handle box,
* so that it can be detached from the main window */
handlebox = gtk_handle_box_new ();
gtk_box_pack_start ( GTK_BOX ( GTK_DIALOG(dialog)->vbox ),
handlebox, FALSE, FALSE, 5 ); |
The above should be similar to any other GTK application. Just
initialization of GTK, creating the window, etc. There is only one
thing that probably needs some explanation: a handle box. A handle box
is just another box that can be used to pack widgets in to. The
difference between it and typical boxes is that it can be detached
from a parent window (or, in fact, the handle box remains in the
parent, but it is reduced to a very small rectangle, while all of its
contents are reparented to a new freely floating window). It is
usually nice to have a detachable toolbar, so these two widgets occur
together quite often. /* toolbar will be horizontal, with both icons and text, and
* with 5pxl spaces between items and finally,
* we'll also put it into our handlebox */
toolbar = gtk_toolbar_new ( GTK_ORIENTATION_HORIZONTAL,
GTK_TOOLBAR_BOTH );
gtk_container_set_border_width ( GTK_CONTAINER ( toolbar ) , 5 );
gtk_toolbar_set_space_size ( GTK_TOOLBAR ( toolbar ), 5 );
gtk_container_add ( GTK_CONTAINER ( handlebox ) , toolbar );
/* now we create icon with mask: we'll reuse it to create
* icon widgets for toolbar items */
icon = gdk_pixmap_create_from_xpm_d ( dialog->window, &mask,
&dialog->style->white, gtk_xpm ); |
Well, what we do above is just a straightforward initialization of
the toolbar widget and creation of a GDK pixmap with its mask. If you
want to know something more about using pixmaps, refer to GDK
documentation or to the Pixmaps section
earlier in this tutorial. /* our first item is <close> button */
iconw = gtk_pixmap_new ( icon, mask ); /* icon widget */
close_button =
gtk_toolbar_append_item ( GTK_TOOLBAR (toolbar), /* our toolbar */
"Close", /* button label */
"Closes this app", /* this button's tooltip */
"Private", /* tooltip private info */
iconw, /* icon widget */
GTK_SIGNAL_FUNC (delete_event), /* a signal */
NULL );
gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); /* space after item */ |
In the above code you see the simplest case: adding a button to
toolbar. Just before appending a new item, we have to construct a
pixmap widget to serve as an icon for this item; this step will have
to be repeated for each new item. Just after the item we also add a
space, so the following items will not touch each other. As you see
gtk_toolbar_append_item returns a pointer to our newly created button
widget, so that we can work with it in the normal way. /* now, let's make our radio buttons group... */
iconw = gtk_pixmap_new ( icon, mask );
icon_button = gtk_toolbar_append_element(
GTK_TOOLBAR(toolbar),
GTK_TOOLBAR_CHILD_RADIOBUTTON, /* a type of element */
NULL, /* pointer to widget */
"Icon", /* label */
"Only icons in toolbar", /* tooltip */
"Private", /* tooltip private string */
iconw, /* icon */
GTK_SIGNAL_FUNC (radio_event), /* signal */
toolbar); /* data for signal */
gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); |
Here we begin creating a radio buttons group. To do this we use
gtk_toolbar_append_element. In fact, using this function one can also
+add simple items or even spaces (type = GTK_TOOLBAR_CHILD_SPACE
or +GTK_TOOLBAR_CHILD_BUTTON). In the above case we start
creating a radio group. In creating other radio buttons for this group
a pointer to the previous button in the group is required, so that a
list of buttons can be easily constructed (see the section on Radio Buttons earlier in this
tutorial). /* following radio buttons refer to previous ones */
iconw = gtk_pixmap_new ( icon, mask );
text_button =
gtk_toolbar_append_element(GTK_TOOLBAR(toolbar),
GTK_TOOLBAR_CHILD_RADIOBUTTON,
icon_button,
"Text",
"Only texts in toolbar",
"Private",
iconw,
GTK_SIGNAL_FUNC (radio_event),
toolbar);
gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) );
iconw = gtk_pixmap_new ( icon, mask );
both_button =
gtk_toolbar_append_element(GTK_TOOLBAR(toolbar),
GTK_TOOLBAR_CHILD_RADIOBUTTON,
text_button,
"Both",
"Icons and text in toolbar",
"Private",
iconw,
GTK_SIGNAL_FUNC (radio_event),
toolbar);
gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) );
gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(both_button),TRUE); |
In the end we have to set the state of one of the buttons manually
(otherwise they all stay in active state, preventing us from switching
between them). /* here we have just a simple toggle button */
iconw = gtk_pixmap_new ( icon, mask );
tooltips_button =
gtk_toolbar_append_element(GTK_TOOLBAR(toolbar),
GTK_TOOLBAR_CHILD_TOGGLEBUTTON,
NULL,
"Tooltips",
"Toolbar with or without tips",
"Private",
iconw,
GTK_SIGNAL_FUNC (toggle_event),
toolbar);
gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) );
gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(tooltips_button),TRUE); |
A toggle button can be created in the obvious way (if one knows how to create
radio buttons already). /* to pack a widget into toolbar, we only have to
* create it and append it with an appropriate tooltip */
entry = gtk_entry_new ();
gtk_toolbar_append_widget( GTK_TOOLBAR (toolbar),
entry,
"This is just an entry",
"Private" );
/* well, it isn't created within thetoolbar, so we must still show it */
gtk_widget_show ( entry ); |
As you see, adding any kind of widget to a toolbar is simple. The
one thing you have to remember is that this widget must be shown manually
(contrary to other items which will be shown together with the toolbar). /* that's it ! let's show everything. */
gtk_widget_show ( toolbar );
gtk_widget_show (handlebox);
gtk_widget_show ( dialog );
/* rest in gtk_main and wait for the fun to begin! */
gtk_main ();
return 0;
} |
So, here we are at the end of toolbar tutorial. Of course, to appreciate
it in full you need also this nice XPM icon, so here it is: /* XPM */
static char * gtk_xpm[] = {
"32 39 5 1",
". c none",
"+ c black",
"@ c #3070E0",
"# c #F05050",
"$ c #35E035",
"................+...............",
"..............+++++.............",
"............+++++@@++...........",
"..........+++++@@@@@@++.........",
"........++++@@@@@@@@@@++........",
"......++++@@++++++++@@@++.......",
".....+++@@@+++++++++++@@@++.....",
"...+++@@@@+++@@@@@@++++@@@@+....",
"..+++@@@@+++@@@@@@@@+++@@@@@++..",
".++@@@@@@+++@@@@@@@@@@@@@@@@@@++",
".+#+@@@@@@++@@@@+++@@@@@@@@@@@@+",
".+##++@@@@+++@@@+++++@@@@@@@@$@.",
".+###++@@@@+++@@@+++@@@@@++$$$@.",
".+####+++@@@+++++++@@@@@+@$$$$@.",
".+#####+++@@@@+++@@@@++@$$$$$$+.",
".+######++++@@@@@@@++@$$$$$$$$+.",
".+#######+##+@@@@+++$$$$$$@@$$+.",
".+###+++##+##+@@++@$$$$$$++$$$+.",
".+###++++##+##+@@$$$$$$$@+@$$@+.",
".+###++++++#+++@$$@+@$$@++$$$@+.",
".+####+++++++#++$$@+@$$++$$$$+..",
".++####++++++#++$$@+@$++@$$$$+..",
".+#####+++++##++$$++@+++$$$$$+..",
".++####+++##+#++$$+++++@$$$$$+..",
".++####+++####++$$++++++@$$$@+..",
".+#####++#####++$$+++@++++@$@+..",
".+#####++#####++$$++@$$@+++$@@..",
".++####++#####++$$++$$$$$+@$@++.",
".++####++#####++$$++$$$$$$$$+++.",
".+++####+#####++$$++$$$$$$$@+++.",
"..+++#########+@$$+@$$$$$$+++...",
"...+++########+@$$$$$$$$@+++....",
".....+++######+@$$$$$$$+++......",
"......+++#####+@$$$$$@++........",
".......+++####+@$$$$+++.........",
".........++###+$$$@++...........",
"..........++##+$@+++............",
"...........+++++++..............",
".............++++..............."}; |
|