Тип ComboBox QML

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

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

Свойства

• 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 : перечисление
• implicitIndicatorHeight : real
• implicitIndicatorWidth : real
• indicator : Item
• inputMethodComposing : bool
• inputMethodHints : флаги
• 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, перечисление 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, реагируя на сигнал 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.

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

[только для чтения, с 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, установка явной ширины всё равно может привести к усечению.

Примечание: эта функция требует, чтобы 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 : Item

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

См. также Настройка 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()

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

Вы можете обработать этот сигнал, чтобы добавить новый введенный элемент в модель, например:

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.