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

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