- Qt 6.7
- Qt Qml
- QQmlEngine Proxy Page
- Qt 6.7.3 Reference Documentation

# QQmlEngine Proxy Page

## Types

enum | QQmlModuleImportSpecialVersions { QQmlModuleImportModuleAny, QQmlModuleImportLatest, QQmlModuleImportAuto }

## Functions

QObject * | qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
class Q_DECL_IMPORT | qmlProtectModule(const char *uri, int majVersion)
int | qmlRegisterAnonymousType(const char *uri, int versionMajor)
int | qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
int | qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
class Q_DECL_IMPORT | qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)
class Q_DECL_IMPORT | qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)
int | qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
int | qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
int | qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue (QQmlEngine *, QJSEngine *)> callback)
int | qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)
int | qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
class Q_DECL_IMPORT | qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)
int | qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)
class Q_DECL_IMPORT | qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

## Macros

| QML_ADDED_IN_VERSION(MAJOR, MINOR)
| QML_ANONYMOUS
| QML_ATTACHED(ATTACHED_TYPE)
`(since 6.5)` | QML_CONSTRUCTIBLE_VALUE
| QML_DECLARE_TYPE
| QML_DECLARE_TYPEINFO(Type, Flags)
| QML_ELEMENT
| QML_EXTENDED(EXTENDED_TYPE)
| QML_EXTENDED_NAMESPACE(EXTENDED_NAMESPACE)
| QML_EXTRA_VERSION(MAJOR, MINOR)
| QML_FOREIGN(FOREIGN_TYPE)
| QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)
| QML_IMPLEMENTS_INTERFACES(interfaces)
| QML_INTERFACE
| QML_NAMED_ELEMENT(name)
| QML_REMOVED_IN_VERSION(MAJOR, MINOR)
| QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)
| QML_SINGLETON
`(since 6.5)` | QML_STRUCTURED_VALUE
| QML_UNAVAILABLE
| QML_UNCREATABLE(reason)
| QML_VALUE_TYPE(name)

## Type Documentation

### enum QQmlModuleImportSpecialVersions

Defines some special values that can be passed to the version arguments of qmlRegisterModuleImport() and qmlUnregisterModuleImport().

Constant | Value | Description
--- | --- | ---
`QQmlEngine::QQmlModuleImportModuleAny` | `-1` | When passed as majorVersion of the base module, signifies that the import is to be applied to any version of the module.
`QQmlEngine::QQmlModuleImportLatest` | `-1` | When passed as major or minor version of the imported module, signifies that the latest overall, or latest minor version of a specified major version shall be imported.
`QQmlEngine::QQmlModuleImportAuto` | `-2` | When passed as major version of the imported module, signifies that the version of the base module shall be forwarded.

## Function Documentation

### template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

The form of this template function is:

     template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)

This returns the attached object instance that has been attached to the specified attachee by the attaching type T.

If create is true and type T is a valid attaching type, this creates and returns a new attached object instance.

Returns `nullptr` if type T is not a valid attaching type, or if create is false and no attachment object instance has previously been created for attachee.

See also QML_ATTACHED() and Providing Attached Properties.

### class Q_DECL_IMPORT qmlProtectModule(const char *uri, int majVersion)

This function protects a module from further modification. This can be used to prevent other plugins from injecting types into your module. It can also be a performance improvement, as it allows the engine to skip checking for the possibility of new types or plugins when this import is reached.

Once qmlProtectModule has been called, a QML engine will not search for a new `qmldir` file to load the module anymore. It will re-use any `qmldir` files it has loaded before, though. Therefore, types present at this point continue to work. Mind that different QML engines may load different modules. The module protection, however, is global and affects all engines. The overhead of locating `qmldir` files and loading plugins may be noticeable with slow file systems. Therefore, protecting a module once you are sure you won't need to load it anymore can be a good optimization. Mind also that the module lock not only affects plugins but also any other qmldir directives, like `import` or `prefer`, as well as any composite types or scripts declared in a `qmldir` file.

In addition, after this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error.

