diff --git a/src/webenginewidgets/api/qwebenginescript.cpp b/src/webenginewidgets/api/qwebenginescript.cpp
index e2f2673306d5a05ea17bff59210efa22c83b12d9..e834c5067ae928819fa18b8a92dfcec858d745cf 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<QWebEngineScript::InjectionPoint>(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<UserScript::InjectionPoint>(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);
diff --git a/src/webenginewidgets/api/qwebenginescriptcollection.cpp b/src/webenginewidgets/api/qwebenginescriptcollection.cpp
index 2f1f31b0ee2ac07f0458b51084922b0366e9cd00..21cb0d05e162dd880cf9bc087e12423117ebb2b6 100644
--- a/src/webenginewidgets/api/qwebenginescriptcollection.cpp
+++ b/src/webenginewidgets/api/qwebenginescriptcollection.cpp
@@ -41,6 +41,14 @@
using QtWebEngineCore::UserScript;
+/*!
+ \class QWebEngineScriptCollection
+ \inmodule QtWebEngineWidgets
+ \since 5.5
+ \brief The QWebEngineScriptCollection class represents a collection of user scripts.
+
+*/
+
QWebEngineScriptCollection::QWebEngineScriptCollection(QWebEngineScriptCollectionPrivate *collectionPrivate)
:d(collectionPrivate)
{
@@ -50,31 +58,67 @@ QWebEngineScriptCollection::~QWebEngineScriptCollection()
{
}
+/*!
+ * \brief QWebEngineScriptCollection::count
+ * \return the number of elements in the collection.
+ */
+
int QWebEngineScriptCollection::count() const
{
return d->count();
}
+/*!
+ * \brief QWebEngineScriptCollection::contains
+ * \param value
+ * \return \c true if the collection contains an occurrence of \a value; otherwise returns false.
+ */
+
bool QWebEngineScriptCollection::contains(const QWebEngineScript &value) const
{
return d->contains(value);
}
+/*!
+ * \brief QWebEngineScriptCollection::findScript
+ * \param name
+ * \return the first script found in collection the name property of which is \a name, or a null QWebEngineScript if none was found.
+ * \note the order in which the script collection is traversed is undefined, which means this should be used when the unicity is
+ * guaranteed at the application level.
+ * \sa findScripts()
+ */
+
QWebEngineScript QWebEngineScriptCollection::findScript(const QString &name) const
{
return d->find(name);
}
+/*!
+ * \brief QWebEngineScriptCollection::findScripts
+ * \param name
+ * \return the list of scripts in the collection the name property of which is \a name, or an empty list if none was found.
+ */
+
QList<QWebEngineScript> QWebEngineScriptCollection::findScripts(const QString &name) const
{
return d->toList(name);
}
-
+/*!
+ * \brief QWebEngineScriptCollection::insert
+ * \param s
+ *
+ * Inserts script \c s into the collection.
+ */
void QWebEngineScriptCollection::insert(const QWebEngineScript &s)
{
d->insert(s);
}
-
+/*!
+ * \brief QWebEngineScriptCollection::insert
+ * \param list
+ *
+ * Inserts scripts \c list into the collection.
+ */
void QWebEngineScriptCollection::insert(const QList<QWebEngineScript> &list)
{
d->reserve(list.size());
@@ -82,16 +126,30 @@ void QWebEngineScriptCollection::insert(const QList<QWebEngineScript> &list)
d->insert(s);
}
+/*!
+ * \brief QWebEngineScriptCollection::remove
+ * \param script
+ * Removes \a script from the collection, if it is present.
+ * \return \c true if the script was found and successfully removed from the collection, \c false otherwise.
+ */
bool QWebEngineScriptCollection::remove(const QWebEngineScript &script)
{
return d->remove(script);
}
+/*!
+ * \brief QWebEngineScriptCollection::clear
+ * Removes all scripts from this collection.
+ */
void QWebEngineScriptCollection::clear()
{
d->clear();
}
+/*!
+ * \brief QWebEngineScriptCollection::toList
+ * \return a QList with the values of the scripts used in this collection.
+ */
QList<QWebEngineScript> QWebEngineScriptCollection::toList() const
{
return d->toList();