gtk.ToolItem
Prev | The gtk Class Reference | Next

## gtk.ToolItem

gtk.ToolItem — the base class of widgets that can be added to `gtk.Toolbar` (new in PyGTK 2.4)

## Synopsis

    class gtk.ToolItem(gtk.Bin):
        gtk.ToolItem()
        def set_homogeneous(homogeneous)
        def get_homogeneous()
        def set_expand(expand)
        def get_expand()
        def set_tooltip(tooltips, tip_text=None, tip_private=None)
        def set_use_drag_window(use_drag_window)
        def get_use_drag_window()
        def set_visible_horizontal(visible_horizontal)
        def get_visible_horizontal()
        def set_visible_vertical(visible_vertical)
        def get_visible_vertical()
        def set_is_important(is_important)
        def get_is_important()
        def get_icon_size()
        def get_orientation()
        def get_toolbar_style()
        def get_relief_style()
        def retrieve_proxy_menu_item()
        def set_proxy_menu_item(menu_item_id, menu_item)
        def get_proxy_menu_item(menu_item_id)
        def rebuild_menu()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.ToolItem

## gtk.ToolItem Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

### Note

These properties are available in GTK+ 2.4 and above.

"is-important" | Read-Write | If `True`, the toolbar item is considered important and the toolbar buttons show text in `gtk.TOOLBAR_BOTH_HORIZ` mode. Default value: `False`
"visible-horizontal" | Read-Write | If `True`, the toolbar item is visible when the toolbar is in a horizontal orientation. Default value: `True`
"visible-vertical" | Read-Write | If `True`, the toolbar item is visible when the toolbar is in a vertical orientation. Default value: `True`

## gtk.ToolItem Style Properties

gtk.Widget Style Properties

## gtk.ToolItem Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"create-menu-proxy" | `def callback(`toolitem`, `user_param1`, `...`)`
"set-tooltip" | `def callback(`toolitem`, `tooltips`, `tip_text`, `tip_private`, `user_param1`, `...`)`
"toolbar-reconfigured" | `def callback(`toolitem`, `user_param1`, `...`)`

## Description

### Note

This widget is available in PyGTK 2.4 and above.

A `gtk.ToolItem` is a widget that can appear on a `gtk.Toolbar`. To create a toolbar item that contains something else than a button, use the gtk.ToolItem() constructor then use the `gtk.Container.add`() method to add a child widget to the tool item.

To create and use toolbar items that contain buttons, see the `gtk.ToolButton`, `gtk.ToggleToolButton` and `gtk.RadioToolButton` classes. See the `gtk.Toolbar` class for a description of the toolbar widget.

## Constructor

        gtk.ToolItem()

Returns : | the new `gtk.ToolItem`

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new empty `gtk.ToolItem`

## Methods

### gtk.ToolItem.set_homogeneous

        def set_homogeneous(homogeneous)

`homogeneous` : | if `True` the tool item is the same size as other homogeneous items

### Note

This method is available in PyGTK 2.4 and above.

The `set_homogeneous`() method sets the homogeneous setting of the tool item to the value of `homogeneous`. If `homogeneous` is `True` the 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.

### gtk.ToolItem.get_homogeneous

        def get_homogeneous()

Returns : | `True` if the item is the same size as other homogeneous items.

### Note

This method is available in PyGTK 2.4 and above.

The `get_homogeneous`() method returns the setting of the homogeneous setting of the tool item. If `True` the tool item is the same size as other homogeneous items. See the `set_homogeneous()` method for more detail.

### gtk.ToolItem.set_expand

        def set_expand(expand)

`expand` : | If `True` the tool item is allocated extra space when available

### Note

This method is available in PyGTK 2.4 and above.

The `set_expand`() method sets the expand setting of the tool item to the value of `expand`. If `expand` is `True` the tool item is allocated extra space when there is more room on the toolbar than needed for the items. The effect is that the item gets bigger when the toolbar gets bigger and smaller when the toolbar gets smaller.

### gtk.ToolItem.get_expand

        def get_expand()

Returns : | `True` if the tool item is allocated extra space when available.

### Note

This method is available in PyGTK 2.4 and above.

The `get_expand`() method returns the value of the expand setting of the tool item. If `True` the tool item is allocated extra space. See the `gtk.ToolItem.set_expand()` method for more detail.

### gtk.ToolItem.set_tooltip

        def set_tooltip(tooltips, tip_text=None, tip_private=None)

