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

source code of kirigami/src/pagepool.h