GtkToolbar: GTK+ 3 Reference Manual

GtkToolbar

GtkToolbar — Create bars of buttons and other widgets

Functions

GtkWidget *	gtk_toolbar_new ()
void	gtk_toolbar_insert ()
gint	gtk_toolbar_get_item_index ()
gint	gtk_toolbar_get_n_items ()
GtkToolItem *	gtk_toolbar_get_nth_item ()
gint	gtk_toolbar_get_drop_index ()
void	gtk_toolbar_set_drop_highlight_item ()
void	gtk_toolbar_set_show_arrow ()
void	gtk_toolbar_unset_icon_size ()
gboolean	gtk_toolbar_get_show_arrow ()
GtkToolbarStyle	gtk_toolbar_get_style ()
GtkIconSize	gtk_toolbar_get_icon_size ()
GtkReliefStyle	gtk_toolbar_get_relief_style ()
void	gtk_toolbar_set_style ()
void	gtk_toolbar_set_icon_size ()
void	gtk_toolbar_unset_style ()

Properties

GtkIconSize	icon-size	Read / Write
gboolean	icon-size-set	Read / Write
gboolean	show-arrow	Read / Write
GtkToolbarStyle	toolbar-style	Read / Write

Child Properties

gboolean	expand	Read / Write
gboolean	homogeneous	Read / Write

Style Properties

GtkReliefStyle	button-relief	Read
int	internal-padding	Read
int	max-child-expand	Read
GtkShadowType	shadow-type	Read
int	space-size	Read
GtkToolbarSpaceStyle	space-style	Read

Signals

gboolean	focus-home-or-end	Action
void	orientation-changed	Run First
gboolean	popup-context-menu	Run Last
void	style-changed	Run First

Types and Values

struct	GtkToolbar
enum	GtkToolbarSpaceStyle

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkToolbar

Implemented Interfaces

GtkToolbar implements AtkImplementorIface, GtkBuildable, GtkToolShell and GtkOrientable.

Includes

#include <gtk/gtk.h>

Description

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

A toolbar can contain instances of a subclass of GtkToolItem. To add a GtkToolItem to the a toolbar, use gtk_toolbar_insert(). To remove an item from the toolbar use gtk_container_remove(). To add a button to the toolbar, add an instance of GtkToolButton.

Toolbar items can be visually grouped by adding instances of GtkSeparatorToolItem to the toolbar. If the GtkToolbar child property “expand” is TRUE and the property “draw” is set to FALSE, the effect is to force all following items to the end of the toolbar.

By default, a toolbar can be shrunk, upon which it will add an arrow button to show an overflow menu offering access to any GtkToolItem child that has a proxy menu item. To disable this and request enough size for all children, call gtk_toolbar_set_show_arrow() to set “show-arrow” to FALSE.

Creating a context menu for the toolbar can be done by connecting to the “popup-context-menu” signal.

CSS nodes

GtkToolbar has a single CSS node with name toolbar.

Functions

gtk_toolbar_new ()

GtkWidget *
gtk_toolbar_new (void);

Creates a new toolbar.

Returns

the newly-created toolbar.

gtk_toolbar_insert ()

void
gtk_toolbar_insert (GtkToolbar *toolbar,
                    GtkToolItem *item,
                    gint pos);

Insert a GtkToolItem into the toolbar at position pos . If pos is 0 the item is prepended to the start of the toolbar. If pos is negative, the item is appended to the end of the toolbar.

Parameters

toolbar	a GtkToolbar
item	a GtkToolItem
pos	the position of the new item

Since: 2.4

gtk_toolbar_get_item_index ()

gint
gtk_toolbar_get_item_index (GtkToolbar *toolbar,
                            GtkToolItem *item);

Returns the position of item on the toolbar, starting from 0. It is an error if item is not a child of the toolbar.

Parameters

toolbar	a GtkToolbar
item	a GtkToolItem that is a child of `toolbar`

Returns

the position of item on the toolbar.

