Sur cette page

QDialogButtonBox Class

La classe QDialogButtonBox est un widget qui présente des boutons dans une disposition appropriée au style du widget actuel. Plus d'informations...

En-tête : #include <QDialogButtonBox>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Héritages : 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

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()

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 de message présentent généralement des boutons dans une disposition conforme aux directives d'interface de la plate-forme concernée. Invariablement, les différentes plates-formes ont des dispositions différentes pour leurs boîtes de dialogue. QDialogButtonBox permet à un développeur d'ajouter des boutons et utilisera automatiquement la présentation appropriée pour l'environnement de bureau de l'utilisateur.

La plupart des boutons d'une boîte de dialogue jouent certains rôles. Ces rôles sont les suivants

  • 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 y avoir d'autres façons de rejeter la boîte de dialogue, ce qui peut entraîner des résultats destructeurs.

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 deux façons d'utiliser QDialogButtonBox. L'une d'entre elles consiste à créer soi-même les boutons (ou les textes des boutons) et à les ajouter à la boîte à boutons, en précisant leur rôle.

QDialogButtonBox *buttonBox = new QDialogButtonBox(Qt::Vertical);
buttonBox->addButton(findButton, QDialogButtonBox::ActionRole);
buttonBox->addButton(moreButton, QDialogButtonBox::ActionRole);

QDialogButtonBox fournit également plusieurs boutons standard (par exemple, OK, Annuler, Enregistrer) que vous pouvez utiliser. Ils existent sous forme de drapeaux, de sorte que vous pouvez les regrouper par 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 mélanger les boutons normaux et les boutons standard.

Actuellement, les boutons sont disposés de la manière suivante si la boîte à boutons est horizontale :

Plusieurs boutons utilisant la disposition horizontale GnomeLayout GnomeLayout HorizontalBoîte à boutons disposée à l'horizontale GnomeLayout
Plusieurs boutons utilisant la disposition horizontale KdeLayout KdeLayout HorizontaleBoîte à boutons disposée à l'horizontale KdeLayout
Plusieurs boutons utilisant la disposition horizontale MacLayout MacLayout HorizontaleBoîte à boutons disposée à l'horizontale MacLayout
Plusieurs boutons utilisant la disposition horizontale WinLayout WinLayout HorizontaleBoîte à boutons disposée à l'horizontale WinLayout

Les boutons sont disposés de la manière suivante si la boîte à boutons est verticale :

En outre, les boîtes à boutons qui ne contiennent que des boutons avec ActionRole ou HelpRole peuvent être considérées comme sans modèle et avoir un autre aspect sur macOS :

modeless horizontal MacLayoutPlusieurs boutons utilisant le style horizontal sans modèle sur macOS Capture d'écran de modeless horizontal MacLayout
sans modèle vertical MacLayoutPlusieurs boutons utilisant le style horizontal sans modèle sur macOS Capture d'écran de modeless vertical MacLayout

Lorsqu'un bouton est cliqué dans la boîte à boutons, le signal clicked() est émis pour le bouton pressé. Par commodité, si le bouton est associé à AcceptRole, RejectRole ou HelpRole, les signaux accepted(), rejected() ou helpRequested() sont émis respectivement.

Si vous voulez qu'un bouton spécifique soit le bouton par défaut, vous devez appeler QPushButton::setDefault() sur ce bouton vous-même. Toutefois, si aucun bouton par défaut n'est défini et pour conserver le bouton par défaut sur toutes les plateformes lors de l'utilisation de la propriété QPushButton::autoDefault, le premier bouton poussoir ayant le rôle d'acceptation devient le bouton par défaut lorsque la QDialogButtonBox est affichée,

Voir également QMessageBox, QPushButton, et QDialog.

Documentation sur les types de membres

enum QDialogButtonBox::ButtonLayout

Cette énumération décrit la politique de mise en page à utiliser lors de la disposition des boutons contenus dans la boîte à boutons.

ConstanteValeurDescription
QDialogButtonBox::WinLayout0Utiliser une politique appropriée pour les applications sous Windows.
QDialogButtonBox::MacLayout1Utiliser une politique appropriée pour les applications sous macOS.
QDialogButtonBox::KdeLayout2Utiliser une stratégie appropriée pour les applications sous KDE.
QDialogButtonBox::GnomeLayout3Utiliser une politique appropriée pour les applications sous GNOME.
QDialogButtonBox::AndroidLayout4Utiliser une politique appropriée pour les applications sur Android. Cette valeur d'énumération a été ajoutée dans Qt 5.10.