Returns true if the module with uri as a module identifier and majVersion as a major version number was found and locked, otherwise returns false. The module must contain exported types in order to be found.

### template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)

This template function registers the C++ type in the QML system as an anonymous type. The resulting QML type does not have a name. Therefore, instances of this type cannot be created from the QML system. You can, however, access instances of the type when they are exposed as properties of other types.

Use this function when the type will not be referenced by name, specifically for C++ types that are used on the left-hand side of a property binding. To indicate to which module the type belongs use uri and versionMajor.

For example, consider the following two classes:

     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;
     };

In QML, we assign a string to the `baz` property of `bar`:

     Foo {
         bar.baz: "abc"
         Component.onCompleted: print(bar.baz)
     }

For the QML engine to know that the `Bar` type has a `baz` property, we have to make `Bar` known:

     qmlRegisterType<Foo>("App", 1, 0, "Foo");
     qmlRegisterAnonymousType<Bar>("App", 1);

As the `Foo` type is instantiated in QML, it must be registered with the version of qmlRegisterType() that takes an element name.

Returns the QML type id.

See also QML_ANONYMOUS and Choosing the Correct Integration Method Between C++ and QML.

### template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This template function registers the C++ type and its extension object in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor. Properties not available in the main type will be searched for in the extension object.

Returns the QML type id.

See also 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)

This template function registers the C++ type and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

While the type has a name and a type, it cannot be created. An error message with the given reason is printed if the user attempts to create an instance of this type.

This is useful where the type is only intended for providing attached properties, enum values or an abstract base class with its extension.

Returns the QML type id.

See also QML_EXTENDED(), QML_UNCREATABLE(), and qmlRegisterUncreatableType().

### class Q_DECL_IMPORT qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

This function registers a module in a particular uri with a version specified in versionMajor and versionMinor.

This can be used to make a certain module version available, even if no types are registered for that version. This is particularly useful for keeping the versions of related modules in sync.

### class Q_DECL_IMPORT qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

Registers a qmldir-import for module uri of major version moduleMajor.

This has the same effect as an `import` statement in a qmldir file: Whenever uri of version moduleMajor is imported, import of version importMajor. importMinor is automatically imported, too. If importMajor is QQmlModuleImportLatest the latest version available of that module is imported, and importMinor does not matter. If importMinor is QQmlModuleImportLatest the latest minor version of a importMajor is chosen. If importMajor is QQmlModuleImportAuto the version of import is version of uri being imported, and importMinor does not matter. If moduleMajor is QQmlModuleImportModuleAny the module import is applied for any major version of uri. For example, you may specify that whenever any version of MyModule is imported, the latest version of MyOtherModule should be imported. Then, the following call would be appropriate:

     qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                             "MyOtherModule", QQmlModuleImportLatest);

Or, you may specify that whenever major version 5 of "MyModule" is imported, then version 3.14 of "MyOtherModule" should be imported:

     qmlRegisterModuleImport("MyModule", 5, "MyOtherModule", 3, 14);

Finally, if you always want the same version of "MyOtherModule" to be imported whenever "MyModule" is imported, specify the following:

     qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                             "MyOtherModule", QQmlModuleImportAuto);

See also qmlUnregisterModuleImport().

### template <typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

This template function registers the specified revision of a C++ type in the QML system with the library imported from uri having the version number composed from versionMajor and versionMinor.

Returns the QML type id.

     template<typename T, int metaObjectRevision>
     int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

This function is typically used to register the revision of a base class to use for the specified version of the type (see Type Revisions and Versions).

### int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)

This function is used to register a singleton object cppObject, with a particular uri and typeName. Its version is a combination of versionMajor and versionMinor.

Installing a singleton type into a URI allows you to provide arbitrary functionality (methods and properties) to QML code without requiring individual instances of the type to be instantiated by the client.

Use this function to register an object of the given type T as a singleton type.

A QObject singleton type may be referenced via the type name with which it was registered; in turn this type name may be used as the target in a Connections type, or like any other type ID. However, there's one exception: a QObject singleton type property can't be aliased because the singleton type name does not identify an object within the same component as any other item.

