Using QML Modules with Plugins
QML modules may use plugins to expose components defined in C++ to QML applications. Qt Creator 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 :
- Create custom components and place all the
.qml
files in a directory dedicated to your module. For example:imports\asset_imports
. - 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 exampleimportPaths: [ "imports", "asset_imports" ]
. - Create a
qmldir
file for your module and place it in the module directory. For more information, see Module Definition qmldir Files. - Create a
qmltypes
file, preferably usingqmlplugindump
. For more information see, Generating qmltypes Files. - Create a directory named
designer
in your module directory. - Create a
.metainfo
file for your module and place it in thedesigner
directory. Use a metainfo file delivered with Qt, such asqtquickcontrols2.metainfo
, as an example. - Import the module into the project, as instructed in Importing QML Modules.
Registering QML Types
When you write a QML module or use QML from a C++ application, and the C++ is a part of your qmake project, you typically register new types with the qmlRegisterType()
function or expose some class instances with QQmlContext::setContextProperty(). The Qt Creator C++ code model now scans for these calls and tells the QML code model about them. This means that properties are displayed during code completion and the JavaScript code checker does not complain about unknown types. However, this works only when the source code is available, and therefore, you must explicitly generate type information for QML modules with plugins before distributing them.
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 Creator 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.
For Qt 4.7.x, you can compile a version of the tool called qmldump
from the sources in <QtCreator>/share/qtcreator/qml/qmldump
if the Qt version contains private headers.
Dumping Plugins Automatically
If a module with plugins lacks the qmltypes
file, Qt Creator 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.
Importing QML Modules
By default, Qt Creator will look in the QML import path of Qt for QML modules.
If you use qmake and your application adds additional import paths that Qt Creator should use, specify them using QML_IMPORT_PATH
in the .pro
file of your application: QML_IMPORT_PATH += path/to/module
.
If you use CMake, add the following command to the CMakeLists.txt file to set the QML import path:
set(QML_IMPORT_PATH ${CMAKE_SOURCE_DIR}/qml ${CMAKE_BINARY_DIR}/imports CACHE STRING "" FORCE)
The import path affects all the targets built by the CMake project.