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

Commit a3f19ba

Browse files
Skycoder42Skycoder42
committed
added widgets doc and quick main module doc
(no qml doc yet)
1 parent dda9335 commit a3f19ba

File tree

12 files changed

+443
-38
lines changed

12 files changed

+443
-38
lines changed

‎doc/inputviewfactory.dox‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
/*!
2+
@class QtMvvm::InputViewFactory
3+
4+
The factory is used by the QuickPresenter to create input views and delegates for various
5+
types. This is used to for example create the edits of input dialogs or for the list delegates
6+
of a SettingsView.
7+
8+
@sa QuickPresenter, QuickPresenter::inputViewFactory, MessageConfig::TypeInputDialog,
9+
QtMvvm::getInput, SettingsViewModel
10+
*/
11+
12+
/*!
13+
@fn QtMvvm::InputViewFactory::getInputUrl
14+
15+
@param type The input type to create a view for
16+
@param viewProperties A map with extra properties to be set on the edit
17+
@returns A url to a QML component suitable for editing input of the given type
18+
19+
The factory first checks if the given type is registered as alias. If yes, it continues with
20+
the aliased type. Then it checks for a url registered as simple view exists for the given
21+
type and uses that one if present. If no simple view is set the default mapping for type to
22+
urls is used (See MessageConfig::TypeInputDialog for a full table of supported types). If no
23+
url can be found for a type, an invalid url is returned.
24+
25+
The viewProperties are used to setup the created view by settings them as properties on the
26+
view. For every key-value-pair in the map, QObject::setProperty is called on the view to
27+
set the property.
28+
29+
@sa MessageConfig::TypeInputDialog, InputViewFactory::addSimpleInput,
30+
InputViewFactory::addInputAlias, InputViewFactory::getDelegate
31+
*/
32+
33+
/*!
34+
@fn QtMvvm::InputViewFactory::getDelegate
35+
36+
@param type The input type to create a delegate for
37+
@param viewProperties A map with extra properties to be set on the delegate
38+
@returns A url to a QML component suitable for editing input of the given type, as a delegate
39+
40+
Delegates can be used to provide "editabel" list items for ListViews. (For example, the
41+
SettingsView makes use of them). Available roles are:
42+
- group
43+
- key
44+
- type
45+
- title
46+
- tooltip
47+
- delegateUrl
48+
- inputValue
49+
- properties
50+
51+
The factory first checks if the given type is registered as alias. If yes, it continues with
52+
the aliased type. Then it checks for a url registered as simple delegate exists for the given
53+
type and uses that one if present. If no simple delegate is set the default mapping for type
54+
to urls is used (See MessageConfig::TypeInputDialog for a full table of supported types). If
55+
no url can be found for a type, the MsgDelegate is returned, which will simply show an input
56+
of the given type. Thus, for all not explicitly supported delegate types, the getInputUrl() is
57+
used to find an edit for the dialog.
58+
59+
The viewProperties are used to setup the created delegate by settings them as properties on
60+
the delegate. For every key-value-pair in the map, QObject::setProperty is called on the
61+
delegate to set the property.
62+
63+
@sa MessageConfig::TypeInputDialog, InputViewFactory::addSimpleDelegate,
64+
InputViewFactory::addDelegateAlias, InputViewFactory::getInputUrl
65+
*/
66+
67+
/*!
68+
@fn QtMvvm::InputViewFactory::addSimpleInput(const QUrl &)
69+
70+
@tparam TType The type to add an input view for
71+
@param qmlFileUrl The URL of the QML file that contains the component
72+
73+
The qmlFileUrl must be a valid URL to a QML file with a displayable quick item. The item must
74+
have a property named `inputValue` that is used to read and write the edit data.
75+
76+
@sa InputViewFactory::getInputUrl, InputViewFactory::addInputAlias
77+
*/
78+
79+
/*!
80+
@fn QtMvvm::InputViewFactory::addSimpleInput(const QByteArray &, const QUrl &)
81+
82+
@param type The type to add an input view for
83+
@param qmlFileUrl The URL of the QML file that contains the component
84+
85+
The qmlFileUrl must be a valid URL to a QML file with a displayable quick item. The item must
86+
have a property named `inputValue` that is used to read and write the edit data.
87+
88+
@sa InputViewFactory::getInputUrl, InputViewFactory::addInputAlias
89+
*/
90+
91+
/*!
92+
@fn QtMvvm::InputViewFactory::addSimpleDelegate(const QUrl &)
93+
94+
@tparam TType The type to add a delegate view for
95+
@param qmlFileUrl The URL of the QML file that contains the component
96+
97+
The qmlFileUrl must be a valid URL to a QML file with a displayable quick item that can be
98+
used as a delegate for a ListView.
99+
100+
@sa InputViewFactory::getDelegate, InputViewFactory::addDelegateAlias
101+
*/
102+
103+
/*!
104+
@fn QtMvvm::InputViewFactory::addSimpleDelegate(const QByteArray &, const QUrl &)
105+
106+
@param type The type to add a delegate view for
107+
@param qmlFileUrl The URL of the QML file that contains the component
108+
109+
The qmlFileUrl must be a valid URL to a QML file with a displayable quick item that can be
110+
used as a delegate for a ListView.
111+
112+
@sa InputViewFactory::getDelegate, InputViewFactory::addDelegateAlias
113+
*/
114+
115+
/*!
116+
@fn QtMvvm::InputViewFactory::addInputAlias()
117+
118+
@tparam TAliasType The type to add as a new alias
119+
@tparam TTargetType The type the alias should be translated to
120+
121+
If an input view for the alias type is requested, one of the target type is created instead.
122+
123+
@sa InputViewFactory::getInputUrl, InputViewFactory::addSimpleInput
124+
*/
125+
126+
/*!
127+
@fn QtMvvm::InputViewFactory::addInputAlias(const QByteArray &, const QByteArray &)
128+
129+
@param alias The type to add as a new alias
130+
@param targetType The type the alias should be translated to
131+
132+
If an input view for the alias type is requested, one of the target type is created instead.
133+
134+
@sa InputViewFactory::getInputUrl, InputViewFactory::addSimpleInput
135+
*/
136+
137+
/*!
138+
@fn QtMvvm::InputViewFactory::addDelegateAlias()
139+
140+
@tparam TAliasType The type to add as a new alias
141+
@tparam TTargetType The type the alias should be translated to
142+
143+
If an delegate view for the alias type is requested, one of the target type is created
144+
instead.
145+
146+
@sa InputViewFactory::getDelegate, InputViewFactory::addSimpleDelegate
147+
*/
148+
149+
/*!
150+
@fn QtMvvm::InputViewFactory::addDelegateAlias(const QByteArray &, const QByteArray &)
151+
152+
@param alias The type to add as a new alias
153+
@param targetType The type the alias should be translated to
154+
155+
If an delegate view for the alias type is requested, one of the target type is created
156+
instead.
157+
158+
@sa InputViewFactory::getDelegate, InputViewFactory::addSimpleDelegate
159+
*/

