QmlDocument

Since: BlackBerry 10.0.0

#include <bb/cascades/QmlDocument>

Represents a QML document that can be loaded into a C++ application.

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.

This example shows how to load and instantiate a QmlDocument document:
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
}
See also:

QDeclarativeEngine, QDeclarativeContext, QDeclarativeComponent, UIObject


Overview

Properties Index

QUrlsource [read-only]

Public Functions Index

virtual ~QmlDocument ()
T *createRootObject (QDeclarativeContext *context=0)
QDeclarativeContext *documentContext ()
QList< QDeclarativeError >errors ()
boolhasErrors ()
boolload ()
voidsetContextProperty (const QString &propertyName, QObject *object)
QUrlsource () const

Static Public Functions Index

Buildercreate (const QString &qmlAsset, bool autoLoad=true)
Buildercreate (const QUrl &source, bool autoLoad=true)
QDeclarativeEngine *defaultDeclarativeEngine ()

Properties

QUrl source[read-only]

A QUrl from which this document has been loaded.

Since:

BlackBerry 10.0.0

Public Functions

virtual~QmlDocument ()

Destructor.

Since:

BlackBerry 10.0.0

T * createRootObject (
  • class T,
  • QDeclarativeContext *context )

A template method for instantiating a root node from the QML document associated with this class.

The node will be created using the context associated with this document unless a specific context is specified with the optional context parameter, in which case the component will be created using that passed context.

This method can be called multiple times to create multiple instances of the root node.

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

The ownership of the returned node is transferred to the user. The document must be successfully loaded prior to this call and the type specified for the template must be a UIObject subclass, otherwise this method will return 0.

Example of creating a root node:

QmlDocument *qml = QmlDocument::create("asset:///ApplicationScreen.qml");
if (!qml->hasErrors()) {
    // Creates a control which inherits context properties from
    // the shared context
    Control *control = qml->createRootObject<Control>();
    // ...
}

Example of creating a root node with a derived context:

QmlDocument *qml = QmlDocument::create("asset:///ApplicationScreen.qml");
if (!qml->hasErrors()) {
    QDeclarativeContext *derivedContext = 
            new QDeclarativeContext(qml->documentContext());
    derivedContext->setContextProperty("myObject", dataObject);
    // Creates a control with derived declarative context
    Control *control =
            qml->createRootObject<Control>(derivedContext);
    // ...
}
Return:

A newly created root object of the tree represented by the document, or 0 if the root node cannot be created.

Parameters
context

An optional context for creating the root node. If not set the shared document's context will be used for creating the root node.

See also:

documentContext(), QDeclarativeComponent::create()

Since:

BlackBerry 10.0.0

QDeclarativeContext * documentContext ()

Returns the shared context associated with this document.

This context is derived from the root context of the shared QDeclarativeEngine.

One would typically use this method in case there's a need to override context properties for a new instance of the root node. In this case one can create a child context, override context properties on this new context and use it to create the root node.

The QmlDocument owns the returned context. However, the user will be responsible for derived contexts created from this context.

Return:

A shared context associated with this document.

Since:

BlackBerry 10.0.0

QList< QDeclarativeError > errors ()

Returns the list of the errors produced when loading the document.

The list will be empty if there were no errors or the document hasn't yet been loaded.

Return:

A list of errors.

Since:

BlackBerry 10.0.0

bool hasErrors ()

Returns false when this document was successfully loaded.

This method returns false if the document associated with this object was loaded successfully. It returns true if the document hasn't yet been loaded or it failed to load. If it failed to load the QmlDocument::errors() method can used to get the list of errors.

See also:

errors(), Builder::load()

Return:

true if this document has errors, false otherwise.

Since:

BlackBerry 10.0.0

bool load ()

Explictly loads this document.

If the document is already loaded, this function has no effect

Return:

returns true if loadded successfully, false otherwise.

Since:

BlackBerry 10.0.0

void setContextProperty (

Sets the context property for the shared context associated with this document.

Each document has its own context derived from the root context of the shared declarative engine.

For your own contexts derived from the shared context associated with the documents you will need to use QDeclarativeContext::setContextProperty directly.

Parameters
propertyName

The name of the context property to set.

object

The value of the property to set.

Since:

BlackBerry 10.0.0

QUrl source ()

Returns the source QUrl from which this document has been loaded.

Return:

the source QUrl

Since:

BlackBerry 10.0.0

Static Public Functions

Builder create (
  • const QString &qmlAsset,
  • boolautoLoad )

Creates and returns a builder for constructing a QmlDocument instance with a parent object and an asset name to load the document from.

Parameters
qmlAsset

The QML asset name load the document from, specified relative to the assets root.

autoLoad

if true the document is automatic loaded, otherwise it is required to call load fuction explicitly. The default is true .

Since:

BlackBerry 10.0.0

Builder create (
  • const QUrl &source,
  • boolautoLoad )

Creates and returns a builder for constructing a QmlDocument instance with a parent object and a URL to load the document from.

Parameters
source

The URL to load the document from. Currently only relative and "file://" URLs are supported

autoLoad

if true the document is automatic loaded, otherwise it is required to call load fuction explicitly. The default is true .

Since:

BlackBerry 10.0.0

QDeclarativeEngine * defaultDeclarativeEngine ()

Returns the default declarative engine used to load and create this document.

The declarative engine is owned by the bb::cascades::Application instance and is not supposed to change ownership.

See also:

QDeclarativeEngine

Return:

the default declarative engine

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus