QDialogButtonBox Class

Die Klasse QDialogButtonBox ist ein Widget, das Schaltflächen in einem Layout präsentiert, das dem aktuellen Widgetstil entspricht. Mehr...

Kopfzeile: #include <QDialogButtonBox>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Vererbungen: QWidget

Öffentliche Typen

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

Eigenschaften

Öffentliche Funktionen

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

Signale

void accepted()
void clicked(QAbstractButton *button)
void helpRequested()
void rejected()

Reimplementierte geschützte Funktionen

virtual void changeEvent(QEvent *event) override
virtual bool event(QEvent *event) override

Detaillierte Beschreibung

Dialoge und Meldungsfenster zeigen normalerweise Schaltflächen in einem Layout an, das den Schnittstellenrichtlinien für die jeweilige Plattform entspricht. Verschiedene Plattformen haben zwangsläufig unterschiedliche Layouts für ihre Dialoge. QDialogButtonBox erlaubt es einem Entwickler, Schaltflächen hinzuzufügen und verwendet automatisch das passende Layout für die Desktop-Umgebung des Benutzers.

Die meisten Schaltflächen für einen Dialog folgen bestimmten Rollen. Solche Rollen beinhalten:

  • Akzeptieren oder Ablehnen des Dialogs.
  • Um Hilfe bitten.
  • Ausführen von Aktionen im Dialog selbst (z. B. Zurücksetzen von Feldern oder Anwenden von Änderungen).

Es kann auch alternative Möglichkeiten geben, den Dialog zu beenden, was zu destruktiven Ergebnissen führen kann.

Die meisten Dialoge verfügen über Schaltflächen, die fast als Standardschaltflächen angesehen werden können (z. B. OK und Cancel ). Manchmal ist es praktisch, diese Schaltflächen auf eine standardisierte Weise zu erstellen.

Es gibt mehrere Möglichkeiten, QDialogButtonBox zu verwenden. Eine Möglichkeit besteht darin, die Schaltflächen (oder Schaltflächentexte) selbst zu erstellen und sie der Schaltflächenbox hinzuzufügen, wobei ihre Rolle angegeben wird.

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

Alternativ bietet QDialogButtonBox mehrere Standardschaltflächen (z. B. OK, Abbrechen, Speichern), die Sie verwenden können. Sie existieren als Flags, so dass Sie sie im Konstruktor mit ODER verknüpfen können.

    buttonBox = new QDialogButtonBox(QDialogButtonBox::Ok
                                     | QDialogButtonBox::Cancel);

    connect(buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept);
    connect(buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);

Sie können normale Schaltflächen und Standardschaltflächen mischen und anpassen.

Derzeit sind die Schaltflächen folgendermaßen angeordnet, wenn die Schaltflächenbox horizontal ist:

GnomeLayout HorizontalSchaltflächenfeld in horizontaler Anordnung GnomeLayout
KdeLayout HorizontalSchaltflächenfeld in horizontaler Anordnung KdeLayout
MacLayout HorizontalHorizontal angeordnete Schaltflächenbox MacLayout
WinLayout HorizontalHorizontal angeordnete Schaltflächenbox WinLayout

Die Schaltflächen werden wie folgt angeordnet, wenn die Schaltflächenbox vertikal ist:

Zusätzlich können Schaltflächenfelder, die nur Schaltflächen mit ActionRole oder HelpRole enthalten, als modeless betrachtet werden und haben unter macOS ein anderes Aussehen:

modeless horizontal MacLayout Screenshot von modeless horizontal MacLayout
modelllos vertikal MacLayout Bildschirmfoto von modelllos vertikal MacLayout

Wenn eine Schaltfläche im Schaltflächenfeld angeklickt wird, wird das Signal clicked() für die tatsächliche Schaltfläche ausgegeben, die gedrückt wird. Wenn die Schaltfläche ein AcceptRole, RejectRole oder HelpRole hat, werden der Einfachheit halber die Signale accepted(), rejected() bzw. helpRequested() ausgegeben.

