diff options
author | Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> | 2016-01-20 12:02:15 +0100 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> | 2016-01-20 11:27:34 +0000 |
commit | 28fddd86f3c8b0b3a9c8f3bc7998fc75c1cda5ee (patch) | |
tree | 9135f0c693a47a97be912329d2d67e26985d12bb | |
parent | f32f4af43c207072e6bb175b9e63e0d3ebc2cc1d (diff) | |
download | qtwebengine-28fddd86f3c8b0b3a9c8f3bc7998fc75c1cda5ee.tar.gz |
Doc: add documentation for the WebEngineScript item
Change-Id: Ice1b0a403686b4a280b2709a79fe2ed18ace3ab6
Reviewed-by: Joerg Bornemann <joerg.bornemann@theqtcompany.com>
-rw-r--r-- | src/webengine/api/qquickwebenginescript.cpp | 68 | ||||
-rw-r--r-- | src/webengine/doc/src/qquickwebengineview_lgpl.qdoc | 2 |
2 files changed, 68 insertions, 2 deletions
diff --git a/src/webengine/api/qquickwebenginescript.cpp b/src/webengine/api/qquickwebenginescript.cpp index 71dad701f..7a545e456 100644 --- a/src/webengine/api/qquickwebenginescript.cpp +++ b/src/webengine/api/qquickwebenginescript.cpp @@ -46,6 +46,27 @@ using QtWebEngineCore::UserScript; +/*! + \qmltype WebEngineScript + \instantiates QQuickWebEngineScript + \inqmlmodule QtWebEngine + \since QtWebEngine 1.1 + \brief Enables the programmatic injection of scripts in the JavaScript engine. + + The WebEngineScript type enables the programmatic injection of so called \e {user scripts} in + the JavaScript engine at different points, determined by injectionPoint, during the loading of + web content. + + Scripts can be executed either in the main JavaScript \e world, along with the rest of the + JavaScript coming from the web contents, or in their own isolated world. While the DOM of the + page can be accessed from any world, JavaScript variables of a function defined in one world are + not accessible from a different one. The worldId property provides some predefined IDs for this + purpose. + + Use \l{WebEngineView::userScripts}{WebEngineView.userScripts} to access a list of scripts + attached to the web view. +*/ + QQuickWebEngineScript::QQuickWebEngineScript() : d_ptr(new QQuickWebEngineScriptPrivate) { @@ -79,6 +100,12 @@ QString QQuickWebEngineScript::toString() const return ret; } +/*! + \qmlproperty QString WebEngineScript::name + + The name of the script. Can be useful to retrieve a particular script from + \l{WebEngineView::userScripts}{WebEngineView.userScripts}. +*/ QString QQuickWebEngineScript::name() const { Q_D(const QQuickWebEngineScript); @@ -91,7 +118,7 @@ QString QQuickWebEngineScript::name() const This property holds the remote source location of the user script (if any). Unlike \l sourceCode, this property allows referring to user scripts that - are not already loaded in memory, for instance, when stored on disk. + are not already loaded in memory, for instance, when stored on disk. Setting this property will change the \l sourceCode of the script. @@ -122,20 +149,57 @@ ASSERT_ENUMS_MATCH(QQuickWebEngineScript::Deferred, UserScript::AfterLoad) ASSERT_ENUMS_MATCH(QQuickWebEngineScript::DocumentReady, UserScript::DocumentLoadFinished) ASSERT_ENUMS_MATCH(QQuickWebEngineScript::DocumentCreation, UserScript::DocumentElementCreation) +/*! + \qmlproperty enumeration WebEngineScript::injectionPoint + + The point in the loading process at which the script will be executed. + The default value is \c Deferred. + + \value DocumentCreation + The script will be executed as soon as the document is created. This is not suitable for + any DOM operation. + \value DocumentReady + The script will run as soon as the DOM is ready. This is equivalent to the + \c DOMContentLoaded event firing in JavaScript. + \value Deferred + The script will run when the page load finishes, or 500 ms after the document is ready, + whichever comes first. +*/ QQuickWebEngineScript::InjectionPoint QQuickWebEngineScript::injectionPoint() const { Q_D(const QQuickWebEngineScript); return static_cast<QQuickWebEngineScript::InjectionPoint>(d->coreScript.injectionPoint()); } - +/*! + \qmlproperty enumeration WebEngineScript::worldId + + The world ID defining which isolated world the script is executed in. + + \value MainWorld + The world used by the page's web contents. It can be useful in order to expose custom + functionality to web contents in certain scenarios. + \value ApplicationWorld + The default isolated world used for application level functionality implemented in + JavaScript. + \value UserWorld + The first isolated world to be used by scripts set by users if the application is not + making use of more worlds. As a rule of thumb, if that functionality is exposed to the + application users, each individual script should probably get its own isolated world. +*/ QQuickWebEngineScript::ScriptWorldId QQuickWebEngineScript::worldId() const { Q_D(const QQuickWebEngineScript); return static_cast<QQuickWebEngineScript::ScriptWorldId>(d->coreScript.worldId()); } +/*! + \qmlproperty int WebEngineScript::runOnSubframes + Set this property to \c true if the script is executed on every frame in the page, or \c false + if it is only ran for the main frame. + The default value is \c{false}. + */ bool QQuickWebEngineScript::runOnSubframes() const { Q_D(const QQuickWebEngineScript); diff --git a/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc b/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc index 212d9010a..f9810aafd 100644 --- a/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc +++ b/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc @@ -257,6 +257,8 @@ \readonly List of script objects attached to the view. + + \sa WebEngineScript */ /*! |