Gtk.Button¶

Example¶

Subclasses:	`Gtk.ColorButton`, `Gtk.FontButton`, `Gtk.LinkButton`, `Gtk.LockButton`, `Gtk.ModelButton`, `Gtk.ScaleButton`, `Gtk.ToggleButton`

Methods¶

Inherited:	Gtk.Bin (1), Gtk.Container (35), Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10), Gtk.Actionable (5), Gtk.Activatable (6)
Structs:	Gtk.ContainerClass (5), Gtk.WidgetClass (12), GObject.ObjectClass (5)

class	`new` ()
class	`new_from_icon_name` (icon_name, size)
class	`new_from_stock` (stock_id)
class	`new_with_label` (label)
class	`new_with_mnemonic` (label)
	`clicked` ()
	`enter` ()
	`get_alignment` ()
	`get_always_show_image` ()
	`get_event_window` ()
	`get_focus_on_click` ()
	`get_image` ()
	`get_image_position` ()
	`get_label` ()
	`get_relief` ()
	`get_use_stock` ()
	`get_use_underline` ()
	`leave` ()
	`pressed` ()
	`released` ()
	`set_alignment` (xalign, yalign)
	`set_always_show_image` (always_show)
	`set_focus_on_click` (focus_on_click)
	`set_image` (image)
	`set_image_position` (position)
	`set_label` (label)
	`set_relief` (relief)
	`set_use_stock` (use_stock)
	`set_use_underline` (use_underline)

Virtual Methods¶

Inherited:	Gtk.Container (10), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10), Gtk.Actionable (4), Gtk.Activatable (2)

	`do_activate` ()
	`do_clicked` ()
	`do_enter` ()
	`do_leave` ()
	`do_pressed` ()
	`do_released` ()

Properties¶

Inherited:	Gtk.Container (3), Gtk.Widget (39), Gtk.Actionable (2), Gtk.Activatable (2)

Name	Type	Flags	Short Description
`always-show-image`	`bool`	r/w/c/en	Whether the image will always be shown
`image`	`Gtk.Widget`	r/w/en	Child widget to appear next to the button text
`image-position`	`Gtk.PositionType`	r/w/en	The position of the image relative to the text
`label`	`str`	r/w/c/en	Text of the label widget inside the button, if the button contains a label widget
`relief`	`Gtk.ReliefStyle`	r/w/en	The border relief style
`use-stock`	`bool`	d/r/w/c/en	If set, the label is used to pick a stock item instead of being displayed `deprecated`
`use-underline`	`bool`	r/w/c/en	If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key
`xalign`	`float`	d/r/w/en	Horizontal position of child in available space. 0.0 is left aligned, 1.0 is right aligned `deprecated`
`yalign`	`float`	d/r/w/en	Vertical position of child in available space. 0.0 is top aligned, 1.0 is bottom aligned `deprecated`

Style Properties¶

Inherited:	Gtk.Widget (17)

Name	Type	Default	Flags	Short Description
`child-displacement-x`	`int`	`0`	d/r	How far in the x direction to move the child when the button is depressed `deprecated`
`child-displacement-y`	`int`	`0`	d/r	How far in the y direction to move the child when the button is depressed `deprecated`
`default-border`	`Gtk.Border`	`None`	d/r	Extra space to add for GTK_CAN_DEFAULT buttons `deprecated`
`default-outside-border`	`Gtk.Border`	`None`	d/r	Extra space to add for GTK_CAN_DEFAULT buttons that is always drawn outside the border `deprecated`
`displace-focus`	`bool`	`False`	d/r	Whether the child_displacement_x/_y properties should also affect the focus rectangle `deprecated`
`image-spacing`	`int`	`2`	d/r	Spacing in pixels between the image and label `deprecated`
`inner-border`	`Gtk.Border`	`None`	d/r	Border between button edges and child. `deprecated`

Signals¶

Inherited:	Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Short Description
`activate`	The `::activate` signal on `Gtk.Button` is an action signal and emitting it causes the button to animate press then release.
`clicked`	Emitted when the button has been activated (pressed and released).
`enter`	Emitted when the pointer enters the button. `deprecated`
`leave`	Emitted when the pointer leaves the button. `deprecated`
`pressed`	Emitted when the button is pressed. `deprecated`
`released`	Emitted when the button is released. `deprecated`

Fields¶

