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

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.

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.

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 в списке раскрывающегося окна.

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

См. также highlightedIndex.

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

void decrementCurrentIndex()

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

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

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

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

Способ выполнения поиска определяется заданными флагами match. По умолчанию раскрывающийся список выполняет чувствительный к регистру поиск по точному совпадению (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.