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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-modules-installedmodules.html
\title Installed Modules
\brief Creating and importing installed modules
Installed modules are modules that are identifiable to the QML engine by a URI in the form of a
dotted identifier string. 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. This contrasts with
\l{qtqml-modules-locatedmodules.html}{located modules}, which are imported according to their
location on the file system.
When importing an installed module, an unquoted URI is used, with a mandatory version number:
\snippet qml/imports/installed-module.qml imports
Installed modules must be made available in the \l{qtqml-syntax-imports.html#qml-import-path}{import
path} in order to be found by the QML engine.
\section1 Locally Installed Modules
A directory of QML and/or C++ files can be shared as an installed module if it contains a
\l{qtqml-modules-qmldir.html}{qmldir file} with the module metadata. Any QML file on the local file
system can import this directory as a module by using an \l{qtqml-syntax-imports.html}{import}
statement that refers to the module's URI, enabling the file to use the
\l{qtqml-typesystem-objecttypes.html}{QML object types} defined within that directory.
The module's \c qmldir file must reside in a directory structure within the
\l{qtqml-syntax-imports.html#qml-import-path}{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 \c qmldir file of the module \c com.mycompany.mymodule must be located in the sub-path
\c com/mycompany/mymodule/qmldir somewhere in the
\l{qtqml-syntax-imports.html#qml-import-path}{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 \c com/mycompany/mymodule.2/qmldir or \c
com/mycompany/mymodule.2.1/qmldir. The engine will automatically load the module which matches best.
\section2 An Example
Consider the following QML project directory structure. Under the top level directory \c myapp,
there are a set of common UI components in a sub-directory named \c mycomponents, and the main
application code in a sub-directory named \c main, like this:
\code
myapp
|- mycomponents
|- CheckBox.qml
|- DialogBox.qml
|- Slider.qml
|- main
|- application.qml
\endcode
To make the \c mycomponents directory available as an installed module, the directory must include a
\l{qtqml-modules-qmldir.html}{qmldir file} that describes the object types made available by the
module. For example, to make the \c CheckBox, \c DialogBox and \c Slider types available for version
1.0 of the module, the \c qmldir file would contain the following:
\code
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml
\endcode
Additionally, the location of the \c qmldir file in the
\l{qtqml-syntax-imports.html#qml-import-path}{import path} must match the module's dotted identifier
string. So, say the top level \c myapp directory is located in \c C:\qml\projects, and say the
module should be identified as "myapp.mycomponents". In this case:
\list
\li The path \c C:\qml\projects should be added to the
\l{qtqml-syntax-imports.html#qml-import-path}{import path}
\li The qmldir file should be located under \c C:\qml\projects\myapp\mycomponents\qmldir
\endlist
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:
\qml
import myapp.mycomponents 1.0
DialogBox {
CheckBox {
// ...
}
Slider {
// ...
}
}
\endqml
\section1 Remotely Installed Modules
Installed modules are also accessible as a network resource. In the previous example, if the \c
C:\qml\projects directory was hosted as \c 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.
Note that when a file imports a module over a network, it can only access QML and JavaScript files
provided by the module; it cannot access any types defined by C++ plugins in the module.
\section1 In-application Modules
C++ applications can define installed modules directly within the application using
qmlRegisterType().
For example, the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++ tutorial}
defines a C++ class named \c PieChart and makes this type available to QML by calling
qmlRegisterType():
\code
qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
\endcode
This allows the application's QML files to use the \c PieChart type by importing the declared
\c Charts module:
\snippet qml/imports/chart.qml import
For \l{QQmlExtensionPlugin}{QML plugins}, the
module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method
can be reimplemented by the developer to register the necessary types for the module. Below is the
\c registerTypes() implementation from the \l{qml/cppextensions/plugins}{QML plugins}
example:
\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
Once the plugin is built and installed, and includes a \l{Adding Module Metadata with a qmldir file}{qmldir file},
the module can be imported from QML, like this:
\snippet qml/imports/timeexample.qml import
*/
|
