Qt Quick Controls QML Types

Qt Quick Controls provides QML types for creating user interfaces. These QML types work in conjunction with Qt Quick and Qt Quick Layouts.

Qt Quick Controls QML types can be imported into your application using the following import statement in your .qml file:

 import QtQuick.Controls

QML Types

Using Qt Quick Controls types in property declarations

As mentioned in Qt Quick Templates 2 QML Types, each type in Qt Quick Controls is backed by a C++ "template" type. These types are non-visual implementations of controls' logic and behavior.

For example, the Menu type's API and behavior is defined by the C++ type in Qt Quick Templates. Each style that wants to provide a Menu must have a Menu.qml available, and the root item in that file must be the Menu from Qt Quick Templates. When you import QtQuick.Controls and create a Menu in QML, the type you get is actually the QML Menu defined by the style's Menu.qml.

In order to use a control as the type in a property declaration, you should use the corresponding type from Qt Quick Templates. For example, suppose you had a PopupOpener component, which was a Button that opened a Popup:

 // PopupButton.qml
 import QtQuick.Controls

 Button {
     required property Popup popup

     onClicked: popup.open()
 }

 // main.qml
 PopupButton {
     popup: saveChangesDialog
 }

 Dialog {
     id: saveChangesDialog

     // ...
 }

Running this code will result in an error:

 Unable to assign Dialog_QMLTYPE to Popup_QMLTYPE

This is because of the inheritance hierarchy:

 Popup (C++ type in QtQuick.Templates)
 │   └── Popup (QML type in QtQuick.Controls)
 └── Dialog (C++ type in QtQuick.Templates)
     └── Dialog (QML type in QtQuick.Controls)

Dialog from QtQuick.Controls does not derive from the Popup from QtQuick.Controls, but from QtQuick.Templates.

Instead, use the Popup from Qt Quick Templates as the property type:

 // PopupButton.qml
 import QtQuick.Controls
 import QtQuick.Templates as T

 Button {
     required property T.Popup popup

     onClicked: popup.open()
 }

For more information on the Qt Quick Controls module, see the Qt Quick Controls module documentation.

Related Information

• Qt Quick Controls Guidelines