File indexing completed on 2024-05-12 07:47:32
0001 /* 0002 SPDX-FileCopyrightText: 2013 Marco Martin <mart@kde.org> 0003 SPDX-FileCopyrightText: 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef PLASMA_SHAREDQMLENGINE_H 0009 #define PLASMA_SHAREDQMLENGINE_H 0010 0011 #include <QObject> 0012 #include <QQmlComponent> 0013 #include <QQmlContext> 0014 0015 #include <memory> 0016 0017 class QQmlComponent; 0018 class QQmlEngine; 0019 class KLocalizedContext; 0020 class SharedQmlEnginePrivate; 0021 0022 0023 /** 0024 * @class Plasma::SharedQmlEngine Plasma/sharedqmlengine.h Plasma/SharedQmlEngine 0025 * 0026 * @short An object that instantiates an entire QML context, with its own declarative engine 0027 * 0028 * Plasma::SharedQmlEngine provides a class to conveniently use QML based 0029 * declarative user interfaces. 0030 * A SharedQmlEngine corresponds to one QML file (which can include others). 0031 * It will a shared QQmlEngine with a single root object, described in the QML file. 0032 */ 0033 class SharedQmlEngine : public QObject 0034 { 0035 Q_OBJECT 0036 0037 Q_PROPERTY(QUrl source READ source WRITE setSource) 0038 Q_PROPERTY(QString translationDomain READ translationDomain WRITE setTranslationDomain) 0039 Q_PROPERTY(bool initializationDelayed READ isInitializationDelayed WRITE setInitializationDelayed) 0040 Q_PROPERTY(QObject *rootObject READ rootObject) 0041 Q_PROPERTY(QQmlComponent::Status status READ status NOTIFY statusChanged) 0042 0043 public: 0044 /** 0045 * Construct a new Plasma::SharedQmlEngine 0046 * 0047 * @param parent The QObject parent for this object. 0048 */ 0049 explicit SharedQmlEngine(const std::shared_ptr<QQmlEngine> &engine, QObject *parent = nullptr); 0050 0051 ~SharedQmlEngine() override; 0052 0053 /** 0054 * Call this method before calling setupBindings to install a translation domain for all 0055 * i18n global functions. If a translation domain is set all i18n calls delegate to the 0056 * matching i18nd calls with the provided translation domain. 0057 * 0058 * The translationDomain affects all i18n calls including those from imports. Because of 0059 * that modules intended to be used as imports should prefer the i18nd variants and set 0060 * the translation domain explicitly in each call. 0061 * 0062 * This method is only required if your declarative usage is inside a library. If it's 0063 * in an application there is no need to set the translation domain as the application's 0064 * domain can be used. 0065 * 0066 * @param translationDomain The translation domain to be used for i18n calls. 0067 */ 0068 void setTranslationDomain(const QString &translationDomain); 0069 0070 /** 0071 * @return the translation domain for the i18n calls done in this QML engine 0072 */ 0073 QString translationDomain() const; 0074 0075 /** 0076 * Sets the path of the QML file to parse and execute 0077 * 0078 * @param path the absolute path of a QML file 0079 */ 0080 void setSource(const QUrl &source); 0081 0082 /** 0083 * @return the absolute path of the current QML file 0084 */ 0085 QUrl source() const; 0086 0087 /** 0088 * Sets whether the execution of the QML file has to be delayed later in the event loop. It has to be called before setQmlPath(). 0089 * In this case it will be possible to assign new objects in the main engine context 0090 * before the main component gets initialized. 0091 * In that case it will be possible to access it immediately from the QML code. 0092 * The initialization will either be completed automatically asynchronously 0093 * or explicitly by calling completeInitialization() 0094 * 0095 * @param delay if true the initialization of the QML file will be delayed 0096 * at the end of the event loop 0097 */ 0098 void setInitializationDelayed(const bool delay); 0099 0100 /** 0101 * @return true if the initialization of the QML file will be delayed 0102 * at the end of the event loop 0103 */ 0104 bool isInitializationDelayed() const; 0105 0106 /** 0107 * @return the declarative engine that runs the qml file assigned to this widget. 0108 */ 0109 std::shared_ptr<QQmlEngine> engine(); 0110 0111 /** 0112 * @return the root object of the declarative object tree 0113 */ 0114 QObject *rootObject() const; 0115 0116 /** 0117 * @return the main QQmlComponent of the engine 0118 */ 0119 QQmlComponent *mainComponent() const; 0120 0121 /** 0122 * The components's creation context. 0123 */ 0124 QQmlContext *rootContext() const; 0125 0126 /** 0127 * The component's current status. 0128 */ 0129 QQmlComponent::Status status() const; 0130 0131 /** 0132 * Creates and returns an object based on the provided url to a Qml file 0133 * with the same QQmlEngine and the same root context as the main object, 0134 * that will be the parent of the newly created object 0135 * @param source url where the QML file is located 0136 * @param context The QQmlContext in which we will create the object, 0137 * if 0 it will use the engine's root context 0138 * @param initialProperties optional properties that will be set on 0139 * the object when created (and before Component.onCompleted 0140 * gets emitted 0141 */ 0142 QObject *createObjectFromSource(const QUrl &source, QQmlContext *context = nullptr, const QVariantMap &initialProperties = QVariantMap()); 0143 0144 /** 0145 * Creates and returns an object based on the provided QQmlComponent 0146 * with the same QQmlEngine and the same root context as the admin object, 0147 * that will be the parent of the newly created object 0148 * @param component the component we want to instantiate 0149 * @param context The QQmlContext in which we will create the object, 0150 * if 0 it will use the engine's root context 0151 * @param initialProperties optional properties that will be set on 0152 * the object when created (and before Component.onCompleted 0153 * gets emitted 0154 */ 0155 QObject *createObjectFromComponent(QQmlComponent *component, QQmlContext *context = nullptr, const QVariantMap &initialProperties = QVariantMap()); 0156 0157 public Q_SLOTS: 0158 /** 0159 * Finishes the process of initialization. 0160 * If isInitializationDelayed() is false, calling this will have no effect. 0161 * @param initialProperties optional properties that will be set on 0162 * the object when created (and before Component.onCompleted 0163 * gets emitted 0164 */ 0165 void completeInitialization(const QVariantMap &initialProperties = QVariantMap()); 0166 0167 Q_SIGNALS: 0168 /** 0169 * Emitted when the parsing and execution of the QML file is terminated 0170 */ 0171 void finished(); 0172 0173 void statusChanged(QQmlComponent::Status); 0174 0175 private: 0176 const std::unique_ptr<SharedQmlEnginePrivate> d; 0177 }; 0178 0179 #endif // multiple inclusion guard