QScriptClass Class Reference

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

#include <qscriptclass.h>

Inheritance diagram for QScriptClass:

Public Types
enum	Extension { Callable, HasInstance }
	This enum specifies the possible extensions to a QScriptClass. More...
enum	QueryFlag { HandlesReadAccess = 0x01, HandlesWriteAccess = 0x02 }
	This enum describes flags that are used to query a QScriptClass regarding how access to a property should be handled. More...

Public Functions
QScriptEngine *	engine () const
	Returns the engine that this QScriptClass is associated with. More...
virtual QVariant	extension (Extension extension, const QVariant &argument=QVariant())
	This virtual function can be reimplemented in a QScriptClass subclass to provide support for extensions. More...
virtual QString	name () const
	Returns the name of the script class. More...
virtual QScriptClassPropertyIterator *	newIterator (const QScriptValue &object)
	Returns an iterator for traversing custom properties of the given object. More...
virtual QScriptValue	property (const QScriptValue &object, const QScriptString &name, uint id)
	Returns the value of the property with the given name of the given object. More...
virtual QScriptValue::PropertyFlags	propertyFlags (const QScriptValue &object, const QScriptString &name, uint id)
	Returns the flags of the property with the given name of the given object. More...
virtual QScriptValue	prototype () const
	Returns the object to be used as the prototype of new instances of this class (created with QScriptEngine::newObject()). More...
	QScriptClass (QScriptEngine *engine)
	Constructs a QScriptClass object to be used in the given engine. More...
virtual QueryFlags	queryProperty (const QScriptValue &object, const QScriptString &name, QueryFlags flags, uint *id)
	Queries this script class for how access to the property with the given name of the given object should be handled. More...
virtual void	setProperty (QScriptValue &object, const QScriptString &name, uint id, const QScriptValue &value)
	Sets the property with the given name of the given object to the given value. More...
virtual bool	supportsExtension (Extension extension) const
	Returns true if the QScriptClass supports the given extension; otherwise, false is returned. More...
virtual	~QScriptClass ()
	Destroys the QScriptClass object. More...

Protected Functions
	QScriptClass (QScriptEngine *engine, QScriptClassPrivate &dd)

Protected Variables
QScopedPointer< QScriptClassPrivate >	d_ptr

Detailed Description

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

Since

4.4

The 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 QScriptClass as argument.

By subclassing 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 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 QScriptClass.

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

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

Reimplement 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 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 property() and setProperty() (by calling QScriptValue::data()) to perform custom processing.

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

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

See also

QScriptClassPropertyIterator, QScriptEngine::newObject(), {Custom Script Class Example}

Definition at line 43 of file qscriptclass.h.

Enumerations

Extension

enum QScriptClass::Extension

This enum specifies the possible extensions to a QScriptClass.

• Callable Instances of this class can be called as functions.

• HasInstance Instances of this class implement [[HasInstance]].

See also

extension()

Enumerator
Callable
HasInstance

Definition at line 52 of file qscriptclass.h.

                   {
        Callable,
        HasInstance
    };

QueryFlag

enum QScriptClass::QueryFlag

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

• HandlesReadAccess The QScriptClass handles read access to this property.
• HandlesWriteAccess The QScriptClass handles write access to this property.

See also

queryProperty()

Enumerator
HandlesReadAccess
HandlesWriteAccess

Definition at line 46 of file qscriptclass.h.

                   {
        HandlesReadAccess = 0x01,
        HandlesWriteAccess = 0x02
    };

Constructors and Destructors

QScriptClass() [1/2]

QScriptClass::QScriptClass

(

QScriptEngine *

engine

)

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

The engine does not take ownership of the QScriptClass object.

Definition at line 142 of file qscriptclass.cpp.

    : d_ptr(new QScriptClassPrivate)
{
    d_ptr->q_ptr = this;
    d_ptr->engine = engine;
}

~QScriptClass()

QScriptClass::~QScriptClass ( )

virtual

Destroys the QScriptClass object.

If a QScriptClass object is deleted before the associated engine(), any Qt Script objects using the QScriptClass will be "demoted" to normal Qt Script objects.

Definition at line 166 of file qscriptclass.cpp.

{
}

QScriptClass() [2/2]

QScriptClass::QScriptClass ( QScriptEngine *  engine, QScriptClassPrivate &  dd  )

protected

Warning

This function is not part of the public interface.

Definition at line 152 of file qscriptclass.cpp.

    : d_ptr(&dd)
{
    d_ptr->q_ptr = this;
    d_ptr->engine = engine;
}

Functions

engine()

QScriptEngine * QScriptClass::engine

(

)

const

Returns the engine that this QScriptClass is associated with.

Definition at line 173 of file qscriptclass.cpp.

Referenced by QDeclarativeGlobalScriptClass::explicitSetProperty(), QDeclarativeSqlQueryScriptClass::property(), qmlsqldatabase_change_version(), qmlsqldatabase_databasesPath(), qmlsqldatabase_executeSql(), QScriptClass(), and QDeclarativeGlobalScriptClass::setProperty().

