From b61870a9c75110e08ed1efbc96e672425a233379 Mon Sep 17 00:00:00 2001 From: Skycoder42 Date: Tue, 13 Mar 2018 00:59:26 +0100 Subject: [PATCH] added more quick qml doc, excluded internal types --- doc/Doxyfile | 19 ++- doc/qtmvvm.dox | 20 +++ src/imports/mvvmquick/androidfilechooser.cpp | 56 -------- src/imports/mvvmquick/androidfilechooser.h | 141 +++++++++++++++---- src/imports/mvvmquick/qqmlquickpresenter.h | 110 ++++++++++++++- 5 files changed, 257 insertions(+), 89 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 2ab1bf4..cddd903 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -250,6 +250,7 @@ ALIASES = "accessors{1}=< storedAc{1}= \ userAc{1}= \ "constantAc=" \ + "readonlyAc=" \ "finalAc=" \ "default{1}=Default: \1
" \ "readAcFn{1}=READ accessor for \1" \ @@ -896,7 +897,16 @@ RECURSIVE = YES # run. EXCLUDE = ../src/3rdparty \ - ../src/plugins + ../src/plugins \ + ../src/imports/mvvmquick/settingsuibuilder.h \ + ../src/imports/mvvmquick/TintIcon.qml \ + ../src/imports/mvvmquick/MsgBoxBase.qml \ + ../src/imports/mvvmquick/MsgBox.qml \ + ../src/imports/mvvmquick/InputDialog.qml \ + ../src/imports/mvvmquick/ListSection.qml \ + ../src/imports/mvvmquick/OverviewListView.qml \ + ../src/imports/mvvmquick/AndroidFileDialog.qml \ + ../src/imports/mvvmquick/AndroidFolderDialog.qml # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -919,7 +929,8 @@ EXCLUDE_PATTERNS = moc_* \ *_p.* \ *.cpp \ */src/mvvmquick/*.qml \ - */src/mvvmdatasyncquick/*.qml + */src/mvvmdatasyncquick/*.qml \ + */imports/mvvmquick/*model.h # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -935,6 +946,9 @@ EXCLUDE_SYMBOLS = QtMvvm::__helpertypes \ QtMvvmQuickDeclarativeModule \ QtMvvmDataSyncCoreDeclarativeModule \ QtMvvmDataSyncQuickDeclarativeModule \ + QtMvvm::MultiFilterProxyModel \ + QtMvvm::SettingsEntryModel \ + QtMvvm::SettingsSectionModel \ \ QAbstractAspect \ QAndroidActivityResultReceiver \ @@ -956,7 +970,6 @@ EXCLUDE_SYMBOLS = QtMvvm::__helpertypes \ ApplicationWindow \ Dialog \ Drawer \ - FileChooser \ Item \ Label \ ListView \ diff --git a/doc/qtmvvm.dox b/doc/qtmvvm.dox index e308889..554704d 100644 --- a/doc/qtmvvm.dox +++ b/doc/qtmvvm.dox @@ -66,6 +66,26 @@ The following list shows which classes belong to which Qt module, in alphabetica Current Version
        1.0 + +Available Types +- @ref QtMvvm::InputViewFactory "InputViewFactory" (uncreatable) +- QuickPresenter (singleton) +- FileChooser +- AlertDialog +- ContrastToolBar +- ToolBarLabel +- ActionButton +- RoundActionButton +- MenuButton +- FileDialog +- FolderDialog +- PresenterProgress +- PresentingStackView +- PopupPresenter +- DialogPresenter +- PresentingDrawer +- SettingsView +- QtMvvmApp */ /*! diff --git a/src/imports/mvvmquick/androidfilechooser.cpp b/src/imports/mvvmquick/androidfilechooser.cpp index 73eb071..a00379c 100644 --- a/src/imports/mvvmquick/androidfilechooser.cpp +++ b/src/imports/mvvmquick/androidfilechooser.cpp @@ -16,26 +16,6 @@ AndroidFileChooser::AndroidFileChooser(QObject *parent) : AndroidFileChooser::~AndroidFileChooser() {} -QString AndroidFileChooser::title() const -{ - return _title; -} - -QUrl AndroidFileChooser::folderUrl() const -{ - return _folderUrl; -} - -AndroidFileChooser::ChooserType AndroidFileChooser::type() const -{ - return _type; -} - -QStringList AndroidFileChooser::mimeTypes() const -{ - return _mimeTypes; -} - AndroidFileChooser::ChooserFlags AndroidFileChooser::chooserFlags() const { return _flags; @@ -83,42 +63,6 @@ void AndroidFileChooser::open() this); } -void AndroidFileChooser::setTitle(const QString &title) -{ - if (_title == title) - return; - - _title = title; - emit titleChanged(title); -} - -void AndroidFileChooser::setFolderUrl(const QUrl &contentUrl) -{ - if (_folderUrl == contentUrl) - return; - - _folderUrl = contentUrl; - emit folderUrlChanged(contentUrl); -} - -void AndroidFileChooser::setType(AndroidFileChooser::ChooserType type) -{ - if (_type == type) - return; - - _type = type; - emit typeChanged(type); -} - -void AndroidFileChooser::setMimeTypes(const QStringList &mimeType) -{ - if (_mimeTypes == mimeType) - return; - - _mimeTypes = mimeType; - emit mimeTypesChanged(mimeType); -} - void AndroidFileChooser::setChooserFlags(ChooserFlags chooserFlags) { if (_flags == chooserFlags) diff --git a/src/imports/mvvmquick/androidfilechooser.h b/src/imports/mvvmquick/androidfilechooser.h index 125d71d..551f2b1 100644 --- a/src/imports/mvvmquick/androidfilechooser.h +++ b/src/imports/mvvmquick/androidfilechooser.h @@ -8,73 +8,166 @@ #include #include +#ifdef DOXYGEN_RUN +namespace de::skycoder42::QtMvvm::Quick { + +/*! @brief A QML class access the native file chooser on android + * + * @since 1.0 + * + * @warning Available on android only! + * + * A C++ wrapper around the android java API to access the native file chooser. It can only + * be used on Android, and serves as the base for the android implementation of the file and + * folder dialogs. + * + * @sa FileDialog, FolderDialog + */ +class FileChooser : public QtObject +#else namespace QtMvvm { class AndroidFileChooser : public QObject, public QAndroidActivityResultReceiver +#endif { Q_OBJECT - Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged) - - Q_PROPERTY(QUrl folderUrl READ folderUrl WRITE setFolderUrl NOTIFY folderUrlChanged) - Q_PROPERTY(ChooserType type READ type WRITE setType NOTIFY typeChanged) - Q_PROPERTY(QStringList mimeTypes READ mimeTypes WRITE setMimeTypes NOTIFY mimeTypesChanged) + /*! @brief The activity title/description of the file chooser + * + * @default{Empty} + * + * @accessors{ + * @memberAc{title} + * @notifyAc{titleChanged()} + * } + */ + Q_PROPERTY(QString title MEMBER _title NOTIFY titleChanged) + + /*! @brief The URL of the place to show the dialog from + * + * @default{Empty} + * + * @accessors{ + * @memberAc{folderUrl} + * @notifyAc{folderUrlChanged()} + * } + */ + Q_PROPERTY(QUrl folderUrl MEMBER _folderUrl NOTIFY folderUrlChanged) + /*! @brief The type of URL to get + * + * @default{`FileChooser::OpenDocument`} + * + * Basically the open mode to get a fitting URL for. + * + * @accessors{ + * @memberAc{type} + * @notifyAc{typeChanged()} + * } + * + * @sa FileChooser::ChooserType + */ + Q_PROPERTY(ChooserType type MEMBER _type NOTIFY typeChanged) + /*! @brief A list of acceptable mimetypes. Can contain wildcards + * + * @default{`["*@/*"]` (with just 1 slash instead of `@/`)} + * + * @accessors{ + * @memberAc{mimeTypes} + * @notifyAc{mimeTypesChanged()} + * } + */ + Q_PROPERTY(QStringList mimeTypes MEMBER _mimeTypes NOTIFY mimeTypesChanged) + /*! @brief Additional flags to configure the chooser + * + * @default{`FileChooser::OpenableFlag | FileChooser::AlwaysGrantWriteFlag`} + * + * @accessors{ + * @memberAc{chooserFlags} + * @notifyAc{chooserFlagsChanged()} + * } + * + * @sa FileChooser::ChooserFlag + */ Q_PROPERTY(ChooserFlags chooserFlags READ chooserFlags WRITE setChooserFlags NOTIFY chooserFlagsChanged) + /*! @brief The chooser result url(s) the user selected + * + * @default{Invalid} + * + * Can either be a single QUrl or a QList. The list is only returned when + * FileChooser::OpenMultipleDocuments is used as FileChooser::type. For all other cases + * a single QUrl is returned. + * + * @accessors{ + * @memberAc{folderUrl} + * @notifyAc{folderUrlChanged()} + * @readonlyAc + * } + */ Q_PROPERTY(QVariant result READ result NOTIFY resultChanged) public: + //! The different modes the chooser can return urls for enum ChooserType { - GetContent = 0, - OpenDocument = 1, - OpenMultipleDocuments = 2, - CreateDocument = 3, - OpenDocumentTree = 4 + GetContent = 0, //!< Get a non-permanent, read only content url + OpenDocument = 1, //!< Get a permanent content url + OpenMultipleDocuments = 2, //!< Get a list of permanent content urls + CreateDocument = 3, //!< Create a new permanent content url + OpenDocumentTree = 4 //!< Get a URL to content folder }; Q_ENUM(ChooserType) + //! Extra flags to configure how to open the URLs enum ChooserFlag { - OpenableFlag = 0x01, - LocalOnlyFlag = 0x02, - AlwaysGrantWriteFlag = 0x04, - PersistPermissionsFlag = 0x08 + OpenableFlag = 0x01, //!< The returned URL must be openable (for reading) + LocalOnlyFlag = 0x02, //!< Only local files are allowed + AlwaysGrantWriteFlag = 0x04, //!< Always allow writing, not only for FileChooser::CreateDocument + PersistPermissionsFlag = 0x08 //!< Persist the permission to access the content across reboots }; Q_DECLARE_FLAGS(ChooserFlags, ChooserFlag) Q_FLAG(ChooserFlags) + //! @private explicit AndroidFileChooser(QObject *parent = nullptr); ~AndroidFileChooser(); - QString title() const; - QUrl folderUrl() const; - ChooserType type() const; - QStringList mimeTypes() const; + //! @private ChooserFlags chooserFlags() const; - + //! @private QVariant result() const; +#ifdef DOXYGEN_RUN +public: +#else public Q_SLOTS: +#endif + //! Opens the file chooser by sending the show intent void open(); - void setTitle(const QString &title); - void setFolderUrl(const QUrl &folderUrl); - void setType(ChooserType type); - void setMimeTypes(const QStringList &mimeTypes); + //! @private void setChooserFlags(ChooserFlags chooserFlags); Q_SIGNALS: + //! Emitted when the user select a url (or multiple) void accepted(); + //! Emitted when the user cancels without selecting a url void rejected(); + //! @notifyAcFn{FileChooser::title} void titleChanged(const QString &title); + //! @notifyAcFn{FileChooser::folderUrl} void folderUrlChanged(const QUrl &folderUrl); + //! @notifyAcFn{FileChooser::type} void typeChanged(ChooserType type); + //! @notifyAcFn{FileChooser::mimeTypes} void mimeTypesChanged(const QStringList &mimeTypes); + //! @notifyAcFn{FileChooser::chooserFlags} void chooserFlagsChanged(ChooserFlags chooserFlags); - + //! @notifyAcFn{FileChooser::result} void resultChanged(QVariant result); protected: + //! @private void handleActivityResult(int receiverRequestCode, int resultCode, const QAndroidJniObject &data) override; private: diff --git a/src/imports/mvvmquick/qqmlquickpresenter.h b/src/imports/mvvmquick/qqmlquickpresenter.h index d506dd7..cc4c1f5 100644 --- a/src/imports/mvvmquick/qqmlquickpresenter.h +++ b/src/imports/mvvmquick/qqmlquickpresenter.h @@ -16,41 +16,139 @@ #include +#ifdef DOXYGEN_RUN +namespace de::skycoder42::QtMvvm::Quick { + +/*! @brief A QML singleton to access common presenter methods globally + * + * @since 1.0 + * + * The main purpose of the class is to create a communication channel between the QML code and + * the C++ presenter logic. + * + * @sa QtMvvm::QuickPresenter + */ +class QuickPresenter : public QtObject +#else namespace QtMvvm { class QQmlQuickPresenter : public QObject +#endif { Q_OBJECT + /*! @brief The name of the currently active Quick Controls 2 Style + * + * @default{`QQuickStyle::name()`} + * + * @accessors{ + * @memberAc{currentStyle} + * @readonlyAc + * @constantAc + * } + */ Q_PROPERTY(QString currentStyle READ currentStyle CONSTANT) + /*! @brief The view factory provided by the C++ presenter + * + * @default{`QtMvvm::QuickPresenter::inputViewFactory`} + * + * @accessors{ + * @memberAc{inputViewFactory} + * @notifyAc{inputViewFactoryChanged()} + * @readonlyAc + * } + */ Q_PROPERTY(InputViewFactory* inputViewFactory READ inputViewFactory NOTIFY inputViewFactoryChanged) + /*! @brief The primary presenter QML object. + * + * @default{`null`} + * + * This property must be set in the root QML component that is loaded by the qml + * application in order to actually make presenting possible. When using the QtMvvmApp, + * this is take care of automatically. + * + * @accessors{ + * @memberAc{qmlPresenter} + * @notifyAc{qmlPresenterChanged()} + * } + * + * @sa QtMvvmApp + */ Q_PROPERTY(QObject* qmlPresenter MEMBER _qmlPresenter NOTIFY qmlPresenterChanged) + /*! @brief Specifies whether the presenter is currently loading a new view component + * + * @default{`false`} + * + * @accessors{ + * @memberAc{viewLoading} + * @notifyAc{viewLoadingChanged()} + * @readonlyAc + * } + * + * @sa QuickPresenter::loadingProgress + */ Q_PROPERTY(bool viewLoading READ isViewLoading NOTIFY viewLoadingChanged) + /*! @brief Reports the current loading progress when currently loading a new view + * + * @default{`0.0`} + * + * Is limited to the interval `[0.0,0.1]` + * + * @accessors{ + * @memberAc{loadingProgress} + * @notifyAc{loadingProgressChanged()} + * @readonlyAc + * } + * + * @sa QuickPresenter::viewLoading + */ Q_PROPERTY(qreal loadingProgress READ loadingProgress NOTIFY loadingProgressChanged) public: + //! @private explicit QQmlQuickPresenter(QQmlEngine *engine); + //! @private QString currentStyle() const; + //! @private InputViewFactory* inputViewFactory() const; - + //! @private bool isViewLoading() const; + //! @private qreal loadingProgress() const; - Q_INVOKABLE QStringList mimeTypeFilters(const QStringList &mimeTypes) const; +#ifndef DOXYGEN_RUN +#define static +#endif + //! Converts a list of mimetypes into a list of extension filters, for a file dialog + Q_INVOKABLE static QStringList mimeTypeFilters(const QStringList &mimeTypes) const; +#ifdef DOXYGEN_RUN +public: +#else public Q_SLOTS: - void toggleDrawer(); - void popView(); +#endif + //! Toggles the state of the current drawer, if any is beeing used + static void toggleDrawer(); + //! Pops the current top level view + static void popView(); - void hapticLongPress(); + //! Performs haptic feedback of a long press (Android only) + static void hapticLongPress(); + +#ifndef DOXYGEN_RUN +#undef static +#endif Q_SIGNALS: + //! @notifyAcFn{QuickPresenter::qmlPresenter} void qmlPresenterChanged(QObject* qmlPresenter); + //! @notifyAcFn{QuickPresenter::viewLoading} void viewLoadingChanged(bool viewLoading); + //! @notifyAcFn{QuickPresenter::loadingProgress} void loadingProgressChanged(qreal loadingProgress); - + //! @notifyAcFn{QuickPresenter::inputViewFactory} void inputViewFactoryChanged(InputViewFactory* inputViewFactory); private Q_SLOTS:
Accessors
STORED\1
USER\1
CONSTANT
READ ONLY
FINAL