QQmlExtensionPlugin Class

An example

Suppose there is a new TimeModel C++ class that should be made available as a new QML element. It provides the current time through hour and minute properties, like this:

 class TimeModel : public QObject
 {
     Q_OBJECT
     Q_PROPERTY(int hour READ hour NOTIFY timeChanged)
     Q_PROPERTY(int minute READ minute NOTIFY timeChanged)
     ...

To make this class available as a QML type, create a plugin that registers this type with a specific module using qmlRegisterType(). For this example the plugin module will be named com.nokia.TimeExample (as defined in the project file further below).

 class QExampleQmlPlugin : public QQmlExtensionPlugin
 {
     Q_OBJECT
     Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QQmlExtensionInterface" FILE "plugin.json")

 public:
     void registerTypes(const char *uri)
     {
         Q_ASSERT(uri == QLatin1String("com.nokia.TimeExample"));
         qmlRegisterType<TimeModel>(uri, 1, 0, "Time");
     }
 };

This registers the TimeModel class with the 1.0 version of this plugin library, as a QML type called Time. The Q_ASSERT statement ensures the module is imported correctly by any QML components that use this plugin.

The project file defines the project as a plugin library and specifies it should be built into the com/nokia/TimeExample directory:

 TEMPLATE = lib
 CONFIG += qt plugin
 QT += qml

 DESTDIR = com/nokia/TimeExample
 TARGET = qmlqtimeexampleplugin
 ...

Finally, a qmldir file is required in the com/nokia/TimeExample directory that describes the plugin. This directory includes a Clock.qml file that should be bundled with the plugin, so it needs to be specified in the qmldir file:

Once the project is built and installed, the new Time element can be used by any QML component that imports the com.nokia.TimeExample module:

The full source code is available in the plugins example.

The Tutorial: Writing QML extensions with C++ also contains a chapter on creating QML plugins.

Note that the QtQuick 1 version is called QDeclarativeExtensionPlugin.