diff --git a/doc/Doxyfile b/doc/Doxyfile index 8782f3f..2ab1bf4 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -44,7 +44,7 @@ PROJECT_NUMBER = 1.0.0 # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "Project desciption here" +PROJECT_BRIEF = "A mvvm oriented library for Qt, to create Projects for Widgets and Quick in parallel" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 diff --git a/doc/doc.pro b/doc/doc.pro index fa8b33f..c2cb033 100644 --- a/doc/doc.pro +++ b/doc/doc.pro @@ -6,7 +6,8 @@ OTHER_FILES += Doxyfile \ ../README.md \ *.dox \ snippets/*.cpp \ - images/* + images/* \ + gh_header.html system($$QMAKE_MKDIR $$shell_quote($$shell_path($$OUT_PWD/qtmvvm))) diff --git a/doc/gh_header.html b/doc/gh_header.html index 7f66a92..b2a5eff 100644 --- a/doc/gh_header.html +++ b/doc/gh_header.html @@ -51,7 +51,7 @@ $extrastylesheet - + diff --git a/doc/inputwidgetfactory.dox b/doc/inputwidgetfactory.dox new file mode 100644 index 0000000..d5ede8f --- /dev/null +++ b/doc/inputwidgetfactory.dox @@ -0,0 +1,79 @@ +/*! +@class QtMvvm::InputWidgetFactory + +The factory is used by the WidgetsPresenter to create input widgets for various types. This is +used to for example create the edits of input dialogs or for the edit fields of a +SettingsDialog. + +@sa WidgetsPresenter, WidgetsPresenter::inputWidgetFactory, MessageConfig::TypeInputDialog, +QtMvvm::getInput, SettingsViewModel +*/ + +/*! +@fn QtMvvm::InputWidgetFactory::createInput + +@param type The input type to create a widget for +@param parent The parent widget for the created widget +@param viewProperties A map with extra properties to be set on the edit +@returns A newly created widget suitable for editing input of the given type +@throws PresenterException In case no widget could be found or created for the given type + +The factory first checks if the given type is registered as alias. If yes, it continues with +the aliased type. Then it checks for a widget registered as simple widget exists for the given +type and uses that one if present. If no simple widget is set the default mapping for type to +widgets is used (See MessageConfig::TypeInputDialog for a full table of supported types). If no +widget can be found for a type, an exception is thrown. + +The viewProperties are used to setup the created widget by settings them as properties on the +widget. For every key-value-pair in the map, QObject::setProperty is called on the widget to +set the property. + +@sa MessageConfig::TypeInputDialog, InputWidgetFactory::addSimpleWidget, +InputWidgetFactory::addAlias +*/ + +/*! +@fn QtMvvm::InputWidgetFactory::addSimpleWidget() + +@tparam TType The type to add a widget for +@tparam TWidget The type of the widget to provide for that type + +The TWidget type must extend QWidget and have a constructor that takes a single `QWidget*` as +argument. + +@sa MessageConfig::createInput, InputWidgetFactory::addAlias +*/ + +/*! +@fn QtMvvm::InputWidgetFactory::addSimpleWidget(const QByteArray &, const std::function &) + +@param type The type to add a widget for +@param creator A function that creates a new instance of a widget for the given type + +The `QWidget*` argument of the creator function must be used as the parent of the created +widget that is returned by the function. + +@sa MessageConfig::createInput, InputWidgetFactory::addAlias +*/ + +/*! +@fn QtMvvm::InputWidgetFactory::addAlias() + +@tparam TAliasType The type to add as a new alias +@tparam TTargetType The type the alias should be translated to + +If an input widget for the alias type is requested, one of the target type is created instead. + +@sa MessageConfig::createInput, InputWidgetFactory::addSimpleWidget +*/ + +/*! +@fn QtMvvm::InputWidgetFactory::addAlias(const QByteArray &, const QByteArray &) + +@param alias The type to add as a new alias +@param targetType The type the alias should be translated to + +If an input widget for the alias type is requested, one of the target type is created instead. + +@sa MessageConfig::createInput, InputWidgetFactory::addSimpleWidget +*/ diff --git a/doc/ipresenter.dox b/doc/ipresenter.dox index 8fdbc0a..f46d368 100644 --- a/doc/ipresenter.dox +++ b/doc/ipresenter.dox @@ -14,6 +14,8 @@ void myPresenterInit() } Q_COREAPP_STARTUP_FUNCTION(myPresenterInit) @endcode + +@sa #QtMvvm_IPresenterIid */ /*! diff --git a/doc/ipresentingview.dox b/doc/ipresentingview.dox new file mode 100644 index 0000000..25d443c --- /dev/null +++ b/doc/ipresentingview.dox @@ -0,0 +1,21 @@ +/*! +@class QtMvvm::IPresentingView + +If a the viewmodel of a view that was presented by the WidgetsPresenter as used as the parent +view of another viewmodel, the parent view can implement this interface in order to be used +as presenter for the view of the child viewmodel. In such a case, if the parent view implements +this interface, the tryPresent() method is called to try the presentation of the child view + +@sa #QtMvvm_IPresentingViewIid, WidgetsPresenter +*/ + +/*! +@fn QtMvvm::IPresentingView::tryPresent + +@param view The view that is tryed to be presented +@returns `true` if successfully presented, `false` if not + +If true is returned, the presenter assumes presentation was successful and thus completes. If +false is returned, it resumes presenting the view normally, just as if that interface was never +implemented +*/ diff --git a/doc/message.dox b/doc/message.dox index 59540ff..a7880a9 100644 --- a/doc/message.dox +++ b/doc/message.dox @@ -228,21 +228,22 @@ via QVariant can be used as input value. However, only for the most common types edit views exist. In case you want to use types not present in the list below, you need to create edit views yourself - Type | Widgets edit | Quick edit ---------------------|-------------------------------|------------ - bool | QCheckBox | CheckBox - switch | -/- | Switch - QString, string | QLineEdit | TextField - int | QSpinBox | SpinBox - double, number | QDoubleSpinBox | DoubleSpinBox - QDate | QDateEdit | -/- - QTime | QTimeEdit | -/- - QDateTime, date | QDateTimeEdit | -/- - QFont | QFontComboBox | FontEdit - QKeySequence | QKeySequenceEdit | -/- - QUrl, url | QLineEdit with QUrlValidator | UrlField - selection, list | QComboBox | ListEdit - radiolist | -/- | RadioListEdit + Type | Widgets edit | Quick edit +------------------------|-------------------------------|------------ + bool | QCheckBox | CheckBox + switch | -/- | Switch + QString, string | QLineEdit | TextField + int | QSpinBox | SpinBox + double, number | QDoubleSpinBox | DoubleSpinBox + QDate | QDateEdit | -/- + QTime | QTimeEdit | -/- + QDateTime, date | QDateTimeEdit | -/- + QFont | QFontComboBox | FontEdit + QKeySequence | QKeySequenceEdit | -/- + QUrl, url | QLineEdit with QUrlValidator | UrlField + selection, list | QComboBox | ListEdit + radiolist | -/- | RadioListEdit + action (settings only) | QPushButton | ItemDelegate The following types have special properties as well: diff --git a/doc/settingsviewmodel.dox b/doc/settingsviewmodel.dox index a932687..0d0faed 100644 --- a/doc/settingsviewmodel.dox +++ b/doc/settingsviewmodel.dox @@ -20,7 +20,7 @@ Restoring defaults is only allowed if both this property and the attribute of th are true. @accessors{ - @readAc{canRestoreDefaults} + @readAc{canRestoreDefaults()} @constantAc } @@ -30,16 +30,34 @@ are true. /*! @property QtMvvm::SettingsViewModel::restoreConfig -@default{`A basic question messagebox`} +@default{A basic question messagebox} If you want to modify the text or options, you can replace the messagebox with another dialog. @accessors{ - @readAc{restoreConfig} + @readAc{restoreConfig()} @constantAc } */ +/*! +@property QtMvvm::SettingsViewModel::settingsSetupLoader + +@default{Injected} + +Do not set this property yourself. It is automatically injected when showing the viewmodel. +You can use the ServiceRegistry::registerInterface if you need to use a loader different from +the default one. + +@accessors{ + @readAc{settingsSetupLoader()} + @writeAc{setSettingsSetupLoader()} + @notifyAc{settingsSetupLoaderChanged()} +} + +@sa #QTMVVM_INJECT +*/ + /*! @var QtMvvm::SettingsViewModel::paramSettings diff --git a/doc/widgetspresenter.dox b/doc/widgetspresenter.dox new file mode 100644 index 0000000..02b1541 --- /dev/null +++ b/doc/widgetspresenter.dox @@ -0,0 +1,117 @@ +/*! +@class QtMvvm::WidgetsPresenter + +This presenter is automatically registered as the default presenter for the IPresenter +interface with the ServiceRegistry, but as weak service, in order to make it possible to +overwrite it. + +The class handles all the logic required for presenting widget based views. You can extend +this class and reimplement it's virtual methods if you need to adjust how certain views or +dialogs are presented, or if you want to support custom stuff +*/ + +/*! +@property QtMvvm::WidgetsPresenter::inputWidgetFactory + +@default{Injected} + +Do not set this property yourself. It is automatically injected when showing the viewmodel. +You can use the ServiceRegistry::registerInterface if you need to use a factory different from +the default one. + +@accessors{ + @readAc{inputWidgetFactory()} + @writeAc{setInputWidgetFactory()} +} + +@sa #QTMVVM_INJECT +*/ + +/*! +@fn QtMvvm::WidgetsPresenter::registerView() + +@tparam TView The widget type register within the presenter. Must extend QWidget + +The widget is registered with the current presenter. It is registered implicitly, which means +that it's name will be used to find it when a viewmodel is presented for it. Thus, it must be +named after the viewmodel. If the viewmodel is for example named `MyViewModel`, then the view +must start with `My` too. For example it can be named `MyWidget`, `MyDialog`, `MyWindow`, +`MyView`, ... + +@note Implicit detection of views for viewmodels can sometimes lead to ambiguities and thus a +wrong view beeing found. In such cases, use registerViewExplicitly() instead. + +@sa WidgetsPresenter::registerViewExplicitly +*/ + +/*! +@fn QtMvvm::WidgetsPresenter::registerView(const QMetaObject *) + +@param viewType The widget type register within the presenter. Must extend QWidget + +The widget is registered with the current presenter. It is registered implicitly, which means +that it's name will be used to find it when a viewmodel is presented for it. Thus, it must be +named after the viewmodel. If the viewmodel is for example named `MyViewModel`, then the view +must start with `My` too. For example it can be named `MyWidget`, `MyDialog`, `MyWindow`, +`MyView`, ... + +@note Implicit detection of views for viewmodels can sometimes lead to ambiguities and thus a +wrong view beeing found. In such cases, use registerViewExplicitly() instead. + +@sa WidgetsPresenter::registerViewExplicitly +*/ + +/*! +@fn QtMvvm::WidgetsPresenter::registerViewExplicitly() + +@tparam TViewModel The viewmodel to to register the view for +@tparam TView The widget type register within the presenter. Must extend QWidget + +The widget is registered with the current presenter. It is registered explicitly, which means +that whenever the given viewmodel is beeing presented, this exact view will be used. Explicit +registration have precedence over implicit ones. + +@sa WidgetsPresenter::registerView +*/ + +/*! +@fn QtMvvm::WidgetsPresenter::registerViewExplicitly(const QMetaObject *, const QMetaObject *) + +@param viewModelType The viewmodel to to register the view for +@param viewType The widget type register within the presenter. Must extend QWidget + +The widget is registered with the current presenter. It is registered explicitly, which means +that whenever the given viewmodel is beeing presented, this exact view will be used. Explicit +registration have precedence over implicit ones. + +@sa WidgetsPresenter::registerView +*/ + +/*! +@fn QtMvvm::WidgetsPresenter::findWidgetMetaObject + +@param viewModelMetaObject The metobject of the viewmodel to find a view for +@returns The metaobject of the view to used, or `nullptr` if none was found + +The default implementation simply check all explicitly registered views and then tries to +match the name with the implicitly registered ones. If no match if found, the same is tried +for the parent viewmodel type recursively, until the ViewModel base is reached. +*/ + +/*! +@fn QtMvvm::WidgetsPresenter::tryPresent + +@param view The view to be presented +@param parentView The parent view to present the view to +@returns `true` if successfully presented, `false` if not + +This method is called to perform the actual presentation (i.e. the parenting and how to show) +the view. The default implementation first checks if the parent implements IPresentingView and +if yes if it is able to present the view. If not, a bunch of standard widget types are checked +for special presentation methods. QDialogs are presented via QDialog::open. QDockWidgets that +are presented to a QMainWindow are added as dock widget (QMainWindow::addDockWidget). If the +parent or its central widget are a QMdiArea, and the views class name ends with `MdiWindow`, +it is presented as QMdiSubWindow. For all other cases, showForeground() is called. + +@sa WidgetsPresenter::showForeground, QDialog, QMainWindow, QDockWidget, QMdiArea +*/ diff --git a/src/mvvmcore/ipresenter.h b/src/mvvmcore/ipresenter.h index 5adabfa..c2c36eb 100644 --- a/src/mvvmcore/ipresenter.h +++ b/src/mvvmcore/ipresenter.h @@ -46,7 +46,7 @@ public: } -//! The IID of the IPresenter class +//! The IID of the QtMvvm::IPresenter class #define QtMvvm_IPresenterIid "de.skycoder42.qtmvvm.core.IPresenter" Q_DECLARE_INTERFACE(QtMvvm::IPresenter, QtMvvm_IPresenterIid) Q_DECLARE_METATYPE(QtMvvm::IPresenter*) diff --git a/src/mvvmwidgets/inputwidgetfactory.cpp b/src/mvvmwidgets/inputwidgetfactory.cpp index 66ad38f..82f4e04 100644 --- a/src/mvvmwidgets/inputwidgetfactory.cpp +++ b/src/mvvmwidgets/inputwidgetfactory.cpp @@ -18,7 +18,8 @@ using namespace QtMvvm; -InputWidgetFactory::InputWidgetFactory() : +InputWidgetFactory::InputWidgetFactory(QObject *parent) : + QObject(parent), d(new InputWidgetFactoryPrivate()) {} diff --git a/src/mvvmwidgets/inputwidgetfactory.h b/src/mvvmwidgets/inputwidgetfactory.h index 5ac5aed..0d62aa2 100644 --- a/src/mvvmwidgets/inputwidgetfactory.h +++ b/src/mvvmwidgets/inputwidgetfactory.h @@ -3,6 +3,7 @@ #include +#include #include #include @@ -12,21 +13,29 @@ namespace QtMvvm { class InputWidgetFactoryPrivate; -class InputWidgetFactory +//! A factory class to generate input edit widgets by their type names +class InputWidgetFactory : public QObject { + Q_OBJECT + public: - InputWidgetFactory(); + Q_INVOKABLE explicit InputWidgetFactory(QObject *parent = nullptr); virtual ~InputWidgetFactory(); + //! Create a new input widget of the given input type virtual QWidget *createInput(const QByteArray &type, QWidget *parent, const QVariantMap &viewProperties); - virtual void addSimpleWidget(const QByteArray &type, const std::function &creator); + //! Adds a new generator to create widgets for the given type template inline void addSimpleWidget(); + //! @copybrief addSimpleWidget() + virtual void addSimpleWidget(const QByteArray &type, const std::function &creator); - virtual void addAlias(const QByteArray &alias, const QByteArray &targetType); + //! Adds a type name alias template inline void addAlias(); + //! @copybrief addAlias() + virtual void addAlias(const QByteArray &alias, const QByteArray &targetType); private: QScopedPointer d; diff --git a/src/mvvmwidgets/ipresentingview.h b/src/mvvmwidgets/ipresentingview.h index a58c937..a2e8b93 100644 --- a/src/mvvmwidgets/ipresentingview.h +++ b/src/mvvmwidgets/ipresentingview.h @@ -7,17 +7,21 @@ namespace QtMvvm { +//! A simple interface to make it possible for any view to present subviews class Q_MVVMWIDGETS_EXPORT IPresentingView { public: inline virtual ~IPresentingView() = default; + //! Is called to try to present a view virtual bool tryPresent(QWidget *view) = 0; }; } +//! The IID of the QtMvvm::IPresentingView class #define QtMvvm_IPresentingViewIid "de.skycoder42.qtmvvm.widgets.IPresentingView" Q_DECLARE_INTERFACE(QtMvvm::IPresentingView, QtMvvm_IPresentingViewIid) +//! @file ipresentingview.h The header of the IPresentingView interface #endif // QTMVVM_IPRESENTINGVIEW_H diff --git a/src/mvvmwidgets/settingsdialog.h b/src/mvvmwidgets/settingsdialog.h index 9662d0d..5306638 100644 --- a/src/mvvmwidgets/settingsdialog.h +++ b/src/mvvmwidgets/settingsdialog.h @@ -12,16 +12,20 @@ namespace QtMvvm { class SettingsDialogPrivate; +//! The widgets view implementation for the SettingsViewModel class Q_MVVMWIDGETS_EXPORT SettingsDialog : public QDialog { Q_OBJECT public: + //! View constructor Q_INVOKABLE explicit SettingsDialog(QtMvvm::ViewModel *viewModel, QWidget *parent = nullptr); ~SettingsDialog(); protected: + //! Returns the stylesheet used highlight labels found when searching virtual QString labelFilterStyleSheet() const; + //! Return a url to overwrite the default settings icon virtual QUrl iconOverwrite() const; private: diff --git a/src/mvvmwidgets/widgetspresenter.cpp b/src/mvvmwidgets/widgetspresenter.cpp index f041806..1d92b63 100644 --- a/src/mvvmwidgets/widgetspresenter.cpp +++ b/src/mvvmwidgets/widgetspresenter.cpp @@ -28,6 +28,7 @@ namespace { void qtMvvmWidgetsInit() { + QtMvvm::ServiceRegistry::instance()->registerObject(true); QtMvvm::ServiceRegistry::instance()->registerInterface(true); } @@ -91,16 +92,8 @@ void WidgetsPresenter::present(ViewModel *viewModel, const QVariantHash ¶ms, view->setAttribute(Qt::WA_DeleteOnClose); viewModel->onInit(params); - // present the view - auto presented = false; - auto tPresenter = dynamic_cast(parentView); - if(tPresenter) - presented = tPresenter->tryPresent(view); - if(!presented) - presented = tryPresent(view, parentView); - - //handle the present result - if(!presented) { + // present the view and handle the present result + if(!tryPresent(view, parentView)) { view->deleteLater(); throw PresenterException(QByteArrayLiteral("Unable to find a method that is able to present a view of type") + viewMetaObject->className()); @@ -125,12 +118,12 @@ void WidgetsPresenter::showDialog(const MessageConfig &config, MessageResult *re InputWidgetFactory *WidgetsPresenter::inputWidgetFactory() const { - return d->inputViewFactory.data(); + return d->inputViewFactory; } void WidgetsPresenter::setInputWidgetFactory(InputWidgetFactory *inputWidgetFactory) { - d->inputViewFactory.reset(inputWidgetFactory); + d->inputViewFactory = inputWidgetFactory; emit inputWidgetFactoryChanged(inputWidgetFactory); } @@ -179,6 +172,10 @@ const QMetaObject *WidgetsPresenter::findWidgetMetaObject(const QMetaObject *vie bool WidgetsPresenter::tryPresent(QWidget *view, QWidget *parentView) { + auto tPresenter = dynamic_cast(parentView); + if(tPresenter && tPresenter->tryPresent(view)) + return true; + auto metaObject = view->metaObject(); // Check if QDialog @@ -434,7 +431,7 @@ void WidgetsPresenter::presentOtherDialog(const MessageConfig &config, QPointer< // ------------- Private Implementation ------------- WidgetsPresenterPrivate::WidgetsPresenterPrivate() : - inputViewFactory(new InputWidgetFactory()), + inputViewFactory(), implicitMappings({&SettingsDialog::staticMetaObject}), explicitMappings() {} diff --git a/src/mvvmwidgets/widgetspresenter.h b/src/mvvmwidgets/widgetspresenter.h index 44d5348..f60f1dd 100644 --- a/src/mvvmwidgets/widgetspresenter.h +++ b/src/mvvmwidgets/widgetspresenter.h @@ -15,48 +15,67 @@ namespace QtMvvm { class WidgetsPresenterPrivate; +//! The IPresenter implementation for the widgets module class Q_MVVMWIDGETS_EXPORT WidgetsPresenter : public QObject, public IPresenter { Q_OBJECT Q_INTERFACES(QtMvvm::IPresenter) + //! The factory to create input widgets with, as injected property Q_PROPERTY(InputWidgetFactory* inputWidgetFactory READ inputWidgetFactory WRITE setInputWidgetFactory NOTIFY inputWidgetFactoryChanged) + QTMVVM_INJECT(InputWidgetFactory*, inputWidgetFactory) public: + //! Invokable constructor Q_INVOKABLE explicit WidgetsPresenter(QObject *parent = nullptr); ~WidgetsPresenter(); - template + //! Register a subclass of the WidgetsPresenter as the active presenter for the CoreApp + template static void registerAsPresenter(); + //! Register a view to be found by the presenter template static void registerView(); + //! @copybrief registerView() static void registerView(const QMetaObject *viewType); + //! Register a view for a viewmodel to be found by the presenter template static void registerViewExplicitly(); + //! @copybrief registerViewExplicitly() static void registerViewExplicitly(const QMetaObject *viewModelType, const QMetaObject *viewType); void present(ViewModel *viewModel, const QVariantHash ¶ms, QPointer parent) override; void showDialog(const MessageConfig &config, MessageResult *result) override; + //! @readAcFn{WidgetsPresenter::inputWidgetFactory} InputWidgetFactory* inputWidgetFactory() const; public Q_SLOTS: + //! @writeAcFn{WidgetsPresenter::inputWidgetFactory} void setInputWidgetFactory(InputWidgetFactory* inputWidgetFactory); Q_SIGNALS: + //! @notifyAcFn{WidgetsPresenter::inputWidgetFactory} void inputWidgetFactoryChanged(InputWidgetFactory* inputWidgetFactory); protected: + //! Is called to find the meta object of the view to be used for the given viewmodel virtual const QMetaObject *findWidgetMetaObject(const QMetaObject *viewModelMetaObject); + //! Try to present the given view on the parent view virtual bool tryPresent(QWidget *view, QWidget *parentView); + //! Called to show a widget in the foreground virtual void showForeground(QWidget *view) const; + //! Called to present a dialog of MessageConfig::TypeMessageBox virtual void presentMessageBox(const MessageConfig &config, QPointer result); + //! Called to present a dialog of MessageConfig::TypeInputDialog virtual void presentInputDialog(const MessageConfig &config, QPointer result); + //! Called to present a dialog of MessageConfig::TypeFileDialog virtual void presentFileDialog(const MessageConfig &config, QPointer result); + //! Called to present a dialog of a non standard MessageConfig::type virtual void presentOtherDialog(const MessageConfig &config, QPointer result); private: diff --git a/src/mvvmwidgets/widgetspresenter_p.h b/src/mvvmwidgets/widgetspresenter_p.h index 161e27e..fac617a 100644 --- a/src/mvvmwidgets/widgetspresenter_p.h +++ b/src/mvvmwidgets/widgetspresenter_p.h @@ -17,7 +17,7 @@ public: static WidgetsPresenter *currentPresenter(); - QScopedPointer inputViewFactory; + InputWidgetFactory* inputViewFactory; QSet implicitMappings; QHash explicitMappings; };