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
- centerButtons : bool
- orientation : Qt::Orientation
- standardButtons : StandardButtons
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:
GnomeLayout Horizontal | Caja de botones dispuesta en horizontal GnomeLayout |
KdeLayout Horizontal | Caja de botones en horizontal KdeLayout |
MacLayout Horizontal | Botonera horizontal MacLayout |
WinLayout Horizontal | Caja de botones en horizontal WinLayout |
La disposición de los botones es la siguiente si la caja de botones es vertical:
| GnomeLayout | KdeLayout | MacLayout | WinLayout |
GnomeLayout Vertical | KdeLayout Vertical | MacLayout Vertical | WinLayout 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 MacLayout | Captura de pantalla de modeless horizontal MacLayout |
| modeless vertical MacLayout | 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.
| Constante | Valor | Descripción |
|---|---|---|
QDialogButtonBox::WinLayout | 0 | Utilizar una política apropiada para aplicaciones en Windows. |
QDialogButtonBox::MacLayout | 1 | Utilizar una política apropiada para aplicaciones en macOS. |
QDialogButtonBox::KdeLayout | 2 | Usar una política apropiada para aplicaciones en KDE. |
QDialogButtonBox::GnomeLayout | 3 | Utilice una política apropiada para aplicaciones en GNOME. |
QDialogButtonBox::AndroidLayout | 4 | Utilizar 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.
| Constante | Valor | Descripción |
|---|---|---|
QDialogButtonBox::InvalidRole | -1 | El botón no es válido. |
QDialogButtonBox::AcceptRole | 0 | Al hacer clic en el botón, se acepta el diálogo (p. ej., Aceptar). |
QDialogButtonBox::RejectRole | 1 | Al hacer clic en el botón se rechaza el diálogo (por ejemplo, Cancelar). |
QDialogButtonBox::DestructiveRole | 2 | Al 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::ActionRole | 3 | Pulsar el botón provoca cambios en los elementos del diálogo. |
QDialogButtonBox::HelpRole | 4 | Se puede pulsar el botón para solicitar ayuda. |
QDialogButtonBox::YesRole | 5 | El botón es del tipo "Sí". |
QDialogButtonBox::NoRole | 6 | El botón es similar a "No". |
QDialogButtonBox::ApplyRole | 8 | El botón aplica los cambios actuales. |
QDialogButtonBox::ResetRole | 7 | El 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.
| Constante | Valor | Descripción |
|---|---|---|
QDialogButtonBox::Ok | 0x00000400 | Botón "OK" definido con el parámetro AcceptRole. |
QDialogButtonBox::Open | 0x00002000 | Botón "Abrir" definido en AcceptRole. |
QDialogButtonBox::Save | 0x00000800 | Botón "Guardar" definido en AcceptRole. |
QDialogButtonBox::Cancel | 0x00400000 | Botón "Cancelar" definido en RejectRole. |
QDialogButtonBox::Close | 0x00200000 | Botón "Cerrar" definido en RejectRole. |
QDialogButtonBox::Discard | 0x00800000 | Un botón "Descartar" o "No guardar", según la plataforma, definido en DestructiveRole. |
QDialogButtonBox::Apply | 0x02000000 | Un botón "Aplicar" definido en ApplyRole. |
QDialogButtonBox::Reset | 0x04000000 | Un botón "Restablecer" definido en ResetRole. |
QDialogButtonBox::RestoreDefaults | 0x08000000 | Un botón "Restaurar valores predeterminados" definido en ResetRole. |
QDialogButtonBox::Help | 0x01000000 | Botón "Ayuda" definido en HelpRole. |
QDialogButtonBox::SaveAll | 0x00001000 | Botón "Guardar todo" definido en AcceptRole. |
QDialogButtonBox::Yes | 0x00004000 | Botón "Sí" definido en YesRole. |
QDialogButtonBox::YesToAll | 0x00008000 | Botón "Sí a todo" definido en YesRole. |
QDialogButtonBox::No | 0x00010000 | Botón "No" definido en NoRole. |
QDialogButtonBox::NoToAll | 0x00020000 | Botón "No a todo" definido en NoRole. |
QDialogButtonBox::Abort | 0x00040000 | Botón "Abortar" definido en RejectRole. |
QDialogButtonBox::Retry | 0x00080000 | Botón "Reintentar" definido en AcceptRole. |
QDialogButtonBox::Ignore | 0x00100000 | Botón "Ignorar" definido en AcceptRole. |
QDialogButtonBox::NoButton | 0x00000000 | Un 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.
Captura de pantalla de modeless horizontal
Captura de pantalla de modeless vertical