Qt 5.9 | Qt QML | Module Definition qmldir Files

Qt 5.9.9 Reference Documentation

# Module Definition qmldir Files

There are two distinct types of `qmldir` files:

- QML document directory listing files
- QML module definition files

This documentation covers only the second form of `qmldir` file, which lists the QML types, JavaScript files, and plugins that are available under a module. For more information about the first form of `qmldir` file, see directory listing qmldir files.

## Contents of a Module Definition qmldir File

A `qmldir` file is a plain-text file that contains the following commands:

Syntax | Usage
--- | ---

      module <ModuleIdentifier>

Declares the module identifier of the module. The <ModuleIdentifier> is the (dotted URI notation) identifier for the module, which must match the module's install path.

The module identifier directive must be the first line of the file. Exactly one module identifier directive may exist in the `qmldir` file.

Example:

      module ExampleModule

      [singleton] <TypeName> <InitialVersion> <File>

Declares a QML object type to be made available by the module.

- `[singleton]` Optional. Used to declare a singleton type.
- `<TypeName>` is the type being made available
- `<InitialVersion>` is the module version for which the type is to be made available
- `<File>` is the (relative) file name of the QML file that defines the type

Zero or more object type declarations may exist in the `qmldir` file, however each object type must have a unique type name within any particular version of the module.

Note: To declare a `singleton` type, the QML file defining the type must include the `pragma Singleton` statement.

Example:

      //Style.qml with custom singleton type definition
      pragma Singleton
      import QtQuick 2.0

      QtObject {
          property int textSize: 20
          property color textColor: "green"
      }

      // qmldir declaring the singleton type
      module CustomStyles
      singleton Style 1.0 Style.qml

      // singleton type in use
      import QtQuick 2.0
      import CustomStyles 1.0

      Text {
          font.pixelSize: Style.textSize
          color: Style.textColor
          text: "Hello World"
      }

      internal <TypeName> <File>

Declares an object type that is in the module but should not be made available to users of the module.

Zero or more internal object type declarations may exist in the `qmldir` file.

Example:

      internal MyPrivateType MyPrivateType.qml

This is necessary if the module may be imported remotely (see Remotely Installed Identified Modules) because if an exported type depends on an non-exported type within the module, the engine must also load the non-exported type.

      <ResourceIdentifier> <InitialVersion> <File>

Declares a JavaScript file to be made available by the module. The resource will be made available via the specified identifier with the specified version number.

Zero or more JavaScript resource declarations may exist in the `qmldir` file, however each JavaScript resource must have a unique identifier within any particular version of the module.

Example:

      MyScript 1.0 MyScript.js

See the documentation about defining JavaScript resources and Importing JavaScript Resources In QML for more information.

      plugin <Name> [<Path>]

Declares a plugin to be made available by the module.

- `<Name>` is the plugin library name. This is usually not the same as the file name of the plugin binary, which is platform dependent; e.g. the library `MyAppTypes` would produce `libMyAppTypes.so` on Linux and `MyAppTypes.dll` on Windows.
- `<Path>` (optional) specifies either:
  - an absolute path to the directory containing the plugin file, or
  - a relative path from the directory containing the `qmldir` file to the directory containing the plugin file.

  By default the engine searches for the plugin library in the directory that contains the `qmldir` file. (The plugin search path can be queried with QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath().)

Zero or more C++ plugin declarations may exist in the `qmldir` file, however since plugin loading is a relatively expensive operation, clients are advised to specify at most a single plugin.

Example:

      plugin MyPluginLibrary

      classname <C++ plugin class>

Provides the class name of the C++ plugin used by the module.

This information is required for all the QML modules that depend on a C++ plugin for additional functionality. Qt Quick applications built with static linking cannot resolve the module imports without this information.

      typeinfo <File>

Declares a type description file for the module that can be read by QML tools such as Qt Creator to access information about the types defined by the module's plugins. `<File>` is the (relative) file name of a `.qmltypes` file.

Example:

      typeinfo mymodule.qmltypes

