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.