Wenn Sie möchten, dass eine bestimmte Schaltfläche als Standardschaltfläche verwendet wird, müssen Sie QPushButton::setDefault() für diese Schaltfläche selbst aufrufen. Wenn jedoch keine Standardschaltfläche festgelegt ist und die Standardschaltfläche plattformübergreifend beibehalten werden soll, wenn die Eigenschaft QPushButton::autoDefault verwendet wird, wird die erste Drucktaste mit der Rolle "Akzeptieren" zur Standardschaltfläche, wenn die QDialogButtonBox angezeigt wird,

Siehe auch QMessageBox, QPushButton, und QDialog.

Dokumentation der Mitgliedstypen

enum QDialogButtonBox::ButtonLayout

Diese Aufzählung beschreibt die Layout-Richtlinie, die bei der Anordnung der in der Button-Box enthaltenen Buttons verwendet werden soll.

KonstanteWertBeschreibung
QDialogButtonBox::WinLayout0Verwenden Sie eine Richtlinie, die für Anwendungen unter Windows geeignet ist.
QDialogButtonBox::MacLayout1Verwenden Sie eine Richtlinie, die für Anwendungen unter macOS geeignet ist.
QDialogButtonBox::KdeLayout2Verwenden Sie eine Richtlinie, die für Anwendungen unter KDE geeignet ist.
QDialogButtonBox::GnomeLayout3Verwenden Sie eine Richtlinie, die für Anwendungen unter GNOME geeignet ist.
QDialogButtonBox::AndroidLayout4Verwenden Sie eine Richtlinie, die für Anwendungen unter Android geeignet ist. Dieser Enum-Wert wurde in Qt 5.10 hinzugefügt.

Das Layout der Schaltflächen wird durch die current style festgelegt. Auf der X11-Plattform kann es jedoch von der Desktop-Umgebung beeinflusst werden.

enum QDialogButtonBox::ButtonRole

Diese Aufzählung beschreibt die Rollen, die zur Beschreibung von Schaltflächen in der Schaltflächenbox verwendet werden können. Kombinationen dieser Rollen werden als Flags verwendet, um verschiedene Aspekte ihres Verhaltens zu beschreiben.

KonstanteWertBeschreibung
QDialogButtonBox::InvalidRole-1Die Schaltfläche ist ungültig.
QDialogButtonBox::AcceptRole0Das Anklicken der Schaltfläche führt dazu, dass der Dialog akzeptiert wird (z. B. OK).
QDialogButtonBox::RejectRole1Das Anklicken der Schaltfläche führt zur Ablehnung des Dialogs (z. B. Abbrechen).
QDialogButtonBox::DestructiveRole2Das Anklicken der Schaltfläche führt zu einer destruktiven Änderung (z. B. für Änderungen verwerfen) und schließt den Dialog.
QDialogButtonBox::ActionRole3Das Anklicken der Schaltfläche führt zu Änderungen an den Elementen innerhalb des Dialogs.
QDialogButtonBox::HelpRole4Die Schaltfläche kann angeklickt werden, um Hilfe anzufordern.
QDialogButtonBox::YesRole5Die Schaltfläche ist eine "Ja"-ähnliche Schaltfläche.
QDialogButtonBox::NoRole6Die Schaltfläche ist eine "Nein"-ähnliche Schaltfläche.
QDialogButtonBox::ApplyRole8Die Schaltfläche wendet aktuelle Änderungen an.
QDialogButtonBox::ResetRole7Die Schaltfläche setzt die Felder des Dialogs auf die Standardwerte zurück.

Siehe auch StandardButton.

enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons

Diese Enums beschreiben Flags für Standard-Buttons. Jeder Button hat eine definierte ButtonRole.