Inherited:	Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Type	Access	Description
bin	`Gtk.Bin`	r

Class Details¶

class Gtk.Button(*args, **kwargs)¶

Bases:	`Gtk.Bin`, `Gtk.Actionable`, `Gtk.Activatable`
Abstract:	No
Structure:	`Gtk.ButtonClass`

The Gtk.Button widget is generally used to trigger a callback function that is called when the button is pressed. The various signals and how to use them are outlined below.

The Gtk.Button widget can hold any valid child widget. That is, it can hold almost any other standard Gtk.Widget. The most commonly used child is the Gtk.Label.

CSS nodes

Gtk.Button has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class.

Other style classes that are commonly used with Gtk.Button include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class.

Button-like widgets like Gtk.ToggleButton, Gtk.MenuButton, Gtk.VolumeButton, Gtk.LockButton, Gtk.ColorButton, Gtk.FontButton or Gtk.FileChooserButton use style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file to differentiate themselves from a plain Gtk.Button.

classmethod new()[source]¶

Returns:	The newly created `Gtk.Button` widget.
Return type:	`Gtk.Widget`

Creates a new Gtk.Button widget. To add a child widget to the button, use Gtk.Container.add().

classmethod new_from_icon_name(icon_name, size)[source]¶

Parameters:	icon_name (`str` or `None`) – an icon name or `None` size (`int`) – an icon size (`Gtk.IconSize`)
Returns:	a new `Gtk.Button` displaying the themed icon
Return type:	`Gtk.Widget`

Creates a new button containing an icon from the current icon theme.

If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

This function is a convenience wrapper around Gtk.Button.new() and Gtk.Button.set_image().

New in version 3.10.

classmethod new_from_stock(stock_id)[source]¶

Parameters:	stock_id (`str`) – the name of the stock item
Returns:	a new `Gtk.Button`
Return type:	`Gtk.Widget`

Creates a new Gtk.Button containing the image and text from a ‘stock item [gtkstock]’. Some stock ids have preprocessor macros like Gtk.STOCK_OK and Gtk.STOCK_APPLY.

If stock_id is unknown, then it will be treated as a mnemonic label (as for Gtk.Button.new_with_mnemonic()).

Deprecated since version 3.10: Stock items are deprecated. Use Gtk.Button.new_with_label() instead.

classmethod new_with_label(label)[source]¶

Parameters:	label (`str`) – The text you want the `Gtk.Label` to hold.
Returns:	The newly created `Gtk.Button` widget.
Return type:	`Gtk.Widget`

Creates a Gtk.Button widget with a Gtk.Label child containing the given text.

classmethod new_with_mnemonic(label)[source]¶

Parameters:	label (`str`) – The text of the button, with an underscore in front of the mnemonic character
Returns:	a new `Gtk.Button`
Return type:	`Gtk.Widget`

Creates a new Gtk.Button containing a label. If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.

clicked()[source]¶: Emits a Gtk.Button ::clicked signal to the given Gtk.Button.

enter()[source]¶: Emits a Gtk.Button ::enter signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::enter-notify-event signal.

get_alignment()[source]¶

Returns:

xalign:	return location for horizontal alignment
yalign:	return location for vertical alignment

Return type: (xalign: float, yalign: float)

Gets the alignment of the child in the button.

New in version 2.4.

Deprecated since version 3.14: Access the child widget directly if you need to control its alignment.

get_always_show_image()[source]¶

Returns:	`True` if the button will always show the image
Return type:	`bool`

Returns whether the button will ignore the Gtk.Settings :gtk-button-images setting and always show the image, if available.

New in version 3.6.

get_event_window()[source]¶

Returns:	self’s event window.
Return type:	`Gdk.Window`

Returns the button’s event window if it is realized, None otherwise. This function should be rarely needed.

New in version 2.22.

get_focus_on_click()[source]¶

Returns:	`True` if the button grabs focus when it is clicked with the mouse.
Return type:	`bool`

Returns whether the button grabs focus when it is clicked with the mouse. See Gtk.Button.set_focus_on_click().

New in version 2.4.

Deprecated since version 3.20: Use Gtk.Widget.get_focus_on_click() instead

get_image()[source]¶

Returns:	a `Gtk.Widget` or `None` in case there is no image
Return type:	`Gtk.Widget` or `None`

