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}=
Accessors | <
"constantAc=
---|
CONSTANT |
" \
"readonlyAc=READ ONLY |
" \
"finalAc=FINAL |
" \
+ "defaultAc=DEFAULT |
" \
"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