Next: , Previous: GtkToolbar, Up: Top


66 GtkToolItem

The base class of widgets that can be added to GtkToolbar

66.1 Overview

<gtk-tool-item>s are widgets that can appear on a toolbar. To create a toolbar item that contain something else than a button, use gtk-tool-item-new. Use gtk-container-add to add a child widget to the tool item.

For toolbar items that contain buttons, see the <gtk-tool-button>, <gtk-toggle-tool-button> and <gtk-radio-tool-button> classes.

66.2 Usage

— Class: <gtk-tool-item>

Derives from <gtk-bin>.

This class defines the following slots:

visible-horizontal
Whether the toolbar item is visible when the toolbar is in a horizontal orientation.
visible-vertical
Whether the toolbar item is visible when the toolbar is in a vertical orientation.
is-important
Whether the toolbar item is considered important. When TRUE, toolbar buttons show text in GTK_TOOLBAR_BOTH_HORIZ mode
— Signal on <gtk-tool-item>: create-menu-proxy ⇒ <gboolean>

This signal is emitted when the toolbar needs information from tool-item about whether the item should appear in the toolbar overflow menu. In response the tool item should either

The toolbar may cache the result of this signal. When the tool item changes how it will respond to this signal it must call gtk-tool-item-rebuild-menu to invalidate the cache and ensure that the toolbar rebuilds its overflow menu.

— Signal on <gtk-tool-item>: toolbar-reconfigured

This signal is emitted when some property of the toolbar that the item is a child of changes. For custom subclasses of <gtk-tool-item>, the default handler of this signal use the functions to find out what the toolbar should look like and change themselves accordingly.

— Signal on <gtk-tool-item>: set-tooltip (arg0 <gtk-tooltips>) (arg1 <gchararray>) (arg2 <gchararray>) ⇒ <gboolean>

This signal is emitted when the toolitem's tooltip changes. Application developers can use gtk-tool-item-set-tooltip to set the item's tooltip.

— Function: gtk-tool-item-new ⇒  (ret <gtk-tool-item>)

Creates a new <gtk-tool-item>

ret
the new <gtk-tool-item>

Since 2.4

— Function: gtk-tool-item-set-homogeneous (self <gtk-tool-item>) (homogeneous bool)
— Method: set-homogeneous

Sets whether tool-item is to be allocated the same size as other homogeneous items. The effect is that all homogeneous items will have the same width as the widest of the items.

tool-item
a <gtk-tool-item:>
homogeneous
whether tool-item is the same size as other homogeneous items

Since 2.4

— Function: gtk-tool-item-get-homogeneous (self <gtk-tool-item>) ⇒  (ret bool)
— Method: get-homogeneous

Returns whether tool-item is the same size as other homogeneous items. See gtk-tool-item-set-homogeneous.

tool-item
a <gtk-tool-item:>
ret
#t’ if the item is the same size as other homogeneous item.s

Since 2.4

— Function: gtk-tool-item-set-expand (self <gtk-tool-item>) (expand bool)
— Method: set-expand

Sets whether tool-item is allocated extra space when there is more room on the toolbar then needed for the items. The effect is that the item gets bigger when the toolbar gets bigger and smaller when the toolbar gets smaller.

tool-item
a <gtk-tool-item:>
expand
Whether tool-item is allocated extra space

Since 2.4

— Function: gtk-tool-item-get-expand (self <gtk-tool-item>) ⇒  (ret bool)
— Method: get-expand

Returns whether tool-item is allocated extra space. See gtk-tool-item-set-expand.

tool-item
a <gtk-tool-item:>
ret
#t’ if tool-item is allocated extra space.

Since 2.4

— Function: gtk-tool-item-set-tooltip (self <gtk-tool-item>) (tooltips <gtk-tooltips>) (tip_text mchars) (tip_private mchars)
— Method: set-tooltip

Sets the <gtk-tooltips> object to be used for tool-item, the text to be displayed as tooltip on the item and the private text to be used. See gtk-tooltips-set-tip.

tool-item
a <gtk-tool-item:>
tooltips
The <gtk-tooltips> object to be used
tip-text
text to be used as tooltip text for tool-item
tip-private
text to be used as private tooltip text

Since 2.4

— Function: gtk-tool-item-set-use-drag-window (self <gtk-tool-item>) (use_drag_window bool)
— Method: set-use-drag-window

Sets whether toolitem has a drag window. When ‘#t’ the toolitem can be used as a drag source through gtk-drag-source-set. When toolitem has a drag window it will intercept all events, even those that would otherwise be sent to a child of toolitem.

toolitem
a <gtk-tool-item>
use-drag-window
Whether toolitem has a drag window.

Since 2.4

— Function: gtk-tool-item-get-use-drag-window (self <gtk-tool-item>) ⇒  (ret bool)
— Method: get-use-drag-window

Returns whether toolitem has a drag window. See gtk-tool-item-set-use-drag-window.

toolitem
a <gtk-tool-item>
ret
#t’ if toolitem uses a drag window.

Since 2.4

— Function: gtk-tool-item-set-visible-vertical (self <gtk-tool-item>) (visible_vertical bool)
— Method: set-visible-vertical

