QQmlExpression Class Reference

The QQmlExpression class evaluates JavaScript in a QML context. More...

#include <qqmlexpression.h>

Inheritance diagram for QQmlExpression:

Collaboration diagram for QQmlExpression:

Signals
void	valueChanged ()
	Emitted each time the expression value changes from the last time it was evaluated.
Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Public Member Functions
	QQmlExpression ()
	Create an invalid QQmlExpression.
	QQmlExpression (QQmlContext *, QObject *, const QString &, QObject *=nullptr)
	Create a QQmlExpression object that is a child of parent.
	QQmlExpression (const QQmlScriptString &, QQmlContext *=nullptr, QObject *=nullptr, QObject *=nullptr)
	Create a QQmlExpression object that is a child of parent.
	~QQmlExpression () override
	Destroy the QQmlExpression instance.
QQmlEngine *	engine () const
	Returns the QQmlEngine this expression is associated with, or \nullptr if there is no association or the QQmlEngine has been destroyed.
QQmlContext *	context () const
	Returns the QQmlContext this expression is associated with, or \nullptr if there is no association or the QQmlContext has been destroyed.
QString	expression () const
	Returns the expression string.
void	setExpression (const QString &)
	Set the expression to expression.
bool	notifyOnValueChanged () const
	Returns true if the valueChanged() signal is emitted when the expression's evaluated value changes.
void	setNotifyOnValueChanged (bool)
	Sets whether the valueChanged() signal is emitted when the expression's evaluated value changes.
QString	sourceFile () const
	Returns the source file URL for this expression.
int	lineNumber () const
	Returns the source file line number for this expression.
int	columnNumber () const
	Returns the source file column number for this expression.
void	setSourceLocation (const QString &fileName, int line, int column=0)
	Set the location of this expression to line and column of url.
QObject *	scopeObject () const
	Returns the expression's scope object, if provided, otherwise 0.
bool	hasError () const
	Returns true if the last call to evaluate() resulted in an error, otherwise false.
void	clearError ()
	Clear any expression errors.
QQmlError	error () const
	Return any error from the last call to evaluate().
QVariant	evaluate (bool *valueIsUndefined=nullptr)
	Evaulates the expression, returning the result of the evaluation, or an invalid QVariant if the expression is invalid or has an error.
Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.
virtual	~QObject ()
	Destroys the object, deleting all its child objects.
virtual bool	event (QEvent *event)
	This virtual function receives events to an object and should return true if the event e was recognized and processed.
virtual bool	eventFilter (QObject *watched, QEvent *event)
	Filters events if this object has been installed as an event filter for the watched object.
QString	objectName () const
Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.
void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QBindable< QString >	bindableObjectName ()
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false.
bool	isWindowType () const
	Returns true if the object is a window; otherwise returns false.
bool	isQuickItemType () const
	Returns true if the object is a QQuickItem; otherwise returns false.
bool	signalsBlocked () const noexcept
	Returns true if signals are blocked; otherwise returns false.
bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
QThread *	thread () const
	Returns the thread in which the object lives.
bool	moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
	Changes the thread affinity for this object and its children and returns true on success.
int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
int	startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
void	killTimer (int id)
	Kills the timer with timer identifier, id.
void	killTimer (Qt::TimerId id)
template<typename T >
T	findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
template<typename T >
QList< T >	findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) 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.
template<typename T >
T	findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
const QObjectList &	children () const
	Returns a list of child objects.
void	setParent (QObject *parent)
	Makes the object a child of parent.
void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.
void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
bool	disconnect (const QObject *receiver, const char *member=nullptr) const
void	dumpObjectTree () const
	Dumps a tree of children to the debug output.
void	dumpObjectInfo () const
	Dumps information about signal connections, etc.
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.
bool	setProperty (const char *name, QVariant &&value)
QVariant	property (const char *name) const
	Returns the value of the object's name property.
QList< QByteArray >	dynamicPropertyNames () const
QBindingStorage *	bindingStorage ()
const QBindingStorage *	bindingStorage () const
QObject *	parent () const
	Returns a pointer to the parent object.
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.

Friends
class	QQmlDebugger
class	QQmlContext

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe
Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe
static QMetaObject::Connection	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	\threadsafe
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.
template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
Protected Member Functions inherited from QObject
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 \nullptr.
int	senderSignalIndex () const
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.
bool	isSignalConnected (const QMetaMethod &signal) const
virtual void	timerEvent (QTimerEvent *event)
	This event handler can be reimplemented in a subclass to receive timer events for the object.
virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.
virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.
virtual void	connectNotify (const QMetaMethod &signal)
virtual void	disconnectNotify (const QMetaMethod &signal)
	QObject (QObjectPrivate &dd, QObject *parent=nullptr)
Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Properties inherited from QObject
QString	objectName
	the name of this object
Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

The QQmlExpression class evaluates JavaScript in a QML context.

Since

5.0 \inmodule QtQml

For example, given a file main.qml like this:

\qml import QtQuick 2.0

Item { width: 200; height: 200 } \endqml

The following code evaluates a JavaScript expression in the context of the above QML:

QQmlEngine *engine = new QQmlEngine;
QQmlComponent component(engine, QUrl::fromLocalFile("main.qml"));
 
QObject *myObject = component.create();
QQmlExpression *expr = new QQmlExpression(engine->rootContext(), myObject, "width * 2");
int result = expr->evaluate().toInt();  // result = 400

Definition at line 21 of file qqmlexpression.h.

Constructor & Destructor Documentation

QQmlExpression() [1/3]

QQmlExpression::QQmlExpression

(

)

Create an invalid QQmlExpression.

As the expression will not have an associated QQmlContext, this will be a null expression object and its value will always be an invalid QVariant.

Definition at line 86 of file qqmlexpression.cpp.

QQmlExpression() [2/3]

QQmlExpression::QQmlExpression	(	QQmlContext *	ctxt,
		QObject *	scope,
		const QString &	expression,
		QObject *	parent = nullptr )

Create a QQmlExpression object that is a child of parent.

The expression JavaScript will be executed in the ctxt QQmlContext. If specified, the scope object's properties will also be in scope during the expression's execution.

Definition at line 154 of file qqmlexpression.cpp.

References d, expression(), and QQmlContextData::get().

Here is the call graph for this function:

QQmlExpression() [3/3]

QQmlExpression::QQmlExpression ( const QQmlScriptString & script, QQmlContext * ctxt = nullptr, QObject * scope = nullptr, QObject * parent = nullptr )

explicit

Create a QQmlExpression object that is a child of parent.

The script provides the expression to be evaluated, the context to evaluate it in, and the scope object to evaluate it with. If provided, ctxt and scope will override the context and scope object provided by script.

See also

QQmlScriptString

Definition at line 100 of file qqmlexpression.cpp.

References d, QSharedDataPointer< T >::data(), engine(), QQmlContextData::get(), QQmlEnginePrivate::get(), QQmlBinding::Invalid, QQmlContext::isValid(), and scopeObject().

Here is the call graph for this function:

~QQmlExpression()

QQmlExpression::~QQmlExpression ( )

override

Destroy the QQmlExpression instance.

Definition at line 174 of file qqmlexpression.cpp.

Member Function Documentation

clearError()

void QQmlExpression::clearError

(

)

Clear any expression errors.

Calls to hasError() following this will return false.

See also

hasError(), error()

Definition at line 381 of file qqmlexpression.cpp.

References d.

columnNumber()

int QQmlExpression::columnNumber

(

)

const

Returns the source file column number for this expression.

The source location must have been previously set by calling setSourceLocation().

Definition at line 333 of file qqmlexpression.cpp.

References d, and qmlConvertSourceCoordinate< quint16, int >().

Here is the call graph for this function:

context()

QQmlContext * QQmlExpression::context

(

)

const

Returns the QQmlContext this expression is associated with, or \nullptr if there is no association or the QQmlContext has been destroyed.

Definition at line 192 of file qqmlexpression.cpp.

References d.

engine()

QQmlEngine * QQmlExpression::engine

(

)

const

Returns the QQmlEngine this expression is associated with, or \nullptr if there is no association or the QQmlEngine has been destroyed.

Definition at line 182 of file qqmlexpression.cpp.

References d.

Referenced by QQmlExpression(), and error().

Here is the caller graph for this function:

error()

QQmlError QQmlExpression::error

(

)

const

Return any error from the last call to evaluate().

If there was no error, this returns an invalid QQmlError instance.

See also

hasError(), clearError()

Definition at line 394 of file qqmlexpression.cpp.

References d, and engine().

Referenced by QQuickScriptActionPrivate::execute(), and QQuickStateChangeScript::execute().

Here is the call graph for this function:

Here is the caller graph for this function:

evaluate()

QVariant QQmlExpression::evaluate

(

bool *

valueIsUndefined = nullptr

)

