Тип QML ComboBox

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

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

Свойства

• acceptableInput : bool
• count : int
• currentIndex : int
• currentText : string
• currentValue : var
• delegate : Component
• displayText : string
• down : bool
• editText : string
• editable : bool
• flat : bool
• highlightedIndex : int
• implicitContentWidthPolicy : enumeration
• implicitIndicatorHeight : real
• implicitIndicatorWidth : real
• indicator : Item
• inputMethodComposing : bool
• inputMethodHints : flags
• model : model
• popup : Popup
• pressed : bool
• selectTextByMouse : bool
• textRole : string
• validator : Validator
• valueRole : string

Сигналы

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

Методы

• void decrementCurrentIndex()
• int find(string text, enumeration flags)
• void incrementCurrentIndex()
• int indexOfValue(object value)
• void selectAll()
• string textAt(int 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 необходимо настроить для использования конкретной роли текста для его отображаемого текста и экземпляров delegate. Если вы хотите использовать роль элемента модели, которая соответствует роли текста, установите 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, Элементы управления вводом и Управление фокусом в Qt Quick Controls.

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

[только для чтения, начиная с QtQuick.Controls 2.2 (Qt 5.9)] 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.

[только для чтения, начиная с QtQuick.Controls 2.14 (Qt 5.14)] currentValue : var

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] down : bool

Данное свойство указывает, визуально ли кнопка выпадающего списка ComboBox внизу.

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

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] editText : string

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

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

См. также editable, currentText и displayText.

[с QtQuick.Controls 2.2 (Qt 5.9)] editable : bool

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

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

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

См. также validator.

[с QtQuick.Controls 2.1 (Qt 5.8)] flat : bool

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

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

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

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

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

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

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

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

[с QtQuick.Controls 6.0 (Qt 6.0)] implicitContentWidthPolicy : enumeration

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

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

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

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

implicitContentWidthPolicy предоставляет простой способ управления тем, как вычисляется implicitContentWidth, что, в свою очередь, влияет на implicitWidth ComboBox и гарантирует, что текст не будет обрезаться.

Доступные значения:

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

Так как это свойство влияет только на implicitWidth ComboBox, установка явной ширины width всё ещё может привести к обрезанию.

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

[только для чтения, с QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorHeight : real

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

Значение равно indicator ? indicator.implicitHeight : 0.

Обычно используется вместе с implicitContentHeight и implicitBackgroundHeight для вычисления implicitHeight.

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

См. также implicitIndicatorWidth.

[только для чтения, с QtQuick.Controls 2.5 (Qt 5.12)] implicitIndicatorWidth : real

Это свойство содержит неявную ширину указателя.

Значение равно indicator ? indicator.implicitWidth : 0.

Обычно используется вместе с implicitContentWidth и implicitBackgroundWidth для вычисления implicitWidth.

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

См. также implicitIndicatorHeight.

indicator : Item

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

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

[только для чтения, с QtQuick.Controls 2.2 (Qt 5.9)] inputMethodComposing : bool

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

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

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

[с 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.

[с QtQuick.Controls 2.15 (Qt 5.15)] selectTextByMouse : bool

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

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

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

textRole : string

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

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

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

[с QtQuick.Controls 2.2 (Qt 5.9)] validator : Validator

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

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

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

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

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

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

[с QtQuick.Controls 2.14 (Qt 5.14)] valueRole : string

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

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

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

См. также model и currentValue.

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

[since QtQuick.Controls 2.2 (Qt 5.9)] void accepted()

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

Примечание: Соответствующий обработчик onAccepted.

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

void activated(int index)

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

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

Примечание: Соответствующий обработчик onActivated.

См. также currentIndex.

void highlighted(int index)

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

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

Примечание: Соответствующий обработчик onHighlighted.

См. также highlightedIndex.

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

void decrementCurrentIndex()

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

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

int find(string text, enumeration flags)

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

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

Например:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

См. также textRole.

void incrementCurrentIndex()

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

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

[since QtQuick.Controls 2.14 (Qt 5.14)] int indexOfValue(object value)

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

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

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

См. также find(), currentValue, currentIndex и valueRole.

[since QtQuick.Controls 2.2 (Qt 5.9)] void selectAll()

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

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

См. также editText.

string textAt(int index)

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

Например:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

См. также textRole.