1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-modules-topic.html
\title QML Modules
\brief Description of how to write modules for QML
A QML module provides versioned types and JavaScript resources in a type
namespace which may be used by clients who import the module. The types which
a module provides may be defined in C++ within a plugin, or in QML documents.
Modules make use of the QML versioning system which allows modules to be
independently updated.
Defining of a QML module allows:
\list
\li The sharing of common QML types within a project - for example, a group of
UI components that are used by different windows
\li The distribution of QML-based libraries
\li The modularization of distinct features, so that applications only load the
libraries necessary for their individual needs
\li Versioning of types and resources so that the module can be updated safely
without breaking client code
\endlist
\section1 Defining a QML Module
A module is defined by a \l{qtqml-modules-qmldir.html}
{module definition qmldir file}. Each module has an associated type
namespace, which is the module's identifier. A module can provide QML object
types (defined either by QML documents or via a C++ plugin) and JavaScript
resources, and may be imported by clients.
To define a module, a developer should gather together the various QML
documents, JavaScript resources and C++ plugins which belong in the module
into a single directory, and write an appropriate \l{qtqml-modules-qmldir.html}
{module definition qmldir file} which should also be placed into the directory.
The directory can then be installed into the
\l{qtqml-syntax-imports.html#qml-import-path}{QML import path} as a module.
Note that defining a module is not the only way to share common QML types
within a project - a simple \l{Importing QML Document Directories}
{QML document directory import} may also be used for this purpose.
\section1 Supported QML Module Types
There are two different types of modules supported by QML:
\list
\li \l{Identified Modules}
\li \l{Legacy Modules} (deprecated)
\endlist
Identified modules explicitly define their identifier and are installed into
QML import path. Identified modules are more maintainable (due to type
versioning) and are provided with type registration guarantees by the QML
engine which are not provided to legacy modules. Legacy modules are only
supported to allow legacy code to continue to work with the latest version of
QML, and should be avoided by clients if possible.
Clients may import a QML module from within QML documents or JavaScript files.
Please see the documentation about
\l{qtqml-syntax-imports.html#module-namespace-imports}{importing a QML module}
for more information on the topic.
\section1 Providing Types and Functionality in a C++ Plugin
An application which has a lot of logic implemented in C++, or which defines
types in C++ and exposes them to QML, may wish to implement a QML plugin. A
QML extension module developer may wish to implement some types in a C++ plugin
(as opposed to defining them via QML documents) to achieve better performance
or for greater flexibility.
Every C++ plugin for QML has an initialiatization function which is called by
the QML engine when it loads the plugin. This initialization function must
register any types that the plugin provides, but must not do anything else
(for example, instantiating QObjects is not allowed).
See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.
*/
|
