From 9f6bd308cc87dc9cbde527abefc2931379754456 Mon Sep 17 00:00:00 2001 From: Anmol Gautam Date: Thu, 5 Jul 2018 12:15:14 +0530 Subject: [PATCH] Added documentation for i18n and UserScript QML API --- src/lib/plugins/qml/api/i18n/qmli18n.cpp | 6 +++ src/lib/plugins/qml/api/i18n/qmli18n.h | 3 ++ .../qml/api/userscript/qmluserscript.h | 54 ++++++++++++++++--- .../qml/api/userscript/qmluserscripts.cpp | 30 +++++++++++ .../qml/api/userscript/qmluserscripts.h | 12 +++++ 5 files changed, 99 insertions(+), 6 deletions(-) diff --git a/src/lib/plugins/qml/api/i18n/qmli18n.cpp b/src/lib/plugins/qml/api/i18n/qmli18n.cpp index 5e6e6a2ab..ef1da46e5 100644 --- a/src/lib/plugins/qml/api/i18n/qmli18n.cpp +++ b/src/lib/plugins/qml/api/i18n/qmli18n.cpp @@ -37,11 +37,17 @@ void QmlI18n::initTranslations() textdomain(domain.toUtf8()); } +/** + * @brief wrapper for gettext function + */ QString QmlI18n::i18n(const QString &string) { return QString::fromUtf8(gettext(string.toUtf8())); } +/** + * @brief wrapper for ngettext function + */ QString QmlI18n::i18np(const QString &string1, const QString &string2, int count) { return QString::fromUtf8(ngettext(string1.toUtf8(), string2.toUtf8(), count)); diff --git a/src/lib/plugins/qml/api/i18n/qmli18n.h b/src/lib/plugins/qml/api/i18n/qmli18n.h index e6d28e1cb..dc82e3af8 100644 --- a/src/lib/plugins/qml/api/i18n/qmli18n.h +++ b/src/lib/plugins/qml/api/i18n/qmli18n.h @@ -24,6 +24,9 @@ // fatal error C1189: #error : The C++ Standard Library forbids macroizing keywords #undef inline +/** + * @brief The class exposing GNU Gettext to QML + */ class QmlI18n : public QObject { Q_OBJECT diff --git a/src/lib/plugins/qml/api/userscript/qmluserscript.h b/src/lib/plugins/qml/api/userscript/qmluserscript.h index dcf20d180..f4772942f 100644 --- a/src/lib/plugins/qml/api/userscript/qmluserscript.h +++ b/src/lib/plugins/qml/api/userscript/qmluserscript.h @@ -22,25 +22,52 @@ #include #include +/** + * @brief The class exposing QWebEngineScript to QML + */ class FALKON_EXPORT QmlUserScript : public QObject { Q_OBJECT + /** + * @brief Checks if the UserScript is null + */ Q_PROPERTY(bool null READ null CONSTANT) + /** + * @brief Name of the UserScript + */ Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged) + /** + * @brief Checks if the UserScript runs on sub frames + */ Q_PROPERTY(bool runsOnSubFrames READ runsOnSubFrames WRITE setRunsOnSubFrames NOTIFY runsOnSubFramesChanged) + /** + * @brief WorldId of the UserScript + */ Q_PROPERTY(int worldId READ worldId WRITE setWorldId NOTIFY worldIdChanged) + /** + * @brief Source code of the UserScript + */ Q_PROPERTY(QString sourceCode READ sourceCode WRITE setSourceCode NOTIFY sourceCodeChanged) + /** + * @brief Injection point of the UserScript + */ Q_PROPERTY(int injectionPoint READ injectionPoint WRITE setInjectionPoint NOTIFY injectionPointChanged) public: + /** + * @brief The enum exposing QWebEngineScript::InjectionPoint + */ enum InjectionPoint { - DocumentCreation = QWebEngineScript::DocumentCreation, - DocumentReady = QWebEngineScript::DocumentReady, - Deferred = QWebEngineScript::Deferred + DocumentCreation = QWebEngineScript::DocumentCreation, //!< Represents QWebEngineScript::DocumentCreation + DocumentReady = QWebEngineScript::DocumentReady, //!< Represents QWebEngineScript::DocumentReady, + Deferred = QWebEngineScript::Deferred //!< Represents QWebEngineScript::Deferred }; + /** + * @brief The enum wrapping QWebEngineScript::ScriptWorldId + */ enum ScriptWorldId { - MainWorld = QWebEngineScript::MainWorld, - ApplicationWorld = QWebEngineScript::ApplicationWorld, - UserWorld = QWebEngineScript::UserWorld + MainWorld = QWebEngineScript::MainWorld, //!< Represents QWebEngineScript::MainWorld + ApplicationWorld = QWebEngineScript::ApplicationWorld, //!< Represents QWebEngineScript::ApplicationWorld + UserWorld = QWebEngineScript::UserWorld //! < Represents QWebEngineScript::UserWorld }; Q_ENUMS(InjectionPoint) Q_ENUMS(ScriptWorldId) @@ -49,10 +76,25 @@ public: QWebEngineScript webEngineScript() const; void setWebEngineScript(const QWebEngineScript &script); Q_SIGNALS: + /** + * @brief The signal emitted when the script name is changed + */ void nameChanged(const QString &name); + /** + * @brief The signal emitted when runsOnSubFrame property of the script is changed + */ void runsOnSubFramesChanged(bool runsOnSubFrames); + /** + * @brief The signal emitted when worldId property of the script is changed + */ void worldIdChanged(int worldId); + /** + * @brief The signal emitted when source code of the script is changed + */ void sourceCodeChanged(const QString &sourceCode); + /** + * @brief The signal emitted when injectionPoint property of the script is changed + */ void injectionPointChanged(int injectionPoint); private: QWebEngineScript m_webEngineScript; diff --git a/src/lib/plugins/qml/api/userscript/qmluserscripts.cpp b/src/lib/plugins/qml/api/userscript/qmluserscripts.cpp index 8a19c4aff..b46b1dce9 100644 --- a/src/lib/plugins/qml/api/userscript/qmluserscripts.cpp +++ b/src/lib/plugins/qml/api/userscript/qmluserscripts.cpp @@ -51,6 +51,11 @@ QList QmlUserScripts::toQObjectList(QList list) con return userScriptList; } +/** + * @brief Checks if the script is in collection + * @param object of type QmlUserScript + * @return true if the the script in in collection, else false + */ bool QmlUserScripts::contains(QObject *object) const { QmlUserScript *userScript = qobject_cast(object); @@ -61,6 +66,11 @@ bool QmlUserScripts::contains(QObject *object) const return mApp->webProfile()->scripts()->contains(webEngineScript); } +/** + * @brief Finds a script in collection by name + * @param name of the script + * @return object of type QmlUserScript, representing the script of given name + */ QObject *QmlUserScripts::findScript(const QString &name) const { QWebEngineScript webEngineScript = mApp->webProfile()->scripts()->findScript(name); @@ -69,12 +79,20 @@ QObject *QmlUserScripts::findScript(const QString &name) const return qmlUserScript; } +/** + * @brief Finds all scripts in collection by a given name + * @return list of objects, each of type QmlUserScript, representing the script of given name + */ QList QmlUserScripts::findScripts(const QString &name) const { QList list = mApp->webProfile()->scripts()->findScripts(name); return toQObjectList(list); } +/** + * @brief Inserts a script into collection + * @param object of type QmlUserScript + */ void QmlUserScripts::insert(QObject *object) const { QmlUserScript *userScript = qobject_cast(object); @@ -85,6 +103,10 @@ void QmlUserScripts::insert(QObject *object) const mApp->webProfile()->scripts()->insert(webEngineScript); } +/** + * @brief Inserts a list of scripts into collection + * @param list of objects, each of type QmlUserScript + */ void QmlUserScripts::insert(const QList &list) const { for (QObject *object : list) { @@ -97,6 +119,10 @@ void QmlUserScripts::insert(const QList &list) const } } +/** + * @brief Removes a script from collection + * @param object of type QmlUserScript + */ void QmlUserScripts::remove(QObject *object) const { QmlUserScript *userScript = qobject_cast(object); @@ -107,6 +133,10 @@ void QmlUserScripts::remove(QObject *object) const mApp->webProfile()->scripts()->remove(webEngineScript); } +/** + * @brief Gets all the scripts of the collection + * @return list of objects, each of type QmlUserScript + */ QList QmlUserScripts::toList() const { QList list = mApp->webProfile()->scripts()->toList(); diff --git a/src/lib/plugins/qml/api/userscript/qmluserscripts.h b/src/lib/plugins/qml/api/userscript/qmluserscripts.h index c34444e43..1d8827977 100644 --- a/src/lib/plugins/qml/api/userscript/qmluserscripts.h +++ b/src/lib/plugins/qml/api/userscript/qmluserscripts.h @@ -20,11 +20,23 @@ #include "qmluserscript.h" #include +/** + * @brief The class exposing QWebEngineScriptCollection to QML + */ class FALKON_EXPORT QmlUserScripts : public QObject { Q_OBJECT + /** + * @brief Number of elements in the collection + */ Q_PROPERTY(int count READ count CONSTANT) + /** + * @brief Size of the collection + */ Q_PROPERTY(int size READ size CONSTANT) + /** + * @brief Checks if the collection is empty + */ Q_PROPERTY(bool empty READ empty CONSTANT) public: explicit QmlUserScripts(QObject *parent = nullptr);