En esta página

QDialogButtonBox Class

La clase QDialogButtonBox es un widget que muestra botones en una disposición adecuada al estilo del widget actual. Más información...

Encabezado: #include <QDialogButtonBox>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredan: 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()

Miembros públicos estáticos

(since 6.12) QKeySequence standardButtonShortcut(QDialogButtonBox::StandardButton button)
(since 6.12) QString standardButtonText(QDialogButtonBox::StandardButton button)

Funciones protegidas reimplementadas

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

Descripción detallada

Los cuadros de diálogo y los cuadros de mensaje suelen presentar botones en un diseño que se ajusta a las directrices de interfaz de cada plataforma. Como es habitual, las distintas plataformas tienen diseños diferentes para sus cuadros de diálogo. QDialogButtonBox permite al desarrollador añadirle botones y utilizará automáticamente el diseño adecuado para el entorno de escritorio del usuario.

La mayoría de los botones de un cuadro de diálogo cumplen determinadas funciones. Entre ellas se incluyen:

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

También puede haber formas alternativas de cerrar el cuadro de diálogo que puedan provocar 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 resulta conveniente crear estos botones de forma estándar.

Hay varias formas de utilizar QDialogButtonBox. Una de ellas consiste en crear los botones (o los textos de los botones) uno mismo y añadirlos al cuadro de botones, especificando su función.

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

Como alternativa, QDialogButtonBox proporciona varios botones estándar (por ejemplo, «Aceptar», «Cancelar» o «Guardar») que puedes utilizar. Estos se definen como indicadores, por lo que puedes combinarlos mediante el operador OR en el constructor.

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

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

Se pueden mezclar y combinar botones normales y botones estándar.

Actualmente, los botones se disponen de la siguiente manera si el cuadro de botones es horizontal:

Varios botones que utilizan la disposición horizontal de GnomeLayout GnomeLayout HorizontalCuadro de botones dispuesto en horizontal GnomeLayout
Varios botones que utilizan la disposición horizontal de KdeLayout KdeLayout HorizontalCuadro de botones dispuesto en horizontal KdeLayout
Varios botones que utilizan la disposición horizontal de MacLayout MacLayout HorizontalCuadro de botones dispuesto en horizontal MacLayout
Varios botones que utilizan la disposición horizontal de WinLayout WinLayout HorizontalCuadro de botones dispuesto en horizontal WinLayout

Los botones se disponen de la siguiente manera si el cuadro de botones es vertical:

Además, los cuadros de botones que solo contienen botones con « ActionRole » o « HelpRole » pueden considerarse «sin modo» y tienen un aspecto alternativo en macOS:

sin modo, horizontal MacLayoutVarios botones con el estilo horizontal no modal en macOS Captura de pantalla de «sin modo» horizontal MacLayout
sin modo vertical MacLayoutVarios botones con el estilo «horizontal sin modo» en macOS Captura de pantalla de sin modo vertical MacLayout

Al hacer clic en un botón del cuadro de botones, se emite la señal « clicked()» correspondiente al botón concreto que se ha pulsado. Para mayor comodidad, 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 concreto sea el predeterminado, debe llamar usted mismo a QPushButton::setDefault() sobre él. Sin embargo, si no hay ningún botón predeterminado establecido y para mantener cuál es el botón predeterminado en todas las plataformas al utilizar la propiedad QPushButton::autoDefault, el primer botón con el rol «accept» se convierte en el botón predeterminado cuando se muestra el QDialogButtonBox,

Véase también QMessageBox, QPushButton y QDialog.

Documentación sobre tipos de miembros

enum QDialogButtonBox::ButtonLayout

Esta enumeración describe la política de disposición que se debe utilizar al organizar los botones contenidos en el cuadro de botones.

