ButtonGroup QML Type
Grupo de botones de selección mutuamente excluyentes. Más...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
Propiedades
- buttons : list<AbstractButton>
- checkState : enumeration
(since QtQuick.Controls 2.4 (Qt 5.11)) - checkedButton : AbstractButton
- exclusive : bool
(since QtQuick.Controls 2.3 (Qt 5.10))
Propiedades adjuntas
- group : ButtonGroup
Señales
- clicked(AbstractButton button)
(since QtQuick.Controls 2.1 (Qt 5.8))
Métodos
- void addButton(AbstractButton button)
- void removeButton(AbstractButton button)
Descripción detallada
ButtonGroup es un grupo de botones no visual y mutuamente excluyente. Se utiliza con controles como RadioButton, en los que solo se puede seleccionar una de las opciones a la vez.
La forma más sencilla de utilizar ButtonGroup es asignarle una lista de botones. Por ejemplo, la lista de elementos hijos de un posicionador o de un diseño que gestione un grupo de botones mutuamente excluyentes.
ButtonGroup {
buttons: column.children
}
Column {
id: column
RadioButton {
checked: true
text: qsTr("DAB")
}
RadioButton {
text: qsTr("FM")
}
RadioButton {
text: qsTr("AM")
}
}Los botones mutuamente excluyentes no siempre comparten el mismo elemento padre, o en ocasiones el diseño padre puede contener elementos que no deberían incluirse en el grupo de botones. Estos casos se gestionan mejor utilizando la propiedad adjunta group.
ButtonGroup { id: radioGroup }
Column {
Label {
text: qsTr("Radio:")
}
RadioButton {
checked: true
text: qsTr("DAB")
ButtonGroup.group: radioGroup
}
RadioButton {
text: qsTr("FM")
ButtonGroup.group: radioGroup
}
RadioButton {
text: qsTr("AM")
ButtonGroup.group: radioGroup
}
}Otra opción es filtrar la lista de elementos hijos. Esto resulta especialmente útil si se utiliza un repetidor para rellenarla, ya que el repetidor también será un elemento hijo del diseño padre:
ButtonGroup {
buttons: column.children.filter((child) => child !== repeater)
}
Column {
id: column
Repeater {
id: repeater
model: [ qsTr("DAB"), qsTr("AM"), qsTr("FM") ]
RadioButton {
required property string modelData
text: modelData
}
}
}Los casos de uso más avanzados pueden gestionarse mediante los métodos ` addButton() ` y ` removeButton() `.
Véase también « RadioButton » y «Controles de botón».
Documentación de propiedades
buttons : list<AbstractButton>
Esta propiedad contiene la lista de botones.
ButtonGroup {
buttons: column.children
}
Column {
id: column
RadioButton {
checked: true
text: qsTr("Option A")
}
RadioButton {
text: qsTr("Option B")
}
}Véase también group.
checkState : enumeration [since QtQuick.Controls 2.4 (Qt 5.11)]
Esta propiedad contiene el estado de selección combinado del grupo de botones.
Estados disponibles:
| Constante | Descripción |
|---|---|
Qt.Unchecked | Ninguno de los botones está marcado. |
Qt.PartiallyChecked | Algunos de los botones están marcados. |
Qt.Checked | Todos los botones están marcados. |
Al establecer el estado de selección de un grupo de botones no exclusivos en « Qt.Unchecked » o « Qt.Checked », se desmarcan o se marcan todos los botones del grupo, respectivamente. Se ignora « Qt.PartiallyChecked ».
Al establecer el estado de selección de un grupo de botones exclusivo en « Qt.Unchecked », se desmarca el « checkedButton ». Se ignoran « Qt.Checked » y « Qt.PartiallyChecked ».
Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).
checkedButton : AbstractButton
Esta propiedad indica el botón seleccionado actualmente en un grupo exclusivo, o null si no hay ninguno o si el grupo no es exclusivo.
Por defecto, es el primer botón marcado que se añade a un grupo de botones exclusivo.
Véase también « exclusive ».
exclusive : bool [since QtQuick.Controls 2.3 (Qt 5.10)]
Esta propiedad indica si el grupo de botones es exclusivo. El valor por defecto es « true ».
Si esta propiedad es « true », solo se podrá marcar un botón del grupo en un momento dado. El usuario puede hacer clic en cualquier botón para marcarlo, y ese botón sustituirá al existente como botón marcado del grupo.
En un grupo exclusivo, el usuario no puede desmarcar el botón actualmente marcado haciendo clic en él; en su lugar, debe hacer clic en otro botón del grupo para establecer el nuevo botón marcado de dicho grupo.
En un grupo no exclusivo, marcar y desmarcar botones no afecta a los demás botones del grupo. Además, el valor de la propiedad ` checkedButton ` es ` null`.
Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).
Documentación de la propiedad adjunta
ButtonGroup.group : ButtonGroup [attached]
Esta propiedad asocia un botón a un grupo de botones.
ButtonGroup { id: group }
RadioButton {
checked: true
text: qsTr("Option A")
ButtonGroup.group: group
}
RadioButton {
text: qsTr("Option B")
ButtonGroup.group: group
}Véase también buttons.
Documentación sobre señales
[since QtQuick.Controls 2.1 (Qt 5.8)] clicked(AbstractButton button)
Esta señal se emite cuando se ha pulsado un « button » del grupo.
Esta señal resulta útil para implementar un controlador de señales común para todos los botones del mismo grupo.
ButtonGroup {
buttons: column.children
onClicked: button => {
console.log("clicked:", button.text)
}
}
Column {
id: column
Button { text: "First" }
Button { text: "Second" }
Button { text: "Third" }
}Nota: El controlador correspondiente es onClicked.
Esta señal se introdujo en QtQuick.Controls 2.1 (Qt 5.8).
Véase también AbstractButton::clicked().
Documentación del método
void addButton(AbstractButton button)
Añade un elemento « button » al grupo de botones.
Nota: Normalmente no es necesario añadir objetosmanualmente a un grupo de botones. La propiedad « buttons » y la propiedad adjunta « group » proporcionan una sintaxis cómoda y declarativa.
Véase también buttons y group.
void removeButton(AbstractButton button)
Elimina un objeto « button » del grupo de botones.
© 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.