`tooltips` : | The `gtk.Tooltips` object to be used
`tip_text` : | the text to be used as tooltip text for the tool item or `None`
`tip_private` : | the text to be used as private tooltip text or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_tooltip`() method sets the `gtk.Tooltips` object specified by `tooltips` to be used for the tool item with the tooltip text specified by `tip_text` and the private text specified by `tip_private`. See the `gtk.Tooltips.set_tip()` method for more information.

### gtk.ToolItem.set_use_drag_window

        def set_use_drag_window(use_drag_window)

`use_drag_window` : | if `True` the tool item has a drag window.

### Note

This method is available in PyGTK 2.4 and above.

The `set_use_drag_window`() method determines whether the tool item has a drag window according to the value of `use_drag_window`. If `use_drag_window` is `True` the toolitem can be used as a drag source through the `gtk.Widget.drag_source_set()` method. When the tool item has a drag window it will intercept all events, even those that would otherwise be sent to a child of the tool item

### gtk.ToolItem.get_use_drag_window

        def get_use_drag_window()

Returns : | `True` if the tool item uses a drag window.

### Note

This method is available in PyGTK 2.4 and above.

The `get_use_drag_window`() returns the setting that determines if the tool item has a drag window. See the `set_use_drag_window()` for more information.

### gtk.ToolItem.set_visible_horizontal

        def set_visible_horizontal(visible_horizontal)

`visible_horizontal` : | if `True` the tool item is visible when in horizontal mode

### Note

This method is available in PyGTK 2.4 and above.

The `set_visible_horizontal`() method sets the "visible-horizontal" property to the value of `visible_horizontal`. If `visible_horizontal` is `True`, the tool item is visible when the toolbar is docked horizontally.

### gtk.ToolItem.get_visible_horizontal

        def get_visible_horizontal()

Returns : | `True` if the tool item is visible on toolbars that are docked horizontally.

### Note

This method is available in PyGTK 2.4 and above.

The `get_visible_horizontal`() method returns the value of the "visible-horizontal" property. If "visible-horizontal" is `True`, the tool item is visible on toolbars that are docked horizontally.

### gtk.ToolItem.set_visible_vertical

        def set_visible_vertical(visible_vertical)

`visible_vertical` : | if `True`, the tool item is visible when the toolbar is in vertical mode

### Note

This method is available in PyGTK 2.4 and above.

The `set_visible_vertical`() method sets the "visible-vertical" property to the value of `visible_vertical`. If `visible_vertical` is `True`, the tool item 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 `False` the tool item will not appear on toolbars that are docked vertically.

### gtk.ToolItem.get_visible_vertical

        def get_visible_vertical()

Returns : | True if the tool item is visible when the toolbar is docked vertically

### Note

This method is available in PyGTK 2.4 and above.

The `get_visible_vertical`() method returns the value of the "visible-vertical" property. If "visible-vertical" is `True`, the tool item is visible when the toolbar is docked vertically. See the `set_visible_vertical()` method for more information.

### gtk.ToolItem.set_is_important

        def set_is_important(is_important)

`is_important` : | if `True`, the tool item should be considered important

### Note

This method is available in PyGTK 2.4 and above.

The `set_is_important`() method sets the "is-important" property to the value of `is_important`. If `is_important` is `True` the tool item should be considered important. The `gtk.ToolButton` class uses this property to determine whether to show 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".

### gtk.ToolItem.get_is_important

        def get_is_important()

Returns : | `True` if the tool item is considered important.

### Note

This method is available in PyGTK 2.4 and above.

The `get_is_important`() method returns the value of the "is-important" property. If "is-important" is `True`, the tool item is considered important. See the `set_is_important()` method for more information.

### gtk.ToolItem.get_icon_size

        def get_icon_size()

Returns : | the icon size used for the tool item

### Note

This method is available in PyGTK 2.4 and above.

The `get_icon_size`() method returns the icon size used for the tool item. Custom subclasses of `gtk.ToolItem` should call this method to find out what size icons they should use. The return value should be one of: `gtk.ICON_SIZE_MENU`, `gtk.ICON_SIZE_SMALL_TOOLBAR`, `gtk.ICON_SIZE_LARGE_TOOLBAR`, `gtk.ICON_SIZE_BUTTON`, `gtk.ICON_SIZE_DND`, `gtk.ICON_SIZE_DIALOG` or an integer value returned from the `gtk.icon_size_register`() function.

### gtk.ToolItem.get_orientation

        def get_orientation()

Returns : | the orientation used for the tool item

### Note

This method is available in PyGTK 2.4 and above.

The `get_orientation`() method returns the orientation used for the tool item. Custom subclasses of `gtk.ToolItem` should call this method to find out what size icons they should use. The return value should be either `gtk.ORIENTATION_HORIZONTAL` or `gtk.ORIENTATION_VERTICAL`.

### gtk.ToolItem.get_toolbar_style

        def get_toolbar_style()

Returns : | the toolbar style used for the tool item

### Note

This method is available in PyGTK 2.4 and above.

The `get_toolbar_style`() method returns the toolbar style used for the tool item. Custom subclasses of `gtk.ToolItem` should call this method in the "toolbar-reconfigured" signal handler to find out in what style the toolbar is displayed and change themselves accordingly.

Possibilities are:

- `gtk.TOOLBAR_BOTH`, meaning the tool item should show both an icon and a label, stacked vertically

- `gtk.TOOLBAR_ICONS`, meaning the toolbar shows only icons

- `gtk.TOOLBAR_TEXT`, meaning the tool item should only show text

- `gtk.TOOLBAR_BOTH_HORIZ`, meaning the tool item should show both an icon and a label, arranged horizontally..

### gtk.ToolItem.get_relief_style

        def get_relief_style()

Returns : | the relief style used for the tool item

### Note

This method is available in PyGTK 2.4 and above.

The `get_relief_style`() method returns the relief style of the tool item. See the `gtk.Button.set_relief`() method for more information. Custom subclasses of `gtk.ToolItem` should call this method in the handler of the `gtk.ToolItem` "toolbar-reconfigured" signal to find out the relief style of buttons.

The return value should be one of: `gtk.RELIEF_NORMAL`, `gtk.RELIEF_HALF` or `gtk.RELIEF_NONE`.

### gtk.ToolItem.retrieve_proxy_menu_item

        def retrieve_proxy_menu_item()

Returns : | The `gtk.MenuItem` that is going to appear in the overflow menu for the tool item

### Note

This method is available in PyGTK 2.4 and above.

The `retrieve_proxy_menu_item`() method returns the `gtk.MenuItem` that was last set by the `set_proxy_menu_item()` method, i.e. the `gtk.MenuItem` that is going to appear in the overflow menu.

### gtk.ToolItem.set_proxy_menu_item

        def set_proxy_menu_item(menu_item_id, menu_item)

`menu_item_id` : | a string used to identify `menu_item`
`menu_item` : | a `gtk.MenuItem` to be used in the overflow menu or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_proxy_menu_item`() method sets the `gtk.MenuItem` specified by `menu_item` to be used in the toolbar overflow menu. `menu_item_id` is used to identify the caller of this method and should also be used with the `get_proxy_menu_item()` method. If `menu_item` is `None` the tool item will not appear in the overflow menu.

