Back to Qt.io
Contact Us Blog Download Qt

ButtonGroup QML Type

チェック可能なボタンの相互排他的グループ。もっと見る...

Import Statement: import QtQuick.Controls
Inherits:

QtObject

プロパティ

付属物件

信号

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

方法

詳細説明

ButtonGroup は、視覚的でない、相互に排他的なボタンのグループです。これは、RadioButton のような、一度に1つのオプションしか選択できないコントロールで使用されます。

ButtonGroupを使用する最も簡単な方法は、ボタンのリストを割り当てることです。例えば、ポジショナーの子のリストや、相互に排他的なボタンのグループを管理するレイアウトなどです。

ButtonGroup {
    buttons: column.children
}

Column {
    id: column

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

    RadioButton {
        text: qsTr("FM")
    }

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

互いに排他的なボタンは、常に同じ親アイテムを共有するとは限りませんし、親レイアウトには、ボタングループに含めるべきではないアイテムが含まれていることもあります。このような場合は、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
    }
}

もう一つのオプションは、子アイテムのリストをフィルタリングすることです。リピーターも親レイアウトの子になるため、リピーターを使って入力する場合は特に便利です：

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

より高度なユースケースは、addButton() とremoveButton() メソッドで処理できます。

RadioButton 、ボタンコントロールも参照してください 。

プロパティの説明

buttons : list<AbstractButton>

このプロパティは、ボタンのリストを保持します。

ButtonGroup {
    buttons: column.children
}

Column {
    id: column

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

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

groupも参照してください 。


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

このプロパティは、ボタングループの複合チェック状態を保持します。

利用可能な状態

定数説明
Qt.Uncheckedどのボタンもチェックされていない。
Qt.PartiallyCheckedいくつかのボタンがチェックされています。
Qt.Checkedすべてのボタンがチェックされている。

非排他的ボタングループのチェック状態をQt.Unchecked またはQt.Checked に設定すると、それぞれグループ内のすべてのボタンのチェックを解除またはチェックします。Qt.PartiallyChecked は無視されます。

排他的ボタングループのチェック状態をQt.Unchecked に設定すると、checkedButton のチェックが解除されます。Qt.Checked とQt.PartiallyChecked は無視されます。

このプロパティは、QtQuick.Controls 2.4（Qt 5.11）で導入されました。


checkedButton : AbstractButton

このプロパティは、排他的グループ内の現在選択されているボタンを保持します。排他的グループがない場合、またはグループが非排他的な場合は、null 。

デフォルトでは、排他的なボタングループに追加された最初のチェックされたボタンです。

exclusiveも参照 。


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

このプロパティは、ボタングループが排他的であるかどうかを保持します。デフォルト値はtrue です。

このプロパティがtrue の場合、グループ内のボタンは常に1つしかチェックできません。ユーザは任意のボタンをクリックしてチェックすることができ、そのボタンはグループ内のチェックされたボタンとして既存のボタンに取って代わります。

排他的グループでは、ユーザーは現在チェックされているボタンをクリックしてもチェックを外すことはできません。代わりに、グループ内の別のボタンをクリックして、そのグループの新しいチェック済みボタンを設定する必要があります。

非排他的グループでは、ボタンをチェックしたり、チェックを外したりしても、グループ内の他のボタンには影響しません。さらに、checkedButton プロパティの値はnull です。

このプロパティは、QtQuick.Controls 2.3（Qt 5.10）で導入されました。


Attached プロパティの説明

ButtonGroup.group : ButtonGroup

このプロパティは、ボタンをボタングループにアタッチします。

ButtonGroup { id: group }

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

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

buttonsも参照してください 。


Signal ドキュメント

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

このシグナルは、グループ内のbutton がクリックされたときに発行されます。

このシグナルは、同じグループ内のすべてのボタンに対して共通のシグナルハンドラを実装するのに便利です。

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

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

注意: 対応するハンドラはonClicked です。

このシグナルは QtQuick.Controls 2.1 (Qt 5.8) で導入されました。

AbstractButton::clicked()も参照してください 。


メソッドの説明

void addButton(AbstractButton button)

ボタングループにbutton を追加します。

注意: 手動でオブジェクトをボタングループに追加することは通常不要です。buttons プロパティとgroup attached プロパティは、便利で宣言的な構文を提供します。

buttons とgroupも参照してください 。


void removeButton(AbstractButton button)

ボタングループからbutton を削除します。

注意： ボタングループからオブジェクトを手動で削除することは通常不要です。buttons プロパティとgroup attached プロパティは、便利で宣言的な構文を提供します。

buttons およびgroupも参照してください 。


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