Note: cppObject must outlive the QML engine in which it is used. Moreover, cppObject must have the same thread affinity as the engine. If you want separate singleton instances for multiple engines, you need to use qmlRegisterSingletonType. See Threads and QObjects for more information about thread safety.

NOTE: qmlRegisterSingleton can only be used when all types of that module are registered procedurally.

Usage:

     // 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());

In order to use the registered singleton type in QML, you must import the URI with the corresponding version.

     import QtQuick 2.0
     import Qt.example.qobjectSingleton 1.0
     Item {
         id: root
         property int someValue: MyApi.someProperty

         Component.onCompleted: {
             console.log(MyApi.doSomething())
         }
     }

See also QML_SINGLETON and qmlRegisterSingletonType.

### int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue (QQmlEngine *, QJSEngine *)> callback)

This function may be used to register a singleton type provider callback in a particular uri and typeName with a version specified in versionMajor and versionMinor.

Installing a singleton type allows developers to provide arbitrary functionality (methods and properties) to a client without requiring individual instances of the type to be instantiated by the client.

A singleton type may be either a QObject or a QJSValue. This function should be used to register a singleton type provider function which returns a QJSValue as a singleton type.

NOTE: QJSValue singleton type properties will not trigger binding re-evaluation if changed.

Usage:

     // 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);

Alternatively, you can use a 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;
     });

In order to use the registered singleton type in QML, you must import the singleton type.

     import QtQuick 2.0
     import Qt.example.qjsvalueApi 1.0 as ExampleApi
     Item {
         id: root
         property int someValue: ExampleApi.MyApi.someProperty
     }

See also QML_SINGLETON and Choosing the Correct Integration Method Between C++ and QML.

### template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)

This function may be used to register a singleton type provider callback in a particular uri and typeName with a version specified in versionMajor and versionMinor.

Installing a singleton type into a uri allows developers to provide arbitrary functionality (methods and properties) to clients without requiring individual instances ot the type to be instantiated by the client.

A singleton type may be either a QObject or a QJSValue. This function should be used to register a singleton type provider function which returns a QObject of the given type T as a singleton type.

A QObject singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a Connections type or otherwise used as any other type id would. One exception to this is that a QObject singleton type property may not be aliased.

NOTE: A QObject singleton type instance returned from a singleton type provider is owned by the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.

Usage:

     // 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 = nullptr)
             : 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);

Alternatively, you can use a 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;
     });

In order to use the registered singleton type in QML, you must import the singleton type.

     import QtQuick 2.0
     import Qt.example.qobjectSingleton 1.0
     Item {
         id: root
         property int someValue: MyApi.someProperty

         Component.onCompleted: {
             someValue = MyApi.doSomething()
         }
     }

See also QML_SINGLETON and Choosing the Correct Integration Method Between C++ and QML.

### template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

This template function registers the C++ type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor.

Returns the QML type id.

There are two forms of this template function:

     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);

The former is the standard form which registers the type T as a new type. The latter allows a particular revision of a class to be registered in a specified version (see Type Revisions and Versions).

For example, this registers a C++ class `MySliderItem` as a QML type named `Slider` for version 1.0 of a type namespace called "com.mycompany.qmlcomponents":

     qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

Once this is registered, the type can be used in QML by importing the specified type namespace and version number:

     import com.mycompany.qmlcomponents 1.0

     Slider {
         // ...
     }

Note that it's perfectly reasonable for a library to register types to older versions than the actual version of the library. Indeed, it is normal for the new library to allow QML written to previous versions to continue to work, even if more advanced versions of some of its types are available.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and Choosing the Correct Integration Method Between C++ and QML.

### class Q_DECL_IMPORT qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

This function registers the staticMetaObject and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

An instance of the meta object cannot be created. An error message with the given reason is printed if the user attempts to create it.

This function is useful for registering Q_NAMESPACE namespaces.

Returns the QML type id.

For example:

     namespace MyNamespace {
       Q_NAMESPACE
       enum MyEnum {
           Key1,
           Key2,
       };
       Q_ENUM_NS(MyEnum)
     }

     //...
     qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

