QmlDocument

QML documents are loaded using a specified asset name. QML documents are considered to be assets, meaning that they should be packaged with the application.

All documents loaded with this class will share the same QDeclarativeEngine which is associated with the application. However, each document will have its own QDeclarativeContext derived from the root context of the shared application engine. Properties of this context can be set using QmlDocument::setContextProperty() method. The shared context is accessible via the QmlDocument::documentContext() method. New contexts can be derived from this context and used for creating root nodes.

Once the document is successuflly loaded using the builder's QmlDocument::Builder::load(const QString&) method (one should use QmlDocument::hasErrors() method to check whether the document was loaded successfully) a root node can be instantiated for the tree represented by this document using the QmlDocument::createRootObject() template method. The root node must be a derivative of the UIObject class. Multiple root nodes can be instantiated from the same QmlDocument instance. It is possible to specify a context to create a root node with, in case a derived context needs to be created.

During the instantiation of the root node, the UIObject::creationCompleted() signal will be emitted for all UIObjects in the tree.

Note that the context properties should be set prior to instantiating the root node of the document.

A note regarding ownership of the objects associated with the QmlDocument object. By default the QmlDocument object is owned by the Application instance and will have the lifespan of the application. If the user wants to handle the lifespan the QObject::setParent method can be used to transfer the ownership. If the QmlDocument instance is only used for creating a single instance of the root object this root object can be set as a parent of the QmlDocument instance so the latter will be deleted when the node instance is deleted.

The QmlDocument object owns its encapsulated context and declarative component. The user is responsible for all contexts derived from the shared document's context. The declarative engine is owned by the application instance and must not be deleted.

The root nodes created using QmlDocument::createRootObject() are owned by the user. The QmlDocument object which was used to create the root node must have longer lifespan than the root nodes themselves.

QmlDocument *qml = QmlDocument::create("asset:///ApplicationScreen.qml");
if (!qml->hasErrors()) {
    Page *page = qml->createRootObject<Page>();
    if (page) {
        setScene(page);
    }
}
// qml object is owned by the application

Here's an example of loading and instantiating a QmlDocument document and setting shared context properties:

QmlDocument *qml = QmlDocument::create("asset:///ApplicationScreen.qml")
   // Sets shared context property myObject to 'this'
   .property("myObject", this)
   // Sets shared context property myData to 'dataObject'     
   .property("myData", dataObject);

if (!qml->hasErrors()) {
    Page *page= qml->createRootObject<Page>();
    if (page) {
        setScene(page);
    }
}

Here's an example of creating a root node with a derived context:

QmlDocument *qml = QmlDocument::create("asset:///ApplicationScreen.qml");
if (!qml->hasErrors()) {
    QDeclarativeContext *derivedContext1 = 
            new QDeclarativeContext(qml->documentContext());
    derivedContext1->setContextProperty("myObject", this);
    derivedContext1->setContextProperty("myData", dataObject1);

    // Create a control with derived declarative context
    Control *control1 =
            qml->createRootObject<Control>(derivedContext1);

    // Now create another root node with a different context
    QDeclarativeContext *derivedContext2 =
            new QDeclarativeContext(qml->documentContext());
    derivedContext2->setContextProperty("myObject", that);
    derivedContext2->setContextProperty("myData", dataObject2);
    Control *control2 =
            qml->createRootObject<Control>(derivedContext2);

    // A way to ensure the context doesn't get leaked
    derivedContext->setParent(control2);

    // ... use the created controls
}