Contents

• Public Types
• Public Functions
• Related Non-Members
• Detailed Description

Detailed Description

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

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

For the object-based types (including Date and RegExp), use the newT() functions inQScriptEngine (e.g.QScriptEngine::newObject()) to create aQScriptValue of the desired type. For the primitive types, use one of theQScriptValue 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 aQScriptValue to another type. You can also use the genericqscriptvalue_cast() function.

Object values have zero or more properties which are themselves QScriptValues. UsesetProperty() to set a property of an object, and callproperty() 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 tosetProperty(). The attributes of a property can be queried by calling thepropertyFlags() 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 theQScriptValueIterator class.

Object values have an internalprototype property, which can be accessed withprototype() andsetPrototype(). 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) theproperty() function will automatically attempt to look up look the property in theprototype() (and in the prototype of theprototype(), and so on), if the object itself does not have the requested property. Note that this prototype-based lookup is not performed bysetProperty();setProperty() will always create the property in the script object itself. For more information, see theQtScript documentation.

Function objects (objects for whichisFunction() returns true) can be invoked by callingcall(). Constructor functions can be used to construct new objects by callingconstruct().

Useequals(),strictlyEquals() andlessThan() to compare aQScriptValue to another.

Object values can have custom data associated with them; see thesetData() anddata() 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 (seeQScriptClass) to store a C++ type that contains the "native" object data.

Note that aQScriptValue for whichisObject() is true only carries a reference to an actual object; copying theQScriptValue 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 afor-in statement in script code, orQScriptValueIterator in C++.

Member Type Documentation

enum QScriptValue::PropertyFlag
flags QScriptValue::PropertyFlags

This enum describes the attributes of a property.

This flag is used to indicate that an existing property is aQObject member (a property or method).

Flags in this range are not used by Qt Script, and can be used for custom purposes.

The PropertyFlags type is a typedef forQFlags<PropertyFlag>. It stores an OR combination of PropertyFlag values.

enum QScriptValue::ResolveFlag
flags QScriptValue::ResolveFlags

This enum specifies how to look up a property of an object.

Check the object's own properties first, then search the scope chain.

Check the object's own properties first, then search the prototype chain, and finally search the scope chain.

The ResolveFlags type is a typedef forQFlags<ResolveFlag>. It stores an OR combination of ResolveFlag values.

enum QScriptValue::SpecialValue

This enum is used to specify a single-valued type.

Member Function Documentation

QScriptValue::QScriptValue()

Constructs an invalidQScriptValue.

QScriptValue::QScriptValue(constQScriptValue & other)

Constructs a newQScriptValue that is a copy ofother.

Note that ifother is an object (i.e.,isObject() would return true), then only a reference to the underlying object is copied into the new script value (i.e., the object itself is not copied).

QScriptValue::QScriptValue(SpecialValue value)

Constructs a newQScriptValue with a specialvalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(bool value)

Constructs a newQScriptValue with a booleanvalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(int value)

Constructs a newQScriptValue with a numbervalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(uint value)

Constructs a newQScriptValue with a numbervalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(qsreal value)

Constructs a newQScriptValue with a numbervalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(constQString & value)

Constructs a newQScriptValue with a stringvalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(constQLatin1String & value)

Constructs a newQScriptValue with a stringvalue.

This function was introduced in Qt 4.5.

QScriptValue::QScriptValue(constchar * value)

Constructs a newQScriptValue with a stringvalue.

This function was introduced in Qt 4.5.

QScriptValue::~QScriptValue()

Destroys thisQScriptValue.

QScriptValue QScriptValue::call(constQScriptValue & thisObject = QScriptValue(), constQScriptValueList & args = QScriptValueList())

Calls thisQScriptValue as a function, usingthisObject as the `this' object in the function call, and passingargs as arguments to the function. Returns the value returned from the function.

If thisQScriptValue is not a function, call() does nothing and returns an invalidQScriptValue.

Note that ifthisObject is not an object, the global object (seeQScriptEngine::globalObject()) will be used as the `this' object.

Calling call() can cause an exception to occur in the script engine; in that case, call() returns the value that was thrown (typically anError object). You can callQScriptEngine::hasUncaughtException() to determine if an exception occurred.

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

See alsoconstruct().

QScriptValue QScriptValue::call(constQScriptValue & thisObject, constQScriptValue & arguments)

Calls thisQScriptValue as a function, usingthisObject as the `this' object in the function call, and passingarguments as arguments to the function. Returns the value returned from the function.

If thisQScriptValue is not a function,call() does nothing and returns an invalidQScriptValue.

arguments can be an arguments object, an array, null or undefined; any other type will cause a TypeError to be thrown.

Note that ifthisObject is not an object, the global object (seeQScriptEngine::globalObject()) will be used as the `this' object.

One common usage of this function is to forward native function calls to another function:

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

