En esta página

DialogButtonBox QML Type

Un cuadro de botones que se utiliza en los cuadros de diálogo. Más...

Import Statement: import QtQuick.Controls
Inherits:

Container

Propiedades

Propiedades adjuntas

Señales

Métodos

Descripción detallada

Los cuadros de diálogo y los cuadros de mensaje suelen presentar los botones en un orden que se ajusta a las directrices de interfaz de cada plataforma. Inevitablemente, las diferentes plataformas tienen los botones de los cuadros de diálogo en órdenes distintas. DialogButtonBox permite al desarrollador añadirle botones y utilizará automáticamente el orden adecuado para la plataforma 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 indeseados.

La mayoría de los cuadros de diálogo cuentan con 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 DialogButtonBox. Una de ellas consiste en especificar los botones estándar (p. ej., « OK », « Cancel » y « Save ») y dejar que el cuadro de botones se encargue de configurarlos.

Cuadro de diálogo con los botones «Aceptar» y «Cancelar»

DialogButtonBox {
    standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}

Como alternativa, los botones y sus funciones se pueden especificar manualmente:

DialogButtonBox {
    Button {
        text: qsTr("Save")
        DialogButtonBox.buttonRole: DialogButtonBox.AcceptRole
    }
    Button {
        text: qsTr("Close")
        DialogButtonBox.buttonRole: DialogButtonBox.DestructiveRole
    }
}

También puedes combinar botones normales y botones estándar.

Al hacer clic en un botón del cuadro de botones, se emite la señal clicked() correspondiente al botón que se ha pulsado. Además, se emiten automáticamente las siguientes señales cuando se pulsa un botón con las funciones respectivas:

FunciónSeñal
AcceptRole, YesRoleaccepted()
ApplyRoleapplied()
DiscardRolediscarded()
HelpRolehelpRequested()
RejectRole, NoRolerejected()
ResetRolereset()

Véase también Dialog.

Documentación de la propiedad

alignment : flags

Esta propiedad determina la alineación de los botones.

Valores posibles:

ConstanteDescripción
Qt.AlignLeftLos botones están alineados a la izquierda.
Qt.AlignHCenterLos botones están centrados horizontalmente.
Qt.AlignRightLos botones están alineados a la derecha.
Qt.AlignTopLos botones están alineados en la parte superior.
Qt.AlignVCenterLos botones están centrados verticalmente.
Qt.AlignBottomLos botones están alineados en la parte inferior.

De forma predeterminada, no se establece ninguna alineación específica; al leer la propiedad de alineación se obtiene un valor de indicador predeterminado equivalente a 0. La propiedad se puede restablecer a este valor asignándole el valor « undefined ». En este caso, los botones se redimensionan para ocupar todo el espacio disponible.

Nota: Esta propiedad asume una disposición horizontal de los botones. Ten en cuenta que, al ejecutar el estilo iOS, el control « DialogButtonBox » utilizará una disposición vertical si esta propiedad se establece en cualquier valor distinto de « undefined » y hay más de dos botones. En todos los demás casos, los botones se dispondrán horizontalmente.

