Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Login

Gtk::Toolbar

Description

A toolbar is created with a call to Gtk::Toolbar.new.

A toolbar can contain instances of a subclass of Gtk::ToolItem. To add a Gtk::ToolItem 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 Gtk::ToolButton.

Toolbar items can be visually grouped by adding instances of Gtk::SeparatorToolItem to the toolbar. If a Gtk::SeparatorToolItem has the "expand" property set to TRUE and the "draw" property set to FALSE the effect is to force all following items to the end of the toolbar.

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

Deprecated since 2.4 Usage

Gtk::Toolbar is a bar of buttons and other widgets.

Any of Gtk::ToggleButton, Gtk::RadioButton, or an arbitrary widget can be added to the toolbar with Gtk::Toolbar#append, Gtk::Toolbar#prepend, and Gtk::Toolbar#insert.

Widgets can be visibly grouped by adding gaps between widgets using Gtk::Toolbar#append_space, Gtk::Toolbar#prepend_space, and Gtk::Toolbar#insert_space.

Included Modules

  • #<Module:0x7fd7f0460418>
  • #<Module:0x7fd7f0567618>

Class Methods

Gtk::Toolbar.new
Creates a new toolbar.
  • Returns: the newly-created toolbar.

Instance Methods

insert(position, toolitem)

Inserts a toolitem in the toolbar at the given position.

  • position: the number of widgets to insert this item after.
  • toolitem: a Gtk::ToolItem to add to the toolbar.
  • Returns: the new toolbar item as a Gtk::ToolItem.

Since 2.4

item_index(toolitem)

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

  • toolitem: a Gtk::ToolItem that is a child of the toolbar.
  • Returns: the position of item on the toolbar.

Since 2.4

n_items

Returns the number of items on the toolbar.

  • Returns: the number of items on the toolbar

Since 2.4

nth_item(n)

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

  • n: a position on the toolbar.
  • Returns: The n'th Gtk::ToolItem on toolbar, or nil if there isn't an n'th item.

Since 2.4

