Buttons - PyGObject

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Edit this page
Toggle table of contents sidebar

# 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        if button.props.active:
    25            state = 'on'
    26        else:
    27            state = 'off'
    28        print('Button', name, 'was turned', state)
    29
    30
    31def on_activate(app):
    32    win = ToggleButtonWindow(application=app)
    33    win.present()
    34
    35
    36app = Gtk.Application(application_id='com.example.App')
    37app.connect('activate', on_activate)
    38
    39app.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(
    12            uri='https://www.gtk.org', label='Visit GTK Homepage'
    13        )
    14        self.set_child(button)
    15
    16
    17def on_activate(app):
    18    win = LinkButtonWindow(application=app)
    19    win.present()
    20
    21
    22app = Gtk.Application(application_id='com.example.App')
    23app.connect('activate', on_activate)
    24
    25app.run(None)