‎doc/inputwidgetfactory.dox‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,10 @@ InputWidgetFactory::addAlias
3939
@tparam TWidget The type of the widget to provide for that type
4040

4141
The TWidget type must extend QWidget and have a constructor that takes a single `QWidget*` as
42-
argument.
42+
argument. It furthermore needs to have a USER property, which is used to read and write the
43+
input value.
4344

44-
@sa MessageConfig::createInput, InputWidgetFactory::addAlias
45+
@sa InputWidgetFactory::createInput, InputWidgetFactory::addAlias
4546
*/
4647

4748
/*!
@@ -51,9 +52,10 @@ argument.
5152
@param creator A function that creates a new instance of a widget for the given type
5253

5354
The `QWidget*` argument of the creator function must be used as the parent of the created
54-
widget that is returned by the function.
55+
widget that is returned by the function. It furthermore needs to have a USER property, which is
56+
used to read and write the input value.
5557

56-
@sa MessageConfig::createInput, InputWidgetFactory::addAlias
58+
@sa InputWidgetFactory::createInput, InputWidgetFactory::addAlias
5759
*/
5860

5961
/*!
@@ -64,7 +66,7 @@ widget that is returned by the function.
6466

6567
If an input widget for the alias type is requested, one of the target type is created instead.
6668

67-
@sa MessageConfig::createInput, InputWidgetFactory::addSimpleWidget
69+
@sa InputWidgetFactory::createInput, InputWidgetFactory::addSimpleWidget
6870
*/
6971

7072
/*!
@@ -75,5 +77,5 @@ If an input widget for the alias type is requested, one of the target type is cr
7577

7678
If an input widget for the alias type is requested, one of the target type is created instead.
7779

78-
@sa MessageConfig::createInput, InputWidgetFactory::addSimpleWidget
80+
@sa InputWidgetFactory::createInput, InputWidgetFactory::addSimpleWidget
7981
*/

