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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
/****************************************************************************
**
** 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-syntax-directoryimports.html
\title Importing QML Document Directories
\brief Description of directory import statements in QML
A local directory of QML files can be imported without any additional setup or
configuration. A remote directory of QML files can also be imported, but
requires a directory listing \c qmldir file to exist. A local directory may
optionally contain a directory listing \c qmldir file in order to define the
type names which should be provided to clients which import the directory, and
to specify JavaScript resources which should be made available to importers.
\section1 Local Directory Imports
Any QML file on the local file system can import a local directory as using an
import statement that refers to the directory's absolute or relative file
system path, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}
{object types} defined within that directory.
If the local directory contains a directory listing \c qmldir file, the types
will be made available with the type names specified in the \c qmldir file;
otherwise, they will be made available with type names derived from the
filenames of the QML documents. Only filenames beginning with an uppercase
letter and ending with ".qml" will be exposed as types if no \c qmldir file
is specified in the directory.
\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
The \c main/application.qml file can import the \c mycomponents directory using
the relative path to that directory, allowing it to use the QML object types
defined within that directory:
\qml
import "../mycomponents"
DialogBox {
CheckBox {
// ...
}
Slider {
// ...
}
}
\endqml
The directory may be imported into a qualified local namespace, in which case
uses of any types provided in the directory must be qualified:
\qml
import "../mycomponents" as MyComponents
MyComponents.DialogBox {
// ...
}
\endqml
The ability to import a local directory is convenient for cases such as
in-application component sets and application prototyping, although any code
that imports such modules must must update their relevant \c import statements
if the module directory moves to another location. This can be avoided if
\l{qtqml-modules-identifiedmodules.html}{QML modules} are used instead,
as an installed module is imported with a unique identifier string rather than
a file system path.
\section1 Remotely Located Directories
A directory of QML files can also be imported from a remote location if the
directory contains a directory listing \c qmldir file.
For example, if the \c myapp directory in the previous example was hosted at
"http://www.my-example-server.com", and the \c mycomponents directory
contained a \c qmldir file defined as follows:
\code
CheckBox CheckBox.qml
DialogBox DialogBox.qml
Slider Slider.qml
\endcode
Then, the directory could be imported using the URL to the remote
\c mycomponents directory:
\qml
import "http://www.my-example-server.com/myapp/mycomponents"
DialogBox {
CheckBox {
// ...
}
Slider {
// ...
}
}
\endqml
Note that when a file imports a directory over a network, it can only access QML
and JavaScript files specified in the \c qmldir file located in the directory.
\warning When importing directories from a remote server, developers should
always be careful to only load directories from trusted sources to avoid
loading malicious code.
\section1 Directory Listing qmldir Files
A directory listing \c qmldir file distinctly different from a
\l{qtqml-modules-qmldir.html}{module definition qmldir file}. A directory
listing \c qmldir file allows a group of QML documents to be quickly and easily
shared, but it does not define a type namespace into which the QML object types
defined by the documents are registered, nor does it support versioning of
those QML object types.
The syntax of a directory listing \c qmldir file is as follows:
\table
\header
\li Command
\li Syntax
\li Description
\row
\li Object Type Declaration
\li <TypeName> <FileName>
\li An object type declaration allows a QML document to be exposed with
the given \c <TypeName>.
Example:
\code
RoundedButton RoundedBtn.qml
\endcode
\row
\li Internal Object Type Declaration
\li internal <TypeName> <FileName>
\li An internal object type declaration allows a QML document to be
registered as a type which becomes available only to the other
QML documents contained in the directory import. The internal
type will not be made available to clients who import the directory.
Example:
\code
internal HighlightedButton HighlightedBtn.qml
\endcode
\li JavaScript Resource Declaration
\li <Identifier> <FileName>
\li A JavaScript resource declaration allows a JavaScript file to be
exposed via the given identifier.
Example:
\code
MathFunctions mathfuncs.js
\endcode
\endtable
A local file system directory may optionally include a \c qmldir file. This
allows the engine to only expose certain QML types to clients who import the
directory. Additionally, JavaScript resources in the directory are not exposed
to clients unless they are declared in a \c qmldir file.
*/
|
