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:

 module <ModuleIdentifier>

 module ExampleModule

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

 //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>

 internal MyPrivateType MyPrivateType.qml

 <ResourceIdentifier> <InitialVersion> <File>

 MyScript 1.0 MyScript.js

 plugin <Name> [<Path>]

 plugin MyPluginLibrary

 classname <C++ plugin class>

 typeinfo <File>

 typeinfo mymodule.qmltypes

 depends <ModuleIdentifier> <InitialVersion>

 depends MyOtherModule 1.0

 # <Comment>

 # this is a comment

 designersupported

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
     // using the QML_ELEMENT or QML_NAMED_ELEMENT macros.
     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". The URI is
         // the import name given via the build system, for example as
         // QML_IMPORT_NAME in qmake. The name is either the C++ class
         // name or, in case of QML_NAMED_ELEMENT(), an explicitly given
         // name. The version is constructed from the major version
         // given via the build system, as QML_IMPORT_MAJOR_VERSION in
         // qmake, and any revisions given in the class or its base
         // classes by Q_REVISION(), the REVISION argument to Q_PROPERTY,
         // or QML_ADDED_IN_MINOR_VERSION(). Usually types are only
         // exported once, if at all. The following tells us that there
         // are two variants of Animation, and that 'import QtQuick 2.0'
         // will expose a different revision than imports of later
         // versions.
         exports: [
             "QtQuick/Animation 2.0",
             "QtQuick/Animation 2.1"
         ]

         // The meta object revisions for the exports specified in 'exports'.
         // Each meta object revision may add additional properties or methods,
         // relative to the previous one. Those will only be visible when the
         // module is imported with at least the corresponding version as
         // specified in the 'exports' list.
         // The exportMetaObjectRevisions list must have exactly the same
         // length as the 'exports' list. For example, the 'animations' property
         // described below will only be available through the QtQuick/Animation
         // 2.1 export. Usually the revisions will match the versions in the
         // 'exports' list.
         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", "OnceOnly" ]
         }

         // 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: 1 }
         Signal {
             name: "runningChanged"
             Parameter { type: "bool" }
             Parameter { name: "foo"; type: "bool" }
         }
     }
 }