QML modules may use plugins to expose components defined in C++ to QML applications. Qt Creator cannot load the plugins to determine the details of the contained components, and therefore, the modules must provide extra type information for code completion and the semantic checks to work correctly.

When you write a QML module or use QML from a C++ application you typically register new types with the qmlRegisterType() function or expose some class instances with QQmlContext::setContextProperty(). The Qt Creator C++ code model now scans for these calls and tells the QML code model about them. This means that properties are displayed during code completion and the JavaScript code checker does not complain about unknown types. However, this works only when the source code is available, and therefore, you must explicitly generate type information for QML modules with plugins before distributing them.

Classes registered with qmlRegisterType() can be used as backend objects in the Qt Quick Designer. For more information, see Adding Connections.

By default, Qt Creator will look in the QML import path of Qt for QML modules. If your applications adds additional import paths that Qt Creator should use, then you can specify those using QML_IMPORT_PATH in the .pro file of your application.

Ideally, QML modules have a plugins.qmltypes file in the same directory as the qmldir file. The qmltypes file contains a description of the types exported by the module's plugins and is loaded by Qt Creator when the module is imported.

For Qt 4.8 and later, one or more qmltypes files can be listed in the qmldir file under the typeinfo header. These files will be read in addition to plugins.qmltypes. For more information, see Writing a qmltypes File.

Generating qmltypes Files

You can create and edit qmltypes files manually, but you are recommended to use the qmlplugindump tool shipped with Qt 4.8 and later to generate them automatically.

Once you have obtained qmlplugindump for the Qt version the QML module's plugins were compiled with, run the following command to load My.Module version 1.0 from /import/path/my/module including all its plugins and output a description of the plugins' types to /import/path/my/module/plugins.qmltypes:

qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes

You can safely ignore the debug output.

For Qt 4.7.x, you can compile a version of the tool called qmldump from the sources in <QtCreator>/share/qtcreator/qml/qmldump if the Qt version contains private headers.

Dumping Plugins Automatically

If a module with plugins lacks the qmltypes file, Qt Creator tries to generate a temporary file itself by running the qmldump program in the background. However, this automatic dumping is a fallback mechanism with many points of failure and you cannot rely upon it.

Running QML Modules in Qt Quick Designer

Qt Quick Designer uses a QML emulation layer (also called QML Puppet) to render and preview images and to collect data. To be able to render custom types correctly from QML modules, the emulation layer must be built with the same Qt version as the QML modules.

By default, a fallback emulation layer is provided by Qt Creator and built with the same Qt version as Qt Creator. Therefore, your QML modules will mostly not work out of the box.

To use an emulation layer that is built with the Qt configured in the build and run kit for the project, select Tools > Options > Qt Quick > Qt Quick Designer > Use QML emulation layer which is built by the selected Qt radio button. Qt Creator builds the emulation layer when you select the Design mode.

A plugin should behave differently depending on whether it is run by the emulation layer or an application. For example, animations should not be run in the Design mode. You can use the value of the QML_PUPPET_MODE environment variable to check whether the plugin is currently being run by an application or edited in the Design mode.

If you want to use a different module in Qt Quick Designer than in your actual application for example to mockup C++ items, then you can use QML_DESIGNER_IMPORT_PATH in the .pro file. Modules in the import paths defined in QML_DESIGNER_IMPORT_PATH will be used only in Qt Quick Designer.