{
    Q_D(const QScriptClass);
    return d->engine;
}

extension()

QVariant QScriptClass::extension ( Extension  extension, const QVariant &  argument = QVariant()  )

virtual

This virtual function can be reimplemented in a 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 QVariant. You can call supportsExtension() to check if an extension is supported by the QScriptClass. By default, no extensions are supported, and this function returns an invalid 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 QScriptContext that represents the function call, and you should return a 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) {
    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 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. extension() should return true if the value delegates behavior to the object, false otherwise.

See also

supportsExtension()

Definition at line 381 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::call(), QScript::ClassObjectDelegate::construct(), and QScript::ClassObjectDelegate::hasInstance().

{
    Q_UNUSED(extension);
    Q_UNUSED(argument);
    return QVariant();
}

name()

QString QScriptClass::name ( ) const

virtual

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.

Definition at line 207 of file qscriptclass.cpp.

Referenced by QDeclarativeGlobalScriptClass::explicitSetProperty(), and QDeclarativeGlobalScriptClass::QDeclarativeGlobalScriptClass().

{
    return QString();
}

newIterator()

QScriptClassPropertyIterator * QScriptClass::newIterator ( const QScriptValue &  object )

virtual

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.

See also

QScriptValueIterator

Definition at line 330 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::getOwnPropertyNames().

{
    Q_UNUSED(object);
    return 0;
}

property()

QScriptValue QScriptClass::property ( const QScriptValue &  object, const QScriptString &  name, uint  id  )

virtual

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 QScriptValue.

See also

setProperty(), propertyFlags()

Reimplemented in NodeListClass, NamedNodeMapClass, and QDeclarativeSqlQueryScriptClass.

Definition at line 263 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::getOwnPropertyDescriptor(), and QScript::ClassObjectDelegate::getOwnPropertySlot().

{
    Q_UNUSED(object);
    Q_UNUSED(name);
    Q_UNUSED(id);
    return QScriptValue();
}

propertyFlags()

QScriptValue::PropertyFlags QScriptClass::propertyFlags ( const QScriptValue &  object, const QScriptString &  name, uint  id  )

virtual

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.

See also

property()

Reimplemented in QDeclarativeSqlQueryScriptClass.

Definition at line 283 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::deleteProperty(), and QScript::ClassObjectDelegate::getOwnPropertyDescriptor().

{
    Q_UNUSED(object);
    Q_UNUSED(name);
    Q_UNUSED(id);
    return 0;
}

prototype()

QScriptValue QScriptClass::prototype ( ) const

virtual

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 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.

Definition at line 194 of file qscriptclass.cpp.

Referenced by QScriptEngine::newObject().

{
    return QScriptValue();
}

queryProperty()

QScriptClass::QueryFlags QScriptClass::queryProperty ( const QScriptValue &  object, const QScriptString &  name, QueryFlags  flags, uint *  id  )

virtual

Queries this script class for how access to the property with the given name of the given object should be handled.

The given flags specify the aspects of interest. This function should return a subset of flags to indicate which aspects of property access should be further handled by the script class.

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

You can optionally use the id argument to store a value that will subsequently be passed on to functions such as property() and setProperty().

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 property foo, but not write access; if foo is then assigned a value, it will become a normal script object property, and subsequently you will no longer be queried regarding read access to foo.

See also

property()

Reimplemented in NodeListClass, NamedNodeMapClass, QDeclarativeSqlQueryScriptClass, and QDeclarativeGlobalScriptClass.

Definition at line 241 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::deleteProperty(), QScript::ClassObjectDelegate::getOwnPropertyDescriptor(), QScript::ClassObjectDelegate::getOwnPropertySlot(), and QScript::ClassObjectDelegate::put().

{
    Q_UNUSED(object);
    Q_UNUSED(name);
    Q_UNUSED(flags);
    Q_UNUSED(id);
    return 0;
}

setProperty()

void QScriptClass::setProperty ( QScriptValue &  object, const QScriptString &  name, uint  id, const QScriptValue &  value  )

virtual

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.

See also

property()

Reimplemented in QDeclarativeSqlQueryScriptClass, and QDeclarativeGlobalScriptClass.

Definition at line 305 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::deleteProperty(), and QScript::ClassObjectDelegate::put().

{
    Q_UNUSED(object);
    Q_UNUSED(name);
    Q_UNUSED(id);
    Q_UNUSED(value);
}

supportsExtension()

bool QScriptClass::supportsExtension ( Extension  extension ) const

virtual

Returns true if the 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.

See also

extension()

Definition at line 346 of file qscriptclass.cpp.

Referenced by QScript::ClassObjectDelegate::getCallData(), and QScript::ClassObjectDelegate::getConstructData().

{
    Q_UNUSED(extension);
    return false;
}

Properties

d_ptr

QScopedPointer<QScriptClassPrivate> QScriptClass::d_ptr

protected

Definition at line 87 of file qscriptclass.h.

Referenced by QScriptClass().

---

The documentation for this class was generated from the following files:

• /src/script/api/qscriptclass.h
• /src/script/api/qscriptclass.cpp