QScriptValue Class Reference
[QtScript module]

Detailed Description

The QScriptValue class acts as a container for the Qt Script data types.

QScriptValue supports the types defined in the ECMA-262 standard: The primitive types, which are Undefined, Null, Boolean, Number, and String; and the Object type. Additionally, Qt Script has built-in support for QVariant, QObject and QMetaObject.

For the object-based types (including Date and RegExp), use the newT() functions in QScriptEngine (e.g. QScriptEngine::newObject()) to create a QScriptValue of the desired type. For the primitive types, use one of the QScriptValue constructor overloads.

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 QScriptValue to another type. You can also use the generic qscriptvalue_cast() function.

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

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

Each property can have a set of attributes; these are specified as the third (optional) argument to setProperty(). The attributes of a property can be queried by calling the propertyFlags() function. The following code snippet creates a property that cannot be modified by script code:

 QScriptValue val(&myEngine, 123);
 myObject.setProperty("myReadOnlyProperty", val, QScriptValue::ReadOnly);

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

Object values have an internal prototype property, which can be accessed with prototype() and setPrototype(). Properties added to a prototype are shared by all objects having that prototype; this is referred to as prototype-based inheritance. In practice, it means that (by default) the property() function will automatically attempt to look up look the property in the prototype() (and in the prototype of the prototype(), and so on), if the object itself does not have the requested property. Note that this prototype-based lookup is not performed by setProperty(); setProperty() will always create the property in the script object itself. For more information, see the QtScript documentation.

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

Use equals(), strictlyEquals() and lessThan() to compare a QScriptValue to another.

Object values can have custom data associated with them; see the setData() and data() functions. By default, this data is not accessible to scripts; it can be used to store any data you want to associate with the script object. Typically this is used by custom class objects (see QScriptClass) to store a C++ type that contains the "native" object data.

Note that a QScriptValue for which isObject() is true only carries a reference to an actual object; copying the QScriptValue 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 QScriptValueIterator in C++.

See also QScriptEngine and QScriptValueIterator.

Member Type Documentation

 QScriptEngine engine;
 engine.evaluate("function fullName() { return this.firstName + ' ' + this.lastName; }");
 engine.evaluate("somePerson = { firstName: 'John', lastName: 'Doe' }");

 QScriptValue global = engine.globalObject();
 QScriptValue fullName = global.property("fullName");
 QScriptValue who = global.property("somePerson");
 qDebug() << fullName.call(who).toString(); // "John Doe"

 engine.evaluate("function cube(x) { return x * x * x; }");
 QScriptValue cube = global.property("cube");
 QScriptValueList args;
 args << 3;
 qDebug() << cube.call(QScriptValue(), args).toNumber(); // 27

 QScriptValue myNativeFunction(QScriptContext *ctx, QScriptEngine *)
 {
     QScriptValue otherFunction = ...;
     return otherFunction.call(ctx->thisObject(), ctx->argumentsObject());
 }