GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkToolbar

## Name

GtkToolbar -- create bars of buttons and other widgets.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkToolbar;
    enum        GtkToolbarChildType;
    enum        GtkToolbarSpaceStyle;
    struct      GtkToolbarChild;
    GtkWidget*  gtk_toolbar_new                 (void);
    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);
    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);
    void        gtk_toolbar_append_space        (GtkToolbar *toolbar);
    void        gtk_toolbar_prepend_space       (GtkToolbar *toolbar);
    void        gtk_toolbar_insert_space        (GtkToolbar *toolbar,
                                                 gint position);
    GtkWidget*  gtk_toolbar_append_element      (GtkToolbar *toolbar,
                                                 GtkToolbarChildType type,
                                                 GtkWidget *widget,
                                                 const char *text,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkWidget *icon,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data);
    GtkWidget*  gtk_toolbar_prepend_element     (GtkToolbar *toolbar,
                                                 GtkToolbarChildType type,
                                                 GtkWidget *widget,
                                                 const char *text,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkWidget *icon,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data);
    GtkWidget*  gtk_toolbar_insert_element      (GtkToolbar *toolbar,
                                                 GtkToolbarChildType type,
                                                 GtkWidget *widget,
                                                 const char *text,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkWidget *icon,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data,
                                                 gint position);
    void        gtk_toolbar_append_widget       (GtkToolbar *toolbar,
                                                 GtkWidget *widget,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text);
    void        gtk_toolbar_prepend_widget      (GtkToolbar *toolbar,
                                                 GtkWidget *widget,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text);
    void        gtk_toolbar_insert_widget       (GtkToolbar *toolbar,
                                                 GtkWidget *widget,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 gint position);
    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,
                                                 gboolean enable);
    GtkWidget*  gtk_toolbar_insert_stock        (GtkToolbar *toolbar,
                                                 const gchar *stock_id,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data,
                                                 gint position);
    void        gtk_toolbar_set_icon_size       (GtkToolbar *toolbar,
                                                 GtkIconSize icon_size);
    GtkIconSize gtk_toolbar_get_icon_size       (GtkToolbar *toolbar);
    GtkOrientation gtk_toolbar_get_orientation  (GtkToolbar *toolbar);
    GtkToolbarStyle gtk_toolbar_get_style       (GtkToolbar *toolbar);
    gboolean    gtk_toolbar_get_tooltips        (GtkToolbar *toolbar);
    void        gtk_toolbar_remove_space        (GtkToolbar *toolbar,
                                                 gint position);
    void        gtk_toolbar_unset_icon_size     (GtkToolbar *toolbar);
    void        gtk_toolbar_unset_style         (GtkToolbar *toolbar);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkToolbar

## Properties

      "orientation"          GtkOrientation       : Read / Write
      "toolbar-style"        GtkToolbarStyle      : Read / Write

## Style Properties

      "button-relief"        GtkReliefStyle       : Read
      "space-size"           gint                 : Read
      "shadow-type"          GtkShadowType        : Read
      "space-style"          GtkToolbarSpaceStyle : Read
      "internal-padding"     gint                 : Read

## Signal Prototypes

    "orientation-changed"
                void        user_function      (GtkToolbar *toolbar,
                                                GtkOrientation orientation,
                                                gpointer user_data);
    "style-changed"
                void        user_function      (GtkToolbar *toolbar,
                                                GtkToolbarStyle style,
                                                gpointer user_data);

## Description

A toolbar is created with a call to gtk_toolbar_new().

Buttons with text and/or images are added with gtk_toolbar_append_item(), gtk_toolbar_prepend_item(), and gtk_toolbar_insert_item().

Any of GtkToggleButton, GtkRadioButton, or an arbitrary widget can be added to the toolbar with gtk_toolbar_append_element(), gtk_toolbar_prepend_element(), and gtk_toolbar_insert_element().

Widgets can be visibly grouped by adding gaps between widgets using gtk_toolbar_append_space(), gtk_toolbar_prepend_space(), and gtk_toolbar_insert_space().