Since: 2.4

gtk_toolbar_get_n_items ()

gint
gtk_toolbar_get_n_items (GtkToolbar *toolbar);

Returns the number of items on the toolbar.

Parameters

toolbar

a GtkToolbar

Returns

the number of items on the toolbar

Since: 2.4

gtk_toolbar_get_nth_item ()

GtkToolItem *
gtk_toolbar_get_nth_item (GtkToolbar *toolbar,
                          gint n);

Returns the n 'th item on toolbar , or NULL if the toolbar does not contain an n 'th item.

Parameters

toolbar	a GtkToolbar
n	A position on the toolbar

Returns

The n 'th GtkToolItem on toolbar , or NULL if there isn’t an n 'th item.

[nullable][transfer none]

Since: 2.4

gtk_toolbar_get_drop_index ()

gint
gtk_toolbar_get_drop_index (GtkToolbar *toolbar,
                            gint x,
                            gint y);

Returns the position corresponding to the indicated point on toolbar . This is useful when dragging items to the toolbar: this function returns the position a new item should be inserted.

x and y are in toolbar coordinates.

Parameters

toolbar	a GtkToolbar
x	x coordinate of a point on the toolbar
y	y coordinate of a point on the toolbar

Returns

The position corresponding to the point (x , y ) on the toolbar.

Since: 2.4

gtk_toolbar_set_drop_highlight_item ()

void
gtk_toolbar_set_drop_highlight_item (GtkToolbar *toolbar,
                                     GtkToolItem *tool_item,
                                     gint index_);

Highlights toolbar to give an idea of what it would look like if item was added to toolbar at the position indicated by index_ . If item is NULL, highlighting is turned off. In that case index_ is ignored.

The tool_item passed to this function must not be part of any widget hierarchy. When an item is set as drop highlight item it can not added to any widget hierarchy or used as highlight item for another toolbar.

Parameters

toolbar	a GtkToolbar
tool_item	a GtkToolItem, or `NULL` to turn of highlighting.	[allow-none]
index_	a position on `toolbar`

Since: 2.4

gtk_toolbar_set_show_arrow ()

void
gtk_toolbar_set_show_arrow (GtkToolbar *toolbar,
                            gboolean show_arrow);

Sets whether to show an overflow menu when toolbar isn’t allocated enough size to show all of its items. If TRUE, items which can’t fit in toolbar , and which have a proxy menu item set by gtk_tool_item_set_proxy_menu_item() or “create-menu-proxy”, will be available in an overflow menu, which can be opened by an added arrow button. If FALSE, toolbar will request enough size to fit all of its child items without any overflow.

Parameters

toolbar	a GtkToolbar
show_arrow	Whether to show an overflow menu

Since: 2.4

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.

Parameters

toolbar

a GtkToolbar

gtk_toolbar_get_show_arrow ()

gboolean
gtk_toolbar_get_show_arrow (GtkToolbar *toolbar);

Returns whether the toolbar has an overflow menu. See gtk_toolbar_set_show_arrow().

Parameters

toolbar

a GtkToolbar

Returns

TRUE if the toolbar has an overflow menu.

Since: 2.4

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().

Parameters

toolbar

a GtkToolbar

Returns

the current style of toolbar

gtk_toolbar_get_icon_size ()

GtkIconSize
gtk_toolbar_get_icon_size (GtkToolbar *toolbar);

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

Parameters

toolbar

a GtkToolbar

Returns

the current icon size for the icons on the toolbar.

gtk_toolbar_get_relief_style ()

GtkReliefStyle
gtk_toolbar_get_relief_style (GtkToolbar *toolbar);

Returns the relief style of buttons on toolbar . See gtk_button_set_relief().

Parameters

toolbar

a GtkToolbar

Returns

The relief style of buttons on toolbar .

Since: 2.4

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.

Parameters

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

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.

This should only be used for special-purpose toolbars, normal application toolbars should respect the user preferences for the size of icons.

Parameters

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

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.

