Qt 5.8 | Qt Quick Controls 2 | QML Types | ComboBox QML Type

Qt 5.8.0 Reference Documentation

# ComboBox QML Type

Combined button and popup list for selecting options. More...

Import Statement: | import QtQuick.Controls 2.1
Since: | Qt 5.7

- List of all members, including inherited members

## Properties

- count : int
- currentIndex : int
- currentText : string
- delegate : Component
- displayText : string
- flat : bool
- highlightedIndex : int
- indicator : Item
- model : model
- popup : Popup
- pressed : bool
- textRole : string

## Signals

- void activated(int index)
- void highlighted(int index)

## Methods

- void decrementCurrentIndex()
- int find(string text, flags)
- void incrementCurrentIndex()
- 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 other types of data models are also supported.

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

## ComboBox Model Roles

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`.

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(), currentText, and highlightedIndex.

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

It is recommended to use ItemDelegate (or any other AbstractButton derivatives) as the delegate. This ensures that the interaction works as expected, and the popup will automatically close when appropriate. When other types are used as the delegate, the popup must be closed manually. For example, if MouseArea is used:

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

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.

flat : bool

This property holds whether the combo box button is flat.

A flat combo box button does not draw a background unless it is interacted with. In comparison to normal combo boxes, flat combo boxes provide looks that make them stand out less from the rest of the UI. For instance, when placing a combo box into a tool bar, it may be desirable to make the combo box flat so it matches better with the flat looks of tool buttons.

The default value is `false`.

This QML property was introduced in QtQuick.Controls 2.1.

[read-only] highlightedIndex : int

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

When a highlighted item is activated, the popup is closed, currentIndex is set to `highlightedIndex`, and the value of this property is reset to `-1`, as there is no longer a highlighted item.

See also highlighted() and currentIndex.

indicator : Item

This property holds the drop indicator item.

See also Customizing ComboBox.

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.

popup : Popup

This property holds the popup.

The popup can be opened or closed manually, if necessary:

      onSpecialEvent: comboBox.popup.close()

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.

When the model has multiple roles, `textRole` can be set to determine which role should be displayed.

See also model, currentText, displayText, and ComboBox Model Roles.

## Signal Documentation

void activated(int index)

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

An item is activated when it is selected while the popup is open, causing the popup to close (and currentIndex to change), or while the popup is closed and the combo box is navigated via keyboard, causing the currentIndex to change. The currentIndex property is set to index.

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.

The highlighted signal is only emitted when the popup is open and an item is highlighted, but not necessarily activated.

See also highlightedIndex.

## Method Documentation

void decrementCurrentIndex()

Decrements the current index of the combo box, or the highlighted index if the popup list is visible.

See also currentIndex and highlightedIndex.

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.

Constant | Description
--- | ---
`Qt.MatchExactly` | The search term matches exactly (default).
`Qt.MatchRegExp` | The search term matches as a regular expression.
`Qt.MatchWildcard` | The search term matches using wildcards.
`Qt.MatchFixedString` | The search term matches as a fixed string.
`Qt.MatchStartsWith` | The search term matches the start of the item.
`Qt.MatchEndsWidth` | The search term matches the end of the item.
`Qt.MatchContains` | The search term is contained in the item.
`Qt.MatchCaseSensitive` | The search is case sensitive.

See also textRole.

void incrementCurrentIndex()

Increments the current index of the combo box, or the highlighted index if the popup list is visible.

See also currentIndex and highlightedIndex.

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.