## Details

### struct GtkToolbar

    struct GtkToolbar;

`num_children` is an integer specifying how many toolbar items the GtkToolbar contains. `children` is a GList of the child widgets of the toolbar.

`orientation`

### enum GtkToolbarChildType

    typedef enum
    {
      GTK_TOOLBAR_CHILD_SPACE,
      GTK_TOOLBAR_CHILD_BUTTON,
      GTK_TOOLBAR_CHILD_TOGGLEBUTTON,
      GTK_TOOLBAR_CHILD_RADIOBUTTON,
      GTK_TOOLBAR_CHILD_WIDGET
    } GtkToolbarChildType;

GtkToolbarChildType is used to set the type of new elements that are added to a GtkToolbar.

`GTK_TOOLBAR_CHILD_SPACE` | a space in the style of the toolbar's GtkToolbarSpaceStyle.
`GTK_TOOLBAR_CHILD_BUTTON` | a GtkButton.
`GTK_TOOLBAR_CHILD_TOGGLEBUTTON` | a GtkToggleButton.
`GTK_TOOLBAR_CHILD_RADIOBUTTON` | a GtkRadioButton.
`GTK_TOOLBAR_CHILD_WIDGET` | a standard GtkWidget.

### enum GtkToolbarSpaceStyle

    typedef enum
    {
      GTK_TOOLBAR_SPACE_EMPTY,
      GTK_TOOLBAR_SPACE_LINE
    } GtkToolbarSpaceStyle;

### struct GtkToolbarChild

    struct GtkToolbarChild
    {
      GtkToolbarChildType type;
      GtkWidget *widget;
      GtkWidget *icon;
      GtkWidget *label;
    };

### gtk_toolbar_new ()

    GtkWidget*  gtk_toolbar_new                 (void);

Creates a new toolbar.

Returns : | the newly-created toolbar.

### gtk_toolbar_append_item ()

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

Adds a new button to the end (right or bottom edges) of the given toolbar.

`toolbar` : | a GtkToolbar.
`text` : | give your toolbar button a label.
`tooltip_text` : | a string that appears when the user holds the mouse over this item.
`tooltip_private_text` : | use with GtkTipsQuery.
`icon` : | a GtkWidget that should be used as the button's icon.
`callback` : | the function to be executed when the button is pressed.
`user_data` : | a pointer to any data you wish to be passed to the callback.
Returns : | the new toolbar item as a GtkWidget.

### gtk_toolbar_prepend_item ()

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

Adds a new button to the beginning (top or left edges) of the given toolbar.

`toolbar` : | a GtkToolbar.
`text` : | give your toolbar button a label.
`tooltip_text` : | a string that appears when the user holds the mouse over this item.
`tooltip_private_text` : | use with GtkTipsQuery.
`icon` : | a GtkWidget that should be used as the button's icon.
`callback` : | the function to be executed when the button is pressed.
`user_data` : | a pointer to any data you wish to be passed to the callback.
Returns : | the new toolbar item as a GtkWidget.

### gtk_toolbar_insert_item ()

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

Inserts a new item into the toolbar. You must specify the position in the toolbar where it will be inserted.

`toolbar` : | a GtkToolbar.
`text` : | give your toolbar button a label.
`tooltip_text` : | a string that appears when the user holds the mouse over this item.
`tooltip_private_text` : | use with GtkTipsQuery.
`icon` : | a GtkWidget that should be used as the button's icon.
`callback` : | the function to be executed when the button is pressed.
`user_data` : | a pointer to any data you wish to be passed to the callback.
`position` : | the number of widgets to insert this item after.
Returns : | the new toolbar item as a GtkWidget.

### gtk_toolbar_append_space ()

    void        gtk_toolbar_append_space        (GtkToolbar *toolbar);

Adds a new space to the end of the toolbar.

`toolbar` : | a GtkToolbar.

