QDeclarativeContext Class Reference

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

#include <qdeclarativecontext.h>

Inheritance diagram for QDeclarativeContext:

Public Functions
QUrl	baseUrl () const
	Returns the base url of the component, or the containing component if none is set. More...
QObject *	contextObject () const
	Return the context object, or 0 if there is no context object. More...
QVariant	contextProperty (const QString &) const
	Returns the value of the name property for this context as a QVariant. More...
QDeclarativeEngine *	engine () const
	Return the context's QDeclarativeEngine, or 0 if the context has no QDeclarativeEngine or the QDeclarativeEngine was destroyed. More...
bool	isValid () const
	Returns whether the context is valid. More...
QDeclarativeContext *	parentContext () const
	Return the context's parent QDeclarativeContext, or 0 if this context has no parent or if the parent has been destroyed. More...
	QDeclarativeContext (QDeclarativeEngine *parent, QObject *objParent=0)
	Create a new QDeclarativeContext as a child of engine's root context, and the QObject parent. More...
	QDeclarativeContext (QDeclarativeContext *parent, QObject *objParent=0)
	Create a new QDeclarativeContext with the given parentContext, and the QObject parent. More...
QUrl	resolvedUrl (const QUrl &)
	Resolves the URL src relative to the URL of the containing component. More...
void	setBaseUrl (const QUrl &)
	Explicitly sets the url resolvedUrl() will use for relative references to baseUrl. More...
void	setContextObject (QObject *)
	Set the context object. More...
void	setContextProperty (const QString &, QObject *)
	Set the value of the name property on this context. More...
void	setContextProperty (const QString &, const QVariant &)
	Set a the value of the name property on this context. More...
virtual	~QDeclarativeContext ()
	Destroys the QDeclarativeContext. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	event (QEvent *)
	This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Private Functions
	QDeclarativeContext (QDeclarativeContextData *)
	QDeclarativeContext (QDeclarativeEngine *, bool)

Friends
class	QDeclarativeBoundSignalProxy
class	QDeclarativeComponent
class	QDeclarativeComponentPrivate
class	QDeclarativeContextData
class	QDeclarativeContextScriptClass
class	QDeclarativeEngine
class	QDeclarativeEnginePrivate
class	QDeclarativeExpression
class	QDeclarativeExpressionPrivate
class	QDeclarativeObjectScriptClass
class	QDeclarativeScriptPrivate
class	QDeclarativeVME

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

The QDeclarativeContext class defines a context within a QML engine.

Since

4.7

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 and 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;
QStringListModel modelData;
QDeclarativeContext *context = new QDeclarativeContext(engine.rootContext());
context->setContextProperty("myModel", &modelData);

QDeclarativeComponent component(&engine);
component.setData("import QtQuick 1.0\nListView { model: myModel }", QUrl());
QObject *window = component.create(context);

Note it is the responsibility of the creator to delete any QDeclarativeContext it constructs. If the context object in the example is no longer needed when the window component instance is destroyed, the context must be destroyed explicitly. The simplest way to ensure this is to set window as the parent of context.

To simplify binding and maintaining larger data sets, a context object can be set on a QDeclarativeContext. All the properties of the context object are available by name in the context, as though they were all individually added through calls to QDeclarativeContext::setContextProperty(). Changes to the property's values are detected through the property's notify signal. Setting a context object is both faster and easier than manually adding and maintaing context property values.

The following example has the same effect as the previous one, but it uses a context object.

class MyDataSet : ... {
    ...
    QAbstractItemModel *myModel;
    ...
};

MyDataSet myDataSet;
QDeclarativeEngine engine;
QDeclarativeContext *context = new QDeclarativeContext(engine.rootContext());
context->setContextObject(&myDataSet);

QDeclarativeComponent component(&engine);
component.setData("import QtQuick 1.0\nListView { model: myModel }", QUrl());
component.create(context);

All properties added explicitly by QDeclarativeContext::setContextProperty() take precedence over the context object's properties.

