KDeclarative

qmlobject.h
1 /*
2  SPDX-FileCopyrightText: 2013 Marco Martin <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef QMLOBJECT_H
8 #define QMLOBJECT_H
9 
10 #include <QObject>
11 
12 #include <QQmlComponent>
13 
14 #include <kdeclarative/kdeclarative_export.h>
15 
16 #if KDECLARATIVE_ENABLE_DEPRECATED_SINCE(5, 98)
17 #include <KPackage/Package>
18 #endif
19 
20 class QQmlEngine;
21 class QQmlComponent;
22 class QQmlContext;
23 
24 namespace KDeclarative
25 {
26 class QmlObjectPrivate;
27 
28 /**
29  * @class KDeclarative::QmlObject qmlobject.h KDeclarative/QmlObject
30  *
31  * @author Marco Martin <[email protected]>
32  *
33  * @short An object that instantiates an entire QML context, with its own declarative engine
34  *
35  * KDeclarative::QmlObject provides a class to conveniently use QML based
36  * declarative user interfaces inside Plasma widgets.
37  * A QmlObject corresponds to one QML file (which can include others).
38  * It will have its own QQmlEngine with a single root object,
39  * described in the QML file.
40  */
41 class KDECLARATIVE_EXPORT QmlObject : public QObject
42 {
43  Q_OBJECT
44 
45  Q_PROPERTY(QUrl source READ source WRITE setSource)
46  Q_PROPERTY(QString translationDomain READ translationDomain WRITE setTranslationDomain)
47  Q_PROPERTY(bool initializationDelayed READ isInitializationDelayed WRITE setInitializationDelayed)
48  Q_PROPERTY(QObject *rootObject READ rootObject)
49  Q_PROPERTY(QQmlComponent::Status status READ status NOTIFY statusChanged)
50 
51 public:
52  /**
53  * Constructs a new QmlObject
54  *
55  * @param parent the parent of this object
56  */
57  explicit QmlObject(QObject *parent = nullptr);
58 
59  /**
60  * Constructs a new QmlObject
61  *
62  * @param engine a QQmlEngine we want to use
63  * @param parent the parent of this object
64  *
65  * @deprecated Since 5.95, Use QmlObject(std::shared_ptr<QmlEngine>, QObject*)
66  * instead.
67  */
68 #if KDECLARATIVE_ENABLE_DEPRECATED_SINCE(5, 95)
69  KDECLARATIVE_DEPRECATED_VERSION(5, 95, "Use QmlObject(std::shared_ptr<QQmlEngine>, QmlContext*, QObject*) instead")
70  explicit QmlObject(QQmlEngine *engine, QObject *parent = nullptr);
71 #endif
72 
73  /**
74  * Constructs a new QmlObject
75  *
76  * @param engine the QQmlEngine to use
77  * @param rootContext the root context to use for object creation
78  * @param parent the parent of this object
79  *
80  * @deprecated Since 5.95, Use QmlObject(std::shared_ptr<QmlEngine>, QmlContext*, QObject*)
81  * instead.
82  */
83 #if KDECLARATIVE_ENABLE_DEPRECATED_SINCE(5, 95)
84  KDECLARATIVE_DEPRECATED_VERSION(5, 95, "Use QmlObject(std::shared_ptr<QQmlEngine>, QQmlContext*, QObject*) instead")
85  explicit QmlObject(QQmlEngine *engine, QQmlContext *rootContext, QObject *parent = nullptr);
86 #endif
87 
88  /**
89  * Construct a new QmlObject
90  *
91  * @param engine The QQmlEngine to use. If this object is the first user of
92  * the engine (e.g. use_count() is 1), KDeclarative::setupEngine() will be
93  * called. If this is nullptr, a new engine will be created for this object
94  * to use.
95  * @param rootContext The QML context to use for object creation. If this is
96  * nullptr, the engine's root context will be used.
97  * @param parent The QObject parent for this object.
98  */
99  explicit QmlObject(std::shared_ptr<QQmlEngine> engine, QQmlContext *rootContext = nullptr, QObject *parent = nullptr);
100 
101  ~QmlObject() override;
102 
103  /**
104  * Call this method before calling setupBindings to install a translation domain for all
105  * i18n global functions. If a translation domain is set all i18n calls delegate to the
106  * matching i18nd calls with the provided translation domain.
107  *
108  * The translationDomain affects all i18n calls including those from imports. Because of
109  * that modules intended to be used as imports should prefer the i18nd variants and set
110  * the translation domain explicitly in each call.
111  *
112  * This method is only required if your declarative usage is inside a library. If it's
113  * in an application there is no need to set the translation domain as the application's
114  * domain can be used.
115  *
116  * @param translationDomain The translation domain to be used for i18n calls.
117  * @since 5.0
118  */
119  void setTranslationDomain(const QString &translationDomain);
120 
121  /**
122  * @return the translation domain for the i18n calls done in this QML engine
123  * @since 5.0
124  */
125  QString translationDomain() const;
126 
127  /**
128  * Sets the path of the QML file to parse and execute
129  *
130  * @param path the absolute path of a QML file
131  */
132  void setSource(const QUrl &source);
133 
134  /**
135  * @return the absolute path of the current QML file
136  */
137  QUrl source() const;
138 
139 #if KDECLARATIVE_ENABLE_DEPRECATED_SINCE(5, 98)
140  /**
141  * Load the package called packageName, then loads the
142  * mainscript file for that package
143  *
144  * @param packageName the plugin name of the package
145  * @seprecated Since 5.98, use KPackage manually and set the source URL to the "mainscript" file path
146  */
147  KDECLARATIVE_DEPRECATED_VERSION(5, 98, "use KPackage manually and set the source URL to the \"mainscript\" file path")
148  void loadPackage(const QString &packageName);
149 
150  /**
151  * Sets a package, then loads the
152  * mainscript file for that package
153  *
154  * @param package the package we want to use to provide QML
155  * files to this QML object
156  * @seprecated Since 5.98, use KPackage manually and set the source URL to the "mainscript" file path
157  */
158  KDECLARATIVE_DEPRECATED_VERSION(5, 98, "use KPackage manually and set the source URL to the \"mainscript\" file path")
159  void setPackage(const KPackage::Package &package);
160 
161  /**
162  * @return the optional package, if any
163  * @seprecated Since 5.98, use KPackage manually and set the source URL to the "mainscript" file path
164  */
165  KDECLARATIVE_DEPRECATED_VERSION(5, 98, "use KPackage manually and set the source URL to the \"mainscript\" file path")
166  KPackage::Package package() const;
167 #endif
168 
169  /**
170  * Sets whether the execution of the QML file has to be delayed later in the event loop. It has to be called before setQmlPath().
171  * In this case it will be possible to assign new objects in the main engine context
172  * before the main component gets initialized.
173  * In that case it will be possible to access it immediately from the QML code.
174  * The initialization will either be completed automatically asynchronously
175  * or explicitly by calling completeInitialization()
176  *
177  * @param delay if true the initialization of the QML file will be delayed
178  * at the end of the event loop
179  */
180  void setInitializationDelayed(const bool delay);
181 
182  /**
183  * @return true if the initialization of the QML file will be delayed
184  * at the end of the event loop
185  */
186  bool isInitializationDelayed() const;
187 
188  /**
189  * @return the declarative engine that runs the qml file assigned to this widget.
190  */
191  QQmlEngine *engine();
192 
193  /**
194  * @return the root object of the declarative object tree
195  */
196  QObject *rootObject() const;
197 
198  /**
199  * @return the main QQmlComponent of the engine
200  */
201  QQmlComponent *mainComponent() const;
202 
203  /**
204  * The components's creation context.
205  * @since 5.11
206  */
207  QQmlContext *rootContext() const;
208 
209  /**
210  * The component's current status.
211  * @since 5.11
212  */
213  QQmlComponent::Status status() const;
214 
215  /**
216  * Creates and returns an object based on the provided url to a Qml file
217  * with the same QQmlEngine and the same root context as the main object,
218  * that will be the parent of the newly created object
219  * @param source url where the QML file is located
220  * @param context The QQmlContext in which we will create the object,
221  * if 0 it will use the engine's root context
222  * @param initialProperties optional properties that will be set on
223  * the object when created (and before Component.onCompleted
224  * gets emitted
225  */
226  QObject *createObjectFromSource(const QUrl &source, QQmlContext *context = nullptr, const QVariantHash &initialProperties = QVariantHash());
227 
228  /**
229  * Creates and returns an object based on the provided QQmlComponent
230  * with the same QQmlEngine and the same root context as the admin object,
231  * that will be the parent of the newly created object
232  * @param component the component we want to instantiate
233  * @param context The QQmlContext in which we will create the object,
234  * if 0 it will use the engine's root context
235  * @param initialProperties optional properties that will be set on
236  * the object when created (and before Component.onCompleted
237  * gets emitted
238  */
239  QObject *createObjectFromComponent(QQmlComponent *component, QQmlContext *context = nullptr, const QVariantHash &initialProperties = QVariantHash());
240 
241 public Q_SLOTS:
242  /**
243  * Finishes the process of initialization.
244  * If isInitializationDelayed() is false, calling this will have no effect.
245  * @param initialProperties optional properties that will be set on
246  * the object when created (and before Component.onCompleted
247  * gets emitted
248  */
249  void completeInitialization(const QVariantHash &initialProperties = QVariantHash());
250 
251 Q_SIGNALS:
252  /**
253  * Emitted when the parsing and execution of the QML file is terminated
254  */
255  void finished();
256 
257  void statusChanged(QQmlComponent::Status);
258 
259 protected:
260  /**
261  * Constructs a new QmlObject
262  *
263  * @param engine a QQmlEngine we want to use
264  * @param rootContext the root context we want to use for objects creation
265  * @param obj setupEngine is called when this is set to nullptr. This way the creator can
266  * influence if the engine should be initialized or not in case it is shared between
267  * multiple objects (such as QmlObjectSharedEngine)
268  * @param parent the parent of this object
269  * @since 5.45
270  *
271  * @deprecated Since 5.95, Use QmlObject(std::shared_ptr<QmlEngine>, QmlContext*, QObject*)
272  * instead. The "obj" parameter has been dropped, instead setupEngine will be
273  * called if this QmlObject is the first user of the engine.
274  */
275 #if KDECLARATIVE_ENABLE_DEPRECATED_SINCE(5, 95)
276  KDECLARATIVE_DEPRECATED_VERSION(5, 95, "Use QmlObject(std::shared_ptr<QQmlEngine>, QQmlContext*, QObject*) instead")
277  explicit QmlObject(QQmlEngine *engine, QQmlContext *rootContext, QmlObject *obj, QObject *parent = nullptr);
278 #endif
279 
280 private:
281  friend class QmlObjectPrivate;
282  QmlObjectPrivate *const d;
283 
284  Q_PRIVATE_SLOT(d, void scheduleExecutionEnd())
285  Q_PRIVATE_SLOT(d, void checkInitializationCompleted())
286 };
287 
288 }
289 
290 #endif // multiple inclusion guard
An object that instantiates an entire QML context, with its own declarative engine.
Definition: qmlobject.h:41
virtual QVariant rootObject()
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Sep 25 2022 03:58:34 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.