QML QQmlEngine

QQmlEngine

• Qt 官方文档: https://doc.qt.io/qt-5/qqmlengine.html#rootContext
• QQmlEngine类提供了一个实例化QML组件的环境。
  • Header:   #include <QQmlEngine>
  • qmake:    QT += qml
  • Since:      Qt 5.0
  • Inherits:    QJSEngine
  • Inherited By:QQmlApplicationEngine
• 公共属性

enum	ObjectOwnership { CppOwnership, JavaScriptOwnership }

• 属性

offlineStoragePath : QString

• 公共槽

void	retranslate()

• 信号

void	exit(int retCode)
void	quit()
void	warnings(const QList<QQmlError> &warnings)

• 静态公共成员

QQmlContext *	contextForObject(const QObject *object)
QQmlEngine::ObjectOwnership	objectOwnership(QObject *object)
void	setContextForObject(QObject *object, QQmlContext *context)
void	setObjectOwnership(QObject *object, QQmlEngine::ObjectOwnership ownership)

• 重新实现保护函数

virtual bool	event(QEvent *e) override

详细说明

• 每个QML组件在 QQmlContext中实例化。
  • QQmlContext对于向QML组件传递数据是必不可少的。
  • 在QML中，上下文按层次结构排列，该层次结构由QQmlEngine管理。
• 在创建任何QML组件之前，应用程序必须创建QQmlEngine以获得对QML上下文的访问。
• 下面的示例展示了如何创建一个简单的Text项。

QQmlEngine engine;
QQmlComponent component(&engine);
component.setData("import QtQuick 2.0\nText { text: \"Hello world!\" }", QUrl());
QQuickItem *item = qobject_cast<QQuickItem *>(component.create());

//add item to view, etc
...

• 在这种情况下，Text项将在引擎的根上下文中创建。
• 参考：QQmlComponent, QQmlContext, 和QML Global Object.

成员类型文档

【enum QQmlEngine::ObjectOwnership】

• objectowownership控制当相应的JavaScript对象被引擎垃圾收集时QML是否自动销毁QObject。两种所有权选择是:

Constant	Value	Description
QQmlEngine::CppOwnership	0	对象属于c++代码，QML永远不会删除它。JavaScript destroy()方法不能用于这些对象。这个选项类似于QScriptEngine::QtOwnership.
QQmlEngine::JavaScriptOwnership	1	对象属于JavaScript。当该对象作为方法调用的返回值返回给QML时，QML将跟踪并删除该对象，如果该对象没有剩余的JavaScript引用，也没有QObject::parent()。一个QQmlEngine跟踪的对象将在该QQmlEngine的析构函数期间被删除。因此，如果删除了其中一个引擎，那么来自两个不同引擎的具有javascriptow所有权的对象之间的JavaScript引用将无效。这个选项类似于QScriptEngine::ScriptOwnership.

• 通常，应用程序不需要显式地设置对象的所有权。QML使用启发式方法设置默认所有权。
• 默认情况下，由QML创建的对象具有javascriptow所有权。
  • 例外的是通过调用QQmlComponent::create()或 QQmlComponent::beginCreate()创建的根对象，它们默认拥有cppow所有权。
  • 这些根级对象的所有权被认为已经转移给了c++调用者。
• 不是由QML创建的对象默认具有CppOwnership。
  • 例外的是c++方法调用返回的对象;他们的所有权将被设置为javascriptowownership。
  • 这只适用于Q_INVOKABLE方法或槽的显式调用，但不适用于属性getter调用。
• 调用 setObjectOwnership()会覆盖QML使用的默认所有权启发法。

属性文档

【offlineStoragePath : QString】

• 此属性保存用于存储离线用户数据的目录
• 返回放置SQL和其他脱机存储的目录。
• 使用openDatabase()创建的SQL数据库存储在这里。
• 默认值是平台标准用户应用程序数据目录中的QML/OfflineStorage。
• 请注意，该路径当前可能在文件系统上不存在，因此希望在此位置创建新文件的调用者应首先创建它-请参阅QDir::mkpath()。
• 相关函数：