### gtk_toolbar_prepend_space ()

    void        gtk_toolbar_prepend_space       (GtkToolbar *toolbar);

Adds a new space to the beginning of the toolbar.

`toolbar` : | a GtkToolbar.

### gtk_toolbar_insert_space ()

    void        gtk_toolbar_insert_space        (GtkToolbar *toolbar,
                                                 gint position);

Inserts a new space in the toolbar at the specified position.

`toolbar` : | a GtkToolbar
`position` : | the number of widgets after which a space should be inserted.

### gtk_toolbar_append_element ()

    GtkWidget*  gtk_toolbar_append_element      (GtkToolbar *toolbar,
                                                 GtkToolbarChildType type,
                                                 GtkWidget *widget,
                                                 const char *text,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkWidget *icon,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data);

Adds a new element to the end of a toolbar.

If `type` == `GTK_TOOLBAR_CHILD_WIDGET`, `widget` is used as the new element. If `type` == `GTK_TOOLBAR_CHILD_RADIOBUTTON`, `widget` is used to determine the radio group for the new element. In all other cases, `widget` must be `NULL`.

`toolbar` : | a GtkToolbar.
`type` : | a value of type GtkToolbarChildType that determines what `widget` will be.
`widget` : | a GtkWidget, or `NULL`.
`text` : | the element's label.
`tooltip_text` : | the element's tooltip.
`tooltip_private_text` : | used for context-sensitive help about this toolbar element.
`icon` : | a GtkWidget that provides pictorial representation of the element's function.
`callback` : | the function to be executed when the button is pressed.
`user_data` : | any data you wish to pass to the callback.
Returns : | the new toolbar element as a GtkWidget.

### gtk_toolbar_prepend_element ()

    GtkWidget*  gtk_toolbar_prepend_element     (GtkToolbar *toolbar,
                                                 GtkToolbarChildType type,
                                                 GtkWidget *widget,
                                                 const char *text,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkWidget *icon,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data);

Adds a new element to the beginning of a toolbar.

If `type` == `GTK_TOOLBAR_CHILD_WIDGET`, `widget` is used as the new element. If `type` == `GTK_TOOLBAR_CHILD_RADIOBUTTON`, `widget` is used to determine the radio group for the new element. In all other cases, `widget` must be `NULL`.

`toolbar` : | a GtkToolbar.
`type` : | a value of type GtkToolbarChildType that determines what `widget` will be.
`widget` : | a GtkWidget, or `NULL`
`text` : | the element's label.
`tooltip_text` : | the element's tooltip.
`tooltip_private_text` : | used for context-sensitive help about this toolbar element.
`icon` : | a GtkWidget that provides pictorial representation of the element's function.
`callback` : | the function to be executed when the button is pressed.
`user_data` : | any data you wish to pass to the callback.
Returns : | the new toolbar element as a GtkWidget.

### gtk_toolbar_insert_element ()

    GtkWidget*  gtk_toolbar_insert_element      (GtkToolbar *toolbar,
                                                 GtkToolbarChildType type,
                                                 GtkWidget *widget,
                                                 const char *text,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkWidget *icon,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data,
                                                 gint position);

Inserts a new element in the toolbar at the given position.

If `type` == `GTK_TOOLBAR_CHILD_WIDGET`, `widget` is used as the new element. If `type` == `GTK_TOOLBAR_CHILD_RADIOBUTTON`, `widget` is used to determine the radio group for the new element. In all other cases, `widget` must be `NULL`.

`toolbar` : | a GtkToolbar.
`type` : | a value of type GtkToolbarChildType that determines what `widget` will be.
`widget` : | a GtkWidget, or `NULL`.
`text` : | the element's label.
`tooltip_text` : | the element's tooltip.
`tooltip_private_text` : | used for context-sensitive help about this toolbar element.
`icon` : | a GtkWidget that provides pictorial representation of the element's function.
`callback` : | the function to be executed when the button is pressed.
`user_data` : | any data you wish to pass to the callback.
`position` : | the number of widgets to insert this element after.
Returns : | the new toolbar element as a GtkWidget.