ConstanteValorDescripción
QDialogButtonBox::WinLayout0Utiliza una política adecuada para aplicaciones en Windows.
QDialogButtonBox::MacLayout1Utiliza una política adecuada para aplicaciones en macOS.
QDialogButtonBox::KdeLayout2Utilice una política adecuada para aplicaciones en KDE.
QDialogButtonBox::GnomeLayout3Utiliza una política adecuada para aplicaciones en GNOME.
QDialogButtonBox::AndroidLayout4Utiliza una política adecuada para aplicaciones en Android. Este valor de enumeración se añadió en Qt 5.10.

La disposición de los botones viene determinada por la propiedad ` current style`. Sin embargo, en la plataforma X11, puede verse influida por el entorno de escritorio.

enum QDialogButtonBox::ButtonRole

Esta enumeración describe las funciones que se pueden utilizar para definir los botones del cuadro de botones. Las combinaciones de estas funciones se utilizan como indicadores 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 cuadro de diálogo (p. ej., «Aceptar»).
QDialogButtonBox::RejectRole1Al hacer clic en el botón, se rechaza el cuadro de diálogo (p. ej., «Cancelar»).
QDialogButtonBox::DestructiveRole2Al hacer clic en el botón se produce un cambio destructivo (p. ej., al descartar cambios) y se cierra el cuadro de diálogo.
QDialogButtonBox::ActionRole3Al hacer clic en el botón, se modifican los elementos del cuadro de diálogo.
QDialogButtonBox::HelpRole4Se puede hacer clic en el botón para solicitar ayuda.
QDialogButtonBox::YesRole5El botón es similar a un botón de «Sí».
QDialogButtonBox::NoRole6El botón es similar a un «No».
QDialogButtonBox::ApplyRole8El botón aplica los cambios actuales.
QDialogButtonBox::ResetRole7El botón restablece los campos del cuadro de diálogo a sus valores predeterminados.

Véase también StandardButton.

enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons

Estas enumeraciones describen los indicadores de los botones estándar. Cada botón tiene un ButtonRole definido.

ConstanteValorDescripción
QDialogButtonBox::Ok0x00000400Un botón «OK» definido con el AcceptRole.
QDialogButtonBox::Open0x00002000Un botón «Abrir» definido con la AcceptRole.
QDialogButtonBox::Save0x00000800Un botón «Guardar» definido con el AcceptRole.
QDialogButtonBox::Cancel0x00400000Un botón «Cancelar» definido con el RejectRole.
QDialogButtonBox::Close0x00200000Un botón «Cerrar» definido con la función ` RejectRole`.
QDialogButtonBox::Discard0x00800000Un botón «Descartar» o «No guardar», dependiendo de la plataforma, definido con el DestructiveRole.
QDialogButtonBox::Apply0x02000000Un botón «Aplicar» definido con la función ` ApplyRole`.
QDialogButtonBox::Reset0x04000000Un botón «Restablecer» definido con la función ` ResetRole`.
QDialogButtonBox::RestoreDefaults0x08000000Un botón «Restablecer valores predeterminados» definido con la propiedad ` ResetRole`.
QDialogButtonBox::Help0x01000000Un botón «Ayuda» definido con el HelpRole.
QDialogButtonBox::SaveAll0x00001000Un botón «Guardar todo» definido con la función AcceptRole.
QDialogButtonBox::Yes0x00004000Un botón «Sí» definido con el YesRole.
QDialogButtonBox::YesToAll0x00008000Un botón «Sí a todo» definido con el YesRole.
QDialogButtonBox::No0x00010000Un botón «No» definido con NoRole.
QDialogButtonBox::NoToAll0x00020000Un botón «No a todo» definido con el atributo NoRole.
QDialogButtonBox::Abort0x00040000Un botón «Abortar» definido con RejectRole.
QDialogButtonBox::Retry0x00080000Un botón «Reintentar» definido con el AcceptRole.
QDialogButtonBox::Ignore0x00100000Un botón «Ignorar» definido con la función AcceptRole.
QDialogButtonBox::NoButton0x00000000Un botón no válido.

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