On the QML side, you can now use the registered enums:

     Component.onCompleted: console.log(MyNamespace.Key2)

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_UNCREATABLE().

### template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

This template function registers the C++ type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor.

While the type has a name and a type, it cannot be created, and the given error message will result if creation is attempted.

This is useful where the type is only intended for providing attached properties or enum values.

Returns the QML type id.

See also QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), and Choosing the Correct Integration Method Between C++ and QML.

### class Q_DECL_IMPORT qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

Removes a module import previously registered with qmlRegisterModuleImport()

Calling this function makes sure that import of version importMajor.importMinor is not automatically imported anymore when uri of version moduleMajor is. The version resolution works the same way as with qmlRegisterModuleImport().

See also qmlRegisterModuleImport().

## Macro Documentation

### QML_ADDED_IN_VERSION(MAJOR, MINOR)

Declares that the enclosing type or namespace was added in the specified MAJOR.MINOR version. The version is assumed to be in line with any revisions given by Q_REVISION() macros on methods, slots, or signals, and any REVISION() attributes on properties declared with Q_PROPERTY().

QML_ADDED_IN_VERSION() only takes effect if the type or namespace is available in QML, by having a QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, or QML_INTERFACE macro.

If the QML module the type belongs to is imported with a lower version than the one determined this way, the QML type is invisible.

See also QML_ELEMENT and QML_NAMED_ELEMENT.

### QML_ANONYMOUS

Declares the enclosing type to be available, but anonymous in QML. The type cannot be created or used to declare properties in QML, but when passed from C++, it is recognized. In QML, you can use properties of this type if they are declared in C++.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), and QML_INTERFACE.

### QML_ATTACHED(ATTACHED_TYPE)

Declares that the enclosing type attaches ATTACHED_TYPE as an attached property to other types. This takes effect if the type is exposed to QML using a QML_ELEMENT or QML_NAMED_ELEMENT() macro.

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), and Providing Attached Properties.

### `[since 6.5]` QML_CONSTRUCTIBLE_VALUE

Marks the surrounding value type as constructible. That is, any Q_INVOKABLE constructors of the type that take exactly one argument can be used when assigning a JavaScript value to a property of this type.

You can declare a constructible value type as follows:

     class MyValueType
     {
         Q_GADGET
         QML_VALUE_TYPE(myValueType)
         QML_CONSTRUCTIBLE_VALUE
     public:
         Q_INVOKABLE MyValueType(double d);

         // ...
     };

With the above type, the following QML code will produce a `MyValueType` value using the given constructor and assign it to the property.

     QtObject {
         property myValueType v: 5.4
     }

You can also construct lists of values this way:

     QtObject {
         property list<myValueType> v: [5.4, 4.5, 3.3]
     }

If you make value types addressable, you can use such a type in a type assertion to explicitly construct it:

     pragma ValueTypeBehavior: Addressable

     QtObject {
         function process(d: real) {
             let v = d as myValueType;
             // v is a myValueType now, not a number
         }
     }

This macro was introduced in Qt 6.5.

See also QML_VALUE_TYPE.

### QML_DECLARE_TYPE

Equivalent to `Q_DECLARE_METATYPE(TYPE *)` and `Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)`

### QML_DECLARE_TYPEINFO(Type, Flags)

Declares additional properties of the given Type as described by the specified Flags.

Current the only supported type info is `QML_HAS_ATTACHED_PROPERTIES` which declares that the Type supports attached properties. QML_DECLARE_TYPEINFO() is not necessary if Type contains the QML_ATTACHED macro.

### QML_ELEMENT

Declares the enclosing type or namespace to be available in QML, using its class or namespace name as the QML element name.

For example, this makes the C++ class `Slider` available as a QML type named `Slider`. All its properties, invokable methods and enums are exposed.

     class Slider : public QObject
     {
         Q_OBJECT
         QML_ELEMENT
         Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
         // ...
     public:
         enum Slippiness {
             Dry, Wet, Icy
         };
         Q_ENUM(Slippiness)

         Q_INVOKABLE void slide(Slippiness slippiness);

         // ...
     }

