PyQt - QCheckBox Widget

The QCheckBox widget is a user interface element that allows users to toggle between two states: checked and unchecked. It is commonly used in forms, preference settings, and any scenario where binary choices are presented to the user.

A rectangular box before the text label appears when a QCheckBox object is added to the parent window. Just as QRadioButton, it is also a selectable button. Its common use is in a scenario when the user is asked to choose one or more of the available options.

Unlike Radio buttons, check boxes are not mutually exclusive by default. In order to restrict the choice to one of the available items, the check boxes must be added to QButtonGroup.

Basic Properties of QCheckBox Widget

• Text − Text displayed next to the checkbox.
• Checked State − Initial state of the checkbox (checked or unchecked).
• Tristate − Allows for an additional state, typically used for "indeterminate" status.
• Enabled − Determines if the checkbox is interactive or not.

Methods Used in QCheckBox Widget

The following table lists commonly used QCheckBox class methods −

Each time a checkbox is either checked or cleared, the object emits stateChanged() signal.

Example 1: Basic Checkbox

In this example, we create a simple window with a checkbox labeled as "Enable Feature". The checkbox is initially checked (setChecked(True)). When the checkbox state changes, it calls the checkbox_state_changed method which prints whether the feature is enabled or disabled.

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QCheckBox

class MainWindow(QMainWindow):
   def __init__(self):
      super().__init__()

      checkbox = QCheckBox('Enable Feature', self)
      checkbox.setChecked(True)
      checkbox.stateChanged.connect(self.checkbox_state_changed)

      self.setCentralWidget(checkbox)

   def checkbox_state_changed(self, state):
      if state == 2:
         print("Feature enabled!")
      else:
         print("Feature disabled!")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Output

The above code produces the following output −

Example 2: Dynamic Checkbox Creation

Here, we dynamically create five checkboxes labeled "Option 0" to "Option 4" using a QVBoxLayout. Each checkbox is connected to the checkbox_state_changed method that prints whether the checkbox is checked or unchecked when its state changes.

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QCheckBox, QWidget

class MainWindow(QMainWindow):
   def __init__(self):
      super().__init__()

      central_widget = QWidget()
      layout = QVBoxLayout()

      for i in range(5):
         checkbox = QCheckBox(f'Option {i}', self)
         layout.addWidget(checkbox)
         checkbox.stateChanged.connect(self.checkbox_state_changed)

      central_widget.setLayout(layout)
      self.setCentralWidget(central_widget)

   def checkbox_state_changed(self, state):
      checkbox = self.sender()
      print(f"{checkbox.text()} is {'checked' if state == 2 else 'unchecked'}")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Output

On execution of above code, we get the following result −