src/script/qscriptengine.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: Nokia Corporation (qt-info@nokia.com)
   5 **
   6 ** This file is part of the QtScript module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** No Commercial Usage
  10 ** This file contains pre-release code and may not be distributed.
  11 ** You may use this file in accordance with the terms and conditions
  12 ** contained in the either Technology Preview License Agreement or the
  13 ** Beta Release License Agreement.
  14 **
  15 ** GNU Lesser General Public License Usage
  16 ** Alternatively, this file may be used under the terms of the GNU Lesser
  17 ** General Public License version 2.1 as published by the Free Software
  18 ** Foundation and appearing in the file LICENSE.LGPL included in the
  19 ** packaging of this file.  Please review the following information to
  20 ** ensure the GNU Lesser General Public License version 2.1 requirements
  21 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  22 **
  23 ** In addition, as a special exception, Nokia gives you certain
  24 ** additional rights. These rights are described in the Nokia Qt LGPL
  25 ** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
  26 ** package.
  27 **
  28 ** GNU General Public License Usage
  29 ** Alternatively, this file may be used under the terms of the GNU
  30 ** General Public License version 3.0 as published by the Free Software
  31 ** Foundation and appearing in the file LICENSE.GPL included in the
  32 ** packaging of this file.  Please review the following information to
  33 ** ensure the GNU General Public License version 3.0 requirements will be
  34 ** met: http://www.gnu.org/copyleft/gpl.html.
  35 **
  36 ** If you are unsure which license is appropriate for your use, please
  37 ** contact the sales department at http://www.qtsoftware.com/contact.
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #ifndef QSCRIPTENGINE_H
  43 #define QSCRIPTENGINE_H
  44
  45 #include <QtCore/qmetatype.h>
  46
  47 #ifndef QT_NO_SCRIPT
  48
  49 #include <QtCore/qvariant.h>
  50
  51 #ifndef QT_NO_QOBJECT
  52 #include <QtCore/qobject.h>
  53 #else
  54 #include <QtCore/qobjectdefs.h>
  55 #endif
  56
  57 #include <QtScript/qscriptvalue.h>
  58 #include <QtScript/qscriptcontext.h>
  59 #include <QtScript/qscriptstring.h>
  60
  61 QT_BEGIN_HEADER
  62
  63 QT_BEGIN_NAMESPACE
  64
  65 QT_MODULE(Script)
  66
  67 class QDateTime;
  68 class QScriptClass;
  69 class QScriptEngineAgent;
  70 class QScriptEnginePrivate;
  71
  72 #ifndef QT_NO_QOBJECT
  73
  74 template <class T>
  75 inline QScriptValue qscriptQMetaObjectConstructor(QScriptContext *, QScriptEngine *, T *)
  76 {
  77     return QScriptValue();
  78 }
  79
  80 #endif // QT_NO_QOBJECT
  81
  82 #ifndef QT_NO_REGEXP
  83 class QRegExp;
  84 #endif
  85
  86 #ifndef QT_NO_MEMBER_TEMPLATES
  87 template <typename T>
  88 inline QScriptValue qScriptValueFromValue(QScriptEngine *, const T &);
  89
  90 template <typename T>
  91 inline T qScriptValueToValue(const QScriptValue &);
  92 #endif
  93
  94 class QScriptSyntaxCheckResultPrivate;
  95 class Q_SCRIPT_EXPORT QScriptSyntaxCheckResult
  96 {
  97 public:
  98     enum State {
  99         Error,
 100         Intermediate,
 101         Valid
 102     };
 103
 104     QScriptSyntaxCheckResult(const QScriptSyntaxCheckResult &other);
 105     ~QScriptSyntaxCheckResult();
 106
 107     State state() const;
 108     int errorLineNumber() const;
 109     int errorColumnNumber() const;
 110     QString errorMessage() const;
 111
 112     QScriptSyntaxCheckResult &operator=(const QScriptSyntaxCheckResult &other);
 113
 114 private:
 115     QScriptSyntaxCheckResult();
 116     QScriptSyntaxCheckResult(QScriptSyntaxCheckResultPrivate *d);
 117     QScriptSyntaxCheckResultPrivate *d_ptr;
 118
 119     Q_DECLARE_PRIVATE(QScriptSyntaxCheckResult)
 120     friend class QScriptEnginePrivate;
 121 };
 122
 123 class Q_SCRIPT_EXPORT QScriptEngine
 124 #ifndef QT_NO_QOBJECT
 125     : public QObject
 126 #endif
 127 {
 128 #ifndef QT_NO_QOBJECT
 129     Q_OBJECT
 130 #endif
 131 public:
 132     enum ValueOwnership {
 133         QtOwnership,
 134         ScriptOwnership,
 135         AutoOwnership
 136     };
 137
 138     enum QObjectWrapOption {
 139         ExcludeChildObjects = 0x0001,
 140         ExcludeSuperClassMethods = 0x0002,
 141         ExcludeSuperClassProperties = 0x0004,
 142         ExcludeSuperClassContents = 0x0006,
 143         SkipMethodsInEnumeration = 0x0008,
 144         ExcludeDeleteLater = 0x0010,
 145
 146         AutoCreateDynamicProperties = 0x0100,
 147         PreferExistingWrapperObject = 0x0200
 148     };
 149     Q_DECLARE_FLAGS(QObjectWrapOptions, QObjectWrapOption)
 150
 151     QScriptEngine();
 152 #ifndef QT_NO_QOBJECT
 153     explicit QScriptEngine(QObject *parent);
 154 #endif
 155     virtual ~QScriptEngine();
 156
 157     QScriptValue globalObject() const;
 158     void setGlobalObject(const QScriptValue &object);
 159
 160     QScriptContext *currentContext() const;
 161     QScriptContext *pushContext();
 162     void popContext();
 163
 164     bool canEvaluate(const QString &program) const;
 165     static QScriptSyntaxCheckResult checkSyntax(const QString &program);
 166
 167     QScriptValue evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1);
 168
 169     bool isEvaluating() const;
 170     void abortEvaluation(const QScriptValue &result = QScriptValue());
 171
 172     bool hasUncaughtException() const;
 173     QScriptValue uncaughtException() const;
 174     int uncaughtExceptionLineNumber() const;
 175     QStringList uncaughtExceptionBacktrace() const;
 176     void clearExceptions();
 177
 178     QScriptValue nullValue();
 179     QScriptValue undefinedValue();
 180
 181     typedef QScriptValue (*FunctionSignature)(QScriptContext *, QScriptEngine *);
 182     typedef QScriptValue (*FunctionWithArgSignature)(QScriptContext *, QScriptEngine *, void *);
 183
 184     QScriptValue newFunction(FunctionSignature signature, int length = 0);
 185     QScriptValue newFunction(FunctionSignature signature, const QScriptValue &prototype, int length = 0);
 186
 187     QScriptValue newFunction(FunctionWithArgSignature signature, void *arg);
 188
 189     QScriptValue newVariant(const QVariant &value);
 190     QScriptValue newVariant(const QScriptValue &object, const QVariant &value);
 191
 192 #ifndef QT_NO_REGEXP
 193     QScriptValue newRegExp(const QRegExp &regexp);
 194 #endif
 195
 196     QScriptValue newObject();
 197     QScriptValue newObject(QScriptClass *scriptClass, const QScriptValue &data = QScriptValue());
 198     QScriptValue newArray(uint length = 0);
 199     QScriptValue newRegExp(const QString &pattern, const QString &flags);
 200     QScriptValue newDate(qsreal value);
 201     QScriptValue newDate(const QDateTime &value);
 202     QScriptValue newActivationObject();
 203
 204 #ifndef QT_NO_QOBJECT
 205     QScriptValue newQObject(QObject *object, ValueOwnership ownership = QtOwnership,
 206                             const QObjectWrapOptions &options = 0);
 207     QScriptValue newQObject(const QScriptValue &scriptObject, QObject *qtObject,
 208                             ValueOwnership ownership = QtOwnership,
 209                             const QObjectWrapOptions &options = 0);
 210
 211     QScriptValue newQMetaObject(const QMetaObject *metaObject, const QScriptValue &ctor = QScriptValue());
 212
 213 #  ifndef QT_NO_MEMBER_TEMPLATES
 214     template <class T> QScriptValue scriptValueFromQMetaObject();
 215 #  endif // QT_NO_MEMBER_TEMPLATES
 216
 217 #endif // QT_NO_QOBJECT
 218
 219
 220
 221     QScriptValue defaultPrototype(int metaTypeId) const;
 222     void setDefaultPrototype(int metaTypeId, const QScriptValue &prototype);
 223
 224
 225     typedef QScriptValue (*MarshalFunction)(QScriptEngine *, const void *);
 226     typedef void (*DemarshalFunction)(const QScriptValue &, void *);
 227
 228
 229
 230 #ifndef QT_NO_MEMBER_TEMPLATES
 231     template <typename T>
 232     inline QScriptValue toScriptValue(const T &value)
 233     {
 234         return qScriptValueFromValue(this, value);
 235     }
 236     template <typename T>
 237     inline T fromScriptValue(const QScriptValue &value)
 238     {
 239         return qScriptValueToValue<T>(value);
 240     }
 241 #endif // QT_NO_MEMBER_TEMPLATES
 242
 243     void installTranslatorFunctions(const QScriptValue &object = QScriptValue());
 244
 245     QScriptValue importExtension(const QString &extension);
 246     QStringList availableExtensions() const;
 247     QStringList importedExtensions() const;
 248
 249     void collectGarbage();
 250
 251     void setProcessEventsInterval(int interval);
 252     int processEventsInterval() const;
 253
 254     void setAgent(QScriptEngineAgent *agent);
 255     QScriptEngineAgent *agent() const;
 256
 257     QScriptString toStringHandle(const QString &str);
 258     QScriptValue toObject(const QScriptValue &value);
 259
 260     QScriptValue objectById(qint64 id) const;
 261
 262 #ifndef QT_NO_QOBJECT
 263 Q_SIGNALS:
 264     void signalHandlerException(const QScriptValue &exception);
 265 #endif
 266
 267 private:
 268     QScriptValue create(int type, const void *ptr);
 269
 270     bool convert(const QScriptValue &value, int type, void *ptr);
 271     static bool convertV2(const QScriptValue &value, int type, void *ptr);
 272
 273     void registerCustomType(int type, MarshalFunction mf, DemarshalFunction df,
 274                             const QScriptValue &prototype);
 275
 276     friend inline void qScriptRegisterMetaType_helper(QScriptEngine *,
 277         int, MarshalFunction, DemarshalFunction, const QScriptValue &);
 278
 279     friend inline QScriptValue qScriptValueFromValue_helper(QScriptEngine *, int, const void *);
 280
 281     friend inline bool qscriptvalue_cast_helper(const QScriptValue &, int, void *);
 282
 283 protected:
 284 #ifdef QT_NO_QOBJECT
 285     QScriptEnginePrivate *d_ptr;
 286
 287     QScriptEngine(QScriptEnginePrivate &dd);
 288 #else
 289     QScriptEngine(QScriptEnginePrivate &dd, QObject *parent = 0);
 290 #endif
 291
 292 private:
 293     Q_DECLARE_PRIVATE(QScriptEngine)
 294     Q_DISABLE_COPY(QScriptEngine)
 295 #ifndef QT_NO_QOBJECT
 296     Q_PRIVATE_SLOT(d_func(), void _q_objectDestroyed(QObject *))
 297 #endif
 298 };
 299
 300 #ifndef QT_NO_QOBJECT
 301 template <class T>
 302 inline QScriptValue qScriptValueFromQMetaObject(
 303     QScriptEngine *engine
 304 #ifndef qdoc
 305     , T * /* dummy */ = 0
 306 #endif
 307     )
 308 {
 309     typedef QScriptValue(*ConstructPtr)(QScriptContext *, QScriptEngine *, T *);
 310     ConstructPtr cptr = qscriptQMetaObjectConstructor<T>;
 311     return engine->newQMetaObject(&T::staticMetaObject,
 312                                   engine->newFunction(reinterpret_cast<QScriptEngine::FunctionWithArgSignature>(cptr), 0));
 313 }
 314
 315 #define Q_SCRIPT_DECLARE_QMETAOBJECT(T, _Arg1) \
 316 template<> inline QScriptValue qscriptQMetaObjectConstructor<T>(QScriptContext *ctx, QScriptEngine *eng, T *) \
 317 { \
 318     _Arg1 arg1 = qscriptvalue_cast<_Arg1> (ctx->argument(0)); \
 319     T* t = new T(arg1); \
 320     if (ctx->isCalledAsConstructor()) \
 321         return eng->newQObject(ctx->thisObject(), t, QScriptEngine::AutoOwnership); \
 322     QScriptValue o = eng->newQObject(t, QScriptEngine::AutoOwnership); \
 323     o.setPrototype(ctx->callee().property(QString::fromLatin1("prototype"))); \
 324     return o; \
 325 }
 326
 327 #  ifndef QT_NO_MEMBER_TEMPLATES
 328     template <class T> QScriptValue QScriptEngine::scriptValueFromQMetaObject()
 329     {
 330         return qScriptValueFromQMetaObject<T>(this);
 331     }
 332 #  endif // QT_NO_MEMBER_TEMPLATES
 333
 334 #endif // QT_NO_QOBJECT
 335
 336 inline QScriptValue qScriptValueFromValue_helper(QScriptEngine *engine, int type, const void *ptr)
 337 {
 338     if (!engine)
 339         return QScriptValue();
 340
 341     return engine->create(type, ptr);
 342 }
 343
 344 template <typename T>
 345 inline QScriptValue qScriptValueFromValue(QScriptEngine *engine, const T &t)
 346 {
 347     return qScriptValueFromValue_helper(engine, qMetaTypeId<T>(), &t);
 348 }
 349
 350 template <>
 351 inline QScriptValue qScriptValueFromValue<QVariant>(QScriptEngine *engine, const QVariant &v)
 352 {
 353     QScriptValue result = qScriptValueFromValue_helper(engine, v.userType(), v.data());
 354     if (!result.isValid())
 355         result = engine->newVariant(v);
 356     return result;
 357 }
 358
 359 inline bool qscriptvalue_cast_helper(const QScriptValue &value, int type, void *ptr)
 360 {
 361     return QScriptEngine::convertV2(value, type, ptr);
 362 }
 363
 364 template<typename T>
 365 T qscriptvalue_cast(const QScriptValue &value
 366 #if !defined qdoc && defined Q_CC_MSVC && _MSC_VER < 1300
 367 , T * = 0
 368 #endif
 369     )
 370 {
 371     T t;
 372     const int id = qMetaTypeId<T>();
 373
 374     if (qscriptvalue_cast_helper(value, id, &t))
 375         return t;
 376     else if (value.isVariant())
 377         return qvariant_cast<T>(value.toVariant());
 378
 379     return T();
 380 }
 381
 382 #if !defined Q_CC_MSVC || _MSC_VER >= 1300
 383 template <>
 384 inline QVariant qscriptvalue_cast<QVariant>(const QScriptValue &value)
 385 {
 386     return value.toVariant();
 387 }
 388 #endif
 389
 390 template <typename T>
 391 inline T qScriptValueToValue(const QScriptValue &value)
 392 {
 393     return qscriptvalue_cast<T>(value);
 394 }
 395
 396 inline void qScriptRegisterMetaType_helper(QScriptEngine *eng, int type,
 397                                            QScriptEngine::MarshalFunction mf,
 398                                            QScriptEngine::DemarshalFunction df,
 399                                            const QScriptValue &prototype)
 400 {
 401     eng->registerCustomType(type, mf, df, prototype);
 402 }
 403
 404 template<typename T>
 405 int qScriptRegisterMetaType(
 406     QScriptEngine *eng,
 407     QScriptValue (*toScriptValue)(QScriptEngine *, const T &t),
 408     void (*fromScriptValue)(const QScriptValue &, T &t),
 409     const QScriptValue &prototype = QScriptValue()
 410 #ifndef qdoc
 411     , T * /* dummy */ = 0
 412 #endif
 413 )
 414 {
 415     const int id = qRegisterMetaType<T>(); // make sure it's registered
 416
 417     qScriptRegisterMetaType_helper(
 418         eng, id, reinterpret_cast<QScriptEngine::MarshalFunction>(toScriptValue),
 419         reinterpret_cast<QScriptEngine::DemarshalFunction>(fromScriptValue),
 420         prototype);
 421
 422     return id;
 423 }
 424
 425 template <class Container>
 426 QScriptValue qScriptValueFromSequence(QScriptEngine *eng, const Container &cont)
 427 {
 428     QScriptValue a = eng->newArray();
 429     typename Container::const_iterator begin = cont.begin();
 430     typename Container::const_iterator end = cont.end();
 431     typename Container::const_iterator it;
 432     quint32 i;
 433     for (it = begin, i = 0; it != end; ++it, ++i)
 434         a.setProperty(i, qScriptValueFromValue(eng, *it));
 435     return a;
 436 }
 437
 438 template <class Container>
 439 void qScriptValueToSequence(const QScriptValue &value, Container &cont)
 440 {
 441     quint32 len = value.property(QLatin1String("length")).toUInt32();
 442     for (quint32 i = 0; i < len; ++i) {
 443         QScriptValue item = value.property(i);
 444 #if defined Q_CC_MSVC && !defined Q_CC_MSVC_NET
 445         cont.push_back(qscriptvalue_cast<Container::value_type>(item));
 446 #else
 447         cont.push_back(qscriptvalue_cast<typename Container::value_type>(item));
 448 #endif
 449     }
 450 }
 451
 452 template<typename T>
 453 int qScriptRegisterSequenceMetaType(
 454     QScriptEngine *engine,
 455     const QScriptValue &prototype = QScriptValue()
 456 #ifndef qdoc
 457     , T * /* dummy */ = 0
 458 #endif
 459 )
 460 {
 461     return qScriptRegisterMetaType<T>(engine, qScriptValueFromSequence,
 462                                       qScriptValueToSequence, prototype);
 463 }
 464
 465 #ifndef QT_NO_QOBJECT
 466 Q_SCRIPT_EXPORT bool qScriptConnect(QObject *sender, const char *signal,
 467                                     const QScriptValue &receiver,
 468                                     const QScriptValue &function);
 469 Q_SCRIPT_EXPORT bool qScriptDisconnect(QObject *sender, const char *signal,
 470                                        const QScriptValue &receiver,
 471                                        const QScriptValue &function);
 472 #endif // QT_NO_QOBJECT
 473
 474 Q_DECLARE_OPERATORS_FOR_FLAGS(QScriptEngine::QObjectWrapOptions)
 475
 476 QT_END_NAMESPACE
 477
 478 QT_END_HEADER
 479
 480 #endif // QT_NO_SCRIPT
 481 #endif // QSCRIPTENGINE_H