The Context Hierarchy

Contexts form a hierarchy. The root of this hierarchy is the QML engine's QDeclarativeEngine::rootContext(){root context}. Child contexts inherit the context properties of their parents; if a child context sets a context property that already exists in its parent, the new context property overrides that of the parent.

The following example defines two contexts - context1 and context2. The second context overrides the "b" context property inherited from the first with a new value.

QDeclarativeEngine engine;
QDeclarativeContext *context1 = new QDeclarativeContext(engine.rootContext());
QDeclarativeContext *context2 = new QDeclarativeContext(context1);

context1->setContextProperty("a", 12);
context1->setContextProperty("b", 12);

context2->setContextProperty("b", 15);

While QML objects instantiated in a context are not strictly owned by that context, their bindings are. If a context is destroyed, the property bindings of outstanding QML objects will stop evaluating.

Warning

Setting the context object or adding new context properties after an object has been created in that context is an expensive operation (essentially forcing all bindings to reevaluate). Thus whenever possible you should complete "setup" of the context before using it to create any objects.

See also

{Using QML Bindings in C++ Applications}

Definition at line 64 of file qdeclarativecontext.h.

Constructors and Destructors

QDeclarativeContext() [1/4]

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

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

Definition at line 179 of file qdeclarativecontext.cpp.

: QObject(*(new QDeclarativeContextPrivate), parent)
{
    Q_D(QDeclarativeContext);
    d->data = new QDeclarativeContextData(this);

    d->data->setParent(engine?QDeclarativeContextData::get(engine->rootContext()):0);
}

QDeclarativeContext() [2/4]

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

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

Definition at line 192 of file qdeclarativecontext.cpp.

: QObject(*(new QDeclarativeContextPrivate), parent)
{
    Q_D(QDeclarativeContext);
    d->data = new QDeclarativeContextData(this);

    d->data->setParent(parentContext?QDeclarativeContextData::get(parentContext):0);
}

~QDeclarativeContext()

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).

Definition at line 218 of file qdeclarativecontext.cpp.

{
    Q_D(QDeclarativeContext);

    if (!d->data->isInternal)
        d->data->destroy();
}

QDeclarativeContext() [3/4]

QDeclarativeContext::QDeclarativeContext ( QDeclarativeContextData *  data )

private

Warning

This function is not part of the public interface.

Definition at line 204 of file qdeclarativecontext.cpp.

: QObject(*(new QDeclarativeContextPrivate), 0)
{
    Q_D(QDeclarativeContext);
    d->data = data;
}

QDeclarativeContext() [4/4]

QDeclarativeContext::QDeclarativeContext ( QDeclarativeEngine *  e, bool    )

private

Warning

This function is not part of the public interface.

Definition at line 166 of file qdeclarativecontext.cpp.

: QObject(*(new QDeclarativeContextPrivate))
{
    Q_D(QDeclarativeContext);
    d->data = new QDeclarativeContextData(this);

    d->data->engine = e;
}

Functions

baseUrl()

QUrl QDeclarativeContext::baseUrl

(

)

const

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

Definition at line 463 of file qdeclarativecontext.cpp.

Referenced by setBaseUrl().

{
    Q_D(const QDeclarativeContext);
    const QDeclarativeContextData* data = d->data;
    while (data && data->url.isEmpty())
        data = data->parent;

    if (data)
        return data->url;
    else
        return QUrl();
}

contextObject()

QObject * QDeclarativeContext::contextObject

(

)

const

Return the context object, or 0 if there is no context object.

Definition at line 261 of file qdeclarativecontext.cpp.

{
    Q_D(const QDeclarativeContext);
    return d->data->contextObject;
}

contextProperty()

QVariant QDeclarativeContext::contextProperty

(

const QString &

name

)

const

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

Definition at line 374 of file qdeclarativecontext.cpp.

Referenced by QDeclarativeContextPrivate::context_at(), QDeclarativeContextPrivate::context_count(), contextProperty(), and QDeclarativeVisualDataModel::indexOf().

