added viewmodel and settings viewmodel doc

doc/settingsviewmodel.dox

@@ -0,0 +1,138 @@
+/*!
+@class QtMvvm::SettingsViewModel
+
+It's a ready made viewmodel to show a settings dialog. See @ref settings_xml. To show the
+dialog, call show from another ViewModel or the CoreApp:
+
+@code{.cpp}
+show<QtMvvm::SettingsViewModel>();
+@endcode
+
+TODO link to image page
+*/
+
+/*!
+@property QtMvvm::SettingsViewModel::canRestoreDefaults
+
+@default{`true`}
+
+Restoring defaults is only allowed if both this property and the attribute of the settings XML
+are true.
+
+@accessors{
+	@readAc{canRestoreDefaults}
+	@constantAc
+}
+
+@sa @ref settings_xml_elements_config_attribs
+*/
+
+/*!
+@property QtMvvm::SettingsViewModel::restoreConfig
+
+@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}
+	@constantAc
+}
+*/
+
+/*!
+@var QtMvvm::SettingsViewModel::paramSettings
+
+<b>Value:</b> `"settings"`
+
+@sa SettingsViewModel::showParams
+*/
+
+/*!
+@var QtMvvm::SettingsViewModel::paramSetupFile
+
+<b>Value:</b> `"setupFile"`
+
+@sa SettingsViewModel::showParams
+*/
+
+/*!
+@fn QtMvvm::SettingsViewModel::showParams
+
+@param settings The QSettings to operate on. Can be null to use the default settings
+@param setupFile The path to a file to be used to create the settings. Can be empty to use the
+default path
+@return A paramater hash to be passed to ViewModel::show
+
+It's a shortcut to generate parameters for the show methods to show a settings viewmodel. Use
+them as:
+
+@code{.cpp}
+show<QtMvvm::SettingsViewModel>(QtMvvm::SettingsViewModel::showParams(...));
+@endcode
+
+@note Unless you need to explicitly set the settings or setup file a normal show without any
+parameters will just do fine.
+
+@sa ViewModel::show, SettingsViewModel::paramSettings, SettingsViewModel::paramSetupFile
+*/
+
+/*!
+@fn QtMvvm::SettingsViewModel::loadSetup
+
+@param frontend The name of the current frontend
+@returns The loaded settings setup
+
+If loading fails an empty setup is returned. Logging is performed internally, so you can just
+proceed without error checking and show an empty settings dialog.
+*/
+
+/*!
+@fn QtMvvm::SettingsViewModel::loadValue
+
+@param key The full key of the settings entry to be loaded
+@param defaultValue a default value to return in case the value is not found in the settings
+@returns The value found under the given key
+
+You can override this method if you want to support loading and saving settings from a
+different source then the normally used QSettings
+
+@sa SettingsViewModel::saveValue, SettingsViewModel::resetValue
+*/
+
+/*!
+@fn QtMvvm::SettingsViewModel::saveValue
+
+@param key The full key of the settings entry to be saved
+@param value The value to be stored under the key
+
+You can override this method if you want to support loading and saving settings from a
+different source then the normally used QSettings
+
+@sa SettingsViewModel::loadValue, SettingsViewModel::resetValue
+*/
+
+/*!
+@fn QtMvvm::SettingsViewModel::resetValue
+
+@param key The full key of the settings entry to be resetted
+
+You can override this method if you want to support loading and saving settings from a
+different source then the normally used QSettings
+
+@sa SettingsViewModel::loadValue, SettingsViewModel::saveValue
+*/
+
+/*!
+@fn QtMvvm::SettingsViewModel::callAction
+
+@param key The key of the entry that triggered the action
+@param parameters A map with additional parameters for the action call
+
+This method is called by the GUI when an entry with the
+@ref settings_xml_types_action "action" type is pressed by the user. The key is what would
+normally be used as the settings key. The parameters are deduced from the settings XML. See
+the type documentation for more details.
+
+@sa @ref settings_xml_types_action
+*/

doc/settingsxml.dox

