TUTORIAL

Tutoriel PyQt5 - Bouton radio

Ce tutoriel présente le widget PyQt5 QRadioButton avec des exemples : créer des boutons radio, connecter un slot au signal toggled, présélectionner une option et conserver des groupes indépendants.

Sur cette page

Un QRadioButton permet à l’utilisateur de choisir exactement une option dans un ensemble, ce qui en fait le widget approprié lorsque plusieurs choix sont mutuellement exclusifs. Pour des choix activé/désactivé indépendants, utilisez plutôt un QCheckBox, car chaque case à cocher conserve son propre état. Chaque QRadioButton combine un indicateur rond et une étiquette de texte, et les boutons radio qui partagent le même widget parent forment automatiquement un groupe exclusif : en sélectionner un désélectionne les autres.

Créer des widgets QRadioButton

Transmettez le texte visible de l’option au constructeur QRadioButton et ajoutez les boutons à une mise en page comme n’importe quel autre widget. Le script suivant crée une fenêtre qui demande dans quelle ville vit l’utilisateur, propose New York et Houston, et réserve un second QLabel pour la réponse. Il requiert PyQt5 et un affichage graphique ; la vérification importlib.util.find_spec permet au fichier de se terminer proprement lorsque PyQt5 n’est pas installé, tandis que sur un bureau il ouvre la fenêtre illustrée ci-dessous.

Le code de l’exemple ainsi que les libellés affichés dans la fenêtre restent en anglais.

import importlib.util
import sys

if importlib.util.find_spec("PyQt5") is None:
    sys.exit(0)  # PyQt5 is required for the GUI below

from PyQt5.QtWidgets import (
    QApplication,
    QLabel,
    QRadioButton,
    QVBoxLayout,
    QWidget,
)


class basicRadiobuttonExample(QWidget):
    def __init__(self):
        super().__init__()

        self.init_ui()

    def init_ui(self):
        self.label = QLabel("Which city do you live in?")
        self.rbtn1 = QRadioButton("New York")
        self.rbtn2 = QRadioButton("Houston")
        self.label2 = QLabel("")

        self.rbtn1.toggled.connect(self.onClicked)
        self.rbtn2.toggled.connect(self.onClicked)

        layout = QVBoxLayout()
        layout.addWidget(self.label)
        layout.addWidget(self.rbtn1)
        layout.addWidget(self.rbtn2)
        layout.addWidget(self.label2)

        self.setGeometry(200, 200, 300, 150)

        self.setLayout(layout)
        self.setWindowTitle("PyQt5 Radio Button Example")

        self.show()

    def onClicked(self):
        radioBtn = self.sender()
        if radioBtn.isChecked():
            self.label2.setText("You live in " + radioBtn.text())


if __name__ == "__main__":
    app = QApplication(sys.argv)
    ex = basicRadiobuttonExample()
    sys.exit(app.exec_())

Fenêtre PyQt5 affichée, intitulée « PyQt5 Radio Button Example », montrant la question « Which city do you live in? », les boutons radio New York et Houston non cochés et une ligne de résultat vide

La chaîne passée au constructeur ("New York", "Houston") devient le texte affiché à côté de chaque indicateur rond. self.label pose la question, self.label2 commence comme une étiquette vide qui indiquera ensuite la sélection, et QVBoxLayout empile les widgets verticalement dans l’ordre où ils sont ajoutés. setGeometry(200, 200, 300, 150) positionne et dimensionne la fenêtre, et setWindowTitle() définit le titre de la fenêtre.

Répondre au signal toggled

Un QRadioButton émet le signal toggled chaque fois que son état coché change dans un sens ou dans l’autre : une fois avec un état coché lorsqu’il est sélectionné, et une fois avec un état décoché pour le bouton qui perd la sélection. Connecter les deux boutons au même slot — self.rbtn1.toggled.connect(self.onClicked) et self.rbtn2.toggled.connect(self.onClicked) — suffit pour suivre tout le groupe.

Comme toggled se déclenche aussi pour le bouton désélectionné, le slot filtre avec isChecked() afin que seul le bouton nouvellement sélectionné mette à jour le résultat. Dans onClicked, self.sender() renvoie le widget qui a émis le signal, text() lit son étiquette d’option visible, et self.label2.setText("You live in " + radioBtn.text()) écrit la réponse ; la chaîne affichée reste en anglais dans l’exemple.

Le signal toggled transporte aussi le nouvel état coché sous forme de booléen, donc un slot déclaré comme def onClicked(self, checked) peut utiliser cette valeur au lieu d’appeler isChecked(). Vérifier isChecked() sur l’émetteur est le motif le plus simple ici, car il indique clairement quel bouton a produit le texte.

Interaction dans l’exemple de base : la sélection du bouton radio Houston le coche, désélectionne New York et met à jour l’étiquette de résultat avec « You live in Houston »

Définir une sélection par défaut avec setChecked()

Les nouvelles instances de QRadioButton démarrent non cochées, donc la fenêtre s’ouvre sans aucune option sélectionnée. Pour présélectionner une option au démarrage de l’application, appelez setChecked() sur ce bouton : self.rbtn1.setChecked(True).

