QML QQmlEngine
template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
- 这将返回通过附加类型T附加到指定附加对象的附加对象实例。
- 如果create为true并且类型T是有效的附加类型,则创建并返回一个新的附加对象实例。
- 如果类型T不是有效的附加类型,或者如果create为false并且之前没有为附加对象创建任何附加对象实例,则返回0。
- 参考:QML_ATTACHED() 和Providing Attached Properties.
void qmlClearTypeRegistrations()
- 清除所有存储的类型注册,例如使用qmlRegisterType()生成的注册。
- 当 QQmlEngine存在时不要调用此函数,否则行为将未定义。
- 在调用此函数之前,必须删除任何现有的QQmlEngines。
- 此函数只影响应用程序全局缓存。删除QQmlEngine以清除与该引擎相关的所有缓存数据。
QQmlContext *qmlContext(const QObject *object)
- 返回与对象关联的QQmlContext(如果有的话)。
- 这相当于 QQmlEngine::contextForObject(object)。
- 注意:添加#include <QtQml>来使用这个函数。
- 参考:contextForObject() and qmlEngine().
QQmlEngine *qmlEngine(const QObject *object)
- 返回与对象关联的QQmlEngine(如果有的话)。这相当于 QQmlEngine::contextForObject(object)->engine(),但更高效。
- 注意:添加#include <QtQml>来使用这个函数。
- 参考:contextForObject() and qmlContext().
bool qmlProtectModule(const char *uri, int majVersion)
- 这个函数保护模块不被类型注册。这可以用来防止其他插件将类型注入到您的模块中。
- 它还可以提高性能,因为它允许引擎在导入时跳过对新类型或插件可能性的检查。
- 性能的好处主要体现在从应用程序内部注册特定的应用程序类型,而不是通过插件。
- 使用qmlProtectModule允许引擎在导入uri时跳过对插件的检查,这在缓慢的文件系统中是很明显的。
- 在这个函数被调用后,任何向这个uri注册c++类型的尝试,主要版本组合将导致运行时错误。
- 在向引擎注册了所有类型之后调用它。
- 如果以uri作为模块标识符(module identifier )且以majVersion作为主要版本号的模块被找到并锁定,则返回true,否则返回false。模块必须包含导出的类型才能被找到。
template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)
- 这个模板函数在QML系统中将c++类型注册为匿名类型。产生的QML类型没有名称。
- 因此,不能从QML系统创建此类型的实例。但是,当该类型的实例作为其他类型的属性公开时,您可以访问它们。
- 当类型不通过名称引用时,使用此函数,特别是对于在属性绑定left-hand 使用的c++类型。要指示类型属于哪个模块,请使用uri和versionMajor。
- 例如,考虑以下两个类
class Bar : public QObject { Q_OBJECT Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged) public: Bar() {} QString baz() const { return mBaz; } void setBaz(const QString &baz) { if (baz == mBaz) return; mBaz = baz; emit bazChanged(); } signals: void bazChanged(); private: QString mBaz; }; class Foo : public QObject { Q_OBJECT Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL) public: Foo() {} Bar *bar() { return &mBar; } private: Bar mBar; };
- 在QML中,我们为bar的baz属性赋值一个字符串:
Foo { bar.baz: "abc" Component.onCompleted: print(bar.baz) }
- 让QML引擎知道Bar类型有一个baz属性,我们必须让Bar知道:
qmlRegisterType<Foo>("App", 1, 0, "Foo"); qmlRegisterAnonymousType<Bar>("App", 1);
- 由于Foo类型在QML中实例化,它必须注册到带有元素名称的qmlRegisterType()版本中。
- 返回QML类型id。
- 该函数是在Qt 5.14中引入的。
- 参考:QML_EXTENDED(), qmlRegisterType(), and Registering Extension Objects.
template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
- 这个模板函数在QML系统中注册c++类型及其扩展,名称为qmlName,在从uri导入的库中,版本号由versionMajor和versionMinor组成
- 虽然类型有名称和类型,但不能创建它。如果用户试图创建该类型的实例,将打印带有给定原因的错误消息。
- 当类型仅用于提供附加属性、枚举值或抽象基类及其扩展时,这很有用。
- 返回QML类型id。
- 参考:QML_EXTENDED(), QML_UNCREATABLE(), 和qmlRegisterUncreatableType().
template <typename T> int qmlRegisterInterface(const char *typeName)
- 这个模板函数在QML系统中以typeName的名字注册c++类型。
- 在引擎中注册为接口的类型也应该声明自己为元对象系统(meta object system )的接口。例如:
struct FooInterface { public: virtual ~FooInterface(); virtual void doSomething() = 0; }; Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
- 当以这种方式注册到QML引擎时,它们可以作为属性类型使用:
Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)
- 当你将一个QObject子类赋给这个属性时,QML引擎会自动将接口转换为FooInterface*。
- 返回QML类型id。
- 参考:QML_INTERFACE.
void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)
- 这个函数在一个特定的uri中注册一个模块,该模块的版本在versionMajor和versionMinor中指定。
- 这可用于使某个模块版本可用,即使没有为该版本注册类型。这对于保持相关模块的版本同步特别有用。
- 该函数是在Qt 5.9中引入的。
template<typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);
- 这个模板函数在QML系统中注册c++类型的指定修订版本,使用从uri导入的库,该库的版本号由versionMajor和versionMinor组成。
- 返回QML类型id。
- 此函数通常用于注册基类的修订,以用于类型的指定版本(参考 Type Revisions and Versions)
int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
- 这个函数用于注册一个带有特定 uri 和typeName的单例对象cppObject。版本号为versionMajor和versionMinor的组合。
- 在URI中安装一个单例类型允许您向QML代码提供任意的功能(方法和属性),而不需要客户端实例化该类型的单个实例。
- 使用此函数将给定类型T的对象注册为单例类型。
- QObject单例类型可以通过注册它的类型名来引用; 反过来,此类型名可以用作Connections类型中的目标,或类似于任何其他类型ID。
- 然而,有一个例外:QObject单例类型属性不能有别名,因为单例类型名称不能识别与任何其他项相同组件中的对象。
- 注意:cppObject必须比使用它的QML引擎存在得更久。
- 此外,cppObject必须具有与引擎相同的线程关联。
- 如果你想为多个引擎提供单独的单例实例,你需要使用 qmlRegisterSingletonType。有关线程安全的更多信息,请参见 Threads and QObjects。
- 案例:
// First, define your QObject which provides the functionality. class SingletonTypeExample : public QObject { Q_OBJECT Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) public: explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {} Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } int someProperty() const { return m_someProperty; } void setSomeProperty(int val) { if (m_someProperty != val) { m_someProperty = val; emit somePropertyChanged(val); } } signals: void somePropertyChanged(int newValue); private: int m_someProperty = 0; };
// Second, create an instance of the object // allocate example before the engine to ensure that it outlives it QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample); QQmlEngine engine; // Third, register the singleton type provider with QML by calling this // function in an initialization function. qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());
- 为了在QML中使用已注册的单例类型,您必须导入具有相应版本的URI。
import QtQuick 2.0 import Qt.example.qobjectSingleton 1.0 Item { id: root property int someValue: MyApi.someProperty Component.onCompleted: { console.log(MyApi.doSomething()) } }
- 该函数是在Qt 5.14中引入的。
- 参考:QML_SINGLETON 和 qmlRegisterSingletonType.
int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue (*)(QQmlEngine *, QJSEngine *) callback)
- 这个函数可以用来在一个特定的uri和typeName中注册一个在versionMajor和versionMinor中指定的版本的单例类型提供程序回调。
- 安装单例类型允许开发人员向客户端提供任意的功能(方法和属性),而不需要客户端实例化该类型的单个实例。
- 一个单例类型可以是QObject或者QJSValue。此函数应用于注册一个单例类型提供程序函数,该函数将QJSValue作为单例类型返回。
- 注意:QJSValue单例类型属性如果改变将不会触发绑定重新计算
- 示例:
// First, define the singleton type provider function (callback). static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine) { Q_UNUSED(engine) static int seedValue = 5; QJSValue example = scriptEngine->newObject(); example.setProperty("someProperty", seedValue++); return example; } // Second, register the singleton type provider with QML by calling this function in an initialization function. qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);
- 或者,你也可以使用c++ 11 lambda:
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue { Q_UNUSED(engine) static int seedValue = 5; QJSValue example = scriptEngine->newObject(); example.setProperty("someProperty", seedValue++); return example; });
- 为了在QML中使用注册的单例类型,您必须导入该单例类型。
import QtQuick 2.0 import Qt.example.qjsvalueApi 1.0 as ExampleApi Item { id: root property int someValue: ExampleApi.MyApi.someProperty }
template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*)(QQmlEngine *, QJSEngine *) callback)
- 这个函数可以用来在一个特定的uri和typeName中注册一个在versionMajor和versionMinor中指定的版本的单例类型提供程序回调。
- 在uri中安装一个单例类型允许开发人员向客户端提供任意的功能(方法和属性),而不需要客户端实例化该类型的单个实例。
- 一个单例类型可以是QObject或者QJSValue。此函数应用于注册一个单例类型提供程序函数,该函数将给定类型T的QObject作为单例类型返回。
- QObject单例类型可以通过它被注册的类型名来引用,这个类型名可以作为Connections 类型中的目标,也可以像其他任何类型id一样使用。一个例外是QObject单例类型属性可能没有别名。
- 注意: 从单例类型提供程序返回的QObject单例类型实例由QML引擎拥有,除非该对象有显式的QQmlEngine::CppOwnership标志集。
- 示例:
// First, define your QObject which provides the functionality. class SingletonTypeExample : public QObject { Q_OBJECT Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) public: SingletonTypeExample(QObject* parent = 0) : QObject(parent), m_someProperty(0) { } ~SingletonTypeExample() {} Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } int someProperty() const { return m_someProperty; } void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); } signals: void somePropertyChanged(int newValue); private: int m_someProperty; }; // Second, define the singleton type provider function (callback). static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine) { Q_UNUSED(engine) Q_UNUSED(scriptEngine) SingletonTypeExample *example = new SingletonTypeExample(); return example; } // Third, register the singleton type provider with QML by calling this function in an initialization function. qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);
- 或者,你也可以使用c++ 11 lambda:
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * { Q_UNUSED(engine) Q_UNUSED(scriptEngine) SingletonTypeExample *example = new SingletonTypeExample(); return example; });
- 为了在QML中使用注册的单例类型,您必须导入该单例类型。
import QtQuick 2.0 import Qt.example.qobjectSingleton 1.0 Item { id: root property int someValue: MyApi.someProperty Component.onCompleted: { someValue = MyApi.doSomething() } }
template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)
- 此函数重载qmlRegisterSingletonType。
- 该函数是在Qt 5.14中引入的。
int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
- 该函数可用于在uri导入的库中注册一个名为qmlName的单例类型,该库的版本号由versionMajor和versionMinor组成。
- 该类型由位于url的QML文件定义。
- url必须是绝对url,即url. isrelative () == false。
- 此外,类型的QML文件必须在其导入语句中有pragma Singleton语句。
- 单个类型可以通过其注册的类型名来引用,这个类型名可以作为Connections类型中的目标,也可以像其他任何类型id一样使用。
- 一个例外是单例类型属性不能有别名(因为单例类型名称不能识别与其他项目相同组件中的对象)。
- 示例:
// First, define your QML singleton type which provides the functionality. pragma Singleton import QtQuick 2.0 Item { property int testProp1: 125 }
// Second, register the QML singleton type by calling this function in an initialization function. qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");
- 为了在QML中使用注册的单例类型,您必须导入该单例类型。
import QtQuick 2.0 import Qt.example.qobjectSingleton 1.0 Item { id: root property int someValue: RegisteredSingleton.testProp1 }
- 也可以在不使用qmlRegisterSingletonType函数的情况下注册QML单例类型。
- 这可以通过在类型的QML文件的导入中添加一个pragma Singleton语句来实现。
- 此外,该类型必须用singleton关键字在qmldir文件中定义,QML文件必须使用singleton导入qmldir。
- 参考:QML_SINGLETON.
template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
- 这个模板函数在QML系统中注册c++类型,名称为qmlName,在从uri导入的库中,版本号由versionMajor和versionMinor组成。
- 返回QML类型id。
- 这个模板函数有两种形式:
template<typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); template<typename T, int metaObjectRevision> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
- 前者是将T型登记为新型的标准形式。后者允许类的特定修订在指定的版本中注册(请参阅 Type Revisions and Versions)。
- 例如,它注册了一个c++类MySliderItem作为一个名为Slider的QML类型,用于1.0版本的命名空间类型"com.mycompany.qmlcomponents":
qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
- 一旦注册了该类型,就可以通过导入指定的类型命名空间和版本号来在QML中使用该类型:
import com.mycompany.qmlcomponents 1.0 Slider { // ... }
- 请注意,将类型注册到比库的实际版本更老的版本是完全合理的。
- 实际上,新库允许写到以前版本的QML继续工作是正常的,即使某些类型的更高级版本可用。
- 参考: QML_ELEMENT, QML_NAMED_ELEMENT(), and Choosing the Correct Integration Method Between C++ and QML.
int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
- 该函数在QML系统中注册一个名为qmlName的类型,该类型位于从uri导入的库中,版本号由versionMajor和versionMinor组成。
- 该类型由位于url的QML文件定义。
- url必须是绝对url,即url. isrelative () == false。
- 通常,QML文件可以作为类型直接从其他QML文件加载,或者使用qmldir文件。
- 这个函数允许将文件注册为c++代码中的类型,例如当类型映射需要在启动时进行程序确定时。
- 如果注册不成功,则返回-1。
int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
- 该函数在QML系统中注册一个名为qmlName的类型,该类型位于从uri导入的类型名称空间中,版本号由versionMajor和versionMinor组成,但任何实例化该类型的尝试都会产生给定的错误消息。
- 通常,插件导出的类型应该是固定的。但是,如果c++类型不可用,您至少应该“保留”QML类型名,并为不可用类型的用户提供有意义的错误消息。
- 返回QML类型id。
- 例子:
#ifdef NO_GAMES_ALLOWED qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); #else qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); #endif
- 这将导致任何导入“MinehuntCore”类型命名空间的QML,并试图使用该类型产生错误消息:
fun.qml: Get back to work, slacker! Game { ^
- 如果没有这个,“Game is not a type”的信息就会被给出。
- 参考:QML_UNAVAILABLE, qmlRegisterUncreatableType(), 和Choosing the Correct Integration Method Between C++ and QML.
int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
- 该函数在QML系统中注册staticMetaObject及其扩展,其名称为qmlName,该名称来自从uri导入的库,版本号由versionMajor和versionMinor组成。
- 不能创建元对象的实例。如果用户试图创建一个错误消息,则会打印一个带有给定原因的错误消息。
- 该函数用于注册 Q_NAMESPACE 名称空间。
- 返回QML类型id。
- 比如:
namespace MyNamespace { Q_NAMESPACE enum MyEnum { Key1, Key2, }; Q_ENUMS(MyEnum) } //... qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");
- 在QML端,你现在可以使用注册的枚举:
omponent.onCompleted: console.log(MyNamespace.Key2)
- 该函数是在Qt 5.8中引入的
- 参考:QML_ELEMENT, QML_NAMED_ELEMENT(), 和QML_UNCREATABLE().
template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
- 这个模板函数在QML系统中注册c++类型,名称为qmlName,在从uri导入的库中,版本号由versionMajor和versionMinor组成。
- 虽然该类型有名称和类型,但不能创建它,如果尝试创建,将产生给定的错误消息。
- 当类型仅用于提供附加的属性或枚举值时,这很有用。
- 返回QML类型id。
- 参考: QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), 和Choosing the Correct Integration Method Between C++ and QML.
int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
- 返回类型的QML类型id,该类型在特定uri中以名称qmlName注册,以及在versionMajor和versionMinor中指定的版本。
- 该函数返回与QML类型注册函数(如qmlRegisterType()和qmlRegisterSingletonType())相同的值。
- 如果qmlName、uri和versionMajor匹配已注册的类型,但versionMinor中指定的次要版本更高,则返回与次要版本最近的类型id。
- 如果没有找到匹配类型或给定参数之一无效,则返回-1。
- 该函数是在Qt 5.12中引入的。
- 参考:QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), 和qmlRegisterSingletonType().