ComboBox QML Type

A combo box control. More...

Import Statement: import Qt.labs.controls 1.0
Inherits:

Control

Properties

Signals

Methods

  • int find(string text, flags)
  • string textAt(int index)

Detailed Description

ComboBox is a combined button and popup list. It provides a means of presenting a list of options to the user in a way that takes up the minimum amount of screen space.

ComboBox is populated with a data model. The data model is commonly a JavaScript array, a ListModel or an integer, but also other types of data models are supported.

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

ComboBox is able to visualize standard data models that provide the modelData role:

  • models that have only one role
  • models that do not have named roles (JavaScript array, integer)

When using models that have multiple named roles, ComboBox must be configured to use a specific text role for its display text and delegate instances.

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

Note: If ComboBox is assigned a data model that has multiple named roles, but textRole is not defined, ComboBox is unable to visualize it and throws a ReferenceError: modelData is not defined.

Note: Types in the Qt.labs module are not guaranteed to remain compatible in future versions.

See also Customizing ComboBox and Input Controls.

Property Documentation

[read-only] count : int

This property holds the number of items in the combo box.


currentIndex : int

This property holds the index of the current item in the combo box.

See also activated() and currentText.


[read-only] currentText : string

This property holds the text of the current item in the combo box.

See also currentIndex, displayText, and textRole.


delegate : Component

This property holds a delegate that presents an item in the combo box popup.

See also ItemDelegate and Customizing ComboBox.


displayText : string

This property holds the text that is displayed on the combo box button.

By default, the display text presents the current selection. That is, it follows the text of the current item. However, the default display text can be overridden with a custom value.

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

See also currentText and textRole.


[read-only] highlightedIndex : int

This property holds the index of the highlighted item in the combo box popup list.

See also highlighted() and currentIndex.


model : model

This property holds the model providing data for the combo box.

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

See also textRole and Data Models.


This property holds the popup.

See also Customizing ComboBox.


pressed : bool

This property holds whether the combo box button is pressed.


textRole : string

This property holds the model role used for populating the combo box.

See also model, currentText, and displayText.


Signal Documentation

void activated(int index)

This signal is emitted when the item at index is activated by the user.

See also currentIndex.


void highlighted(int index)

This signal is emitted when the item at index in the popup list is highlighted by the user.

See also highlightedIndex.


Method Documentation

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

Returns the index of the specified text, or -1 if no match is found.

The way the search is performed is defined by the specified match flags. By default, combo box performs case sensitive exact matching (Qt.MatchExactly). All other match types are case-insensitive unless the Qt.MatchCaseSensitive flag is also specified.

ConstantDescription
Qt.MatchExactlyThe search term matches exactly (default).
Qt.MatchRegExpThe search term matches as a regular expression.
Qt.MatchWildcardThe search term matches using wildcards.
Qt.MatchFixedStringThe search term matches as a fixed string.
Qt.MatchStartsWithThe search term matches the start of the item.
Qt.MatchEndsWidthThe search term matches the end of the item.
Qt.MatchContainsThe search term is contained in the item.
Qt.MatchCaseSensitiveThe search is case sensitive.

See also textRole.


string textAt(int index)

Returns the text for the specified index, or an empty string if the index is out of bounds.

See also textRole.


© 2017 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.