Тип 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
• textRole : string
• validator : Validator
• valueRole : string

Сигналы

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

Методы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

currentIndex : int

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

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

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

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

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

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

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

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

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

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

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

delegate : Component

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

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

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

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

displayText : string

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

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

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.

textRole : string

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

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

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

validator : Validator

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

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

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

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

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

void activated(index)

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

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

См. также currentIndex.

void highlighted(index)

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

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

См. также highlightedIndex.

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

void decrementCurrentIndex()

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

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

int find(text, enumeration flags)

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

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

См. также textRole.

void incrementCurrentIndex()

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

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

int indexOfValue(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(index)

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

См. также textRole.