PyQt QCheckBox

Summary: in this tutorial, you’ll learn how to use the PyQt QCheckBox class to create a checkbox widget.

Introduction to the PyQt QCheckBox widget

The QCheckBox class allows you to create a checkbox widget, which can be switched on or off. To create a checkbox using the QCheckBox class, you follow these steps:

First, import the QCheckBox class:

from PyQt6.QtWidgets import QCheckBoxCode language: JavaScript (javascript)

Second, create a new instance of the QCheckBox class:

checkbox = QCheckBox(text)Code language: Python (python)

The following program shows a window that has a checkbox:

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QCheckBox, QGridLayout
from PyQt6.QtCore import Qt


class MainWindow(QWidget):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.setWindowTitle('PyQt QCheckBox')
        self.setGeometry(100, 100, 320, 210)

        # create a grid layout
        layout = QGridLayout()
        self.setLayout(layout)

        # create a checkbox
        checkbox = QCheckBox('I agree', self)

        layout.addWidget(checkbox, 0, 0, Qt.AlignmentFlag.AlignCenter)

        # show the window
        self.show()


if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = MainWindow()
    sys.exit(app.exec())Code language: Python (python)

Note that the program uses the QGridLayout to place the check box on the window.

Output:

The stateChanged signal

A checkbox emits the stateChanged signal whenever you check or uncheck it.

If you want to do something when the checkbox is checked or unchecked, you can connect a slot to the stateChanged signal. For example:

checkbox = QCheckBox('I agree', self)
checkbox.stateChanged.connect(self.on_checkbox_changed)Code language: Python (python)

The stateChanged signal sends a value that indicates whether the button is checked or unchecked. To check the state of a QCheckBox, you create a Qt.CheckState instance:

state = Qt.CheckState(value)Code language: Python (python)

And compare it with one of three values:

Note that the Qt.CheckState.PartiallyChecked is used for a tristate checkbox that will be covered shortly.

For example:

def on_checkbox_changed(self, value):
    state = Qt.CheckState(value)
    if state == Qt.CheckState.Checked:
        print('Checked')
    elif state == Qt.CheckState.Unchecked:
        print('Unchecked')Code language: Python (python)

Also, you can use the isChecked() method to check if a checkbox is checked.

The following shows a complete program that displays a message in the console when a checkbox is checked or unchecked:

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QCheckBox, QGridLayout
from PyQt6.QtCore import Qt


class MainWindow(QWidget):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.setWindowTitle('PyQt QCheckBox')
        self.setGeometry(100, 100, 320, 210)

        # create a grid layout
        layout = QGridLayout()
        self.setLayout(layout)

        # create a checkbox
        checkbox = QCheckBox('I agree', self)
        checkbox.stateChanged.connect(self.on_checkbox_changed)

        layout.addWidget(checkbox, 0, 0, Qt.AlignmentFlag.AlignCenter)

        # show the window
        self.show()

    def on_checkbox_changed(self, value):
        state = Qt.CheckState(value)
        if state == Qt.CheckState.Checked:
            print('Checked')
        elif state == Qt.CheckState.Unchecked:
            print('Unchecked')


if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = MainWindow()
    sys.exit(app.exec())Code language: Python (python)

Setting checked or unchecked of PyQt QCheckBox programmatically

The QCheckBox class has the setChecked() method that allows you to check or uncheck a checkbox programmatically.

If you pass True to the setChecked() method, the checkbox will be checked. However, if you pass False to the setCheck() method, the checkbox will be unchecked.

Also, you can use the setCheckState() method of the QCheckBox class to set the state of the checkbox. The setCheckState() method accepts one of three state values of the Qt.CheckState enum.

The following program illustrates how to use the setChecked() method to check and uncheck a checkbox:

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QCheckBox, QPushButton, QGridLayout
from PyQt6.QtCore import Qt


class MainWindow(QWidget):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.setWindowTitle('PyQt QCheckBox')
        self.setGeometry(100, 100, 320, 210)

        # create a grid layout
        layout = QGridLayout()
        self.setLayout(layout)

        # create a checkbox
        self.checkbox = QCheckBox('I agree', self)

        check_button = QPushButton('Check', self)
        check_button.clicked.connect(self.check)

        uncheck_button = QPushButton('Uncheck', self)
        uncheck_button.clicked.connect(self.uncheck)

        layout.addWidget(self.checkbox, 0, 0, 0, 2,
                         Qt.AlignmentFlag.AlignCenter)
        layout.addWidget(check_button, 1, 0)
        layout.addWidget(uncheck_button, 1, 1)

        # show the window
        self.show()

    def check(self):
        self.checkbox.setChecked(True)

    def uncheck(self):
        self.checkbox.setChecked(False)


if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = MainWindow()
    sys.exit(app.exec())Code language: Python (python)

Output:

How it works.

First, create a checkbox and add it to the attribute of the class:

self.checkbox = QCheckBox('I agree', self)Code language: Python (python)

By making the checkbox an attribute of the class, we can reference it in other methods within the same class.

Second, create two QPushButton widgets and connect each of them to the check() and uncheck() methods:

check_button = QPushButton('Check', self)
check_button.clicked.connect(self.check)

uncheck_button = QPushButton('Uncheck', self)
uncheck_button.clicked.connect(self.uncheck)Code language: Python (python)

Third, call the setChecked() method with True to check the checkbox in the check() method:

def check(self):
    self.checkbox.setChecked(True)Code language: Python (python)

Finally, call the setChecked() method with False to uncheck the checkbox in the uncheck() method:

def uncheck(self):
    self.checkbox.setChecked(False)Code language: Python (python)

Creating a tristate checkbox

Besides checked and unchecked, a QCheckBox supports the third state that indicates “no change”. In this case, a checkbox has three states:

• Checked
• Unchecked
• Partially checked

In practice, you use a tristate checkbox to give the user the option of neither checking nor unchecking the checkbox.

To create a tristate checkbox, you use the setTristate() to True:

checkbox.setTristate(True)Code language: Python (python)

The following program shows a tristate checkbox:

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QCheckBox,  QGridLayout
from PyQt6.QtCore import Qt


class MainWindow(QWidget):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.setWindowTitle('PyQt QCheckBox')
        self.setGeometry(100, 100, 320, 210)

        # create a grid layout
        layout = QGridLayout()
        self.setLayout(layout)

        # create a tristate checkbox
        self.checkbox = QCheckBox('A Tristate Checkbox', self)
        self.checkbox.setTristate(True)

        layout.addWidget(self.checkbox, 0, 0, Qt.AlignmentFlag.AlignCenter)

        # show the window
        self.show()


if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = MainWindow()
    sys.exit(app.exec())Code language: Python (python)

Output:

Summary

• Use the QCheckbox class to create a checkbox widget.
• The stateChanged signal is emitted when the checkbox is checked or unchecked.
• Use the setChecked() or setState() method to check or uncheck a checkbox programmatically.
• Use setTristate() method to create a tristate checkbox.