Parameters

toolbar

a GtkToolbar

Types and Values

struct GtkToolbar

struct GtkToolbar;

enum GtkToolbarSpaceStyle

GtkToolbarSpaceStyle has been deprecated since version 3.20 and should not be used in newly-written code.

Whether spacers are vertical lines or just blank.

Members

GTK_TOOLBAR_SPACE_EMPTY	Use blank spacers.
GTK_TOOLBAR_SPACE_LINE	Use vertical lines for spacers.

Property Details

The `“icon-size”` property

  “icon-size”                GtkIconSize

The size of the icons in a toolbar is normally determined by the toolbar-icon-size setting. When this property is set, it overrides the setting.

This should only be used for special-purpose toolbars, normal application toolbars should respect the user preferences for the size of icons.

Owner: GtkToolbar

Flags: Read / Write

Default value: GTK_ICON_SIZE_LARGE_TOOLBAR

Since: 2.10

The `“icon-size-set”` property

  “icon-size-set”            gboolean

Is TRUE if the icon-size property has been set.

Owner: GtkToolbar

Flags: Read / Write

Default value: FALSE

Since: 2.10

The `“show-arrow”` property

  “show-arrow”               gboolean

If an arrow should be shown if the toolbar doesn't fit.

Owner: GtkToolbar

Flags: Read / Write

Default value: TRUE

The `“toolbar-style”` property

  “toolbar-style”            GtkToolbarStyle

How to draw the toolbar.

Owner: GtkToolbar

Flags: Read / Write

Default value: GTK_TOOLBAR_BOTH_HORIZ

Child Property Details

The `“expand”` child property

  “expand”                   gboolean

Whether the item should receive extra space when the toolbar grows.

Owner: GtkToolbar

Flags: Read / Write

Default value: FALSE

The `“homogeneous”` child property

  “homogeneous”              gboolean

Whether the item should be the same size as other homogeneous items.

Owner: GtkToolbar

Flags: Read / Write

Default value: FALSE

Style Property Details

The `“button-relief”` style property

  “button-relief”            GtkReliefStyle

Type of bevel around toolbar buttons.

Owner: GtkToolbar

Flags: Read

Default value: GTK_RELIEF_NONE

The `“internal-padding”` style property

  “internal-padding”         int

Amount of border space between the toolbar shadow and the buttons.

GtkToolbar:internal-padding has been deprecated since version 3.6 and should not be used in newly-written code.

Use the standard padding CSS property (through objects like GtkStyleContext and GtkCssProvider); the value of this style property is ignored.

Owner: GtkToolbar

Flags: Read

Allowed values: >= 0

Default value: 0

The `“max-child-expand”` style property

  “max-child-expand”         int

Maximum amount of space an expandable item will be given.

Owner: GtkToolbar

Flags: Read

Allowed values: >= 0

Default value: 2147483647

The `“shadow-type”` style property

  “shadow-type”              GtkShadowType

Style of bevel around the toolbar.

GtkToolbar:shadow-type has been deprecated since version 3.6 and should not be used in newly-written code.

Use the standard border CSS property (through objects like GtkStyleContext and GtkCssProvider); the value of this style property is ignored.

Owner: GtkToolbar

Flags: Read

Default value: GTK_SHADOW_OUT

The `“space-size”` style property

  “space-size”               int

Size of toolbar spacers.

GtkToolbar:space-size has been deprecated since version 3.20 and should not be used in newly-written code.

Use the standard margin/padding CSS properties on the separator elements; the value of this style property is ignored.

Owner: GtkToolbar

Flags: Read

Allowed values: >= 0

Default value: 12

The `“space-style”` style property

  “space-style”              GtkToolbarSpaceStyle

Style of toolbar spacers.

GtkToolbar:space-style has been deprecated since version 3.20 and should not be used in newly-written code.

Use CSS properties on the separator elements to style toolbar spacers; the value of this style property is ignored.

Owner: GtkToolbar

Flags: Read

