gtk.ToolItem

gtk.ToolItem
Prev	The gtk Class Reference	Next

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:

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