@@ -225,6 +225,9 @@ type, for entry elements). It defines the actual type of for example the default
 - double or number
 - bool
 - QDateTime or datetime
+- @ref settings_xml_types_action
+- list or selection
+- radiolist
 - ...
 
 The type you need depends on what kind of data you want to represent via the XML elements. But
@@ -267,4 +270,14 @@ of or condiditions around and conditions. This is a very reduced boolean logic,
 be enough to create the desired filters. For example, you may want to show an element only on
 windows or on android when the material design is used. The resulting string would be:
 `windows|android&material`.
+
+@subsection settings_xml_types_action action
+The action type is meant as a placeholder for a pressable button. An action edit will simply
+display a button or similar, and instead of representing a value in the settings, pressing it
+will trigger QtMvvm::SettingsViewModel::callAction. The Entries `key` attribute is passed as
+the first parameter to the method. The parameters can be specified by adding a `<Property>`
+to the entry with the key `args` and the type `object`. The property of this object are the
+elements of the map passed as the second parameter.
 */
+
+//! TODO add small sample code snippits?

doc/viewmodel.dox

@@ -0,0 +1,117 @@
+/*!
+@class QtMvvm::ViewModel
+
+The ViewModel is the primary class of the core library is must be implemented to create
+custom viewmodels to be shown via the mvvm mechanism. To create a custom viewmodel, simply
+implement this class and show the viewmodel via one of the show methods. Viewmodels presented
+that way support automatic injection via injectable properties.
+
+@attention In order for a viewmodel be showble, it must implement an invokable constructor
+with a single QObject* parameter for the parent. It basically should look like this:
+@code{.cpp}
+Q_INVOKABLE explicit MyViewModel(QObject *parent = nullptr);
+@endcode
+
+@sa CoreApp::show, #QTMVVM_INJECT
+*/
+
+/*!
+@fn QtMvvm::ViewModel::onInit
+
+@param params The parameters to initialize the viewmodel with
+
+This method is called by the presenter right after creating the view and reparenting the
+viewmodel to the view. The parameters are the ones that have been passed to the show method
+called to show this viewmodel instance. Reimplement this method if you need to perform
+initializations after beeing assigned to a viewmodel or if you want to support a parametrized
+viewmodel.
+
+@sa ViewModel::show, ViewModel::showForResult, CoreApp::show
+*/
+
+/*!
+@fn QtMvvm::ViewModel::onResult
+
+@param requestCode The request code of the show request for the viewmodel that triggered the
+result
+@param result The result passed from the viewmodel
+
+When showing a child viewmodel via showForResult(), then the result of that show request is
+reported back via this function. The requestCode is the one that was passed to the
+showForResult() method, and the result what the viewmodel reported back. If the showed
+viewmodel emitted resultReady() before beeing destroyed, this value passed to that signal is
+whats reported as result. If the child viewmodel gets destroyed without ever emitting that
+signal, this method is still called, but with an invalid QVariant as result.
+
+@sa ViewModel::showForResult, ViewModel::resultReady
+*/
+
+/*!
+@fn QtMvvm::ViewModel::resultReady
+
+@param result The result that should be passed to the parent viewmodel
+
+Viewmodels that have been created via showForResult() must emit this signal to report back the
+result of the show request. Doing so will lead to the onResult() method of the showing
+viewmodel beeing with the emitted result as second parameter. Not emitting this signal before
+the viewmodel gets destroy leads to the onResult() beeing called with an invalid result.
+
+@sa ViewModel::showForResult, ViewModel::onResult
+*/
+
+/*!
+@fn QtMvvm::ViewModel::show(const QVariantHash &) const
+
+@param params The show parameters to be passed to the created viewmodel
+
+This method will send a show request to the core app to show a viewmodel of the given type.
+The parameters are passed to the onInit() method by the presenter after creating and parenting
+the view. The viewmodel will be shown asynchronously, so this method will return immediatly.
+
+@sa ViewModel::showForResult, ViewModel::onInit, CoreApp::show
+*/
+
+/*!
+@fn QtMvvm::ViewModel::show(const char *, const QVariantHash &) const
+
+@param viewModelName The name of the viewmodel class to be shown
+@copydetails ViewModel::show(const QVariantHash &) const
+*/
+
+/*!
+@fn QtMvvm::ViewModel::show(const QMetaObject *, const QVariantHash &) const
+
+@param viewMetaObject The metaobject of the viewmodel class to be shown
+@copydetails ViewModel::show(const QVariantHash &) const
+*/
+
+/*!
+@fn QtMvvm::ViewModel::showForResult(quint32, const QVariantHash &) const
+
+@param requestCode The code of the show request
+@param params The show parameters to be passed to the created viewmodel
+
+This method will send a show request to the core app to show a viewmodel of the given type.
+The parameters are passed to the onInit() method by the presenter after creating and parenting
+the view. The viewmodel will be shown asynchronously, so this method will return immediatly.
+The viewmodel is show for a result, meaning that a result is reported back via onInit() as
+soon as the shown viewmodel emits resultReady() or has been destroyed. The request code is
+passed to the onResult() method in order to identify the show request.
+
+@sa ViewModel::show, ViewModel::onInit, ViewModel::resultReady, ViewModel::onResult,
+CoreApp::show
+*/
+
+/*!
+@fn QtMvvm::ViewModel::showForResult(quint32, const char *, const QVariantHash &) const
+
+@param viewModelName The name of the viewmodel class to be shown
+@copydetails ViewModel::showForResult(quint32, const QVariantHash &) const
+*/
+
+/*!
+@fn QtMvvm::ViewModel::showForResult(quint32, const QMetaObject *, const QVariantHash &) const
+
+@param viewMetaObject The metaobject of the viewmodel class to be shown
+@copydetails ViewModel::showForResult(quint32, const QVariantHash &) const
+*/

