A CheckButton displays a small box which is allowed to be in one of three states; checked, unchecked or inconsistent. It is displayed with a Label next to it indicating what function the CheckButton performs.

A CheckButton is based on the ToggleButton widget, and inherits many of the same methods, properties and signals.


The CheckButton can be constructed using:

checkbutton = Gtk.CheckButton(label)

The label parameter allows the associated text to be defined at construction time.


The label on the CheckButton is definable after construction via:


It is good practice to use a mnemonic in the label. This requires an underscore inserted into the label (e.g. “_Cancel”). GTK+ parses the underscore and converts it into an underline beneath the following character, which the user can then access as a shortcut to the function.


By default, the CheckButton will be in the inactive (unchecked) state. To set the state the following can be used:


The active parameter should be set to either True which sets the CheckButton to ticked, or False which is unticked.

To retrieve the state of the CheckButton:


In some cases, the CheckButton may be set to an inconsistent state, which is used to indicate the status of other CheckButton widgets. For example, three CheckButton’s may be a mix of checked and unchecked, which leaves the fourth set as inconsistent. This can be set programatically with:


To retrieve whether a CheckButton is set as inconsistent use:


If the CheckButton is in an inconsistent state, True will be returned.


The commonly used signals of a CheckButton are:

"toggled" (checkbutton)

A "toggled" signal emits from the CheckButton when the mode is changed to active or inactive.


Below is an example of a CheckButton:

#!/usr/bin/env python3

from gi.repository import Gtk

class CheckButton(Gtk.Window):
    def __init__(self):
        self.connect("destroy", Gtk.main_quit)

        checkbutton = Gtk.CheckButton(label="CheckButton")
        checkbutton.connect("toggled", self.on_check_button_toggled)

    def on_check_button_toggled(self, checkbutton):
        if checkbutton.get_active():
            print("CheckButton toggled on!")
            print("CheckButton toggled off!")

window = CheckButton()


Download: CheckButton