Skip to content
This repository was archived by the owner on Mar 4, 2023. It is now read-only.

Commit 36fdab3

Browse files
Skycoder42Skycoder42
committed
added viewmodel and settings viewmodel doc
1 parent c928bd1 commit 36fdab3

File tree

6 files changed

+304
-5
lines changed

6 files changed

+304
-5
lines changed

‎doc/settingsviewmodel.dox‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/*!
2+
@class QtMvvm::SettingsViewModel
3+
4+
It's a ready made viewmodel to show a settings dialog. See @ref settings_xml. To show the
5+
dialog, call show from another ViewModel or the CoreApp:
6+
7+
@code{.cpp}
8+
show<QtMvvm::SettingsViewModel>();
9+
@endcode
10+
11+
TODO link to image page
12+
*/
13+
14+
/*!
15+
@property QtMvvm::SettingsViewModel::canRestoreDefaults
16+
17+
@default{`true`}
18+
19+
Restoring defaults is only allowed if both this property and the attribute of the settings XML
20+
are true.
21+
22+
@accessors{
23+
@readAc{canRestoreDefaults}
24+
@constantAc
25+
}
26+
27+
@sa @ref settings_xml_elements_config_attribs
28+
*/
29+
30+
/*!
31+
@property QtMvvm::SettingsViewModel::restoreConfig
32+
33+
@default{`<i>A basic question messagebox</i>`}
34+
35+
If you want to modify the text or options, you can replace the messagebox with another dialog.
36+
37+
@accessors{
38+
@readAc{restoreConfig}
39+
@constantAc
40+
}
41+
*/
42+
43+
/*!
44+
@var QtMvvm::SettingsViewModel::paramSettings
45+
46+
<b>Value:</b> `"settings"`
47+
48+
@sa SettingsViewModel::showParams
49+
*/
50+
51+
/*!
52+
@var QtMvvm::SettingsViewModel::paramSetupFile
53+
54+
<b>Value:</b> `"setupFile"`
55+
56+
@sa SettingsViewModel::showParams
57+
*/
58+
59+
/*!
60+
@fn QtMvvm::SettingsViewModel::showParams
61+
62+
@param settings The QSettings to operate on. Can be null to use the default settings
63+
@param setupFile The path to a file to be used to create the settings. Can be empty to use the
64+
default path
65+
@return A paramater hash to be passed to ViewModel::show
66+
67+
It's a shortcut to generate parameters for the show methods to show a settings viewmodel. Use
68+
them as:
69+
70+
@code{.cpp}
71+
show<QtMvvm::SettingsViewModel>(QtMvvm::SettingsViewModel::showParams(...));
72+
@endcode
73+
74+
@note Unless you need to explicitly set the settings or setup file a normal show without any
75+
parameters will just do fine.
76+
77+
@sa ViewModel::show, SettingsViewModel::paramSettings, SettingsViewModel::paramSetupFile
78+
*/
79+
80+
/*!
81+
@fn QtMvvm::SettingsViewModel::loadSetup
82+
83+
@param frontend The name of the current frontend
84+
@returns The loaded settings setup
85+
86+
If loading fails an empty setup is returned. Logging is performed internally, so you can just
87+
proceed without error checking and show an empty settings dialog.
88+
*/
89+
90+
/*!
91+
@fn QtMvvm::SettingsViewModel::loadValue
92+
93+
@param key The full key of the settings entry to be loaded
94+
@param defaultValue a default value to return in case the value is not found in the settings
95+
@returns The value found under the given key
96+
97+
You can override this method if you want to support loading and saving settings from a
98+
different source then the normally used QSettings
99+
100+
@sa SettingsViewModel::saveValue, SettingsViewModel::resetValue
101+
*/
102+
103+
/*!
104+
@fn QtMvvm::SettingsViewModel::saveValue
105+
106+
@param key The full key of the settings entry to be saved
107+
@param value The value to be stored under the key
108+
109+
You can override this method if you want to support loading and saving settings from a
110+
different source then the normally used QSettings
111+
112+
@sa SettingsViewModel::loadValue, SettingsViewModel::resetValue
113+
*/
114+
115+
/*!
116+
@fn QtMvvm::SettingsViewModel::resetValue
117+
118+
@param key The full key of the settings entry to be resetted
119+
120+
You can override this method if you want to support loading and saving settings from a
121+
different source then the normally used QSettings
122+
123+
@sa SettingsViewModel::loadValue, SettingsViewModel::saveValue
124+
*/
125+
126+
/*!
127+
@fn QtMvvm::SettingsViewModel::callAction
128+
129+
@param key The key of the entry that triggered the action
130+
@param parameters A map with additional parameters for the action call
131+
132+
This method is called by the GUI when an entry with the
133+
@ref settings_xml_types_action "action" type is pressed by the user. The key is what would
134+
normally be used as the settings key. The parameters are deduced from the settings XML. See
135+
the type documentation for more details.
136+
137+
@sa @ref settings_xml_types_action
138+
*/