src/mvvmcore/settingsviewmodel.cpp

@@ -74,10 +74,10 @@ void SettingsViewModel::resetValue(const QString &key)
 	d->settings->remove(key);
 }
 
-void SettingsViewModel::callAction(const QString &entryId, const QVariantMap &parameters)
+void SettingsViewModel::callAction(const QString &key, const QVariantMap &parameters)
 {
 	Q_UNUSED(parameters)
-	logWarning() << "Unknown action requested with entry id" << entryId
+	logWarning() << "Unknown action requested with entry id" << key
 				 << "and parameters" << parameters;
 }
 

src/mvvmcore/settingsviewmodel.h

@@ -13,45 +13,65 @@
 namespace QtMvvm {
 
 class SettingsViewModelPrivate;
+//! A ViewModel for a generic settings dialog based of an XML settings file
 class Q_MVVMCORE_EXPORT SettingsViewModel : public ViewModel
 {
 	Q_OBJECT
 
+	//! Specifies if restoring the defaults is generally allowed
 	Q_PROPERTY(bool canRestoreDefaults READ canRestoreDefaults CONSTANT)
+	//! The message configuration to be used to for a dialog to ask for settings restore
 	Q_PROPERTY(QtMvvm::MessageConfig restoreConfig READ restoreConfig CONSTANT)
 
+	//! The settings setup loader to use to create the settings dialog. Is an injected property
 	Q_PROPERTY(QtMvvm::ISettingsSetupLoader* settingsSetupLoader READ settingsSetupLoader WRITE setSettingsSetupLoader NOTIFY settingsSetupLoaderChanged)
 	QTMVVM_INJECT(QtMvvm::ISettingsSetupLoader*, settingsSetupLoader)
 
 public:
+	//! The parameter for a QSettings object for the onInit() method
 	static const QString paramSettings;
+	//! The parameter for a settings setup file for the onInit() method
 	static const QString paramSetupFile;
 
-	static QVariantHash showParams(QSettings *settings = nullptr, const QString &setupFile = {});
+	//! Generates show parameter to show a settings viewmodel via ViewModel::show
+	static QVariantHash showParams(QSettings *settings, const QString &setupFile = {});
 
+	//! Invokable constructor
 	Q_INVOKABLE explicit SettingsViewModel(QObject *parent = nullptr);
 	~SettingsViewModel();
 
+	//! @readAcFn{SettingsViewModel::canRestoreDefaults}
 	virtual bool canRestoreDefaults() const;
+	//! @readAcFn{SettingsViewModel::restoreConfig}
 	virtual QtMvvm::MessageConfig restoreConfig() const;
-
+	//! @readAcFn{SettingsViewModel::settingsSetupLoader}
 	ISettingsSetupLoader* settingsSetupLoader() const;
+
+	//! Loads the settings setup of the prepared file for the given frontend
 	SettingsElements::Setup loadSetup(const QString &frontend) const;
 
+	//! Returns the settings this viewmodel operates on
 	QSettings *settings() const;
 
+	//! Loads the value for the given key from the settings
 	Q_INVOKABLE virtual QVariant loadValue(const QString &key, const QVariant &defaultValue = {}) const;
+	//! Saves the value with the given key
 	Q_INVOKABLE virtual void saveValue(const QString &key, const QVariant &value);
+	//! Resets the value or group identified by the key
 	Q_INVOKABLE virtual void resetValue(const QString &key);
 
 public Q_SLOTS:
-	virtual void callAction(const QString &entryId, const QVariantMap &parameters);
+	//! Is called when an action type edit is pressed
+	virtual void callAction(const QString &key, const QVariantMap &parameters);
 
+	//! @writeAcFn{SettingsViewModel::settingsSetupLoader}
 	void setSettingsSetupLoader(QtMvvm::ISettingsSetupLoader* settingsSetupLoader);
 
 Q_SIGNALS:
+	//! @notifyAcFn{SettingsViewModel::settingsSetupLoader}
 	void settingsSetupLoaderChanged(QtMvvm::ISettingsSetupLoader* settingsSetupLoader);
 
+	//! Is emitted when the initialization has been completed and the viewmodel is ready for loading settings
 	void beginLoadSetup();
 
 protected:

src/mvvmcore/viewmodel.h

@@ -16,29 +16,40 @@ namespace QtMvvm {
 class CoreApp;
 
 class ViewModelPrivate;
+//! The base class for all viewmodels
 class Q_MVVMCORE_EXPORT ViewModel : public QObject
 {
 	Q_OBJECT
 
 public:
+	//! Default constructor with parent
 	explicit ViewModel(QObject *parent = nullptr);
 	~ViewModel();
 
 public Q_SLOTS:
+	//! Called by the presenter to initialize the viewmodel
 	virtual void onInit(const QVariantHash &params);
+	//! Called by the presenter when a result of a showed viewmodel is ready
 	virtual void onResult(quint32 requestCode, const QVariant &result);
 
 Q_SIGNALS:
+	//! Should be emitted when the viewmodels result is ready
 	void resultReady(const QVariant &result);
 
 protected:
+	//! Show another viewmodel as a child of this one
 	template <typename TViewModel>
 	inline void show(const QVariantHash &params = {}) const;
+	//! @copybrief ViewModel::show(const QVariantHash &) const
 	void show(const char *viewModelName, const QVariantHash &params = {}) const;
+	//! @copybrief ViewModel::show(const QVariantHash &) const
 	void show(const QMetaObject *viewMetaObject, const QVariantHash &params = {}) const;
+	//! Show another viewmodel as a child of this one and expect its result
 	template <typename TViewModel>
 	inline void showForResult(quint32 requestCode, const QVariantHash &params = {}) const;
+	//! @copybrief ViewModel::showForResult(quint32, const QVariantHash &) const
 	void showForResult(quint32 requestCode, const char *viewModelName, const QVariantHash &params = {}) const;
+	//! @copybrief ViewModel::showForResult(quint32, const QVariantHash &) const
 	void showForResult(quint32 requestCode, const QMetaObject *viewMetaObject, const QVariantHash &params = {}) const;
 
 private: