Home · All Classes · All Functions · Overviews

QDeclarativeContext Class Reference
[QtDeclarative module]

The QDeclarativeContext class defines a context within a QML engine. More...

 #include <QDeclarativeContext>

Inherits QObject.

This class was introduced in Qt 4.7.


Public Functions

QDeclarativeContext ( QDeclarativeEngine * engine, QObject * parent = 0 )
QDeclarativeContext ( QDeclarativeContext * parentContext, QObject * parent = 0 )
virtual ~QDeclarativeContext ()
void addDefaultObject ( QObject * defaultObject )
QUrl baseUrl () const
QVariant contextProperty ( const QString & name ) const
QDeclarativeEngine * engine () const
QDeclarativeContext * parentContext () const
QUrl resolvedUrl ( const QUrl & src )
void setBaseUrl ( const QUrl & baseUrl )
void setContextProperty ( const QString & name, QObject * value )
void setContextProperty ( const QString & name, const QVariant & value )

Additional Inherited Members


Detailed Description

The QDeclarativeContext class defines a context within a QML engine.

Contexts allow data to be exposed to the QML components instantiated by the QML engine.

Each QDeclarativeContext contains a set of properties, distinct from its QObject properties, that allow data to be explicitly bound to a context by name. The context properties are defined or updated by calling QDeclarativeContext::setContextProperty(). The following example shows a Qt model being bound to a context and then accessed from a QML file.

 QDeclarativeEngine engine;
 QDeclarativeContext context(engine.rootContext());
 context.setContextProperty("myModel", modelData);

 QDeclarativeComponent component(&engine, "ListView { model=myModel }");
 component.create(&context);

To simplify binding and maintaining larger data sets, QObject's can be added to a QDeclarativeContext. These objects are known as the context's default objects. In this case all the properties of the QObject are made available by name in the context, as though they were all individually added by calling QDeclarativeContext::setContextProperty(). Changes to the property's values are detected through the property's notify signal. This method is also slightly more faster than manually adding property values.

The following example has the same effect as the one above, but it is achieved using a default object.

 class MyDataSet : ... {
     ...
     Q_PROPERTY(QAbstractItemModel *myModel READ model NOTIFY modelChanged)
     ...
 };

 MyDataSet myDataSet;
 QDeclarativeEngine engine;
 QDeclarativeContext context(engine.rootContext());
 context.addDefaultObject(&myDataSet);

 QDeclarativeComponent component(&engine, "ListView { model=myModel }");
 component.create(&context);

Default objects added first take precedence over those added later. All properties added explicitly by QDeclarativeContext::setContextProperty() take precedence over default object properties.

Contexts are hierarchal, with the root context being created by the QDeclarativeEngine. A component instantiated in a given context has access to that context's data, as well as the data defined by its ancestor contexts. Data values (including those added implicitly by the default objects) in a context override those in ancestor contexts. Data that should be available to all components instantiated by the QDeclarativeEngine should be added to the root context.

In the following example,

 QDeclarativeEngine engine;
 QDeclarativeContext context1(engine.rootContext());
 QDeclarativeContext context2(&context1);
 QDeclarativeContext context3(&context2);

 context1.setContextProperty("a", 12);
 context2.setContextProperty("b", 13);
 context3.setContextProperty("a", 14);
 context3.setContextProperty("c", 14);

a QML component instantiated in context1 would have access to the "a" data, a QML component instantiated in context2 would have access to the "a" and "b" data, and a QML component instantiated in context3 would have access to the "a", "b" and "c" data - although its "a" data would return 14, unlike that in context1 or context2.


Member Function Documentation

QDeclarativeContext::QDeclarativeContext ( QDeclarativeEngine * engine, QObject * parent = 0 )

Create a new QDeclarativeContext as a child of engine's root context, and the QObject parent.

QDeclarativeContext::QDeclarativeContext ( QDeclarativeContext * parentContext, QObject * parent = 0 )

Create a new QDeclarativeContext with the given parentContext, and the QObject parent.

QDeclarativeContext::~QDeclarativeContext ()   [virtual]

Destroys the QDeclarativeContext.

Any expressions, or sub-contexts dependent on this context will be invalidated, but not destroyed (unless they are parented to the QDeclarativeContext object).

void QDeclarativeContext::addDefaultObject ( QObject * defaultObject )

Add defaultObject to this context. The object will be added after any existing default objects.

QUrl QDeclarativeContext::baseUrl () const

Returns the base url of the component, or the containing component if none is set.

See also setBaseUrl().

QVariant QDeclarativeContext::contextProperty ( const QString & name ) const

Returns the value of the name property for this context as a QVariant.

See also setContextProperty().

QDeclarativeEngine * QDeclarativeContext::engine () const

Return the context's QDeclarativeEngine, or 0 if the context has no QDeclarativeEngine or the QDeclarativeEngine was destroyed.

QDeclarativeContext * QDeclarativeContext::parentContext () const

Return the context's parent QDeclarativeContext, or 0 if this context has no parent or if the parent has been destroyed.

QUrl QDeclarativeContext::resolvedUrl ( const QUrl & src )

Resolves the URL src relative to the URL of the containing component.

See also QDeclarativeEngine::baseUrl() and setBaseUrl().

void QDeclarativeContext::setBaseUrl ( const QUrl & baseUrl )

Explicitly sets the url resolvedUrl() will use for relative references to baseUrl.

Calling this function will override the url of the containing component used by default.

See also baseUrl() and resolvedUrl().

void QDeclarativeContext::setContextProperty ( const QString & name, QObject * value )

Set the value of the name property on this context.

QDeclarativeContext does not take ownership of value.

See also contextProperty().

void QDeclarativeContext::setContextProperty ( const QString & name, const QVariant & value )

Set a the value of the name property on this context.


Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt 4.7.0