ComboBox QML Type

オプションを選択するためのボタンとポップアップリストを組み合わせたもの。詳細...

• 継承されたメンバーを含む、すべてのメンバーのリスト

プロパティ

• acceptableInput : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• count : int
• currentIndex : int
• currentText : string
• currentValue : var (since QtQuick.Controls 2.14 (Qt 5.14))
• delegate : Component
• delegateModel : model
• displayText : string
• down : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• editText : string (since QtQuick.Controls 2.2 (Qt 5.9))
• editable : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• flat : bool (since QtQuick.Controls 2.1 (Qt 5.8))
• highlightOnHover : bool (since QtQuick.Controls 6.12 (Qt 6.12))
• highlightedIndex : int
• implicitContentWidthPolicy : enumeration (since QtQuick.Controls 6.0 (Qt 6.0))
• implicitIndicatorHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitIndicatorWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• indicator : Item
• inputMethodComposing : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• inputMethodHints : flags (since QtQuick.Controls 2.2 (Qt 5.9))
• model : model
• popup : Popup
• pressed : bool
• selectTextByMouse : bool (since QtQuick.Controls 2.15 (Qt 5.15))
• textRole : string
• validator : Validator (since QtQuick.Controls 2.2 (Qt 5.9))
• valueRole : string (since QtQuick.Controls 2.14 (Qt 5.14))

信号

• void accepted() (since QtQuick.Controls 2.2 (Qt 5.9))
• void activated(int index)
• void highlighted(int index)

方法

• void decrementCurrentIndex()
• int find(string text, enumeration flags)
• void incrementCurrentIndex()
• int indexOfValue(object value) (since QtQuick.Controls 2.14 (Qt 5.14))
• void selectAll() (since QtQuick.Controls 2.2 (Qt 5.9))
• string textAt(int index)
• var valueAt(int index) (since QtQuick.Controls 2.14 (Qt 5.14))

詳細説明

ComboBoxは、ボタンとポップアップリストを組み合わせたものです。画面上のスペースを最小限に抑えながら、ユーザーに選択肢のリストを表示する手段を提供します。

ComboBoxにはデータモデルが設定されます。データモデルとしては、一般的にJavaScript配列、ListModel 、または整数が使用されますが、その他のタイプのデータモデルもサポートされています。

ComboBox {
    model: ["First", "Second", "Third"]
}

編集可能なコンボボックス

ComboBoxはeditable に設定可能です。編集可能なComboBoxは、モデルに含まれる内容に基づいてテキストのオートコンプリートを行います。

次の例は、accepted シグナルに反応して、編集可能なコンボボックスにコンテンツを追加する方法を示しています。

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

ComboBoxのポップアップ

デフォルトでは、ComboBoxのポップアップの外側をクリックするとポップアップが閉じられ、そのイベントはスタック順の下位にあるアイテムに伝播されます。ポップアップが閉じないようにするには、closePolicy を設定します：

    popup.closePolicy: Popup.CloseOnEscape

イベントの伝播を防ぐには、modal プロパティをtrue に設定します：

    popup.modal: true

ComboBoxのモデルロール

ComboBoxは、「modelData 」ロールを提供する標準データモデルを可視化できます：

• ロールが 1 つしかないモデル
• 名前付きロールを持たないモデル（JavaScript配列、整数）

複数の名前付きロールを持つモデルを使用する場合、ComboBoxでは、display text およびdelegate インスタンスに対して特定のtext role を使用するように設定する必要があります。モデル項目のtextロールに対応するロールを使用したい場合は、valueRole に設定します。その後、currentValue プロパティおよびindexOfValue()メソッドを使用して、それらの値に関する情報を取得できます。

例：

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    // Used as an example of a backend - this would usually be
    // e.g. a C++ type exposed to QML.
    QtObject {
        id: backend
        property int modifier
    }

    ComboBox {
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
        textRole: "text"
        valueRole: "value"
        // Set currentValue to the value stored in the backend.
        currentValue: backend.modifier
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
    }
}

