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 */
29class 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
76public:
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
147Q_SIGNALS:
148 void lastLoadedUrlChanged();
149 void lastLoadedItemChanged();
150 void itemsChanged();
151 void urlsChanged();
152 void cachePagesChanged();
153
154private:
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

source code of kirigami/src/pagepool.h