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
- 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() |
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:
GnomeLayout Horizontal | Cuadro de botones dispuesto en horizontal GnomeLayout |
KdeLayout Horizontal | Cuadro de botones dispuesto en horizontal KdeLayout |
MacLayout Horizontal | Cuadro de botones dispuesto en horizontal MacLayout |
WinLayout Horizontal | Cuadro de botones dispuesto en horizontal WinLayout |
Los botones se disponen de la siguiente manera si el cuadro de botones es vertical:
| GnomeLayout | KdeLayout | MacLayout | WinLayout |
GnomeLayout Vertical | KdeLayout Vertical | MacLayout Vertical | WinLayout 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 MacLayout | Captura de pantalla de «sin modo» horizontal MacLayout |
| sin modo vertical MacLayout | 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.
| Constante | Valor | Descripción |
|---|---|---|
QDialogButtonBox::WinLayout | 0 | Utiliza una política adecuada para aplicaciones en Windows. |
QDialogButtonBox::MacLayout | 1 | Utiliza una política adecuada para aplicaciones en macOS. |
QDialogButtonBox::KdeLayout | 2 | Utilice una política adecuada para aplicaciones en KDE. |
QDialogButtonBox::GnomeLayout | 3 | Utiliza una política adecuada para aplicaciones en GNOME. |
QDialogButtonBox::AndroidLayout | 4 | Utiliza 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.
| 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 cuadro de diálogo (p. ej., «Aceptar»). |
QDialogButtonBox::RejectRole | 1 | Al hacer clic en el botón, se rechaza el cuadro de diálogo (p. ej., «Cancelar»). |
QDialogButtonBox::DestructiveRole | 2 | Al 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::ActionRole | 3 | Al hacer clic en el botón, se modifican los elementos del cuadro de diálogo. |
QDialogButtonBox::HelpRole | 4 | Se puede hacer clic en el botón para solicitar ayuda. |
QDialogButtonBox::YesRole | 5 | El botón es similar a un botón de «Sí». |
QDialogButtonBox::NoRole | 6 | El botón es similar a un «No». |
QDialogButtonBox::ApplyRole | 8 | El botón aplica los cambios actuales. |
QDialogButtonBox::ResetRole | 7 | El 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.
| Constante | Valor | Descripción |
|---|---|---|
QDialogButtonBox::Ok | 0x00000400 | Un botón «OK» definido con el AcceptRole. |
QDialogButtonBox::Open | 0x00002000 | Un botón «Abrir» definido con la AcceptRole. |
QDialogButtonBox::Save | 0x00000800 | Un botón «Guardar» definido con el AcceptRole. |
QDialogButtonBox::Cancel | 0x00400000 | Un botón «Cancelar» definido con el RejectRole. |
QDialogButtonBox::Close | 0x00200000 | Un botón «Cerrar» definido con la función ` RejectRole`. |
QDialogButtonBox::Discard | 0x00800000 | Un botón «Descartar» o «No guardar», dependiendo de la plataforma, definido con el DestructiveRole. |
QDialogButtonBox::Apply | 0x02000000 | Un botón «Aplicar» definido con la función ` ApplyRole`. |
QDialogButtonBox::Reset | 0x04000000 | Un botón «Restablecer» definido con la función ` ResetRole`. |
QDialogButtonBox::RestoreDefaults | 0x08000000 | Un botón «Restablecer valores predeterminados» definido con la propiedad ` ResetRole`. |
QDialogButtonBox::Help | 0x01000000 | Un botón «Ayuda» definido con el HelpRole. |
QDialogButtonBox::SaveAll | 0x00001000 | Un botón «Guardar todo» definido con la función AcceptRole. |
QDialogButtonBox::Yes | 0x00004000 | Un botón «Sí» definido con el YesRole. |
QDialogButtonBox::YesToAll | 0x00008000 | Un botón «Sí a todo» definido con el YesRole. |
QDialogButtonBox::No | 0x00010000 | Un botón «No» definido con NoRole. |
QDialogButtonBox::NoToAll | 0x00020000 | Un botón «No a todo» definido con el atributo NoRole. |
QDialogButtonBox::Abort | 0x00040000 | Un botón «Abortar» definido con RejectRole. |
QDialogButtonBox::Retry | 0x00080000 | Un botón «Reintentar» definido con el AcceptRole. |
QDialogButtonBox::Ignore | 0x00100000 | Un botón «Ignorar» definido con la función 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 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.
Captura de pantalla de «sin modo» horizontal
Captura de pantalla de sin modo vertical