### gtk_toolbar_append_widget ()

    void        gtk_toolbar_append_widget       (GtkToolbar *toolbar,
                                                 GtkWidget *widget,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text);

Adds a widget to the end of the given toolbar.

`toolbar` : | a GtkToolbar.
`widget` : | a GtkWidget to add to the toolbar.
`tooltip_text` : | the element's tooltip.
`tooltip_private_text` : | used for context-sensitive help about this toolbar element.

### gtk_toolbar_prepend_widget ()

    void        gtk_toolbar_prepend_widget      (GtkToolbar *toolbar,
                                                 GtkWidget *widget,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text);

Adds a widget to the beginning of the given toolbar.

`toolbar` : | a GtkToolbar.
`widget` : | a GtkWidget to add to the toolbar.
`tooltip_text` : | the element's tooltip.
`tooltip_private_text` : | used for context-sensitive help about this toolbar element.

### gtk_toolbar_insert_widget ()

    void        gtk_toolbar_insert_widget       (GtkToolbar *toolbar,
                                                 GtkWidget *widget,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 gint position);

Inserts a widget in the toolbar at the given position.

`toolbar` : | a GtkToolbar.
`widget` : | a GtkWidget to add to the toolbar.
`tooltip_text` : | the element's tooltip.
`tooltip_private_text` : | used for context-sensitive help about this toolbar element.
`position` : | the number of widgets to insert this widget after.

### gtk_toolbar_set_orientation ()

    void        gtk_toolbar_set_orientation     (GtkToolbar *toolbar,
                                                 GtkOrientation orientation);

Sets whether a toolbar should appear horizontally or vertically.

`toolbar` : | a GtkToolbar.
`orientation` : | a new GtkOrientation.

### gtk_toolbar_set_style ()

    void        gtk_toolbar_set_style           (GtkToolbar *toolbar,
                                                 GtkToolbarStyle style);

Alters the view of `toolbar` to display either icons only, text only, or both.

`toolbar` : | a GtkToolbar.
`style` : | the new style for `toolbar`.

### gtk_toolbar_set_tooltips ()

    void        gtk_toolbar_set_tooltips        (GtkToolbar *toolbar,
                                                 gboolean enable);

Sets if the tooltips of a toolbar should be active or not.

`toolbar` : | a GtkToolbar.
`enable` : | set to `FALSE` to disable the tooltips, or `TRUE` to enable them.

### gtk_toolbar_insert_stock ()

    GtkWidget*  gtk_toolbar_insert_stock        (GtkToolbar *toolbar,
                                                 const gchar *stock_id,
                                                 const char *tooltip_text,
                                                 const char *tooltip_private_text,
                                                 GtkSignalFunc callback,
                                                 gpointer user_data,
                                                 gint position);

Inserts a stock item at the specified position of the toolbar. If `stock_id` is not a known stock item ID, it's inserted verbatim, except that underscores are used to mark mnemonics (see gtk_label_new_with_mnemonic()).

`toolbar` : | A GtkToolbar
`stock_id` : | The id of the stock item you want to insert
`tooltip_text` : | The text in the tooltip of the toolbar button
`tooltip_private_text` : | The private text of the tooltip
`callback` : | The callback called when the toolbar button is clicked.
`user_data` : | user data passed to callback
`position` : | The position the button shall be inserted at. -1 means at the end.
Returns : | the inserted widget

### gtk_toolbar_set_icon_size ()

    void        gtk_toolbar_set_icon_size       (GtkToolbar *toolbar,
                                                 GtkIconSize icon_size);

This function sets the size of stock icons in the toolbar. You can call it both before you add the icons and after they've been added. The size you set will override user preferences for the default icon size.

`toolbar` : | A GtkToolbar
`icon_size` : | The GtkIconSize that stock icons in the toolbar shall have.

