Skip to main content
`Ctrl`+`K`

# Buttons

## Button

The Button widget is another commonly used widget. It is generally used to attach a function that is called when the button is pressed.

The `Gtk.Button` widget can hold any valid child widget. That is it can hold most any other standard `Gtk.Widget`. The most commonly used child is the `Gtk.Label`. Normally you will use `Gtk.Button.props.label` to set the button label, or `Gtk.Button.props.icon_name` if you want an icon instead.

Usually, you want to connect to the button’s `clicked` signal which is emitted when the button has been pressed and released.

### Example

     1import gi
     2
     3gi.require_version("Gtk", "4.0")
     4from gi.repository import Gtk
     5
     6
     7class ButtonWindow(Gtk.ApplicationWindow):
     8    def __init__(self, **kargs):
     9        super().__init__(**kargs, title="Button Demo")
    10
    11        hbox = Gtk.Box(spacing=6)
    12        self.set_child(hbox)
    13
    14        button = Gtk.Button.new_with_label("Click Me")
    15        button.connect("clicked", self.on_click_me_clicked)
    16        hbox.append(button)
    17
    18        button = Gtk.Button.new_with_mnemonic("_Open")
    19        button.connect("clicked", self.on_open_clicked)
    20        hbox.append(button)
    21
    22        button = Gtk.Button.new_with_mnemonic("_Close")
    23        button.connect("clicked", self.on_close_clicked)
    24        hbox.append(button)
    25
    26    def on_click_me_clicked(self, _button):
    27        print("[Click me] button was clicked")
    28
    29    def on_open_clicked(self, _button):
    30        print("[Open] button was clicked")
    31
    32    def on_close_clicked(self, _button):
    33        print("Closing application")
    34        self.close()
    35
    36
    37def on_activate(app):
    38    win = ButtonWindow(application=app)
    39    win.present()
    40
    41
    42app = Gtk.Application(application_id="com.example.App")
    43app.connect("activate", on_activate)
    44
    45app.run(None)

## ToggleButton

A `Gtk.ToggleButton` is very similar to a normal `Gtk.Button`, but when clicked they remain activated, or pressed, until clicked again. When the state of the button is changed, the toggled signal is emitted.

To retrieve the state of the `Gtk.ToggleButton`, you can use `Gtk.ToggleButton.props.active`. This returns `True` if the button is “down”. You can also set the toggle button’s state, with `Gtk.ToggleButton.props.active`. Note that, if you do this, and the state actually changes, it causes the “toggled” signal to be emitted.

### Example

     1import gi
     2
     3gi.require_version("Gtk", "4.0")
     4from gi.repository import Gtk
     5
     6
     7class ToggleButtonWindow(Gtk.ApplicationWindow):
     8    def __init__(self, **kargs):
     9        super().__init__(**kargs, title="ToggleButton Demo")
    10
    11        hbox = Gtk.Box(spacing=6)
    12        self.set_child(hbox)
    13
    14        button = Gtk.ToggleButton(label="Button 1")
    15        button.connect("toggled", self.on_button_toggled, "1")
    16        hbox.append(button)
    17
    18        button = Gtk.ToggleButton(label="B_utton 2", use_underline=True)
    19        button.set_active(True)
    20        button.connect("toggled", self.on_button_toggled, "2")
    21        hbox.append(button)
    22
    23    def on_button_toggled(self, button, name):
    24        state = "on" if button.props.active else "off"
    25        print("Button", name, "was turned", state)
    26
    27
    28def on_activate(app):
    29    win = ToggleButtonWindow(application=app)
    30    win.present()
    31
    32
    33app = Gtk.Application(application_id="com.example.App")
    34app.connect("activate", on_activate)
    35
    36app.run(None)

## LinkButton

A `Gtk.LinkButton` is a `Gtk.Button` with a hyperlink, similar to the one used by web browsers, which triggers an action when clicked. It is useful to show quick links to resources.

The URI bound to a `Gtk.LinkButton` can be set specifically using `Gtk.LinkButton.props.uri`.

### Example

     1import gi
     2
     3gi.require_version("Gtk", "4.0")
     4from gi.repository import Gtk
     5
     6
     7class LinkButtonWindow(Gtk.ApplicationWindow):
     8    def __init__(self, **kargs):
     9        super().__init__(**kargs, title="LinkButton Demo")
    10
    11        button = Gtk.LinkButton(uri="https://www.gtk.org", label="Visit GTK Homepage")
    12        self.set_child(button)
    13
    14
    15def on_activate(app):
    16    win = LinkButtonWindow(application=app)
    17    win.present()
    18
    19
    20app = Gtk.Application(application_id="com.example.App")
    21app.connect("activate", on_activate)
    22
    23app.run(None)