See alsoconstruct() andQScriptContext::argumentsObject().

QScriptValue QScriptValue::construct(constQScriptValueList & args = QScriptValueList())

Creates a newObject and calls thisQScriptValue as a constructor, using the created object as the `this' object and passingargs as arguments. If the return value from the constructor call is an object, then that object is returned; otherwise the default constructed object is returned.

If thisQScriptValue is not a function, construct() does nothing and returns an invalidQScriptValue.

Calling construct() can cause an exception to occur in the script engine; in that case, construct() returns the value that was thrown (typically anError object). You can callQScriptEngine::hasUncaughtException() to determine if an exception occurred.

See alsocall() andQScriptEngine::newObject().

QScriptValue QScriptValue::construct(constQScriptValue & arguments)

Creates a newObject and calls thisQScriptValue as a constructor, using the created object as the `this' object and passingarguments as arguments. If the return value from the constructor call is an object, then that object is returned; otherwise the default constructed object is returned.

If thisQScriptValue is not a function,construct() does nothing and returns an invalidQScriptValue.

arguments can be an arguments object, an array, null or undefined. Any other type will cause a TypeError to be thrown.

See alsocall(),QScriptEngine::newObject(), andQScriptContext::argumentsObject().

QScriptValue QScriptValue::data() const

Returns the internal data of thisQScriptValue object.QtScript uses this property to store the primitive value of Date, String, Number and Boolean objects. For other types of object, custom data may be stored usingsetData().

This function was introduced in Qt 4.4.

See alsosetData().

QScriptEngine * QScriptValue::engine() const

Returns theQScriptEngine that created thisQScriptValue, or 0 if thisQScriptValue is invalid or the value is not associated with a particular engine.

bool QScriptValue::equals(constQScriptValue & other) const

Returns true if thisQScriptValue is equal toother, otherwise returns false. The comparison follows the behavior described inECMA-262 section 11.9.3, "The Abstract Equality Comparison Algorithm".

This function can return true even if the type of thisQScriptValue is different from the type of theother value; i.e. the comparison is not strict. For example, comparing the number 9 to the string "9" returns true; comparing an undefined value to a null value returns true; comparing aNumber object whose primitive value is 6 to aString object whose primitive value is "6" returns true; and comparing the number 1 to the boolean valuetrue returns true. If you want to perform a comparison without such implicit value conversion, usestrictlyEquals().

Note that if thisQScriptValue or theother value are objects, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsostrictlyEquals() andlessThan().

bool QScriptValue::instanceOf(constQScriptValue & other) const

Returns true if thisQScriptValue is an instance ofother; otherwise returns false.

ThisQScriptValue is considered to be an instance ofother ifother is a function and the value of theprototype property ofother is in the prototype chain of thisQScriptValue.

bool QScriptValue::isArray() const

Returns true if thisQScriptValue is an object of the Array class; otherwise returns false.

See alsoQScriptEngine::newArray().

bool QScriptValue::isBool() const

Returns true if thisQScriptValue is of the primitive type Boolean; otherwise returns false.

This function was introduced in Qt 4.5.

See alsotoBool().

bool QScriptValue::isDate() const

Returns true if thisQScriptValue is an object of the Date class; otherwise returns false.

See alsoQScriptEngine::newDate().

bool QScriptValue::isError() const

Returns true if thisQScriptValue is an object of the Error class; otherwise returns false.

See alsoQScriptContext::throwError().

bool QScriptValue::isFunction() const

Returns true if thisQScriptValue is a function; otherwise returns false.

See alsocall().

bool QScriptValue::isNull() const

Returns true if thisQScriptValue is of the primitive type Null; otherwise returns false.

See alsoQScriptEngine::nullValue().

bool QScriptValue::isNumber() const

Returns true if thisQScriptValue is of the primitive type Number; otherwise returns false.

See alsotoNumber().

bool QScriptValue::isObject() const

Returns true if thisQScriptValue is of the Object type; otherwise returns false.

Note that function values, variant values, andQObject values are objects, so this function returns true for such values.

See alsotoObject() andQScriptEngine::newObject().

bool QScriptValue::isQMetaObject() const

Returns true if thisQScriptValue is aQMetaObject; otherwise returns false.

See alsotoQMetaObject() andQScriptEngine::newQMetaObject().

bool QScriptValue::isQObject() const

Returns true if thisQScriptValue is aQObject; otherwise returns false.

Note: This function returns true even if theQObject that thisQScriptValue wraps has been deleted.

See alsotoQObject() andQScriptEngine::newQObject().

bool QScriptValue::isRegExp() const

Returns true if thisQScriptValue is an object of the RegExp class; otherwise returns false.

See alsoQScriptEngine::newRegExp().

bool QScriptValue::isString() const