{
    Q_D(const QDeclarativeContext);
    QVariant value;
    int idx = -1;

    QDeclarativeContextData *data = d->data;

    if (data->propertyNames)
        idx = data->propertyNames->value(name);

    if (idx == -1) {
        QByteArray utf8Name = name.toUtf8();
        if (data->contextObject) {
            QObject *obj = data->contextObject;
            QDeclarativePropertyCache::Data local;
            QDeclarativePropertyCache::Data *property =
                QDeclarativePropertyCache::property(data->engine, obj, name, local);

            if (property) value = obj->metaObject()->property(property->coreIndex).read(obj);
        }
        if (!value.isValid() && parentContext())
            value = parentContext()->contextProperty(name);
    } else {
        if (idx >= d->propertyValues.count())
            value = QVariant::fromValue(data->idValues[idx - d->propertyValues.count()].data());
        else
            value = d->propertyValues[idx];
    }

    return value;
}

engine()

QDeclarativeEngine * QDeclarativeContext::engine

(

)

const

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

Definition at line 242 of file qdeclarativecontext.cpp.

Referenced by QDeclarativeQtScriptExpression::eval(), QTextDocumentWithImageResources::loadResource(), QDeclarativeProperty::QDeclarativeProperty(), qmlEngine(), QDeclarativeXmlListModel::reload(), QDeclarativeContextData::resolvedUrl(), QDeclarativeExpressionPrivate::scriptValue(), and QDeclarativeEngineDebugService::setMethodBody().

{
    Q_D(const QDeclarativeContext);
    return d->data->engine;
}

isValid()

bool QDeclarativeContext::isValid

(

)

const

Returns whether the context is valid.

To be valid, a context must have a engine, and it's contextObject(), if any, must not have been deleted.

Definition at line 232 of file qdeclarativecontext.cpp.

Referenced by setContextObject(), and setContextProperty().

{
    Q_D(const QDeclarativeContext);
    return d->data && d->data->isValid();
}

parentContext()

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.

Definition at line 252 of file qdeclarativecontext.cpp.

Referenced by contextProperty(), and QDeclarativeListViewPrivate::createSection().

{
    Q_D(const QDeclarativeContext);
    return d->data->parent?d->data->parent->asQDeclarativeContext():0;
}

resolvedUrl()

QUrl QDeclarativeContext::resolvedUrl

(

const QUrl &

src

)

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

See also

QDeclarativeEngine::baseUrl(), setBaseUrl()

Definition at line 413 of file qdeclarativecontext.cpp.

Referenced by QTextDocumentWithImageResources::loadResource(), and QDeclarativeFontLoader::setSource().

{
    Q_D(QDeclarativeContext);
    return d->data->resolvedUrl(src);
}

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

resolvedUrl()

Definition at line 452 of file qdeclarativecontext.cpp.

{
    Q_D(QDeclarativeContext);

    d->data->url = baseUrl;
}

setContextObject()

void QDeclarativeContext::setContextObject

(

QObject *

object

)

Set the context object.

Definition at line 270 of file qdeclarativecontext.cpp.

Referenced by QDeclarativeLoaderPrivate::_q_sourceLoaded(), and QDeclarativeVisualDataModel::item().

{
    Q_D(QDeclarativeContext);

    QDeclarativeContextData *data = d->data;

    if (data->isInternal) {
        qWarning("QDeclarativeContext: Cannot set context object for internal context.");
        return;
    }

    if (!isValid()) {
        qWarning("QDeclarativeContext: Cannot set context object on invalid context.");
        return;
    }

    data->contextObject = object;
}

setContextProperty() [1/2]

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.

Definition at line 338 of file qdeclarativecontext.cpp.

Referenced by QDeclarativeListViewPrivate::createSection(), QDeclarativeVisualDataModel::item(), and setContextProperty().

