1 | /* |
2 | * SPDX-FileCopyrightText: 2019 Marco Martin <mart@kde.org> |
3 | * |
4 | * SPDX-License-Identifier: LGPL-2.0-or-later |
5 | */ |
6 | #pragma once |
7 | |
8 | #include <QObject> |
9 | #include <QPointer> |
10 | #include <QQuickItem> |
11 | |
12 | /*! |
13 | * \qmltype PagePool |
14 | * \inqmlmodule org.kde.kirigami |
15 | * |
16 | * \brief A pool of Page items. |
17 | * |
18 | * Pages will be unique per url and the items |
19 | * will be kept around unless explicitly deleted. |
20 | * |
21 | * Instances are C++ owned and can be deleted only manually using deletePage(). |
22 | * |
23 | * Instance are unique per url: if you need 2 different instances for a page |
24 | * url, you should instantiate them in the traditional way |
25 | * or use a different PagePool instance. |
26 | * |
27 | * \sa PagePoolAction |
28 | */ |
29 | class PagePool : public QObject |
30 | { |
31 | Q_OBJECT |
32 | QML_ELEMENT |
33 | /*! |
34 | * \qmlproperty url PagePool::lastLoadedUrl |
35 | * |
36 | * The last url that was loaded with loadPage. Useful if you need |
37 | * to have a "checked" state to buttons or list items that |
38 | * load the page when clicked. |
39 | */ |
40 | Q_PROPERTY(QUrl lastLoadedUrl READ lastLoadedUrl NOTIFY lastLoadedUrlChanged FINAL) |
41 | |
42 | /*! |
43 | * \qmlproperty Item PagePool::lastLoadedItem |
44 | * |
45 | * The last item that was loaded with loadPage. |
46 | */ |
47 | Q_PROPERTY(QQuickItem *lastLoadedItem READ lastLoadedItem NOTIFY lastLoadedItemChanged FINAL) |
48 | |
49 | /*! |
50 | * \qmlproperty list<Item> PagePool::items |
51 | * |
52 | * All items loaded/managed by the PagePool. |
53 | * \since 5.84 |
54 | */ |
55 | Q_PROPERTY(QList<QQuickItem *> items READ items NOTIFY itemsChanged FINAL) |
56 | |
57 | /*! |
58 | * \qmlproperty list<url> PagePool::urls |
59 | * |
60 | * All page URLs loaded/managed by the PagePool. |
61 | * \since 5.84 |
62 | */ |
63 | Q_PROPERTY(QList<QUrl> urls READ urls NOTIFY urlsChanged FINAL) |
64 | |
65 | /*! |
66 | * \qmlproperty bool PagePool::cachePages |
67 | * |
68 | * If \c true (default) the pages will be kept around, will have C++ ownership and |
69 | * only one instance per page will be created. |
70 | * If \c false the pages will have Javascript ownership (thus deleted on pop by the |
71 | * page stacks) and each call to loadPage will create a new page instance. When |
72 | * cachePages is false, Components get cached nevertheless. |
73 | */ |
74 | Q_PROPERTY(bool cachePages READ cachePages WRITE setCachePages NOTIFY cachePagesChanged FINAL) |
75 | |
76 | public: |
77 | PagePool(QObject *parent = nullptr); |
78 | ~PagePool() override; |
79 | |
80 | QUrl lastLoadedUrl() const; |
81 | QQuickItem *lastLoadedItem() const; |
82 | QList<QQuickItem *> items() const; |
83 | QList<QUrl> urls() const; |
84 | |
85 | void setCachePages(bool cache); |
86 | bool cachePages() const; |
87 | |
88 | /*! |
89 | * Returns the instance of the item defined in the QML file identified |
90 | * by url, only one instance will be made per url if cachePAges is true. |
91 | * If the url is remote (i.e. http) don't rely on the return value but |
92 | * us the async callback instead. |
93 | * |
94 | * @param url full url of the item: it can be a well formed Url, an |
95 | * absolute path or a relative one to the path of the qml file the |
96 | * PagePool is instantiated from |
97 | * @param callback If we are loading a remote url, we can't have the |
98 | * item immediately but will be passed as a parameter to the provided |
99 | * callback. Normally, don't set a callback, use it only in case of |
100 | * remote urls |
101 | * @returns the page instance that will have been created if necessary. |
102 | * If the url is remote it will return null, as well will return null |
103 | * if the callback has been provided |
104 | */ |
105 | Q_INVOKABLE QQuickItem *loadPage(const QString &url, QJSValue callback = QJSValue()); |
106 | |
107 | Q_INVOKABLE QQuickItem *loadPageWithProperties(const QString &url, const QVariantMap &properties, QJSValue callback = QJSValue()); |
108 | |
109 | /*! |
110 | * @returns The url of the page for the given instance, empty if there is no correspondence |
111 | */ |
112 | Q_INVOKABLE QUrl urlForPage(QQuickItem *item) const; |
113 | |
114 | /*! |
115 | * @returns The page associated with a given URL, nullptr if there is no correspondence |
116 | */ |
117 | Q_INVOKABLE QQuickItem *pageForUrl(const QUrl &url) const; |
118 | |
119 | /*! |
120 | * @returns true if the is managed by the PagePool |
121 | * @param the page can be either a QQuickItem or an url |
122 | */ |
123 | Q_INVOKABLE bool contains(const QVariant &page) const; |
124 | |
125 | /*! |
126 | * Deletes the page (only if is managed by the pool. |
127 | * @param page either the url or the instance of the page |
128 | */ |
129 | Q_INVOKABLE void deletePage(const QVariant &page); |
130 | |
131 | /*! |
132 | * @returns full url from an absolute or relative path |
133 | */ |
134 | Q_INVOKABLE QUrl resolvedUrl(const QString &file) const; |
135 | |
136 | /*! |
137 | * @returns true if the url identifies a local resource (local file or a file inside Qt's resource system). |
138 | * False if the url points to a network location |
139 | */ |
140 | Q_INVOKABLE bool isLocalUrl(const QUrl &url); |
141 | |
142 | /*! |
143 | * Deletes all pages managed by the pool. |
144 | */ |
145 | Q_INVOKABLE void clear(); |
146 | |
147 | Q_SIGNALS: |
148 | void lastLoadedUrlChanged(); |
149 | void lastLoadedItemChanged(); |
150 | void itemsChanged(); |
151 | void urlsChanged(); |
152 | void cachePagesChanged(); |
153 | |
154 | private: |
155 | QQuickItem *createFromComponent(QQmlComponent *component, const QVariantMap &properties); |
156 | |
157 | QUrl m_lastLoadedUrl; |
158 | QPointer<QQuickItem> m_lastLoadedItem; |
159 | QHash<QUrl, QQuickItem *> m_itemForUrl; |
160 | QHash<QUrl, QQmlComponent *> m_componentForUrl; |
161 | QHash<QQuickItem *, QUrl> m_urlForItem; |
162 | |
163 | bool m_cachePages = true; |
164 | }; |
165 | |