gtk.ToolButton
Prev | The gtk Class Reference | Next

## gtk.ToolButton

gtk.ToolButton — a `gtk.ToolItem` subclass that displays buttons (new in PyGTK 2.4)

## Synopsis

    class gtk.ToolButton(gtk.ToolItem):
        gtk.ToolButton(icon_widget=None, label=None)
        gtk.ToolButton(stock_id)
        def set_label(label)
        def get_label()
        def set_use_underline(use_underline)
        def get_use_underline()
        def set_stock_id(stock_id)
        def get_stock_id()
        def set_icon_name(icon_name)
        def get_icon_name()
        def set_icon_widget(icon_widget)
        def get_icon_widget()
        def set_label_widget(label_widget)
        def get_label_widget()

## Ancestry

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

## Implemented Interfaces

`gtk.ToolButton` implements `gtk.Buildable`

## gtk.ToolButton Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

gtk.ToolItem Properties

"icon-name" | Read-Write | The themed icon name to display in the item. This property only has an effect if not overridden by "label", "icon-widget" or "stock-id" properties. Default value: `None`. Available in GTK+ 2.8 and above.
"icon-widget" | Read-Write | The icon widget to display in the item. Default value: `None`.
"label" | Read-Write | The text to show in the item. Default value: `None`.
"label-widget" | Read-Write | The widget to use as the item label instead of "label". Default value: `None`.
"stock-id" | Read-Write | The stock icon displayed on the item if "label" and "label-widget" are `None`. Default value: `None`.
"use-underline" | Read-Write | If `True`, an underline in the "label" property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu. Default value: `False`.

## gtk.ToolButton Style Properties

gtk.Widget Style Properties

"icon-spacing" | Read-Write | Spacing in pixels between the icon and label

## gtk.ToolButton Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.ToolItem Signal Prototypes

## Signal Prototypes

"clicked" | `def callback(`toolbutton`, `user_param1`, `...`)`

## Description

### Note

This widget is available in PyGTK 2.4 and above.

A `gtk.ToolButton` is a sub class of `gtk.ToolItem` that contains a button. Use the gtk.ToolButton() constructor to create a new `gtk.ToolButton` specifying a widget to use as the icon and a label for the text. Alternatively use the other gtk.ToolButton() constructor to create a `gtk.ToolButton` from a stock item.

The label of a `gtk.ToolButton` is determined by the properties "label_widget", "label", and "stock_id". If "label_widget" specifies a `gtk.Widget`, that widget is used as the label. If "label-widget" is `None`, then the string in "label" is used as the label. If both "label-widget" and "label" are `None`, the label is determined by the stock item specified by "stock-id". Finally, if "label-widget", "label" and "stock-id" are all `None`, the button does not have a label.

The icon of a `gtk.ToolButton` is determined by the properties "icon-widget" and "stock-id". If "icon-widget" specifies a `gtk.Widget`, that widget is used as the icon. If "icon-widget" is `None`, the icon is determined by the stock item specified by "stock-id". If both "icon-widget" and "stock-id" are `None`, the button does not have an icon.

## Constructor

### gtk.ToolButton

        gtk.ToolButton(icon_widget=None, label=None)

`icon_widget` : | a `gtk.Widget` that will be used as the icon widget, or `None`
`label` : | a string that will be used as the label, or `None`
Returns : | A new `gtk.ToolButton`

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new `gtk.ToolButton` optionally using the icon specified by `icon_widget` and the label text specified by `label`. If both `icon_widget` and `label` are `None`, the tool button will be empty.

### gtk.ToolButton

        gtk.ToolButton(stock_id)

`stock_id` : | a string that specifies a stock item
Returns : | A new `gtk.ToolButton`

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new `gtk.ToolButton` using the stock item specified by `stock_id` to determine the icon and label text. It is an error if `stock_id` is not a name of a stock item.

## Methods

### gtk.ToolButton.set_label

        def set_label(label)

`label` : | a string that will be used as label, or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `set_label`() method sets the "label" property to the value of `label`. If the "label_widget" property is `None`, label will be used as the label of the tool button.

### gtk.ToolButton.get_label

        def get_label()

Returns : | The label, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `get_label`() method returns the value of the "label" property that is used as the label of the tool button if the "label-widget" property is `None`.

### gtk.ToolButton.set_use_underline

        def set_use_underline(use_underline)

