Тип QML ComboBox

Комбинированная кнопка и всплывающее меню для выбора опций. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• acceptableInput : bool
• count : int
• currentIndex : int
• currentText : string
• currentValue : string
• delegate : Component
• displayText : string
• down : bool
• editText : string
• editable : bool
• flat : bool
• highlightedIndex : int
• implicitIndicatorHeight : real
• implicitIndicatorWidth : real
• indicator : Item
• inputMethodComposing : bool
• inputMethodHints : flags
• model : model
• popup : Popup
• pressed : bool
• selectTextByMouse : bool
• textRole : string
• validator : Validator
• valueRole : string

Сигналы

• void accepted()
• void activated(int index)
• void highlighted(int index)

Методы

• void decrementCurrentIndex()
• int find(string text, enumeration flags)
• void incrementCurrentIndex()
• int indexOfValue(object value)
• void selectAll()
• string textAt(int index)

Подробное описание

ComboBox — это комбинированная кнопка и всплывающее меню. Он обеспечивает способ представления списка опций для пользователя таким образом, чтобы занимать минимальное пространство на экране.

ComboBox заполняется моделью данных. Модель данных обычно представляет собой массив JavaScript, ListModel или целое число, но поддерживаются и другие типы моделей данных.

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

Редактируемый ComboBox

ComboBox можно сделать редактируемым. Редактируемый ComboBox автоматически дополняет свой текст, основываясь на доступных значениях в модели.

Следующий пример демонстрирует добавление содержимого в редактируемый 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 способен визуализировать стандартные модели данных, которые предоставляют modelData роль:

• модели, имеющие только одну роль
• модели, не имеющие именованных ролей (массив JavaScript, целое число)

При использовании моделей, имеющих несколько именованных ролей, ComboBox должен быть настроен на использование определенной роли текста для своего текста отображения и экземпляров делегата. Если нужно использовать роль элемента модели, соответствующую роли текста, установите 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 {
        textRole: "text"
        valueRole: "value"
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
        // Set the initial currentIndex to the value stored in the backend.
        Component.onCompleted: currentIndex = indexOfValue(backend.modifier)
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
    }
}

Примечание: Если ComboBox присваивается модель данных, которая имеет несколько именованных ролей, но textRole не определена, ComboBox не может её визуализировать и генерирует ReferenceError: modelData is not defined.

См. также Настройка ComboBox, Элементы управления вводом и Управление фокусом в Qt Quick Controls.

Документация по свойствам

[только для чтения] acceptableInput : bool

Это свойство содержит значение, указывающее, содержит ли поле ввода ComboBox допустимый текст.

Если валидатор задан, значение истинно только если текущий текст является допустимым для валидатора как окончательная строка (не как промежуточная строка).

Это свойство было добавлено в QtQuick.Controls 2.2 (Qt 5.9).

См. также validator и accepted.

[только для чтения] count : int

Это свойство содержит количество элементов в ComboBox.

currentIndex : int

Это свойство содержит индекс текущего элемента в ComboBox.

Значение по умолчанию — -1 когда count — 0, и 0 в противном случае.

См. также activated(), currentText и highlightedIndex.

[только для чтения] currentText : string

Это свойство содержит текст текущего элемента в ComboBox.

См. также currentIndex, displayText, textRole и editText.

[только для чтения] currentValue : string

Это свойство содержит значение текущего элемента в ComboBox.

Пример использования этого свойства см. в разделе Роли модели ComboBox.

Это свойство было добавлено в QtQuick.Controls 2.14 (Qt 5.14).

См. также currentIndex, currentText и valueRole.

delegate : Component

Это свойство содержит делегат, представляющий элемент в всплывающем меню ComboBox.

Рекомендуется использовать ItemDelegate (или любой другой производный от AbstractButton) в качестве делегата. Это гарантирует, что взаимодействие будет работать как ожидается, и всплывающее меню будет автоматически закрываться при необходимости. При использовании других типов в качестве делегата, всплывающее меню необходимо закрывать вручную. Например, если используется MouseArea:

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

См. также ItemDelegate и Настройка ComboBox.

displayText : string

Это свойство содержит текст, отображаемый на кнопке ComboBox.

По умолчанию, отображаемый текст представляет текущий выбор. То есть, он следует за текстом текущего элемента. Однако, отображаемый текст по умолчанию можно переопределить пользовательским значением.

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

См. также currentText и textRole.

down : bool

Данное свойство указывает, визуально ли кнопка раскрывающегося списка в открытом состоянии.

Если явно не задано, это свойство равно true при pressed или popup.visible равно true. Чтобы вернуть значение по умолчанию, установите это свойство в undefined.

Это свойство было добавлено в QtQuick.Controls 2.2 (Qt 5.9).

См. также pressed и popup.

editText : string

Это свойство содержит текст в текстовом поле редактируемого раскрывающегося списка.

Это свойство было добавлено в QtQuick.Controls 2.2 (Qt 5.9).

См. также editable, currentText и displayText.

editable : bool

Это свойство указывает, редактируется ли раскрывающийся список.

Значение по умолчанию равно false.

Это свойство было добавлено в QtQuick.Controls 2.2 (Qt 5.9).

См. также validator.

flat : bool

Это свойство указывает, является ли кнопка раскрывающегося списка плоской.

Кнопка плоского раскрывающегося списка не рисует фон, пока с ней не взаимодействуют. По сравнению с обычными раскрывающимися списками, плоские раскрывающиеся списки имеют внешний вид, который делает их менее заметными на общем фоне пользовательского интерфейса. Например, при размещении раскрывающегося списка в панели инструментов может быть желательно сделать его плоским, чтобы он лучше соответствовал плоскому стилю кнопок инструментов.

Значение по умолчанию равно false.

Это свойство было добавлено в QtQuick.Controls 2.1 (Qt 5.8).

[только для чтения] highlightedIndex : int

Это свойство содержит индекс выделенного элемента в всплывающем списке раскрывающегося списка.

При активации выделенного элемента всплывающее окно закрывается, currentIndex устанавливается в highlightedIndex, и значение этого свойства сбрасывается до -1, так как выделенный элемент больше не существует.

См. также highlighted() и currentIndex.

[только для чтения] implicitIndicatorHeight : real

Это свойство содержит неявную высоту индикатора.

Значение равно indicator ? indicator.implicitHeight : 0.

Обычно используется вместе с implicitContentHeight и implicitBackgroundHeight для вычисления implicitHeight.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также implicitIndicatorWidth.

[только для чтения] implicitIndicatorWidth : real

Это свойство содержит неявдую ширину индикатора.

Значение равно indicator ? indicator.implicitWidth : 0.

Обычно используется вместе с implicitContentWidth и implicitBackgroundWidth для вычисления implicitWidth.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также implicitIndicatorHeight.

indicator : Item

Это свойство содержит элемент индикатора раскрытия.

См. также Настройка ComboBox.

[только для чтения] inputMethodComposing : bool

Это свойство указывает, имеет ли редактируемый раскрывающийся список частичный ввод текста от метода ввода.

Во время составления метода ввода может полагаться на события мыши или клавиатуры от раскрывающегося списка для редактирования или подтверждения частичного текста. Это свойство может использоваться для определения времени отключения обработчиков событий, которые могут помешать корректной работе метода ввода.

Это свойство было добавлено в QtQuick.Controls 2.2 (Qt 5.9).

inputMethodHints : flags

Предоставляет подсказки методу ввода о предполагаемом содержимом раскрывающегося списка и о том, как он должен работать.

Значение по умолчанию равно 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 - Это маска, дающая ненулевое значение, если используются какие-либо исключительные флаги.

Это свойство было добавлено в 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()

См. также Настройка ComboBox.

pressed : bool

Это свойство указывает, физически ли нажата кнопка раскрывающегося списка. Кнопка может быть нажата с помощью событий касания или клавиатуры.

См. также down.

selectTextByMouse : bool

Это свойство указывает, можно ли выбрать текст в поле редактирования для ComboBox с помощью мыши.

Значение по умолчанию равно false.

Это свойство было добавлено в QtQuick.Controls 2.15 (Qt 5.15).

textRole : string

Это свойство содержит роль модели, используемой для заполнения раскрывающегося списка.

Когда модель имеет несколько ролей, textRole можно установить, чтобы определить, какая роль должна быть отображена.

См. также model, currentText, displayText и Роли модели ComboBox.

validator : Validator

Это свойство содержит валидатор текста ввода для редактируемого раскрывающегося списка.

При установке валидатора текстовое поле будет принимать только ввод, который оставляет свойство text в промежуточном состоянии. Сигнал accepted будет выпущен только в том случае, если текст находится в допустимом состоянии при нажатии клавиш Возврат или Ввод.

В настоящее время поддерживаются валидаторы IntValidator, DoubleValidator и RegExpValidator. Ниже приведен пример использования валидаторов, который позволяет вводить целые числа от 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

Это свойство содержит роль модели, используемую для хранения значения, связанного с каждым элементом в модели.

Пример использования этого свойства см. в Ролях модели ComboBox.

Это свойство было добавлено в QtQuick.Controls 2.14 (Qt 5.14).

См. также model и currentValue.

Документация сигналов

void accepted()

Этот сигнал испускается при нажатии клавиш 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 и "" соответственно.

Примечание: Если на комбобоксе установлен валидатор, сигнал будет испущен только в случае корректного ввода.

Примечание: Соответствующий обработчик — onAccepted.

Этот сигнал был добавлен в QtQuick.Controls 2.2 (Qt 5.9).

void activated(int index)

Этот сигнал испускается, когда пользователь активирует элемент по индексу index.

Элемент активируется, когда он выбирается при открытом выпадающем списке, что приводит к закрытию выпадающего списка (и изменению currentIndex) или когда выпадающий список закрыт и комбобокс прокручивается с помощью клавиатуры, что приводит к изменению currentIndex. Свойство currentIndex устанавливается в значение index.

Примечание: Соответствующий обработчик — onActivated.

См. также currentIndex.

void highlighted(int index)

Этот сигнал испускается, когда пользователь выделяет элемент по индексу index в выпадающем списке.

Сигнал highlighted испускается только при открытом выпадающем списке и выделении элемента, но необязательно при activated.

Примечание: Соответствующий обработчик — onHighlighted.

См. также highlightedIndex.

Документация методов

void decrementCurrentIndex()

Уменьшает текущий индекс комбобокса или выделенный индекс, если выпадающий список видимый.

См. также currentIndex и highlightedIndex.

int find(string text, enumeration flags)

Возвращает индекс указанного text или -1 если совпадение не найдено.

Способ выполнения поиска определяется заданными флагами соответствия flags. По умолчанию комбобокс выполняет чувствительное к регистру точное соответствие (Qt.MatchExactly). Все другие типы соответствия нечувствительны к регистру, если не указан также флаг Qt.MatchCaseSensitive.

См. также textRole.

void incrementCurrentIndex()

Увеличивает текущий индекс комбобокса или выделенный индекс, если выпадающий список видимый.

См. также currentIndex и highlightedIndex.

int indexOfValue(object value)

Возвращает индекс указанного value или -1 если совпадение не найдено.

Пример использования этого метода см. в Ролях модели ComboBox.

Этот метод был добавлен в QtQuick.Controls 2.14 (Qt 5.14).

См. также find(), currentValue, currentIndex и valueRole.

void selectAll()

Выделяет весь текст в поле редактирования текста комбобокса.

Этот метод был добавлен в QtQuick.Controls 2.2 (Qt 5.9).

См. также editText.

string textAt(int index)

Возвращает текст для указанного index или пустую строку, если индекс вне границ.

См. также textRole.