drop_index(x, 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: 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

set_drop_highlight_item(tool_item, 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 nil, 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.

  • tool_item: a GtkToolItem, or NULL to turn of highlighting
  • index_: a position on toolbar
  • Returns: self: FIXME (In GTK API, the return is void.)

Since 2.4

show_arrow?

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

  • Returns: true if an arrow should be shown if the toolbar doesn't fit

Since 2.4

show_arrow=(show_arrow)

Sets whether to show an overflow menu when toolbar doesn't have room for all items on it. If TRUE, items that there are not room are available through an overflow menu.

  • show_arrow: true if an arrow should be shown if the toolbar doesn't fit
  • Returns: show_arrow

Since 2.4

set_show_arrow(show_arrow)

Same as show_arrow=.

  • show_arrow: true if an arrow should be shown if the toolbar doesn't fit
  • Returns: self

Since 2.4

orientation
Retrieves the current orientation of the toolbar. See Gtk::Toolbar#orientation=.
  • Returns: the orientation
orientation=(orientation)
Sets whether a toolbar should appear horizontally or vertically.
set_orientation(orientation)
Same as Gtk::Toolbar#orientation=.
icon_size
Retrieves the icon size fo the toolbar. See Gtk::Toolbar#icon_size=.
  • Returns : the current icon size for the icons on the toolbar.
icon_size=(icon_size)
This method 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.
  • icon_size: The GtkIconSize that stock icons in the toolbar shall have.
  • Returns: icon_size
set_icon_size(icon_size)

This method 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.

  • icon_size: The GtkIconSize that stock icons in the toolbar shall have.
  • Returns: self
unset_icon_size
Unsets toolbar icon size set with Gtk::Toolbar#icon_size=, so that user preferences will be used to determine the icon size.
  • Returns: self
icon_size_set?
Gets the value whether the icon-size property has been set or not.
  • Returns: true if the icon-size property has been set
icon_size_set=(icon_size_set)
Sets the value whether the icon-size property has been set or not.
  • icon_size_set: true if the icon-size property has been set
  • Returns: icon_size_set
set_icon_size_set(icon_size_set)
Same as icon_size_set=.
  • icon_size_set: true if the icon-size property has been set
  • Returns: self
toolbar_style
Retrieves whether the toolbar has text, icons, or both . See Gtk::Toolbar#toolbar_style=.
  • Returns : the current style of toolbar
toolbar_style=(style)
Alters the view of toolbar to display either icons only, text only, or both.
set_toolbar_style(style)
Same as Gtk::Toolbar#toolbar_style=.
unset_style
Unsets a toolbar style set with Gtk::Toolbar#toolbar_style=, so that user preferences will be used to determine the toolbar style.
  • Returns: self
relief_style
Returns the relief style of buttons on toolbar. See Gtk::Button#relief=.
  • Returns: The relief style of buttons on toolbar.

Inherited Instance Methods? FIXME

ref_accessible
See Atk::Implementor#ref_accessible.
add_child
See Gtk::Buildable#add_child.
construct_child
See Gtk::Buildable#construct_child.
get_internal_child
See Gtk::Buildable#get_internal_child.
name
See Gtk::Buildable#name.
name=
See Gtk::Buildable#name=.
set_buildable_property
See Gtk::Buildable#set_buildable_property.
set_name
See Gtk::Buildable#set_name.

Best Guess Bad Documentation Methods? FIXME

fill_toolbar
  • Returns: self: FIXME
focus_home_or_end
  • Returns: self: FIXME
setup_toolbar
  • Returns: self: FIXME
builder_name
See Gtk::Buildable#builder_name.
builder_name=
See Gtk::Buildable#builder_name=.
drop_index
  • Returns: self: FIXME
icon_size
Gets the Size of icons in this toolbar.
  • Returns: Size of icons in this toolbar
icon_size=(icon_size)
Sets the Size of icons in this toolbar.
  • icon_size: Size of icons in this toolbar
  • Returns: icon_size
icon_size_set=(icon_size_set)
Sets the value whether the icon-size property has been set or not.
  • icon_size_set: true if the icon-size property has been set
  • Returns: icon_size_set
icon_size_set?
Gets the value whether the icon-size property has been set or not.
  • Returns: true if the icon-size property has been set
item_index
  • Returns: self: FIXME
n_items
  • Returns: self: FIXME
nth_item
  • Returns: self: FIXME
relief_style
  • Returns: self: FIXME
set_builder_name
See Gtk::Buildable#set_builder_name.
set_drop_highlight_item
  • Returns: self: FIXME
set_icon_size(icon_size)
Same as icon_size=.
  • icon_size: Size of icons in this toolbar
  • Returns: self
set_icon_size_set(icon_size_set)
Same as icon_size_set=.
  • icon_size_set: true if the icon-size property has been set
  • Returns: self
set_show_arrow(show_arrow)
Same as show_arrow=.
  • show_arrow: true if an arrow should be shown if the toolbar doesn't fit
  • Returns: self
set_toolbar_style(toolbar_style)
Same as toolbar_style=.
  • toolbar_style: How to draw the toolbar
  • Returns: self
show_arrow=(show_arrow)
Sets the value if an arrow should be shown if the toolbar doesn't fit.
  • show_arrow: true if an arrow should be shown if the toolbar doesn't fit
  • Returns: show_arrow
show_arrow?
Gets the value if an arrow should be shown if the toolbar doesn't fit.
  • Returns: true if an arrow should be shown if the toolbar doesn't fit
toolbar_style
Gets the How to draw the toolbar.
  • Returns: How to draw the toolbar
toolbar_style=(toolbar_style)
Sets the How to draw the toolbar.
  • toolbar_style: How to draw the toolbar
  • Returns: toolbar_style
tooltips=(tooltips)
Sets the value if the tooltips of the toolbar should be active or not.
  • tooltips: true if the tooltips of the toolbar should be active or not
  • Returns: tooltips
tooltips?
Gets the value if the tooltips of the toolbar should be active or not.
  • Returns: true if the tooltips of the toolbar should be active or not
unset_icon_size
  • Returns: self: FIXME
unset_style
  • Returns: self: FIXME

Deprecated Instance Methods

append(text, tooltip_text = nil, tooltip_private_text = nil, icon = nil) { ... }

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

  • 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 : used for context-sensitive help about this toolbar element.
  • icon: a Gtk::Widget that should be used as the button's icon.
  • { ... }: the block to be executed when the button is pressed.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

append(type, widget = nil, text = nil, tooltip_text = nil, tooltip_private_text = nil, icon = nil) { ... }

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 nil.

  • type: a GtkToolbarChildType
  • widget: a Gtk::Widget, or nil.
  • 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 : used for context-sensitive help about this toolbar element.
  • icon: a Gtk::Widget that should be used as the button's icon.
  • { ... }: the block to be executed when the button is pressed.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

append(widget, tooltip_text = nil, tooltip_private_text = nil)

Adds a widget to the end of the given toolbar.

  • widget: a Gtk::Widget to add to the toolbar.
  • tooltip_text: a string that appears when the user holds the mouse over this item.
  • tooltip_private_text : used for context-sensitive help about this toolbar element.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

append(stock_id, tooltip_text = nil, tooltip_private_text = nil){ ... }

Adds a stock item to the end of the given toolbar. If stock_id is not a known stock item ID, it's added verbatim, except that underscores are used to mark mnemonics (see Gtk::Label.new).

  • stock_id: The id of the stock item you want to append. (Gtk::Stock).
  • tooltip_text: a string that appears when the user holds the mouse over this item.
  • tooltip_private_text : used for context-sensitive help about this toolbar element.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

append_space

Adds a new space to the end of the toolbar.

  • Returns: self

Deprecated since 2.4

prepend(text, tooltip_text = nil, tooltip_private_text = nil, icon = nil) { ... }

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

  • 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 : used for context-sensitive help about this toolbar element.
  • icon: a Gtk::Widget that should be used as the button's icon.
  • { ... }: the block to be executed when the button is pressed.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

prepend(type, widget = nil, text = nil, tooltip_text = nil, tooltip_private_text = nil, icon = nil) { ... }

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 nil.

  • type: a GtkToolbarChildType
  • widget: a Gtk::Widget, or nil.
  • 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 : used for context-sensitive help about this toolbar element.
  • icon: a Gtk::Widget that should be used as the button's icon.
  • { ... }: the block to be executed when the button is pressed.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

prepend(widget, tooltip_text = nil, tooltip_private_text = nil)

Adds a widget to the beginning of the given toolbar.

  • widget: a Gtk::Widget to add to the toolbar.
  • tooltip_text: a string that appears when the user holds the mouse over this item.
  • tooltip_private_text : used for context-sensitive help about this toolbar element.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

prepend(stock_id, tooltip_text = nil, tooltip_private_text = nil){ ... }

Adds a stock item to the beginning of the given toolbar. If stock_id is not a known stock item ID, it's added verbatim, except that underscores are used to mark mnemonics (see Gtk::Label.new).

  • stock_id: The id of the stock item you want to prepend. (Gtk::Stock).
  • tooltip_text: a string that appears when the user holds the mouse over this item.
  • tooltip_private_text : used for context-sensitive help about this toolbar element.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

prepend_space

Adds a new space to the beginning of the toolbar.

  • Returns: self

Deprecated since 2.4

insert(position, text, tooltip_text = nil, tooltip_private_text = nil, icon = nil) { ... }

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

  • position: the number of widgets to insert this item after.
  • 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 : used for context-sensitive help about this toolbar element.
  • icon: a Gtk::Widget that should be used as the button's icon.
  • { ... }: the block to be executed when the button is pressed.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

insert(position, type, widget = nil, text = nil, tooltip_text = nil, tooltip_private_text = nil, icon = nil) { ... }

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 nil.

  • position: the number of widgets to insert this item after.
  • type: a GtkToolbarChildType
  • widget: a Gtk::Widget, or nil.
  • 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 : used for context-sensitive help about this toolbar element.
  • icon: a Gtk::Widget that should be used as the button's icon.
  • { ... }: the block to be executed when the button is pressed.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

insert(position, widget, tooltip_text = nil, tooltip_private_text = nil)

Inserts a widget in the toolbar at the given position.

  • position: the number of widgets to insert this item after.
  • widget: a Gtk::Widget to add to the toolbar.
  • tooltip_text: a string that appears when the user holds the mouse over this item.
  • tooltip_private_text : used for context-sensitive help about this toolbar element.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

insert(position, stock_id, tooltip_text = nil, tooltip_private_text = nil){ ... }

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

  • position: the number of widgets to insert this item after.
  • stock_id: The id of the stock item you want to insert. (Gtk::Stock).
  • tooltip_text: a string that appears when the user holds the mouse over this item.
  • tooltip_private_text : used for context-sensitive help about this toolbar element.
  • Returns: the new toolbar item as a Gtk::Widget.

Deprecated since 2.4

insert_space(position)

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

  • position: the number of widgets after which a space should be inserted.
  • Returns: self

Deprecated since 2.4

remove_space(position)

Removes a space from the specified position.

  • position: the index of the space to remove.
  • Returns: self

Deprecated since 2.4

tooltips?

Retrieves whether tooltips are enabled. See Gtk::Toolbar#tooltips=.

  • Returns: true if tooltips are enabled

Deprecated since 2.14 and should not be used in newly-written code. The toolkit-wide Gtk::Settings.properties "gtk-enable-tooltips" property is now used instead.

tooltips=(enable)

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

  • enable: set to false to disable the tooltips, or true to enable them.
  • Returns: enable

Deprecated since 2.14 and should not be used in newly-written code. The toolkit-wide Gtk::Settings.properties "gtk-enable-tooltips" property is now used instead.

set_tooltips(enable)

Same as Gtk::Toolbar#tooltips=.

  • enable: set to false to disable the tooltips, or true to enable them.
  • Returns: self

Deprecated since 2.14 and should not be used in newly-written code. The toolkit-wide Gtk::Settings.properties "gtk-enable-tooltips" property is now used instead.

tooltips
  • Returns: self: FIXME
tooltips
  • Returns: self: FIXME

Constants

GtkToolbarStyle

Used to customize the appearance of a Gtk::Toolbar. Note that setting the toolbar style overrides the user's preferences for the default toolbar style.

Gtk::Toolbar::Style::ICONS
Buttons display only icons in the toolbar.
Gtk::Toolbar::Style::TEXT
Buttons display only text labels in the toolbar.
Gtk::Toolbar::Style::BOTH
Buttons display text and icons in the toolbar.
Gtk::Toolbar::Style::BOTH_HORIZ
Buttons display icons and text alongside each other, rather than vertically stacked

GtkToolbarSpaceStyle

Gtk::Toolbar::SPACE_EMPTY
Gtk::Toolbar::SPACE_LINE
BOTH
BOTH_HORIZ
ICONS
SPACE_EMPTY
SPACE_LINE
TEXT

Deprecated Constants

GtkToolbarChildType

Deprecated since 2.4

GtkToolbarChildType is used to set the type of new elements that are added to a Gtk::Toolbar.

CHILD_SPACE
a space in the style of the toolbar's GtkToolbarSpaceStyle.
CHILD_BUTTON
a Gtk::Button.
CHILD_TOGGLEBUTTON
a Gtk::ToggleButton.
CHILD_RADIOBUTTON
a Gtk::RadioButton.
CHILD_WIDGET
a standard Gtk::Widget.

Properties

icon-size: Gtk::IconSize (Read/Write)

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.

Default value: GTK::IconSize::LARGE_TOOLBAR

Since 2.10

icon-size-set: true or false (Read/Write)

Whether the icon-size property has been set

Default value: false

Since 2.10

orientation: Gtk::Orientation (Read/Write)

The orientation of the toolbar.

Default value: Gtk::ORIENTATION_HORIZONTAL

show-arrow: true or false (Read/Write)

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

Default value: true

toolbar-style: Integer (Read/Write)

How to draw the toolbar

Default value: Gtk::Toolbar::Style::BOTH

tooltips: true or false (Read/Write)

If the tooltips of the toolbar should be active or not

Default value: TRUE

Since 2.8

Style Properties

button-relief: Gtk::ReliefStyle (Read)

Type of bevel around toolbar buttons

Default value: Gtk::RELIEF_NONE

internal-padding: Integer (Read)

Amount of border space between the toolbar shadow and the buttons

Allowed values: >= 0

Default value: 0

max-child-expand: Integer (Read)

Maximum amount of space an expandable item will be given

Allowed values: >= 0

Default value: 2147483647

shadow-type: Gtk::ShadowType (Read)

Style of bevel around the toolbar

Default value: Gtk::SHADOW_OUT

space-size: Integer (Read)

Size of spacers

Allowed values: >= 0

Default value: 12

space-style: Gtk::Toolbar::SpaceStyle (Read)

Whether spacers are vertical lines or just blank

Default value: Gtk::Toolbar::SPACE_LINE

Child Properties

expand: true or false (Read/Write)

Whether the item should receive extra space when the toolbar grows

Default value: false

homogeneous: true or false (Read/Write)

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

Default value: false

Signals

focus-home-or-end: self
A keybinding signal used internally by GTK+. This signal can't be used in application code
  • self: 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
orientation-changed: self, orientation
Should be used if you wish to perform an action when the orientation of a toolbar is changed.
  • self: the object which emitted the signal.
  • orientation: the new Gtk::Orientation of the toolbar.
  • user_data: user data set when the signal handler was connected.
popup-context-menu: self

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.

  • self: the Gtk::Toolbar 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
style-changed: self, style
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.
  • self: the Gtk::Toolbar which emitted the signal.
  • style: the new GtkToolbarStyle of toolbar.
  • user_data: user data set when the signal handler was connected.

See Also

  • Gtk::ToolItem - Base class of widgets that can be added to a toolbar.

ChangeLog

  • 2008-10-03 Added highlighting to "since x.x" and "deprecated x.x" phrases - royw
  • 2008-10-01 Added deprecation information - royw
  • 2005-05-07 Added Child/Style properties. - Masao
  • 2003-05-26 Added - Masao