Gets the widget that is currenty set as the image of self. This may have been explicitly set by Gtk.Button.set_image() or constructed by Gtk.Button.new_from_stock().

New in version 2.6.

get_image_position()[source]¶

Returns:	the position
Return type:	`Gtk.PositionType`

Gets the position of the image relative to the text inside the button.

New in version 2.10.

get_label()[source]¶

Returns:	The text of the label widget. This string is owned by the widget and must not be modified or freed.
Return type:	`str`

Fetches the text from the label of the button, as set by Gtk.Button.set_label(). If the label text has not been set the return value will be None. This will be the case if you create an empty button with Gtk.Button.new() to use as a container.

get_relief()[source]¶

Returns:	The current `Gtk.ReliefStyle`
Return type:	`Gtk.ReliefStyle`

Returns the current relief style of the given Gtk.Button.

get_use_stock()[source]¶

Returns:	`True` if the button label is used to select a stock item instead of being used directly as the label text.
Return type:	`bool`

Returns whether the button label is a stock item.

Deprecated since version 3.10.

get_use_underline()[source]¶

Returns:	`True` if an embedded underline in the button label indicates the mnemonic accelerator keys.
Return type:	`bool`

Returns whether an embedded underline in the button label indicates a mnemonic. See Gtk.Button.set_use_underline ().

leave()[source]¶: Emits a Gtk.Button ::leave signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::leave-notify-event signal.

pressed()[source]¶: Emits a Gtk.Button ::pressed signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::button-press-event signal.

released()[source]¶: Emits a Gtk.Button ::released signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::button-release-event signal.

set_alignment(xalign, yalign)[source]¶

Parameters:	xalign (`float`) – the horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned yalign (`float`) – the vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned

Sets the alignment of the child. This property has no effect unless the child is a Gtk.Misc or a Gtk.Alignment.

New in version 2.4.

Deprecated since version 3.14: Access the child widget directly if you need to control its alignment.

set_always_show_image(always_show)[source]¶

Parameters:	always_show (`bool`) – `True` if the menuitem should always show the image

If True, the button will ignore the Gtk.Settings :gtk-button-images setting and always show the image, if available.

Use this property if the button would be useless or hard to use without the image.

New in version 3.6.

set_focus_on_click(focus_on_click)[source]¶

Parameters:	focus_on_click (`bool`) – whether the button grabs focus when clicked with the mouse

Sets whether the button will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application.

New in version 2.4.

Deprecated since version 3.20: Use Gtk.Widget.set_focus_on_click() instead

set_image(image)[source]¶

Parameters:	image (`Gtk.Widget` or `None`) – a widget to set as the image for the button, or `None` to unset

Set the image of self to the given widget. The image will be displayed if the label text is None or if Gtk.Button :always-show-image is True. You don’t have to call Gtk.Widget.show() on image yourself.

New in version 2.6.

set_image_position(position)[source]¶

Parameters:	position (`Gtk.PositionType`) – the position

Sets the position of the image relative to the text inside the button.

New in version 2.10.

set_label(label)[source]¶

Parameters:	label (`str`) – a string

Sets the text of the label of the button to str. This text is also used to select the stock item if Gtk.Button.set_use_stock() is used.

This will also clear any previously set labels.

set_relief(relief)[source]¶

Parameters:	relief (`Gtk.ReliefStyle`) – The `Gtk.ReliefStyle` as described above

Sets the relief style of the edges of the given Gtk.Button widget. Two styles exist, Gtk.ReliefStyle.NORMAL and Gtk.ReliefStyle.NONE. The default style is, as one can guess, Gtk.ReliefStyle.NORMAL. The deprecated value Gtk.ReliefStyle.HALF behaves the same as Gtk.ReliefStyle.NORMAL.

set_use_stock(use_stock)[source]¶

Parameters:	use_stock (`bool`) – `True` if the button should use a stock item

If True, the label set on the button is used as a stock id to select the stock item for the button.

Deprecated since version 3.10.

set_use_underline(use_underline)[source]¶

Parameters:	use_underline (`bool`) – `True` if underlines in the text indicate mnemonics

If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.

do_activate() virtual¶

do_clicked() virtual¶: Emits a Gtk.Button ::clicked signal to the given Gtk.Button.

do_enter() virtual¶: Emits a Gtk.Button ::enter signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::enter-notify-event signal.