Evaulates the expression, returning the result of the evaluation, or an invalid QVariant if the expression is invalid or has an error.

valueIsUndefined is set to true if the expression resulted in an undefined value.

See also

hasError(), error()

Definition at line 271 of file qqmlexpression.cpp.

References d.

Referenced by QQuickScriptActionPrivate::execute(), QQuickStateChangeScript::execute(), QQuickVisualTestUtils::findItem(), and QQmlWatchProxy::notifyValueChanged().

Here is the caller graph for this function:

expression()

QString QQmlExpression::expression

(

)

const

Returns the expression string.

Definition at line 201 of file qqmlexpression.cpp.

References d.

Referenced by QQmlExpression(), QQuickScriptActionPrivate::debugAction(), and setExpression().

Here is the caller graph for this function:

hasError()

bool QQmlExpression::hasError

(

)

const

Returns true if the last call to evaluate() resulted in an error, otherwise false.

See also

error(), clearError()

Definition at line 369 of file qqmlexpression.cpp.

References d.

Referenced by QQuickScriptActionPrivate::execute(), and QQuickStateChangeScript::execute().

Here is the caller graph for this function:

lineNumber()

int QQmlExpression::lineNumber

(

)

const

Returns the source file line number for this expression.

The source location must have been previously set by calling setSourceLocation().

Definition at line 323 of file qqmlexpression.cpp.

References d, and qmlConvertSourceCoordinate< quint16, int >().

Here is the call graph for this function:

notifyOnValueChanged()

bool QQmlExpression::notifyOnValueChanged

(

)

const

Returns true if the valueChanged() signal is emitted when the expression's evaluated value changes.

Definition at line 281 of file qqmlexpression.cpp.

References d.

scopeObject()

QObject * QQmlExpression::scopeObject

(

)

const

Returns the expression's scope object, if provided, otherwise 0.

In addition to data provided by the expression's QQmlContext, the scope object's properties are also in scope during the expression's evaluation.

Definition at line 357 of file qqmlexpression.cpp.

References d.

Referenced by QQmlExpression().

Here is the caller graph for this function:

setExpression()

void QQmlExpression::setExpression

(

const QString &

expression

)

Set the expression to expression.

Definition at line 210 of file qqmlexpression.cpp.

References d, and expression().

Here is the call graph for this function:

setNotifyOnValueChanged()

void QQmlExpression::setNotifyOnValueChanged

(

bool

notifyOnChange

)

Sets whether the valueChanged() signal is emitted when the expression's evaluated value changes.

If notifyOnChange is true, the QQmlExpression will monitor properties involved in the expression's evaluation, and emit QQmlExpression::valueChanged() if they have changed. This allows an application to ensure that any value associated with the result of the expression remains up to date.

If notifyOnChange is false (default), the QQmlExpression will not montitor properties involved in the expression's evaluation, and QQmlExpression::valueChanged() will never be emitted. This is more efficient if an application wants a "one off" evaluation of the expression.

Definition at line 303 of file qqmlexpression.cpp.

References d.

setSourceLocation()

void QQmlExpression::setSourceLocation	(	const QString &	url,
		int	line,
		int	column = 0 )

Set the location of this expression to line and column of url.

This information is used by the script engine.

Definition at line 343 of file qqmlexpression.cpp.

References d, line, qmlConvertSourceCoordinate< int, quint16 >(), and url.

Here is the call graph for this function:

sourceFile()

QString QQmlExpression::sourceFile

(

)

const

Returns the source file URL for this expression.

The source location must have been previously set by calling setSourceLocation().

Definition at line 313 of file qqmlexpression.cpp.

References d.

valueChanged

void QQmlExpression::valueChanged ( )

signal

Emitted each time the expression value changes from the last time it was evaluated.

The expression must have been evaluated at least once (by calling QQmlExpression::evaluate()) before this signal will be emitted.

Referenced by QQmlWatchProxy::QQmlWatchProxy().

Here is the caller graph for this function:

Friends And Related Symbol Documentation

QQmlContext

friend class QQmlContext

friend

Definition at line 61 of file qqmlexpression.h.

QQmlDebugger

friend class QQmlDebugger

friend

Definition at line 60 of file qqmlexpression.h.

---

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

• qtdeclarative/src/qml/qml/qqmlexpression.h (f6f5c683b37dc629b9ade6fffd34d0bc08e5e4ef)
• qtdeclarative/src/qml/qml/qqmlexpression.cpp (2f757945b3079f723d2983853bababf086439fbf)