‎doc/message.dox‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -228,22 +228,25 @@ via QVariant can be used as input value. However, only for the most common types
228228
edit views exist. In case you want to use types not present in the list below, you need to
229229
create edit views yourself
230230

231-
Type | Widgets edit | Quick edit
232-
------------------------|-------------------------------|------------
233-
bool | QCheckBox | CheckBox
234-
switch | -/- | Switch
235-
QString, string | QLineEdit | TextField
236-
int | QSpinBox | SpinBox
237-
double, number | QDoubleSpinBox | DoubleSpinBox
238-
QDate | QDateEdit | -/-
239-
QTime | QTimeEdit | -/-
240-
QDateTime, date | QDateTimeEdit | -/-
241-
QFont | QFontComboBox | FontEdit
242-
QKeySequence | QKeySequenceEdit | -/-
243-
QUrl, url | QLineEdit with QUrlValidator | UrlField
244-
selection, list | QComboBox | ListEdit
245-
radiolist | -/- | RadioListEdit
246-
action (settings only) | QPushButton | ItemDelegate
231+
Type | Widgets edit | Quick edit | Quick delegate
232+
------------------------|-------------------------------|---------------|----------------
233+
bool | QCheckBox | CheckBox | BoolDelegate
234+
switch | -/- | Switch | SwitchDelegate
235+
QString, string | QLineEdit | TextField | MsgDelegate (*)
236+
int | QSpinBox | SpinBox | MsgDelegate
237+
double, number | QDoubleSpinBox | DoubleSpinBox | MsgDelegate
238+
QDate | QDateEdit | -/- | -/-
239+
QTime | QTimeEdit | -/- | -/-
240+
QDateTime, date | QDateTimeEdit | -/- | -/-
241+
QFont | QFontComboBox | FontEdit | MsgDelegate
242+
QKeySequence | QKeySequenceEdit | -/- | -/-
243+
QUrl, url | QLineEdit with QUrlValidator | UrlField | MsgDelegate
244+
selection, list | QComboBox | ListEdit | ListDelegate
245+
radiolist | -/- | RadioListEdit | -/-
246+
action (settings only) | QPushButton | -/- | ItemDelegate
247+
248+
(*) The MsgDelegate is used for any type but the ones that have explicit delegates. It will
249+
show a dialog with an input of the "Quick edit" column
247250

248251
The following types have special properties as well:
249252

‎doc/qtmvvm.dox‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,14 @@ The following list shows which classes belong to which Qt module, in alphabetica
5050

5151
<b>Current Version</b><br/>
5252
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.0
53+
54+
<b>Available Types</b>
55+
- @ref QtMvvm::MessageConfig "MessageConfig" (uncreatable)
56+
- @ref QtMvvm::MessageResult "MessageResult" (uncreatable)
57+
- MvvmBinding
58+
- Message (singleton)
59+
- @ref QtMvvm::SettingsViewModel "SettingsViewModel" (uncreatable)
60+
- @ref QtMvvm::ViewModel "ViewModel" (uncreatable)
5361
*/
5462

