QScriptClass

Synopsis

Functions

Virtual functions

Detailed Description

The PySide.QtScript.QScriptClass class provides an interface for defining custom behavior of (a class of) Qt Script objects.

The PySide.QtScript.QScriptClass class defines an interface for handling various aspects of interaction with the Qt Script objects associated with the class. Such objects are created by calling QScriptEngine.newObject() , passing a pointer to the PySide.QtScript.QScriptClass as argument.

By subclassing PySide.QtScript.QScriptClass , 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 than QScriptEngine.newQObject() . For example, you can use PySide.QtScript.QScriptClass to implement array-type objects (i.e. objects that handle the length 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 using QScriptValue.setProperty() to define getter/setter functions for the relevant properties, rather than subclassing PySide.QtScript.QScriptClass .

Reimplement queryProperty() to specify which properties are handled in a custom way by your script class (i.e. should be delegated to the PySide.QtScript.QScriptClass ), and which properties should be handled just like normal Qt Script object properties.

Reimplement PySide.QtScript.QScriptClass.property() and PySide.QtScript.QScriptClass.setProperty() to perform the actual access (read or write) to the properties that your class handles. Additionally, you can reimplement PySide.QtScript.QScriptClass.propertyFlags() to specify custom flags for your properties.

Reimplement PySide.QtScript.QScriptClass.newIterator() 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 the PySide.QtScript.QScriptValueIterator class, or when an object is used in a for-in enumeration statement in a script.

When implementing custom classes of objects, you typically use QScriptValue.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 of PySide.QtScript.QScriptClass.property() and PySide.QtScript.QScriptClass.setProperty() (by calling QScriptValue.data() ) to perform custom processing.

Reimplement PySide.QtScript.QScriptClass.prototype() to provide a custom prototype object for your script class.

Reimplement PySide.QtScript.QScriptClass.supportsExtension() and PySide.QtScript.QScriptClass.extension() if your custom script class supports one or more of the extensions specified by the Extension enum.

class PySide.QtScript.QScriptClass(engine)
Parameters:enginePySide.QtScript.QScriptEngine

Constructs a PySide.QtScript.QScriptClass object to be used in the given engine .

The engine does not take ownership of the PySide.QtScript.QScriptClass object.

PySide.QtScript.QScriptClass.QueryFlag

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

Constant Description
QScriptClass.HandlesReadAccess The PySide.QtScript.QScriptClass handles read access to this property.
QScriptClass.HandlesWriteAccess The PySide.QtScript.QScriptClass handles write access to this property.

See also

queryProperty()

PySide.QtScript.QScriptClass.Extension

This enum specifies the possible extensions to a PySide.QtScript.QScriptClass .

Constant Description
QScriptClass.Callable Instances of this class can be called as functions.
QScriptClass.HasInstance Instances of this class implement [[ HasInstance ]].
PySide.QtScript.QScriptClass.engine()
Return type:PySide.QtScript.QScriptEngine

Returns the engine that this PySide.QtScript.QScriptClass is associated with.

PySide.QtScript.QScriptClass.extension(extension[, argument=None])
Parameters:
Return type:

object

This virtual function can be reimplemented in a PySide.QtScript.QScriptClass subclass to provide support for extensions. The optional argument can be provided as input to the extension ; the result must be returned in the form of a PySide.QtCore.QVariant . You can call PySide.QtScript.QScriptClass.supportsExtension() to check if an extension is supported by the PySide.QtScript.QScriptClass . By default, no extensions are supported, and this function returns an invalid PySide.QtCore.QVariant .

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 using QScriptValue.call() ). The argument will contain a pointer to the PySide.QtScript.QScriptContext that represents the function call, and you should return a PySide.QtCore.QVariant 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:
    context = argument
    engine = context.engine()
    sum = 0
    for i in range(0, context.argumentCount()):
        sum += context.argument(i).toNumber()
    return sum

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

PySide.QtScript.QScriptClass.name()
Return type:unicode

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.

PySide.QtScript.QScriptClass.newIterator(object)
Parameters:objectPySide.QtScript.QScriptValue
Return type:PySide.QtScript.QScriptClassPropertyIterator

Returns an iterator for traversing custom properties of the given object .

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 by queryProperty() ) 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.

PySide.QtScript.QScriptClass.property(object, name, id)
Parameters:
Return type:

PySide.QtScript.QScriptValue

Returns the value of the property with the given name of the given object .

The id argument is only useful if you assigned a value to it in queryProperty() .

The default implementation does nothing and returns an invalid PySide.QtScript.QScriptValue .

PySide.QtScript.QScriptClass.propertyFlags(object, name, id)
Parameters:
Return type:

PySide.QtScript.QScriptValue.PropertyFlags

Returns the flags of the property with the given name of the given object .

The id argument is only useful if you assigned a value to it in queryProperty() .

The default implementation returns 0.

PySide.QtScript.QScriptClass.prototype()
Return type:PySide.QtScript.QScriptValue

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

The default implementation returns an invalid PySide.QtScript.QScriptValue , 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 the QtScript documentation for more information on how prototypes are used.

PySide.QtScript.QScriptClass.setProperty(object, name, id, value)
Parameters:

Sets the property with the given name of the given object to the given value .

The id argument is only useful if you assigned a value to it in queryProperty() .

The default implementation does nothing.

An invalid value represents a request to remove the property.

PySide.QtScript.QScriptClass.supportsExtension(extension)
Parameters:extensionPySide.QtScript.QScriptClass.Extension
Return type:PySide.QtCore.bool

Returns true if the PySide.QtScript.QScriptClass supports the given extension ; otherwise, false is returned. By default, no extensions are supported.

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