Default value: GTK_TOOLBAR_SPACE_LINE

Signal Details

The `“focus-home-or-end”` signal

gboolean
user_function (GtkToolbar *toolbar,
               gboolean    focus_home,
               gpointer    user_data)

A keybinding signal used internally by GTK+. This signal can't be used in application code

Parameters

toolbar	the GtkToolbar which emitted the signal
focus_home	`TRUE` if the first item should be focused
user_data	user data set when the signal handler was connected.

Returns

TRUE if the signal was handled, FALSE if not

Flags: Action

The `“orientation-changed”` signal

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

Emitted when the orientation of the toolbar changes.

Parameters

toolbar	the object which emitted the signal
orientation	the new GtkOrientation of the toolbar
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“popup-context-menu”` signal

gboolean
user_function (GtkToolbar *toolbar,
               int         x,
               int         y,
               int         button,
               gpointer    user_data)

Emitted when the user right-clicks the toolbar or uses the keybinding to display a popup menu.

Application developers should handle this signal if they want to display a context menu on the toolbar. The context-menu should appear at the coordinates given by x and y . The mouse button number is given by the button parameter. If the menu was popped up using the keybaord, button is -1.

Parameters

toolbar	the GtkToolbar which emitted the signal
x	the x coordinate of the point where the menu should appear
y	the y coordinate of the point where the menu should appear
button	the mouse button the user pressed, or -1
user_data	user data set when the signal handler was connected.

Returns

return TRUE if the signal was handled, FALSE if not

Flags: Run Last

The `“style-changed”` signal

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

Emitted when the style of the toolbar changes.

Parameters

toolbar	The GtkToolbar which emitted the signal
style	the new GtkToolbarStyle of the toolbar
user_data	user data set when the signal handler was connected.

Flags: Run First

GtkToolbar

Functions

Properties

Child Properties

Style Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

CSS nodes

Functions

gtk_toolbar_new ()

Returns

gtk_toolbar_insert ()

Parameters

gtk_toolbar_get_item_index ()

Parameters

Returns

gtk_toolbar_get_n_items ()

Parameters

Returns

gtk_toolbar_get_nth_item ()

Parameters

Returns

gtk_toolbar_get_drop_index ()

Parameters

Returns

gtk_toolbar_set_drop_highlight_item ()

Parameters

gtk_toolbar_set_show_arrow ()

Parameters

gtk_toolbar_unset_icon_size ()

Parameters

gtk_toolbar_get_show_arrow ()

Parameters

Returns

gtk_toolbar_get_style ()

Parameters

Returns

gtk_toolbar_get_icon_size ()

Parameters

Returns

gtk_toolbar_get_relief_style ()

Parameters

Returns

gtk_toolbar_set_style ()

Parameters

gtk_toolbar_set_icon_size ()

Parameters

gtk_toolbar_unset_style ()

Parameters

Types and Values

struct GtkToolbar

enum GtkToolbarSpaceStyle

Members

Property Details

The “icon-size” property

The “icon-size-set” property

The “show-arrow” property

The “toolbar-style” property

Child Property Details

The “expand” child property

The “homogeneous” child property

Style Property Details

The “button-relief” style property

The “internal-padding” style property

The “max-child-expand” style property

The “shadow-type” style property

The “space-size” style property

The “space-style” style property

Signal Details

The “focus-home-or-end” signal

Parameters

Returns

The “orientation-changed” signal

Parameters

The “popup-context-menu” signal

Parameters

The `“icon-size”` property

The `“icon-size-set”` property

The `“show-arrow”` property

The `“toolbar-style”` property

The `“expand”` child property

The `“homogeneous”` child property

The `“button-relief”` style property

The `“internal-padding”` style property

The `“max-child-expand”` style property

The `“shadow-type”` style property

The `“space-size”` style property

The `“space-style”` style property

The `“focus-home-or-end”` signal

The `“orientation-changed”` signal

The `“popup-context-menu”` signal

The `“style-changed”` signal