- Qt Design Studio Manual
- Using QML Modules with Plugins
- Qt Design Studio Manual 2.3.1

Simulating Dynamic Systems ◦ Dynamic Behaviors

# Using QML Modules with Plugins

QML modules may use plugins to expose components defined in C++ to QML applications. Qt Design Studio 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.

To create a QML module and make it appear in the Library view:

1. Create custom components and place all the `.qml` files in a directory dedicated to your module. For example: `imports\asset_imports`.
2. For Qt Quick UI projects (.qmlproject), specify the path to the directory that contains the module in the .qmlproject file of the application where you want to use the module as a value of the `importPaths` variable. For example `importPaths: [ "imports", "asset_imports" ]`.
3. Create a `qmldir` file for your module and place it in the module directory. For more information, see Module Definition qmldir Files.
4. Create a `qmltypes` file, preferably using `qmlplugindump`. For more information see, Generating qmltypes Files.
5. Create a directory named `designer` in your module directory.
6. Create a `.metainfo` file for your module and place it in the `designer` directory. Meta information is needed to display the components in the Components tab in Library. Use a metainfo file delivered with Qt, such as `qtquickcontrols2.metainfo`, as an example.
7. Build your module using the same Qt version and compiler as Qt Design Studio. For more information, see Running QML Modules in Design Mode.

Your module should now appear in the Components tab in Library. Your components should appear in a subsection of the Components tab if a valid `.metainfo` file is in place.

## Generating qmltypes Files

Ideally, QML modules have a `plugins.qmltypes` file in the same directory as the `qmldir` file. The `qmltypes` file contains a description of the components exported by the module's plugins and is loaded by Qt Design Studio 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.

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' components to `/import/path/my/module/plugins.qmltypes`:

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

You can safely ignore the debug output.

### Dumping Plugins Automatically

If a module with plugins lacks the `qmltypes` file, Qt Design Studio 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 Design Mode

A QML emulation layer (also called QML Puppet) is used in the Design mode to render and preview images and to collect data. To be able to render custom components correctly from QML modules, the emulation layer must be built with the same Qt version and compiler as the QML modules.

On Windows, select Help > About Qt Design Studio to check the Qt version and compiler that you need to use to build your plugin. For example: `Based on Qt 5.15.2 (MSVC 2019, 64 bit)`.

On macOS, select Qt Design Studio > About Qt Design Studio to see something like: `Based on Qt 5.15.2 (Clang 10.0 (Apple), 64 bit)`.

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 the Design mode than in your actual application for example to mockup C++ items, you can use `QML_DESIGNER_IMPORT_PATH` in the `.pro` file (for qmake projects), or declare and set the property `qmlDesignerImportPaths` in your product (for Qbs projects). Modules in the import paths defined in `QML_DESIGNER_IMPORT_PATH` will be used only in the Design mode. For an example, see Qt Quick Controls - Contact List.

Simulating Dynamic Systems ◦ Dynamic Behaviors