KonstanteWertBeschreibung
QDialogButtonBox::Ok0x00000400Eine "OK"-Schaltfläche, die mit dem AcceptRole definiert ist.
QDialogButtonBox::Open0x00002000Eine "Öffnen"-Schaltfläche, die mit AcceptRole definiert ist.
QDialogButtonBox::Save0x00000800Eine "Speichern"-Schaltfläche, die mit AcceptRole definiert wurde.
QDialogButtonBox::Cancel0x00400000Eine "Abbrechen"-Schaltfläche, die mit der RejectRole definiert wurde.
QDialogButtonBox::Close0x00200000Eine "Schließen"-Schaltfläche, die mit der RejectRole definiert wird.
QDialogButtonBox::Discard0x00800000Eine Schaltfläche "Verwerfen" oder "Nicht speichern", je nach Plattform, die mit DestructiveRole definiert wird.
QDialogButtonBox::Apply0x02000000Eine "Anwenden"-Schaltfläche, die mit der ApplyRole definiert wird.
QDialogButtonBox::Reset0x04000000Eine "Zurücksetzen"-Schaltfläche, die mit der ResetRole definiert wird.
QDialogButtonBox::RestoreDefaults0x08000000Eine Schaltfläche "Standardeinstellungen wiederherstellen", die mit ResetRole definiert wird.
QDialogButtonBox::Help0x01000000Eine "Hilfe"-Schaltfläche, die mit HelpRole definiert wurde.
QDialogButtonBox::SaveAll0x00001000Eine Schaltfläche "Alles speichern", definiert mit AcceptRole.
QDialogButtonBox::Yes0x00004000Eine "Ja"-Schaltfläche, die mit YesRole definiert wurde.
QDialogButtonBox::YesToAll0x00008000Eine "Ja zu allen"-Schaltfläche, die mit YesRole definiert wurde.
QDialogButtonBox::No0x00010000Eine "Nein"-Schaltfläche, die mit der NoRole definiert wird.
QDialogButtonBox::NoToAll0x00020000Eine "Nein zu allen"-Schaltfläche, die mit der NoRole definiert wird.
QDialogButtonBox::Abort0x00040000Eine "Abbrechen"-Schaltfläche, die mit der RejectRole definiert wird.
QDialogButtonBox::Retry0x00080000Eine "Wiederholen"-Schaltfläche, die mit der AcceptRole definiert wird.
QDialogButtonBox::Ignore0x00100000Eine "Ignorieren"-Schaltfläche, die mit der AcceptRole definiert wurde.
QDialogButtonBox::NoButton0x00000000Eine ungültige Schaltfläche.

Der Typ StandardButtons ist ein Typedef für QFlags<StandardButton>. Er speichert eine ODER-Kombination von StandardButton-Werten.

Siehe auch ButtonRole und standardButtons.

Dokumentation der Eigenschaft

centerButtons : bool

Diese Eigenschaft legt fest, ob die Schaltflächen im Schaltflächenfeld zentriert sind

Standardmäßig ist diese Eigenschaft false. Dieses Verhalten ist für die meisten Arten von Dialogen geeignet. Eine bemerkenswerte Ausnahme sind Nachrichtenboxen auf den meisten Plattformen (z. B. Windows), bei denen die Schaltflächenbox horizontal zentriert ist.

Zugriffsfunktionen:

bool centerButtons() const
void setCenterButtons(bool center)

Siehe auch QMessageBox.

orientation : Qt::Orientation

Diese Eigenschaft gibt die Ausrichtung der Schaltflächenbox an

Standardmäßig ist die Ausrichtung horizontal (d. h. die Schaltflächen sind nebeneinander angeordnet). Die möglichen Ausrichtungen sind Qt::Horizontal und Qt::Vertical.

Zugriffsfunktionen:

Qt::Orientation orientation() const
void setOrientation(Qt::Orientation orientation)

standardButtons : StandardButtons

Sammlung von Standardschaltflächen in der Buttonbox

Diese Eigenschaft steuert, welche Standardschaltflächen von der Schaltflächenbox verwendet werden.

Zugriffsfunktionen:

QDialogButtonBox::StandardButtons standardButtons() const
void setStandardButtons(QDialogButtonBox::StandardButtons buttons)

Siehe auch addButton().

Dokumentation der Mitgliedsfunktionen

QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)

Konstruiert eine leere, horizontale Buttonbox mit der angegebenen parent.

Siehe auch orientation und addButton().

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

Konstruiert eine horizontale Schaltflächenbox mit der angegebenen parent, die die durch buttons angegebenen Standardschaltflächen enthält.

Siehe auch orientation und addButton().

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

Konstruiert eine leere Button-Box mit den angegebenen orientation und parent.

Siehe auch orientation und addButton().

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

