Gtk.ToolButton

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Actionable Gtk.Actionable GObject.GInterface->Gtk.Actionable Gtk.Activatable Gtk.Activatable GObject.GInterface->Gtk.Activatable Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.ToolButton Gtk.ToolButton Gtk.Actionable->Gtk.ToolButton Gtk.ToolItem Gtk.ToolItem Gtk.Activatable->Gtk.ToolItem Gtk.Bin Gtk.Bin Gtk.Bin->Gtk.ToolItem Gtk.Buildable->Gtk.Widget Gtk.Container Gtk.Container Gtk.Container->Gtk.Bin Gtk.ToolItem->Gtk.ToolButton Gtk.Widget->Gtk.Container

Subclasses:Gtk.MenuToolButton, Gtk.ToggleToolButton

Properties

Inherited:Gtk.ToolItem (3), Gtk.Container (3), Gtk.Widget (39), Gtk.Activatable (2), Gtk.Actionable (2)
Name Type Flags Short Description
icon-name str r/w The name of the themed icon displayed on the item
icon-widget Gtk.Widget r/w Icon widget to display in the item
label str r/w Text to show in the item.
label-widget Gtk.Widget r/w Widget to use as the item label
stock-id str d/r/w The stock icon displayed on the item deprecated
use-underline bool r/w/en If set, an underline in the label property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu

Style Properties

Inherited:Gtk.Widget (17)
Name Type Default Flags Short Description
icon-spacing int 3 r/w Spacing in pixels between the icon and label

Signals

Inherited:Gtk.ToolItem (2), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)
Name Short Description
clicked This signal is emitted when the tool button is clicked with the mouse or activated with the keyboard.

Fields

Inherited:Gtk.ToolItem (2), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)
Name Type Access Description
parent Gtk.ToolItem r  

Class Details

class Gtk.ToolButton(*args, **kwargs)
Bases:Gtk.ToolItem, Gtk.Actionable
Abstract:No
Structure:Gtk.ToolButtonClass

Gtk.ToolButtons are Gtk.ToolItems containing buttons.

Use Gtk.ToolButton.new() to create a new Gtk.ToolButton.

The label of a Gtk.ToolButton is determined by the properties Gtk.ToolButton :label-widget, Gtk.ToolButton :label, and Gtk.ToolButton :stock-id. If Gtk.ToolButton :label-widget is non-None, then that widget is used as the label. Otherwise, if Gtk.ToolButton :label is non-None, that string is used as the label. Otherwise, if Gtk.ToolButton :stock-id is non-None, the label is determined by the stock item. Otherwise, the button does not have a label.

The icon of a Gtk.ToolButton is determined by the properties Gtk.ToolButton :icon-widget and Gtk.ToolButton :stock-id. If Gtk.ToolButton :icon-widget is non-None, then that widget is used as the icon. Otherwise, if Gtk.ToolButton :stock-id is non-None, the icon is determined by the stock item. Otherwise, the button does not have a icon.

CSS nodes

Gtk.ToolButton has a single CSS node with name toolbutton.

classmethod new(icon_widget, label)[source]
Parameters:
  • icon_widget (Gtk.Widget or None) – a widget that will be used as the button contents, or None
  • label (str or None) – a string that will be used as label, or None
Returns:

A new Gtk.ToolButton

Return type:

Gtk.ToolItem

Creates a new Gtk.ToolButton using icon_widget as contents and label as label.

New in version 2.4.

classmethod new_from_stock(stock_id)[source]
Parameters:stock_id (str) – the name of the stock item
Returns:A new Gtk.ToolButton
Return type:Gtk.ToolItem

Creates a new Gtk.ToolButton containing the image and text from a stock item. Some stock ids have preprocessor macros like Gtk.STOCK_OK and Gtk.STOCK_APPLY.

It is an error if stock_id is not a name of a stock item.

New in version 2.4.

Deprecated since version 3.10: Use Gtk.ToolButton.new() together with Gtk.Image.new_from_icon_name() instead.

get_icon_name()[source]
Returns:the icon name or None if the tool button has no themed icon
Return type:str or None

Returns the name of the themed icon for the tool button, see Gtk.ToolButton.set_icon_name().

New in version 2.8.

get_icon_widget()[source]
Returns:The widget used as icon on self, or None.
Return type:Gtk.Widget or None

Return the widget used as icon widget on self. See Gtk.ToolButton.set_icon_widget().

New in version 2.4.

get_label()[source]
Returns:The label, or None
Return type:str or None

Returns the label used by the tool button, or None if the tool button doesn’t have a label. or uses a the label from a stock item. The returned string is owned by GTK+, and must not be modified or freed.

New in version 2.4.

