Contents

• Public Types
• Public Functions
• Detailed Description

Detailed Description

TheQScriptClass class provides an interface for defining custom behavior of (a class of) Qt Script objects.

TheQScriptClass class defines an interface for handling various aspects of interaction with the Qt Script objects associated with the class. Such objects are created by callingQScriptEngine::newObject(), passing a pointer to theQScriptClass as argument.

By subclassingQScriptClass, you can define precisely how access to properties of the objects that use your class is handled. This enables a fully dynamic handling of properties, e.g. it's more powerful thanQScriptEngine::newQObject(). For example, you can useQScriptClass to implement array-type objects (i.e. objects that handle thelength property, and properties whose names are valid array indexes, in a special way), or to implement a "live" (runtime-defined) proxy to an underlying object.

If you just need to handle access to a set of properties that are known at the time an object is created (i.e. "semi-statically"), you might consider usingQScriptValue::setProperty() to define getter/setter functions for the relevant properties, rather than subclassingQScriptClass.

ReimplementqueryProperty() to specify which properties are handled in a custom way by your script class (i.e. should bedelegated to theQScriptClass), and which properties should be handled just like normal Qt Script object properties.

Reimplementproperty() andsetProperty() to perform the actual access (read or write) to the properties that your class handles. Additionally, you can reimplementpropertyFlags() to specify custom flags for your properties.

ReimplementnewIterator() to provide an iterator for objects of your custom class. This is only necessary if objects of your class can have custom properties that you want to be reported when an object is used together with theQScriptValueIterator class, or when an object is used in a for-in enumeration statement in a script.

When implementing custom classes of objects, you typically useQScriptValue::setData() to store instance-specific data as part of object initialization; the data won't be accessible from scripts directly, but you can access it in e.g. your reimplementations ofproperty() andsetProperty() (by callingQScriptValue::data()) to perform custom processing.

Reimplementprototype() to provide a custom prototype object for your script class.

ReimplementsupportsExtension() andextension() if your custom script class supports one or more of the extensions specified by the Extension enum.

Member Type Documentation

enum QScriptClass::Extension

This enum specifies the possible extensions to aQScriptClass.

See alsoextension().

enum QScriptClass::QueryFlag
flags QScriptClass::QueryFlags

This enum describes flags that are used to query aQScriptClass regarding how access to a property should be handled.

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

See alsoqueryProperty().

Member Function Documentation

QScriptClass::QScriptClass(QScriptEngine * engine)

Constructs aQScriptClass object to be used in the givenengine.

The engine does not take ownership of theQScriptClass object.

[virtual]QScriptClass::~QScriptClass()

Destroys theQScriptClass object.

If aQScriptClass object is deleted before the associatedengine(), any Qt Script objects using theQScriptClass will be "demoted" to normal Qt Script objects.

QScriptEngine * QScriptClass::engine() const

Returns the engine that thisQScriptClass is associated with.

[virtual]QVariant QScriptClass::extension(Extension extension, constQVariant & argument = QVariant())

This virtual function can be reimplemented in aQScriptClass subclass to provide support for extensions. The optionalargument can be provided as input to theextension; the result must be returned in the form of aQVariant. You can callsupportsExtension() to check if an extension is supported by theQScriptClass. By default, no extensions are supported, and this function returns an invalidQVariant.

If you implement the Callable extension, Qt Script will call this function when an instance of your class is called as a function (e.g. from a script or usingQScriptValue::call()). Theargument will contain a pointer to theQScriptContext that represents the function call, and you should return aQVariant that holds the result of the function call. In the following example the sum of the arguments to the script function are added up and returned:

if (extension== Callable) {QScriptContext*context= qvariant_cast<QScriptContext*>(argument);QScriptEngine*engine= context->engine();double sum=0;for (int i=0; i< context->argumentCount();++i)        sum+= context->argument(i).toNumber();return sum;}

If you implement theHasInstance extension, Qt Script will call this function as part of evaluating theinstanceof operator, as described in ECMA-262 Section 11.8.6. Theargument is a QScriptValueList containing two items: The first item is the object thatHasInstance is being applied to (an instance of your class), and the second item can be any value. extension() should return true if the value delegates behavior to the object, false otherwise.

See alsosupportsExtension().

[virtual]QString QScriptClass::name() const

Returns the name of the script class.

Qt Script uses this name to generate a default string representation of objects in case you do not provide a toString function.

The default implementation returns a null string.

[virtual]QScriptClassPropertyIterator * QScriptClass::newIterator(constQScriptValue & object)

Returns an iterator for traversing custom properties of the givenobject.

The default implementation returns 0, meaning that there are no custom properties to traverse.

Reimplement this function if objects of your script class can have one or more custom properties (e.g. those reported to be handled byqueryProperty()) that you want to appear when an object's properties are enumerated (e.g. by a for-in statement in a script).

Qt Script takes ownership of the new iterator object.

See alsoQScriptValueIterator.

[virtual]QScriptValue QScriptClass::property(constQScriptValue & object, constQScriptString & name,uint id)

Returns the value of the property with the givenname of the givenobject.

Theid argument is only useful if you assigned a value to it inqueryProperty().

The default implementation does nothing and returns an invalidQScriptValue.

See alsosetProperty() andpropertyFlags().

[virtual]QScriptValue::PropertyFlags QScriptClass::propertyFlags(constQScriptValue & object, constQScriptString & name,uint id)

Returns the flags of the property with the givenname of the givenobject.

Theid argument is only useful if you assigned a value to it inqueryProperty().

The default implementation returns 0.

See alsoproperty().

[virtual]QScriptValue QScriptClass::prototype() const

Returns the object to be used as the prototype of new instances of this class (created withQScriptEngine::newObject()).

The default implementation returns an invalidQScriptValue, meaning that the standard Object prototype will be used. Reimplement this function to provide your own custom prototype.

Typically you initialize your prototype object in the constructor of your class, then return it in this function.

See the "Making Use of Prototype-Based Inheritance" section in theQtScript documentation for more information on how prototypes are used.

[virtual]QueryFlags QScriptClass::queryProperty(constQScriptValue & object, constQScriptString & name,QueryFlags flags,uint * id)

Queries this script class for how access to the property with the givenname of the givenobject should be handled. The givenflags specify the aspects of interest. This function should return a subset offlags to indicate which aspects of property access should be further handled by the script class.

For example, if theflags containHandlesReadAccess, and you would like your class to handle the reading of the property (through theproperty() function), the returned flags should includeHandlesReadAccess. If the returned flags do not containHandlesReadAccess, the property will be handled as a normal script object property.

You can optionally use theid argument to store a value that will subsequently be passed on to functions such asproperty() andsetProperty().

The default implementation of this function returns 0.

Note: This function is only called if the given property isn't already a normal property of the object. For example, say you advertise that you want to handle read access to propertyfoo, but not write access; iffoo is then assigned a value, it will become a normal script object property, and subsequently you will no longer be queried regarding read access tofoo.

See alsoproperty().

[virtual]void QScriptClass::setProperty(QScriptValue & object, constQScriptString & name,uint id, constQScriptValue & value)

Sets the property with the givenname of the givenobject to the givenvalue.

Theid argument is only useful if you assigned a value to it inqueryProperty().

The default implementation does nothing.

An invalidvalue represents a request to remove the property.

See alsoproperty().

[virtual]bool QScriptClass::supportsExtension(Extension extension) const

Returns true if theQScriptClass supports the givenextension; otherwise, false is returned. By default, no extensions are supported.

Reimplement this function to indicate which extensions your custom class supports.

See alsoextension().