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 "qscriptable.h"

    43 #include "qscriptable_p.h"

    44 #include "qscriptengine.h"

    45 

    46 QT_BEGIN_NAMESPACE

    47 

    48 /*!

    49   \since 4.3

    50   \class QScriptable

    51 

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

    53 

    54   \ingroup script

    55 

    56 

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

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

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

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

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

    62 

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

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

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

    66   Script environment from the slots and property access functions of

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

    68 

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

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

    71   inspect the arguments stored in the QScriptContext to know the

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

    73   script functions from your slot.

    74 

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

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

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

    78   then you wrap an instance of your class using

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

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

    81   to see how this can be done.

    82 

    83   The following is what subclassing QScriptable typically looks

    84   like:

    85 

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

    87 

    88   The only difference from regular QObject subclassing is that you

    89   also inherit from QScriptable.

    90 

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

    92   inherited from QScriptable:

    93 

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

    95 

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

    97 */

    98 

    99 /*!

   100   \internal

   101 */

   102 QScriptable::QScriptable()

   103     : d_ptr(new QScriptablePrivate())

   104 {

   105     d_ptr->q_ptr = this;

   106 }

   107 

   108 /*!

   109   \internal

   110 */

   111 QScriptable::~QScriptable()

   112 {

   113 }

   114 

   115 /*!

   116   Returns a pointer to the QScriptEngine associated with the current

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

   118   script code.

   119 */

   120 QScriptEngine *QScriptable::engine() const

   121 {

   122     Q_D(const QScriptable);

   123     return d->engine;

   124 }

   125 

   126 /*!

   127   Returns a pointer to the QScriptContext associated with the current

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

   129   script code.

   130 */

   131 QScriptContext *QScriptable::context() const

   132 {

   133     if (QScriptEngine *e = engine())

   134         return e->currentContext();

   135 

   136     return 0;

   137 }

   138 

   139 /*!

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

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

   142   from script code.

   143 */

   144 

   145 QScriptValue QScriptable::thisObject() const

   146 {

   147     if (QScriptContext *c = context())

   148         return c->thisObject();

   149 

   150     return QScriptValue();

   151 }

   152 

   153 /*!

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

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

   156   code.

   157 

   158   \sa argument()

   159 */

   160 int QScriptable::argumentCount() const

   161 {

   162     if (QScriptContext *c = context())

   163         return c->argumentCount();

   164 

   165     return -1;

   166 }

   167 

   168 /*!

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

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

   171 

   172   \sa argumentCount()

   173 */

   174 QScriptValue QScriptable::argument(int index) const

   175 {

   176     if (QScriptContext *c = context())

   177         return c->argument(index);

   178 

   179     return QScriptValue();

   180 }

   181 

   182 QT_END_NAMESPACE