Tutorial on PyQt6 QCheckBox widget

The QCheckBox widget in PyQt6 is used to create checkable options that the user can toggle on or off.

It supports multiple states (checked, unchecked, or partially checked) and is commonly used in forms, settings, and interactive applications where users can select one or more options.

In this tutorial, we’ll cover:

1. Basics of QCheckBox

A QCheckBox can be created by instantiating the class and optionally setting its label text.

Example: Basic QCheckBox Setup

from PyQt6.QtWidgets import QApplication, QMainWindow, QCheckBox

def main():
    app = QApplication([])
    window = QMainWindow()
    window.setWindowTitle("Basic QCheckBox Example")
    window.setGeometry(100, 100, 300, 200)

    checkbox = QCheckBox("Option 1", window)
    checkbox.setGeometry(50, 50, 150, 30)

    window.show()
    app.exec()

if __name__ == "__main__":
    main()

Output:

• A window with a single checkbox labeled “Option 1”.

2. Connecting Signals to Actions

The stateChanged signal is emitted whenever the checkbox state changes. You can connect this signal to a custom function.

Example: Handling State Changes

from PyQt6.QtWidgets import QApplication, QMainWindow, QCheckBox

def on_state_changed(state):
    print(f"Checkbox state changed to: {state}")

def main():
    app = QApplication([])
    window = QMainWindow()
    window.setWindowTitle("State Changed Example")
    window.setGeometry(100, 100, 300, 200)

    checkbox = QCheckBox("Enable Feature", window)
    checkbox.setGeometry(50, 50, 150, 30)
    checkbox.stateChanged.connect(on_state_changed)

    window.show()
    app.exec()

if __name__ == "__main__":
    main()

Output:

• Prints the checkbox state (0 for unchecked, 2 for checked) to the console when toggled.

3. Managing and Retrieving Checkbox States

You can programmatically check or uncheck a checkbox and retrieve its state using:

• isChecked(): Returns True if the checkbox is checked.
• setChecked(True/False): Sets the checkbox state.

Example: Checking and Setting State

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

def check_state():
    if checkbox.isChecked():
        print("Checkbox is checked!")
    else:
        print("Checkbox is unchecked!")

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("CheckBox State Example")
window.setGeometry(100, 100, 300, 200)

checkbox = QCheckBox("Accept Terms", window)
checkbox.setGeometry(50, 50, 150, 30)
checkbox.setChecked(True)  # Set the initial state to checked

button = QPushButton("Check State", window)
button.setGeometry(50, 100, 100, 30)
button.clicked.connect(check_state)

window.show()
app.exec()

Output:

• Clicking “Check State” prints the checkbox state to the console.

4. Creating Tri-State Checkboxes

A tri-state checkbox can have three states:

1. Checked
2. Unchecked
3. Partially checked (indeterminate)

Enable tri-state mode using setTristate(True).

Example: Tri-State Checkbox

from PyQt6.QtWidgets import QApplication, QMainWindow, QCheckBox

def on_state_changed(state):
    if state == 0:
        print("Unchecked")
    elif state == 1:
        print("Partially Checked")
    elif state == 2:
        print("Checked")

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Tri-State CheckBox Example")
window.setGeometry(100, 100, 300, 200)

checkbox = QCheckBox("Select All", window)
checkbox.setGeometry(50, 50, 150, 30)
checkbox.setTristate(True)
checkbox.stateChanged.connect(on_state_changed)

window.show()
app.exec()

Output:

• The checkbox toggles between unchecked, partially checked, and checked states.

5. Grouping Checkboxes

While checkboxes are independent by default, you can group them logically by placing them in a container (e.g., a QGroupBox or QWidget).

Example: Multiple Checkboxes

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

def show_selected():
    selected_options = []
    if option1.isChecked():
        selected_options.append("Option 1")
    if option2.isChecked():
        selected_options.append("Option 2")
    if option3.isChecked():
        selected_options.append("Option 3")
    label.setText(f"Selected: {', '.join(selected_options)}")

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Grouped CheckBoxes")
window.setGeometry(100, 100, 300, 200)

