QJSValue Class

Detailed Description

QJSValue supports the types defined in the ECMA-262 standard: The primitive types, which are Undefined, Null, Boolean, Number, and String; and the Object and Array types. Additionally, built-in support is provided for Qt/C++ types such as QVariant and QObject.

For the object-based types (including Date and RegExp), use the newT() functions in QJSEngine (e.g. QJSEngine::newObject()) to create a QJSValue of the desired type. For the primitive types, use one of the QJSValue constructor overloads. For other types, e.g. registered gadget types such as QPoint, you can use QJSEngine::toScriptValue.

The methods named isT() (e.g. isBool(), isUndefined()) can be used to test if a value is of a certain type. The methods named toT() (e.g. toBool(), toString()) can be used to convert a QJSValue to another type. You can also use the generic qjsvalue_cast() function.

Object values have zero or more properties which are themselves QJSValues. Use setProperty() to set a property of an object, and call property() to retrieve the value of a property.

 QJSEngine myEngine;
 QJSValue myObject = myEngine.newObject();
 QJSValue myOtherObject = myEngine.newObject();
 myObject.setProperty("myChild", myOtherObject);
 myObject.setProperty("name", "John Doe");

If you want to iterate over the properties of a script object, use the QJSValueIterator class.

Object values have an internal prototype property, which can be accessed with prototype() and setPrototype().

Function objects (objects for which isCallable()) returns true) can be invoked by calling call(). Constructor functions can be used to construct new objects by calling callAsConstructor().

Use equals() or strictlyEquals() to compare a QJSValue to another.

Note that a QJSValue for which isObject() is true only carries a reference to an actual object; copying the QJSValue will only copy the object reference, not the object itself. If you want to clone an object (i.e. copy an object's properties to another object), you can do so with the help of a for-in statement in script code, or QJSValueIterator in C++.

Working With Arrays

To create an array using QJSValue, use QJSEngine::newArray():

 // Assumes that this class was declared in QML.
 QJSValue jsArray = engine->newArray(3);

To set individual elements in the array, use the setProperty(quint32 arrayIndex, const QJSValue &value) overload. For example, to fill the array above with integers:

 for (int i = 0; i < 3; ++i) {
     jsArray.setProperty(i, QRandomGenerator::global().generate());
 }

To determine the length of the array, access the "length" property. To access array elements, use the property(quint32 arrayIndex) overload. The following code reads the array we created above back into a list:

 QVector<int> integers;
 const int length = jsArray.property("length").toInt();
 for (int i = 0; i < length; ++i) {
     integers.append(jsArray.property(i).toInt());
 }