Sets whether toolitem is visible when the toolbar is docked vertically. Some tool items, such as text entries, are too wide to be useful on a vertically docked toolbar. If visible-vertical is ‘#ftoolitem will not appear on toolbars that are docked vertically.

toolitem
a <gtk-tool-item>
visible-vertical
whether toolitem is visible when the toolbar is in vertical mode

Since 2.4

— Function: gtk-tool-item-get-visible-vertical (self <gtk-tool-item>) ⇒  (ret bool)
— Method: get-visible-vertical

Returns whether toolitem is visible when the toolbar is docked vertically. See gtk-tool-item-set-visible-vertical.

toolitem
a <gtk-tool-item>
ret
Whether toolitem is visible when the toolbar is docked vertically

Since 2.4

— Function: gtk-tool-item-set-is-important (self <gtk-tool-item>) (is_important bool)
— Method: set-is-important

Sets whether tool-item should be considered important. The <gtk-tool-button> class uses this property to determine whether to show or hide its label when the toolbar style is ‘GTK_TOOLBAR_BOTH_HORIZ’. The result is that only tool buttons with the "is_important" property set have labels, an effect known as "priority text"

tool-item
a <gtk-tool-item>
is-important
whether the tool item should be considered important

Since 2.4

— Function: gtk-tool-item-get-is-important (self <gtk-tool-item>) ⇒  (ret bool)
— Method: get-is-important

Returns whether tool-item is considered important. See gtk-tool-item-set-is-important

tool-item
a <gtk-tool-item>
ret
#t’ if tool-item is considered important.

Since 2.4

— Function: gtk-tool-item-get-icon-size (self <gtk-tool-item>) ⇒  (ret <gtk-icon-size>)
— Method: get-icon-size

Returns the icon size used for tool-item. Custom subclasses of <gtk-tool-item> should call this function to find out what size icons they should use.

tool-item
a <gtk-tool-item:>
ret
a <gtk-icon-size> indicating the icon size used for tool-item

Since 2.4

— Function: gtk-tool-item-get-orientation (self <gtk-tool-item>) ⇒  (ret <gtk-orientation>)
— Method: get-orientation

Returns the orientation used for tool-item. Custom subclasses of <gtk-tool-item> should call this function to find out what size icons they should use.

tool-item
a <gtk-tool-item:>
ret
a <gtk-orientation> indicating the orientation used for tool-item

Since 2.4

— Function: gtk-tool-item-get-toolbar-style (self <gtk-tool-item>) ⇒  (ret <gtk-toolbar-style>)
— Method: get-toolbar-style

Returns the toolbar style used for tool-item. Custom subclasses of <gtk-tool-item> should call this function in the handler of the GtkToolItem::toolbar_reconfigured signal to find out in what style the toolbar is displayed and change themselves accordingly

Possibilities are:

tool-item
a <gtk-tool-item:>
ret
A <gtk-toolbar-style> indicating the toolbar style used for tool-item.

Since 2.4

— Function: gtk-tool-item-get-relief-style (self <gtk-tool-item>) ⇒  (ret <gtk-relief-style>)
— Method: get-relief-style

Returns the relief style of tool-item. See gtk-button-set-relief-style. Custom subclasses of <gtk-tool-item> should call this function in the handler of the <gtk-tool-item::toolbar-reconfigured> signal to find out the relief style of buttons.

tool-item
a <gtk-tool-item:>
ret
a <gtk-relief-style> indicating the relief style used for tool-item.

Since 2.4

— Function: gtk-tool-item-get-proxy-menu-item (self <gtk-tool-item>) (menu_item_id mchars) ⇒  (ret <gtk-widget>)
— Method: get-proxy-menu-item

If menu-item-id matches the string passed to gtk-tool-item-set-proxy-menu-item return the corresponding <gtk-menu-item>.

Custom subclasses of <gtk-tool-item> should use this function to update their menu item when the <gtk-tool-item> changes. That the menu-item-ids must match ensures that a <gtk-tool-item> will not inadvertently change a menu item that they did not create.

tool-item
a <gtk-tool-item:>
menu-item-id
a string used to identify the menu item
ret
The <gtk-menu-item> passed to gtk-tool-item-set-proxy-menu-item, if the menu-item-ids match.

Since 2.4

— Function: gtk-tool-item-set-proxy-menu-item (self <gtk-tool-item>) (menu_item_id mchars) (menu_item <gtk-widget>)
— Method: set-proxy-menu-item

Sets the <gtk-menu-item> used in the toolbar overflow menu. The menu-item-id is used to identify the caller of this function and should also be used with gtk-tool-item-get-proxy-menu-item.

tool-item
a <gtk-tool-item:>
menu-item-id
a string used to identify menu-item
menu-item
a <gtk-menu-item> to be used in the overflow menu

Since 2.4

— Function: gtk-tool-item-rebuild-menu (self <gtk-tool-item>)
— Method: rebuild-menu

Calling this function signals to the toolbar that the overflow menu item for tool-item has changed. If the overflow menu is visible when this function it called, the menu will be rebuilt.

The function must be called when the tool item changes what it will do in response to the "create_menu_proxy" signal.

tool-item
a <gtk-tool-item>

Since 2.6