You can use the build system to register the type in the type namespace com.mycompany.qmlcomponents with major version `1`. For qmake, specify the following in your project file:

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

With CMake, you pass the URI and version to qt_add_qml_module

     qt6_add_qml_module(myapp
       URI com.mycompany.qmlcomponents
       VERSION 1.0
     )

Once registered, the type can be used in QML by importing the same type namespace and version number:

     import com.mycompany.qmlcomponents 1.0

     Slider {
         value: 12
         Component.onCompleted: slide(Slider.Icy)

         // ...
     }

You can also make namespaces tagged with Q_NAMESPACE available this way, in order to expose any enums tagged with Q_ENUM_NS they contain:

     namespace MyNamespace {
       Q_NAMESPACE
       QML_ELEMENT

       enum MyEnum {
           Key1,
           Key2,
       };
       Q_ENUM_NS(MyEnum)
     }

In QML, you can then use the enums:

     Component.onCompleted: console.log(MyNamespace.Key2)

NOTE: When classes have the same name but are located in different namespaces using QML_ELEMENT on both of them will cause a conflict. Make sure to use QML_NAMED_ELEMENT() for one of them instead.

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also Choosing the Correct Integration Method Between C++ and QML, QML_NAMED_ELEMENT(), Q_REVISION(), and QML_ADDED_IN_VERSION().

### QML_EXTENDED(EXTENDED_TYPE)

Declares that the enclosing type uses EXTENDED_TYPE as an extension to provide further properties, methods, and enumerations in QML. This takes effect if the type is exposed to QML using a QML_ELEMENT or QML_NAMED_ELEMENT() macro.

Warning: Members of EXTENDED_TYPE are implicitly treated as FINAL.

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE(), and Registering Extension Objects.

### QML_EXTENDED_NAMESPACE(EXTENDED_NAMESPACE)

Declares that the enclosing type uses EXTENDED_NAMESPACE as an extension to provide further enumerations in QML. This takes effect if the type is exposed to QML using a QML_ELEMENT or QML_NAMED_ELEMENT() macro. The enumerations need to be exposed to the metaobject system for this to work.

For example, give the following C++ code

     namespace MyNamespace {
         Q_NAMESPACE
         enum MyEnum { MyEnumerator = 10 };
         Q_ENUM_NS(MyEnum)
     }

     class QmlType : public QObject
     {
         Q_OBJECT
         QML_ELEMENT
         QML_EXTENDED_NAMESPACE(MyNamespace)
     }

we can access the enum in QML:

     QmlType {
         property int i: QmlType.MyEnumerator // i will be 10
     }

Note: EXTENDED_NAMESPACE can also be a QObject or QGadget; in that case - and in contrast to QML_EXTENDED, which also exposes methods and properties - only its enumerations are exposed.

Note: EXTENDED_NAMESPACE must have a metaobject; i.e. it must either be a namespace which contains the Q_NAMESPACE macro or a QObject/QGadget.

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(), Registering Extension Objects, Q_ENUM, and Q_ENUM_NS.

### QML_EXTRA_VERSION(MAJOR, MINOR)

Declare that the type should also be available in version MAJOR.MINOR. This can be helpful if a type should be available in multiple major versions.

Types are automatically registered for:

- The major version they were introduced in, see QML_ADDED_IN_VERSION.
- Any major versions any their members were introduced in.
- The current major version of their module, unless they were QML_REMOVED_IN_VERSION before that.

Notably, they are not automatically registered in any PAST_MAJOR_VERSIONS between the above. You can use QML_EXTRA_VERSION to manually register your types in further major versions.

Note: Keeping multiple PAST_MAJOR_VERSIONS around is computationally expensive.

See also QML_ELEMENT and QML_ADDED_IN_VERSION.

### QML_FOREIGN(FOREIGN_TYPE)