option1 = QCheckBox("Option 1", window)
option1.setGeometry(50, 50, 150, 30)

option2 = QCheckBox("Option 2", window)
option2.setGeometry(50, 80, 150, 30)

option3 = QCheckBox("Option 3", window)
option3.setGeometry(50, 110, 150, 30)

label = QLabel("Selected: None", window)
label.setGeometry(50, 140, 200, 30)

option1.stateChanged.connect(show_selected)
option2.stateChanged.connect(show_selected)
option3.stateChanged.connect(show_selected)

window.show()
app.exec()

Output:

• Dynamically displays selected options in the label.

6. Styling Checkboxes with CSS

You can customize the appearance of checkboxes using setStyleSheet().

Example: Custom Style

checkbox.setStyleSheet("""
    QCheckBox {
        font-size: 14px;
        color: darkgreen;
    }
    QCheckBox::indicator {
        width: 20px;
        height: 20px;
    }
    QCheckBox::indicator:checked {
        background-color: lightgreen;
        border: 2px solid green;
    }
    QCheckBox::indicator:unchecked {
        background-color: lightpink;
        border: 2px solid red;
    }
""")

7. Practical Examples

Example 1: Newsletter Preferences

from PyQt6.QtWidgets import QApplication, QMainWindow, QCheckBox, QPushButton, QLabel

def save_preferences():
    preferences = []
    if daily.isChecked():
        preferences.append("Daily Newsletter")
    if weekly.isChecked():
        preferences.append("Weekly Newsletter")
    if promotions.isChecked():
        preferences.append("Promotional Offers")
    label.setText(f"Preferences: {', '.join(preferences)}")

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Newsletter Preferences")
window.setGeometry(100, 100, 300, 250)

daily = QCheckBox("Daily Newsletter", window)
daily.setGeometry(50, 50, 200, 30)

weekly = QCheckBox("Weekly Newsletter", window)
weekly.setGeometry(50, 80, 200, 30)

promotions = QCheckBox("Promotional Offers", window)
promotions.setGeometry(50, 110, 200, 30)

button = QPushButton("Save", window)
button.setGeometry(50, 150, 100, 30)
button.clicked.connect(save_preferences)

label = QLabel("", window)
label.setGeometry(50, 190, 250, 30)

window.show()
app.exec()

Output:

• Allows the user to select newsletter preferences and saves the choices.

Example 2: Select All/Deselect All

from PyQt6.QtWidgets import QApplication, QMainWindow, QCheckBox

def toggle_all(state):
    check1.setChecked(state)
    check2.setChecked(state)
    check3.setChecked(state)

def on_select_all_changed():
    state = select_all.isChecked()
    toggle_all(state)

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Select All Example")
window.setGeometry(100, 100, 300, 200)

select_all = QCheckBox("Select All", window)
select_all.setGeometry(50, 50, 150, 30)
select_all.stateChanged.connect(on_select_all_changed)

check1 = QCheckBox("Option 1", window)
check1.setGeometry(50, 80, 150, 30)

check2 = QCheckBox("Option 2", window)
check2.setGeometry(50, 110, 150, 30)

check3 = QCheckBox("Option 3", window)
check3.setGeometry(50, 140, 150, 30)

window.show()
app.exec()

Output:

• Toggling “Select All” checks or unchecks all options.

Summary

In this tutorial, we covered:

1. Basics of QCheckBox: Creating and configuring checkboxes.
2. Signals: Handling stateChanged events for interactivity.
3. State Management: Checking and setting checkbox states.
4. Tri-State Checkboxes: Using setTristate for partial selection.
5. Grouping Checkboxes: Managing multiple related checkboxes.
6. Styling: Customizing checkboxes with CSS.
7. Practical Examples: Building newsletter preferences and “Select All” functionality.

The QCheckBox widget is versatile and an essential tool for creating user-friendly interfaces in PyQt6 applications. Mastering its features will help you create highly interactive and professional GUIs.