gtk_tut-10.html

GTK development guide

  gtk_container_set_border_width (GTK_CONTAINER (window), 10);

  main_vbox = gtk_vbox_new (FALSE, 0);
  gtk_container_add (GTK_CONTAINER (window), main_vbox);

  frame_horz = gtk_frame_new ("Horizontal Button Boxes");
  gtk_box_pack_start (GTK_BOX (main_vbox), frame_horz, TRUE, TRUE, 10);

  vbox = gtk_vbox_new (FALSE, 0);
  gtk_container_set_border_width (GTK_CONTAINER (vbox), 10);
  gtk_container_add (GTK_CONTAINER (frame_horz), vbox);

  gtk_box_pack_start (GTK_BOX (vbox),
           create_bbox (TRUE, "Spread (spacing 40)", 40, 85, 20, GTK_BUTTONBOX_SPREAD),
                      TRUE, TRUE, 0);

  gtk_box_pack_start (GTK_BOX (vbox),
           create_bbox (TRUE, "Edge (spacing 30)", 30, 85, 20, GTK_BUTTONBOX_EDGE),
                      TRUE, TRUE, 5);

  gtk_box_pack_start (GTK_BOX (vbox),
           create_bbox (TRUE, "Start (spacing 20)", 20, 85, 20, GTK_BUTTONBOX_START),
                      TRUE, TRUE, 5);

  gtk_box_pack_start (GTK_BOX (vbox),
           create_bbox (TRUE, "End (spacing 10)", 10, 85, 20, GTK_BUTTONBOX_END),
                      TRUE, TRUE, 5);

  frame_vert = gtk_frame_new ("Vertical Button Boxes");
  gtk_box_pack_start (GTK_BOX (main_vbox), frame_vert, TRUE, TRUE, 10);

  hbox = gtk_hbox_new (FALSE, 0);
  gtk_container_set_border_width (GTK_CONTAINER (hbox), 10);
  gtk_container_add (GTK_CONTAINER (frame_vert), hbox);

  gtk_box_pack_start (GTK_BOX (hbox),
           create_bbox (FALSE, "Spread (spacing 5)", 5, 85, 20, GTK_BUTTONBOX_SPREAD),
                      TRUE, TRUE, 0);

  gtk_box_pack_start (GTK_BOX (hbox),
           create_bbox (FALSE, "Edge (spacing 30)", 30, 85, 20, GTK_BUTTONBOX_EDGE),
                      TRUE, TRUE, 5);

  gtk_box_pack_start (GTK_BOX (hbox),
           create_bbox (FALSE, "Start (spacing 20)", 20, 85, 20, GTK_BUTTONBOX_START),
                      TRUE, TRUE, 5);

  gtk_box_pack_start (GTK_BOX (hbox),
           create_bbox (FALSE, "End (spacing 20)", 20, 85, 20, GTK_BUTTONBOX_END),
                      TRUE, TRUE, 5);

  gtk_widget_show_all (window);

  /* Enter the event loop */
  gtk_main ();
    
  return(0);
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>   
<H2><A NAME="ss10.11">10.11 Toolbar</A>
</H2>

<P>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.
<P>Creating a toolbar is (as one may already suspect) done with the
following function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_toolbar_new( GtkOrientation orientation,
                            GtkToolbarStyle  style );
</PRE>
</CODE></BLOCKQUOTE>
<P>where orientation may be one of:
<P>
<BLOCKQUOTE><CODE>
<PRE>
  GTK_ORIENTATION_HORIZONTAL    
  GTK_ORIENTATION_VERTICAL
</PRE>
</CODE></BLOCKQUOTE>
<P>and style one of:
<P>
<BLOCKQUOTE><CODE>
<PRE>
  GTK_TOOLBAR_TEXT
  GTK_TOOLBAR_ICONS
  GTK_TOOLBAR_BOTH
</PRE>
</CODE></BLOCKQUOTE>
<P>The style applies to all the buttons created with the `item' functions
(not to buttons inserted into toolbar as separate widgets).
<P>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:
<P>
<BLOCKQUOTE><CODE>
<PRE>
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 );
</PRE>
</CODE></BLOCKQUOTE>
<P>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:
<P>
<BLOCKQUOTE><CODE>
<PRE>
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 );
</PRE>
</CODE></BLOCKQUOTE>
<P>To simplify adding spaces between toolbar items, you may use the
following functions:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_toolbar_append_space( GtkToolbar *toolbar );

void gtk_toolbar_prepend_space( GtkToolbar *toolbar );

void gtk_toolbar_insert_space( GtkToolbar *toolbar,
                               gint        position );
 
</PRE>
</CODE></BLOCKQUOTE>
<P>While the size of the added space can be set globally for a
whole toolbar with the function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_toolbar_set_space_size( GtkToolbar *toolbar,
                                 gint        space_size) ;
</PRE>
</CODE></BLOCKQUOTE>
<P>If it's required, the orientation of a toolbar and its style can be
changed "on the fly" using the following functions:
<P>
<BLOCKQUOTE><CODE>
<PRE>
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 );
</PRE>
</CODE></BLOCKQUOTE>
<P>Where <CODE>orientation</CODE> is one of <CODE>GTK_ORIENTATION_HORIZONTAL</CODE> or
<CODE>GTK_ORIENTATION_VERTICAL</CODE>. The <CODE>style</CODE> is used to set
appearance of the toolbar items by using one of
<CODE>GTK_TOOLBAR_ICONS</CODE>, <CODE>GTK_TOOLBAR_TEXT</CODE>, or
<CODE>GTK_TOOLBAR_BOTH</CODE>.
<P>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):
<P>
<BLOCKQUOTE><CODE>
<PRE>
#include &lt;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);
}
</PRE>
</CODE></BLOCKQUOTE>
<P>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.
<P>
<BLOCKQUOTE><CODE>
<PRE>
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 */
</PRE>
</CODE></BLOCKQUOTE>
<P>In fact not all of the above widgets are needed here, but to make things
clearer I put them all together.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* 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 );
}
</PRE>
</CODE></BLOCKQUOTE>
<P>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).
<P>
<BLOCKQUOTE><CODE>
<PRE>
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 (&amp;argc, &amp;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 );
</PRE>
</CODE></BLOCKQUOTE>
<P>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.
<P>
<BLOCKQUOTE><CODE>
<PRE>
  /* 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, &amp;mask,
      &amp;dialog->style->white, gtk_xpm );
</PRE>
</CODE></BLOCKQUOTE>
<P>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 
<A HREF="gtk_tut-9.html#sec_Pixmaps">Pixmaps</A> section
earlier in this tutorial.
<P>
<BLOCKQUOTE><CODE>
<PRE>
  /* our first item is &lt;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 */
</PRE>
</CODE></BLOCKQUOTE>
<P>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.
<P>
<BLOCKQUOTE><CODE>
<PRE>
  /* 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 ) );
</PRE>