Declares that any QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION(), QML_REMOVED_IN_MINOR_VERSION(), QML_EXTENDED(), or QML_EXTENDED_NAMESPACE() macros in the enclosing C++ type do not apply to the enclosing type but instead to FOREIGN_TYPE. The enclosing type still needs to be registered with the meta object system using a Q_GADGET or Q_OBJECT macro.

This is useful for registering types that cannot be amended to add the macros, for example because they belong to 3rdparty libraries. To register a namespace, see QML_FOREIGN_NAMESPACE().

Note: You may want to use QML_NAMED_ELEMENT() instead of QML_ELEMENT. With QML_ELEMENT, the element is named after the struct it is contained in, not the foreign type. The Foreign objects integration chapter in Writing advanced QML Extensions with C++ demonstrates this.

Note: QML_ATTACHED() can currently not be redirected like this. It has to be specificed in the same type that implements qmlAttachedProperties().

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_FOREIGN_NAMESPACE().

### QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)

Declares that any QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, QML_INTERFACE, QML_UNCREATABLE(), QML_SINGLETON, QML_ADDED_IN_VERSION(), QML_REMOVED_IN_VERSION(), QML_ADDED_IN_MINOR_VERSION(), or QML_REMOVED_IN_MINOR_VERSION() macros in the enclosing C++ namespace do not apply to the enclosing type but instead to FOREIGN_NAMESPACE. The enclosing namespace still needs to be registered with the meta object system using a Q_NAMESPACE macro.

This is useful for registering namespaces that cannot be amended to add the macros, for example because they belong to 3rdparty libraries.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_FOREIGN().

### QML_IMPLEMENTS_INTERFACES(interfaces)

This macro tells Qt which QML interfaces the class implements. This macro should only be used for interfacing with classes using QML_INTERFACE, use Q_INTERFACES otherwise. It's required in order for declarative registration via QML_ELEMENT to function properly.

See also QML_INTERFACE and Q_INTERFACES.

### QML_INTERFACE

This macro registers the enclosing C++ type in the QML system as an interface.

Types registered as an interface in QML should also declare themselves as an interface with the meta object system. For example:

     struct FooInterface
     {
         QML_INTERFACE
     public:
         virtual ~FooInterface();
         virtual void doSomething() = 0;
     };

     Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")

When registered with QML in this way, they can be used as property types:

Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

When you assign a QObject sub-class to this property, the QML engine does the interface cast to `FooInterface*` automatically.

Interface types are implicitly anonymous and uncreatable in QML.

NOTE: When inheriting from types using QML_INTERFACE, use QML_IMPLEMENTS_INTERFACES instead of Q_INTERFACES.

See also QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), and QML_ANONYMOUS.

### QML_NAMED_ELEMENT(name)

Declares the enclosing type or namespace to be available in QML, using name as the element name. Otherwise behaves the same as QML_ELEMENT.

     class SqlEventDatabase : public QObject
     {
         Q_OBJECT
         QML_NAMED_ELEMENT(EventDatabase)

         // ...
     };

See also Choosing the Correct Integration Method Between C++ and QML and QML_ELEMENT.

### QML_REMOVED_IN_VERSION(MAJOR, MINOR)

Declares that the enclosing type or namespace was removed in the specified MAJOR.MINOR version. This is primarily useful when replacing the implementation of a QML type. If a corresponding QML_ADDED_IN_VERSION() is present on a different type or namespace of the same QML name, then the removed type is used when importing versions of the module lower than MAJOR.MINOR, and the added type is used when importing versions of the module greater or equal MAJOR.MINOR.

QML_REMOVED_IN_VERSION() only takes effect if type or namespace is available in QML, by having a QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS, or QML_INTERFACE macro.

See also QML_ELEMENT and QML_NAMED_ELEMENT.

### QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)

This macro declares the enclosing or referenced type as a sequential container managing a sequence of VALUE_TYPE elements. VALUE_TYPE can be an actual value type or a pointer to an object type. You will rarely be able to add this macro to the actual container declaration since containers are usually templates. You should use QML_FOREIGN to attach the type registration to a template instantiation. Using this technique you can, for example, declare sequential containers like this:

     class IntDequeRegistration
     {
       Q_GADGET
       QML_FOREIGN(std::deque<int>)
       QML_ANONYMOUS
       QML_SEQUENTIAL_CONTAINER(int)
     };

