From bb84cf18e742657e0bb8ac52ca7776b76cd19fb6 Mon Sep 17 00:00:00 2001 From: Pierre Rossi Date: Wed, 3 Jun 2015 15:31:24 +0200 Subject: Add documentation for QWebEngineScript and QWebEngineScriptCollection Change-Id: I494f31a6b4efc038a96ca68142fa2f9a56d53802 Reviewed-by: Andras Becsi --- src/webenginewidgets/api/qwebenginescript.cpp | 113 +++++++++++++++++++++++++- 1 file changed, 112 insertions(+), 1 deletion(-) (limited to 'src/webenginewidgets/api/qwebenginescript.cpp') diff --git a/src/webenginewidgets/api/qwebenginescript.cpp b/src/webenginewidgets/api/qwebenginescript.cpp index e2f267330..e834c5067 100644 --- a/src/webenginewidgets/api/qwebenginescript.cpp +++ b/src/webenginewidgets/api/qwebenginescript.cpp @@ -41,10 +41,63 @@ using QtWebEngineCore::UserScript; +/*! + \class QWebEngineScript + \inmodule QtWebEngineWidgets + \since 5.5 + \brief The QWebEngineScript class encapsulates a JavaScript program. + \preliminary + + QWebEngineScript allows the programatic injection of so called "user scripts" in the + javascript engine at different points, determined by injectionPoint(), during the loading of web contents. + + Scripts can be executed either in the main javascript 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 a function defined in one world are not accessible from a different one. + ScriptWorldId provides some predefined ids for this purpose. + +*/ +/*! + \enum QWebEngineScript::InjectionPoint + + This enum describes the timing for when the script injection should happen. + + \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 DOMContentLoaded + event firing in JavaScript. + \value Deferred The script will run when the page load finishes, or 500ms after the document is ready, whichever + comes first. + +*/ +/*! + \enum QWebEngineScript::ScriptWorldId + + This enum provides pre defined world ids for isolating user scripts into different worlds. + + \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 thumbs, if that functionality is exposed to the application users, each individual script + should probably get its own isolated world. + +*/ + +/*! + * \brief QWebEngineScript::QWebEngineScript + * + * Constructs a null script. + */ + QWebEngineScript::QWebEngineScript() : d(new UserScript) { } +/*! + * \brief QWebEngineScript::isNull + * \return \c true is the script is null, \c false otherwise. + */ QWebEngineScript::QWebEngineScript(const QWebEngineScript &other) : d(other.d) @@ -66,11 +119,24 @@ bool QWebEngineScript::isNull() const return d->isNull(); } +/*! + * \brief QWebEngineScript::name + * \return The name of the script. Can be useful to retrieve a given script from a QWebEngineScriptCollection. + * + * \sa QWebEngineScriptCollection::findScript(), QWebEngineScriptCollection::findScripts() + */ + QString QWebEngineScript::name() const { return d->name(); } +/*! + * \brief QWebEngineScript::setName + * \param scriptName + * + * Sets the script name to \a scriptName. + */ void QWebEngineScript::setName(const QString &scriptName) { if (scriptName == name()) @@ -78,11 +144,20 @@ void QWebEngineScript::setName(const QString &scriptName) d->setName(scriptName); } +/*! + * \brief QWebEngineScript::sourceCode + * \return the source of the script. + */ QString QWebEngineScript::sourceCode() const { return d->sourceCode(); } +/*! + * \brief QWebEngineScript::setSourceCode + * \param scriptSource + * Sets the script source to \a scriptSource. + */ void QWebEngineScript::setSourceCode(const QString &scriptSource) { if (scriptSource == sourceCode()) @@ -94,11 +169,24 @@ ASSERT_ENUMS_MATCH(QWebEngineScript::Deferred, UserScript::AfterLoad) ASSERT_ENUMS_MATCH(QWebEngineScript::DocumentReady, UserScript::DocumentLoadFinished) ASSERT_ENUMS_MATCH(QWebEngineScript::DocumentCreation, UserScript::DocumentElementCreation) +/*! + * \brief QWebEngineScript::injectionPoint + * \return the point in the loading process at which the script will be executed. + * The default value is QWebEngineScript::Deferred. + * + * \sa setInjectionPoint + */ QWebEngineScript::InjectionPoint QWebEngineScript::injectionPoint() const { return static_cast(d->injectionPoint()); } - +/*! + * \brief QWebEngineScript::setInjectionPoint + * \param p + * Sets the point at which to execute the script to be \p. + * + * \sa QWebEngineScript::InjectionPoint + */ void QWebEngineScript::setInjectionPoint(QWebEngineScript::InjectionPoint p) { if (p == injectionPoint()) @@ -106,11 +194,20 @@ void QWebEngineScript::setInjectionPoint(QWebEngineScript::InjectionPoint p) d->setInjectionPoint(static_cast(p)); } +/*! + * \brief QWebEngineScript::worldId + * \return the world id defining which world the script is executed in. + */ quint32 QWebEngineScript::worldId() const { return d->worldId(); } +/*! + * \brief QWebEngineScript::setWorldId + * \param id + * Sets the world id of the isolated world to use when running this script. + */ void QWebEngineScript::setWorldId(quint32 id) { if (id == d->worldId()) @@ -118,11 +215,20 @@ void QWebEngineScript::setWorldId(quint32 id) d->setWorldId(id); } +/*! + * \brief QWebEngineScript::runsOnSubFrames + * \return \c true if the script is executed on every frame in the page, \c false if it is only ran for the main frame. + */ bool QWebEngineScript::runsOnSubFrames() const { return d->runsOnSubFrames(); } +/*! + * \brief QWebEngineScript::setRunsOnSubFrames + * \param on + * Sets whether or not the script is executed on sub frames in addition to the main frame. + */ void QWebEngineScript::setRunsOnSubFrames(bool on) { if (runsOnSubFrames() == on) @@ -130,6 +236,11 @@ void QWebEngineScript::setRunsOnSubFrames(bool on) d->setRunsOnSubFrames(on); } +/*! + * \brief QWebEngineScript::operator == + * \param other + * \return \c true if this QWebEngineScript is equal to \a other, otherwise returns \c false. + */ bool QWebEngineScript::operator==(const QWebEngineScript &other) const { return d == other.d || *d == *(other.d); -- cgit v1.2.3