You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
151 lines
6.5 KiB
151 lines
6.5 KiB
/*!
|
|
@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
|
|
|
|
@section qtmvvm_viewmodel_singleton "Singleton Viewmodels"
|
|
Normally, showing a viewmodel will always create a new instance of it, and thus show a new
|
|
gui. However, by adding the #QTMVVM_SINGLETON macro to the class definition, your viewmodel
|
|
becomes a single instance. This means, it will only be created once, and subsequent show
|
|
requests will instead only trigger the instanceInvoked() signal on the existing instance.
|
|
|
|
If the existing instance gets destroyed at some point, show requests will show a new instance.
|
|
|
|
@section qtmvvm_viewmodel_container "Container Viewmodels"
|
|
Some viewmodel require a special viewmodel as their parent to be show in. To simplify the
|
|
handling of those viewmodel, you can specify a parent container for a viewmodel via the
|
|
#QTMVVM_CONTAINER_VM macro. If added, everytime you try to show a viewmodel of this kind, the
|
|
presenter will first create a new viewmodel of the type specified by the macro, and then
|
|
show the original viewmodel immediatly after as child of the newly created parent. (The parent
|
|
and the child can both be singletons)
|
|
|
|
You can specify parameters to be passed to the parent that is to be created via a special
|
|
parameter named `"qtmvvm_container_params"`. The value of that property must be a variant hash
|
|
as well. In addition, a special parameter is added to the parent parameter, the
|
|
`"qtmvvm_container_for"` parameter, which contains the name of the viewmodel that triggered
|
|
its creation.
|
|
|
|
@sa CoreApp::show, #QTMVVM_INJECT, #QTMVVM_SINGLETON, #QTMVVM_CONTAINER_VM
|
|
*/
|
|
|
|
/*!
|
|
@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::instanceInvoked
|
|
|
|
@param params The show parameters that were passed to the show method
|
|
|
|
If this viewmodel is a single instance viewmodel (#QTMVVM_SINGLETON), then only the first show
|
|
will actually create a viewmodel. All subsequent shows for that type will instead trigger this
|
|
signal on the existing instance.
|
|
|
|
@sa #QTMVVM_SINGLETON, @ref qtmvvm_viewmodel_singleton
|
|
*/
|
|
|
|
/*!
|
|
@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
|
|
*/
|
|
|