From 0404a6360198b0d28f4804591cf9c6bfe769fe4b Mon Sep 17 00:00:00 2001 From: Skycoder42 Date: Tue, 7 Aug 2018 19:55:27 +0200 Subject: [PATCH] updated qml core doc --- doc/coreapp.dox | 4 +- doc/qtmvvm.dox | 3 ++ doc/serviceregistry.dox | 5 +- src/imports/mvvmcore/plugins.qmltypes | 36 +++++++++++-- src/imports/mvvmcore/qqmlcoreapp.h | 18 +++++++ src/imports/mvvmcore/qqmlmvvmmessage.cpp | 12 ++--- src/imports/mvvmcore/qqmlmvvmmessage.h | 19 +++++-- src/imports/mvvmcore/qqmlserviceregistry.h | 60 +++++++++++++++++++--- src/mvvmcore/serviceregistry.h | 2 +- 9 files changed, 135 insertions(+), 24 deletions(-) diff --git a/doc/coreapp.dox b/doc/coreapp.dox index 8756e13..2cf42c2 100644 --- a/doc/coreapp.dox +++ b/doc/coreapp.dox @@ -133,7 +133,7 @@ consideration where neccessary. */ /*! -@fn QtMvvm::CoreApp::showDialog +@fn QtMvvm::CoreApp::showDialog(const MessageConfig &) @param config The configuration of the message to be shown @returns A message result to keep track of the shown dialog @@ -148,7 +148,7 @@ been closed. */ /*! -@fn QtMvvm::CoreApp::safeCastInputType +@fn QtMvvm::CoreApp::safeCastInputType(const QByteArray &, const QVariant &) @param type The edit type the given value is supposed to be of @param value The value to be cast to the type specified by the edit type diff --git a/doc/qtmvvm.dox b/doc/qtmvvm.dox index 096d6ce..4ea3ca9 100644 --- a/doc/qtmvvm.dox +++ b/doc/qtmvvm.dox @@ -54,8 +54,11 @@ The following list shows which classes belong to which Qt module, in alphabetica Available Types - @ref QtMvvm::MessageConfig "MessageConfig" (uncreatable) - @ref QtMvvm::MessageResult "MessageResult" (uncreatable) +- @ref QtMvvm::ProgressControl "ProgressControl" (uncreatable) - MvvmBinding - Message (singleton) +- CoreApp (singleton) +- ServiceRegistry (singleton) - @ref QtMvvm::SettingsViewModel "SettingsViewModel" (uncreatable) - @ref QtMvvm::ViewModel "ViewModel" (uncreatable) */ diff --git a/doc/serviceregistry.dox b/doc/serviceregistry.dox index 156b246..f981e25 100644 --- a/doc/serviceregistry.dox +++ b/doc/serviceregistry.dox @@ -365,14 +365,15 @@ as it is requested for the first time. It is created by calling the given `fn` f The function must return an object that implements the interface of `iid`, unless it is the id of the service itself. The arguments are passed as object list and are determined by the `injectables` parameter. That is a list of iids. When the function is called internally, the -registry will "inject" all services found by the iids as parameters of this function, comnined +registry will "inject" all services found by the iids as parameters of this function, combined to a list of objects. If the service is registered as weak, registering another service for the same iid will not throw an exception but instead discard (and delete) this one. @sa QtMvvm::registerInterface, ServiceRegistry::registerObject, -ServiceRegistry::registerPlugin, ServiceRegistry::serviceObj*/ +ServiceRegistry::registerPlugin, ServiceRegistry::serviceObj +*/ /*! @fn QtMvvm::ServiceRegistry::registerService(QByteArray, QString, QString, DestructionScope, bool) diff --git a/src/imports/mvvmcore/plugins.qmltypes b/src/imports/mvvmcore/plugins.qmltypes index a13d321..084e680 100644 --- a/src/imports/mvvmcore/plugins.qmltypes +++ b/src/imports/mvvmcore/plugins.qmltypes @@ -565,6 +565,18 @@ Module { Parameter { name: "onResult"; type: "QJSValue" } } Method { name: "getColor"; revision: 1 } + Method { + name: "showProgress" + revision: 1 + type: "QtMvvm::ProgressControl*" + Parameter { name: "title"; type: "string" } + Parameter { name: "label"; type: "string" } + Parameter { name: "maximum"; type: "int" } + Parameter { name: "minimum"; type: "int" } + Parameter { name: "allowCancel"; type: "bool" } + Parameter { name: "value"; type: "int" } + Parameter { name: "cancelText"; type: "string" } + } Method { name: "showProgress" revision: 1 @@ -617,6 +629,15 @@ Module { Parameter { name: "title"; type: "string" } } Method { name: "showProgress"; revision: 1; type: "QtMvvm::ProgressControl*" } + Method { + name: "showIndeterminateProgress" + revision: 1 + type: "QtMvvm::ProgressControl*" + Parameter { name: "title"; type: "string" } + Parameter { name: "label"; type: "string" } + Parameter { name: "allowCancel"; type: "bool" } + Parameter { name: "cancelText"; type: "string" } + } Method { name: "showIndeterminateProgress" revision: 1 @@ -639,6 +660,15 @@ Module { Parameter { name: "title"; type: "string" } } Method { name: "showIndeterminateProgress"; revision: 1; type: "QtMvvm::ProgressControl*" } + Method { + name: "showBusy" + revision: 1 + type: "QtMvvm::ProgressControl*" + Parameter { name: "title"; type: "string" } + Parameter { name: "label"; type: "string" } + Parameter { name: "allowCancel"; type: "bool" } + Parameter { name: "cancelText"; type: "string" } + } Method { name: "showBusy" revision: 1 @@ -685,18 +715,18 @@ Module { } Method { name: "registerObject" - Parameter { name: "object"; type: "QObject"; isPointer: true } + Parameter { name: "service"; type: "QObject"; isPointer: true } Parameter { name: "scope"; type: "QtMvvm::QQmlServiceRegistry::DestructionScope" } Parameter { name: "weak"; type: "bool" } } Method { name: "registerObject" - Parameter { name: "object"; type: "QObject"; isPointer: true } + Parameter { name: "service"; type: "QObject"; isPointer: true } Parameter { name: "scope"; type: "QtMvvm::QQmlServiceRegistry::DestructionScope" } } Method { name: "registerObject" - Parameter { name: "object"; type: "QObject"; isPointer: true } + Parameter { name: "service"; type: "QObject"; isPointer: true } } Method { name: "registerObject" diff --git a/src/imports/mvvmcore/qqmlcoreapp.h b/src/imports/mvvmcore/qqmlcoreapp.h index c41525d..65a3bdd 100644 --- a/src/imports/mvvmcore/qqmlcoreapp.h +++ b/src/imports/mvvmcore/qqmlcoreapp.h @@ -5,22 +5,40 @@ #include +#ifdef DOXYGEN_RUN +namespace de::skycoder42::QtMvvm::Core { + +/*! @brief A QML singleton to access some QtMvvm::CoreApp functionality + * + * @extends QtQml.QtObject + * @since 1.1 + * + * @sa QtMvvm::CoreApp + */ +class CoreApp +#else namespace QtMvvm { class QQmlCoreApp : public QObject +#endif { Q_OBJECT public: + //! @private explicit QQmlCoreApp(QObject *parent = nullptr); + //! @copydoc QtMvvm::CoreApp::showDialog Q_INVOKABLE QtMvvm::MessageResult *showDialog(const QtMvvm::MessageConfig &config); + //! @copydoc QtMvvm::CoreApp::safeCastInputType Q_INVOKABLE QVariant safeCastInputType(const QString &type, const QVariant &value); public Q_SLOTS: + //! @copydoc QtMvvm::CoreApp::show(const char *, const QVariantHash &, QPointer); void show(const QString &viewModelName, const QVariantHash ¶ms = {}, QtMvvm::ViewModel *parentViewModel = nullptr); Q_SIGNALS: + //! @copydoc QtMvvm::CoreApp::appStarted void appStarted(); }; diff --git a/src/imports/mvvmcore/qqmlmvvmmessage.cpp b/src/imports/mvvmcore/qqmlmvvmmessage.cpp index 58fb2c5..1ae2e45 100644 --- a/src/imports/mvvmcore/qqmlmvvmmessage.cpp +++ b/src/imports/mvvmcore/qqmlmvvmmessage.cpp @@ -118,23 +118,23 @@ void QtMvvm::QQmlMvvmMessage::getColor(const QJSValue &onResult, const QString & QtMvvm::getColor(title, color, argb); } -ProgressControl *QtMvvm::QQmlMvvmMessage::showProgress(const QString &title, const QString &label, int maximum, int minimum, bool allowCancel, int value) +ProgressControl *QtMvvm::QQmlMvvmMessage::showProgress(const QString &title, const QString &label, int maximum, int minimum, bool allowCancel, int value, const QString &cancelText) { - auto control = QtMvvm::showProgress(title, label, maximum, minimum, allowCancel, value); + auto control = QtMvvm::showProgress(title, label, maximum, minimum, allowCancel, value, cancelText); QQmlEngine::setObjectOwnership(control, QQmlEngine::JavaScriptOwnership); return control; } -ProgressControl *QtMvvm::QQmlMvvmMessage::showIndeterminateProgress(const QString &title, const QString &label, bool allowCancel) +ProgressControl *QtMvvm::QQmlMvvmMessage::showIndeterminateProgress(const QString &title, const QString &label, bool allowCancel, const QString &cancelText) { - auto control = QtMvvm::showIndeterminateProgress(title, label, allowCancel); + auto control = QtMvvm::showIndeterminateProgress(title, label, allowCancel, cancelText); QQmlEngine::setObjectOwnership(control, QQmlEngine::JavaScriptOwnership); return control; } -ProgressControl *QtMvvm::QQmlMvvmMessage::showBusy(const QString &title, const QString &label, bool allowCancel) +ProgressControl *QtMvvm::QQmlMvvmMessage::showBusy(const QString &title, const QString &label, bool allowCancel, const QString &cancelText) { - auto control = QtMvvm::showBusy(title, label, allowCancel); + auto control = QtMvvm::showBusy(title, label, allowCancel, cancelText); QQmlEngine::setObjectOwnership(control, QQmlEngine::JavaScriptOwnership); return control; } diff --git a/src/imports/mvvmcore/qqmlmvvmmessage.h b/src/imports/mvvmcore/qqmlmvvmmessage.h index c1bb28c..017a802 100644 --- a/src/imports/mvvmcore/qqmlmvvmmessage.h +++ b/src/imports/mvvmcore/qqmlmvvmmessage.h @@ -19,7 +19,7 @@ namespace de::skycoder42::QtMvvm::Core { * * @sa QtMvvm::MessageConfig, QtMvvm::CoreApp::showDialog */ -class Message : public QtObject +class Message #else namespace QtMvvm { @@ -110,23 +110,34 @@ public Q_SLOTS: const QStringList &supportedMimeTypes = {}, const QUrl &dir = {}); + //! @brief A QML version of the QtMvvm::getColor method + //! @copydoc QtMvvm::getColor(const std::function &, const QString &, const QColor &, bool) QTMVVM_REVISION_1 static void getColor(const QJSValue &onResult = {}, const QString &title = {}, const QColor &color = {}, bool argb = false); + //! @brief A QML version of the QtMvvm::showProgress method + //! @copydoc QtMvvm::showProgress(const QString &, const QString &, int, int, bool, int, const QString &) QTMVVM_REVISION_1 static QtMvvm::ProgressControl *showProgress(const QString &title = {}, const QString &label = {}, int maximum = 100, int minimum = 0, bool allowCancel = true, - int value = 0); + int value = 0, + const QString &cancelText = {}); + //! @brief A QML version of the QtMvvm::showIndeterminateProgress method + //! @copydoc QtMvvm::showIndeterminateProgress(const QString &, const QString &, bool, const QString &) QTMVVM_REVISION_1 static QtMvvm::ProgressControl *showIndeterminateProgress(const QString &title = {}, const QString &label = {}, - bool allowCancel = true); + bool allowCancel = true, + const QString &cancelText = {}); + //! @brief A QML version of the QtMvvm::showBusy method + //! @copydoc QtMvvm::showBusy(const QString &, const QString &, bool, const QString &) QTMVVM_REVISION_1 static QtMvvm::ProgressControl *showBusy(const QString &title = {}, const QString &label = {}, - bool allowCancel = true); + bool allowCancel = true, + const QString &cancelText = {}); #ifndef DOXYGEN_RUN #undef static diff --git a/src/imports/mvvmcore/qqmlserviceregistry.h b/src/imports/mvvmcore/qqmlserviceregistry.h index 66bb452..dd8090b 100644 --- a/src/imports/mvvmcore/qqmlserviceregistry.h +++ b/src/imports/mvvmcore/qqmlserviceregistry.h @@ -8,36 +8,84 @@ #include #include +#ifdef DOXYGEN_RUN +namespace de::skycoder42::QtMvvm::Core { + +/*! @brief A QML singleton to access some QtMvvm::ServiceRegistry functionality + * + * @extends QtQml.QtObject + * @since 1.1 + * + * @sa QtMvvm::ServiceRegistry + */ +class ServiceRegistry +#else namespace QtMvvm { class QQmlServiceRegistry : public QObject +#endif { Q_OBJECT public: + //! @copybrief QtMvvm::ServiceRegistry enum DestructionScope { - DestroyOnAppQuit = ServiceRegistry::DestroyOnAppQuit, - DestroyOnAppDestroy = ServiceRegistry::DestroyOnAppDestroy, - DestroyOnRegistryDestroy = ServiceRegistry::DestroyOnRegistryDestroy, - - DestroyNever = ServiceRegistry::DestroyNever + DestroyOnAppQuit = ServiceRegistry::DestroyOnAppQuit, //!< @copybrief QtMvvm::ServiceRegistry::DestroyOnAppQuit + DestroyOnAppDestroy = ServiceRegistry::DestroyOnAppDestroy, //!< @copybrief QtMvvm::ServiceRegistry::DestroyOnAppDestroy + DestroyOnRegistryDestroy = ServiceRegistry::DestroyOnRegistryDestroy, //!< @copybrief QtMvvm::ServiceRegistry::DestroyOnRegistryDestroy + DestroyNever = ServiceRegistry::DestroyNever //!< @copybrief QtMvvm::ServiceRegistry::DestroyNever }; Q_ENUM(DestructionScope) + //! @private explicit QQmlServiceRegistry(QQmlEngine *parent = nullptr); + //! @copydoc QtMvvm::ServiceRegistry::isRegistered() const Q_INVOKABLE bool isRegistered(const QString &iid) const; - Q_INVOKABLE void registerObject(QObject *object, QtMvvm::QQmlServiceRegistry::DestructionScope scope = DestroyOnAppQuit, bool weak = false); + //! @copydoc QtMvvm::ServiceRegistry::registerObject(TService *, DestructionScope, bool) + Q_INVOKABLE void registerObject(QObject *service, QtMvvm::QQmlServiceRegistry::DestructionScope scope = DestroyOnAppQuit, bool weak = false); + /*! + * @brief Register a service via a constructor function + * + * @param iid The interface id of the type to register the service for + * @param function The function to be called to construct the service + * @param weak Specifies if the registration should be a weak one or a normal one + * + * If the function returns successfully, from now on a service of the given type can be accessed + * via the registry for the interface. The service is lazy initialized an will be created as soon + * as it is requested for the first time. It is created by calling the given `function`. + * + * If the service is registered as weak, registering another service for the same iid will not + * throw an exception but instead discard (and delete) this one. + */ Q_INVOKABLE void registerObject(const QString &iid, const QJSValue &function, bool weak = false); + /*! + * @brief Register a qml component as service object + * + * @param componentUrl The URL of the component to be created + * @param weak Specifies if the registration should be a weak one or a normal one + * + * This method works similar to the other register methods, but is special in that it + * allows you to register a qml component. On construction, that component is loaded + * synchronously and then insanciated to create an instance of the contained object. + * + * Unlike the other methods, the destruction scope for those is always + * ServiceRegistry::DestroyOnAppDestroy, as the object will depend on the QML engine + * + * If the service is registered as weak, registering another service for the same iid will not + * throw an exception but instead discard (and delete) this one. + */ Q_INVOKABLE void registerObject(const QUrl &componentUrl, bool weak = false); + //! @copydoc QtMvvm::ServiceRegistry::registerService(QByteArray, QString, QString, DestructionScope, bool) Q_INVOKABLE void registerPlugin(const QString &iid, QString pluginType = {}, QString pluginKey = {}, DestructionScope scope = DestroyOnAppDestroy, bool weak = false); + //! @copydoc QtMvvm::ServiceRegistry::serviceObj(const QByteArray &) Q_INVOKABLE QObject *service(const QString &iid); private: diff --git a/src/mvvmcore/serviceregistry.h b/src/mvvmcore/serviceregistry.h index 9af7392..24a8f97 100644 --- a/src/mvvmcore/serviceregistry.h +++ b/src/mvvmcore/serviceregistry.h @@ -36,7 +36,7 @@ public: //! Checks if a given interface or service is already registered template bool isRegistered() const; - //! @copybrief ServiceRegistry::isRegistered() + //! @copybrief ServiceRegistry::isRegistered() const bool isRegistered(const QByteArray &iid) const; //! Register a service for its interface via the type