|
8 | 8 | #include <QtAndroidExtras/QAndroidActivityResultReceiver> |
9 | 9 | #include <QtAndroidExtras/QAndroidJniObject> |
10 | 10 |
|
| 11 | +#ifdef DOXYGEN_RUN |
| 12 | +namespace de::skycoder42::QtMvvm::Quick { |
| 13 | + |
| 14 | +/*! @brief A QML class access the native file chooser on android |
| 15 | + * |
| 16 | + * @since 1.0 |
| 17 | + * |
| 18 | + * @warning Available on android only! |
| 19 | + * |
| 20 | + * A C++ wrapper around the android java API to access the native file chooser. It can only |
| 21 | + * be used on Android, and serves as the base for the android implementation of the file and |
| 22 | + * folder dialogs. |
| 23 | + * |
| 24 | + * @sa FileDialog, FolderDialog |
| 25 | + */ |
| 26 | +class FileChooser : public QtObject |
| 27 | +#else |
11 | 28 | namespace QtMvvm { |
12 | 29 |
|
13 | 30 | class AndroidFileChooser : public QObject, public QAndroidActivityResultReceiver |
| 31 | +#endif |
14 | 32 | { |
15 | 33 | Q_OBJECT |
16 | 34 |
|
17 | | - Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged) |
18 | | - |
19 | | - Q_PROPERTY(QUrl folderUrl READ folderUrl WRITE setFolderUrl NOTIFY folderUrlChanged) |
20 | | - Q_PROPERTY(ChooserType type READ type WRITE setType NOTIFY typeChanged) |
21 | | - Q_PROPERTY(QStringList mimeTypes READ mimeTypes WRITE setMimeTypes NOTIFY mimeTypesChanged) |
| 35 | + /*! @brief The activity title/description of the file chooser |
| 36 | + * |
| 37 | + * @default{<i>Empty</i>} |
| 38 | + * |
| 39 | + * @accessors{ |
| 40 | + * @memberAc{title} |
| 41 | + * @notifyAc{titleChanged()} |
| 42 | + * } |
| 43 | + */ |
| 44 | + Q_PROPERTY(QString title MEMBER _title NOTIFY titleChanged) |
| 45 | + |
| 46 | + /*! @brief The URL of the place to show the dialog from |
| 47 | + * |
| 48 | + * @default{<i>Empty</i>} |
| 49 | + * |
| 50 | + * @accessors{ |
| 51 | + * @memberAc{folderUrl} |
| 52 | + * @notifyAc{folderUrlChanged()} |
| 53 | + * } |
| 54 | + */ |
| 55 | + Q_PROPERTY(QUrl folderUrl MEMBER _folderUrl NOTIFY folderUrlChanged) |
| 56 | + /*! @brief The type of URL to get |
| 57 | + * |
| 58 | + * @default{`FileChooser::OpenDocument`} |
| 59 | + * |
| 60 | + * Basically the open mode to get a fitting URL for. |
| 61 | + * |
| 62 | + * @accessors{ |
| 63 | + * @memberAc{type} |
| 64 | + * @notifyAc{typeChanged()} |
| 65 | + * } |
| 66 | + * |
| 67 | + * @sa FileChooser::ChooserType |
| 68 | + */ |
| 69 | + Q_PROPERTY(ChooserType type MEMBER _type NOTIFY typeChanged) |
| 70 | + /*! @brief A list of acceptable mimetypes. Can contain wildcards |
| 71 | + * |
| 72 | + * @default{`["*@/*"]` (with just 1 slash instead of `@/`)} |
| 73 | + * |
| 74 | + * @accessors{ |
| 75 | + * @memberAc{mimeTypes} |
| 76 | + * @notifyAc{mimeTypesChanged()} |
| 77 | + * } |
| 78 | + */ |
| 79 | + Q_PROPERTY(QStringList mimeTypes MEMBER _mimeTypes NOTIFY mimeTypesChanged) |
| 80 | + /*! @brief Additional flags to configure the chooser |
| 81 | + * |
| 82 | + * @default{`FileChooser::OpenableFlag | FileChooser::AlwaysGrantWriteFlag`} |
| 83 | + * |
| 84 | + * @accessors{ |
| 85 | + * @memberAc{chooserFlags} |
| 86 | + * @notifyAc{chooserFlagsChanged()} |
| 87 | + * } |
| 88 | + * |
| 89 | + * @sa FileChooser::ChooserFlag |
| 90 | + */ |
22 | 91 | Q_PROPERTY(ChooserFlags chooserFlags READ chooserFlags WRITE setChooserFlags NOTIFY chooserFlagsChanged) |
23 | 92 |
|
| 93 | + /*! @brief The chooser result url(s) the user selected |
| 94 | + * |
| 95 | + * @default{<i>Invalid</i>} |
| 96 | + * |
| 97 | + * Can either be a single QUrl or a QList<QUrl>. The list is only returned when |
| 98 | + * FileChooser::OpenMultipleDocuments is used as FileChooser::type. For all other cases |
| 99 | + * a single QUrl is returned. |
| 100 | + * |
| 101 | + * @accessors{ |
| 102 | + * @memberAc{folderUrl} |
| 103 | + * @notifyAc{folderUrlChanged()} |
| 104 | + * @readonlyAc |
| 105 | + * } |
| 106 | + */ |
24 | 107 | Q_PROPERTY(QVariant result READ result NOTIFY resultChanged) |
25 | 108 |
|
26 | 109 | public: |
| 110 | + //! The different modes the chooser can return urls for |
27 | 111 | enum ChooserType { |
28 | | - GetContent = 0, |
29 | | - OpenDocument = 1, |
30 | | - OpenMultipleDocuments = 2, |
31 | | - CreateDocument = 3, |
32 | | - OpenDocumentTree = 4 |
| 112 | + GetContent = 0, //!< Get a non-permanent, read only content url |
| 113 | + OpenDocument = 1, //!< Get a permanent content url |
| 114 | + OpenMultipleDocuments = 2, //!< Get a list of permanent content urls |
| 115 | + CreateDocument = 3, //!< Create a new permanent content url |
| 116 | + OpenDocumentTree = 4 //!< Get a URL to content folder |
33 | 117 | }; |
34 | 118 | Q_ENUM(ChooserType) |
35 | 119 |
|
| 120 | + //! Extra flags to configure how to open the URLs |
36 | 121 | enum ChooserFlag { |
37 | | - OpenableFlag = 0x01, |
38 | | - LocalOnlyFlag = 0x02, |
39 | | - AlwaysGrantWriteFlag = 0x04, |
40 | | - PersistPermissionsFlag = 0x08 |
| 122 | + OpenableFlag = 0x01, //!< The returned URL must be openable (for reading) |
| 123 | + LocalOnlyFlag = 0x02, //!< Only local files are allowed |
| 124 | + AlwaysGrantWriteFlag = 0x04, //!< Always allow writing, not only for FileChooser::CreateDocument |
| 125 | + PersistPermissionsFlag = 0x08 //!< Persist the permission to access the content across reboots |
41 | 126 | }; |
42 | 127 | Q_DECLARE_FLAGS(ChooserFlags, ChooserFlag) |
43 | 128 | Q_FLAG(ChooserFlags) |
44 | 129 |
|
| 130 | + //! @private |
45 | 131 | explicit AndroidFileChooser(QObject *parent = nullptr); |
46 | 132 | ~AndroidFileChooser(); |
47 | 133 |
|
48 | | - QString title() const; |
49 | | - QUrl folderUrl() const; |
50 | | - ChooserType type() const; |
51 | | - QStringList mimeTypes() const; |
| 134 | + //! @private |
52 | 135 | ChooserFlags chooserFlags() const; |
53 | | - |
| 136 | + //! @private |
54 | 137 | QVariant result() const; |
55 | 138 |
|
| 139 | +#ifdef DOXYGEN_RUN |
| 140 | +public: |
| 141 | +#else |
56 | 142 | public Q_SLOTS: |
| 143 | +#endif |
| 144 | + //! Opens the file chooser by sending the show intent |
57 | 145 | void open(); |
58 | 146 |
|
59 | | - void setTitle(const QString &title); |
60 | | - void setFolderUrl(const QUrl &folderUrl); |
61 | | - void setType(ChooserType type); |
62 | | - void setMimeTypes(const QStringList &mimeTypes); |
| 147 | + //! @private |
63 | 148 | void setChooserFlags(ChooserFlags chooserFlags); |
64 | 149 |
|
65 | 150 | Q_SIGNALS: |
| 151 | + //! Emitted when the user select a url (or multiple) |
66 | 152 | void accepted(); |
| 153 | + //! Emitted when the user cancels without selecting a url |
67 | 154 | void rejected(); |
68 | 155 |
|
| 156 | + //! @notifyAcFn{FileChooser::title} |
69 | 157 | void titleChanged(const QString &title); |
| 158 | + //! @notifyAcFn{FileChooser::folderUrl} |
70 | 159 | void folderUrlChanged(const QUrl &folderUrl); |
| 160 | + //! @notifyAcFn{FileChooser::type} |
71 | 161 | void typeChanged(ChooserType type); |
| 162 | + //! @notifyAcFn{FileChooser::mimeTypes} |
72 | 163 | void mimeTypesChanged(const QStringList &mimeTypes); |
| 164 | + //! @notifyAcFn{FileChooser::chooserFlags} |
73 | 165 | void chooserFlagsChanged(ChooserFlags chooserFlags); |
74 | | - |
| 166 | + //! @notifyAcFn{FileChooser::result} |
75 | 167 | void resultChanged(QVariant result); |
76 | 168 |
|
77 | 169 | protected: |
| 170 | + //! @private |
78 | 171 | void handleActivityResult(int receiverRequestCode, int resultCode, const QAndroidJniObject &data) override; |
79 | 172 |
|
80 | 173 | private: |
|
0 commit comments