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

Function Documentation

void qmlClearTypeRegistrations()

Clears all stored type registrations, such as those produced with qmlRegisterType().

Do not call this function while a QQmlEngine exists or behavior will be undefined. Any existing QQmlEngines must be deleted before calling this function. This function only affects the application global cache. Delete the QQmlEngine to clear all cached data relating to that engine.

QObject *qmlExtendedObject(QObject *base)

This function returns the extension object that belongs to base, if there is any. Otherwise it returns nullptr.

See also QML_EXTENDED.

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

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

void 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).

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.

int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

This function registers a type in the QML system with the name qmlName, in the type namespace imported from uri having the version number composed from versionMajor and versionMinor, but any attempt to instantiate the type will produce the given error message.

Normally, the types exported by a plugin 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.

Returns the QML type id.

Example:

 #ifdef NO_GAMES_ALLOWED
 qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
 #else
 qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
 #endif

This will cause any QML which imports the "MinehuntCore" type namespace and attempts to use the type to produce an error message:

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

Without this, a generic "Game is not a type" message would be given.

See also QML_UNAVAILABLE, qmlRegisterUncreatableType(), and 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)

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().

int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

Returns the QML type id of a type that was registered with the name qmlName in a particular uri and a version specified in versionMajor and versionMinor.

This function returns the same value as the QML type registration functions such as qmlRegisterType() and qmlRegisterSingletonType().

If qmlName, uri and versionMajor match a registered type, but the specified minor version in versionMinor is higher, then the id of the type with the closest minor version is returned.

Returns -1 if no matching type was found or one of the given parameters was invalid.

See also QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), and qmlRegisterSingletonType().

void 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().