Modern QML modules | Qt Qml (original) (raw)
QML modules have become more powerful and easier to use in Qt 6. The following sections describe how to modernize QML modules that already use qt_add_qml_module.
See also Port QML modules to CMake on how to port a QML module to the qt_add_qml_module CMake API.
Use qt_standard_project_setup
qt_standard_project_setup sets up Qt CMake policies needed for modern QML modules, among other things. To modernize your QML module and follow best practices, call qt_standard_project_setup in the project's top-level CMakeLists.txt
file before any qt_add_qml_module call:
qt_standard_project_setup(REQUIRES 6.8)
Use the new standard resource path prefix
The standard resource path for QML modules moved from :/
to :/qt/qml
with QTP0001. Don't use custom resource prefixes nor extend import paths in the engine. Remove all RESOURCE_PREFIX
arguments from all qt_add_qml_module calls, as well as all calls to QQmlEngine::addImportPath or similar. Change all qrc paths in your C++ and QML code to use the new resource path prefix:
// C++ usages like: QUrl someUrl("qrc:/MyQmlModule/MyResource1.png"); // need to be changed to QUrl someUrl("qrc:/qt/qml/MyQmlModule/MyResource1.png");
// QML usages like: ":/MyQmlModule/MyResource1.png" // need to be changed to ":/qt/qml/MyQmlModule/MyResource1.png"
See also Using the Qt Resource System with QML.
Use loadFromModule to load your QML files
With the default import path, you can use the loadFromModule
methods, like QQmlApplicationEngine::loadFromModule, QQuickView::loadFromModule, or QQmlComponent::loadFromModule, for example.
Use loadFromModule
to load your QML file, for example:
engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml"))); // becomes engine.loadFromModule("MyQmlModule", "Main");
Replace OUTPUT_DIRECTORY and IMPORT_PATH with DEPENDENCIES TARGET
Avoid setting an IMPORT_PATH
in the qt_add_qml_module. Instead, use DEPENDENCIES TARGET
to declare dependencies to other QML modules that can't be found in the current import path.
Using DEPENDENCIES TARGET
also eliminates the need for the QT_QML_OUTPUT_DIRECTORY
CMake variable and the OUTPUT_DIRECTORY
argument to qt_add_qml_module, so remove their definitions and usages.
For example:
in the CMakeLists.txt file defining the dependent QML module:
don't set QT_QML_OUTPUT_DIRECTORY and remove lines like these:
set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml)
qt_add_qml_module(MyThirdPartyQmlLibraryDependency URI MyThirdPartyQmlLibraryDependency .... # custom output paths are obsolete due to DEPENDENCIES TARGET below, so remove: OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml }
in the CMakeLists.txt file defining the QML module that uses the dependency:
qt_add_qml_module(MyQmlLibrary URI MyQmlModule ... # replace import paths like these: IMPORT_PATH ${CMAKE_CURRENT_BINARY_DIR}/thirdparty/qml # with: DEPENDENCIES TARGET MyThirdPartyQmlLibraryDependency }
Note: You might need to call add_subdirectory()
before calling qt_add_qml_module in your CMakeLists.txt for DEPENDENCIES TARGET
to find the target.
For more information on how to declare module dependencies, see Declaring module dependencies.