1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtqml-modules-topic.html
7\brief Description of how to write modules for QML
9A QML module provides versioned types and JavaScript resources in a type
10namespace which may be used by clients who import the module. The types which
11a module provides may be defined in C++ within a plugin, or in QML documents.
12Modules make use of the QML versioning system which allows modules to be
15Defining of a QML module allows:
17\li The sharing of common QML types within a project - for example, a group of
18 UI components that are used by different windows
19\li The distribution of QML-based libraries
20\li The modularization of distinct features, so that applications only load the
21 libraries necessary for their individual needs
22\li Versioning of types and resources so that the module can be updated safely
23 without breaking client code
27\section1 Defining a QML Module
29A module is defined by a \l{qtqml-modules-qmldir.html}
30{module definition qmldir file}. Each module has an associated type
31namespace, which is the module's identifier. A module can provide QML object
32types (defined either by QML documents or via a C++ plugin) and JavaScript
33resources, and may be imported by clients.
35To define a module, a developer should gather together the various QML
36documents, JavaScript resources and C++ plugins which belong in the module
37into a single directory, and write an appropriate \l{qtqml-modules-qmldir.html}
38{module definition qmldir file} which should also be placed into the directory.
39The directory can then be installed into the
40\l{qtqml-syntax-imports.html#qml-import-path}{QML import path} as a module.
42Note that defining a module is not the only way to share common QML types
43within a project - a simple \l{Importing QML Document Directories}
44{QML document directory import} may also be used for this purpose.
46\section1 Supported QML Module Types
48There are two different types of modules supported by QML:
50\li \l{Identified Modules}
51\li \l{Legacy Modules} (deprecated)
54Identified modules explicitly define their identifier and are installed into
55QML import path. Identified modules are more maintainable (due to type
56versioning) and are provided with type registration guarantees by the QML
57engine which are not provided to legacy modules. Legacy modules are only
58supported to allow legacy code to continue to work with the latest version of
59QML, and should be avoided by clients if possible.
61Clients may import a QML module from within QML documents or JavaScript files.
62Please see the documentation about
63\l{qtqml-syntax-imports.html#module-namespace-imports}{importing a QML module}
64for more information on the topic.
66\section1 Providing Types and Functionality in a C++ Plugin
68An application which has a lot of logic implemented in C++, or which defines
69types in C++ and exposes them to QML, may wish to implement a QML plugin. A
70QML extension module developer may wish to implement some types in a C++ plugin
71(as opposed to defining them via QML documents) to achieve better performance
72or for greater flexibility.
74Every C++ plugin for QML has an initialiatization function which is called by
75the QML engine when it loads the plugin. This initialization function must
76register any types that the plugin provides, but must not do anything else
77(for example, instantiating QObjects is not allowed).
79See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.