buttonLayout : enumeration [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene la política de disposición de botones que se utilizará al organizar los botones que contiene el cuadro de botones. El valor por defecto depende de la plataforma.

Valores disponibles:

ConstanteDescripción
DialogButtonBox.WinLayoutUtiliza una política adecuada para aplicaciones en Windows.
DialogButtonBox.MacLayoutUtiliza una política adecuada para aplicaciones en macOS.
DialogButtonBox.KdeLayoutUtiliza una política adecuada para aplicaciones en KDE.
DialogButtonBox.GnomeLayoutUtiliza una política adecuada para las aplicaciones en GNOME.
DialogButtonBox.AndroidLayoutUtiliza una política adecuada para aplicaciones en Android.

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

defaultButton : AbstractButton [since 6.11]

Esta propiedad contiene el botón predeterminado.

El botón predeterminado será highlighted y recibirá el foco.

Solo se puede establecer como predeterminado un botón del cuadro de botones. Esta propiedad no se puede utilizar junto con la propiedad « defaultStandardButton ».

Esta propiedad se introdujo en Qt 6.11.

Véase también « standardButtons » y « defaultStandardButton ».

defaultStandardButton : enumeration [since 6.11]

Esta propiedad contiene el botón estándar predeterminado.

El botón estándar predeterminado será highlighted y recibirá el foco.

Solo se puede establecer como predeterminado un botón del cuadro de botones. Esta propiedad no se puede utilizar junto con la propiedad « defaultButton ».

Esta propiedad se introdujo en Qt 6.11.

Véase también « standardButtons » y « defaultButton ».

delegate : Component

Esta propiedad contiene un delegado para crear botones estándar.

DialogButtonBox No asume la propiedad del delegado.

Véase también standardButtons.

position : enumeration

Esta propiedad determina la posición del cuadro de botones.

Nota: Si el cuadro de botones se asigna como encabezado o pie de página de un ApplicationWindow o o una página, la posición adecuada se establece automáticamente.

Valores posibles:

ConstanteDescripción
DialogButtonBox.HeaderEl cuadro de botones se encuentra en la parte superior, como encabezado de una ventana o de una página.
DialogButtonBox.FooterEl cuadro de botones se encuentra en la parte inferior, como pie de página de una ventana o página.

El valor por defecto es « Footer ».

Véase también Dialog::header y Dialog::footer.

standardButtons : enumeration

Esta propiedad contiene una combinación de botones estándar que utiliza el cuadro de botones.

DialogButtonBox {
    standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel

    onAccepted: console.log("Ok clicked")
    onRejected: console.log("Cancel clicked")
}

Los botones se colocarán en el orden adecuado para la plataforma del usuario.

Posibles indicadores:

ConstanteDescripción
DialogButtonBox.OkUn botón «Aceptar» definido con la propiedad « AcceptRole ».
DialogButtonBox.OpenUn botón «Abrir» definido con la función ` AcceptRole`.
DialogButtonBox.SaveUn botón «Guardar» definido con la función « AcceptRole ».
DialogButtonBox.CancelUn botón «Cancelar» definido con el RejectRole.
DialogButtonBox.CloseUn botón «Cerrar» definido con la función ` RejectRole`.
DialogButtonBox.DiscardUn botón «Descartar» o «No guardar», dependiendo de la plataforma, definido con el DestructiveRole.
DialogButtonBox.ApplyUn botón «Aplicar» definido con ` ApplyRole`.
DialogButtonBox.ResetUn botón «Restablecer» definido con la función ` ResetRole`.
DialogButtonBox.RestoreDefaultsUn botón «Restablecer valores predeterminados» definido con la propiedad ResetRole.
DialogButtonBox.HelpUn botón «Ayuda» definido con la clase ` HelpRole`.
DialogButtonBox.SaveAllUn botón «Guardar todo» definido con el AcceptRole.
DialogButtonBox.YesUn botón «Sí» definido con el YesRole.
DialogButtonBox.YesToAllUn botón «Sí a todo» definido con el YesRole.
DialogButtonBox.NoUn botón «No» definido con el NoRole.
DialogButtonBox.NoToAllUn botón «No a todo» definido con el NoRole.
DialogButtonBox.AbortUn botón «Abortar» definido con RejectRole.
DialogButtonBox.RetryUn botón «Reintentar» definido con el AcceptRole.
DialogButtonBox.IgnoreUn botón «Ignorar» definido con la función AcceptRole.
DialogButtonBox.NoButtonUn botón no válido.

Véase también standardButton().

Documentación de propiedades asociadas

DialogButtonBox.buttonBox : DialogButtonBox [read-only attached]

Esta propiedad asociada contiene el cuadro de botones que gestiona este botón, o bien null si el botón no se encuentra en ningún cuadro de botones.

DialogButtonBox.buttonRole : enumeration [attached]

Esta propiedad adjunta define la función de cada botón en un cuadro de botones.

DialogButtonBox {
    Button {
        text: qsTr("Save")
        DialogButtonBox.buttonRole: DialogButtonBox.AcceptRole
    }
    Button {
        text: qsTr("Close")
        DialogButtonBox.buttonRole: DialogButtonBox.DestructiveRole
    }
}

Valores disponibles:

ConstanteDescripción
DialogButtonBox.InvalidRoleEl botón no es válido.
DialogButtonBox.AcceptRoleAl hacer clic en el botón, se acepta el cuadro de diálogo (p. ej., OK).
DialogButtonBox.RejectRoleAl hacer clic en el botón, se rechaza el cuadro de diálogo (p. ej., Cancel).
DialogButtonBox.DestructiveRoleAl hacer clic en el botón se produce un cambio destructivo (p. ej., para descartar cambios) y se cierra el cuadro de diálogo.
DialogButtonBox.ActionRoleAl hacer clic en el botón se modifican los elementos del cuadro de diálogo.
DialogButtonBox.HelpRoleSe puede hacer clic en el botón para solicitar ayuda.
DialogButtonBox.YesRoleEl botón es similar al de «Sí».
DialogButtonBox.NoRoleEl botón es similar a un botón de «No».
DialogButtonBox.ResetRoleEl botón restablece los campos del cuadro de diálogo a sus valores predeterminados.
DialogButtonBox.ApplyRoleEl botón aplica los cambios actuales.

Documentación de Signal

accepted()

Esta señal se emite cuando se hace clic en un botón definido con AcceptRole o YesRole.

Nota: El controlador correspondiente es onAccepted.

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

[since QtQuick.Controls 2.3 (Qt 5.10)] applied()

Esta señal se emite cuando se pulsa un botón definido con el control « ApplyRole ».

Nota: El controlador correspondiente es onApplied.

Esta señal se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también ` discarded()` y ` reset()`.

clicked(AbstractButton button)

Esta señal se emite cuando se hace clic en un « button » dentro del cuadro del botón.

Nota: El controlador correspondiente es ` onClicked`.

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

[since QtQuick.Controls 2.3 (Qt 5.10)] discarded()

Esta señal se emite cuando se pulsa un botón definido con el control « DiscardRole ».

Nota: El controlador correspondiente es onDiscarded.

Esta señal se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también ` reset()` y ` applied()`.

helpRequested()

Esta señal se emite cuando se hace clic en un botón definido con el HelpRole.

Nota: El controlador correspondiente es onHelpRequested.

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

rejected()

Esta señal se emite cuando se pulsa un botón definido con RejectRole o NoRole.

Nota: El controlador correspondiente es onRejected.

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

[since QtQuick.Controls 2.3 (Qt 5.10)] reset()

Esta señal se emite cuando se hace clic en un botón definido con el control « ResetRole ».

Nota: El controlador correspondiente es onReset.

Esta señal se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también discarded() y applied().

Documentación del método

AbstractButton standardButton(StandardButton button)

Devuelve el archivo de configuración estándar especificado « button » o « null » si no existe.

Véase también 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.