1/*
2 SPDX-FileCopyrightText: 2013 Marco Martin <mart@kde.org>
3 SPDX-FileCopyrightText:
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef PLASMA_SHAREDQMLENGINE_H
9#define PLASMA_SHAREDQMLENGINE_H
10
11#include "ki18n_version.h"
12#include <QObject>
13#include <QQmlComponent>
14#include <QQmlContext>
15
16#include <memory>
17
18class QQmlComponent;
19class QQmlEngine;
20class KLocalizedQmlContext;
21class SharedQmlEnginePrivate;
22
23/*
24 * An object that instantiates an entire QML context, with its own declarative engine
25 *
26 * SharedQmlEngine provides a class to conveniently use QML based
27 * declarative user interfaces.
28 *
29 * A SharedQmlEngine corresponds to one QML file (which can include others).
30 * It will a shared QQmlEngine with a single root object, described in the QML file.
31 */
32class SharedQmlEngine : public QObject
33{
34 Q_OBJECT
35
36 Q_PROPERTY(QUrl source READ source WRITE setSource)
37 Q_PROPERTY(QString translationDomain READ translationDomain WRITE setTranslationDomain)
38 Q_PROPERTY(bool initializationDelayed READ isInitializationDelayed WRITE setInitializationDelayed)
39 Q_PROPERTY(QObject *rootObject READ rootObject)
40
41public:
42 /*
43 * Construct a new Plasma::SharedQmlEngine
44 *
45 * parent The QObject parent for this object.
46 */
47 explicit SharedQmlEngine(const std::shared_ptr<QQmlEngine> &engine, QObject *parent = nullptr);
48
49 ~SharedQmlEngine() override;
50
51 /*
52 * Call this method before calling setupBindings to install a translation domain for all
53 * i18n global functions. If a translation domain is set all i18n calls delegate to the
54 * matching i18nd calls with the provided translation domain.
55 *
56 * The translationDomain affects all i18n calls including those from imports. Because of
57 * that modules intended to be used as imports should prefer the i18nd variants and set
58 * the translation domain explicitly in each call.
59 *
60 * This method is only required if your declarative usage is inside a library. If it's
61 * in an application there is no need to set the translation domain as the application's
62 * domain can be used.
63 *
64 * translationDomain The translation domain to be used for i18n calls.
65 */
66 void setTranslationDomain(const QString &translationDomain);
67
68 /*
69 * Returns the translation domain for the i18n calls done in this QML engine
70 */
71 QString translationDomain() const;
72
73 /*
74 * Sets the path of the QML file to parse and execute
75 *
76 * path the absolute path of a QML file
77 */
78 void setSource(const QUrl &source);
79
80 /*
81 * Returns the absolute path of the current QML file
82 */
83 QUrl source() const;
84
85 /*
86 * Sets whether the execution of the QML file has to be delayed later in the event loop. It has to be called before setQmlPath().
87 * In this case it will be possible to assign new objects in the main engine context
88 * before the main component gets initialized.
89 * In that case it will be possible to access it immediately from the QML code.
90 * The initialization will either be completed automatically asynchronously
91 * or explicitly by calling completeInitialization()
92 *
93 * delay if true the initialization of the QML file will be delayed
94 * at the end of the event loop
95 */
96 void setInitializationDelayed(const bool delay);
97
98 /*
99 * Returns true if the initialization of the QML file will be delayed
100 * at the end of the event loop
101 */
102 bool isInitializationDelayed() const;
103
104 /*
105 * Returns the declarative engine that runs the qml file assigned to this widget.
106 */
107 std::shared_ptr<QQmlEngine> engine();
108
109 /*
110 * Returns the root object of the declarative object tree
111 */
112 QObject *rootObject() const;
113
114 /*
115 * Returns the main QQmlComponent of the engine
116 */
117 QQmlComponent *mainComponent() const;
118
119 /*
120 * The component's creation context.
121 */
122 QQmlContext *rootContext() const;
123
124 /*
125 * The component's or incubator's error status.
126 */
127 bool isError() const;
128
129 /*
130 * The component's or incubator's error string.
131 */
132 QString errorString() const;
133
134 /*
135 * Creates and returns an object based on the provided url to a Qml file
136 * with the same QQmlEngine and the same root context as the main object,
137 * that will be the parent of the newly created object
138 * source url where the QML file is located
139 * context The QQmlContext in which we will create the object,
140 * if 0 it will use the engine's root context
141 * initialProperties optional properties that will be set on
142 * the object when created (and before Component.onCompleted
143 * gets emitted
144 */
145 QObject *createObjectFromSource(const QUrl &source, QQmlContext *context = nullptr, const QVariantMap &initialProperties = QVariantMap());
146
147 /*
148 * Creates and returns an object based on the provided QQmlComponent
149 * with the same QQmlEngine and the same root context as the admin object,
150 * that will be the parent of the newly created object
151 * component the component we want to instantiate
152 * context The QQmlContext in which we will create the object,
153 * if 0 it will use the engine's root context
154 * initialProperties optional properties that will be set on
155 * the object when created (and before Component.onCompleted
156 * gets emitted
157 */
158 QObject *createObjectFromComponent(QQmlComponent *component, QQmlContext *context = nullptr, const QVariantMap &initialProperties = QVariantMap());
159
160public Q_SLOTS:
161 /*
162 * Finishes the process of initialization.
163 * If isInitializationDelayed() is false, calling this will have no effect.
164 * initialProperties optional properties that will be set on
165 * the object when created (and before Component.onCompleted
166 * gets emitted
167 */
168 void completeInitialization(const QVariantMap &initialProperties = QVariantMap());
169
170Q_SIGNALS:
171 /*
172 * Emitted when the parsing and execution of the QML file is terminated
173 */
174 void finished();
175
176private:
177 const std::unique_ptr<SharedQmlEnginePrivate> d;
178};
179
180#endif // multiple inclusion guard
181

source code of kcmutils/src/quick/sharedqmlengine_p.h