Modifier l’état coché émet toggled exactement comme un clic de l’utilisateur. Si vous voulez que la présélection mette aussi à jour les widgets dépendants comme l’étiquette de résultat, appelez setChecked(True) après avoir connecté le signal ; appelez-la avant la connexion si la sélection initiale doit rester silencieuse.

Créer des groupes indépendants avec QButtonGroup

Tous les widgets QRadioButton ayant le même parent appartiennent à un groupe implicite, donc un seul d’entre eux peut être coché à la fois — même lorsque leurs signaux toggled sont connectés à des slots différents. Lorsqu’une fenêtre pose plusieurs questions indépendantes, encapsulez chaque ensemble d’options dans un QButtonGroup de QtWidgets et enregistrez les boutons avec addButton() ; chaque groupe autorise alors un bouton coché indépendamment des autres. L’exemple suivant demande à la fois une ville et un État et nécessite le même environnement de bureau PyQt5 que le premier script :

Le code de l’exemple ainsi que les libellés affichés dans la fenêtre restent en anglais.

import importlib.util
import sys

if importlib.util.find_spec("PyQt5") is None:
    sys.exit(0)  # PyQt5 is required for the GUI below

from PyQt5.QtWidgets import (
    QApplication,
    QButtonGroup,
    QLabel,
    QRadioButton,
    QVBoxLayout,
    QWidget,
)


class basicRadiobuttonExample(QWidget):
    def __init__(self):
        super().__init__()

        self.init_ui()

    def init_ui(self):
        self.label = QLabel("Which city do you live in?")
        self.rbtn1 = QRadioButton("New York")
        self.rbtn2 = QRadioButton("Houston")
        self.label2 = QLabel("")

        self.label3 = QLabel("Which state do you live in?")
        self.rbtn3 = QRadioButton("New York")
        self.rbtn4 = QRadioButton("Texas")
        self.label4 = QLabel("")

        self.btngroup1 = QButtonGroup()
        self.btngroup2 = QButtonGroup()

        self.btngroup1.addButton(self.rbtn1)
        self.btngroup1.addButton(self.rbtn2)
        self.btngroup2.addButton(self.rbtn3)
        self.btngroup2.addButton(self.rbtn4)

        self.rbtn1.toggled.connect(self.onClickedCity)
        self.rbtn2.toggled.connect(self.onClickedCity)

        self.rbtn3.toggled.connect(self.onClickedState)
        self.rbtn4.toggled.connect(self.onClickedState)

        layout = QVBoxLayout()
        layout.addWidget(self.label)
        layout.addWidget(self.rbtn1)
        layout.addWidget(self.rbtn2)
        layout.addWidget(self.label2)

        layout.addWidget(self.label3)
        layout.addWidget(self.rbtn3)
        layout.addWidget(self.rbtn4)
        layout.addWidget(self.label4)

        self.setGeometry(200, 200, 300, 300)

        self.setLayout(layout)
        self.setWindowTitle("PyQt5 Radio Button Example")

        self.show()

    def onClickedCity(self):
        radioBtn = self.sender()
        if radioBtn.isChecked():
            self.label2.setText("You live in " + radioBtn.text())

    def onClickedState(self):
        radioBtn = self.sender()
        if radioBtn.isChecked():
            self.label4.setText("You live in " + radioBtn.text())


if __name__ == "__main__":
    app = QApplication(sys.argv)
    ex = basicRadiobuttonExample()
    sys.exit(app.exec_())

Fenêtre PyQt5 affichée avec deux ensembles d’options indépendants : un bouton radio de ville sélectionné sous « Which city do you live in? » et un bouton radio d’État sélectionné sous « Which state do you live in? »

Le programme crée deux instances de QButtonGroup, self.btngroup1 pour les boutons de ville et self.btngroup2 pour les boutons d’État. addButton() enregistre chaque bouton radio dans son groupe — self.btngroup1.addButton(self.rbtn1) et self.btngroup1.addButton(self.rbtn2) pour la paire de villes, self.btngroup2.addButton(self.rbtn3) et self.btngroup2.addButton(self.rbtn4) pour la paire d’États. Sans les groupes, choisir Texas effacerait la sélection de ville parce que les quatre boutons partagent le même parent ; avec les groupes en place, chaque question conserve son propre bouton coché et chaque étiquette de résultat se met à jour indépendamment.

Une fenêtre graphique ne peut pas illustrer cette règle dans une sortie texte, donc le modèle Python simple suivant reproduit la même exclusivité : une sélection par groupe, et un second groupe non affecté par le premier. Exécutez cet exemple :

class RadioGroup:
    def __init__(self):
        self.buttons = []
        self.checked = None

    def add(self, label):
        self.buttons.append(label)

    def select(self, label):
        self.checked = label
        return "Selected: " + label


city = RadioGroup()
city.add("New York")
city.add("Houston")

state = RadioGroup()
state.add("New York")
state.add("Texas")

print(city.select("New York"))
print(state.select("Texas"))
print(city.select("Houston"))
print("State group still holds:", state.checked)
Selected: New York
Selected: Texas
Selected: Houston
State group still holds: Texas

QButtonGroup joue le rôle du RadioGroup du modèle : une nouvelle sélection remplace la précédente dans le même groupe, tandis que l’autre groupe conserve sa réponse.