「 Qt Quick コントロールにおけるComboBox、入力コントロール、およびフォーカス管理のカスタマイズ」も参照してください 。

プロパティのドキュメント

acceptableInput : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、コンボボックスに、編集可能なテキストフィールドで許容されるテキストが含まれているかどうかを示します。

バリデータが設定されている場合、この値が `true ` となるのは、現在のテキストがバリデータによって最終的な文字列（中間的な文字列としてではなく）として受け入れられる場合のみです。

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

「 validator 」および「accepted 」も参照してください 。

count : int [read-only]

このプロパティには、コンボボックス内の項目の数が格納されます。

currentIndex : int

このプロパティは、コンボボックス内の現在の項目のインデックスを保持します。

count が0 の場合、デフォルト値は-1 となり、それ以外の場合は0 となります。

activated()、currentText 、およびhighlightedIndexも参照してください 。

currentText : string [read-only]

このプロパティには、コンボボックス内の現在の項目のテキストが格納されます。

関連項目: currentIndex 、displayText 、textRole 、およびeditText 。

currentValue : var [since QtQuick.Controls 2.14 (Qt 5.14)]

このプロパティには、コンボボックス内の現在の項目の値が格納されます。このプロパティを設定すると、currentIndex には対応する値を持つ項目が設定され、該当する項目が見つからない場合は-1 が設定されます。currentIndex とcurrentValue の両方を宣言的に設定すると、未定義の挙動が生じます。一意ではない値をこのプロパティに設定することはサポートされていません。

このプロパティの使用例については、ComboBox Model Roles を参照してください。

このプロパティは、QtQuick.Controls 2.14 (Qt 5.14) で導入されました。

currentIndex 、currentText 、およびvalueRoleも参照してください 。

delegate : Component

このプロパティは、コンボボックスのポップアップに項目を表示するデリゲートを保持します。

デリゲートとしては、ItemDelegate （またはその他のAbstractButton 派生クラス）を使用することを推奨します。これにより、操作が期待通りに動作し、適切なタイミングでポップアップが自動的に閉じられるようになります。他の型をデリゲートとして使用した場合、ポップアップは手動で閉じる必要があります。例えば、MouseArea を使用する場合：

delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: comboBox.popup.close()
    }
}

Qt 6.11 以降、ComboBox はデリゲートの所有権を取得しなくなりました。

「 ItemDelegate 」 および「ComboBoxのカスタマイズ」も参照してください 。

delegateModel : model [read-only]

このプロパティは、コンボボックスにデリゲートインスタンスを提供するモデルを保持します。

通常、popup のcontentItem 内で、ListView に割り当てられます。

「ComboBoxのカスタマイズ」も参照してください 。

displayText : string

このプロパティには、コンボボックスのボタンに表示されるテキストが格納されます。

デフォルトでは、表示テキストには現在の選択内容が反映されます。つまり、現在の項目のテキストがそのまま表示されます。ただし、このデフォルトの表示テキストは、カスタム値で上書きすることができます。

ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}

「 currentText 」および「textRole 」も参照してください 。

down : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、コンボボックスのボタンが視覚的に押下されているかどうかを表します。

明示的に設定されていない場合、pressed またはpopup.visible のいずれかがtrue であるとき、このプロパティはtrue となります。デフォルト値に戻すには、このプロパティをundefined に設定してください。

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

pressed およびpopupも参照してください 。

