QML QQmlEngine 宏

QML   QQmlEngine 宏

• 官方文档：https://doc.qt.io/qt-5/qqmlengine.html

QML_ADDED_IN_MINOR_VERSION(VERSION)

• 声明封闭类型或命名空间是相对于模块的主版本添加到指定的次要版本中。
  • 小版本被假定与Q_REVISION()宏对方法、插槽或信号给出的任何修订，以及Q_PROPERTY()声明的属性上的任何REVISION标记一致。
  • QML_ADDED_IN_MINOR_VERSION()仅在 QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, 或QML_INTERFACE宏时生效。
• 如果类型所属的QML模块的导入版本低于以这种方式确定的版本，那么QML类型是不可见的。
• 参考：QML_ELEMENT 和 QML_NAMED_ELEMENT().

 

QML_ANONYMOUS

• 声明封闭类型可用，但在QML中是匿名的。该类型不能被创建或用作属性类型，但当从c++传递时，它会被识别。
• 参考： QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), 和QML_INTERFACE.

 

QML_ATTACHED(ATTACHED_TYPE)

• 声明封闭类型将ATTACHED_TYPE 作为附加属性（ attached property ）附加到其他类型。
• 如果使用QML_ELEMENT 或 QML_NAMED_ELEMENT() 宏将类型公开给QML，则此方法将生效。
• 参考：QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), 和 Providing Attached Properties.

 

QML_DECLARE_TYPE

• 等价于Q_DECLARE_METATYPE(TYPE *)和Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)

 

QML_DECLARE_TYPEINFO(Type, Flags)

• 按照指定的标志声明给定类型的其他属性。
• 当前唯一支持的类型信息是QML_HAS_ATTACHED_PROPERTIES，它声明类型支持附加属性。
  • 如果Type包含QML_ATTACHED宏，QML_DECLARE_TYPEINFO()是不必要的。

 

QML_ELEMENT

• 声明QML中可用的封闭类型或命名空间，将其类名或命名空间名作为QML元素名。
• 例如，这使得c++类Slider可以作为QML类型Slider使用。

class Slider : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    ...
}

• 你可以使用构建系统在类型命名空间com.mycompany.qmlcomponents中注册类型，在你的项目文件中指定以下内容:

CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.qmlcomponents
QML_IMPORT_MAJOR_VERSION = 1

• 一旦注册，该类型可以通过导入相同的类型名称空间和版本号在QML中使用:

import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}

• 还可以使用这种方法使带有 Q_NAMESPACE 标记的名称空间可用，以便公开它们包含的带有 Q_ENUM_NS  标记的任何枚举。
• 参考： Choosing the Correct Integration Method Between C++ and QML, QML_NAMED_ELEMENT(), Q_REVISION(), 和QML_ADDED_IN_MINOR_VERSION().

 

QML_EXTENDED(EXTENDED_TYPE)

• 声明封闭类型使用EXTENDED_TYPE作为扩展来在QML中提供进一步的属性和方法。
• 如果使用QML_ELEMENT 或 QML_NAMED_ELEMENT() 宏将类型公开给QML，则此方法将生效。
• 参考：QML_ELEMENT, QML_NAMED_ELEMENT(), 和Registering Extension Objects.

 

QML_FOREIGN(FOREIGN_TYPE)

• 声明封闭c++类型中的任何 QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_MINOR_VERSION(), QML_REMOVED_IN_MINOR_VERSION(), QML_ATTACHED(), 或 QML_EXTENDED()宏不适用于封闭类型，而是适用于FOREIGN_TYPE。
• 外围类型仍然需要使用 Q_GADGET 或 Q_OBJECT宏向元对象系统注册。
• 这对于注册不能修改以添加宏的类型很有用，例如，因为它们属于3rdparty库。
• 参考：QML_ELEMENT 和 QML_NAMED_ELEMENT().

 

QML_INTERFACE

• 这个宏在QML系统中将封闭的c++类型注册为接口。
• 在QML中注册为接口的类型也应该将自己声明为元对象系统（meta object system）的接口。例如:

