From 8c9b01adf2fed485aae36356c6d622f300bdc7e8 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 10 Feb 2016 11:04:34 +0100 Subject: Doc: add docs for new QWebEnginePage::runJavaScript() variants Change-Id: Ib84434c86c8003024fd22c2891413afbad33941e Reviewed-by: Allan Sandfeld Jensen --- .../doc/src/qwebenginepage_lgpl.qdoc | 64 +++++++++++++++++----- 1 file changed, 51 insertions(+), 13 deletions(-) (limited to 'src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc') diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc index a65d6011f..97b4159b1 100644 --- a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc +++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc @@ -61,6 +61,14 @@ have been loaded completely, independent of script execution or page rendering. Its argument, either \c true or \c false, indicates whether or not the load operation succeeded. + + Scripts can be executed on the web page by using runJavaScript(), 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. + QWebEngineScript::ScriptWorldId provides some predefined IDs for this purpose. Using the + \c runJavaScript() version without the world ID is the same as running the script in the + \c MainWorld. */ /*! @@ -621,32 +629,62 @@ \brief the zoom factor for the main frame */ +/*! + \fn void QWebEnginePage::runJavaScript(const QString& scriptSource, quint32 worldId, FunctorOrLambda 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. Using the + \e runJavaScript() versions without the world ID is the same as running the script 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, + and it is expected to take a QVariant parameter. For example: + + \code + page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); }); + \endcode + + \warning Do not execute lengthy routines in the callback function, because it might block the + rendering of the web engine page. + + See scripts() for an alternative API to inject scripts. + + \sa QWebEngineScript::ScriptWorldId +*/ + +/*! + \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, quint32 worldId) + \since 5.7 + \overload runJavaScript() + + This convenience function runs the JavaScript code contained in \a scriptSource in the world + specified by \a worldId. +*/ + /*! \fn void QWebEnginePage::runJavaScript(const QString& scriptSource) \overload runJavaScript() - This convenience function runs the JavaScript code contained in \a scriptSource. + This convenience function runs the JavaScript code contained in \a scriptSource in the same + world as other scripts that are part of the loaded site. + + \sa QWebEngineScript::MainWorld */ /*! \fn void QWebEnginePage::runJavaScript(const QString& scriptSource, FunctorOrLambda resultCallback) + \overload runJavaScript() Runs the JavaScript code contained in \a scriptSource. - The script will run in the same \e world as other scripts that are part of the loaded site. + The script will run in the same world as other scripts that are part of the loaded site. - When the script has been executed, \a resultCallback is called with the result of the last executed statement. - \a resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a - QVariant parameter. For example: + When the script has been executed, \a resultCallback is called with the result of the last + executed statement. - \code - page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); }); - \endcode - - \warning Do not execute lengthy routines in the callback function, because it might block the - rendering of the web engine page. - - See scripts() for an alternative API to inject scripts. + \sa QWebEngineScript::MainWorld */ /*! -- cgit v1.2.3