Tutorial on PyQt6 QRadioButton widget

QRadioButton in PyQt6 is a widget that allows users to select a single option from a group of mutually exclusive options.

It is commonly used in forms and settings where you need to present a list of options where only one can be selected.

In this tutorial, we’ll cover:

1. Basics of QRadioButton

A QRadioButton is created by instantiating the class and optionally setting its label text. By default, radio buttons operate independently.

Example: Basic QRadioButton Setup

from PyQt6.QtWidgets import QApplication, QMainWindow, QRadioButton

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

    radio_button = QRadioButton("Option 1", window)
    radio_button.setGeometry(50, 50, 100, 30)

    window.show()
    app.exec()

if __name__ == "__main__":
    main()

Output:

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

2. Grouping Radio Buttons

To make radio buttons mutually exclusive, they must be grouped together. This is achieved by placing them in a QButtonGroup or within the same parent container (e.g., QWidget or QGroupBox).

Example: Grouping Radio Buttons with a QButtonGroup

from PyQt6.QtWidgets import QApplication, QMainWindow, QRadioButton, QButtonGroup

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

    radio_button1 = QRadioButton("Option 1", window)
    radio_button1.setGeometry(50, 50, 100, 30)

    radio_button2 = QRadioButton("Option 2", window)
    radio_button2.setGeometry(50, 90, 100, 30)

    radio_button3 = QRadioButton("Option 3", window)
    radio_button3.setGeometry(50, 130, 100, 30)

    # Group the radio buttons
    button_group = QButtonGroup(window)
    button_group.addButton(radio_button1)
    button_group.addButton(radio_button2)
    button_group.addButton(radio_button3)

    window.show()
    app.exec()

if __name__ == "__main__":
    main()

Output:

• A group of three mutually exclusive radio buttons.

3. Connecting Signals to Actions

The toggled signal is emitted whenever the state of a QRadioButton changes. You can connect it to a custom function to define its behavior.

Example: Handling Toggle Events

from PyQt6.QtWidgets import QApplication, QMainWindow, QRadioButton

def on_radio_button_toggled(is_checked):
    if is_checked:
        print("Option selected!")

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

    radio_button = QRadioButton("Click Me", window)
    radio_button.setGeometry(50, 50, 100, 30)
    radio_button.toggled.connect(on_radio_button_toggled)

    window.show()
    app.exec()

if __name__ == "__main__":
    main()

Output:

• Prints Option selected! to the console when the button is selected.

4. Checking and Setting the State of a Radio Button

You can programmatically check or change the state of a radio button using the following methods:

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

Example: Checking and Setting State

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

def check_button_state():
    if radio_button1.isChecked():
        print("Option 1 is selected!")
    elif radio_button2.isChecked():
        print("Option 2 is selected!")

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

radio_button1 = QRadioButton("Option 1", window)
radio_button1.setGeometry(50, 50, 100, 30)
radio_button1.setChecked(True)  # Default selection

radio_button2 = QRadioButton("Option 2", window)
radio_button2.setGeometry(50, 90, 100, 30)

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

window.show()
app.exec()

Output:

• Clicking “Check State” prints the selected option to the console.

5. Styling QRadioButton with CSS

You can customize the appearance of QRadioButton using the setStyleSheet() method.

Example: Custom Style for Radio Buttons

radio_button.setStyleSheet("""
    QRadioButton {
        font-size: 14px;
        color: darkblue;
    }
    QRadioButton::indicator {
        width: 20px;
        height: 20px;
    }
    QRadioButton::indicator:checked {
        background-color: lightblue;
        border: 2px solid darkblue;
        border-radius: 10px;
    }
""")

6. Practical Examples

Example 1: Pizza Topping Selector

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

def show_selected_topping():
    if pepperoni_button.isChecked():
        label.setText("You selected: Pepperoni")
    elif mushroom_button.isChecked():
        label.setText("You selected: Mushroom")
    elif cheese_button.isChecked():
        label.setText("You selected: Cheese")

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Pizza Topping Selector")
window.setGeometry(100, 100, 300, 250)

pepperoni_button = QRadioButton("Pepperoni", window)
pepperoni_button.setGeometry(50, 50, 150, 30)

mushroom_button = QRadioButton("Mushroom", window)
mushroom_button.setGeometry(50, 90, 150, 30)

cheese_button = QRadioButton("Cheese", window)
cheese_button.setGeometry(50, 130, 150, 30)
cheese_button.setChecked(True)

button = QPushButton("Show Selection", window)
button.setGeometry(50, 170, 150, 30)
button.clicked.connect(show_selected_topping)

label = QLabel("", window)
label.setGeometry(50, 210, 200, 30)

window.show()
app.exec()

Output:

• Selecting a topping and clicking “Show Selection” displays the selected topping in the label.

Example 2: Gender Selection Form

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

def submit_form():
    if male_button.isChecked():
        label.setText("You selected: Male")
    elif female_button.isChecked():
        label.setText("You selected: Female")
    elif other_button.isChecked():
        label.setText("You selected: Other")

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Gender Selection Form")
window.setGeometry(100, 100, 300, 200)

male_button = QRadioButton("Male", window)
male_button.setGeometry(50, 50, 100, 30)
male_button.setChecked(True)

female_button = QRadioButton("Female", window)
female_button.setGeometry(50, 90, 100, 30)

other_button = QRadioButton("Other", window)
other_button.setGeometry(50, 130, 100, 30)

submit_button = QPushButton("Submit", window)
submit_button.setGeometry(150, 50, 100, 30)
submit_button.clicked.connect(submit_form)

label = QLabel("", window)
label.setGeometry(50, 170, 200, 30)

window.show()
app.exec()

Output:

• Selecting a gender and clicking “Submit” displays the selected gender in the label.

Summary

In this tutorial, we covered:

1. Basics of QRadioButton: Creating and configuring radio buttons.
2. Grouping: Making radio buttons mutually exclusive with QButtonGroup.
3. Signals: Handling toggled events to execute custom actions.
4. State Management: Programmatically checking and setting the state.
5. Styling: Customizing appearance with CSS.
6. Practical Examples: Building a pizza topping selector and gender selection form.

QRadioButton is an essential widget for creating forms and interactive GUIs in PyQt6, and mastering it will greatly enhance your ability to build feature-rich applications.