Without such a file, QML tools may be unable to offer features such as code completion for the types defined in your plugins.

      depends <ModuleIdentifier> <InitialVersion>

Declares that this module depends on another.

Example:

      depends MyOtherModule 1.0

This declaration is necessary only in cases when the dependency is hidden: for example, when the C++ code for one module is used to load QML (perhaps conditionally) which then depends on other modules. In such cases, the `depends` declaration is necessary to include the other modules in application packages.

      # <Comment>

Declares a comment. These are ignored by the engine.

Example:

      # this is a comment

      designersupported

Set this property if the plugin is supported by Qt Quick Designer. By default, the plugin will not be supported.

A plugin that is supported by Qt Quick Designer has to be properly tested. This means that the plugin does not crash when running inside the qml2puppet that is used by Qt Quick Designer to execute QML. Generally the plugin should work well in the Qt Quick Designer and not cause any show stoppers, like taking huge amounts of memory, slowing down the qml2puppet heavily or anything else that renders the plugin effectively unusable in the Qt Quick Designer.

The items of an unsupported plugin are not painted in the Qt Quick Designer, but they are still available as empty boxes and the properties can be edited.

Each command in a `qmldir` file must be on a separate line.

## Versioning Semantics

All QML types that are exported for a particular major version are available with the latest version of the same major version. For example, if a module provides a `MyButton` type in version 1.0 and `MyWindow` type in version 1.1, clients importing version `1.1` of the module get to use the `MyButton` and `MyWindow` types. However, the reverse is not true: a type exported for a particular minor version cannot be used by importing an older or earlier minor version. In the example mentioned earlier, if the client had imported version `1.0` of the module, they can use the `MyButton` type only but not the `MyWindow` type.

A module can offer multiple major versions but the clients have access to one major version only at a time. For example, importing `MyExampleModule 2.0` provides access to that major version only and not the previous major version. Although you can organize the artifacts that belong to different major versions under a sigle directory and a `qmldir` file, it is recommended to use different directories for each major version. If you choose to go with the earlier approach (one directory and a `qmldir` file), try to use the version suffix for the file names. For example, artifacts that belong to `MyExampleModule 2.0` can use `.2` suffix in their file name.

A version cannot be imported if no types have been explicitly exported for that version. If a module provides a `MyButton` type in version 1.0 and a `MyWindow` type in version 1.1, you cannot import version 1.2 or version 2.0 of that module.

A type can be defined by different files in different minor versions. In this case, the most closely matching version is used when imported by clients. For example, if a module had specified the following types via its `qmldir` file:

      module ExampleModule
      MyButton 1.0 MyButton.qml
      MyButton 1.1 MyButton11.qml
      MyButton 1.3 MyButton13.qml
      MyRectangle 1.2 MyRectangle12.qml

a client who imports version `1.2` of `ExampleModule` can use the `MyButton` type definition provided by `MyButton11.qml` as it is the latest version of that type, and the `MyRectangle` type definition provided by `MyRectangle12.qml`.

The version system ensures that a given QML file works regardless of the version of installed software, as a versioned import only imports types for that version, leaving other identifiers available, even if the actual installed version might otherwise provide those identifiers.

## Example of a qmldir File

One example of a `qmldir` file follows:

      module ExampleModule
      CustomButton 2.0 CustomButton20.qml
      CustomButton 2.1 CustomButton21.qml
      plugin examplemodule
      MathFunctions 2.0 mathfuncs.js

The above `qmldir` file defines a module called "ExampleModule". It defines the `CustomButton` QML object type in versions 2.0 and 2.1 of the module, with different implementations for each version. It specifies a plugin that must be loaded by the engine when the module is imported by clients, and that plugin may register various C++-defined types with the QML type system. On Unix-like systems the QML engine attempts to load `libexamplemodule.so` as a QQmlExtensionPlugin, and on Windows it loads `examplemodule.dll` as a QQmlExtensionPlugin. Finally, the `qmldir` file specifies a JavaScript resource, which is only available if version 2.0 or a later version (under the same major version) of the module is imported.