get_label_widget()[source]
Returns:The widget used as label on self, or None.
Return type:Gtk.Widget or None

Returns the widget used as label on self. See Gtk.ToolButton.set_label_widget().

New in version 2.4.

get_stock_id()[source]
Returns:the name of the stock item for self.
Return type:str

Returns the name of the stock item. See Gtk.ToolButton.set_stock_id(). The returned string is owned by GTK+ and must not be freed or modifed.

New in version 2.4.

Deprecated since version 3.10: Use Gtk.ToolButton.get_icon_name() instead.

get_use_underline()[source]
Returns:True if underscores in the label property are used as mnemonics on menu items on the overflow menu.
Return type:bool

Returns whether underscores in the label property are used as mnemonics on menu items on the overflow menu. See Gtk.ToolButton.set_use_underline().

New in version 2.4.

set_icon_name(icon_name)[source]
Parameters:icon_name (str or None) – the name of the themed icon

Sets the icon for the tool button from a named themed icon. See the docs for Gtk.IconTheme for more details. The Gtk.ToolButton :icon-name property only has an effect if not overridden by non-None Gtk.ToolButton :label-widget, Gtk.ToolButton :icon-widget and Gtk.ToolButton :stock-id properties.

New in version 2.8.

set_icon_widget(icon_widget)[source]
Parameters:icon_widget (Gtk.Widget or None) – the widget used as icon, or None

Sets icon as the widget used as icon on self. If icon_widget is None the icon is determined by the Gtk.ToolButton :stock-id property. If the Gtk.ToolButton :stock-id property is also None, self will not have an icon.

New in version 2.4.

set_label(label)[source]
Parameters:label (str or None) – a string that will be used as label, or None.

Sets label as the label used for the tool button. The Gtk.ToolButton :label property only has an effect if not overridden by a non-None Gtk.ToolButton :label-widget property. If both the Gtk.ToolButton :label-widget and Gtk.ToolButton :label properties are None, the label is determined by the Gtk.ToolButton :stock-id property. If the Gtk.ToolButton :stock-id property is also None, self will not have a label.

New in version 2.4.

set_label_widget(label_widget)[source]
Parameters:label_widget (Gtk.Widget or None) – the widget used as label, or None

Sets label_widget as the widget that will be used as the label for self. If label_widget is None the Gtk.ToolButton :label property is used as label. If Gtk.ToolButton :label is also None, the label in the stock item determined by the Gtk.ToolButton :stock-id property is used as label. If Gtk.ToolButton :stock-id is also None, self does not have a label.

New in version 2.4.

set_stock_id(stock_id)[source]
Parameters:stock_id (str or None) – a name of a stock item, or None

Sets the name of the stock item. See Gtk.ToolButton.new_from_stock(). The stock_id property only has an effect if not overridden by non-None Gtk.ToolButton :label-widget and Gtk.ToolButton :icon-widget properties.

New in version 2.4.

Deprecated since version 3.10: Use Gtk.ToolButton.set_icon_name() instead.

set_use_underline(use_underline)[source]
Parameters:use_underline (bool) – whether the button label has the form “_Open”

If set, 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.

New in version 2.4.

do_clicked() virtual

Signal Details

Gtk.ToolButton.signals.clicked(tool_button)
Signal Name:clicked
Flags:RUN_FIRST, ACTION
Parameters:tool_button (Gtk.ToolButton) – The object which received the signal

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

Property Details

Gtk.ToolButton.props.icon_name
Name:icon-name
Type:str
Default Value:None
Flags:READABLE, WRITABLE

The name of the themed icon displayed on the item. This property only has an effect if not overridden by Gtk.ToolButton :label-widget, Gtk.ToolButton :icon-widget or Gtk.ToolButton :stock-id properties.

New in version 2.8.

Gtk.ToolButton.props.icon_widget
Name:icon-widget
Type:Gtk.Widget
Default Value:None
Flags:READABLE, WRITABLE

Icon widget to display in the item

Gtk.ToolButton.props.label
Name:label
Type:str
Default Value:None
Flags:READABLE, WRITABLE

Text to show in the item.

Gtk.ToolButton.props.label_widget
Name:label-widget
Type:Gtk.Widget
Default Value:None
Flags:READABLE, WRITABLE

Widget to use as the item label

Gtk.ToolButton.props.stock_id
Name:stock-id
Type:str
Default Value:None
Flags:DEPRECATED, READABLE, WRITABLE

The stock icon displayed on the item

Deprecated since version 3.10: Use Gtk.ToolButton :icon-name instead.

Gtk.ToolButton.props.use_underline
Name:use-underline
Type:bool
Default Value:False
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

If set, an underline in the label property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu