- Qt 6.9
- Qt Qml
- <qqml.h> - Functions to register C++ types to QML
- Qt 6.9.2 Reference Documentation

# <qqml.h> - Functions to register C++ types to QML

Header: | `#include <qqml.h>`

## 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_DECLARE_TYPE
| QML_DECLARE_TYPEINFO(Type, Flags)

## Detailed Description

This header provides a collection of functions that allow the registration of C++ types to QML.

See also Overview - QML and C++ Integration, qqmlintegration.h, and qmltyperegistrar.

## Type Documentation

### enum QQmlModuleImportSpecialVersions

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

Constant | Value | Description
--- | --- | ---
`QQmlModuleImportModuleAny` | `-1` | When passed as majorVersion of the base module, signifies that the import is to be applied to any version of the module.
`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.
`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 attachee is `nullptr`, returns `nullptr`.

If an existing attached object instance of type T exists, it will return it. Otherwise, it will return a newly created instance if create is `true` and T is a valid attaching type, or `nullptr` if it's not.

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_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.