QString	offlineStoragePath() const
void	setOfflineStoragePath(const QString &dir)

成员函数文档

【QQmlEngine::QQmlEngine(QObject *parent = nullptr)】

• 使用给定的父节点创建一个新的QQmlEngine。

 

【[signal]void QQmlEngine::exit(int retCode)】

• 当引擎加载的QML希望使用指定的返回码retCode退出事件循环时，将发出此信号。
• 该函数是在Qt 5.8中引入的。

 

【[signal]void QQmlEngine::quit()】

• 当引擎加载的QML想要退出时，就会发出此信号。

 

【[slot]void QQmlEngine::retranslate()】

• 刷新所有使用标记为转换的字符串的绑定表达式。
• 使用QCoreApplication::installTranslator安装一个新的翻译程序后调用这个函数，以确保您的用户界面显示最新的翻译。
• 注意:由于实现中的限制，该函数刷新了所有引擎的绑定，而不仅仅是那些使用标记为翻译的字符串的绑定。这可能会在未来的版本中得到优化。
• 该函数是在Qt 5.10中引入的。

 

【[signal]void QQmlEngine::warnings(const QList<QQmlError> &warnings)】

• 当QML生成警告消息时，将发出此信号。

 

【[override virtual] QQmlEngine::~QQmlEngine()】

• 销毁QQmlEngine。
• 在这个引擎上创建的任何QQmlContext都将失效，但不会被销毁(除非它们是QQmlEngine对象的父对象)。
• 关于清理JS引擎的详细信息，请参阅QJSEngine 文档。

 

【void QQmlEngine::addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)】

• 用主机providerId设置提供程序，以用于通过image: url方案请求的图像。QQmlEngine获取提供者的所有权。
• 图像提供程序支持pixmap和线程化图像请求。有关实现和使用图像提供程序的详细信息，请参见 QQuickImageProvider 文档

 

【void QQmlEngine::addImportPath(const QString &path)】

• 添加path作为一个目录，该引擎在基于url的目录结构中搜索已安装的模块。
• 该路径可以是本地文件系统目录、 Qt Resource path(:/imports)、 Qt Resource url (qrc:/imports)或URL。
• 在将路径添加到导入路径列表之前，该路径将被转换为规范形式。
• 新添加的路径将是 importPathList()中的第一个路径。
• 参考：setImportPathList() and QML Modules.

 

【void QQmlEngine::addPluginPath(const QString &path)】

• 添加path作为一个目录，引擎在其中为导入的模块搜索本机插件(在qmldir文件中引用)。
• 默认情况下，列表只包含 ., i.e。即引擎在qmldir文件本身的目录中搜索。
• 新添加的路径将是pluginPathList()中的第一个路径。
• 参考：setPluginPathList().

 

【QUrl QQmlEngine::baseUrl() const】

• 返回此引擎的基URL。当相对URL被传递给QQmlComponent构造函数时，基URL仅用于解析组件。
• 如果没有显式设置基URL，此方法将返回应用程序的当前工作目录。
• 参考： setBaseUrl().

 

【void QQmlEngine::clearComponentCache()】

• 清除引擎的内部组件缓存。
• 此函数将销毁之前由引擎加载的所有组件的属性元数据。
  • 所有以前加载的组件和从这些组件创建的所有现有对象的属性绑定将停止工作。
• 这个函数将引擎返回到一个不包含任何已加载组件数据的状态。
  • 为了重新加载以前加载的组件集的较小子集，或者加载以前加载的组件的新版本，这可能很有用。
• 参考：trimComponentCache()

 

【[static] QQmlContext *QQmlEngine::contextForObject(const QObject *object)】

• 返回对象的QQmlContext，如果没有设置上下文则返回0。
• 当QQmlEngine实例化一个QObject时，上下文将自动设置。
•  参考：setContextForObject(), qmlContext(), and qmlEngine().

 

【[override virtual protected]bool QQmlEngine::event(QEvent *e)】

• 重构:QObject::event(QEvent * e)。

 

【QQmlImageProviderBase *QQmlEngine::imageProvider(const QString &providerId) const】

• 如果找到，返回providerId的图像提供程序集;否则返回nullptr
• 参考：QQuickImageProvider.

 

【QStringList QQmlEngine::importPathList() const】

• 返回引擎在基于url的目录结构中搜索已安装模块的目录列表。
  • 例如，如果路径中有/opt/MyApp/lib/imports，那么导入com.mycompany.Feature的QML会导致QQmlEngine在/opt/MyApp/lib/imports/com/mycompany/Feature/中查找该模块提供的组件。
  • 定义类型版本映射和可能的QML扩展插件需要一个qmldir文件。
• 默认情况下，该列表包含应用程序可执行文件的目录、在QML2_IMPORT_PATH环境变量中指定的路径，以及来自QLibraryInfo的内置qml2importpath。
• 参考：addImportPath() and setImportPathList().

 

【bool QQmlEngine::importPlugin(const QString &filePath, const QString &uri, QList<QQmlError> *errors)】

• 使用提供的uri导入名为filePath的插件。如果插件导入成功，返回true;否则返回false。
• 如果失败且非空，错误列表将在其前面添加任何发生的错误。
• 该插件必须是一个实现 QQmlEngineExtensionPlugin接口的Qt插件。

 

【QQmlIncubationController *QQmlEngine::incubationController() const】

• 返回当前设置的孵化期控制器，如果未设置控制器则返回0。
• 参考：setIncubationController().

 

【QNetworkAccessManager *QQmlEngine::networkAccessManager() const】

• 返回一个通用的QNetworkAccessManager，可以由该引擎实例化的任何QML类型使用。
• 如果已经设置了 QQmlNetworkAccessManagerFactory ，并且还没有创建QNetworkAccessManager，那么将使用QQmlNetworkAccessManagerFactory来创建QNetworkAccessManager;否则返回的QNetworkAccessManager将没有代理或缓存集。
• 参考：setNetworkAccessManagerFactory().

 

【QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const】

• 返回当前的QQmlNetworkAccessManagerFactory。
• 参考：setNetworkAccessManagerFactory().

 

【[static]QQmlEngine::ObjectOwnership QQmlEngine::objectOwnership(QObject *object)】

• 返回对象的所有权。
• 参考：setObjectOwnership().

 

【QString QQmlEngine::offlineStorageDatabaseFilePath(const QString &databaseName) const】

• 返回标识符为databaseName的本地存储数据库（ Local Storage）所在的文件路径
• 该函数是在Qt 5.9中引入的。
• 参考：LocalStorage.openDatabaseSync()。

 

【bool QQmlEngine::outputWarningsToStandardError() const】

• 如果警告消息除了由warnings()信号发出外，还将输出到stderr，则返回true，否则返回false。
• 缺省值为true。
• 参考：setOutputWarningsToStandardError().

 

【QStringList QQmlEngine::pluginPathList() const】

• 返回引擎为导入的模块(在qmldir文件中引用)搜索本机插件的目录列表。
• 默认情况下，列表只包含 .，即引擎在qmldir文件本身的目录中搜索。
• 参考: addPluginPath() and setPluginPathList().

 

【void QQmlEngine::removeImageProvider(const QString &providerId)】

• 删除providerId的图像提供程序。
• 参考：addImageProvider() and QQuickImageProvider.

 

【QQmlContext *QQmlEngine::rootContext() const】

• 返回引擎的根上下文。
• 根上下文是由QQmlEngine自动创建的。由引擎实例化的所有QML组件实例应该可用的数据应该放在根上下文中。
• 应该将只对组件实例子集可用的其他数据添加到根上下文的父子上下文中。

 

【void QQmlEngine::setBaseUrl(const QUrl &url)】

