- Qt 6.9
- Qt Qml
- Overview - QML and C++ Integration
- Interacting with QML Objects from C++
- Qt 6.9.3 Reference Documentation

Exposing State from C++ to QML ◦ Integrating with JavaScript values from C++

# Interacting with QML Objects from C++

All QML object types are QObject-derived types, whether they are internally implemented by the engine or defined by third-party sources. This means the QML engine can use the Qt Meta Object System to dynamically instantiate any QML object type and inspect the created objects.

This is useful for creating QML objects from C++ code, whether to display a QML object that can be visually rendered, or to integrate non-visual QML object data into a C++ application. Once a QML object is created, it can be inspected from C++ in order to read and write to properties, invoke methods and receive signal notifications.

For more information about C++ and the different QML integration methods, see the C++ and QML integration overview page.

## Loading QML Objects from C++

A QML document can be loaded with QQmlComponent or QQuickView. QQmlComponent loads a QML document as a C++ object that can then be modified from C++ code. QQuickView also does this, but as QQuickView is a QWindow-derived class, the loaded object will also be rendered into a visual display; QQuickView is generally used to integrate a displayable QML object into an application's user interface.

For example, suppose there is a `MyItem.qml` file that looks like this:

     import QtQuick

     Item {
         width: 100; height: 100
     }

This QML document can be loaded with QQmlComponent or QQuickView with the following C++ code. Using a QQmlComponent requires calling QQmlComponent::create() to create a new instance of the component, while a QQuickView automatically creates an instance of the component, which is accessible via QQuickView::rootObject():

     // Using QQmlComponent
     QQmlEngine engine;
     QQmlComponent component(&engine,
             QUrl::fromLocalFile("MyItem.qml"));
     QObject *object = component.create();
     ...
     delete object;

     // Using QQuickView
     QQuickView view;
     view.setSource(QUrl::fromLocalFile("MyItem.qml"));
     view.show();
     QObject *object = view.rootObject();

This `object` is the instance of the `MyItem.qml` component that has been created. You can now modify the item's properties using QObject::setProperty() or QQmlProperty::write():

     object->setProperty("width", 500);
     QQmlProperty(object, "width").write(500);

The difference between `QObject::setProperty()` and `QQmlProperty::write()` is that the latter will also remove the binding in addition to setting the property value. For example, suppose the `width` assignment above had been a binding to `height`:

     width: height

If the `height` of the `Item` changed after the `object->setProperty("width", 500)` call, the `width` would be updated again, as the binding remains active. However, if the `height` changes after the `QQmlProperty(object, "width").write(500)` call, the `width` will not be changed, as the binding does not exist anymore.

Alternatively, you can cast the object to its actual type and call methods with compile-time safety. In this case the base object of `MyItem.qml` is an Item, which is defined by the QQuickItem class:

     QQuickItem *item = qobject_cast<QQuickItem*>(object);
     item->setWidth(500);

You can also connect to any signals or call methods defined in the component using QMetaObject::invokeMethod() and QObject::connect(). See Invoking QML Methods and Connecting to QML Signals below for further details.

## Accessing QML Objects via well-defined C++ Interfaces

The best way of interacting with QML from C++ is to define an interface for doing so in C++ and accessing it in QML itself. With other methods, refactoring your QML code can easily lead to your QML / C++ interaction breaking. It also helps to reason about the interaction of QML and C++ code, as having it driven via QML can be more easily reasoned about by both users and tooling such as qmllint. Accessing QML from C++ will lead to QML code that cannot be understood without manually verifying that no outside C++ code is modifying a given QML component, and even then the extent of the access might change over time, making continued use of this strategy a maintenance burden.

To let QML drive the interaction, first you need to define a C++ interface:

     class CppInterface : public QObject
     {
         Q_OBJECT
         QML_ELEMENT
         // ...
     };

Using a QML-driven approach, this interface can be interacted with in two ways:

### Singletons

One option is to register the interface as a singleton by adding the QML_SINGLETON macro to the interface, exposing it to all components. Following that, the interface becomes available via a simple import statement:

     import my.company.module

     Item {
         Component.onCompleted: {
             CppInterface.foo();
         }
     }

Use this approach if you need your interface in more places than the root component, as simply passing down an object would require explicitly passing it on to other components via a property or utilizing the slow and not recommended method of using unqualified access.

### Initial properties

Another option is to mark the interface as uncreatable via QML_UNCREATABLE and supplying it to the root QML Component by using QQmlComponent::createWithInitialProperties() and a required property on the QML end.

Your root component may look something like this:

     import QtQuick

     Item {
         required property CppInterface interface
         Component.onCompleted: {
             interface.foo();
         }
     }

Marking the property as required here protects the component against being created without the interface property being set.

You can then initialize your component in the same way as outlined in Loading QML Objects from C++ except using `createWithInitialProperties()`:

     component.createWithInitialProperties(QVariantMap{{u"interface"_s, QVariant::fromValue<CppInterface *>(new CppInterface)}});

This method is to be preferred if you know that your interface only needs to be available to the root component. It also allows for connecting to signals and slots of the interface more easily on the C++ side.

If neither of these methods suit your needs you may want to investigate the usage of C++ models instead.

## Accessing Loaded QML Objects by Object Name

QML components are essentially object trees with children that have siblings and their own children. Child objects of QML components can be located using the QObject::objectName property with QObject::findChild(). For example, if the root item in `MyItem.qml` had a child Rectangle item:

     import QtQuick

     Item {
         width: 100; height: 100

         Rectangle {
             anchors.fill: parent
             objectName: "rect"
         }
     }

The child could be located like this:

     QObject *rect = object->findChild<QObject*>("rect");
     if (rect)
         rect->setProperty("color", "red");