After this, you can use the container like a JavaScript array in QML.

     class Maze
     {
       Q_OBJECT
       Q_ELEMENT
       // 0: North, 1: East, 2: South, 3: West
       Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
       [...]
     }

     Item {
       Maze {
         id: maze
       }

       function showSolution() {
           maze.solution.forEach([...])
       }
     }

Note: For QML Value Types QList is automatically registered as sequential container. For QML Object Types QQmlListProperty is. You don't have to add these registrations.

Note: You cannot currently give the container a custom name. Any argument passed to QML_NAMED_ELEMENT is ignored. The automatically registered sequential containers are available under the familiar list<...> names, for example list<QtObject> or list<font>.

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also QML_ANONYMOUS and QML_FOREIGN().

### QML_SINGLETON

Declares the enclosing type to be a singleton in QML. This only takes effect if the type is a Q_OBJECT and is available in QML (by having a QML_ELEMENT or QML_NAMED_ELEMENT() macro). By default, each QQmlEngine will try to create a singleton instance using either the type's default constructor or a static factory function of the signature `T *create(QQmlEngine *, QJSEngine *)` when the type is first accessed. If both do exist and are accessible, the default constructor is preferred. If there is no default constructor and no factory function the singleton is inaccessible. The QML engine generally assumes ownership of the singleton and will delete it when the engine itself is destroyed. You can prevent this by calling QJSEngine::setObjectOwnership() on the singleton.

In order to declare a default-constructible class as singleton, all you have to do is add QML_SINGLETON:

     class MySingleton : public QObject
     {
         Q_OBJECT
         QML_ELEMENT
         QML_SINGLETON
         // Q_PROPERTY( ... )
     public:
         // members, Q_INVOKABLE functions, etc.
     };

If the singleton class is not default-constructible, but you can modify it, you can add a factory function to it, in order to make it accessible:

     class MySingleton : public QObject
     {
         Q_OBJECT
         QML_ELEMENT
         QML_SINGLETON
         // Q_PROPERTY( ... )

     public:
         static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
         {
             MySingleton *result = nullptr;
             // Create the object using some custom constructor or factory.
             // The QML engine will assume ownership and delete it, eventually.
             return result;
         }

         // members, Q_INVOKABLE functions, etc
     };

If you cannot modify the class and it does not have a default constructor or a suitable factory function, you can provide a QML_FOREIGN wrapper to define the factory function:

     struct SingletonForeign
     {
         Q_GADGET
         QML_FOREIGN(MySingleton)
         QML_SINGLETON
         QML_NAMED_ELEMENT(MySingleton)
     public:

         static MySingleton *create(QQmlEngine *, QJSEngine *engine)
         {
             MySingleton *result = nullptr;
             // Create the instance using some custom constructor or factory.
             // The QML engine will assume ownership and delete it, eventually.
             return result;
         }
     };

Finally, if you want to provide one specific singleton object, the creation of which you cannot control, you can return that from a factory function. This is a replacement for the qmlRegisterSingletonInstance function. If you were calling

     qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);

with myObject being of type `MySingleton *`, you can do the following instead:

     struct SingletonForeign
     {
         Q_GADGET
         QML_FOREIGN(MySingleton)
         QML_SINGLETON
         QML_NAMED_ELEMENT(MySingleton)
     public:

         // Initialize this using myObject where you would previously
         // call qmlRegisterSingletonInstance().
         inline static MySingleton *s_singletonInstance = nullptr;

         static MySingleton *create(QQmlEngine *, QJSEngine *engine)
         {
             // The instance has to exist before it is used. We cannot replace it.
             Q_ASSERT(s_singletonInstance);

             // The engine has to have the same thread affinity as the singleton.
             Q_ASSERT(engine->thread() == s_singletonInstance->thread());

             // There can only be one engine accessing the singleton.
             if (s_engine)
                 Q_ASSERT(engine == s_engine);
             else
                 s_engine = engine;

             // Explicitly specify C++ ownership so that the engine doesn't delete
             // the instance.
             QJSEngine::setObjectOwnership(s_singletonInstance,
                                           QJSEngine::CppOwnership);
             return s_singletonInstance;
         }

     private:
         inline static QJSEngine *s_engine = nullptr;
     };

