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

     2 **

     3 ** Copyright (C) 2010 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-ONLY$

    10 ** GNU Lesser General Public License Usage

    11 ** This file may be used under the terms of the GNU Lesser

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

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

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

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

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

    17 **

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

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

    20 ** $QT_END_LICENSE$

    21 **

    22 ****************************************************************************/

    23 

    24 #include "qscriptable.h"

    25 #include "qscriptable_p.h"

    26 #include "qscriptengine.h"

    27 

    28 QT_BEGIN_NAMESPACE

    29 

    30 /*!

    31   \since 4.3

    32   \class QScriptable

    33 

    34   \brief The QScriptable class provides access to the Qt Script environment from Qt C++ member functions.

    35 

    36   \ingroup script

    37 

    38 

    39   With QScriptEngine::newQObject(), you can expose the signals and

    40   slots and properties of any QObject (or subclass) to script

    41   code. QScriptable augments this functionality by giving your C++

    42   members access to the Qt Script environment they are invoked in;

    43   conceptually, it is similar to QObject::sender().

    44 

    45   By subclassing QScriptable, you get the following functions in your

    46   class: thisObject(), argumentCount(), argument(), context() and

    47   engine(). With these functions, you have full access to the Qt

    48   Script environment from the slots and property access functions of

    49   your class, when they are invoked from script code.

    50 

    51   For example, you can throw a Qt Script exception from a slot;

    52   manipulate the `this' object associated with the function call;

    53   inspect the arguments stored in the QScriptContext to know the

    54   "real" arguments passed to the function from script code; and call

    55   script functions from your slot.

    56 

    57   A typical use case of QScriptable is to implement prototype objects

    58   for custom C++ types. You define the scriptable interface of your

    59   custom type in a QScriptable subclass using properties and slots;

    60   then you wrap an instance of your class using

    61   QScriptEngine::newQObject(), and finally pass the result to

    62   QScriptEngine::setDefaultPrototype(). See the \l{Default Prototypes Example}

    63   to see how this can be done.

    64 

    65   The following is what subclassing QScriptable typically looks

    66   like:

    67 

    68   \snippet doc/src/snippets/code/src_script_qscriptable.cpp 0

    69 

    70   The only difference from regular QObject subclassing is that you

    71   also inherit from QScriptable.

    72 

    73   In the implementation of your slots, you can then use the functions

    74   inherited from QScriptable:

    75 

    76   \snippet doc/src/snippets/code/src_script_qscriptable.cpp 1

    77 

    78   \sa {Default Prototypes Example}, QScriptEngine::newFunction()

    79 */

    80 

    81 /*!

    82   \internal

    83 */

    84 QScriptable::QScriptable()

    85     : d_ptr(new QScriptablePrivate())

    86 {

    87     d_ptr->q_ptr = this;

    88 }

    89 

    90 /*!

    91   \internal

    92 */

    93 QScriptable::~QScriptable()

    94 {

    95 }

    96 

    97 /*!

    98   Returns a pointer to the QScriptEngine associated with the current

    99   Qt function call, or 0 if the Qt function was not invoked from

   100   script code.

   101 */

   102 QScriptEngine *QScriptable::engine() const

   103 {

   104     Q_D(const QScriptable);

   105     return d->engine;

   106 }

   107 

   108 /*!

   109   Returns a pointer to the QScriptContext associated with the current

   110   Qt function call, or 0 if the Qt function was not invoked from

   111   script code.

   112 */

   113 QScriptContext *QScriptable::context() const

   114 {

   115     if (QScriptEngine *e = engine())

   116         return e->currentContext();

   117 

   118     return 0;

   119 }

   120 

   121 /*!

   122   Returns the `this' object associated with the current Qt function

   123   call, or an invalid QScriptValue if the Qt function was not invoked

   124   from script code.

   125 */

   126 

   127 QScriptValue QScriptable::thisObject() const

   128 {

   129     if (QScriptContext *c = context())

   130         return c->thisObject();

   131 

   132     return QScriptValue();

   133 }

   134 

   135 /*!

   136   Returns the number of arguments passed to the function in this

   137   invocation, or -1 if the Qt function was not invoked from script

   138   code.

   139 

   140   \sa argument()

   141 */

   142 int QScriptable::argumentCount() const

   143 {

   144     if (QScriptContext *c = context())

   145         return c->argumentCount();

   146 

   147     return -1;

   148 }

   149 

   150 /*!

   151   Returns the function argument at the given \a index, or an invalid

   152   QScriptValue if the Qt function was not invoked from script code.

   153 

   154   \sa argumentCount()

   155 */

   156 QScriptValue QScriptable::argument(int index) const

   157 {

   158     if (QScriptContext *c = context())

   159         return c->argument(index);

   160 

   161     return QScriptValue();

   162 }

   163 

   164 QT_END_NAMESPACE