5563
/*!

‎doc/quickpresenter.dox‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
/*!
2+
@class QtMvvm::QuickPresenter
3+
4+
This presenter is automatically registered as the default presenter for the IPresenter
5+
interface with the ServiceRegistry, but as weak service, in order to make it possible to
6+
overwrite it.
7+
8+
The class handles all the logic required for presenting Quick Controsl 2 based views. You can
9+
extend this class and reimplement it's virtual methods if you need to adjust how certain views
10+
or dialogs are presented, or if you want to support custom stuff.
11+
12+
By default, the presenter will use the `":/qtmvvm/views"` directory for finding views. When
13+
presenting a viewmodel, the presenter tries to find a view url with a matching name. If the
14+
viewmodel is for example named `MyViewModel`, then the view must start with `My` too. For
15+
example it can be named `MyView.qml` or `MyDialog.qml`
16+
17+
@note Implicit detection of views for viewmodels can sometimes lead to ambiguities and thus a
18+
wrong view beeing found. In such cases, use registerViewExplicitly() instead.
19+
*/
20+
21+
/*!
22+
@property QtMvvm::QuickPresenter::inputViewFactory
23+
24+
@default{<i>Injected</i>}
25+
26+
Do not set this property yourself. It is automatically injected when showing the viewmodel.
27+
You can use the ServiceRegistry::registerInterface if you need to use a factory different from
28+
the default one.
29+
30+
@accessors{
31+
@readAc{inputViewFactory()}
32+
@writeAc{setInputViewFactory()}
33+
@notifyAc{inputViewFactoryChanged()}
34+
}
35+
36+
@sa #QTMVVM_INJECT
37+
*/
38+
39+
/*!
40+
@fn QtMvvm::QuickPresenter::addViewSearchDir
41+
42+
@param dirPath A path to directory to be searched for input views
43+
44+
Simply adds the directory to the ones beeing searched for views. The new directoy will be
45+
prepended to the search list and thus be searched before any other directory.
46+
47+
@sa QuickPresenter::registerViewExplicitly
48+
*/
49+
50+
/*!
51+
@fn QtMvvm::QuickPresenter::registerViewExplicitly(const QUrl &)
52+
53+
@tparam TViewModel The viewmodel to to register the view for
54+
@param viewUrl The QML url register within the presenter. Must be a valid qml component
55+
56+
The url is registered with the current presenter. It is registered explicitly, which means
57+
that whenever the given viewmodel is beeing presented, this exact url will be used. Explicit
58+
registration have precedence over implicit ones.
59+
60+
@sa QuickPresenter::addViewSearchDir
61+
*/
62+
63+
/*!
64+
@fn QtMvvm::QuickPresenter::registerViewExplicitly(const QMetaObject *, const QUrl &)
65+
66+
@param viewModelType The viewmodel to to register the view for
67+
@param viewUrl The QML url register within the presenter. Must be a valid qml component
68+
69+
The url is registered with the current presenter. It is registered explicitly, which means
70+
that whenever the given viewmodel is beeing presented, this exact url will be used. Explicit
71+
registration have precedence over implicit ones.
72+
73+
@sa QuickPresenter::addViewSearchDir
74+
*/
75+
76+
/*!
77+
@fn QtMvvm::QuickPresenter::presentToQml
78+
79+
@param qmlPresenter The presenter to present the view to
80+
@param viewObject The view QML object to be presented
81+
@returns `true` if successfully presented, `false` if not
82+
83+
Is called from the qml presentation part to actually present a view to another view that takes
84+
the role of a presenter, or the actual main presenter.
85+
86+
The default implementation uses presentMethodIndex() to find a method to call, then calls it
87+
and returns the result of that method call. If no method was found, false is returned.
88+
89+
@sa QuickPresenter::presentMethodIndex
90+
*/
91+
92+
/*!
93+
@fn QtMvvm::QuickPresenter::findViewUrl
94+
95+
@param viewModelType The metobject of the viewmodel to find a view for
96+
@returns The URL of the found file
97+
@throws PresenterException If no view url could be found
98+
99+
The default implementation simply check all explicitly registered views and then tries to
100+
match the name with all qml files available in the search dirs. If no match if found, the
101+
same is tried for the parent viewmodel type recursively, until the ViewModel base is reached.
102+
103+
@sa QuickPresenter::addViewSearchDir
104+
*/
105+
106+
/*!
107+
@fn QtMvvm::QuickPresenter::presentMethodIndex
108+
109+
@param presenterMetaObject The metobject of the presenter to search a method on
110+
@param viewObject The QML item to be presented on that presenter
111+
@returns The index of the method from the meta object to be called, or `-1` if no method could
112+
be found.
113+
114+
This method is called to find the method. The method must take a single argument, the view to
115+
be presented, and return a bool to report whether presenting actually worked or not. The
116+
default implementation first checks if the view extends QQuickPopup, and if yes looks for the
117+
`presentPopup` method. If the view is a normal QQuickItem, the name is analyzed. If the name
118+
contains `Drawer`, the `presentDrawerContent` method is checkd. If the name contains `Tab`,
119+
the `presentTab` method is checkd. If none applies or none was found, the method looks for the
120+
`presentItem` method. If that one is not found as well, `-1 is returned.
121+
122+
@sa QuickPresenter::presentToQml
123+
*/
124+
125+
/*!
126+
@fn QtMvvm::QuickPresenter::nameOrClassContains
127+
128+
@param obj The object to search for the string
129+
@param contained The string to be searched
130+
@param caseSensitive Specifies if the check should be case sensitive
131+
@returns `true` if the object or class name contain the string, `false` if not
132+
*/

0 commit comments

Comments
 (0)