do_leave() virtual¶: Emits a Gtk.Button ::leave signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::leave-notify-event signal.

do_pressed() virtual¶: Emits a Gtk.Button ::pressed signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::button-press-event signal.

do_released() virtual¶: Emits a Gtk.Button ::released signal to the given Gtk.Button.

Deprecated since version 2.20: Use the Gtk.Widget ::button-release-event signal.

Signal Details¶

Gtk.Button.signals.activate(button)¶

Signal Name:	`activate`
Flags:	`RUN_FIRST`, `ACTION`
Parameters:	button (`Gtk.Button`) – The object which received the signal

The ::activate signal on Gtk.Button is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the Gtk.Button ::clicked signal.

Gtk.Button.signals.clicked(button)¶

Signal Name:	`clicked`
Flags:	`RUN_FIRST`, `ACTION`
Parameters:	button (`Gtk.Button`) – The object which received the signal

Emitted when the button has been activated (pressed and released).

Gtk.Button.signals.enter(button)¶

Signal Name:	`enter`
Flags:	`RUN_FIRST`
Parameters:	button (`Gtk.Button`) – The object which received the signal

Emitted when the pointer enters the button.

Deprecated since version 2.8: Use the Gtk.Widget ::enter-notify-event signal.

Gtk.Button.signals.leave(button)¶

Signal Name:	`leave`
Flags:	`RUN_FIRST`
Parameters:	button (`Gtk.Button`) – The object which received the signal

Emitted when the pointer leaves the button.

Deprecated since version 2.8: Use the Gtk.Widget ::leave-notify-event signal.

Gtk.Button.signals.pressed(button)¶

Signal Name:	`pressed`
Flags:	`RUN_FIRST`
Parameters:	button (`Gtk.Button`) – The object which received the signal

Emitted when the button is pressed.

Deprecated since version 2.8: Use the Gtk.Widget ::button-press-event signal.

Gtk.Button.signals.released(button)¶

Signal Name:	`released`
Flags:	`RUN_FIRST`
Parameters:	button (`Gtk.Button`) – The object which received the signal

Emitted when the button is released.

Deprecated since version 2.8: Use the Gtk.Widget ::button-release-event signal.

Property Details¶

Gtk.Button.props.always_show_image¶

Name:	`always-show-image`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

If True, the button will ignore the Gtk.Settings :gtk-button-images setting and always show the image, if available.

Use this property if the button would be useless or hard to use without the image.

New in version 3.6.

Gtk.Button.props.image¶

Name:	`image`
Type:	`Gtk.Widget`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

The child widget to appear next to the button text.

New in version 2.6.

Gtk.Button.props.image_position¶

Name:	`image-position`
Type:	`Gtk.PositionType`
Default Value:	`Gtk.PositionType.LEFT`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

The position of the image relative to the text inside the button.

New in version 2.10.

Gtk.Button.props.label¶

Name:	`label`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

Text of the label widget inside the button, if the button contains a label widget

Gtk.Button.props.relief¶

Name:	`relief`
Type:	`Gtk.ReliefStyle`
Default Value:	`Gtk.ReliefStyle.NORMAL`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

The border relief style

Gtk.Button.props.use_stock¶

Name:	`use-stock`
Type:	`bool`
Default Value:	`False`
Flags:	`DEPRECATED`, `READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

If set, the label is used to pick a stock item instead of being displayed

Deprecated since version 3.10.

Gtk.Button.props.use_underline¶

Name:	`use-underline`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT`, `EXPLICIT_NOTIFY`

If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key

Gtk.Button.props.xalign¶

Name:	`xalign`
Type:	`float`
Default Value:	`0.5`
Flags:	`DEPRECATED`, `READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

If the child of the button is a Gtk.Misc or Gtk.Alignment, this property can be used to control its horizontal alignment. 0.0 is left aligned, 1.0 is right aligned.

New in version 2.4.

Deprecated since version 3.14: Access the child widget directly if you need to control its alignment.

Gtk.Button.props.yalign¶

Name:	`yalign`
Type:	`float`
Default Value:	`0.5`
Flags:	`DEPRECATED`, `READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

If the child of the button is a Gtk.Misc or Gtk.Alignment, this property can be used to control its vertical alignment. 0.0 is top aligned, 1.0 is bottom aligned.

New in version 2.4.

Deprecated since version 3.14: Access the child widget directly if you need to control its alignment.