Note that an object may have multiple children with the same `objectName`. For example, ListView creates multiple instances of its delegate, so if its delegate is declared with a particular objectName, the ListView will have multiple children with the same `objectName`. In this case, QObject::findChildren() can be used to find all children with a matching `objectName`.

Warning: Although it is possible to access QML objects from C++ and manipulate them, it is not the recommended approach, except for testing and prototyping purposes. One of the strengths of QML and C++ integration is the ability to implement UIs in QML separate from the C++ logic and dataset backend, and this fails if the C++ side starts manipulating QML directly. Such an approach also makes changing the QML UI difficult without affecting its C++ counterpart.

## Accessing Members of a QML Object Type from C++

### Properties

Any properties declared in a QML object are automatically accessible from C++. Given a QML item like this:

     // MyItem.qml
     import QtQuick

     Item {
         property int someNumber: 100
     }

The value of the `someNumber` property can be set and read using QQmlProperty, or QObject::setProperty() and QObject::property():

     QQmlEngine engine;
     QQmlComponent component(&engine, "MyItem.qml");
     QObject *object = component.create();

     qDebug() << "Property value:" << QQmlProperty::read(object, "someNumber").toInt();
     QQmlProperty::write(object, "someNumber", 5000);

     qDebug() << "Property value:" << object->property("someNumber").toInt();
     object->setProperty("someNumber", 100);

You should always use QObject::setProperty(), QQmlProperty or QMetaProperty::write() to change a QML property value, to ensure the QML engine is made aware of the property change. For example, say you have a custom type `PushButton` with a `buttonText` property that internally reflects the value of a `m_buttonText` member variable. Modifying the member variable directly like this is not a good idea:

     //bad code
     QQmlComponent component(engine, "MyButton.qml");
     PushButton *button = qobject_cast<PushButton*>(component.create());
     button->m_buttonText = "Click me";

Since the value is changed directly, this bypasses Qt's meta-object system and the QML engine is not made aware of the property change. This means property bindings to `buttonText` would not be updated, and any `onButtonTextChanged` handlers would not be called.

### Invoking QML Methods

All QML methods are exposed to the meta-object system and can be called from C++ using QMetaObject::invokeMethod(). You can specify types for the parameters and the return value after the colon character, as shown in the code snippet below. This can be useful, for example, when you want to connect a signal in C++ with a certain signature to a QML-defined method. If you omit the types, the C++ signature will use QVariant.

Here is a C++ application that calls a QML method using QMetaObject::invokeMethod():

QML

     // MyItem.qml
     import QtQuick

     Item {
         function myQmlFunction(msg: string) : string {
             console.log("Got message:", msg)
             return "some return value"
         }
     }

C++

     // main.cpp
     QQmlEngine engine;
     QQmlComponent component(&engine, "MyItem.qml");
     QObject *object = component.create();

     QString returnedValue;
     QString msg = "Hello from C++";
     QMetaObject::invokeMethod(object, "myQmlFunction",
             Q_RETURN_ARG(QString, returnedValue),
             Q_ARG(QString, msg));

     qDebug() << "QML function returned:" << returnedValue;
     delete object;

Notice the parameter and return type specified after the colon. You can use value types and object types as type names.

If the type is omitted or specified as `var` in QML, then you must pass QVariant as type with Q_RETURN_ARG() and Q_ARG() when calling QMetaObject::invokeMethod.

### Connecting to QML Signals

All QML signals are automatically available to C++, and can be connected to using QObject::connect() like any ordinary Qt C++ signal. In return, any C++ signal can be received by a QML object using signal handlers.

Here is a QML component with a signal named `qmlSignal` that is emitted with a string-type parameter. This signal is connected to a C++ object's slot using QObject::connect(), so that the `cppSlot()` method is called whenever the `qmlSignal` is emitted:

     // MyItem.qml
     import QtQuick

     Item {
         id: item
         width: 100; height: 100

         signal qmlSignal(msg: string)

         MouseArea {
             anchors.fill: parent
             onClicked: item.qmlSignal("Hello from QML")
         }
     }

     class MyClass : public QObject
     {
         Q_OBJECT
     public slots:
         void cppSlot(const QString &msg) {
             qDebug() << "Called the C++ slot with message:" << msg;
         }
     };

     int main(int argc, char *argv[]) {
         QGuiApplication app(argc, argv);

         QQuickView view(QUrl::fromLocalFile("MyItem.qml"));
         QObject *item = view.rootObject();

         MyClass myClass;
         QObject::connect(item, SIGNAL(qmlSignal(QString)),
                          &myClass, SLOT(cppSlot(QString)));

         view.show();
         return app.exec();
     }

A QML object type in a signal parameter is translated to a pointer to the class in C++:

     // MyItem.qml
     import QtQuick 2.0

     Item {
         id: item
         width: 100; height: 100

         signal qmlSignal(anObject: Item)

         MouseArea {
             anchors.fill: parent
             onClicked: item.qmlSignal(item)
         }
     }

     class MyClass : public QObject
     {
         Q_OBJECT
     public slots:
         void cppSlot(QQuickItem *item) {
            qDebug() << "Called the C++ slot with item:" << item;

            qDebug() << "Item dimensions:" << item->width()
                     << item->height();
         }
     };

     int main(int argc, char *argv[]) {
         QGuiApplication app(argc, argv);

         QQuickView view(QUrl::fromLocalFile("MyItem.qml"));
         QObject *item = view.rootObject();

         MyClass myClass;
         QObject::connect(item, SIGNAL(qmlSignal(QVariant)),
                          &myClass, SLOT(cppSlot(QVariant)));

         view.show();
         return app.exec();
     }