Qt 5.8 | Qt Quick Controls 2 | QML Types | ButtonGroup QML Type

Qt 5.8.0 Reference Documentation

# ButtonGroup QML Type

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

Import Statement: | import QtQuick.Controls 2.1
Since: | Qt 5.7

- List of all members, including inherited members

## Properties

- buttons : list<AbstractButton>
- checkedButton : AbstractButton

## Attached Properties

- group : ButtonGroup

## Signals

- void clicked(AbstractButton button)

## Methods

- void addButton(AbstractButton button)
- void removeButton(AbstractButton button)

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

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

See also RadioButton and Button Controls.

## Property Documentation

[default] 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.

checkedButton : AbstractButton

This property holds the currently selected button, or `null` if there is none.

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

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

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

This QML signal was introduced in QtQuick.Controls 2.1.

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.