Defining QML Types from C++▲
When extending QML with C++ code, a C++ class can be registered with the QML type system to enable the class to be used as a data type within QML code. While the properties, methods and signals of any QObject-derived class are accessible from QML, as discussed in Exposing Attributes of C++ Types to QML, such a class cannot be used as a data type from QML until it is registered with the type system. Additionally registration can provide other features, such as allowing a class to be used as an instantiable QML object type from QML, or enabling a singleton instance of the class to be imported and used from QML.
Additionally, the Qt QML module provides mechanisms for implementing QML-specific features such as attached properties and default properties in C++.
(Note that a number of the important concepts covered in this document are demonstrated in the Writing QML Extensions with C++ tutorial.)
NOTE: All headers that declare QML types need to be accessible without any prefix from the project's include path.
For more information about C++ and the different QML integration methods, see the C++ and QML integration overview page.
Registering C++ Types with the QML Type System▲
A QObject-derived class can be registered with the QML type system to enable the type to be used as a data type from within QML code.
The engine allows the registration of both instantiable and non-instantiable types. Registering an instantiable type enables a C++ class to be used as the definition of a QML object type, allowing it to be used in object declarations from QML code to create objects of this type. Registration also provides the engine with additional type metadata, enabling the type (and any enums declared by the class) to be used as a data type for property values, method parameters and return values, and signal parameters that are exchanged between QML and C++.
Registering a non-instantiable type also registers the class as a data type in this manner, but the type cannot be used instantiated as a QML object type from QML. This is useful, for example, if a type has enums that should be exposed to QML but the type itself should not be instantiable.
For a quick guide to choosing the correct approach to expose C++ types to QML, see Choosing the Correct Integration Method Between C++ and QML.
Preconditions▲
All the macros mentioned below are available from the qqmlregistration.h header. You need to add the following code to the files using them in order to make the macros available:
#include <QtQml/qqmlregistration.h>Furthermore, your class declarations have to live in headers reachable via your project's include path. The declarations are used to generate registration code at compile time, and the registration code needs to include the headers that contain the declarations.
Registering an Instantiable Object Type▲
Any QObject-derived C++ class can be registered as the definition of a QML object type. Once a class is registered with the QML type system, the class can be declared and instantiated like any other object type from QML code. Once created, a class instance can be manipulated from QML; as Exposing Attributes of C++ Types to QML explains, the properties, methods and signals of any QObject-derived class are accessible from QML code.
To register a QObject-derived class as an instantiable QML object type, add QML_ELEMENT or QML_NAMED_ELEMENT(<name>) to the class declaration. You also need to make adjustments in the build system. For qmake, add CONFIG += qmltypes, a QML_IMPORT_NAME, and a QML_IMPORT_MAJOR_VERSION to your project file. For CMake, the file containing the class should be part of a target set-up with qt_add_qml_module(). This will register the class into the type namespace under the given major version, using either the class name or an explicitly given name as QML type name. The minor version(s) will be derived from any revisions attached to properties, methods, or signals. The default minor version is 0. You can explicitly restrict the type to be available only from specific minor versions by adding the QML_ADDED_IN_MINOR_VERSION() macro to the class declaration. Clients can import suitable versions of the namespace in order to use the type.
For example, suppose there is a Message class with author and creationDate properties: