Тип 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
• implicitContentWidthPolicy : enumeration
• 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 необходимо настроить для использования определенной роли текста для его текста отображения и экземпляров delegate. Если вы хотите использовать роль элемента модели, соответствующую роли текста, установите 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.

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

[только для чтения, начиная с QtQuick.Controls 2.2 (Qt 5.9)] acceptableInput : bool

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

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

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

[только для чтения, начиная с QtQuick.Controls 2.14 (Qt 5.14)] 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 : строка

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

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

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] down : логическое

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

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

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] editText : строка

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

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] editable : логическое

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

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

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

См. также validator.

[с QtQuick.Controls 2.1 (Qt 5.8)] flat : логическое

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

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

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

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

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

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

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

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

[с QtQuick.Controls 6.0 (Qt 6.0)] implicitContentWidthPolicy : перечисление

Это свойство управляет тем, как рассчитывается implicitContentWidth виджета ComboBox.

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

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

Однако, часто невозможно знать, будет ли жёстко заданное значение достаточным, так как размер текста зависит от многих факторов, таких как семейство шрифтов, размер шрифта, переводы и так далее.

implicitContentWidthPolicy предоставляет простой способ управления тем, как рассчитывается implicitContentWidth, что в свою очередь влияет на implicitWidth виджета ComboBox и гарантирует, что текст не будет усечён.

Доступные значения:

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

Поскольку это свойство влияет только на implicitWidth ComboBox, установка явной width всё ещё может привести к усечению.

Примечание: Для этого свойства требуется, чтобы contentItem был типом, производным от TextInput.

Примечание: Это свойство требует вычисления размеров текста и может быть дорогим для больших моделей или моделей, содержимое которых часто обновляется.

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

[только для чтения, с QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorHeight : вещественное

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

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

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

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

См. также implicitIndicatorWidth.

[только для чтения, с QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorWidth : вещественное

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

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

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

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

См. также implicitIndicatorHeight.

indicator : Элемент

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

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

[только для чтения, с QtQuick.Controls 2.2 (Qt 5.9)] inputMethodComposing : логическое

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

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] inputMethodHints : флаги

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

Значение по умолчанию равно 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.

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

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

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

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

textRole : string

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

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

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

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

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

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

В настоящее время поддерживаются валидаторы 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.

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

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

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

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

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

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

[since QtQuick.Controls 2.2 (Qt 5.9)] void 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})
    }
}

Перед испусканием сигнала выполняется проверка на наличие строки в модели. Если она есть, 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.

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

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

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

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

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

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

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

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

См. также editText.

string textAt(int index)

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

См. также textRole.