‎doc/settingsxml.dox‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,9 @@ type, for entry elements). It defines the actual type of for example the default
225225
- double or number
226226
- bool
227227
- QDateTime or datetime
228+
- @ref settings_xml_types_action
229+
- list or selection
230+
- radiolist
228231
- ...
229232

230233
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,
267270
be enough to create the desired filters. For example, you may want to show an element only on
268271
windows or on android when the material design is used. The resulting string would be:
269272
`windows|android&material`.
273+
274+
@subsection settings_xml_types_action action
275+
The action type is meant as a placeholder for a pressable button. An action edit will simply
276+
display a button or similar, and instead of representing a value in the settings, pressing it
277+
will trigger QtMvvm::SettingsViewModel::callAction. The Entries `key` attribute is passed as
278+
the first parameter to the method. The parameters can be specified by adding a `<Property>`
279+
to the entry with the key `args` and the type `object`. The property of this object are the
280+
elements of the map passed as the second parameter.
270281
*/
282+
283+
//! TODO add small sample code snippits?

‎doc/viewmodel.dox‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
/*!
2+
@class QtMvvm::ViewModel
3+
4+
The ViewModel is the primary class of the core library is must be implemented to create
5+
custom viewmodels to be shown via the mvvm mechanism. To create a custom viewmodel, simply
6+
implement this class and show the viewmodel via one of the show methods. Viewmodels presented
7+
that way support automatic injection via injectable properties.
8+
9+
@attention In order for a viewmodel be showble, it must implement an invokable constructor
10+
with a single QObject* parameter for the parent. It basically should look like this:
11+
@code{.cpp}
12+
Q_INVOKABLE explicit MyViewModel(QObject *parent = nullptr);
13+
@endcode
14+
15+
@sa CoreApp::show, #QTMVVM_INJECT
16+
*/
17+
18+
/*!
19+
@fn QtMvvm::ViewModel::onInit
20+
21+
@param params The parameters to initialize the viewmodel with
22+
23+
This method is called by the presenter right after creating the view and reparenting the
24+
viewmodel to the view. The parameters are the ones that have been passed to the show method
25+
called to show this viewmodel instance. Reimplement this method if you need to perform
26+
initializations after beeing assigned to a viewmodel or if you want to support a parametrized
27+
viewmodel.
28+
29+
@sa ViewModel::show, ViewModel::showForResult, CoreApp::show
30+
*/
31+
32+
/*!
33+
@fn QtMvvm::ViewModel::onResult
34+
35+
@param requestCode The request code of the show request for the viewmodel that triggered the
36+
result
37+
@param result The result passed from the viewmodel
38+
39+
When showing a child viewmodel via showForResult(), then the result of that show request is
40+
reported back via this function. The requestCode is the one that was passed to the
41+
showForResult() method, and the result what the viewmodel reported back. If the showed
42+
viewmodel emitted resultReady() before beeing destroyed, this value passed to that signal is
43+
whats reported as result. If the child viewmodel gets destroyed without ever emitting that
44+
signal, this method is still called, but with an invalid QVariant as result.
45+
46+
@sa ViewModel::showForResult, ViewModel::resultReady
47+
*/
48+
49+
/*!
50+
@fn QtMvvm::ViewModel::resultReady
51+
52+
@param result The result that should be passed to the parent viewmodel
53+
54+
Viewmodels that have been created via showForResult() must emit this signal to report back the
55+
result of the show request. Doing so will lead to the onResult() method of the showing
56+
viewmodel beeing with the emitted result as second parameter. Not emitting this signal before
57+
the viewmodel gets destroy leads to the onResult() beeing called with an invalid result.
58+
59+
@sa ViewModel::showForResult, ViewModel::onResult
60+
*/
61+
62+
/*!
63+
@fn QtMvvm::ViewModel::show(const QVariantHash &) const
64+
65+
@param params The show parameters to be passed to the created viewmodel
66+
67+
This method will send a show request to the core app to show a viewmodel of the given type.
68+
The parameters are passed to the onInit() method by the presenter after creating and parenting
69+
the view. The viewmodel will be shown asynchronously, so this method will return immediatly.
70+
71+
@sa ViewModel::showForResult, ViewModel::onInit, CoreApp::show
72+
*/
73+
74+
/*!
75+
@fn QtMvvm::ViewModel::show(const char *, const QVariantHash &) const
76+
77+
@param viewModelName The name of the viewmodel class to be shown
78+
@copydetails ViewModel::show(const QVariantHash &) const
79+
*/
80+
81+
/*!
82+
@fn QtMvvm::ViewModel::show(const QMetaObject *, const QVariantHash &) const
83+
84+
@param viewMetaObject The metaobject of the viewmodel class to be shown
85+
@copydetails ViewModel::show(const QVariantHash &) const
86+
*/
87+
88+
/*!
89+
@fn QtMvvm::ViewModel::showForResult(quint32, const QVariantHash &) const
90+
91+
@param requestCode The code of the show request
92+
@param params The show parameters to be passed to the created viewmodel
93+
94+
This method will send a show request to the core app to show a viewmodel of the given type.
95+
The parameters are passed to the onInit() method by the presenter after creating and parenting
96+
the view. The viewmodel will be shown asynchronously, so this method will return immediatly.
97+
The viewmodel is show for a result, meaning that a result is reported back via onInit() as
98+
soon as the shown viewmodel emits resultReady() or has been destroyed. The request code is
99+
passed to the onResult() method in order to identify the show request.
100+
101+
@sa ViewModel::show, ViewModel::onInit, ViewModel::resultReady, ViewModel::onResult,
102+
CoreApp::show
103+
*/
104+
105+
/*!
106+
@fn QtMvvm::ViewModel::showForResult(quint32, const char *, const QVariantHash &) const
107+
108+
@param viewModelName The name of the viewmodel class to be shown
109+
@copydetails ViewModel::showForResult(quint32, const QVariantHash &) const
110+
*/
111+
112+
/*!
113+
@fn QtMvvm::ViewModel::showForResult(quint32, const QMetaObject *, const QVariantHash &) const
114+
115+
@param viewMetaObject The metaobject of the viewmodel class to be shown
116+
@copydetails ViewModel::showForResult(quint32, const QVariantHash &) const
117+
*/