struct FooInterface
{
    QML_INTERFACE
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中隐式匿名且不可创建。
• 参考：QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), 和QML_ANONYMOUS.

 

QML_NAMED_ELEMENT(name)

• 声明QML中可用的封闭类型或名称空间，使用name作为元素名。否则行为与 QML_ELEMENT 相同。

class SqlEventDatabase : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(EventDatabase)

    // ...
};

• 参考：Choosing the Correct Integration Method Between C++ and QML 和QML_ELEMENT.

 

QML_REMOVED_IN_MINOR_VERSION(VERSION)

• 声明封闭类型或命名空间在指定的小版本中被删除，相对于模块的主版本。
  • 这在替换QML类型的实现时非常有用。
  • 如果相应的 QML_ADDED_IN_MINOR_VERSION() 存在不同类型或命名空间相同的QML名字，然后删除类型时使用导入模块的版本低于版本,和添加类型时使用进口大于或等于版本版本的模块。
• QML_REMOVED_IN_MINOR_VERSION()只有当类型或名称空间在QML中可用时才会生效，方法是使用QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, 或 QML_INTERFACE 宏。
• 参考：QML_ELEMENT 和 QML_NAMED_ELEMENT()。

 

QML_SINGLETON

• 在QML中声明封闭类型为单例。
  • 只有当类型是Q_OBJECT并且在QML中可用(通过使用QML_ELEMENT或QML_NAMED_ELEMENT()宏)时才会生效。
  • 默认情况下，当类型第一次被访问时，每个QQmlEngine将尝试使用该类型的默认构造函数创建一个单例实例。
  • 如果没有默认构造函数，单例对象最初是不可访问的。
  • 可以通过使用特定的工厂函数调用qmlRegisterSingletonType()或使用相同类、相同类型名称空间和版本的特定实例调用qmlRegisterSingletonInstance()来覆盖此行为。
• 参考：QML_ELEMENT, QML_NAMED_ELEMENT(), 和qmlRegisterSingletonInstance().

 

QML_UNAVAILABLE

• 这个宏声明封闭类型在QML中不可用。
  • 它使用您指定的任何进一步的QML宏，将一个名为QQmlTypeNotAvailable的内部虚拟类型注册为QML_FOREIGN()类型。
• 通常，模块导出的类型应该是固定的。但是，如果c++类型不可用，您至少应该“reserve”QML类型名，并为不可用类型的用户提供有意义的错误消息。
• 例子:

#ifdef NO_GAMES_ALLOWED
struct MinehuntGame
{
    Q_GADGET
    QML_NAMED_ELEMENT(Game)
    QML_UNAVAILABLE
    QML_UNCREATABLE("Get back to work, slacker!");
};
#else
class MinehuntGame : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(Game)
    // ...
};
#endif

• 这将导致任何试图使用“Game”类型的QML产生错误消息:

fun.qml: Get back to work, slacker!
   Game {
   ^

• 用这种技术，您只需要一个Q_GADGET结构体来定制错误消息，而不需要一个完整的QObject。
• 如果没有QML_UNCREATABLE()， QML_UNAVAILABLE仍然会导致比完全未知类型通常的“is not a type”更具体的错误消息。
• 参考：QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), 和QML_FOREIGN().

 

QML_UNCREATABLE(reason)

• 声明不能从QML中创建封闭类型。
  • 如果该类型在QML中可用，则通过使用QML_ELEMENT或QML_NAMED_ELEMENT()宏来生效。
  • 如果检测到试图从QML创建类型，则将其原因作为错误消息发出。
• 有些QML类型是隐式不可创建的，特别是使用QML_ANONYMOUS公开的类型，或者使用QML_ELEMENT或QML_NAMED_ELEMENT()公开的名称空间。
  • 对于这类类型，QML_UNCREATABLE()可用于提供自定义错误消息。
• 参考: QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_ANONYMOUS.