diff --git a/doc/Doxyfile b/doc/Doxyfile index cddd903..b0d3b4a 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -252,6 +252,7 @@ ALIASES = "accessors{1}=< "constantAc=" \ "readonlyAc=" \ "finalAc=" \ + "defaultAc=" \ "default{1}=Default: \1
" \ "readAcFn{1}=READ accessor for \1" \ "writeAcFn{1}=WRITE accessor for \1" \ @@ -905,6 +906,7 @@ EXCLUDE = ../src/3rdparty \ ../src/imports/mvvmquick/InputDialog.qml \ ../src/imports/mvvmquick/ListSection.qml \ ../src/imports/mvvmquick/OverviewListView.qml \ + ../src/imports/mvvmquick/SectionListView.qml \ ../src/imports/mvvmquick/AndroidFileDialog.qml \ ../src/imports/mvvmquick/AndroidFolderDialog.qml diff --git a/doc/makedoc.sh b/doc/makedoc.sh index 87f2471..2cedc74 100755 --- a/doc/makedoc.sh +++ b/doc/makedoc.sh @@ -41,9 +41,20 @@ if [ "$DOXY_STYLE_EXTRA" ]; then fi for tagFile in $(find "$qtDocs" -name *.tags); do - if [ $(basename "$tagFile") != "qtmvvm.tags" ]; then - echo "TAGFILES += \"$tagFile=https://doc.qt.io/qt-5\"" >> $doxyRes - fi + case $(basename "$tagFile") in + qtjsonserializer.tags) + echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtJsonSerializer\"" >> $doxyRes + ;; + qtdatasync.tags) + echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtDataSync\"" >> $doxyRes + ;; + qtmvvm.tags|qtquickcontrols.tags) + # skipped + ;; + *) + echo "TAGFILES += \"$tagFile=https://doc.qt.io/qt-5\"" >> $doxyRes + ;; + esac done cd "$srcDir" diff --git a/src/imports/mvvmcore/qqmlmvvmbinding.h b/src/imports/mvvmcore/qqmlmvvmbinding.h index ab5be71..4fcb3fd 100644 --- a/src/imports/mvvmcore/qqmlmvvmbinding.h +++ b/src/imports/mvvmcore/qqmlmvvmbinding.h @@ -11,6 +11,7 @@ namespace de::skycoder42::QtMvvm::Core { /*! @brief A QML class to create a local mvvm multiway binding * + * @extends QtQml.QtObject * @since 1.0 * * It is basically a wrapper around the QtMvvm::bind method. The parameters are set via the diff --git a/src/imports/mvvmcore/qqmlmvvmmessage.h b/src/imports/mvvmcore/qqmlmvvmmessage.h index 51b7422..1fa3343 100644 --- a/src/imports/mvvmcore/qqmlmvvmmessage.h +++ b/src/imports/mvvmcore/qqmlmvvmmessage.h @@ -14,6 +14,7 @@ namespace de::skycoder42::QtMvvm::Core { /*! @brief A QML signelton to access the QtMvvm namespace methods for showing simple dialogs * + * @extends QtQml.QtObject * @since 1.0 * * @sa QtMvvm::MessageConfig, QtMvvm::CoreApp::showDialog diff --git a/src/imports/mvvmquick/ActionButton.qml b/src/imports/mvvmquick/ActionButton.qml index 7c5c69c..f75080f 100644 --- a/src/imports/mvvmquick/ActionButton.qml +++ b/src/imports/mvvmquick/ActionButton.qml @@ -2,9 +2,27 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief An extension of the @ref QtQuick.Controls.ToolButton "ToolButton" for better appearance + * + * @extends QtQuick.Controls.ToolButton + * + * @details This version basically adjusts size, icon size and text display to look better and + * fit the Material guidelines. It also adds a tooltip that can be shown via a long press + * + * @sa ContrastToolBar, MenuButton + */ ToolButton { id: _toolButton + /*! @brief A toolTip to be shown when the button is long pressed + * + * @default{`ToolButton.text` (binding)} + * + * @accessors{ + * @memberAc{toolTip} + * @notifyAc{toolTipChanged()} + * } + */ property string toolTip: _toolButton.text display: AbstractButton.IconOnly diff --git a/src/imports/mvvmquick/AlertDialog.qml b/src/imports/mvvmquick/AlertDialog.qml index 19865ac..6976167 100644 --- a/src/imports/mvvmquick/AlertDialog.qml +++ b/src/imports/mvvmquick/AlertDialog.qml @@ -2,10 +2,44 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import QtQuick.Window 2.2 +/*! @brief An extension of the @ref QtQuick.Controls.Dialog "Dialog" for better appearance + * + * @extends QtQuick.Controls.Dialog + * + * @details This version basically adjusts size and makes shure the dialog always appears in + * center of the application. It even takes a possible input method into accout + */ Dialog { id: _alertDialog + /*! @brief Additional hight to give to the dialog + * + * @default{`0`} + * + * The dialog basically assumes that the parent is it's normal height plus this value. The + * combined height is then used to calculate where to show the dialog. Can be used if the + * parent does not fill up the whole application. + * + * @accessors{ + * @memberAc{extraHeight} + * @notifyAc{extraHeightChanged()} + * } + */ property real extraHeight: 0 + /*! @brief The ideal basic width of the dialog + * + * @default{`300`} + * + * Typically, the dialogs width is deduces by using the implicitWidth of it's contents and + * is limited to the parents width. Howver some contents have no useful implicit width. + * With this property, the dialog will try to be at least `baseWidth` or the contents + * implicitWidth wide, whichever is bigger. + * + * @accessors{ + * @memberAc{baseWidth} + * @notifyAc{baseWidthChanged()} + * } + */ property real baseWidth: 300 x: parent ? (parent.width - width) / 2 : 0 @@ -15,6 +49,16 @@ Dialog { modal: true focus: true + /*! @brief A function that calculates the value for the y coordiante + * + * @return type:real A value to be used as the `y` property value + * + * The value is calculated by taking the parent heigth, the dialog height, the input method + * height and the extraHeight into account. I is calculated to center the dialog in the + * parent. + * + * @sa Dialog::extraHeight + */ function deltaY() { var unscaled = Qt.inputMethod.keyboardRectangle.height / Screen.devicePixelRatio; var availHeight = (parent.height + extraHeight) - unscaled - 24; //margins diff --git a/src/imports/mvvmquick/ContrastToolBar.qml b/src/imports/mvvmquick/ContrastToolBar.qml index 4a69d36..c6a09a0 100644 --- a/src/imports/mvvmquick/ContrastToolBar.qml +++ b/src/imports/mvvmquick/ContrastToolBar.qml @@ -2,11 +2,32 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import QtQuick.Controls.Material 2.3 +/*! @brief An extension of the @ref QtQuick.Controls.ToolBar "ToolBar" for better appearance + * + * @extends QtQuick.Controls.ToolBar + * + * @details This version basically adjusts size and text color of the toolbar itself and + * controls within the toolbar to look better and improve contrast + * + * @sa ActionButton, ToolBarLabel, MenuButton + */ ToolBar { id: _contrastToolBar height: 56 + /*! @brief Calculates the optimal text color based on the background color + * + * @param type:color accentColor The color to find a contrasting text color for + * @param type:color baseColor The current default text color + * @return type:color A color for text that is easy to read when used with accentColor as + * the background + * + * The method calculates whether the color should be light or dark and then either returns + * white or black, depending on which color fits better. If baseColor is specified, then + * the color value is checked, too. If baseColor is easily readable, it is simply returned + * as result. Otherwise the method proceeds as usual. + */ function accentTextColor(accentColor, baseColor) { var a = (0.299 * accentColor.r + 0.587 * accentColor.g + 0.144 * accentColor.b); if(typeof baseColor !== "undefined") { diff --git a/src/imports/mvvmquick/DialogPresenter.qml b/src/imports/mvvmquick/DialogPresenter.qml index b28216c..3c7fa1e 100644 --- a/src/imports/mvvmquick/DialogPresenter.qml +++ b/src/imports/mvvmquick/DialogPresenter.qml @@ -3,11 +3,69 @@ import QtQuick.Controls 2.3 import de.skycoder42.QtMvvm.Core 1.0 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief A presentation helper that can present generic mvvm dialogs + * + * @extends QtQml.QtObject + * + * @details You can use this class as presenter for dialogs in case you create your own root + * presenter instead of using the QtMvvmApp. This partial presenter can handle simple dialogs + * (the ones shown via QtMvvm::CoreApp::showDialog). Use it as follows: + * + * @code{.qml} + * MyPresenter { + * id: _root + * + * DialogPresenter { + * id: _rootDialogs + * rootItem: _root.contentItem + * } + * + * function showDialog(config, result) { + * return _rootDialogs.showDialog(config, result); + * } + * + * function closeAction() { + * var closed = false; + * // ... + * if(!closed) + * closed = _rootDialogs.closeAction(); + * // ... + * return closed; + * } + * } + * @endcode + * + * @sa QtMvvmApp + */ QtObject { id: _dialogPresenter + /*! @brief The root item to present dialogs to + * + * @default{`null`} + * + * This propety **must** be set in order for the presenter to work. It will create new + * dialogs with that item as parent, which decides in which relative are they are + * displayed. Unless you want to explicitly reposition dialogs, this should always be the + * root item of the root component of your application. + * + * @accessors{ + * @memberAc{rootItem} + * @notifyAc{rootItemChanged()} + * } + */ property Item rootItem: null + /*! @brief The primary presenting method to present a dialog + * + * @param type:MessageConfig config The message configuration to create a dialog of + * @param type:MessageResult result The result to report the dialog result to + * @return type:bool `true` if successfully presented, `false` if not + * + * Use this method in your main presenter to present dialogs via this sub presenter. + * + * @sa QtMvvm::MessageConfig, QtMvvm::MessageResult, QtMvvmApp::showDialog + */ function showDialog(config, result) { if(config.type == "msgbox") return createMsgBox(config, result) @@ -19,6 +77,15 @@ QtObject { return false; } + /*! @brief Can be called to try to close open dialogs + * + * @return type:bool `true` if a dialog was closed, `false` if not + * + * Use this method in your main presenter react on a close event. It will close the + * latest top level dialog, if one is present. + * + * @sa QtMvvmApp::closeAction + */ function closeAction() { if(_popups.length > 0) { _popups[_popups.length - 1].reject(); @@ -27,7 +94,9 @@ QtObject { return false; } + //! Internal property property var _popups: [] + //! Internal property property Component _msgBoxComponent: MsgBox { id: __msgBox @@ -45,6 +114,7 @@ QtObject { } } + //! Internal property property Component _inputComponent: InputDialog { id: __input @@ -62,6 +132,7 @@ QtObject { } } + //! Internal property property Component _fileComponent: FileDialog { id: __file @@ -79,6 +150,7 @@ QtObject { } } + //! Internal property property Component _folderComponent: FolderDialog { id: __folder @@ -96,6 +168,18 @@ QtObject { } } + /*! @brief Method present a dialog of the QtMvvm::MessageConfig::TypeMessageBox + * + * @param type:MessageConfig config The message configuration to create a dialog of + * @param type:MessageResult result The result to report the dialog result to + * @return type:bool `true` if successfully presented, `false` if not + * + * Used by the showDialog() method to show a dialog of the message box type. You can use + * it yourself if you want to extend the presenter and still keep the default dialogs it + * supports. + * + * @sa DialogPresenter::showDialog + */ function createMsgBox(config, result) { var props = config.viewProperties; props["msgConfig"] = config; @@ -104,6 +188,18 @@ QtObject { return incubator.status !== Component.Error; } + /*! @brief Method present a dialog of the QtMvvm::MessageConfig::TypeInputDialog + * + * @param type:MessageConfig config The message configuration to create a dialog of + * @param type:MessageResult result The result to report the dialog result to + * @return type:bool `true` if successfully presented, `false` if not + * + * Used by the showDialog() method to show a dialog of the input dialog type. You can use + * it yourself if you want to extend the presenter and still keep the default dialogs it + * supports. + * + * @sa DialogPresenter::showDialog + */ function createInput(config, result) { var props = config.viewProperties; props["msgConfig"] = config; @@ -112,6 +208,18 @@ QtObject { return incubator.status !== Component.Error; } + /*! @brief Method present a dialog of the QtMvvm::MessageConfig::TypeFileDialog + * + * @param type:MessageConfig config The message configuration to create a dialog of + * @param type:MessageResult result The result to report the dialog result to + * @return type:bool `true` if successfully presented, `false` if not + * + * Used by the showDialog() method to show a dialog of the file dialog type. You can use + * it yourself if you want to extend the presenter and still keep the default dialogs it + * supports. + * + * @sa DialogPresenter::showDialog + */ function createFile(config, result) { var props = config.viewProperties; props["msgConfig"] = config; diff --git a/src/imports/mvvmquick/FileDialog.qml b/src/imports/mvvmquick/FileDialog.qml index f647e4f..2b0f652 100644 --- a/src/imports/mvvmquick/FileDialog.qml +++ b/src/imports/mvvmquick/FileDialog.qml @@ -4,13 +4,64 @@ import Qt.labs.platform 1.0 as Labs import de.skycoder42.QtMvvm.Core 1.0 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief A file dialog implementation based on the labs file dialog + * + * @extends Qt.labs.platform.FileDialog + * @extends FileChooser + * + * @details It is used internally by the DialogPresenter to create a file dialog for the file + * dialog message type + * + * @note On Android, the dialog extends the FileChooser. For all other platforms, it extends + * the @ref Qt.labs.platform.FileDialog "Qt labs FileDialog" + */ Labs.FileDialog { id: _fileDialog + /*! @brief The QtMvvm::MessageConfig to configure the dialog with + * + * @default{`undefined`} + * + * Various properties are bound to the config to create the dialogs appearance from it. + * + * @accessors{ + * @memberAc{msgConfig} + * @notifyAc{msgConfigChanged()} + * } + * + * @sa QtMvvm::MessageConfig + */ property var msgConfig + /*! @brief The QtMvvm::MessageResult to report the result to + * + * @default{`undefined`} + * + * The dialogs results are reported back to the core app via this result + * + * @accessors{ + * @memberAc{msgResult} + * @notifyAc{msgResultChanged()} + * } + * + * @sa QtMvvm::MessageResult + */ property MessageResult msgResult + /*! @brief A QStringList of mime type names to use as filter + * + * @default{Empty} + * + * Can be set as view property in the message config to limit the selectable files to the + * ones that match the given list of mimetypes. Unlike the android variant, normal file + * dialogs do not accept wildcard mime types. + * + * @accessors{ + * @memberAc{mimeTypes} + * @notifyAc{mimeTypesChanged()} + * } + */ property var mimeTypes + //! Is emitted when the dialog has been closed for any reason signal closed() title: msgConfig.title diff --git a/src/imports/mvvmquick/FolderDialog.qml b/src/imports/mvvmquick/FolderDialog.qml index c4f3b4a..842e3b8 100644 --- a/src/imports/mvvmquick/FolderDialog.qml +++ b/src/imports/mvvmquick/FolderDialog.qml @@ -4,12 +4,26 @@ import Qt.labs.platform 1.0 as Labs import de.skycoder42.QtMvvm.Core 1.0 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief A folder dialog implementation based on the labs folder dialog + * + * @extends Qt.labs.platform.FolderDialog + * @extends FileChooser + * + * @details It is used internally by the DialogPresenter to create a folder dialog for the file + * dialog message type + * + * @note On Android, the dialog extends the FileChooser. For all other platforms, it extends + * the @ref Qt.labs.platform.FolderDialog "Qt labs FolderDialog" + */ Labs.FolderDialog { id: _folderDialog + //! @copydoc FileDialog::msgConfig property var msgConfig + //! @copydoc FileDialog::msgResult property MessageResult msgResult + //! @copydoc FileDialog::closed signal closed() title: msgConfig.title diff --git a/src/imports/mvvmquick/MenuButton.qml b/src/imports/mvvmquick/MenuButton.qml index 745d110..45ba345 100644 --- a/src/imports/mvvmquick/MenuButton.qml +++ b/src/imports/mvvmquick/MenuButton.qml @@ -2,6 +2,29 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief An extension of the ActionButton to provide a simple "more menu" button + * + * @details The button already has a text, icon and tooltip and it will automatically display + * a context menu when pressed. Add the menu items as the children of the button: + * + * @code{.qml} + * MenuButton { + * id: mButton + * + * MenuItem { + * text: "Copy" + * } + * + * MenuItem { + * text: "Paste" + * } + * + * //... + * } + * @endcode + * + * @sa ContrastToolBar + */ ActionButton { id: _menuButton icon.name: "view-more-symbolic" @@ -10,7 +33,32 @@ ActionButton { checkable: true checked: _moreMenu.visible - property alias moreMenu: _moreMenu + /*! @brief type:Menu A reference to the menu this button is showing + * + * @default{A @ref QtQuick.Controls.Menu "Menu" instance} + * + * @accessors{ + * @memberAc{moreMenu} + * @notifyAc{moreMenuChanged()} + * @readonlyAc + * } + * + * @sa menuContent + */ + readonly property alias moreMenu: _moreMenu + /*! @brief type:list The items that should be displayed in the menu + * + * See the @ref QtQuick.Controls.Menu "Menu.contentData" documentation for a + * description of this property. + * + * @accessors{ + * @memberAc{menuContent} + * @notifyAc{menuContentChanged()} + * @defaultAc + * } + * + * @sa moreMenu + */ default property alias menuContent: _moreMenu.contentData MouseArea { //used to catch mouse events to prevent flickering diff --git a/src/imports/mvvmquick/PopupPresenter.qml b/src/imports/mvvmquick/PopupPresenter.qml index 37a41dc..0f3715c 100644 --- a/src/imports/mvvmquick/PopupPresenter.qml +++ b/src/imports/mvvmquick/PopupPresenter.qml @@ -1,13 +1,72 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 +/*! @brief A presentation helper that can present mvvm views that extend the + * @ref QtQuick.Controls.Popup "Popup" type + * + * @extends QtQml.QtObject + * + * @details You can use this class as presenter for popup views in case you create your own + * root presenter instead of using the QtMvvmApp. This partial presenter can handle any view + * that extends the popup type. Use it as follows: + * + * @code{.qml} + * MyPresenter { + * id: _root + * + * PopupPresenter { + * id: _rootPopup + * rootItem: _root.contentItem + * } + * + * function presentPopup(popup) { + * return _rootPopup.presentPopup(popup); + * } + * + * function closeAction() { + * var closed = false; + * // ... + * if(!closed) + * closed = _rootPopup.closeAction(); + * // ... + * return closed; + * } + * } + * @endcode + * + * @sa QtMvvmApp + */ QtObject { id: _popPresenter + /*! @brief The root item to present popup views to + * + * @default{`null`} + * + * This propety **must** be set in order for the presenter to work. It will create new + * popups with that item as parent, which decides in which relative are they are + * displayed. Unless you want to explicitly reposition popups, this should always be the + * root item of the root component of your application. + * + * @accessors{ + * @memberAc{rootItem} + * @notifyAc{rootItemChanged()} + * } + */ property Item rootItem: null + //! Internal property property var _popups: [] + /*! @brief The primary presenting method to present a popup view + * + * @param type:Popup popup The popup to be presented + * @return type:bool `true` if successfully presented, `false` if not + * + * Use this method in your main presenter to present popups via this sub presenter. + * + * @sa QtMvvmApp::presentPopup, @ref QtQuick.Controls.Popup "Popup" + */ function presentPopup(popup) { popup.parent = rootItem; popup.closed.connect(function() { @@ -22,6 +81,15 @@ QtObject { return true; } + /*! @brief Can be called to try to close open popups + * + * @return type:bool `true` if a popup was closed, `false` if not + * + * Use this method in your main presenter react on a close event. It will close the + * latest top level popup, if one is present. + * + * @sa QtMvvmApp::closeAction + */ function closeAction() { if(_popups.length > 0) { _popups[_popups.length - 1].close(); diff --git a/src/imports/mvvmquick/PresenterProgress.qml b/src/imports/mvvmquick/PresenterProgress.qml index caf9310..a3f161c 100644 --- a/src/imports/mvvmquick/PresenterProgress.qml +++ b/src/imports/mvvmquick/PresenterProgress.qml @@ -2,6 +2,19 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief A @ref QtQuick.Controls.ProgressBar "ProgressBar" with automatic bindings to the + * presenters view loading progress + * + * @extends QtQuick.Controls.ProgressBar + * + * @details You can use this bar in your views to display the load progress of new views to the + * user. The bar automatically anchors itself to the top of the view and hides itself when no + * views are beeing loaded. You can use it as is: + * + * @code{.qml} + * PresenterProgress {} + * @endcode + */ ProgressBar { visible: QuickPresenter.viewLoading value: QuickPresenter.loadingProgress diff --git a/src/imports/mvvmquick/PresentingDrawer.qml b/src/imports/mvvmquick/PresentingDrawer.qml index 65dd2ad..2adaac8 100644 --- a/src/imports/mvvmquick/PresentingDrawer.qml +++ b/src/imports/mvvmquick/PresentingDrawer.qml @@ -1,14 +1,54 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 +/*! @brief A @ref QtQuick.Controls.Drawer "Drawer" that can be used as a presenter for drawer + * views + * + * @extends QtQuick.Controls.Drawer + * + * @details You can use this class as presenter for drawer views. Those are views that are not + * drawers themselves, but need to be placed in one in order to properly work. Use it as + * follows: + * + * @code{.qml} + * MyPresenter { + * id: _root + * + * PresentingDrawer { + * id: _rootDrawer + * } + * + * function presentDrawerContent(item) { + * return _rootDrawer.presentDrawerContent(item); + * } + * + * function toggleDrawer() { + * _rootDrawer.toggle(); + * } + * + * function closeAction() { + * var closed = false; + * // ... + * if(!closed) + * closed = _rootDrawer.closeAction(); + * // ... + * return closed; + * } + * } + * @endcode + * + * @sa QtMvvmApp + */ Drawer { id: _presentingDrawer width: Math.min(300, parent.width - 24); height: parent.height - y + //! Internal property property Item _mainChild: null + //! Toggles the current drawer state. It closes an open drawer or opens a closed one function toggle() { if(visible) close(); @@ -16,6 +56,16 @@ Drawer { open(); } + /*! @brief The primary presenting method to present a drawer item + * + * @param type:Item item The item to be shown + * @return type:bool `true` if successfully presented, `false` if not + * + * Replaces the current drawer content by the new item. The old content is deleted and the + * new item set. + * + * @sa QtMvvmApp::presentDrawerContent, @ref QtQuick.Item "Item" + */ function presentDrawerContent(item) { if(_mainChild) _mainChild.destroy(); @@ -25,6 +75,15 @@ Drawer { return true; } + /*! @brief Can be called to try to close open drawers + * + * @return type:bool `true` if a drawer was closed, `false` if not + * + * Use this method in your main presenter react on a close event. It will close the drawer + * in case it is open. + * + * @sa QtMvvmApp::closeAction + */ function closeAction() { if(_mainChild && typeof _mainChild.closeAction == "function") { if(_mainChild.closeAction()) diff --git a/src/imports/mvvmquick/PresentingStackView.qml b/src/imports/mvvmquick/PresentingStackView.qml index 00585f4..e05016f 100644 --- a/src/imports/mvvmquick/PresentingStackView.qml +++ b/src/imports/mvvmquick/PresentingStackView.qml @@ -1,14 +1,85 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 +/*! @brief A presentation helper that can present standard mvvm views + * + * @extends QtQuick.Controls.StackView + * + * @details You can use this class as presenter for normale views in case you create your own + * root presenter instead of using the QtMvvmApp. This partial presenter can handle any view + * that extends the @ref QtQuick.Item "Item" type. Use it as follows: + * + * @code{.qml} + * MyPresenter { + * id: _root + * + * PresentingStackView { + * id: _rootStack + * anchors.fill: parent + * } + * + * function presentItem(item) { + * return _rootStack.presentItem(item); + * } + * + * function closeAction() { + * var closed = false; + * // ... + * if(!closed) + * closed = _rootStack.closeAction(); + * // ... + * return closed; + * } + * } + * @endcode + * + * @sa QtMvvmApp + */ StackView { id: _presenterStack + /*! @brief The duration of the default push and pop animations + * + * @default{`150` milliseconds} + * + * You can use this property to speed up or slow down the default animations + * + * @accessors{ + * @memberAc{animDuration} + * @notifyAc{animDurationChanged()} + * } + * + * @sa opDuration + */ property int animDuration: 150 + /*! @brief The duration of the fade out + * + * @default{`75` milliseconds} + * + * You can use this property to speed up or slow down the fading part of the push and + * pop animations. + * + * @accessors{ + * @memberAc{opDuration} + * @notifyAc{opDurationChanged()} + * } + * + * @sa animDuration + */ property int opDuration: 75 + //! Internal property property var _clearItems: [] + /*! @brief The primary presenting method to present a view + * + * @param type:Item item The item to be presented + * @return type:bool `true` if successfully presented, `false` if not + * + * Use this method in your main presenter to present items via this sub presenter. + * + * @sa QtMvvmApp::presentItem, @ref QtQuick.Item "Item" + */ function presentItem(item) { if(item.presentAsRoot) { //TODO document if(safeReplace(null, item)) @@ -23,6 +94,15 @@ StackView { } } + /*! @brief Can be called to try to close the presenters current top level view + * + * @return type:bool `true` if a view was closed, `false` if not + * + * Use this method in your main presenter react on a close event. It will pop the top + * level view from the stack, if one is present + * + * @sa QtMvvmApp::closeAction + */ function closeAction() { if(_presenterStack.currentItem && typeof _presenterStack.currentItem.closeAction == "function") { @@ -40,6 +120,18 @@ StackView { } } + /*! @brief Pop and delete a view + * + * @param type:Item item an optional item to be popped to + * @param type:int operation How to perform the operation + * @return type:bool `true` if a view was closed, `false` if not + * + * Use this method instead of the @ref QtQuick.Controls.StackView "pop()" method. It will + * not only pop the top level view, but also delete it. This is recommened to do for views + * presented. + * + * @sa PresentingStackView::closeAction, PresentingStackView::safeReplace + */ function safePop(item, operation) { var resItem = pop(item, operation) if(resItem) { @@ -49,6 +141,20 @@ StackView { return false; } + /*! @brief replace and delete views + * + * @param type:Item target The new view to be placed on the stack + * @param type:Item item an optional item to be popped to + * @param type:object properties The presentation properties to be passed to the target + * @param type:int operation How to perform the operation + * @return type:bool `true` if the replacement was successful, `false` if not + * + * Use this method instead of the @ref QtQuick.Controls.StackView "replace()" method. It + * will not only replace the replaced views, but also delete them. This is recommened to + * do for views presented. + * + * @sa PresentingStackView::closeAction, PresentingStackView::safePop + */ function safeReplace(target, item, properties, operation) { var items = []; console.log("current depth: ", depth) @@ -64,6 +170,7 @@ StackView { return false; } + //! Internal method function clearWaitingItems() { _clearItems.forEach(function(item) { if(typeof item.afterPop == "function") diff --git a/src/imports/mvvmquick/QtMvvmApp.qml b/src/imports/mvvmquick/QtMvvmApp.qml index 2b9979a..9e6e17e 100644 --- a/src/imports/mvvmquick/QtMvvmApp.qml +++ b/src/imports/mvvmquick/QtMvvmApp.qml @@ -2,13 +2,56 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief An application root window that is a full fledged QML presenter + * + * @extends QtQuick.Controls.ApplicationWindow + * + * @details This is the standard presenter you should use in your mvvm application as the root + * QML component of the primary qml file loaded by the engine. It will automatically register + * as the main QML presenter and can handle all the standard view types. + * + * @sa PresenterProgress, PresentingStackView, PresentingDrawer, PopupPresenter, + * DialogPresenter, QuickPresenter + */ ApplicationWindow { id: _root visible: true width: 360 height: 520 + /*! @brief type:PresentingDrawer A reference to the PresentingDrawer + * + * @default{`null`} + * + * Returns the PresentingDrawer that is beeing used by the app. It is null by default as + * the presenter only gets created the first time a drawer view is beeing shown. From that + * point on, you can access the drawer via this property. + * + * @accessors{ + * @memberAc{drawer} + * @notifyAc{drawerChanged()} + * @readonlyAc + * } + * + * @sa PresentingDrawer, QtMvvmApp::presentDrawerContent, QtMvvmApp::rootOnlyDrawer + */ readonly property alias drawer: _drawerLoader.item + /*! @brief Specifies if the drawer can be accessed from the root element only + * + * @default{`true`} + * + * If set to `true`, the presenter can only be accessed by the user if only one view is + * currently presented on the internal PresentingStackView. As soon as second view gets + * pushed, the user cannot open the drawer anymore. By settings it to `false`, the drawer + * will always be accessible on any view on the stack. + * + * @accessors{ + * @memberAc{rootOnlyDrawer} + * @notifyAc{rootOnlyDrawerChanged()} + * } + * + * @sa QtMvvmApp::presentDrawerContent, QtMvvmApp::drawer, QtMvvmApp::presentItem + */ property bool rootOnlyDrawer: true PresenterProgress { @@ -42,24 +85,63 @@ ApplicationWindow { rootItem: _root.contentItem } + /*! @brief The presenting method to present a drawer item + * + * @param type:Item item The item to be shown + * @return type:bool `true` if successfully presented, `false` if not + * + * Calls PresentingDrawer::presentDrawerContent on the internally used presenting drawer. + * If no drawer has been presented yet, it is automatically created. + * + * @sa PresentingDrawer::presentDrawerContent, QtMvvmApp::drawer, @ref QtQuick.Item "Item" + */ function presentDrawerContent(item) { if(!_drawerLoader.item) _drawerLoader.active = true; return _drawerLoader.item.presentDrawerContent(item); } + /*! @brief The presenting method to present a view + * + * @param type:Item item The item to be presented + * @return type:bool `true` if successfully presented, `false` if not + * + * Calls PresentingStackView::presentItem on the internally used presenting stack view. + * + * @sa PresentingStackView::presentItem, @ref QtQuick.Item "Item" + */ function presentItem(item) { return _rootStack.presentItem(item); } + /*! @brief The presenting method to present a popup view + * + * @param type:Popup popup The popup to be presented + * @return type:bool `true` if successfully presented, `false` if not + * + * Calls PopupPresenter::presentPopup on the internally used popup presenter. + * + * @sa PopupPresenter::presentPopup, @ref QtQuick.Controls.Popup "Popup" + */ function presentPopup(popup) { return _rootPopup.presentPopup(popup); } + /*! @brief The presenting method to present a dialog + * + * @param type:MessageConfig config The message configuration to create a dialog of + * @param type:MessageResult result The result to report the dialog result to + * @return type:bool `true` if successfully presented, `false` if not + * + * Calls DialogPresenter::showDialog on the internally used dialog presenter. + * + * @sa QtMvvm::MessageConfig, QtMvvm::MessageResult, DialogPresenter::showDialog + */ function showDialog(config, result) { return _rootDialogs.showDialog(config, result); } + //! @copybrief PresentingDrawer::toggle function toggleDrawer() { if(_drawerLoader.item) _drawerLoader.item.toggle(); @@ -67,14 +149,27 @@ ApplicationWindow { console.warn("No drawer like view active. Cannot toggle drawer"); } + /*! @brief Can be called to perform a close operation + * + * @return type:bool `true` if anything was closed, `false` if not + * + * Use this method to perform a close operation. The app will automatically check all + * internally used presenter in a logical order and call this method on all of them until + * one returns with a positive result. This way you have a global method to close any kind + * of active view. This is also used to handle window close events and the mobile back + * button. + * + * @sa PopupPresenter::closeAction, DialogPresenter::closeAction, + * PresentingDrawer::closeAction, PresentingStackView::closeAction + */ function closeAction() { var closed = false; - if(!closed && _drawerLoader.item) - closed = _drawerLoader.item.closeAction(); if(!closed) closed = _rootDialogs.closeAction(); if(!closed) closed = _rootPopup.closeAction(); + if(!closed && _drawerLoader.item) + closed = _drawerLoader.item.closeAction(); if(!closed) closed = _rootStack.closeAction(); return closed; diff --git a/src/imports/mvvmquick/RoundActionButton.qml b/src/imports/mvvmquick/RoundActionButton.qml index ab69e58..9bd275f 100644 --- a/src/imports/mvvmquick/RoundActionButton.qml +++ b/src/imports/mvvmquick/RoundActionButton.qml @@ -2,9 +2,19 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief An extension of the @ref QtQuick.Controls.RoundButton "RoundButton" for better appearance + * + * @extends QtQuick.Controls.RoundButton + * + * @details This version basically adjusts size, icon size and text display to look better and + * fit the Material guidelines. It also adds a tooltip that can be shown via a long press + * + * @sa ContrastToolBar, MenuButton + */ RoundButton { id: _roundButton + //! @copydoc ActionButton property string toolTip: _roundButton.text display: AbstractButton.IconOnly diff --git a/src/imports/mvvmquick/SettingsView.qml b/src/imports/mvvmquick/SettingsView.qml index af4d061..1a033e7 100644 --- a/src/imports/mvvmquick/SettingsView.qml +++ b/src/imports/mvvmquick/SettingsView.qml @@ -5,11 +5,56 @@ import QtQuick.Layouts 1.3 import de.skycoder42.QtMvvm.Core 1.0 import de.skycoder42.QtMvvm.Quick 1.0 +/*! @brief The view implementation for the QtMvvm::SettingsViewModel + * + * @extends QtQuick.Controls.Page + * + * @details This is the view used to present a settings view model. You can extend the class + * if you need to extend that view. + * + * @sa QtMvvm::SettingsViewModel + */ Page { id: _settingsView + + /*! @brief The viewmodel to use + * + * @default{Injected} + * + * @accessors{ + * @memberAc{viewModel} + * @notifyAc{viewModelChanged()} + * } + * + * @sa QtMvvm::SettingsViewModel + */ property SettingsViewModel viewModel: null + /*! @brief Specifiy if a back action should always close the full settings + * + * @default{`false`} + * + * The settings view consists of an internal stack view to present settings pages. By + * default only one page is closed at a time. By setting this property to true, a close + * action will always close all of them. + * + * @accessors{ + * @memberAc{fullClose} + * @notifyAc{fullCloseChanged()} + * } + */ property bool fullClose: false + /*! @brief Can be called to try to close a single settings page + * + * @return type:bool `true` if a page was closed, `false` if not + * + * This method is called by the presenter to close the pages of the settings view one at + * a time. + * + * @note if SettingsView::fullClose is true, this method will always return false. + * + * @sa SettingsView::fullClose, PresentingStackView::closeAction + */ function closeAction() { return !fullClose && _settingsStack.closeAction(); } @@ -158,6 +203,7 @@ Page { state: "title" + //! @brief Can be called to toggle the state of the search bar function toggleSearchState() { if(state == "title") state = "search"; diff --git a/src/imports/mvvmquick/ToolBarLabel.qml b/src/imports/mvvmquick/ToolBarLabel.qml index 0fbf42e..5da7ba5 100644 --- a/src/imports/mvvmquick/ToolBarLabel.qml +++ b/src/imports/mvvmquick/ToolBarLabel.qml @@ -1,6 +1,18 @@ import QtQuick 2.10 import QtQuick.Controls 2.3 +/*! @brief An extension of the @ref QtQuick.Controls.Label "Label" for better appearance when + * used in a toolbar + * + * @extends QtQuick.Controls.Label + * + * @details This special label is bigger in size and correctly aligned for use in a toolbar. + * You can either let it fill the whole toolbar or use it in a layout with + * `Layout.fillWidth: true` and it will perfectly fill up the bar like a normal toolbar label + * for mobile activity titles. + * + * @sa ContrastToolBar + */ Label { id: _toolLabel font.pointSize: 14 diff --git a/src/imports/mvvmquick/androidfilechooser.h b/src/imports/mvvmquick/androidfilechooser.h index 551f2b1..84cd929 100644 --- a/src/imports/mvvmquick/androidfilechooser.h +++ b/src/imports/mvvmquick/androidfilechooser.h @@ -13,6 +13,7 @@ namespace de::skycoder42::QtMvvm::Quick { /*! @brief A QML class access the native file chooser on android * + * @extends QtQml.QtObject * @since 1.0 * * @warning Available on android only! diff --git a/src/imports/mvvmquick/qqmlquickpresenter.h b/src/imports/mvvmquick/qqmlquickpresenter.h index cc4c1f5..dc0b130 100644 --- a/src/imports/mvvmquick/qqmlquickpresenter.h +++ b/src/imports/mvvmquick/qqmlquickpresenter.h @@ -21,6 +21,7 @@ namespace de::skycoder42::QtMvvm::Quick { /*! @brief A QML singleton to access common presenter methods globally * + * @extends QtQml.QtObject * @since 1.0 * * The main purpose of the class is to create a communication channel between the QML code and
Accessors
CONSTANT
READ ONLY
FINAL
DEFAULT