### gtk_toolbar_get_icon_size ()

    GtkIconSize gtk_toolbar_get_icon_size       (GtkToolbar *toolbar);

Retrieves the icon size fo the toolbar. See gtk_toolbar_set_icon_size().

`toolbar` : | a GtkToolbar
Returns : | the current icon size for the icons on the toolbar.

### gtk_toolbar_get_orientation ()

    GtkOrientation gtk_toolbar_get_orientation  (GtkToolbar *toolbar);

Retrieves the current orientation of the toolbar. See gtk_toolbar_set_orientation().

`toolbar` : | a GtkToolbar
Returns : | the orientation

### gtk_toolbar_get_style ()

    GtkToolbarStyle gtk_toolbar_get_style       (GtkToolbar *toolbar);

Retrieves whether the toolbar has text, icons, or both . See gtk_toolbar_set_style().

`toolbar` : | a GtkToolbar
Returns : | the current style of `toolbar`

### gtk_toolbar_get_tooltips ()

    gboolean    gtk_toolbar_get_tooltips        (GtkToolbar *toolbar);

Retrieves whether tooltips are enabled. See gtk_toolbar_set_tooltips().

`toolbar` : | a GtkToolbar
Returns : | `TRUE` if tooltips are enabled

### gtk_toolbar_remove_space ()

    void        gtk_toolbar_remove_space        (GtkToolbar *toolbar,
                                                 gint position);

Removes a space from the specified position.

`toolbar` : | a GtkToolbar.
`position` : | the index of the space to remove.

### gtk_toolbar_unset_icon_size ()

    void        gtk_toolbar_unset_icon_size     (GtkToolbar *toolbar);

Unsets toolbar icon size set with gtk_toolbar_set_icon_size(), so that user preferences will be used to determine the icon size.

`toolbar` : | a GtkToolbar

### gtk_toolbar_unset_style ()

    void        gtk_toolbar_unset_style         (GtkToolbar *toolbar);

Unsets a toolbar style set with gtk_toolbar_set_style(), so that user preferences will be used to determine the toolbar style.

`toolbar` : | a GtkToolbar

## Properties

"`orientation`" (GtkOrientation : Read / Write)

  The orientation of the toolbar

"`toolbar-style`" (GtkToolbarStyle : Read / Write)

  How to draw the toolbar

## Style Properties

"`button-relief`" (GtkReliefStyle : Read)

  Type of bevel around toolbar buttons

"`space-size`" (gint : Read)

  Size of spacers

"`shadow-type`" (GtkShadowType : Read)

  Style of bevel around the toolbar

"`space-style`" (GtkToolbarSpaceStyle : Read)

  Whether spacers are vertical lines or just blank

"`internal-padding`" (gint : Read)

  Amount of border space between the toolbar shadow and the buttons

## Signals

### The "orientation-changed" signal

    void        user_function                  (GtkToolbar *toolbar,
                                                GtkOrientation orientation,
                                                gpointer user_data);

Should be used if you wish to perform an action when the orientation of a toolbar is changed.

`toolbar` : | the object which received the signal.
`orientation` : | the new GtkOrientation of the toolbar.
`user_data` : | user data set when the signal handler was connected.

### The "style-changed" signal

    void        user_function                  (GtkToolbar *toolbar,
                                                GtkToolbarStyle style,
                                                gpointer user_data);

Should be used if you wish to perform an action when ever the style of a toolbar is adjusted. For example, this would be a useful signal to connect to if you want to display more items on the toolbar when it is in icon-only mode; each item takes less space on the bar.

`toolbar` : | the object which received the signal.
`style` : | the new GtkToolbarStyle of `toolbar`.
`user_data` : | user data set when the signal handler was connected.

## See Also

GtkToolTips

  Change the properties of a GtkToolbar's GtkTooltips.

GtkTipsQuery

  Make use of the private tips of toolbar elements.

<<< Previous Page | Home | Up | Next Page >>>
GtkTearoffMenuItem | Selectors (File/Font/Color/Input Devices)