editText : string [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、編集可能なコンボボックスのテキストフィールド内のテキストを保持します。

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

editable 、currentText 、およびdisplayTextも参照してください 。

editable : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、コンボボックスが編集可能かどうかを示します。

デフォルト値はfalse です。

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

「validator」も参照してください 。

flat : bool [since QtQuick.Controls 2.1 (Qt 5.8)]

このプロパティは、コンボボックスのボタンがフラットであるかどうかを指定します。

フラットなコンボボックスのボタンは、操作が行われない限り背景を描画しません。通常のコンボボックスと比較して、フラットなコンボボックスは、UIの他の部分から目立ちにくい外観を提供します。 たとえば、コンボボックスをツールバーに配置する場合、ツールボタンのフラットな外観と調和させるために、コンボボックスをフラットにするのが望ましい場合があります。

デフォルト値は `false` です。

このプロパティは、QtQuick.Controls 2.1 (Qt 5.8) で導入されました。

highlightOnHover : bool [since QtQuick.Controls 6.12 (Qt 6.12)]

このプロパティは、アイテムにカーソルを合わせるとハイライト表示するかどうかを指定します。

デフォルト値はtrue です。

このプロパティは、QtQuick.Controls 6.12 (Qt 6.12) で導入されました。

highlightedIndex : int [read-only]

このプロパティは、コンボボックスのポップアップリスト内でハイライト表示されている項目のインデックスを保持します。

強調表示された項目がアクティブになると、ポップアップは閉じられ、currentIndex はhighlightedIndex に設定され、強調表示された項目がなくなるため、このプロパティの値は-1 にリセットされます。

highlighted() およびcurrentIndexも参照してください 。

implicitContentWidthPolicy : enumeration [since QtQuick.Controls 6.0 (Qt 6.0)]

このプロパティは、ComboBox のimplicitContentWidth の計算方法を制御します。

ComboBox の幅がテキストを表示するのに十分な広さでない場合、そのテキストは省略されます。どの部分が省略されるかによって、エンドユーザーが項目を選択しづらくなる可能性があります。ComboBox の幅を十分に確保し、テキストが省略されないようにする効率的な方法は、確実に十分な広さがあると分かっている幅を設定することです:

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

しかし、テキストのサイズはフォントファミリー、フォントサイズ、翻訳など多くの要因に依存するため、固定値で設定した幅が十分かどうかを事前に判断することは、多くの場合不可能です。

implicitContentWidthPolicy を使用すると、implicitContentWidth の計算方法を簡単に制御できます。これにより、ComboBox の `implicitWidth ` に影響を与え、テキストが省略されないようにすることができます。

使用可能な値は以下の通りです：

デフォルト値は `ContentItemImplicitWidth` です。

このプロパティはComboBox のimplicitWidth にのみ影響するため、明示的なwidth を設定しても、省略が生じる可能性があります。

このプロパティは、QtQuick.Controls 6.0 (Qt 6.0) で導入されました。

implicitIndicatorHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

このプロパティには、暗黙のインジケーターの高さが格納されます。

その値は `indicator ? indicator.implicitHeight : 0` に等しい。

これは通常、implicitContentHeight およびimplicitBackgroundHeight と組み合わせて、implicitHeight を計算するために使用されます。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

implicitIndicatorWidthも参照してください 。

implicitIndicatorWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

このプロパティには、暗黙のインジケーターの幅が格納されます。

その値は `indicator ? indicator.implicitWidth : 0` に等しい。

これは通常、implicitContentWidth およびimplicitBackgroundWidth と組み合わせて、implicitWidth を計算するために使用されます。

このプロパティは、QtQuick.Controls 2.5 (Qt 5.12) で導入されました。

implicitIndicatorHeightも参照してください 。

indicator : Item

このプロパティには、ドロップインジケーターの項目が格納されます。

「ComboBoxのカスタマイズ」も参照してください 。

inputMethodComposing : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、編集可能なコンボボックスに入力方式から部分的なテキストが入力されているかどうかを示します。

入力処理中、入力メソッドはコンボボックスからのマウスイベントやキーイベントを利用して、部分テキストを編集または確定する場合があります。このプロパティを使用することで、入力メソッドの正常な動作を妨げる可能性のあるイベントハンドラを無効にするタイミングを判断できます。

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

inputMethodHints : flags [since QtQuick.Controls 2.2 (Qt 5.9)]

コンボボックスの想定される内容や動作方法について、入力メソッドにヒントを提供します。

デフォルト値はQt.ImhNoPredictiveText です。

この値は、フラグのビット単位の組み合わせ、またはヒントが設定されていない場合はQt.ImhNone となります。

動作を変更するフラグは以下の通りです。

• Qt.ImhHiddenText - パスワードの入力時などに一般的に使用されるように、文字を非表示にする必要があります。
• Qt.ImhSensitiveData - 入力されたテキストは、アクティブな入力メソッドによって、予測ユーザー辞書などの永続的な保存先に保存されないようにします。
• Qt.ImhNoAutoUppercase - 文の終わりに達しても、入力メソッドは自動的に大文字に切り替えないようにします。
• Qt.ImhPreferNumbers - 数字が優先されます（必須ではありません）。
• Qt.ImhPreferUppercase - 大文字の使用が推奨されます（必須ではありません）。
• Qt.ImhPreferLowercase - 小文字が優先されます（必須ではありません）。
• Qt.ImhNoPredictiveText - 入力中に予測入力（辞書検索）を使用しない。
• Qt.ImhDate - テキストエディタは日付フィールドとして機能します。
• Qt.ImhTime - テキストエディタは日時フィールドとして機能します。

入力を制限するフラグ（排他フラグ）は次のとおりです。

• Qt.ImhDigitsOnly - 数字のみ入力可能です。
• Qt.ImhFormattedNumbersOnly - 数値のみの入力のみ許可されます。これには小数点およびマイナス記号が含まれます。
• Qt.ImhUppercaseOnly - 大文字のみの入力のみ許可されます。
• Qt.ImhLowercaseOnly - 小文字のみの入力のみ許可されます。
• Qt.ImhDialableCharactersOnly - 電話のダイヤルに適した文字のみが許可されます。
• Qt.ImhEmailCharactersOnly - メールアドレスに適した文字のみ入力可能です。
• Qt.ImhUrlCharactersOnly - URL に適した文字のみ入力可能です。

マスク:

• Qt.ImhExclusiveInputMask - 排他フラグのいずれかが使用されている場合、このマスクは 0 以外の値を返します。

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

model : model

このプロパティには、コンボボックスにデータを提供するモデルが格納されます。

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

「 textRole 」 および「データモデル」も参照してください 。

popup : Popup

このプロパティはポップアップを保持します。

必要に応じて、ポップアップを手動で開いたり閉じたりすることができます:

onSpecialEvent: comboBox.popup.close()

「コンボボックスのカスタマイズ」も参照してください 。

pressed : bool [read-only]

このプロパティは、コンボボックスのボタンが物理的に押されているかどうかを表します。ボタンは、タッチイベントまたはキーイベントによって押されることがあります。

「down」も参照してください 。

selectTextByMouse : bool [since QtQuick.Controls 2.15 (Qt 5.15)]

このプロパティは、編集可能なComboBox のテキストフィールドをマウスで選択できるかどうかを指定します。

デフォルト値は `false` です。

このプロパティは、QtQuick.Controls 2.15 (Qt 5.15) で導入されました。

textRole : string

このプロパティには、コンボボックスにデータを表示するために使用されるモデルのロールが格納されます。

モデルに複数のロールがある場合、textRole を設定することで、どのロールを表示するかを指定できます。

関連項目： model 、currentText 、displayText 、およびComboBox Model Roles 。

validator : Validator [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、編集可能なコンボボックスのテキスト入力バリデータを持ちます。

バリデータが設定されている場合、テキストフィールドは、textプロパティを中間状態に保つ入力のみを受け付けます。accepted シグナルは、Return またはEnter キーが押された時点で、テキストが許容可能な状態にある場合にのみ発火します。

現在サポートされているバリデータは、IntValidator 、DoubleValidator 、およびRegularExpressionValidator です。以下に、テキストフィールドへの入力を0 から10 の範囲の整数に制限するバリデータの使用例を示します。

ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

acceptableInput 、accepted 、およびeditableも参照してください 。

valueRole : string [since QtQuick.Controls 2.14 (Qt 5.14)]

このプロパティには、モデル内の各アイテムに関連付けられた値を格納するために使用されるモデルのロールが格納されます。

このプロパティの使用例については、ComboBox Model Roles を参照してください。

このプロパティは、QtQuick.Controls 2.14 (Qt 5.14) で導入されました。

model およびcurrentValueも参照してください 。

シグナルのドキュメント

[since QtQuick.Controls 2.2 (Qt 5.9)] void accepted()

このシグナルは、editable のコンボボックスで「Return 」または「Enter 」キーが押されたときに発生します。

このシグナルを処理することで、新しく入力された項目をモデルに追加することができます。例えば、次のようにします。

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

シグナルが発火する前に、その文字列がモデル内に存在するかどうかがチェックされます。存在する場合、currentIndex にはそのインデックスが、currentText には文字列自体が設定されます。

シグナルが発信された後、最初のチェックに失敗した場合（つまり、項目が存在しなかった場合）、シグナルハンドラによってその項目が追加されたかどうかを確認するための別のチェックが行われます。追加された場合は、currentIndex とcurrentText がそれに応じて更新されます。そうでない場合は、それぞれ-1 と"" に設定されます。

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

void activated(int index)

このシグナルは、index にあるアイテムがユーザーによってアクティブ化されたときに発生します。

アイテムは、ポップアップが開いている状態で選択され、ポップアップが閉じられる（かつcurrentIndex が変更される）場合、またはポップアップが閉じられている状態でキーボード操作によりコンボボックスが移動され、currentIndex が変更される場合に、アクティブ化されます。currentIndex プロパティはindex に設定されます。

「currentIndex」も参照してください 。

void highlighted(int index)

このシグナルは、ポップアップリスト内のindex にある項目がユーザーによってハイライトされたときに発火します。

highlightedシグナルは、ポップアップが開いており、かつアイテムがハイライトされている場合にのみ発火しますが、必ずしもactivated である必要はありません。

「highlightedIndex」も参照してください 。

メソッドのドキュメント

void decrementCurrentIndex()

コンボボックスの現在のインデックスを1減らします。ポップアップリストが表示されている場合は、ハイライトされているインデックスを1減らします。

「 currentIndex 」および「highlightedIndex 」も参照してください 。

int find(string text, enumeration flags)

指定されたtext のインデックスを返します。一致する項目が見つからない場合は-1 を返します。

検索の方法は、指定された照合条件（flags ）によって定義されます。デフォルトでは、コンボボックスは大文字と小文字を区別する完全一致（Qt.MatchExactly ）を行います。Qt.MatchCaseSensitive フラグが併せて指定されていない限り、その他のすべての照合タイプは大文字と小文字を区別しません。

例：

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

「textRole」も参照してください 。

void incrementCurrentIndex()

コンボボックスの現在のインデックスを1増やします。ポップアップリストが表示されている場合は、ハイライトされているインデックスを1増やします。

currentIndex およびhighlightedIndexも参照してください 。

[since QtQuick.Controls 2.14 (Qt 5.14)] int indexOfValue(object value)

指定されたvalue のインデックスを返します。一致するものがなかった場合は、-1 を返します。

このメソッドの使用例については、ComboBox Model Roles を参照してください。

このメソッドは、QtQuick.Controls 2.14 (Qt 5.14) で導入されました。

関連項目: find()、currentValue 、currentIndex 、valueRole 、およびvalueAt 。

[since QtQuick.Controls 2.2 (Qt 5.9)] void selectAll()

コンボボックスの編集可能なテキストフィールド内のテキストをすべて選択します。

このメソッドは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。

editTextも参照してください 。

string textAt(int index)

指定されたindex に対応するテキストを返します。インデックスが範囲外の場合は、空の文字列を返します。

例:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

関連項目： textRole 。

[since QtQuick.Controls 2.14 (Qt 5.14)] var valueAt(int index)

コンボボックス内のindex の位置にある値を返します。

このメソッドは、QtQuick.Controls 2.14 (Qt 5.14) で導入されました。

indexOfValueも参照してください 。