From 9d58167d352b2f860f473fd74b63541d7659b811 Mon Sep 17 00:00:00 2001 From: Mitch Curtis Date: Thu, 10 Sep 2015 09:11:13 +0200 Subject: Add extension API to QJSEngine This allows users in a JavaScript-only environment to install extensions including: - Translation functions (qsTr(), etc.) - The console object (console.log(), print(), etc.) - Garbage collection functions (gc()) This deprecates installTranslatorFunctions(). This API results in less clutter in the API, as we'd otherwise need to have several functions for each type of extension. [ChangeLog][QJSEngine] Introduced an extension API that allows installing various function and object extensions (qsTr(), console.log(), etc.) to QJSEngine. [ChangeLog][QJSEngine] installTranslatorFunctions() was deprecated in favor of the new extension API (see installExtensions()). Change-Id: I4d6eb2097c3eda6810e967b2e8f6441c28c91a16 Task-number: QTBUG-40772 Reviewed-by: Simon Hausmann --- src/qml/jsapi/qjsengine.cpp | 121 ++++++++++++++++++++++++++++---- src/qml/jsapi/qjsengine.h | 16 ++++- src/qml/qml/v8/qqmlbuiltinfunctions.cpp | 60 ++++++++++------ src/qml/qml/v8/qqmlbuiltinfunctions_p.h | 3 +- src/qml/qml/v8/qv8engine.cpp | 5 +- 5 files changed, 165 insertions(+), 40 deletions(-) (limited to 'src') diff --git a/src/qml/jsapi/qjsengine.cpp b/src/qml/jsapi/qjsengine.cpp index b217d3fb4c..5ccbccebad 100644 --- a/src/qml/jsapi/qjsengine.cpp +++ b/src/qml/jsapi/qjsengine.cpp @@ -160,8 +160,82 @@ Q_DECLARE_METATYPE(QList) \snippet code/src_script_qjsengine.cpp 5 - \sa QJSValue, {Making Applications Scriptable} + \section1 Extensions + QJSEngine provides a compliant ECMAScript implementation. By default, + familiar utilities like logging are not available, but they can can be + installed via the \l installExtensions() function. + + \sa QJSValue, {Making Applications Scriptable}, + {List of JavaScript Objects and Functions} + +*/ + +/*! + \enum QJSEngine::Extension + + This enum is used to specify extensions to be installed via + \l installExtensions(). + + \value TranslationExtension Indicates that translation functions (\c qsTr(), + for example) should be installed. + + \value ConsoleExtension Indicates that console functions (\c console.log(), + for example) should be installed. + + \value GarbageCollectionExtension Indicates that garbage collection + functions (\c gc(), for example) should be installed. + + \value AllExtensions Indicates that all extension should be installed. + + \b TranslationExtension + + The relation between script translation functions and C++ translation + functions is described in the following table: + + \table + \header \li Script Function \li Corresponding C++ Function + \row \li qsTr() \li QObject::tr() + \row \li QT_TR_NOOP() \li QT_TR_NOOP() + \row \li qsTranslate() \li QCoreApplication::translate() + \row \li QT_TRANSLATE_NOOP() \li QT_TRANSLATE_NOOP() + \row \li qsTrId() \li qtTrId() + \row \li QT_TRID_NOOP() \li QT_TRID_NOOP() + \endtable + + This flag also adds an \c arg() function to the string prototype. + + For more information, see the \l {Internationalization with Qt} + documentation. + + \b ConsoleExtension + + The \l {Console API}{console} object implements a subset of the + \l {https://developer.mozilla.org/en-US/docs/Web/API/Console}{Console API}, + which provides familiar logging functions, such as \c console.log(). + + The list of functions added is as follows: + + \list + \li \c console.assert() + \li \c console.debug() + \li \c console.exception() + \li \c console.info() + \li \c console.log() (equivalent to \c console.debug()) + \li \c console.error() + \li \c console.time() + \li \c console.timeEnd() + \li \c console.trace() + \li \c console.count() + \li \c console.warn() + \li \c {print()} (equivalent to \c console.debug()) + \endlist + + For more information, see the \l {Console API} documentation. + + \b GarbageCollectionExtension + + The \c gc() function is equivalent to calling \l collectGarbage(). */ QT_BEGIN_NAMESPACE @@ -234,8 +308,11 @@ void QJSEngine::collectGarbage() d->m_v4Engine->memoryManager->runGC(); } +#if QT_DEPRECATED_SINCE(5, 6) + /*! \since 5.4 + \obsolete Installs translator functions on the given \a object, or on the Global Object if no object is specified. @@ -258,12 +335,38 @@ void QJSEngine::collectGarbage() \sa {Internationalization with Qt} */ void QJSEngine::installTranslatorFunctions(const QJSValue &object) +{ + installExtensions(TranslationExtension, object); +} + +#endif // QT_DEPRECATED_SINCE(5, 6) + + +/*! + \since 5.6 + + Installs JavaScript \a extensions to add functionality that is not + available in a standard ECMAScript implementation. + + The extensions are installed on the given \a object, or on the + \l {globalObject()}{Global Object} if no object is specified. + + Several extensions can be installed at once by \c {OR}-ing the enum values: + + \code + installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension); + \endcode + + \sa Extension +*/ +void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object) { QV4::ExecutionEngine *otherEngine = QJSValuePrivate::engine(&object); if (otherEngine && otherEngine != d->m_v4Engine) { - qWarning("QJSEngine: Trying to install a translator function from a different engine"); + qWarning("QJSEngine: Trying to install extensions from a different engine"); return; } + QV4::Scope scope(d->m_v4Engine); QV4::ScopedObject obj(scope); QV4::Value *val = QJSValuePrivate::getValue(&object); @@ -271,18 +374,8 @@ void QJSEngine::installTranslatorFunctions(const QJSValue &object) obj = val; if (!obj) obj = scope.engine->globalObject; -#ifndef QT_NO_TRANSLATION - obj->defineDefaultProperty(QStringLiteral("qsTranslate"), QV4::GlobalExtensions::method_qsTranslate); - obj->defineDefaultProperty(QStringLiteral("QT_TRANSLATE_NOOP"), QV4::GlobalExtensions::method_qsTranslateNoOp); - obj->defineDefaultProperty(QStringLiteral("qsTr"), QV4::GlobalExtensions::method_qsTr); - obj->defineDefaultProperty(QStringLiteral("QT_TR_NOOP"), QV4::GlobalExtensions::method_qsTrNoOp); - obj->defineDefaultProperty(QStringLiteral("qsTrId"), QV4::GlobalExtensions::method_qsTrId); - obj->defineDefaultProperty(QStringLiteral("QT_TRID_NOOP"), QV4::GlobalExtensions::method_qsTrIdNoOp); - - // string prototype extension - scope.engine->stringPrototype()->defineDefaultProperty(QStringLiteral("arg"), - QV4::GlobalExtensions::method_string_arg); -#endif + + QV4::GlobalExtensions::init(obj, extensions); } /*! diff --git a/src/qml/jsapi/qjsengine.h b/src/qml/jsapi/qjsengine.h index 123eb727df..40b0a60369 100644 --- a/src/qml/jsapi/qjsengine.h +++ b/src/qml/jsapi/qjsengine.h @@ -81,7 +81,19 @@ public: void collectGarbage(); - void installTranslatorFunctions(const QJSValue &object = QJSValue()); +#if QT_DEPRECATED_SINCE(5, 6) + QT_DEPRECATED void installTranslatorFunctions(const QJSValue &object = QJSValue()); +#endif + + enum Extension { + TranslationExtension = 0x1, + ConsoleExtension = 0x2, + GarbageCollectionExtension = 0x4, + AllExtensions = 0xffffffff + }; + Q_DECLARE_FLAGS(Extensions, Extension) + + void installExtensions(Extensions extensions, const QJSValue &object = QJSValue()); QV8Engine *handle() const { return d; } @@ -102,6 +114,8 @@ private: friend class QV8Engine; }; +Q_DECLARE_OPERATORS_FOR_FLAGS(QJSEngine::Extensions) + inline bool qjsvalue_cast_helper(const QJSValue &value, int type, void *ptr) { return QJSEngine::convertV2(value, type, ptr); diff --git a/src/qml/qml/v8/qqmlbuiltinfunctions.cpp b/src/qml/qml/v8/qqmlbuiltinfunctions.cpp index 3242833e22..5deac8343e 100644 --- a/src/qml/qml/v8/qqmlbuiltinfunctions.cpp +++ b/src/qml/qml/v8/qqmlbuiltinfunctions.cpp @@ -1390,27 +1390,30 @@ static QV4::ReturnedValue writeToConsole(ConsoleLogTypes logType, CallContext *c result.append(jsStack(v4)); } - static QLoggingCategory loggingCategory("qml"); + static QLoggingCategory qmlLoggingCategory("qml"); + static QLoggingCategory jsLoggingCategory("js"); + + QLoggingCategory *loggingCategory = v4->qmlEngine() ? &qmlLoggingCategory : &jsLoggingCategory; QV4::StackFrame frame = v4->currentStackFrame(); const QByteArray baSource = frame.source.toUtf8(); const QByteArray baFunction = frame.function.toUtf8(); - QMessageLogger logger(baSource.constData(), frame.line, baFunction.constData(), loggingCategory.categoryName()); + QMessageLogger logger(baSource.constData(), frame.line, baFunction.constData(), loggingCategory->categoryName()); switch (logType) { case Log: - if (loggingCategory.isDebugEnabled()) + if (loggingCategory->isDebugEnabled()) logger.debug("%s", result.toUtf8().constData()); break; case Info: - if (loggingCategory.isInfoEnabled()) + if (loggingCategory->isInfoEnabled()) logger.info("%s", result.toUtf8().constData()); break; case Warn: - if (loggingCategory.isWarningEnabled()) + if (loggingCategory->isWarningEnabled()) logger.warning("%s", result.toUtf8().constData()); break; case Error: - if (loggingCategory.isCriticalEnabled()) + if (loggingCategory->isCriticalEnabled()) logger.critical("%s", result.toUtf8().constData()); break; default: @@ -1442,6 +1445,9 @@ QV4::ReturnedValue ConsoleObject::method_profile(CallContext *ctx) { QV4::ExecutionEngine *v4 = ctx->d()->engine; + if (!v4->qmlEngine()) + return QV4::Encode::undefined(); // Not yet implemented for JavaScript. + QV4::StackFrame frame = v4->currentStackFrame(); const QByteArray baSource = frame.source.toUtf8(); const QByteArray baFunction = frame.function.toUtf8(); @@ -1461,6 +1467,9 @@ QV4::ReturnedValue ConsoleObject::method_profileEnd(CallContext *ctx) { QV4::ExecutionEngine *v4 = ctx->d()->engine; + if (!v4->qmlEngine()) + return QV4::Encode::undefined(); // Not yet implemented for JavaScript. + QV4::StackFrame frame = v4->currentStackFrame(); const QByteArray baSource = frame.source.toUtf8(); const QByteArray baFunction = frame.function.toUtf8(); @@ -1590,31 +1599,36 @@ QV4::ReturnedValue ConsoleObject::method_exception(CallContext *ctx) -void QV4::GlobalExtensions::init(QQmlEngine *qmlEngine, Object *globalObject) +void QV4::GlobalExtensions::init(Object *globalObject, QJSEngine::Extensions extensions) { ExecutionEngine *v4 = globalObject->engine(); Scope scope(v4); -#ifndef QT_NO_TRANSLATION - globalObject->defineDefaultProperty(QStringLiteral("qsTranslate"), method_qsTranslate); - globalObject->defineDefaultProperty(QStringLiteral("QT_TRANSLATE_NOOP"), method_qsTranslateNoOp); - globalObject->defineDefaultProperty(QStringLiteral("qsTr"), method_qsTr); - globalObject->defineDefaultProperty(QStringLiteral("QT_TR_NOOP"), method_qsTrNoOp); - globalObject->defineDefaultProperty(QStringLiteral("qsTrId"), method_qsTrId); - globalObject->defineDefaultProperty(QStringLiteral("QT_TRID_NOOP"), method_qsTrIdNoOp); -#endif + if (extensions.testFlag(QJSEngine::TranslationExtension)) { + #ifndef QT_NO_TRANSLATION + globalObject->defineDefaultProperty(QStringLiteral("qsTranslate"), QV4::GlobalExtensions::method_qsTranslate); + globalObject->defineDefaultProperty(QStringLiteral("QT_TRANSLATE_NOOP"), QV4::GlobalExtensions::method_qsTranslateNoOp); + globalObject->defineDefaultProperty(QStringLiteral("qsTr"), QV4::GlobalExtensions::method_qsTr); + globalObject->defineDefaultProperty(QStringLiteral("QT_TR_NOOP"), QV4::GlobalExtensions::method_qsTrNoOp); + globalObject->defineDefaultProperty(QStringLiteral("qsTrId"), QV4::GlobalExtensions::method_qsTrId); + globalObject->defineDefaultProperty(QStringLiteral("QT_TRID_NOOP"), QV4::GlobalExtensions::method_qsTrIdNoOp); + + // string prototype extension + scope.engine->stringPrototype()->defineDefaultProperty(QStringLiteral("arg"), QV4::GlobalExtensions::method_string_arg); + #endif + } - globalObject->defineDefaultProperty(QStringLiteral("print"), ConsoleObject::method_log); - globalObject->defineDefaultProperty(QStringLiteral("gc"), method_gc); + if (extensions.testFlag(QJSEngine::ConsoleExtension)) { + globalObject->defineDefaultProperty(QStringLiteral("print"), QV4::ConsoleObject::method_log); - ScopedObject console(scope, v4->memoryManager->allocObject()); - globalObject->defineDefaultProperty(QStringLiteral("console"), console); - ScopedObject qt(scope, v4->memoryManager->allocObject(qmlEngine)); - globalObject->defineDefaultProperty(QStringLiteral("Qt"), qt); + QV4::ScopedObject console(scope, globalObject->engine()->memoryManager->allocObject()); + globalObject->defineDefaultProperty(QStringLiteral("console"), console); + } - // string prototype extension - v4->stringPrototype()->defineDefaultProperty(QStringLiteral("arg"), method_string_arg); + if (extensions.testFlag(QJSEngine::GarbageCollectionExtension)) { + globalObject->defineDefaultProperty(QStringLiteral("gc"), QV4::GlobalExtensions::method_gc); + } } diff --git a/src/qml/qml/v8/qqmlbuiltinfunctions_p.h b/src/qml/qml/v8/qqmlbuiltinfunctions_p.h index bb05376fc0..d373fb6ee6 100644 --- a/src/qml/qml/v8/qqmlbuiltinfunctions_p.h +++ b/src/qml/qml/v8/qqmlbuiltinfunctions_p.h @@ -47,6 +47,7 @@ #include #include +#include QT_BEGIN_NAMESPACE @@ -142,7 +143,7 @@ struct ConsoleObject : Object }; struct GlobalExtensions { - static void init(QQmlEngine *qmlEngine, Object *globalObject); + static void init(Object *globalObject, QJSEngine::Extensions extensions); #ifndef QT_NO_TRANSLATION static ReturnedValue method_qsTranslate(CallContext *ctx); diff --git a/src/qml/qml/v8/qv8engine.cpp b/src/qml/qml/v8/qv8engine.cpp index effc37a0eb..dae932e705 100644 --- a/src/qml/qml/v8/qv8engine.cpp +++ b/src/qml/qml/v8/qv8engine.cpp @@ -174,7 +174,10 @@ const QSet &QV8Engine::illegalNames() const void QV8Engine::initializeGlobal() { QV4::Scope scope(m_v4Engine); - QV4::GlobalExtensions::init(m_engine, m_v4Engine->globalObject); + QV4::GlobalExtensions::init(m_v4Engine->globalObject, QJSEngine::AllExtensions); + + QV4::ScopedObject qt(scope, m_v4Engine->memoryManager->allocObject(m_engine)); + m_v4Engine->globalObject->defineDefaultProperty(QStringLiteral("Qt"), qt); QQmlLocale::registerStringLocaleCompare(m_v4Engine); QQmlDateExtension::registerExtension(m_v4Engine); -- cgit v1.2.3