PyQt QCheckBox

last modified July 9, 2020

PyQt QCheckBox tutorial shows how to work with QCheckBox widget.

PyQt QCheckBox

QCheckBox is a widget that has two states: on and off. It is a box with a label. Checkboxes are typically used to represent features in an application that can be enabled or disabled.

To create exclusive check boxes, we can use the QButtonGroup. With setTristate function, we can change the QCheckBox box to have three states. This can be used in situations where we want to have an additional neutral option.

The stateChanged signal is emitted whenever a checkbox is checked or cleared.

QCheckBox example

The following example uses a QCheckBox to toggle the window title.

#!/usr/bin/python


from PyQt5.QtWidgets import QWidget, QCheckBox, QHBoxLayout, QApplication
from PyQt5.QtCore import Qt
import sys


class Example(QWidget):

    def __init__(self):
        super().__init__()

        self.initUI()

    def initUI(self):

        hbox = QHBoxLayout()

        cb = QCheckBox('Show title', self)
        cb.toggle()
        cb.stateChanged.connect(self.changeTitle)

        hbox.addWidget(cb)

        self.setLayout(hbox)

        self.setGeometry(300, 300, 350, 250)
        self.setWindowTitle('QCheckBox')
        self.show()

    def changeTitle(self, state):

        if state == Qt.Checked:
            self.setWindowTitle('QCheckBox')
        else:
            self.setWindowTitle(' ')


def main():
    app = QApplication(sys.argv)
    ex = Example()
    sys.exit(app.exec_())


if __name__ == '__main__':
    main()

In the example, we create a checkbox that toggles the window title.

cb = QCheckBox('Show title', self)

This is a QCheckBox constructor.

cb.toggle()

Since the title is visible at the start, we check the checkbox with toggle.

cb.stateChanged.connect(self.changeTitle)

We connect the user defined changeTitle function to the stateChanged signal. The changeTitle function toggles the window title.

def changeTitle(self, state):

    if state == Qt.Checked:
        self.setWindowTitle('QCheckBox')
    else:
        self.setWindowTitle(' ')

The state of the widget is passed to the changeTitle function in the state variable. If the widget is checked, we set a title of the window. Otherwise, we set an empty string to the titlebar.

Three-state QCheckBox

The next example demonstrates the three-state QCheckBox.

#!/usr/bin/python


from PyQt5.QtWidgets import (QWidget, QCheckBox, QApplication, 
                             QHBoxLayout, QLabel)
from PyQt5.QtCore import Qt
import sys


class Example(QWidget):

    def __init__(self):
        super().__init__()

        self.initUI()

    def initUI(self):

        hbox = QHBoxLayout()

        checkBox = QCheckBox('Increase taxes', self)
        checkBox.setTristate(True)
        hbox.addWidget(checkBox)

        checkBox.stateChanged.connect(self.changeTitle)

        self.label = QLabel('Negative viewpoint')
        hbox.addSpacing(20)
        hbox.addWidget(self.label)

        self.setLayout(hbox)

        self.move(300, 300)
        self.setWindowTitle('QCheckBox')
        self.show()

    def changeTitle(self, state):
        
        if state == Qt.Checked:
            self.label.setText('Positive viewpoint')
        elif state == Qt.Unchecked:
            self.label.setText('Negative viewpoint')
        else:
            self.label.setText('Neutral viewpoint')


def main():
    
    app = QApplication(sys.argv)
    ex = Example()
    sys.exit(app.exec_())


if __name__ == '__main__':
    main()

We have a QCheckBox with 'Increase taxes' label. By clicking on the checkbox, we can show a positive, negative, or neutral viewpoint.

checkBox = QCheckBox('Increase taxes', self)
checkBox.setTristate(True)

We create a QCheckBox and make it have three states with setTristate.

Exclusive QCheckBox

With the help of the QButtonGroup, we can make checkboxes exclusive; that is, only one of the boxes can be checked at a time.

#!/usr/bin/python


from PyQt5.QtWidgets import (QWidget, QCheckBox, QApplication, 
                             QHBoxLayout, QVBoxLayout, QLabel, QButtonGroup)
from PyQt5.QtCore import Qt
import sys


class Example(QWidget):

    def __init__(self):
        super().__init__()

        self.initUI()

    def initUI(self):

        vbox = QVBoxLayout()
        hbox = QHBoxLayout()

        checkBox1 = QCheckBox('Small', self)
        checkBox2 = QCheckBox('Medium', self)
        checkBox3 = QCheckBox('Large', self)

        group = QButtonGroup(self)
        group.addButton(checkBox1)
        group.addButton(checkBox2)
        group.addButton(checkBox3)

        hbox.addWidget(checkBox1)
        hbox.addWidget(checkBox2)
        hbox.addWidget(checkBox3)

        group.buttonClicked.connect(self.changeText)

        self.label = QLabel('...', self)

        vbox.addLayout(hbox)
        vbox.addSpacing(30)
        vbox.addWidget(self.label)

        self.setLayout(vbox)

        self.move(300, 300)
        self.setWindowTitle('QCheckBox')
        self.show()

    def changeText(self, btn):

        self.label.setText(btn.text())



def main():
    app = QApplication(sys.argv)
    ex = Example()
    sys.exit(app.exec_())


if __name__ == '__main__':
    main()

We have three checkboxes representing small, medium, and large sizes.

group = QButtonGroup(self)
group.addButton(checkBox1)
group.addButton(checkBox2)
group.addButton(checkBox3)

We place the three checkboxes into the QButtonGroup with addButton.

group.buttonClicked.connect(self.changeText)

We react to the buttonClicked signal.

def changeText(self, btn):

    self.label.setText(btn.text())

Upon clicking on any of the checkboxes, we get its text and update the label.

In this tutorial, we have presented the PyQt QCheckBox widget.

List all PyQt tutorials.