1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtScript module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qscriptclass.h"

    43 #include "qscriptstring.h"

    44 

    45 /*!

    46   \since 4.4

    47   \class QScriptClass

    48 

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

    50 

    51   \ingroup script

    52   \mainclass

    53 

    54   The QScriptClass class defines an interface for handling various

    55   aspects of interaction with the Qt Script objects associated with

    56   the class. Such objects are created by calling

    57   QScriptEngine::newObject(), passing a pointer to the QScriptClass as

    58   argument.

    59 

    60   By subclassing QScriptClass, you can define precisely how access to

    61   properties of the objects that use your class is handled. This

    62   enables a fully dynamic handling of properties, e.g. it's more

    63   powerful than QScriptEngine::newQObject(). For example, you can use

    64   QScriptClass to implement array-type objects (i.e. objects that

    65   handle the \c{length} property, and properties whose names are valid

    66   array indexes, in a special way), or to implement a "live"

    67   (runtime-defined) proxy to an underlying object.

    68 

    69   If you just need to handle access to a set of properties that are

    70   known at the time an object is created (i.e. "semi-statically"), you

    71   might consider using QScriptValue::setProperty() to define

    72   getter/setter functions for the relevant properties, rather than

    73   subclassing QScriptClass.

    74 

    75   Reimplement queryProperty() to specify which properties are handled

    76   in a custom way by your script class (i.e. should be

    77   \bold{delegated} to the QScriptClass), and which properties should

    78   be handled just like normal Qt Script object properties.

    79 

    80   Reimplement property() and setProperty() to perform the actual

    81   access (read or write) to the properties that your class

    82   handles. Additionally, you can reimplement propertyFlags() to

    83   specify custom flags for your properties.

    84 

    85   Reimplement newIterator() to provide an iterator for objects of your

    86   custom class. This is only necessary if objects of your class can

    87   have custom properties that you want to be reported when an object

    88   is used together with the QScriptValueIterator class, or when an

    89   object is used in a for-in enumeration statement in a script.

    90 

    91   When implementing custom classes of objects, you typically use

    92   QScriptValue::setData() to store instance-specific data as part of

    93   object initialization; the data won't be accessible from scripts

    94   directly, but you can access it in e.g. your reimplementations of

    95   property() and setProperty() (by calling QScriptValue::data()) to

    96   perform custom processing.

    97 

    98   Reimplement prototype() to provide a custom prototype object for

    99   your script class.

   100 

   101   Reimplement supportsExtension() and extension() if your custom

   102   script class supports one or more of the extensions specified by the

   103   Extension enum.

   104 

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

   106 */

   107 

   108 /*!

   109     \enum QScriptClass::Extension

   110 

   111     This enum specifies the possible extensions to a QScriptClass.

   112 

   113     \value Callable Instances of this class can be called as functions.

   114 

   115     \value HasInstance Instances of this class implement [[HasInstance]].

   116 

   117     \sa extension()

   118 */

   119 

   120 /*!

   121     \enum QScriptClass::QueryFlag

   122 

   123     This enum describes flags that are used to query a QScriptClass

   124     regarding how access to a property should be handled.

   125 

   126     \value HandlesReadAccess The QScriptClass handles read access to this property.

   127     \value HandlesWriteAccess The QScriptClass handles write access to this property.

   128 

   129     \sa queryProperty()

   130 */

   131 

   132 QT_BEGIN_NAMESPACE

   133 

   134 class QScriptClassPrivate

   135 {

   136     Q_DECLARE_PUBLIC(QScriptClass)

   137 public:

   138     QScriptClassPrivate() {}

   139     virtual ~QScriptClassPrivate() {}

   140 

   141     QScriptEngine *engine;

   142 

   143     QScriptClass *q_ptr;

   144 };

   145 

   146 /*!

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

   148 

   149   The engine does not take ownership of the QScriptClass object.

   150 */

   151 QScriptClass::QScriptClass(QScriptEngine *engine)

   152     : d_ptr(new QScriptClassPrivate)

   153 {

   154     d_ptr->q_ptr = this;

   155     d_ptr->engine = engine;

   156 }

   157 

   158 /*!

   159   \internal

   160 */

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

   162     : d_ptr(&dd)

   163 {

   164     d_ptr->q_ptr = this;

   165     d_ptr->engine = engine;

   166 }

   167 

   168 /*!

   169   Destroys the QScriptClass object.

   170 

   171   If a QScriptClass object is deleted before the associated engine(),

   172   any Qt Script objects using the QScriptClass will be "demoted" to

   173   normal Qt Script objects.

   174 */

   175 QScriptClass::~QScriptClass()

   176 {

   177 }

   178 

   179 /*!

   180   Returns the engine that this QScriptClass is associated with.

   181 */

   182 QScriptEngine *QScriptClass::engine() const

   183 {

   184     Q_D(const QScriptClass);

   185     return d->engine;

   186 }

   187 

   188 /*!

   189   Returns the object to be used as the prototype of new instances

   190   of this class (created with QScriptEngine::newObject()).

   191 

   192   The default implementation returns an invalid QScriptValue, meaning

   193   that the standard Object prototype will be used.  Reimplement this

   194   function to provide your own custom prototype.

   195 

   196   Typically you initialize your prototype object in the constructor of

   197   your class, then return it in this function.

   198 

   199   See the "Making Use of Prototype-Based Inheritance" section in the

   200   QtScript documentation for more information on how prototypes are

   201   used.

   202 */

   203 QScriptValue QScriptClass::prototype() const

   204 {

   205     return QScriptValue();

   206 }

   207 

   208 /*!

   209   Returns the name of the script class.

   210 

   211   Qt Script uses this name to generate a default string representation

   212   of objects in case you do not provide a toString function.

   213 

   214   The default implementation returns a null string.

   215 */

   216 QString QScriptClass::name() const

   217 {

   218     return QString();

   219 }

   220 

   221 /*!

   222   Queries this script class for how access to the property with the

   223   given \a name of the given \a object should be handled. The given \a

   224   flags specify the aspects of interest. This function should return a

   225   subset of \a flags to indicate which aspects of property access

   226   should be further handled by the script class.

   227 

   228   For example, if the \a flags contain HandlesReadAccess, and you

   229   would like your class to handle the reading of the property (through

   230   the property() function), the returned flags should include

   231   HandlesReadAccess. If the returned flags do not contain

   232   HandlesReadAccess, the property will be handled as a normal script

   233   object property.

   234 

   235   You can optionally use the \a id argument to store a value that will

   236   subsequently be passed on to functions such as property() and

   237   setProperty().

   238 

   239   The default implementation of this function returns 0.

   240 

   241   Note: This function is only called if the given property isn't

   242   already a normal property of the object. For example, say you

   243   advertise that you want to handle read access to property \c{foo},

   244   but not write access; if \c{foo} is then assigned a value, it will

   245   become a normal script object property, and subsequently you will no

   246   longer be queried regarding read access to \c{foo}.

   247 

   248   \sa property()

   249 */

   250 QScriptClass::QueryFlags QScriptClass::queryProperty(

   251     const QScriptValue &object, const QScriptString &name,

   252     QueryFlags flags, uint *id)

   253 {

   254     Q_UNUSED(object);

   255     Q_UNUSED(name);

   256     Q_UNUSED(flags);

   257     Q_UNUSED(id);

   258     return 0;

   259 }

   260 

   261 /*!

   262   Returns the value of the property with the given \a name of the given

   263   \a object.

   264 

   265   The \a id argument is only useful if you assigned a value to it in

   266   queryProperty().

   267 

   268   The default implementation does nothing and returns an invalid QScriptValue.

   269 

   270   \sa setProperty(), propertyFlags()

   271 */

   272 QScriptValue QScriptClass::property(const QScriptValue &object,

   273                                     const QScriptString &name, uint id)

   274 {

   275     Q_UNUSED(object);

   276     Q_UNUSED(name);

   277     Q_UNUSED(id);

   278     return QScriptValue();

   279 }

   280 

   281 /*!

   282   Returns the flags of the property with the given \a name of the given

   283   \a object.

   284 

   285   The \a id argument is only useful if you assigned a value to it in

   286   queryProperty().

   287 

   288   The default implementation returns 0.

   289 

   290   \sa property()

   291 */

   292 QScriptValue::PropertyFlags QScriptClass::propertyFlags(

   293     const QScriptValue &object, const QScriptString &name, uint id)

   294 {

   295     Q_UNUSED(object);

   296     Q_UNUSED(name);

   297     Q_UNUSED(id);

   298     return 0;

   299 }

   300 

   301 /*!

   302   Sets the property with the given \a name of the given \a object to

   303   the given \a value.

   304 

   305   The \a id argument is only useful if you assigned a value to it in

   306   queryProperty().

   307 

   308   The default implementation does nothing.

   309 

   310   An invalid \a value represents a request to remove the property.

   311 

   312   \sa property()

   313 */

   314 void QScriptClass::setProperty(QScriptValue &object, const QScriptString &name,

   315                                uint id, const QScriptValue &value)

   316 {

   317     Q_UNUSED(object);

   318     Q_UNUSED(name);

   319     Q_UNUSED(id);

   320     Q_UNUSED(value);

   321 }

   322 

   323 /*!

   324   Returns an iterator for traversing custom properties of the given \a

   325   object.

   326 

   327   The default implementation returns 0, meaning that there are no

   328   custom properties to traverse.

   329 

   330   Reimplement this function if objects of your script class can have

   331   one or more custom properties (e.g. those reported to be handled by

   332   queryProperty()) that you want to appear when an object's properties

   333   are enumerated (e.g. by a for-in statement in a script).

   334 

   335   Qt Script takes ownership of the new iterator object.

   336 

   337   \sa QScriptValueIterator

   338 */

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

   340 {

   341     Q_UNUSED(object);

   342     return 0;

   343 }

   344 

   345 /*!

   346   Returns true if the QScriptClass supports the given \a extension;

   347   otherwise, false is returned. By default, no extensions

   348   are supported.

   349 

   350   Reimplement this function to indicate which extensions your custom

   351   class supports.

   352 

   353   \sa extension()

   354 */

   355 bool QScriptClass::supportsExtension(Extension extension) const

   356 {

   357     Q_UNUSED(extension);

   358     return false;

   359 }

   360 

   361 /*!

   362   This virtual function can be reimplemented in a QScriptClass

   363   subclass to provide support for extensions. The optional \a argument

   364   can be provided as input to the \a extension; the result must be

   365   returned in the form of a QVariant. You can call supportsExtension()

   366   to check if an extension is supported by the QScriptClass.  By

   367   default, no extensions are supported, and this function returns an

   368   invalid QVariant.

   369 

   370   If you implement the Callable extension, Qt Script will call this

   371   function when an instance of your class is called as a function

   372   (e.g. from a script or using QScriptValue::call()).  The \a argument

   373   will contain a pointer to the QScriptContext that represents the

   374   function call, and you should return a QVariant that holds the

   375   result of the function call. In the following example the sum of the

   376   arguments to the script function are added up and returned:

   377 

   378   \snippet doc/src/snippets/code/src_script_qscriptclass.cpp 0

   379 

   380   If you implement the HasInstance extension, Qt Script will call this

   381   function as part of evaluating the \c{instanceof} operator, as

   382   described in ECMA-262 Section 11.8.6. The \a argument is a

   383   QScriptValueList containing two items: The first item is the object

   384   that HasInstance is being applied to (an instance of your class),

   385   and the second item can be any value. extension() should return true

   386   if the value delegates behavior to the object, false otherwise.

   387 

   388   \sa supportsExtension()

   389 */

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

   391 {

   392     Q_UNUSED(extension);

   393     Q_UNUSED(argument);

   394     return QVariant();

   395 }

   396 

   397 QT_END_NAMESPACE