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 Identifier Declaration
- Object Type Declaration
- Internal Object Type Declaration
- JavaScript Resource Declaration
- Plugin Declaration
- Plugin Classname Declaration
- Type Description File Declaration
- Module Dependencies Declaration
- Module Import Declaration
- Designer Support Declaration
- Preferred Path Declaration
Note: Each command in a qmldir
file must be on a separate line.
In addition to commands, you can also add comments, which are lines starting with #
.
Module Identifier Declaration
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
Object Type Declaration
[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 Object Type Declaration
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 is imported remotely (see Remotely Installed Identified Modules) because if an exported type depends on a non-exported type within the module, the engine must also load the non-exported type.
JavaScript Resource Declaration
<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 Declaration
[optional] plugin <Name> [<Path>]
Declares a plugin to be made available by the module.
optional
denotes that the plugin itself does not contain any relevant code and only serves to load a library it links to. If given, and if any types for the module are already available, indicating that the library has been loaded by some other means, QML will not load the plugin.<Name>
is the plugin library name. This is usually not the same as the file name of the plugin binary, which is platform dependent. For example, the libraryMyAppTypes
would producelibMyAppTypes.so
on Linux andMyAppTypes.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
Plugin Classname Declaration
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.
Type Description File Declaration
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.
Module Dependencies Declaration
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.
Module Import Declaration
import <ModuleIdentifier> [<Version>]
Declares that this module imports another.
Example:
import MyOtherModule 1.0
The types from the other module are made available in the same type namespace as this module is imported into. Omitting the version imports the latest version available of the other module. Specifying auto
as version imports the same version as the version of this module specified in the QML import
statement.
Designer Support Declaration
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 excessive 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.
Preferred Path Declaration
prefer <Path>
This property directs the QML engine to load any further files for this module from <path>, rather than the current directory. This can be used to load files compiled with qmlcachegen.
For example, you can add a module's QML files as resources to a resource path :/my/path/MyModule/
. Then, add prefer :/my/path/MyModule
to the qmldir file in order to use the files in the resource system, rather than the ones in the file system. If you then use qmlcachegen for those, the pre-compiled files will be available to any clients of the module.
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.
Type Description Files
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 C++ and typically imported via 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 defines QML types in C++ should also ship a type description file.
The best way to create a qmltypes file for your module is to generate it using the build system and the QML_ELEMENT macros. If you follow the documentation on this, no further action is needed. qmltyperegistrar will automatically generate the .qmltypes
files.
Example: If your module is in /tmp/imports/My/Module
, a file called plugins.qmltypes
should be generated alongside the actual plugin binary.
Add the line
typeinfo plugins.qmltypes
to /tmp/imports/My/Module/qmldir
to register it.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.