Sur cette page

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

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 :

Plusieurs boutons utilisant la disposition horizontale de GnomeLayout GnomeLayout HorizontaleBoîte de boutons disposée horizontalement GnomeLayout
Plusieurs boutons utilisant la disposition horizontale KdeLayout KdeLayout HorizontalBoîte de boutons disposée horizontalement KdeLayout
Plusieurs boutons utilisant la disposition horizontale MacLayout MacLayout HorizontaleBoîte de boutons disposée horizontalement MacLayout
Plusieurs boutons utilisant la disposition horizontale WinLayout WinLayout HorizontaleBoîte de boutons disposée horizontalement WinLayout

Les boutons sont disposés de la manière suivante si la zone de boutons est 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 MacLayoutPlusieurs boutons utilisant le style horizontal non modal sous macOS Capture d’écran d’une disposition horizontale non modale MacLayout
vertical sans mode MacLayoutPlusieurs boutons utilisant le style horizontal non modale sous macOS 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.

ConstanteValeurDescription
QDialogButtonBox::WinLayout0Utilisez une politique adaptée aux applications sous Windows.
QDialogButtonBox::MacLayout1Utilise une politique adaptée aux applications sous macOS.
QDialogButtonBox::KdeLayout2Utilisez une stratégie adaptée aux applications sous KDE.
QDialogButtonBox::GnomeLayout3Utiliser une stratégie adaptée aux applications sous GNOME.
QDialogButtonBox::AndroidLayout4Utilisez 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.

ConstanteValeurDescription
QDialogButtonBox::InvalidRole-1Le bouton n'est pas valide.
QDialogButtonBox::AcceptRole0Cliquer sur le bouton entraîne l'acceptation de la boîte de dialogue (par exemple, OK).
QDialogButtonBox::RejectRole1Cliquer sur ce bouton entraîne le rejet de la boîte de dialogue (par exemple, « Annuler »).
QDialogButtonBox::DestructiveRole2Cliquer sur ce bouton entraîne une modification irréversible (par exemple, pour « Annuler les modifications ») et ferme la boîte de dialogue.
QDialogButtonBox::ActionRole3Cliquer sur ce bouton modifie les éléments contenus dans la boîte de dialogue.
QDialogButtonBox::HelpRole4On peut cliquer sur ce bouton pour demander de l'aide.
QDialogButtonBox::YesRole5Ce bouton correspond à un « Oui ».
QDialogButtonBox::NoRole6Ce bouton correspond à un « Non ».
QDialogButtonBox::ApplyRole8Ce bouton applique les modifications en cours.
QDialogButtonBox::ResetRole7Ce 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.

ConstanteValeurDescription
QDialogButtonBox::Ok0x00000400Un bouton « OK » défini avec l'AcceptRole.
QDialogButtonBox::Open0x00002000Un bouton « Ouvrir » défini avec l'AcceptRole.
QDialogButtonBox::Save0x00000800Un bouton « Enregistrer » défini à l'aide de l'AcceptRole.
QDialogButtonBox::Cancel0x00400000Un bouton « Annuler » défini à l'aide de l'RejectRole.
QDialogButtonBox::Close0x00200000Un bouton « Fermer » défini à l'aide de l'RejectRole.
QDialogButtonBox::Discard0x00800000Un bouton « Ignorer » ou « Ne pas enregistrer », selon la plateforme, défini à l’aide de l’ DestructiveRole.
QDialogButtonBox::Apply0x02000000Un bouton « Appliquer » défini à l’aide de la méthode ApplyRole.
QDialogButtonBox::Reset0x04000000Un bouton « Réinitialiser » défini à l’aide de la balise ResetRole.
QDialogButtonBox::RestoreDefaults0x08000000Un bouton « Restaurer les valeurs par défaut » défini à l’aide de la balise ResetRole.
QDialogButtonBox::Help0x01000000Un bouton « Aide » défini à l’aide de l’ HelpRole.
QDialogButtonBox::SaveAll0x00001000Un bouton « Tout enregistrer » défini à l’aide de l’ AcceptRole.
QDialogButtonBox::Yes0x00004000Un bouton « Oui » défini à l'aide de l'YesRole.
QDialogButtonBox::YesToAll0x00008000Un bouton « Oui à tout » défini à l'aide de l'YesRole.
QDialogButtonBox::No0x00010000Un bouton « Non » défini à l'aide de l'NoRole.
QDialogButtonBox::NoToAll0x00020000Un bouton « Non à tout » défini avec l'NoRole.
QDialogButtonBox::Abort0x00040000Un bouton « Abandonner » défini à l'aide de la balise RejectRole.
QDialogButtonBox::Retry0x00080000Un bouton « Réessayer » défini à l'aide de l'AcceptRole.
QDialogButtonBox::Ignore0x00100000Un bouton « Ignorer » défini à l'aide de la méthode AcceptRole.
QDialogButtonBox::NoButton0x00000000Un 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.