Тип ComboBox QML

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

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

Свойства

• 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(int index)
• void highlighted(int index)

Методы

• void decrementCurrentIndex()
• int find(string text, flags = Qt.MatchExactly)
• 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 должен быть настроен для использования конкретной роли текста для его текста отображения и экземпляров делегатов.

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

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

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

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

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

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

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

currentIndex : int

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

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

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

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

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

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

delegate : Component

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

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

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

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

displayText : string

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

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

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

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

down : bool

Это свойство указывает, визуально ли кнопка combo box находится внизу.

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

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

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

editText : string

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

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

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

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

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

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

void activated(int index)

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

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

См. также currentIndex.

void highlighted(int index)

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

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

См. также 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()

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

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

См. также editText.

string textAt(int index)

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

См. также textRole.