Back to Qt.io
Contact Us Blog Download Qt

ButtonGroup QML Type

Mutually-exclusive group of checkable buttons. More...

Import Statement: import QtQuick.Controls
Inherits:

QtObject

Properties

Attached Properties

Signals

Methods

Detailed Description

ButtonGroup is a non-visual, mutually exclusive group of buttons. It is used with controls such as RadioButton, where only one of the options can be selected at a time.

The most straight-forward way to use ButtonGroup is to assign a list of buttons. For example, the list of children of a positioner or a layout that manages a group of mutually exclusive buttons.

ButtonGroup {
    buttons: column.children
}

Column {
    id: column

    RadioButton {
        checked: true
        text: qsTr("DAB")
    }

    RadioButton {
        text: qsTr("FM")
    }

    RadioButton {
        text: qsTr("AM")
    }
}

Mutually exclusive buttons do not always share the same parent item, or the parent layout may sometimes contain items that should not be included in the button group. Such cases are best handled using the group attached property.

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
    }
}

Another option is to filter the list of children. This is especially handy if you're using a repeater to populate it, since the repeater will also be a child of the parent layout:

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
        }
    }
}

More advanced use cases can be handled using the addButton() and removeButton() methods.

See also RadioButton and Button Controls.

Property Documentation

buttons : list<AbstractButton>

This property holds the list of buttons.

ButtonGroup {
    buttons: column.children
}

Column {
    id: column

    RadioButton {
        checked: true
        text: qsTr("Option A")
    }

    RadioButton {
        text: qsTr("Option B")
    }
}

See also group.


[since QtQuick.Controls 2.4 (Qt 5.11)] checkState : enumeration

This property holds the combined check state of the button group.

Available states:

ConstantDescription
Qt.UncheckedNone of the buttons are checked.
Qt.PartiallyCheckedSome of the buttons are checked.
Qt.CheckedAll of the buttons are checked.

Setting the check state of a non-exclusive button group to Qt.Unchecked or Qt.Checked unchecks or checks all buttons in the group, respectively. Qt.PartiallyChecked is ignored.

Setting the check state of an exclusive button group to Qt.Unchecked unchecks the checkedButton. Qt.Checked and Qt.PartiallyChecked are ignored.

This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).


checkedButton : AbstractButton

This property holds the currently selected button in an exclusive group, or null if there is none or the group is non-exclusive.

By default, it is the first checked button added to an exclusive button group.

See also exclusive.


[since QtQuick.Controls 2.3 (Qt 5.10)] exclusive : bool

This property holds whether the button group is exclusive. The default value is true.

If this property is true, then only one button in the group can be checked at any given time. The user can click on any button to check it, and that button will replace the existing one as the checked button in the group.

In an exclusive group, the user cannot uncheck the currently checked button by clicking on it; instead, another button in the group must be clicked to set the new checked button for that group.

In a non-exclusive group, checking and unchecking buttons does not affect the other buttons in the group. Furthermore, the value of the checkedButton property is null.

This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).


Attached Property Documentation

ButtonGroup.group : ButtonGroup

This property attaches a button to a button group.

ButtonGroup { id: group }

RadioButton {
    checked: true
    text: qsTr("Option A")
    ButtonGroup.group: group
}

RadioButton {
    text: qsTr("Option B")
    ButtonGroup.group: group
}

See also buttons.


Signal Documentation

[since QtQuick.Controls 2.1 (Qt 5.8)] clicked(AbstractButton button)

This signal is emitted when a button in the group has been clicked.

This signal is convenient for implementing a common signal handler for all buttons in the same group.

ButtonGroup {
    buttons: column.children
    onClicked: console.log("clicked:", button.text)
}

Column {
    id: column
    Button { text: "First" }
    Button { text: "Second" }
    Button { text: "Third" }
}

Note: The corresponding handler is onClicked.

This signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

See also AbstractButton::clicked().


Method Documentation

void addButton(AbstractButton button)

Adds a button to the button group.

Note: Manually adding objects to a button group is typically unnecessary. The buttons property and the group attached property provide a convenient and declarative syntax.

See also buttons and group.


void removeButton(AbstractButton button)

Removes a button from the button group.

Note: Manually removing objects from a button group is typically unnecessary. The buttons property and the group attached property provide a convenient and declarative syntax.

See also buttons and group.


© 2024 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.