La disposition des boutons est spécifiée par la valeur current style. Cependant, 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 qui peuvent être utilisés pour décrire les boutons dans la boîte à boutons. Les combinaisons de ces rôles sont autant de drapeaux utilisés pour décrire les différents aspects de leur comportement.

ConstanteValeurDescription du bouton
QDialogButtonBox::InvalidRole-1Le bouton n'est pas valide.
QDialogButtonBox::AcceptRole0Un clic sur le bouton entraîne l'acceptation de la boîte de dialogue (par exemple, OK).
QDialogButtonBox::RejectRole1Un clic sur le bouton entraîne le rejet de la boîte de dialogue (par exemple, Annuler).
QDialogButtonBox::DestructiveRole2Un clic sur le bouton entraîne une modification destructive (par exemple, pour rejeter des modifications) et ferme la boîte de dialogue.
QDialogButtonBox::ActionRole3Un clic sur le bouton entraîne des modifications des éléments de la boîte de dialogue.
QDialogButtonBox::HelpRole4Il est possible de cliquer sur le bouton pour demander de l'aide.
QDialogButtonBox::YesRole5Le bouton est un bouton de type "Oui".
QDialogButtonBox::NoRole6Le bouton ressemble à un bouton "Non".
QDialogButtonBox::ApplyRole8Le bouton applique les modifications en cours.
QDialogButtonBox::ResetRole7Le bouton rétablit les valeurs par défaut des champs de la boîte de dialogue.

Voir également StandardButton.

enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons

Ces enums décrivent les drapeaux des boutons standard. Chaque bouton a une valeur définie ButtonRole.

ConstanteValeurDescription
QDialogButtonBox::Ok0x00000400Un bouton "OK" défini à l'aide de l'enum AcceptRole.
QDialogButtonBox::Open0x00002000Un bouton "Ouvrir" défini à l'aide de la constante AcceptRole.
QDialogButtonBox::Save0x00000800Un bouton "Enregistrer" défini à l'aide de l'adresse AcceptRole.
QDialogButtonBox::Cancel0x00400000Un bouton "Annuler" défini à l'aide de l'adresse RejectRole.
QDialogButtonBox::Close0x00200000Un bouton "Fermer" défini à l'aide de l'adresse RejectRole.
QDialogButtonBox::Discard0x00800000Un bouton "Discard" ou "Don't Save", en fonction de la plateforme, défini à l'aide de l'adresse DestructiveRole.
QDialogButtonBox::Apply0x02000000Un bouton "Appliquer" défini à l'aide de l'adresse ApplyRole.
QDialogButtonBox::Reset0x04000000Un bouton "Reset" défini à l'aide de l'adresse ResetRole.
QDialogButtonBox::RestoreDefaults0x08000000Un bouton "Restore Defaults" défini à l'aide de l'adresse ResetRole.
QDialogButtonBox::Help0x01000000Un bouton "Help" défini à l'aide de l'adresse HelpRole.
QDialogButtonBox::SaveAll0x00001000Un bouton "Save All" défini à l'aide de l'adresse AcceptRole.
QDialogButtonBox::Yes0x00004000Un bouton "Oui" défini à l'aide de l'adresse YesRole.
QDialogButtonBox::YesToAll0x00008000Un bouton "Oui à tout" défini à l'aide de l'adresse YesRole.
QDialogButtonBox::No0x00010000Un bouton "Non" défini à l'aide de l'adresse NoRole.
QDialogButtonBox::NoToAll0x00020000Un bouton "Non à tous" défini à l'aide de l'adresse NoRole.
QDialogButtonBox::Abort0x00040000Un bouton "Abort" défini à l'aide de l'adresse RejectRole.
QDialogButtonBox::Retry0x00080000Un bouton "Retry" défini à l'aide de l'adresse AcceptRole.
QDialogButtonBox::Ignore0x00100000Un bouton "Ignorer" défini à l'aide de l'adresse AcceptRole.
QDialogButtonBox::NoButton0x00000000Un bouton invalide.

Le type StandardButtons est un typedef pour QFlags<StandardButton>. Il stocke une combinaison OU de valeurs StandardButton.

Voir également ButtonRole et standardButtons.

Documentation sur les propriétés

centerButtons : bool

Cette propriété indique si les boutons de la boîte à boutons sont centrés

