From 918a9de7cbb33a5168a76f7f0832954fba283047 Mon Sep 17 00:00:00 2001 From: Skycoder42 Date: Thu, 8 Mar 2018 22:07:19 +0100 Subject: [PATCH] added coreapp doc --- README.md | 9 +- doc/coreapp.dox | 186 +++++++++++++++++++++++++++++++++++++++ doc/qtmvvm.dox | 41 +++++++++ src/mvvmcore/coreapp.cpp | 8 +- src/mvvmcore/coreapp.h | 2 +- 5 files changed, 237 insertions(+), 9 deletions(-) create mode 100644 doc/qtmvvm.dox diff --git a/README.md b/README.md index 68cabbc..689c092 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ The key features are: - Create ViewModels in the core application to prepare data for presentation without binding to any concret GUI - Functions to show messageboxes (info, warning, error, etc.) from your core app - Asynchronous, with result handling - - Supports input dialogs and file dialogs out of the box + - Supports input dialogs and native file dialogs out of the box + - Supports native file pickers on Android - custom dialog types can be created - Methods to create Two-Way Bindings from C++ and QML - Macros and a ServiceRegistry to make Dependency Injection possible for Services and ViewModels @@ -113,10 +114,10 @@ If you did install the module as module you can skip this part. To create a new ### Create and initialize the QtMvvm Project Follow the setup to create the project. You can select the GUI-frontends you want to use, as well as additional features. After that you get a basic project skeleton with a simple CoreApp and a ViewModel, as well as the corresponding views. -For more Details on these classes, check the [Documentation](https://skycoder42.github.io/QtMvvm/). +For more Details on these classes, check the [Documentation](https://skycoder42.github.io/QtMvvm/). ### Adding new ViewModels and Views -The most important part is to know how to add new ViewModels and Views. +The most important part is to know how to add new ViewModels and Views. #### Create the ViewModel - Add a new c++ class to your core project. Let it inherit from `QtMvvm::ViewModel` @@ -173,7 +174,7 @@ To create a presenter, the `QtMvvm::IPresenter` must be implemented and provided - The `QtMvvmApp` qml types automatically register themselves as presenter and perform the presentations - Supports Items as new fullscreen pages inside a stack view, as drawer or as tabs - Supports Popups as modal dialogs - - + - ## Icons In many of the UI projects default icons are used for the views (if no icon theme is present). They are taken from: diff --git a/doc/coreapp.dox b/doc/coreapp.dox index 8ba8815..6be23d4 100644 --- a/doc/coreapp.dox +++ b/doc/coreapp.dox @@ -46,4 +46,190 @@ int main(int argc, char *argv[]) { return app.exec(); // bootApp() is called as soon as the eventloop starts (and thus startApp()) } @endcode + +When using the app that way, a 3-step startup is performed: + +1. registerApp() and performRegistrations() are called as part of the QCoreApplication +constructor as first thing to register types etc. from the core application. +2. The rest of the main() in the GUI project runs to register further view related stuff and +register additional services etc. +3. The bootApp() and startApp() methods are called once the eventloop was entered in order to +actually start the application and show the first viewmodels. Once started, the appStarted() +signal is emitted as well. +*/ + +/*! +@fn QtMvvm::CoreApp::disableAutoBoot + +In case you don't want your application be be started automatically whenQCoreApplication::exec +is called, you must call this method **before** The QCoreApplication (or any other application) +constructor is called: + +@code{.cpp} +int main(int argc, char *argv[]) { + CoreApp::disableAutoBoot(); + QApplication app(argc, argv); + //... +} +@endcode + +In order to eventually start the app, simply call bootApp(). + +@sa CoreApp::bootApp, #QTMVVM_REGISTER_CORE_APP, CoreApp::registerApp +*/ + +/*! +@fn QtMvvm::CoreApp::registerApp + +@attention This method is called automatically by the #QTMVVM_REGISTER_CORE_APP macro. If you +use the macro, don't call this method explicitly! + +Internally it performs some initial registrations, calls performRegistrations() and then +schedules the automatic call of bootApp() if not disabled. + +@sa #QTMVVM_REGISTER_CORE_APP, CoreApp::performRegistrations, CoreApp::bootApp, +CoreApp::disableAutoBoot +*/ + +/*! +@fn QtMvvm::CoreApp::show(const QVariantHash &) + +@tparam TViewModel The type of the viewmodel to be presented +@param params A map of named parameters to be passed to the viewmodel + +Creates a new instance of the Viewmodel class, creates to corresponding view and then shows it. +This is done via the IPresenter that is currently registered. + +@sa ViewModel::show, CoreApp::showDialog +*/ + +/*! +@fn QtMvvm::CoreApp::show(const char *, const QVariantHash &) + +@param viewModelName The name of the viewmodel to be presented +@param params A map of named parameters to be passed to the viewmodel + +Creates a new instance of the Viewmodel class, creates to corresponding view and then shows it. +This is done via the IPresenter that is currently registered. + +@sa ViewModel::show, CoreApp::showDialog +*/ + +/*! +@fn QtMvvm::CoreApp::show(const QMetaObject *, const QVariantHash &) + +@param viewModelMetaObject The metaobject of the viewmodel to be presented +@param params A map of named parameters to be passed to the viewmodel + +Creates a new instance of the Viewmodel class, creates to corresponding view and then shows it. +This is done via the IPresenter that is currently registered. + +@sa ViewModel::show, CoreApp::showDialog +*/ + +/*! +@fn QtMvvm::CoreApp::showDialog + +@param config The configuration of the message to be shown +@returns A message result to keep track of the shown dialog + +The configuration is passed to the presenter in order to show a simple dialog. You can use the +returned object to monitor the dialog and receive the result. + +@note By default, the returned object will delete itself automatically once the dialog has +been closed. + +@sa CoreApp::show, MessageConfig, MessageResult +*/ + +/*! +@fn QtMvvm::CoreApp::bootApp + +@attention This method is called automatically by the #QTMVVM_REGISTER_CORE_APP macro or the +registerApp() method, unless it has been deactivated before with disableAutoBoot(). Unless you +disabled the boot that way, don't call this method explicitly! + +Internally it performs the actual start of the application and calls startApp() to start all +services and show the initial viewmodels. + +If startApp() returned successfully, appStarted() is emitted and thus the startup completed. + +@sa #QTMVVM_REGISTER_CORE_APP, CoreApp::startApp, CoreApp::disableAutoBoot, +CoreApp::appStarted +*/ + +/*! +@fn QtMvvm::CoreApp::performRegistrations + +Is called by registerApp() (and thus automatically when using the #QTMVVM_REGISTER_CORE_APP +macro) in order to perform initial registrations of types etc. before any such code is beeing +executed for the gui projects. + +@sa #QTMVVM_REGISTER_CORE_APP, CoreApp::registerApp, CoreApp::startApp +*/ + +/*! +@fn QtMvvm::CoreApp::startApp + +@param arguments The command line arguments that have been passed to the application +@return An exit code as a result of the startup code + +Is called by bootApp() (and thus automatically when using the #QTMVVM_REGISTER_CORE_APP +macro) in order to start the app logic and show initial viewmodels. Return `EXIT_SUCCESS` (0) +to indicate the start was successful. If any other value is returned, the application exits +with that value as return code. + +@sa CoreApp::autoParse, #QTMVVM_REGISTER_CORE_APP, CoreApp::bootApp, CoreApp::closeApp, +CoreApp::performRegistrations +*/ + +/*! +@fn QtMvvm::CoreApp::closeApp + +Is connected to the QCoreApplication::aboutToQuit signal and is called to clean up your +application. Using this method is more convenient as it is only called in case the startup +was successfull (returned `EXIT_SUCCESS`). + +@sa CoreApp::startApp +*/ + +/*! +@fn QtMvvm::CoreApp::autoParse + +@param parser A reference to the commandline parser to use +@param arguments The arguments to be parsed +@returns `true` If parsing was successfull and you can continue starting the App + +Use this method in your startApp() implementation in order to automatically handle special +cases: + +- Errors +- The Help option (`--help`) +- The Version option (`--version`) + +For those three cases `false` is returned and a dialog of the specific GUI shown to the user +with either and error string, the help or the version information. To correctly use it, your +startApp() function should look like this: + +@code{.cpp} +int MyApp::startApp(const QStringList &arguments) +{ + QCommandLineParser parser; + parser.addVersionOption(); + parser.addHelpOption(); + + //Add more options to setup the parser... + + //shows help or version automatically + if(!autoParse(parser, arguments)) + return EXIT_SUCCESS; + + // actual startup code... +} +@endcode + +@note It is important to return with `EXIT_SUCCESS` from the parser in order to actually show +the dialogs to the user. Returning any other value would simply silently quit the application. + +@sa CoreApp::startApp */ diff --git a/doc/qtmvvm.dox b/doc/qtmvvm.dox new file mode 100644 index 0000000..1b368ba --- /dev/null +++ b/doc/qtmvvm.dox @@ -0,0 +1,41 @@ +/*! +@namespace QtMvvm + +The following list shows which classes belong to which Qt module, in alphabetical order: + +- QtMvvmCore: + - Binding + - CoreApp + - IPresenter + - ISettingsSetupLoader + - MessageConfig + - MessageResult + - PresenterException + - ServiceConstructionException + - ServiceDependencyException + - ServiceExistsException + - ServiceRegistry + - SettingsLoaderException + - SettingsViewModel + - ViewModel + - All Methods not explicitly listed +- QtMvvmWidgets: + - InputWidgetFactory + - IPresentingView + - SettingsDialog + - WidgetsPresenter +- QtMvvmQuick: + - InputViewFactory + - QuickPresenter +- QtMvvmDataSyncCore: + - AccountModel + - DataSyncViewModel + - ExchangeDevicesModel + - NetworkExchangeViewModel +- QtMvvmDataSyncWidgets: + - DataSyncWindow + - NetworkExchangeWindow + - registerDataSyncWidgets() +- QtMvvmDataSyncQuick: + - registerDataSyncQuick() +*/ diff --git a/src/mvvmcore/coreapp.cpp b/src/mvvmcore/coreapp.cpp index 1a8c758..da711f6 100644 --- a/src/mvvmcore/coreapp.cpp +++ b/src/mvvmcore/coreapp.cpp @@ -54,14 +54,14 @@ void CoreApp::show(const char *viewModelName, const QVariantHash ¶ms) show(metaObject, params); } -void CoreApp::show(const QMetaObject *viewMetaObject, const QVariantHash ¶ms) +void CoreApp::show(const QMetaObject *viewModelMetaObject, const QVariantHash ¶ms) { - if(!viewMetaObject->inherits(&ViewModel::staticMetaObject)) { + if(!viewModelMetaObject->inherits(&ViewModel::staticMetaObject)) { throw PresenterException(QByteArrayLiteral("Given type (") + - viewMetaObject->className() + + viewModelMetaObject->className() + QByteArrayLiteral(") is not a class that extends QtMvvm::ViewModel")); } - showImp(viewMetaObject, params); + showImp(viewModelMetaObject, params); } MessageResult *CoreApp::showDialog(const MessageConfig &config) diff --git a/src/mvvmcore/coreapp.h b/src/mvvmcore/coreapp.h index 7940062..83fee3b 100644 --- a/src/mvvmcore/coreapp.h +++ b/src/mvvmcore/coreapp.h @@ -40,7 +40,7 @@ public: //! Show a new ViewModel by its name static void show(const char *viewModelName, const QVariantHash ¶ms = {}); //! Show a new ViewModel by its metaobject - static void show(const QMetaObject *viewMetaObject, const QVariantHash ¶ms = {}); + static void show(const QMetaObject *viewModelMetaObject, const QVariantHash ¶ms = {}); //! Show a basic dialog static MessageResult *showDialog(const MessageConfig &config);