Véase también ButtonRole y standardButtons.

Documentación de propiedades

centerButtons : bool

Esta propiedad determina si los botones del cuadro de botones están centrados

Por defecto, esta propiedad tiene el valor « false ». Este comportamiento es adecuado para la mayoría de los tipos de cuadros de diálogo. Una excepción notable son los cuadros de mensaje en la mayoría de las plataformas (por ejemplo, Windows), donde el cuadro de botones está centrado horizontalmente.

Funciones de Access:

bool centerButtons() const
void setCenterButtons(bool center)

Véase también « QMessageBox ».

orientation : Qt::Orientation

Esta propiedad determina la orientación del cuadro de botones

Por defecto, la orientación es horizontal (es decir, los botones se disponen 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

Conjunto de botones estándar del cuadro de botones

Esta propiedad controla qué botones estándar utiliza el cuadro de botones.

Funciones de Access:

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

Véase también addButton().

Documentación de funciones de miembro

QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)

Crea un cuadro de botón horizontal vacío con el parent especificado.

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

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

Crea un cuadro de botones horizontal con el parent indicado, que contiene los botones estándar especificados por buttons.

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

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

Crea un cuadro de botón vacío con los valores indicados en « orientation » y « parent ».

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

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

Crea un cuadro de botones con los valores proporcionados en « orientation » y « parent », que contiene los botones estándar especificados en « 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 hace clic en un botón dentro del cuadro de botones, siempre y cuando se haya definido con la propiedad « AcceptRole » o « YesRole ».

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

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

Añade un objeto ` button ` estándar al cuadro de botones si es válido hacerlo, y devuelve un botón pulsador. Si ` button ` no es válido, no se añade al cuadro 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 » indicado al cuadro 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: El cuadro 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 con el texto « text » indicado, lo añade al cuadro de botones correspondiente a la dirección « role » especificada y devuelve el botón 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 objeto ` QPushButton ` correspondiente al botón estándar ` which`, o ` nullptr ` si el botón estándar no existe en este cuadro de botones.

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

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

Devuelve el rol del botón para el button especificado. Esta función devuelve InvalidRole si button es nullptr o no se ha añadido al cuadro 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 al cuadro 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 el cuadro 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 hace clic en un botón dentro del cuadro de botones. El botón concreto que se ha pulsado se especifica mediante ` 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 hace clic en un botón dentro del cuadro de botones, siempre y cuando se haya definido con la propiedad « HelpRole ».

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

[signal] void QDialogButtonBox::rejected()

Esta señal se emite cuando se hace clic en un botón dentro del cuadro de botones, siempre y cuando se haya definido con « RejectRole » o « NoRole ».

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

void QDialogButtonBox::removeButton(QAbstractButton *button)

Elimina « button » del cuadro de botones sin borrarlo y establece su elemento padre en cero.

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

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

Devuelve el valor de la enumeración de botones estándar correspondiente al button dado, o bien NoButton si el button dado no es un botón estándar.

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

[static, since 6.12] QKeySequence QDialogButtonBox::standardButtonShortcut(QDialogButtonBox::StandardButton button)

Devuelve el atajo de teclado correspondiente al botón estándar « button ». El atajo depende de la plataforma. Devuelve un objeto « QKeySequence » vacío si « button » no tiene ningún atajo asociado o no es un botón estándar reconocido.

Esta función se introdujo en Qt 6.12.

Véase también standardButtonText() y StandardButton.

[static, since 6.12] QString QDialogButtonBox::standardButtonText(QDialogButtonBox::StandardButton button)

Devuelve el texto que se muestra en el botón estándar « button », tal y como aparece en la etiqueta del botón. El texto depende de la plataforma y de la configuración regional.

Devuelve una cadena vacía si « button » no es un botón estándar reconocido.

Esta función se introdujo en Qt 6.12.

Véase también « standardButtonShortcut()» y « 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.