If the module is installed into the QML import path, clients could import and use the module in the following manner:

      import QtQuick 2.0
      import ExampleModule 2.1

      Rectangle {
          width: 400
          height: 400
          color: "lightsteelblue"

          CustomButton {
              color: "gray"
              text: "Click Me!"
              onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
          }
      }

The `CustomButton` type used above would come from the definition specified in the `CustomButton21.qml` file, and the JavaScript resource identified by the `MathFunctions` identifier would be defined in the `mathfuncs.js` file.

## Writing a qmltypes File

QML modules may refer to one or more type information files in their `qmldir` file. These usually have the `.qmltypes` extension and are read by external tools to gain information about types defined in plugins.

As such qmltypes files have no effect on the functionality of a QML module. Their only use is to allow tools such as Qt Creator to provide code completion, error checking and other functionality to users of your module.

Any module that uses plugins should also ship a type description file.

The best way to create a qmltypes file for your module is to generate it using the `qmlplugindump` tool that is provided with Qt.

Example: If your module is in `/tmp/imports/My/Module`, you could run

      qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes

to generate type information for your module. Afterwards, add the line

      typeinfo mymodule.qmltypes

to `/tmp/imports/My/Module/qmldir` to register it.

While the qmldump tool covers most cases, it does not work if:

- The plugin uses a `QQmlCustomParser`. The component that uses the custom parser will not get its members documented.
- The plugin can not be loaded. In particular if you cross-compiled the plugin for a different architecture, qmldump will not be able to load it.

In case you have to create a qmltypes file manually or need to adjust an existing one, this is the file format:

      import QtQuick.tooling 1.1

      // There always is a single Module object that contains all
      // Component objects.
      Module {
          // A Component object directly corresponds to a type exported
          // in a plugin with a call to qmlRegisterType.
          Component {

              // The name is a unique identifier used to refer to this type.
              // It is recommended you simply use the C++ type name.
              name: "QQuickAbstractAnimation"

              // The name of the prototype Component.
              prototype: "QObject"

              // The name of the default property.
              defaultProperty: "animations"

              // The name of the type containing attached properties
              // and methods.
              attachedType: "QQuickAnimationAttached"

              // The list of exports determines how a type can be imported.
              // Each string has the format "URI/Name version" and matches the
              // arguments to qmlRegisterType. Usually types are only exported
              // once, if at all.
              // If the "URI/" part of the string is missing that means the
              // type should be put into the package defined by the URI the
              // module was imported with.
              // For example if this module was imported with 'import Foo 4.8'
              // the Animation object would be found in the package Foo and
              // QtQuick.
              exports: [
                  "Animation 4.7",
                  "QtQuick/Animation 1.0"
              ]

              // The meta object revisions for the exports specified in 'exports'.
              // Describes with revisioned properties will be visible in an export.
              // The list must have exactly the same length as the 'exports' list.
              // For example the 'animations' propery described below will only be
              // available through the QtQuick/Animation 1.0 export.
              exportMetaObjectRevisions: [0, 1]

              Property {
                  name: "animations";
                  type: "QQuickAbstractAnimation"
                  // defaults to false, whether this property is read only
                  isReadonly: true
                  // defaults to false, whether the type of this property was a pointer in C++
                  isPointer: true
                  // defaults to false: whether the type actually is a QQmlListProperty<type>
                  isList: true
                  // defaults to 0: the meta object revision that introduced this property
                  revision: 1
              }
              Property { name: "loops"; type: "int" }
              Property { name: "name"; type: "string" }
              Property { name: "loopsEnum"; type: "Loops" }

              Enum {
                  name: "Loops"
                  values: {
                      "Infinite": -2,
                      "OnceOnly": 1
                  }
              }

              // Signal and Method work the same way. The inner Parameter
              // declarations also support the isReadonly, isPointer and isList
              // attributes which mean the same as for Property
              Method { name: "restart" }
              Signal { name: "started"; revision: 2 }
              Signal {
                  name: "runningChanged"
                  Parameter { type: "bool" }
                  Parameter { name: "foo"; type: "bool" }
              }
          }
      }