Returns true if thisQScriptValue is of the primitive type String; otherwise returns false.

See alsotoString().

bool QScriptValue::isUndefined() const

Returns true if thisQScriptValue is of the primitive type Undefined; otherwise returns false.

See alsoQScriptEngine::undefinedValue().

bool QScriptValue::isValid() const

Returns true if thisQScriptValue is valid; otherwise returns false.

bool QScriptValue::isVariant() const

Returns true if thisQScriptValue is a variant value; otherwise returns false.

See alsotoVariant() andQScriptEngine::newVariant().

bool QScriptValue::lessThan(constQScriptValue & other) const

Returns true if thisQScriptValue is less thanother, otherwise returns false. The comparison follows the behavior described inECMA-262 section 11.8.5, "The Abstract Relational Comparison Algorithm".

Note that if thisQScriptValue or theother value are objects, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsoequals().

QScriptValue QScriptValue::property(constQString & name, constResolveFlags & mode = ResolvePrototype) const

Returns the value of thisQScriptValue's property with the givenname, using the givenmode to resolve the property.

If no such property exists, an invalidQScriptValue is returned.

If the property is implemented using a getter function (i.e. has thePropertyGetter flag set), calling property() has side-effects on the script engine, since the getter function will be called (possibly resulting in an uncaught script exception). If an exception occurred, property() returns the value that was thrown (typically anError object).

See alsosetProperty(),propertyFlags(), andQScriptValueIterator.

QScriptValue QScriptValue::property(constQScriptString & name, constResolveFlags & mode = ResolvePrototype) const

Returns the value of thisQScriptValue's property with the givenname, using the givenmode to resolve the property.

This overload ofproperty() is useful when you need to look up the same property repeatedly, since the lookup can be performed faster when the name is represented as an interned string.

This function was introduced in Qt 4.4.

See alsoQScriptEngine::toStringHandle() andsetProperty().

QScriptValue QScriptValue::property(quint32 arrayIndex, constResolveFlags & mode = ResolvePrototype) const

This is an overloaded function.

Returns the property at the givenarrayIndex, using the givenmode to resolve the property.

This function is provided for convenience and performance when working with array objects.

If thisQScriptValue is not an Array object, this function behaves as ifproperty() was called with the string representation ofarrayIndex.

QScriptValue::PropertyFlags QScriptValue::propertyFlags(constQString & name, constResolveFlags & mode = ResolvePrototype) const

Returns the flags of the property with the givenname, using the givenmode to resolve the property.

See alsoproperty().

QScriptValue::PropertyFlags QScriptValue::propertyFlags(constQScriptString & name, constResolveFlags & mode = ResolvePrototype) const

Returns the flags of the property with the givenname, using the givenmode to resolve the property.

This function was introduced in Qt 4.4.

See alsoproperty().

QScriptValue QScriptValue::prototype() const

If thisQScriptValue is an object, returns the internal prototype (__proto__ property) of this object; otherwise returns an invalidQScriptValue.

See alsosetPrototype() andisObject().

QScriptClass * QScriptValue::scriptClass() const

Returns the custom script class that this script object is an instance of, or 0 if the object is not of a custom class.

This function was introduced in Qt 4.4.

See alsosetScriptClass().

void QScriptValue::setData(constQScriptValue & data)

Sets the internaldata of thisQScriptValue object. You can use this function to set object-specific data that won't be directly accessible to scripts, but may be retrieved in C++ using thedata() function.

This function was introduced in Qt 4.4.

See alsodata() andQScriptEngine::reportAdditionalMemoryCost().

void QScriptValue::setProperty(constQString & name, constQScriptValue & value, constPropertyFlags & flags = KeepExistingFlags)

Sets the value of thisQScriptValue's property with the givenname to the givenvalue.

If thisQScriptValue is not an object, this function does nothing.

If thisQScriptValue does not already have a property with namename, a new property is created; the givenflags then specify how this property may be accessed by script code.

Ifvalue is invalid, the property is removed.

If the property is implemented using a setter function (i.e. has thePropertySetter flag set), calling setProperty() has side-effects on the script engine, since the setter function will be called with the givenvalue as argument (possibly resulting in an uncaught script exception).

Note that you cannot specify custom getter or setter functions for built-in properties, such as thelength property of Array objects or meta properties ofQObject objects.

See alsoproperty().

void QScriptValue::setProperty(constQScriptString & name, constQScriptValue & value, constPropertyFlags & flags = KeepExistingFlags)

Sets the value of thisQScriptValue's property with the givenname to the givenvalue. The givenflags specify how this property may be accessed by script code.

This overload ofsetProperty() is useful when you need to set the same property repeatedly, since the operation can be performed faster when the name is represented as an interned string.

This function was introduced in Qt 4.4.

See alsoQScriptEngine::toStringHandle().