### gtk.ToolItem.get_proxy_menu_item

        def get_proxy_menu_item(menu_item_id)

`menu_item_id` : | a string used to identify the menu item
Returns : | The `gtk.MenuItem` matching `menu_item_id`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_proxy_menu_item`() method returns the `gtk.MenuItem` corresponding to the string specified by `menu_item_id` as passed to the `set_proxy_menu_item()` method.

Custom subclasses of `gtk.ToolItem` should use this method to update their menu item when the `gtk.ToolItem` changes. Forcing a match with `menu_item_id` ensures that a `gtk.ToolItem` will not inadvertently change a menu item that they did not create.

### gtk.ToolItem.rebuild_menu

        def rebuild_menu()

### Note

This method is available in PyGTK 2.6 and above.

The `rebuild_menu`() method ignals to the toolbar that the overflow menu item has changed. If the overflow menu is visible when this method it called, the menu will be rebuilt. The method must be called when the tool item changes what it will do in response to the "create_menu_proxy" signal.

## Signals

### The "create-menu-proxy" gtk.ToolItem Signal

        def callback(toolitem, user_param1, ...)

`toolitem` : | the toolitem that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

### Note

This signal is available in GTK+ 2.4 and above.

The "create-menu-proxy" signal is emitted when the toolbar is displaying an overflow menu and is trying to determine if `toolitem` should appear in the overflow menu. In response `toolitem` should either

- call the `set_proxy_menu_item`() method specifying `menu_item` as `None` and return `True` to indicate that the item should not appear in the overflow menu

- call the `set_proxy_menu_item`() method with a new menu item and return `True`, or

- return `False` to indicate that the signal was not handled by the item. This means that the item will not appear in the overflow menu unless a later handler installs a menu item.

The toolbar may cache the result of this signal. When the tool item changes how it will respond to this signal it must call the `rebuild_menu`()) method to invalidate the cache and ensure that the toolbar rebuilds its overflow menu.

### The "set-tooltip" gtk.ToolItem Signal

        def callback(toolitem, tooltips, tip_text, tip_private, user_param1, ...)

`toolitem` : | the toolitem that received the signal
`tooltips` : | the `gtk.Tooltips`
`tip_text` : | the tooltip text
`tip_private` : | the tooltip private text
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the signal was handled

### Note

This signal is available in GTK+ 2.4 and above.

The "set-tooltip" signal is emitted when the tool item's tooltip changes. Application developers can use the `set_tooltip`() method to set the item's tooltip.

### The "toolbar-reconfigured" gtk.ToolItem Signal

        def callback(toolitem, user_param1, ...)

`toolitem` : | the toolitem that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.4 and above.

The "toolbar-reconfigured" signal is emitted when some property of the toolbar that the item is a child of changes. For custom subclasses of `gtk.ToolItem`, the default handler of this signal uses the methods:

- `gtk.Toolbar.get_orientation`()
- `gtk.Toolbar.get_style`()
- `gtk.Toolbar.get_icon_size`()
- `gtk.Toolbar.get_relief_style`()

to find out what the toolbar should look like and change themselves accordingly.

Prev | Up | Next
gtk.ToolButton | Home | gtk.Tooltips