• 将此引擎的基本URL设置为url。
• 参考：baseUrl().

 

【[static]void QQmlEngine::setContextForObject(QObject *object, QQmlContext *context)】

• 将对象的QQmlContext设置为context。如果对象已经有上下文，则输出一个警告，但上下文不会改变。
• 当QQmlEngine实例化一个QObject时，上下文将自动设置。
• 参考：contextForObject().

 

【void QQmlEngine::setImportPathList(const QStringList &paths)】

• 将路径设置为引擎在基于URL的目录结构中搜索已安装模块的目录列表。。
• 默认情况下，该列表包含应用程序可执行文件的目录、在QML2_IMPORT_PATH环境变量中指定的路径，以及来自QLibraryInfo的内置qml2importpath。
• 参考： importPathList() and addImportPath().

 

【void QQmlEngine::setIncubationController(QQmlIncubationController *controller)】

• 设置引擎孵化控制器。引擎只能有一个主动控制器，它拥有所有权。
• 参考：incubationController().

 

【void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)】

• 设置用于创建QNetworkAccessManager的工厂。
• QNetworkAccessManager用于QML的所有网络访问。通过实现工厂，可以创建具有专用缓存、代理和cookie支持的自定义QNetworkAccessManager。
• 在启动引擎之前必须先将工厂设置好。
• 注:QQmlEngine不拥有工厂所有权
• 参考：networkAccessManagerFactory()

 

【[static]void QQmlEngine::setObjectOwnership(QObject *object, QQmlEngine::ObjectOwnership ownership)】

• 设置对象的所有权。
• 参考： objectOwnership().

 

【void QQmlEngine::setOutputWarningsToStandardError(bool enabled)】

• 将警告消息是否输出到stderr设置为启用。
• 如果enabled为true, QML生成的任何警告消息都将输出到stderr，并由warnings()信号发出。
  • 如果enabled为false，则只会发出warnings()信号。这允许应用程序自己处理警告输出。
• 缺省值为true。
• 参考：outputWarningsToStandardError().

 

【void QQmlEngine::setPluginPathList(const QStringList &paths)】

• 将引擎为导入模块(在qmldir文件中引用)搜索本机插件的目录列表设置为路径。
• 默认情况下，列表只包含.，即引擎在qmldir文件本身的目录中搜索。
• 参考：pluginPathList() and addPluginPath().

 

【template <typename T> T QQmlEngine::singletonInstance(int qmlTypeId)】

• 返回在qmlTypeId下注册的单例类型的实例。
• 模板参数T可以是 QJSValue，也可以是qobject派生类型的指针，这取决于单例对象是如何注册的。
  • 如果还没有创建T的实例，那么现在就创建它。
  • 如果qmlTypeId不代表有效的单例类型，则返回默认构造的QJSValue或nullptr。
• QObject *的例子:

class MySingleton : public QObject {
  Q_OBJECT

  // Register as default constructed singleton.
  QML_ELEMENT
  QML_SINGLETON

  static int typeId;
  // ...
};

MySingleton::typeId = qmlTypeId(...);

// Retrieve as QObject*
QQmlEngine engine;
MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

• QJSValue例子:

// Register with QJSValue callback
int typeId = qmlRegisterSingletonType(...);

// Retrieve as QJSValue
QQmlEngine engine;
QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

• 建议将QML类型id存储在单例类中，例如作为静态成员。通过qmlTypeId()进行查找代价很高。
• 该函数是在Qt 5.12中引入的。
• 参考：QML_SINGLETON, qmlRegisterSingletonType(), and qmlTypeId().

 

【void QQmlEngine::trimComponentCache()】

• 调整引擎的内部组件缓存。
• 此函数将销毁当前未使用的任何已加载组件的属性元数据。
• 如果一个组件本身存在任何实例，任何使用该组件的其他组件的实例，或任何由这些组件实例化的对象，则该组件被认为是在使用中。
• 参考：clearComponentCache().

【C++ 注册流程图】