Тип QML ComboBox

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

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

Свойства

• acceptableInput : bool
• count : int
• currentIndex : int
• currentText : 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

Сигналы

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

Методы

• void decrementCurrentIndex()
• int find(text, flags = Qt.MatchExactly)
• void incrementCurrentIndex()
• void selectAll()
• string textAt(index)

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

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

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

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

Редактируемый 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 должен быть настроен на использование определённой роли текста для своего текста отображения и экземпляров делегата.

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, Элементы управления вводом и Управление фокусом в Qt Quick Controls 2.

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

[только для чтения] 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.

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.

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

void accepted()

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

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

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

void activated(index)

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

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

См. также currentIndex.

void highlighted(index)

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

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

См. также highlightedIndex.

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

void decrementCurrentIndex()

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

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

int find(text, flags = Qt.MatchExactly)

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

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

См. также textRole.

void incrementCurrentIndex()

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

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

void selectAll()

Выделяет весь текст в поле редактирования текста выпадающего списка.

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

См. также editText.

string textAt(index)

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

См. также textRole.