QtMvvm/doc/viewmodel.dox

/*!
@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
*/