updated widgets doc

Author: Skycoder42

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

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)))
 

doc/gh_header.html

@@ -51,7 +51,7 @@
  </tr>
  </tbody>
 </table>
-<a style="float: right;" target="_blank"  href="https://github.com/Skycoder42/QtDataSync">
+<a style="float: right;" target="_blank"  href="https://github.com/Skycoder42/QtMvvm">
 <img style="padding: 10px;" src="$relpath^GitHub_Logo.png"/>
 </a>
 </div>

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<QWidget*(QWidget*)> &)
+
+@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
+*/

doc/ipresenter.dox

@@ -14,6 +14,8 @@ void myPresenterInit()
 }
 Q_COREAPP_STARTUP_FUNCTION(myPresenterInit)
 @endcode
+
+@sa #QtMvvm_IPresenterIid
 */
 
 /*!

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
+*/

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:
 

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{`<i>A basic question messagebox</i>`}
+@default{<i>A basic question messagebox</i>}
 
 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{<i>Injected</i>}
+
+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
 

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{<i>Injected</i>}
+
+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
+*/

src/mvvmcore/ipresenter.h

@@ -46,7 +46,7 @@ class Q_MVVMCORE_EXPORT IPresenter
 
 }
 
-//! 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*)