Konstruiert eine Buttonbox mit den angegebenen orientation und parent, die die durch buttons angegebenen Standardbuttons enthält.

Siehe auch orientation und addButton().

[virtual noexcept] QDialogButtonBox::~QDialogButtonBox()

Zerstört das Schaltflächenfeld.

[signal] void QDialogButtonBox::accepted()

Dieses Signal wird ausgegeben, wenn eine Schaltfläche innerhalb der Schaltflächenbox angeklickt wird, sofern diese mit AcceptRole oder YesRole definiert wurde.

Siehe auch rejected(), clicked(), und helpRequested().

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

Fügt einen Standard button zum Schaltflächenfeld hinzu, wenn dieser gültig ist, und gibt eine Drucktaste zurück. Wenn button ungültig ist, wird es nicht in das Schaltflächenfeld eingefügt und Null zurückgegeben.

Siehe auch removeButton() und clear().

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

Fügt die angegebene button zum Schaltflächenfeld mit der angegebenen role hinzu. Wenn die Rolle ungültig ist, wird die Schaltfläche nicht hinzugefügt.

Wenn die Schaltfläche bereits hinzugefügt wurde, wird sie entfernt und mit der neuen Rolle erneut hinzugefügt.

Hinweis: Das Schaltflächenfeld wird Eigentümer der Schaltfläche.

Siehe auch removeButton() und clear().

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

Erzeugt eine Drucktaste mit der angegebenen text, fügt sie dem Schaltflächenfeld für die angegebene role hinzu und gibt die entsprechende Drucktaste zurück. Wenn role ungültig ist, wird keine Schaltfläche erstellt und Null zurückgegeben.

Siehe auch removeButton() und clear().

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

Gibt die QPushButton zurück, die der Standard-Schaltfläche which entspricht, oder nullptr, wenn die Standard-Schaltfläche in diesem Schaltflächenfeld nicht vorhanden ist.

Siehe auch standardButton(), standardButtons(), und buttons().

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

Gibt die Schaltflächenrolle für die angegebene button zurück. Diese Funktion gibt InvalidRole zurück, wenn button nullptr ist oder dem Schaltflächenfeld nicht hinzugefügt wurde.

Siehe auch buttons() und addButton().

QList<QAbstractButton *> QDialogButtonBox::buttons() const

Gibt eine Liste aller Schaltflächen zurück, die dem Schaltflächenfeld hinzugefügt wurden.

Siehe auch buttonRole(), addButton(), und removeButton().

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

Reimplements: QWidget::changeEvent(QEvent *Event).

void QDialogButtonBox::clear()

Löscht das Schaltflächenfeld und damit alle darin enthaltenen Schaltflächen.

Siehe auch removeButton() und addButton().

[signal] void QDialogButtonBox::clicked(QAbstractButton *button)

Dieses Signal wird ausgegeben, wenn eine Schaltfläche im Schaltflächenfeld angeklickt wird. Die spezifische Schaltfläche, die gedrückt wurde, wird durch button angegeben.

Siehe auch accepted(), rejected(), und helpRequested().

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

Reimplements: QWidget::event(QEvent *Event).

[signal] void QDialogButtonBox::helpRequested()

Dieses Signal wird ausgegeben, wenn eine Schaltfläche innerhalb der Schaltflächenbox angeklickt wird, sofern diese mit HelpRole definiert wurde.

Siehe auch accepted(), rejected(), und clicked().

[signal] void QDialogButtonBox::rejected()

Dieses Signal wird ausgegeben, wenn eine Schaltfläche innerhalb der Schaltflächenbox angeklickt wird, sofern diese mit RejectRole oder NoRole definiert wurde.

Siehe auch accepted(), helpRequested(), und clicked().

void QDialogButtonBox::removeButton(QAbstractButton *button)

Entfernt button aus dem Schaltflächenfeld, ohne es zu löschen, und setzt sein übergeordnetes Element auf Null.

Siehe auch clear(), buttons(), und addButton().

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

Gibt den Enum-Wert der Standardschaltfläche zurück, der der angegebenen button entspricht, oder NoButton, wenn die angegebene button keine Standardschaltfläche ist.

Siehe auch button(), buttons(), und standardButtons().

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