Тип QML ComboBox

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

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

Свойства

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

Сигналы

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

Методы

• void decrementCurrentIndex()
• int find(string text, flags)
• void incrementCurrentIndex()
• 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.

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

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

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

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

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

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

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

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

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

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

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

currentIndex : int

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

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

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

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

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

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

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

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

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

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

editText : string

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

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

См. также editable.

editable : bool

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

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

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

См. также validator.

flat : bool

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

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

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

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

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

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

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

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

indicator : Item

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

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

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

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

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

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

Это свойство QML было добавлено в 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 будет выпущен только в том случае, если текст находится в допустимом состоянии при нажатии клавиши Возврат или Ввод.

В настоящее время поддерживаются валидаторы IntValidator, DoubleValidator и RegExpValidator. Ниже приведён пример использования валидаторов, который позволяет вводить целые числа от 0 до 10 в текстовое поле:

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

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

См. также acceptableInput, accepted и editable.

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

void accepted()

Этот сигнал излучается при нажатии клавиш Возврат или Ввод на редактируемом раскрывающемся списке editable. Если подтвержденная строка в настоящее время не находится в модели, currentIndex будет установлен в -1, и currentText будет обновлено соответственно.

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

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

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

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

int find(string text, flags = Qt.MatchExactly)

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

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

См. также textRole.

void incrementCurrentIndex()

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

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

void selectAll()

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

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

См. также editText.

string textAt(int index)

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

См. также textRole.