From 002e47692b071400e8917a1604b37039860f86c2 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 11 Jul 2019 11:47:30 +0200 Subject: Doc: Edit docs on script injection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task-number: QTBUG-76489 Change-Id: If489ebed802d273b0015bc6cfc190d948c4896e3 Reviewed-by: Jüri Valdmann --- src/webengine/doc/src/webengineview_lgpl.qdoc | 5 +++-- src/webenginewidgets/api/qwebenginepage.cpp | 2 +- src/webenginewidgets/api/qwebengineprofile.cpp | 3 ++- src/webenginewidgets/api/qwebenginescript.cpp | 2 ++ .../api/qwebenginescriptcollection.cpp | 2 ++ src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc | 19 +++++++++++-------- 6 files changed, 21 insertions(+), 12 deletions(-) diff --git a/src/webengine/doc/src/webengineview_lgpl.qdoc b/src/webengine/doc/src/webengineview_lgpl.qdoc index d790cccea..6194a800e 100644 --- a/src/webengine/doc/src/webengineview_lgpl.qdoc +++ b/src/webengine/doc/src/webengineview_lgpl.qdoc @@ -396,7 +396,7 @@ runJavaScript("document.title", function(result) { console.log(result); }); \endcode - Only "plain data" can be returned from JavaScript as the result value. + Only plain data can be returned from JavaScript as the result value. Supported data types include all of the JSON data types as well as, for example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for example, \c{Function} and \c{Promise}. @@ -407,7 +407,8 @@ \warning Do not execute lengthy routines in the callback function, because it might block the rendering of the web content. - See WebEngineView::userScripts for an alternative API to inject scripts. + For more information about injecting scripts, see \l {Script Injection}. + For an alternative way to inject scripts, see WebEngineView::userScripts. */ /*! diff --git a/src/webenginewidgets/api/qwebenginepage.cpp b/src/webenginewidgets/api/qwebenginepage.cpp index 78b89a53c..055047341 100644 --- a/src/webenginewidgets/api/qwebenginepage.cpp +++ b/src/webenginewidgets/api/qwebenginepage.cpp @@ -2183,7 +2183,7 @@ void QWebEnginePage::runJavaScript(const QString& scriptSource, quint32 worldId, In addition, a page might also execute scripts added through QWebEngineProfile::scripts(). - \sa QWebEngineScriptCollection, QWebEngineScript + \sa QWebEngineScriptCollection, QWebEngineScript, {Script Injection} */ QWebEngineScriptCollection &QWebEnginePage::scripts() diff --git a/src/webenginewidgets/api/qwebengineprofile.cpp b/src/webenginewidgets/api/qwebengineprofile.cpp index c8aafa0e8..6644af3ff 100644 --- a/src/webenginewidgets/api/qwebengineprofile.cpp +++ b/src/webenginewidgets/api/qwebengineprofile.cpp @@ -593,7 +593,8 @@ bool QWebEngineProfile::visitedLinksContainsUrl(const QUrl &url) const Returns the collection of scripts that are injected into all pages that share this profile. - \sa QWebEngineScriptCollection, QWebEngineScript, QWebEnginePage::scripts() + \sa QWebEngineScriptCollection, QWebEngineScript, QWebEnginePage::scripts(), + {Script Injection} */ QWebEngineScriptCollection *QWebEngineProfile::scripts() const { diff --git a/src/webenginewidgets/api/qwebenginescript.cpp b/src/webenginewidgets/api/qwebenginescript.cpp index d1e996b3a..af6b9aa8d 100644 --- a/src/webenginewidgets/api/qwebenginescript.cpp +++ b/src/webenginewidgets/api/qwebenginescript.cpp @@ -67,6 +67,8 @@ using QtWebEngineCore::UserScript; Use QWebEnginePage::scripts() and QWebEngineProfile::scripts() to access the collection of scripts associated with a single page or a number of pages sharing the same profile. + + \sa {Script Injection} */ /*! \enum QWebEngineScript::InjectionPoint diff --git a/src/webenginewidgets/api/qwebenginescriptcollection.cpp b/src/webenginewidgets/api/qwebenginescriptcollection.cpp index 5ef0ffd44..8cbeeb804 100644 --- a/src/webenginewidgets/api/qwebenginescriptcollection.cpp +++ b/src/webenginewidgets/api/qwebenginescriptcollection.cpp @@ -55,6 +55,8 @@ using QtWebEngineCore::UserScript; Use QWebEnginePage::scripts() and QWebEngineProfile::scripts() to access the collection of scripts associated with a single page or a number of pages sharing the same profile. + + \sa {Script Injection} */ /*! diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc index 15e57e904..2bf4d0413 100644 --- a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc +++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc @@ -759,10 +759,15 @@ \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, const QWebEngineCallback &resultCallback) \since 5.7 - Runs the JavaScript code contained in \a scriptSource in the world specified by \a worldId. - The world ID values are the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0 - and \c 256. Using the \e runJavaScript() versions without the world ID is the same as running the - script in the \c MainWorld. + Runs the JavaScript code contained in \a scriptSource without checking + whether the DOM of the page has been constructed. If you need more + control over how the script is run, consider using \l scripts() instead. + + To avoid conflicts with other scripts executed on the page, the world in + which the script is run is specified by \a worldId. The world ID values are + the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0 + and \c 256. If you leave out the \c world ID, the script is run in the + \c MainWorld. When the script has been executed, \a resultCallback is called with the result of the last executed statement. \c resultCallback can be any of a function pointer, a functor or a lambda, @@ -772,7 +777,7 @@ page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); }); \endcode - Only "plain data" can be returned from JavaScript as the result value. + Only plain data can be returned from JavaScript as the result value. Supported data types include all of the JSON data types as well as, for example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for example, \c{Function} and \c{Promise}. @@ -784,9 +789,7 @@ during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. - See scripts() for an alternative API to inject scripts. - - \sa QWebEngineScript::ScriptWorldId + \sa scripts(), QWebEngineScript::ScriptWorldId, {Script Injection} */ /*! -- cgit v1.2.3