QDialogButtonBox Class
La classe QDialogButtonBox est un widget qui affiche des boutons selon une disposition adaptée au style actuel du widget. En savoir plus...
| En-tête : | #include <QDialogButtonBox> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake : | QT += widgets |
| Hérite de : | QWidget |
Types publics
| enum | ButtonLayout { WinLayout, MacLayout, KdeLayout, GnomeLayout, AndroidLayout } |
| enum | ButtonRole { InvalidRole, AcceptRole, RejectRole, DestructiveRole, ActionRole, …, ResetRole } |
| enum | StandardButton { Ok, Open, Save, Cancel, Close, …, NoButton } |
| flags | StandardButtons |
Propriétés
- centerButtons : bool
- orientation : Qt::Orientation
- standardButtons : StandardButtons
Fonctions publiques
| QDialogButtonBox(QWidget *parent = nullptr) | |
| QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr) | |
| QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr) | |
| QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr) | |
| virtual | ~QDialogButtonBox() |
| QPushButton * | addButton(QDialogButtonBox::StandardButton button) |
| void | addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role) |
| QPushButton * | addButton(const QString &text, QDialogButtonBox::ButtonRole role) |
| QPushButton * | button(QDialogButtonBox::StandardButton which) const |
| QDialogButtonBox::ButtonRole | buttonRole(QAbstractButton *button) const |
| QList<QAbstractButton *> | buttons() const |
| bool | centerButtons() const |
| void | clear() |
| Qt::Orientation | orientation() const |
| void | removeButton(QAbstractButton *button) |
| void | setCenterButtons(bool center) |
| void | setOrientation(Qt::Orientation orientation) |
| void | setStandardButtons(QDialogButtonBox::StandardButtons buttons) |
| QDialogButtonBox::StandardButton | standardButton(QAbstractButton *button) const |
| QDialogButtonBox::StandardButtons | standardButtons() const |
Signaux
| void | accepted() |
| void | clicked(QAbstractButton *button) |
| void | helpRequested() |
| void | rejected() |
Membres publics statiques
(since 6.12) QKeySequence | standardButtonShortcut(QDialogButtonBox::StandardButton button) |
(since 6.12) QString | standardButtonText(QDialogButtonBox::StandardButton button) |
Fonctions protégées réimplémentées
| virtual void | changeEvent(QEvent *event) override |
| virtual bool | event(QEvent *event) override |
Description détaillée
Les boîtes de dialogue et les fenêtres de message présentent généralement des boutons selon une disposition conforme aux directives d'interface de la plate-forme concernée. Inévitablement, les différentes plates-formes ont des dispositions différentes pour leurs boîtes de dialogue. QDialogButtonBox permet à un développeur d'y ajouter des boutons et utilise automatiquement la disposition adaptée à l'environnement de bureau de l'utilisateur.
La plupart des boutons d’une boîte de dialogue remplissent des rôles bien définis. Parmi ces rôles, on trouve :
- Accepter ou rejeter la boîte de dialogue.
- Demander de l'aide.
- Effectuer des actions sur la boîte de dialogue elle-même (comme réinitialiser des champs ou appliquer des modifications).
Il peut également exister d’autres moyens de fermer la boîte de dialogue, qui peuvent entraîner des conséquences indésirables.
La plupart des boîtes de dialogue comportent des boutons que l'on peut presque considérer comme standard (par exemple, les boutons « OK » et « Cancel »). Il est parfois pratique de créer ces boutons de manière standard.
Il existe plusieurs façons d’utiliser QDialogButtonBox. L’une d’elles consiste à créer soi-même les boutons (ou leurs textes) et à les ajouter à la boîte de dialogue, en précisant leur rôle.
QDialogButtonBox *buttonBox = new QDialogButtonBox(Qt::Vertical);
buttonBox->addButton(findButton, QDialogButtonBox::ActionRole);
buttonBox->addButton(moreButton, QDialogButtonBox::ActionRole);Sinon, QDialogButtonBox fournit plusieurs boutons standard (par exemple, OK, Annuler, Enregistrer) que vous pouvez utiliser. Ils existent sous forme d'indicateurs, ce qui vous permet de les combiner à l'aide de l'opérateur OU dans le constructeur.
buttonBox = new QDialogButtonBox(QDialogButtonBox::Ok
| QDialogButtonBox::Cancel);
connect(buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept);
connect(buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);Vous pouvez combiner à votre guise des boutons normaux et des boutons standard.
Actuellement, les boutons sont disposés de la manière suivante lorsque la boîte à boutons est horizontale :
GnomeLayout Horizontale | Boîte de boutons disposée horizontalement GnomeLayout |
KdeLayout Horizontal | Boîte de boutons disposée horizontalement KdeLayout |
MacLayout Horizontale | Boîte de boutons disposée horizontalement MacLayout |
WinLayout Horizontale | Boîte de boutons disposée horizontalement WinLayout |
Les boutons sont disposés de la manière suivante si la zone de boutons est verticale :
| GnomeLayout | KdeLayout | MacLayout | WinLayout |
GnomeLayout Verticale | KdeLayout Verticale | MacLayout Verticale | WinLayout Verticale |
De plus, les boîtes de boutons qui ne contiennent que des boutons de type « ActionRole » ou « HelpRole » peuvent être considérées comme non modales et présentent un aspect différent sous macOS :
| horizontal non modale MacLayout | Capture d’écran d’une disposition horizontale non modale MacLayout |
| vertical sans mode MacLayout | Capture d’écran de la version non modale verticale MacLayout |
Lorsqu’un bouton est cliqué dans la boîte à boutons, le signal « clicked() » est émis pour le bouton qui a effectivement été enfoncé. Par commodité, si le bouton possède un « AcceptRole », « RejectRole » ou « HelpRole », les signaux « accepted() », « rejected() » ou « helpRequested() » sont émis respectivement.
Si vous souhaitez qu’un bouton spécifique soit défini par défaut, vous devez appeler vous-même la méthode QPushButton::setDefault() sur celui-ci. Cependant, si aucun bouton par défaut n’est défini et afin de conserver le même bouton par défaut sur toutes les plateformes lors de l’utilisation de la propriété QPushButton::autoDefault, le premier bouton de commande ayant le rôle « accept » est désigné comme bouton par défaut lorsque la QDialogButtonBox s’affiche,
Voir également QMessageBox, QPushButton et QDialog.
Documentation sur les types de membres
enum QDialogButtonBox::ButtonLayout
Cette énumération décrit la stratégie de disposition à utiliser lors de l'agencement des boutons contenus dans la boîte de boutons.
| Constante | Valeur | Description |
|---|---|---|
QDialogButtonBox::WinLayout | 0 | Utilisez une politique adaptée aux applications sous Windows. |
QDialogButtonBox::MacLayout | 1 | Utilise une politique adaptée aux applications sous macOS. |
QDialogButtonBox::KdeLayout | 2 | Utilisez une stratégie adaptée aux applications sous KDE. |
QDialogButtonBox::GnomeLayout | 3 | Utiliser une stratégie adaptée aux applications sous GNOME. |
QDialogButtonBox::AndroidLayout | 4 | Utilisez une stratégie adaptée aux applications sous Android. Cette valeur d'énumération a été ajoutée dans Qt 5.10. |
La disposition des boutons est spécifiée par le paramètre « current style ». Toutefois, sur la plateforme X11, elle peut être influencée par l'environnement de bureau.
enum QDialogButtonBox::ButtonRole
Cette énumération décrit les rôles pouvant être utilisés pour définir les boutons de la boîte à boutons. Les combinaisons de ces rôles servent d'indicateurs permettant de décrire différents aspects de leur comportement.
| Constante | Valeur | Description |
|---|---|---|
QDialogButtonBox::InvalidRole | -1 | Le bouton n'est pas valide. |
QDialogButtonBox::AcceptRole | 0 | Cliquer sur le bouton entraîne l'acceptation de la boîte de dialogue (par exemple, OK). |
QDialogButtonBox::RejectRole | 1 | Cliquer sur ce bouton entraîne le rejet de la boîte de dialogue (par exemple, « Annuler »). |
QDialogButtonBox::DestructiveRole | 2 | Cliquer sur ce bouton entraîne une modification irréversible (par exemple, pour « Annuler les modifications ») et ferme la boîte de dialogue. |
QDialogButtonBox::ActionRole | 3 | Cliquer sur ce bouton modifie les éléments contenus dans la boîte de dialogue. |
QDialogButtonBox::HelpRole | 4 | On peut cliquer sur ce bouton pour demander de l'aide. |
QDialogButtonBox::YesRole | 5 | Ce bouton correspond à un « Oui ». |
QDialogButtonBox::NoRole | 6 | Ce bouton correspond à un « Non ». |
QDialogButtonBox::ApplyRole | 8 | Ce bouton applique les modifications en cours. |
QDialogButtonBox::ResetRole | 7 | Ce bouton réinitialise les champs de la boîte de dialogue à leurs valeurs par défaut. |
Voir également StandardButton.
enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons
Ces énumérations décrivent les indicateurs associés aux boutons standard. Chaque bouton dispose d'une ButtonRole définie.
| Constante | Valeur | Description |
|---|---|---|
QDialogButtonBox::Ok | 0x00000400 | Un bouton « OK » défini avec l'AcceptRole. |
QDialogButtonBox::Open | 0x00002000 | Un bouton « Ouvrir » défini avec l'AcceptRole. |
QDialogButtonBox::Save | 0x00000800 | Un bouton « Enregistrer » défini à l'aide de l'AcceptRole. |
QDialogButtonBox::Cancel | 0x00400000 | Un bouton « Annuler » défini à l'aide de l'RejectRole. |
QDialogButtonBox::Close | 0x00200000 | Un bouton « Fermer » défini à l'aide de l'RejectRole. |
QDialogButtonBox::Discard | 0x00800000 | Un bouton « Ignorer » ou « Ne pas enregistrer », selon la plateforme, défini à l’aide de l’ DestructiveRole. |
QDialogButtonBox::Apply | 0x02000000 | Un bouton « Appliquer » défini à l’aide de la méthode ApplyRole. |
QDialogButtonBox::Reset | 0x04000000 | Un bouton « Réinitialiser » défini à l’aide de la balise ResetRole. |
QDialogButtonBox::RestoreDefaults | 0x08000000 | Un bouton « Restaurer les valeurs par défaut » défini à l’aide de la balise ResetRole. |
QDialogButtonBox::Help | 0x01000000 | Un bouton « Aide » défini à l’aide de l’ HelpRole. |
QDialogButtonBox::SaveAll | 0x00001000 | Un bouton « Tout enregistrer » défini à l’aide de l’ AcceptRole. |
QDialogButtonBox::Yes | 0x00004000 | Un bouton « Oui » défini à l'aide de l'YesRole. |
QDialogButtonBox::YesToAll | 0x00008000 | Un bouton « Oui à tout » défini à l'aide de l'YesRole. |
QDialogButtonBox::No | 0x00010000 | Un bouton « Non » défini à l'aide de l'NoRole. |
QDialogButtonBox::NoToAll | 0x00020000 | Un bouton « Non à tout » défini avec l'NoRole. |
QDialogButtonBox::Abort | 0x00040000 | Un bouton « Abandonner » défini à l'aide de la balise RejectRole. |
QDialogButtonBox::Retry | 0x00080000 | Un bouton « Réessayer » défini à l'aide de l'AcceptRole. |
QDialogButtonBox::Ignore | 0x00100000 | Un bouton « Ignorer » défini à l'aide de la méthode AcceptRole. |
QDialogButtonBox::NoButton | 0x00000000 | Un bouton non valide. |
Le type StandardButtons est un typedef pour QFlags<StandardButton>. Il stocke une combinaison OR de valeurs StandardButton.
Voir également ButtonRole et standardButtons.
Documentation sur les propriétés
centerButtons : bool
Cette propriété détermine si les boutons de la boîte de boutons sont centrés
Par défaut, cette propriété est définie sur « false ». Ce comportement convient à la plupart des types de boîtes de dialogue. Une exception notable concerne les boîtes de message sur la plupart des plateformes (par exemple Windows), où la zone des boutons est centrée horizontalement.
Fonctions d'accès :
| bool | centerButtons() const |
| void | setCenterButtons(bool center) |
Voir également QMessageBox.
orientation : Qt::Orientation
Cette propriété définit l'orientation de la boîte de boutons
Par défaut, l'orientation est horizontale (c'est-à-dire que les boutons sont disposés côte à côte). Les orientations possibles sont Qt::Horizontal et Qt::Vertical.
Fonctions d'accès :
| Qt::Orientation | orientation() const |
| void | setOrientation(Qt::Orientation orientation) |
standardButtons : StandardButtons
ensemble de boutons standard dans la boîte à boutons
Cette propriété permet de définir les boutons standard utilisés par la boîte à boutons.
Fonctions d'accès :
| QDialogButtonBox::StandardButtons | standardButtons() const |
| void | setStandardButtons(QDialogButtonBox::StandardButtons buttons) |
Voir également addButton().
Documentation sur les fonctions membres
QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)
Crée une boîte de bouton horizontale vide avec l'parent spécifiée.
Voir également orientation et addButton().
[explicit] QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr)
Crée une boîte de boutons horizontale avec l'parent fournie, contenant les boutons standard spécifiés par buttons.
Voir également orientation et addButton().
QDialogButtonBox::QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr)
Crée une boîte de boutons vide avec les paramètres orientation et parent fournis.
Voir également orientation et addButton().
QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr)
Crée une boîte de boutons avec les paramètres orientation et parent fournis, contenant les boutons standard spécifiés par buttons.
Voir également orientation et addButton().
[virtual noexcept] QDialogButtonBox::~QDialogButtonBox()
Détruit le boîtier des boutons.
[signal] void QDialogButtonBox::accepted()
Ce signal est émis lorsqu'on clique sur un bouton situé dans la zone de boutons, à condition que celui-ci ait été défini à l'aide des méthodes ` AcceptRole ` ou ` YesRole`.
Voir également rejected(), clicked() et helpRequested().
QPushButton *QDialogButtonBox::addButton(QDialogButtonBox::StandardButton button)
Ajoute un élément standard de type « button » à la boîte de boutons si cela est valide, puis renvoie un bouton-poussoir. Si l'élément « button » n'est pas valide, il n'est pas ajouté à la boîte de boutons et la fonction renvoie zéro.
Voir également removeButton() et clear().
void QDialogButtonBox::addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role)
Ajoute l'button on indiquée à la boîte de boutons avec l'role on spécifiée. Si le rôle n'est pas valide, le bouton n'est pas ajouté.
Si le bouton a déjà été ajouté, il est supprimé puis rajouté avec le nouveau rôle.
Remarque : la boîte de boutons prend possession du bouton.
Voir également removeButton() et clear().
QPushButton *QDialogButtonBox::addButton(const QString &text, QDialogButtonBox::ButtonRole role)
Crée un bouton-poussoir avec l'text fournie, l'ajoute à la boîte de boutons correspondant à l'role spécifiée, puis renvoie le bouton-poussoir correspondant. Si l'role n'est pas valide, aucun bouton n'est créé et la fonction renvoie zéro.
Voir également removeButton() et clear().
QPushButton *QDialogButtonBox::button(QDialogButtonBox::StandardButton which) const
Renvoie l'QPushButton correspondant au bouton standard which, ou nullptr si le bouton standard n'existe pas dans cette boîte de boutons.
Voir également standardButton(), standardButtons() et buttons().
QDialogButtonBox::ButtonRole QDialogButtonBox::buttonRole(QAbstractButton *button) const
Renvoie le rôle du bouton pour l'button spécifié. Cette fonction renvoie « InvalidRole » si button est « nullptr » ou n'a pas été ajouté à la boîte de boutons.
Voir également buttons() et addButton().
QList<QAbstractButton *> QDialogButtonBox::buttons() const
Renvoie une liste de tous les boutons qui ont été ajoutés à la boîte à boutons.
Voir également buttonRole(), addButton() et removeButton().
[override virtual protected] void QDialogButtonBox::changeEvent(QEvent *event)
Réimplémente : QWidget::changeEvent(QEvent *event).
void QDialogButtonBox::clear()
Vide la zone des boutons, en supprimant tous les boutons qu'elle contient.
Voir également removeButton() et addButton().
[signal] void QDialogButtonBox::clicked(QAbstractButton *button)
Ce signal est émis lorsqu'on clique sur un bouton situé dans la boîte à boutons. Le bouton précis sur lequel on a cliqué est indiqué par button.
Voir également accepted(), rejected() et helpRequested().
[override virtual protected] bool QDialogButtonBox::event(QEvent *event)
Réimplémente : QWidget::event(QEvent *event).
[signal] void QDialogButtonBox::helpRequested()
Ce signal est émis lorsqu'on clique sur un bouton situé dans la boîte à boutons, à condition que celui-ci ait été défini à l'aide de la méthode ` HelpRole`.
Voir également ` accepted()`, ` rejected()` et ` clicked()`.
[signal] void QDialogButtonBox::rejected()
Ce signal est émis lorsqu'on clique sur un bouton situé dans la zone de boutons, à condition que celui-ci ait été défini à l'aide de l'RejectRole ou de l'NoRole.
Voir également accepted(), helpRequested() et clicked().
void QDialogButtonBox::removeButton(QAbstractButton *button)
Supprime l'élément « button » de la boîte de boutons sans le supprimer et définit son élément parent sur zéro.
Voir également clear(), buttons() et addButton().
QDialogButtonBox::StandardButton QDialogButtonBox::standardButton(QAbstractButton *button) const
Renvoie la valeur standard de l'énumération des boutons correspondant à l'button donné, ou NoButton si l'button donné n'est pas un bouton standard.
Voir également button(), buttons() et standardButtons().
[static, since 6.12] QKeySequence QDialogButtonBox::standardButtonShortcut(QDialogButtonBox::StandardButton button)
Renvoie le raccourci clavier correspondant au bouton standard « button ». Le raccourci dépend de la plateforme. Renvoie une instance vide de type ` QKeySequence ` si le bouton « button » n’est associé à aucun raccourci ou s’il ne s’agit pas d’un bouton standard reconnu.
Cette fonction a été introduite dans Qt 6.12.
Voir également ` standardButtonText()` et ` StandardButton`.
[static, since 6.12] QString QDialogButtonBox::standardButtonText(QDialogButtonBox::StandardButton button)
Renvoie le texte d'affichage correspondant au bouton standard « button », tel qu'il apparaît sur l'étiquette du bouton. Ce texte dépend de la plateforme et des paramètres régionaux.
Renvoie une chaîne vide si « button » n'est pas un bouton standard reconnu.
Cette fonction a été introduite dans Qt 6.12.
Voir également ` standardButtonShortcut()` et ` StandardButton`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
Capture d’écran d’une disposition horizontale non modale
Capture d’écran de la version non modale verticale