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

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class ButtonWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='Button Demo')

        hbox = Gtk.Box(spacing=6)
        self.set_child(hbox)

        button = Gtk.Button.new_with_label('Click Me')
        button.connect('clicked', self.on_click_me_clicked)
        hbox.append(button)

        button = Gtk.Button.new_with_mnemonic('_Open')
        button.connect('clicked', self.on_open_clicked)
        hbox.append(button)

        button = Gtk.Button.new_with_mnemonic('_Close')
        button.connect('clicked', self.on_close_clicked)
        hbox.append(button)

    def on_click_me_clicked(self, _button):
        print('[Click me] button was clicked')

    def on_open_clicked(self, _button):
        print('[Open] button was clicked')

    def on_close_clicked(self, _button):
        print('Closing application')
        self.close()


def on_activate(app):
    win = ButtonWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.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

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class ToggleButtonWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='ToggleButton Demo')

        hbox = Gtk.Box(spacing=6)
        self.set_child(hbox)

        button = Gtk.ToggleButton(label='Button 1')
        button.connect('toggled', self.on_button_toggled, '1')
        hbox.append(button)

        button = Gtk.ToggleButton(label='B_utton 2', use_underline=True)
        button.set_active(True)
        button.connect('toggled', self.on_button_toggled, '2')
        hbox.append(button)

    def on_button_toggled(self, button, name):
        if button.props.active:
            state = 'on'
        else:
            state = 'off'
        print('Button', name, 'was turned', state)


def on_activate(app):
    win = ToggleButtonWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.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

import gi

gi.require_version('Gtk', '4.0')
from gi.repository import Gtk


class LinkButtonWindow(Gtk.ApplicationWindow):
    def __init__(self, **kargs):
        super().__init__(**kargs, title='LinkButton Demo')

        button = Gtk.LinkButton(
            uri='https://www.gtk.org', label='Visit GTK Homepage'
        )
        self.set_child(button)


def on_activate(app):
    win = LinkButtonWindow(application=app)
    win.present()


app = Gtk.Application(application_id='com.example.App')
app.connect('activate', on_activate)

app.run(None)