void QScriptValue::setProperty(quint32 arrayIndex, constQScriptValue & value, constPropertyFlags & flags = KeepExistingFlags)

This is an overloaded function.

Sets the property at the givenarrayIndex to the givenvalue.

This function is provided for convenience and performance when working with array objects.

If thisQScriptValue is not an Array object, this function behaves as ifsetProperty() was called with the string representation ofarrayIndex.

void QScriptValue::setPrototype(constQScriptValue & prototype)

If thisQScriptValue is an object, sets the internal prototype (__proto__ property) of this object to beprototype; otherwise does nothing.

The internal prototype should not be confused with the public property with name "prototype"; the public prototype is usually only set on functions that act as constructors.

See alsoprototype() andisObject().

void QScriptValue::setScriptClass(QScriptClass * scriptClass)

Sets the custom script class of this script object toscriptClass. This can be used to "promote" a plain script object (e.g. created by the "new" operator in a script, or byQScriptEngine::newObject() in C++) to an object of a custom type.

IfscriptClass is 0, the object will be demoted to a plain script object.

This function was introduced in Qt 4.4.

See alsoscriptClass() andsetData().

bool QScriptValue::strictlyEquals(constQScriptValue & other) const

Returns true if thisQScriptValue is equal toother using strict comparison (no conversion), otherwise returns false. The comparison follows the behavior described inECMA-262 section 11.9.6, "The Strict Equality Comparison Algorithm".

If the type of thisQScriptValue is different from the type of theother value, this function returns false. If the types are equal, the result depends on the type, as shown in the following table:

See alsoequals().

bool QScriptValue::toBool() const

Returns the boolean value of thisQScriptValue, using the conversion rules described inECMA-262 section 9.2, "ToBoolean".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

This function was introduced in Qt 4.5.

See alsoisBool().

QDateTime QScriptValue::toDateTime() const

Returns aQDateTime representation of this value, in local time. If thisQScriptValue is not a date, or the value of the date is NaN (Not-a-Number), an invalidQDateTime is returned.

See alsoisDate().

qint32 QScriptValue::toInt32() const

Returns the signed 32-bit integer value of thisQScriptValue, using the conversion rules described inECMA-262 section 9.5, "ToInt32".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsotoNumber() andtoUInt32().

qsreal QScriptValue::toInteger() const

Returns the integer value of thisQScriptValue, using the conversion rules described inECMA-262 section 9.4, "ToInteger".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsotoNumber().

qsreal QScriptValue::toNumber() const

Returns the number value of thisQScriptValue, as defined inECMA-262 section 9.3, "ToNumber".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsoisNumber(),toInteger(),toInt32(),toUInt32(), andtoUInt16().

constQMetaObject * QScriptValue::toQMetaObject() const

If thisQScriptValue is aQMetaObject, returns theQMetaObject pointer that theQScriptValue represents; otherwise, returns 0.

See alsoisQMetaObject().

QObject * QScriptValue::toQObject() const

If thisQScriptValue is aQObject, returns theQObject pointer that theQScriptValue represents; otherwise, returns 0.

If theQObject that thisQScriptValue wraps has been deleted, this function returns 0 (i.e. it is possible for toQObject() to return 0 even whenisQObject() returns true).

See alsoisQObject().

QRegExp QScriptValue::toRegExp() const

Returns theQRegExp representation of this value. If thisQScriptValue is not a regular expression, an emptyQRegExp is returned.

See alsoisRegExp().

QString QScriptValue::toString() const

Returns the string value of thisQScriptValue, as defined inECMA-262 section 9.8, "ToString".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's toString() function (and possibly valueOf()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsoisString().

quint16 QScriptValue::toUInt16() const

Returns the unsigned 16-bit integer value of thisQScriptValue, using the conversion rules described inECMA-262 section 9.7, "ToUint16".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsotoNumber().

quint32 QScriptValue::toUInt32() const

Returns the unsigned 32-bit integer value of thisQScriptValue, using the conversion rules described inECMA-262 section 9.6, "ToUint32".

Note that if thisQScriptValue is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possiblytoString()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

See alsotoNumber() andtoInt32().

QVariant QScriptValue::toVariant() const

Returns theQVariant value of thisQScriptValue, if it can be converted to aQVariant; otherwise returns an invalidQVariant. The conversion is performed according to the following table:

See alsoisVariant().

QScriptValue & QScriptValue::operator=(constQScriptValue & other)

Assigns theother value to thisQScriptValue.

Note that ifother is an object (isObject() returns true), only a reference to the underlying object will be assigned; the object itself will not be copied.

Related Non-Members

Tqscriptvalue_cast(constQScriptValue & value)

Returns the givenvalue converted to the template typeT.

This function was introduced in Qt 4.3.

See alsoqScriptRegisterMetaType() andQScriptEngine::toScriptValue().