Par défaut, cette propriété vaut false. Ce comportement convient à la plupart des types de boîtes de dialogue. Une exception notable est constituée par les boîtes de message sur la plupart des plates-formes (par exemple Windows), où la boîte à 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 à 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

collection de boutons standard dans la boîte à boutons

Cette propriété détermine 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 des fonctions membres

QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)

Construit une boîte à boutons horizontale vide avec l'adresse parent.

Voir aussi orientation et addButton().

[explicit] QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr)

Construit une boîte à boutons horizontale avec l'adresse parent, contenant les boutons standard spécifiés par buttons.

Voir aussi orientation et addButton().

QDialogButtonBox::QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr)

Construit une boîte à boutons vide avec les données orientation et parent.

Voir aussi orientation et addButton().

QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr)

Construit une boîte à boutons avec les données orientation et parent, contenant les boutons standard spécifiés par buttons.

Voir aussi orientation et addButton().

[virtual noexcept] QDialogButtonBox::~QDialogButtonBox()

Détruit la boîte à boutons.

[signal] void QDialogButtonBox::accepted()

Ce signal est émis lorsqu'un bouton situé à l'intérieur de la boîte à boutons est cliqué, à condition qu'il ait été défini à l'aide de la méthode AcceptRole ou YesRole.

Voir aussi rejected(), clicked() et helpRequested().

QPushButton *QDialogButtonBox::addButton(QDialogButtonBox::StandardButton button)

Ajoute un standard button à la boîte à boutons s'il est valide, et renvoie un bouton poussoir. Si button n'est pas valide, il n'est pas ajouté à la boîte à boutons et zéro est renvoyé.

Voir aussi removeButton() et clear().

void QDialogButtonBox::addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role)

Ajoute le button donné à la boîte à boutons avec le role spécifié. 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é et ajouté à nouveau avec le nouveau rôle.

Remarque : la boîte à boutons est propriétaire du bouton.

Voir également removeButton() et clear().

QPushButton *QDialogButtonBox::addButton(const QString &text, QDialogButtonBox::ButtonRole role)

Crée un bouton poussoir avec l'adresse text donnée, l'ajoute à la boîte à boutons pour l'adresse role spécifiée, et renvoie le bouton poussoir correspondant. Si role n'est pas valide, aucun bouton n'est créé et zéro est renvoyé.

Voir aussi removeButton() et clear().

QPushButton *QDialogButtonBox::button(QDialogButtonBox::StandardButton which) const

Renvoie l'adresse QPushButton correspondant au bouton standard which, ou nullptr si le bouton standard n'existe pas dans cette boîte à boutons.

Voir aussi standardButton(), standardButtons() et buttons().

QDialogButtonBox::ButtonRole QDialogButtonBox::buttonRole(QAbstractButton *button) const

Renvoie le rôle de bouton pour le site button spécifié. Cette fonction renvoie InvalidRole si button est nullptr ou n'a pas été ajouté à la boîte à boutons.

Voir aussi 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 aussi buttonRole(), addButton() et removeButton().

[override virtual protected] void QDialogButtonBox::changeEvent(QEvent *event)

Réimplémente : QWidget::changeEvent(QEvent *event).

void QDialogButtonBox::clear()

Efface la boîte à 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'un bouton à l'intérieur de la boîte à boutons est cliqué. Le bouton spécifique qui a été pressé est spécifié par button.

Voir aussi 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'un bouton à l'intérieur de la boîte à boutons est cliqué, à condition qu'il ait été défini à l'aide de l'option HelpRole.

Voir aussi accepted(), rejected() et clicked().

[signal] void QDialogButtonBox::rejected()

Ce signal est émis lorsqu'un bouton situé à l'intérieur de la boîte à boutons est cliqué, à condition qu'il ait été défini à l'aide de la méthode RejectRole ou NoRole.

Voir aussi accepted(), helpRequested() et clicked().

void QDialogButtonBox::removeButton(QAbstractButton *button)

Supprime button de la boîte à boutons sans l'effacer et met son parent à zéro.

Voir également clear(), buttons() et addButton().

QDialogButtonBox::StandardButton QDialogButtonBox::standardButton(QAbstractButton *button) const

Renvoie la valeur de l'énumération des boutons standard correspondant à l'adresse button, ou NoButton si l'adresse button n'est pas un bouton standard.

Voir aussi button(), buttons(), et standardButtons().

© 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.