QtQml.qtqml-cppintegration-interactqmlfromcpp

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.

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 2.0
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:

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

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 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 2.0
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: While it is possible to use C++ to access and manipulate QML objects deep into the object tree, we recommend that you do not take this approach outside of application testing and prototyping. One strength of QML and C++ integration is the ability to implement the QML user interface separately from the C++ logic and dataset backend, and this strategy breaks if the C++ side reaches deep into the QML components to manipulate them directly. This would make it difficult to, for example, swap a QML view component for another view, if the new component was missing a required objectName. It is better for the C++ implementation to know as little as possible about the QML user interface implementation and the composition of the QML object tree.

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 2.0
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);

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

// MyItem.qml
import QtQuick 2.0
Item {
function myQmlFunction(msg) {
console.log("Got message:", msg)
return "some return value"
}
}

// main.cpp
QQmlEngine engine;
QQmlComponent component(&engine, "MyItem.qml");
QObject object = component.create();
QVariant returnedValue;
QVariant msg = "Hello from C++";
QMetaObject::invokeMethod(object, "myQmlFunction",
Q_RETURN_ARG(QVariant, returnedValue),
Q_ARG(QVariant, msg));
qDebug() << "QML function returned:" << returnedValue.toString();
delete object;

// MyItem.qml
import QtQuick 2.0
Item {
id: item
width: 100; height: 100
signal qmlSignal(string msg)
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();
}

 // MyItem.qml
import QtQuick 2.0
Item {
id: item
width: 100; height: 100
signal qmlSignal(var anObject)
MouseArea {
anchors.fill: parent
onClicked: item.qmlSignal(item)
}
}

 class MyClass : public QObject
{
Q_OBJECT
public slots:
void cppSlot(const QVariant &v) {
qDebug() << "Called the C++ slot with value:" << v;
QQuickItem item = qobject_cast<QQuickItem>(v.value<QObject>());
qDebug() << "Item dimensions:" << item->width() << item->height();
}
};
int main(int argc, char argv[]) {
QApplication 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();
}