Gtk.Button¶

class — extends Widget, Accessible, Actionable, Buildable, ConstraintTarget

Calls a callback function when the button is clicked.

The GtkButton widget can hold any valid child widget. That is, it can hold almost any other standard GtkWidget. The most commonly used child is the GtkLabel.

Shortcuts and Gestures¶

The following signals have default keybindings:

Button.activate

CSS nodes¶

GtkButton 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. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class.

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

Button-like widgets like ToggleButton, MenuButton, VolumeButton, LockButton, ColorButton or FontButton use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain GtkButton.

Accessibility¶

GtkButton uses the AccessibleRole.button role.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new GtkButton widget.

To add a child widget to the button, use Button.set_child.

new_from_icon_name¶

@classmethod
def new_from_icon_name(cls, icon_name: str) -> 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.

Parameters:

icon_name — an icon name

new_with_label¶

@classmethod
def new_with_label(cls, label: str) -> Widget

Creates a GtkButton widget with a GtkLabel child.

Parameters:

label — The text you want the GtkLabel to hold

new_with_mnemonic¶

@classmethod
def new_with_mnemonic(cls, label: str) -> Widget

Creates a new GtkButton 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 <kbd>Alt</kbd> and that key activates the button.

Parameters:

label — The text of the button, with an underscore in front of the mnemonic character

Methods¶

get_can_shrink¶

def get_can_shrink(self) -> bool

Retrieves whether the button can be smaller than the natural size of its contents.

get_child¶

def get_child(self) -> Widget | None

Gets the child widget of button.

get_has_frame¶

def get_has_frame(self) -> bool

Returns whether the button has a frame.

get_icon_name¶

def get_icon_name(self) -> str | None

Returns the icon name of the button.

If the icon name has not been set with Button.set_icon_name the return value will be None. This will be the case if you create an empty button with Button.new to use as a container.

get_label¶

def get_label(self) -> str | None

Fetches the text from the label of the button.

If the label text has not been set with Button.set_label the return value will be None. This will be the case if you create an empty button with Button.new to use as a container.

get_use_underline¶

def get_use_underline(self) -> bool

gets whether underlines are interpreted as mnemonics.

See Button.set_use_underline.

set_can_shrink¶

def set_can_shrink(self, can_shrink: bool) -> None

Sets whether the button size can be smaller than the natural size of its contents.

For text buttons, setting can_shrink to true will ellipsize the label.

For icons and custom children, this function has no effect.

Parameters:

can_shrink — whether the button can shrink

set_child¶

def set_child(self, child: Widget | None = ...) -> None

Sets the child widget of button.

Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for button. Most likely, you'll either set the accessibility label or description for button explicitly, or you'll set a labelled-by or described-by relations from child to button.

Parameters:

child — the child widget

set_has_frame¶

def set_has_frame(self, has_frame: bool) -> None

Sets the style of the button.

Buttons can have a flat appearance or have a frame drawn around them.

Parameters:

has_frame — whether the button should have a visible frame

set_icon_name¶

def set_icon_name(self, icon_name: str) -> None

Adds a GtkImage with the given icon name as a child.

If button already contains a child widget, that child widget will be removed and replaced with the image.

Parameters:

icon_name — An icon name

set_label¶

def set_label(self, label: str) -> None

Sets the text of the label of the button to label.

This will also clear any previously set labels.

Parameters:

label — a string

set_use_underline¶

def set_use_underline(self, use_underline: bool) -> None

Sets whether to use underlines as mnemonics.

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

Parameters:

use_underline — True if underlines in the text indicate mnemonics

Virtual methods¶

do_activate¶

def do_activate(self) -> None

Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the clicked signal.

do_clicked¶

def do_clicked(self) -> None

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

Properties¶

can_shrink¶

can_shrink: bool  # read/write

Whether the size of the button can be made smaller than the natural size of its contents.

For text buttons, setting this property will allow ellipsizing the label.

If the contents of a button are an icon or a custom widget, setting this property has no effect.

child¶

child: Widget  # read/write

The child widget.

has_frame¶

has_frame: bool  # read/write

Whether the button has a frame.

icon_name¶

icon_name: str  # read/write

The name of the icon used to automatically populate the button.

label¶

label: str  # read/write

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

use_underline¶

use_underline: bool  # read/write

If set, an underline in the text indicates that the following character is to be used as mnemonic.

Signals¶

activate¶

def on_activate(self) -> None: ...

Emitted to animate press then release.

This is an action signal. Applications should never connect to this signal, but use the Button.clicked signal.

The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys.

clicked¶

def on_clicked(self) -> None: ...

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