This way, the pre-existing class `MySingleton` is declared to be a QML singleton, called `MySingleton`. You can specify an instance for it any time before it is used by setting the `s_singletonInstance` member. None of this requires modification of `MySingleton` itself.

Note: This pattern doesn't work if either the singleton is accessed by multiple QML engines, or if the QML engine accessing it has a different thread affinity than the singleton object itself. As shown above, you can check the parameters to the `create()` method for identity and thread affinity of the engine in order to assert on that.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), and Singletons in QML.

### `[since 6.5]` QML_STRUCTURED_VALUE

Marks the surrounding value type as structured. Structured value types can and will preferably be constructed property-by-property from a JavaScript object. A structured value type, however is always QML_CONSTRUCTIBLE_VALUE, too. This means, you can still provide Q_INVOKABLE constructors in order to handle construction from primitive types.

You can declare a structured value type as follows:

     class MyValueType
     {
         Q_GADGET
         QML_VALUE_TYPE(myValueType)
         QML_STRUCTURED_VALUE
         Q_PROPERTY(double d READ d WRITE setD)
         Q_PROPERTY(string e READ e WRITE setE)

         // ...
     };

Then you can populate a property of this type as follows:

     QtObject {
         property myValueType v: ({d: 4.4, e: "a string"})
     }

The extra parentheses are necessary to disambiguate the JavaScript object from what might be interpreted as a JavaScript code block.

You can also construct lists of values this way:

     QtObject {
         property list<myValueType> v: [
             {d: 4.4, e: "a string"},
             {d: 7.1, e: "another string"}
         ]
     }

If you make value types addressable, you can use such a type in a type assertion to explicitly construct it:

     pragma ValueTypeBehavior: Addressable

     QtObject {
         function process(d: real) {
             let v = {d: d, e: objectName} as myValueType;
             // v is a myValueType now
         }
     }

This macro was introduced in Qt 6.5.

See also QML_VALUE_TYPE and QML_CONSTRUCTIBLE_VALUE.

### QML_UNAVAILABLE

This macro declares the enclosing type to be unavailable in QML. It registers an internal dummy type called `QQmlTypeNotAvailable` as QML_FOREIGN() type, using any further QML macros you specify.

Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.

Example:

     #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

This will cause any QML which attempts to use the "Game" type to produce an error message:

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

Using this technique, you only need a Q_GADGET struct to customize the error message, not a full-blown QObject. Without QML_UNCREATABLE(), QML_UNAVAILABLE still results in a more specific error message than the usual "is not a type" for completely unknown types.

Note: The class name needs to be fully qualified, even if you're already inside the namespace.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), and QML_FOREIGN().

### QML_UNCREATABLE(reason)

Declares that the enclosing type shall not be creatable from QML. This takes effect if the type is available in QML, by having a QML_ELEMENT or QML_NAMED_ELEMENT() macro. The reason will be emitted as error message if an attempt to create the type from QML is detected.

Some QML types are implicitly uncreatable, in particular types exposed with QML_ANONYMOUS or namespaces exposed with QML_ELEMENT or QML_NAMED_ELEMENT().

Since Qt 6.0 you can use "" instead of a reason to use a standard message instead.

See also QML_ELEMENT, QML_NAMED_ELEMENT(), and QML_ANONYMOUS.

### QML_VALUE_TYPE(name)

Declares the enclosing type or namespace to be available in QML, using name as the name. The type has to be a value type and the name has to be lower case.

     class MyValueType
     {
         Q_GADGET
         QML_VALUE_TYPE(myValueType)

         // ...
     };

See also Choosing the Correct Integration Method Between C++ and QML and QML_NAMED_ELEMENT.