`use_underline` : | if `True`, an underline in the label string specifies a mnemonic key for the overflow menu

### Note

This method is available in PyGTK 2.4 and above.

The `set_use_underline`() method sets the "use-underline" property to the value of `use_underline`. If `use_underline` is `True`, an underline in the "label" property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu. For example, if the label property is "_Open" and `use_underline` is `True`, the label on the tool button will be "Open" and the item on the overflow menu will have an underlined 'O'. Labels shown on tool buttons never have mnemonics on them; this property only affects the menu item on the overflow menu.

### gtk.ToolButton.get_use_underline

        def get_use_underline()

Returns : | `True` if underscores in the "label" property are used as mnemonics on menu items on the overflow menu.

### Note

This method is available in PyGTK 2.4 and above.

The `get_use_underline`() method returns the value of the "use-underline" property. If "use-underline" is `True`, underscores in the label property are used as mnemonics on menu items on the overflow menu. See the `set_use_underline()` method for more information.

### gtk.ToolButton.set_stock_id

        def set_stock_id(stock_id)

`stock_id` : | a name of a stock item, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_stock_id`() method sets the "stock-id" property to the value of `stock_id`. The stock item specified by `stock_id` is used to determine the icon and label if not overridden by the "label" and "icon-widget" properties. See the gtk.ToolButton() constructor for more information.

### gtk.ToolButton.get_stock_id

        def get_stock_id()

Returns : | the name of the stock item.

### Note

This method is available in PyGTK 2.4 and above.

The `get_stock_id`() method returns the value of the "stock-id" property that contains the name of a stock item or `None`. See the gtk.ToolButton() constructor for more information.

### gtk.ToolButton.set_icon_name

        def set_icon_name(icon_name)

`icon_name` : | a name of a themed icon, or `None`

### Note

This method is available in PyGTK 2.8 and above.

The `set_icon_name`() method sets the "icon-name" property to the value of `icon_name`. The themed icon name specified by `icon_name` is used to determine the icon for the toolbutton if not overridden by the "label", "stock-id" and "icon-widget" properties. See the gtk.ToolButton() constructor for more information.

In PyGTK 2.10 and above, `icon_name` may be `None` to unset the icon name.

### gtk.ToolButton.get_icon_name

        def get_icon_name()

Returns : | the name of the stock item.

### Note

This method is available in PyGTK 2.8 and above.

The `get_icon_name`() method returns the value of the "icon_name" property that contains the name of a themed icon or `None`. See the gtk.ToolButton() constructor for more information.

### gtk.ToolButton.set_icon_widget

        def set_icon_widget(icon_widget)

`icon_widget` : | the widget used as icon, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_icon_widget`() method sets the "icon-widget" property to the value of `icon_widget`. If `icon_widget` specifies a `gtk.Widget`, it is used as the icon of the tool button. If `icon_widget` is `None` the icon is determined by the "stock_id" property. If the "stock_id" property is also `None`, the tool button will not have an icon.

### gtk.ToolButton.get_icon_widget

        def get_icon_widget()

Returns : | The widget used as icon on `button`, or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_icon_widget`() method returns the value of the "icon-widget" property that contains the `gtk.Widget` used as the icon on the tool button. See the `set_icon_widget()` method for more information.

### gtk.ToolButton.set_label_widget

        def set_label_widget(label_widget)

`label_widget` : | the widget used as the label, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_label_widget`() method sets the "label-widget" property to the `gtk.Widget` specified by `label_widget` that will be used as the label for the tool button. If `label_widget` is `None` the "label" property is used as label. If "label-widget" and "label" are both `None`, the label in the stock item determined by the "stock_id" property is used as the label. If "label-widget", "label" and "stock_id" are all `None`, the tool button will not have a label.

### gtk.ToolButton.get_label_widget

        def get_label_widget()

Returns : | The widget used as label on `button`, or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_label_widget`() method returns the value of the "label-widget" property that is used as the label on the tool button. See the `gtk.ToolButton.set_label_widget()` method for more information.

## Signals

### The "clicked" gtk.ToolButton Signal

        def callback(toolbutton, user_param1, ...)

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

The "clicked" signal is emitted when the tool button is clicked with the mouse or activated with the keyboard.

Prev | Up | Next
gtk.Toolbar | Home | gtk.ToolItem