‎src/mvvmcore/settingsviewmodel.cpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,10 @@ void SettingsViewModel::resetValue(const QString &key)
7474
d->settings->remove(key);
7575
}
7676

77-
void SettingsViewModel::callAction(const QString &entryId, const QVariantMap &parameters)
77+
void SettingsViewModel::callAction(const QString &key, const QVariantMap &parameters)
7878
{
7979
Q_UNUSED(parameters)
80-
logWarning() << "Unknown action requested with entry id" << entryId
80+
logWarning() << "Unknown action requested with entry id" << key
8181
<< "and parameters" << parameters;
8282
}
8383

‎src/mvvmcore/settingsviewmodel.h‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,45 +13,65 @@
1313
namespace QtMvvm {
1414

1515
class SettingsViewModelPrivate;
16+
//! A ViewModel for a generic settings dialog based of an XML settings file
1617
class Q_MVVMCORE_EXPORT SettingsViewModel : public ViewModel
1718
{
1819
Q_OBJECT
1920

21+
//! Specifies if restoring the defaults is generally allowed
2022
Q_PROPERTY(bool canRestoreDefaults READ canRestoreDefaults CONSTANT)
23+
//! The message configuration to be used to for a dialog to ask for settings restore
2124
Q_PROPERTY(QtMvvm::MessageConfig restoreConfig READ restoreConfig CONSTANT)
2225

26+
//! The settings setup loader to use to create the settings dialog. Is an injected property
2327
Q_PROPERTY(QtMvvm::ISettingsSetupLoader* settingsSetupLoader READ settingsSetupLoader WRITE setSettingsSetupLoader NOTIFY settingsSetupLoaderChanged)
2428
QTMVVM_INJECT(QtMvvm::ISettingsSetupLoader*, settingsSetupLoader)
2529

2630
public:
31+
//! The parameter for a QSettings object for the onInit() method
2732
static const QString paramSettings;
33+
//! The parameter for a settings setup file for the onInit() method
2834
static const QString paramSetupFile;
2935

30-
static QVariantHash showParams(QSettings *settings = nullptr, const QString &setupFile = {});
36+
//! Generates show parameter to show a settings viewmodel via ViewModel::show
37+
static QVariantHash showParams(QSettings *settings, const QString &setupFile = {});
3138

39+
//! Invokable constructor
3240
Q_INVOKABLE explicit SettingsViewModel(QObject *parent = nullptr);
3341
~SettingsViewModel();
3442

43+
//! @readAcFn{SettingsViewModel::canRestoreDefaults}
3544
virtual bool canRestoreDefaults() const;
45+
//! @readAcFn{SettingsViewModel::restoreConfig}
3646
virtual QtMvvm::MessageConfig restoreConfig() const;
37-
47+
//! @readAcFn{SettingsViewModel::settingsSetupLoader}
3848
ISettingsSetupLoader* settingsSetupLoader() const;
49+
50+
//! Loads the settings setup of the prepared file for the given frontend
3951
SettingsElements::Setup loadSetup(const QString &frontend) const;
4052

53+
//! Returns the settings this viewmodel operates on
4154
QSettings *settings() const;
4255

56+
//! Loads the value for the given key from the settings
4357
Q_INVOKABLE virtual QVariant loadValue(const QString &key, const QVariant &defaultValue = {}) const;
58+
//! Saves the value with the given key
4459
Q_INVOKABLE virtual void saveValue(const QString &key, const QVariant &value);
60+
//! Resets the value or group identified by the key
4561
Q_INVOKABLE virtual void resetValue(const QString &key);
4662

4763
public Q_SLOTS:
48-
virtual void callAction(const QString &entryId, const QVariantMap &parameters);
64+
//! Is called when an action type edit is pressed
65+
virtual void callAction(const QString &key, const QVariantMap &parameters);
4966

67+
//! @writeAcFn{SettingsViewModel::settingsSetupLoader}
5068
void setSettingsSetupLoader(QtMvvm::ISettingsSetupLoader* settingsSetupLoader);
5169

5270
Q_SIGNALS:
71+
//! @notifyAcFn{SettingsViewModel::settingsSetupLoader}
5372
void settingsSetupLoaderChanged(QtMvvm::ISettingsSetupLoader* settingsSetupLoader);
5473

74+
//! Is emitted when the initialization has been completed and the viewmodel is ready for loading settings
5575
void beginLoadSetup();
5676

5777
protected:

0 commit comments

Comments
 (0)