En esta página

QDialogButtonBox Class

La clase QDialogButtonBox es un widget que presenta botones en un diseño que es apropiado para el estilo de widget actual. Más...

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

Tipos públicos

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

Propiedades

Funciones públicas

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

Señales

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

Funciones protegidas reimplementadas

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

Descripción detallada

Los cuadros de diálogo y de mensajes suelen presentar los botones con un diseño que se ajusta a las directrices de la interfaz de la plataforma en cuestión. Invariablemente, diferentes plataformas tienen diferentes diseños para sus diálogos. QDialogButtonBox permite al desarrollador añadir botones y automáticamente utilizará el diseño apropiado para el entorno de escritorio del usuario.

La mayoría de los botones de un diálogo siguen ciertos roles. Tales roles incluyen:

  • Aceptar o rechazar el diálogo.
  • Pedir ayuda.
  • Realizar acciones en el propio diálogo (como restablecer campos o aplicar cambios).

También puede haber formas alternativas de rechazar el diálogo que pueden causar resultados destructivos.

La mayoría de los cuadros de diálogo tienen botones que casi pueden considerarse estándar (por ejemplo, los botones OK y Cancel ). A veces es conveniente crear estos botones de forma estándar.

Hay un par de formas de usar QDialogButtonBox. Una forma es crear los botones (o los textos de los botones) tu mismo y añadirlos a la caja de botones, especificando su función.

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

Alternativamente, QDialogButtonBox proporciona varios botones estándar (ej. OK, Cancelar, Guardar) que puedes usar. Existen como banderas, por lo que puedes ORDENARLOS juntos en el constructor.

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

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

Puedes mezclar y combinar botones normales y botones estándar.

Actualmente los botones están dispuestos de la siguiente manera si la caja de botones es horizontal:

Varios botones utilizando el diseño horizontal GnomeLayout GnomeLayout HorizontalCaja de botones dispuesta en horizontal GnomeLayout
Varios botones utilizando el diseño horizontal KdeLayout KdeLayout HorizontalCaja de botones en horizontal KdeLayout
Varios botones con la disposición horizontal MacLayout MacLayout HorizontalBotonera horizontal MacLayout
Varios botones utilizando el diseño horizontal WinLayout WinLayout HorizontalCaja de botones en horizontal WinLayout

La disposición de los botones es la siguiente si la caja de botones es vertical:

Además, las cajas de botones que sólo contienen botones con ActionRole o HelpRole pueden considerarse sin modelo y tienen un aspecto alternativo en macOS:

modeless horizontal MacLayoutVarios botones con el estilo modeless horizontal en macOS Captura de pantalla de modeless horizontal MacLayout
modeless vertical MacLayoutVarios botones con el estilo modeless horizontal en macOS Captura de pantalla de modeless vertical MacLayout

Cuando se pulsa un botón en la caja de botones, se emite la señal clicked() para el botón que se pulsa. Por conveniencia, si el botón tiene un AcceptRole, RejectRole, o HelpRole, se emiten las señales accepted(), rejected(), o helpRequested() respectivamente.

Si desea que un botón específico sea el predeterminado, deberá llamar usted mismo a QPushButton::setDefault() en él. Sin embargo, si no hay ningun boton por defecto establecido y para preservar cual es el boton por defecto a traves de las plataformas cuando se usa la propiedad QPushButton::autoDefault, el primer boton push con el rol accept se convierte en el boton por defecto cuando se muestra el QDialogButtonBox,

Ver también QMessageBox, QPushButton, y QDialog.

Documentación de tipos de miembros

enum QDialogButtonBox::ButtonLayout

Este enum describe la política de disposición que se utilizará al organizar los botones contenidos en la caja de botones.

ConstanteValorDescripción
QDialogButtonBox::WinLayout0Utilizar una política apropiada para aplicaciones en Windows.
QDialogButtonBox::MacLayout1Utilizar una política apropiada para aplicaciones en macOS.
QDialogButtonBox::KdeLayout2Usar una política apropiada para aplicaciones en KDE.
QDialogButtonBox::GnomeLayout3Utilice una política apropiada para aplicaciones en GNOME.
QDialogButtonBox::AndroidLayout4Utilizar una política apropiada para aplicaciones en Android. Este valor enum se añadió en Qt 5.10.