{
    Q_D(QDeclarativeContext);
    if (d->notifyIndex == -1)
        d->notifyIndex = this->metaObject()->methodCount();

    QDeclarativeContextData *data = d->data;

    if (data->isInternal) {
        qWarning("QDeclarativeContext: Cannot set property on internal context.");
        return;
    }

    if (!isValid()) {
        qWarning("QDeclarativeContext: Cannot set property on invalid context.");
        return;
    }

    if (!data->propertyNames) data->propertyNames = new QDeclarativeIntegerCache(data->engine);
    int idx = data->propertyNames->value(name);

    if (idx == -1) {
        data->propertyNames->add(name, data->idValueCount + d->propertyValues.count());
        d->propertyValues.append(QVariant::fromValue(value));

        data->refreshExpressions();
    } else {
        d->propertyValues[idx] = QVariant::fromValue(value);
        QMetaObject::activate(this, idx + d->notifyIndex, 0);
    }
}

setContextProperty() [2/2]

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

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

Definition at line 292 of file qdeclarativecontext.cpp.

{
    Q_D(QDeclarativeContext);
    if (d->notifyIndex == -1)
        d->notifyIndex = this->metaObject()->methodCount();

    QDeclarativeContextData *data = d->data;

    if (data->isInternal) {
        qWarning("QDeclarativeContext: Cannot set property on internal context.");
        return;
    }

    if (!isValid()) {
        qWarning("QDeclarativeContext: Cannot set property on invalid context.");
        return;
    }

    if (data->engine) {
        bool ok;
        QObject *o = QDeclarativeEnginePrivate::get(data->engine)->toQObject(value, &ok);
        if (ok) {
            setContextProperty(name, o);
            return;
        }
    }

    if (!data->propertyNames) data->propertyNames = new QDeclarativeIntegerCache(data->engine);

    int idx = data->propertyNames->value(name);
    if (idx == -1) {
        data->propertyNames->add(name, data->idValueCount + d->propertyValues.count());
        d->propertyValues.append(value);

        data->refreshExpressions();
    } else {
        d->propertyValues[idx] = value;
        QMetaObject::activate(this, idx + d->notifyIndex, 0);
    }
}

Friends and Related Functions

QDeclarativeBoundSignalProxy

friend class QDeclarativeBoundSignalProxy

friend

Definition at line 102 of file qdeclarativecontext.h.

QDeclarativeComponent

friend class QDeclarativeComponent

friend

Definition at line 99 of file qdeclarativecontext.h.

QDeclarativeComponentPrivate

friend class QDeclarativeComponentPrivate

friend

Definition at line 100 of file qdeclarativecontext.h.

QDeclarativeContextData

friend class QDeclarativeContextData

friend

Definition at line 103 of file qdeclarativecontext.h.

Referenced by QDeclarativeContext().

QDeclarativeContextScriptClass

friend class QDeclarativeContextScriptClass

friend

Definition at line 97 of file qdeclarativecontext.h.

QDeclarativeEngine

friend class QDeclarativeEngine

friend

Definition at line 93 of file qdeclarativecontext.h.

QDeclarativeEnginePrivate

friend class QDeclarativeEnginePrivate

friend

Definition at line 94 of file qdeclarativecontext.h.

QDeclarativeExpression

friend class QDeclarativeExpression

friend

Definition at line 95 of file qdeclarativecontext.h.

QDeclarativeExpressionPrivate

friend class QDeclarativeExpressionPrivate

friend

Definition at line 96 of file qdeclarativecontext.h.

QDeclarativeObjectScriptClass

friend class QDeclarativeObjectScriptClass

friend

Definition at line 98 of file qdeclarativecontext.h.

QDeclarativeScriptPrivate

friend class QDeclarativeScriptPrivate

friend

Definition at line 101 of file qdeclarativecontext.h.

QDeclarativeVME

friend class QDeclarativeVME

friend

Definition at line 92 of file qdeclarativecontext.h.

---

The documentation for this class was generated from the following files:

• /src/declarative/qml/qdeclarativecontext.h
• /src/declarative/qml/qdeclarativecontext.cpp