Identified modules are modules that are installed and identifiable to the QML engine by a URI in the form of a dotted identifier string, which should be specified by the module in its
qmldir file. This enables such modules to be imported with a unique identifier that remains the same no matter where the module is located on the local file system.
When importing an identified module, an unquoted identifier is used, with an optional version number:
import QtQuick 2.0 import com.nokia.qml.mymodule 1.0
Identified modules must be installed into the import path in order to be found by the QML engine.
Syntactically, each dot-separated segment of the URI must be a well-formed ECMAScript Identifier Name. This means, for example, the segments must not start with a number and they must not contain - (minus) characters. As the URI will be translated into directory names, you should restrict it to alphanumeric characters of the latin alphabet, underscores, and dots.
Locally Installed Identified Modules
qmldir file must reside in a directory structure within the import path that reflects the URI dotted identifier string, where each dot (".") in the identifier reflects a sub-level in the directory tree. For example, the
qmldir file of the module
com.mycompany.mymodule must be located in the sub-path
com/mycompany/mymodule/qmldir somewhere in the import path.
It is possible to store different versions of a module in subdirectories of its own. For example, a version 2.1 of a module could be located under
com/mycompany/mymodule.2.1/qmldir. The engine will automatically load the module which matches best.
Alternatively, versioning for different types can be defined within a qmldir file itself, however this can make updating such a module more difficult (as a
qmldir file merge must take place as part of the update procedure).
Consider the following QML project directory structure. Under the top level directory
myapp, there are a set of common UI components in a sub-directory named
mycomponents, and the main application code in a sub-directory named
main, like this:
myapp |- mycomponents |- CheckBox.qml |- DialogBox.qml |- Slider.qml |- main |- application.qml
To make the
mycomponents directory available as an identified module, the directory must include a qmldir file that defines the module identifier, and describes the object types made available by the module. For example, to make the
Slider types available for version 1.0 of the module, the
qmldir file would contain the following:
module myapp.mycomponents CheckBox 1.0 CheckBox.qml DialogBox 1.0 DialogBox.qml Slider 1.0 Slider.qml
Additionally, the location of the
qmldir file in the import path must match the module's dotted identifier string. So, say the top level
myapp directory is located in
C:\qml\projects, and say the module should be identified as "myapp.mycomponents". In this case:
- The path
C:\qml\projectsshould be added to the import path
- The qmldir file should be located under
Once this is done, a QML file located anywhere on the local filesystem can import the module by referring to its URI and the appropriate version:
Remotely Installed Identified Modules
Identified modules are also accessible as a network resource. In the previous example, if the
C:\qml\projects directory was hosted as
http://www.some-server.com/qml/projects and this URL was added to the QML import path, the module could be imported in exactly the same way.
Semantics of Identified Modules
An identified module is provided with the following guarantees by the QML engine:
- other modules are unable to modify or override types in the module's namespace
- other modules are unable to register new types into the module's namespace
- usage of type names by clients will resolve deterministically to a given type definition depending on the versioning specified and the import order
This ensures that clients which use the module can be certain that the object types defined in the module will behave as the module author documented.
An identified module has several restrictions upon it:
- an identified module must be installed into the QML import path
- the module identifier specified in the module identifier directive must match the install path of the module (relative to the QML import path, where directory separators are replaced with period characters)
- the module must register its types into the module identifier type namespace
- the module may not register types into any other module's namespace
- clients must specify a version when importing the module
For example, if an identified module is installed into
$QML_IMPORT_PATH/ExampleModule, the module identifier directive must be:
If the strict module is installed into
$QML_IMPORT_PATH/com/example/CustomUi, the module identifier directive must be:
Clients will then be able to import the above module with the following import statement (assuming that the module registers types into version 1.0 of its namespace):
import com.example.CustomUi 1.0
© 2023 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.