La disposición de los botones se especifica en current style. Sin embargo, en la plataforma X11, puede estar influenciada por el entorno de escritorio.

enum QDialogButtonBox::ButtonRole

Este enum describe los roles que se pueden utilizar para describir los botones de la caja de botones. Las combinaciones de estos roles son como banderas utilizadas para describir diferentes aspectos de su comportamiento.

ConstanteValorDescripción
QDialogButtonBox::InvalidRole-1El botón no es válido.
QDialogButtonBox::AcceptRole0Al hacer clic en el botón, se acepta el diálogo (p. ej., Aceptar).
QDialogButtonBox::RejectRole1Al hacer clic en el botón se rechaza el diálogo (por ejemplo, Cancelar).
QDialogButtonBox::DestructiveRole2Al hacer clic en el botón se produce un cambio destructivo (p. ej., para descartar cambios) y se cierra la ventana de diálogo.
QDialogButtonBox::ActionRole3Pulsar el botón provoca cambios en los elementos del diálogo.
QDialogButtonBox::HelpRole4Se puede pulsar el botón para solicitar ayuda.
QDialogButtonBox::YesRole5El botón es del tipo "Sí".
QDialogButtonBox::NoRole6El botón es similar a "No".
QDialogButtonBox::ApplyRole8El botón aplica los cambios actuales.
QDialogButtonBox::ResetRole7El botón restablece los valores predeterminados de los campos del cuadro de diálogo.

Ver también StandardButton.

enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons

Estos enums describen las banderas de los botones estándar. Cada botón tiene definida una ButtonRole.

ConstanteValorDescripción
QDialogButtonBox::Ok0x00000400Botón "OK" definido con el parámetro AcceptRole.
QDialogButtonBox::Open0x00002000Botón "Abrir" definido en AcceptRole.
QDialogButtonBox::Save0x00000800Botón "Guardar" definido en AcceptRole.
QDialogButtonBox::Cancel0x00400000Botón "Cancelar" definido en RejectRole.
QDialogButtonBox::Close0x00200000Botón "Cerrar" definido en RejectRole.
QDialogButtonBox::Discard0x00800000Un botón "Descartar" o "No guardar", según la plataforma, definido en DestructiveRole.
QDialogButtonBox::Apply0x02000000Un botón "Aplicar" definido en ApplyRole.
QDialogButtonBox::Reset0x04000000Un botón "Restablecer" definido en ResetRole.
QDialogButtonBox::RestoreDefaults0x08000000Un botón "Restaurar valores predeterminados" definido en ResetRole.
QDialogButtonBox::Help0x01000000Botón "Ayuda" definido en HelpRole.
QDialogButtonBox::SaveAll0x00001000Botón "Guardar todo" definido en AcceptRole.
QDialogButtonBox::Yes0x00004000Botón "Sí" definido en YesRole.
QDialogButtonBox::YesToAll0x00008000Botón "Sí a todo" definido en YesRole.
QDialogButtonBox::No0x00010000Botón "No" definido en NoRole.
QDialogButtonBox::NoToAll0x00020000Botón "No a todo" definido en NoRole.
QDialogButtonBox::Abort0x00040000Botón "Abortar" definido en RejectRole.
QDialogButtonBox::Retry0x00080000Botón "Reintentar" definido en AcceptRole.
QDialogButtonBox::Ignore0x00100000Botón "Ignorar" definido en AcceptRole.
QDialogButtonBox::NoButton0x00000000Un botón no válido.

El tipo StandardButtons es un typedef para QFlags<StandardButton>. Almacena una combinación OR de valores StandardButton.

Véase también ButtonRole y standardButtons.

Documentación de Propiedades

centerButtons : bool

Esta propiedad indica si los botones de la caja de botones están centrados.

Por defecto, esta propiedad es false. Este comportamiento es apropiado para la mayoría de los tipos de diálogo. Una excepción notable son los cuadros de mensaje en la mayoría de las plataformas (por ejemplo, Windows), donde la caja de botones está centrada horizontalmente.

Funciones de acceso:

bool centerButtons() const
void setCenterButtons(bool center)

Véase también QMessageBox.

orientation : Qt::Orientation

Esta propiedad contiene la orientación de la caja de botones

Por defecto, la orientación es horizontal (es decir, los botones están dispuestos uno al lado del otro). Las orientaciones posibles son Qt::Horizontal y Qt::Vertical.

Funciones de acceso:

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

standardButtons : StandardButtons

Colección de botones estándar de la caja de botones

Esta propiedad controla qué botones estándar utiliza la caja de botones.

Funciones de acceso:

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

Véase también addButton().

Documentación de las funciones miembro

QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)

Construye una caja de botones horizontal vacía con la dirección parent.

Véase también orientation y addButton().

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

Construye una caja de botones horizontal con la dirección parent, que contiene los botones estándar especificados por buttons.

Véase también orientation y addButton().

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

Construye una caja de botones vacía con los datos orientation y parent.

Véase también orientation y addButton().

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

Construye una caja de botones con los datos orientation y parent, que contiene los botones estándar especificados por buttons.

Véase también orientation y addButton().

[virtual noexcept] QDialogButtonBox::~QDialogButtonBox()

Destruye la caja de botones.

[signal] void QDialogButtonBox::accepted()

Esta señal se emite cuando se pulsa un botón dentro de la caja de botones, siempre que se haya definido con las etiquetas AcceptRole o YesRole.

Véase también rejected(), clicked(), y helpRequested().

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

Añade un button estándar a la caja de botones si es válido hacerlo, y devuelve un pulsador. Si button no es válido, no se añade a la caja de botones, y se devuelve cero.

Véase también removeButton() y clear().

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

Añade el button dado a la caja de botones con el role especificado. Si el rol no es válido, el botón no se añade.

Si el botón ya se ha añadido, se elimina y se vuelve a añadir con el nuevo rol.

Nota: La caja de botones asume la propiedad del botón.

Véase también removeButton() y clear().

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

Crea un botón pulsador con la dirección text indicada, lo añade a la caja de botones de la dirección role especificada y devuelve el botón pulsador correspondiente. Si role no es válido, no se crea ningún botón y se devuelve cero.

Véase también removeButton() y clear().

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

Devuelve el QPushButton correspondiente al botón estándar which, o nullptr si el botón estándar no existe en esta caja de botones.

Véase también standardButton(), standardButtons() y buttons().

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

Devuelve la función de botón para el button especificado. Esta función devuelve InvalidRole si button es nullptr o no se ha añadido a la caja de botones.

Véase también buttons() y addButton().

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

Devuelve una lista de todos los botones que se han añadido a la caja de botones.

Véase también buttonRole(), addButton() y removeButton().

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

Reimplementa: QWidget::changeEvent(QEvent *event).

void QDialogButtonBox::clear()

Borra la caja de botones, eliminando todos los botones que contiene.

Véase también removeButton() y addButton().

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

Esta señal se emite cuando se pulsa un botón dentro de la caja de botones. El botón concreto que se ha pulsado se especifica en button.

Véase también accepted(), rejected() y helpRequested().

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

Reimplementa: QWidget::event(QEvent *event).

[signal] void QDialogButtonBox::helpRequested()

Esta señal se emite cuando se pulsa un botón dentro de la caja de botones, siempre que se haya definido con la opción HelpRole.

Véase también accepted(), rejected(), y clicked().

[signal] void QDialogButtonBox::rejected()

Esta señal se emite cuando se pulsa un botón dentro de la caja de botones, siempre que se haya definido con las etiquetas RejectRole o NoRole.

Véase también accepted(), helpRequested(), y clicked().

void QDialogButtonBox::removeButton(QAbstractButton *button)

Elimina button de la caja de botones sin borrarlo y pone su padre a cero.

Véase también clear(), buttons() y addButton().

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

Devuelve el valor enum del botón estándar correspondiente a button, o NoButton si button no es un botón estándar.

Véase también button(), buttons() y 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.