← Back to branch summary

~saviq/ubuntu/saucy/qtdeclarative-opensource-src/add-qtquick-delegate-range

« back to all changes in this revision

Viewing changes to src/qml/doc/src/syntax/imports.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 14:17:19 UTC
  • Revision ID: package-import@ubuntu.com-20130205141719-qqeyml8wslpyez52
Tags: upstream-5.0.1
Import upstream version 5.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/qml/doc/src/syntax/imports.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the documentation of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
9
** Commercial License Usage
 
10
** Licensees holding valid commercial Qt licenses may use this file in
 
11
** accordance with the commercial license agreement provided with the
 
12
** Software or, alternatively, in accordance with the terms contained in
 
13
** a written agreement between you and Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/contact-us.
 
16
**
 
17
** GNU Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
/*!
 
28
\page qtqml-syntax-imports.html
 
29
\title Import Statements
 
30
\brief Description of import statements in QML
 
31
 
 
32
\section1 Syntax of an Import Statement
 
33
 
 
34
An import statement allows clients to tell the engine which modules, JavaScript
 
35
resources and component directories are used within a QML document.  The types
 
36
which may be used within a document depends on which modules, resources and
 
37
directories are imported by the document.
 
38
 
 
39
\section2 Import Types
 
40
 
 
41
There are three different types of imports.  Each import type has a slightly
 
42
different syntax, and different semantics apply to different import types.
 
43
 
 
44
\section3 Module (Namespace) Imports
 
45
 
 
46
The most common type of import is a module import.  Clients can import
 
47
\l{qtqml-modules-identifiedmodules.html}{QML modules} which register QML object
 
48
types and JavaScript resources into a given namespace.
 
49
 
 
50
The generic form of a module import is as follows:
 
51
\code
 
52
import <ModuleIdentifier> <Version.Number> [as <Qualifier>]
 
53
\endcode
 
54
 
 
55
\list
 
56
  \li The \c <ModuleIdentifier> is an identifier specified in dotted URI
 
57
      notation, which uniquely identifies the type namespace provided by the
 
58
      module.
 
59
  \li The \c <Version.Number> is a version of the form
 
60
      \c {MajorVersion.MinorVersion} which specifies which definitions of
 
61
      various object types and JavaScript resources will be made available due
 
62
      to the import.
 
63
  \li The \c <Qualifier> is an optional local namespace identifier into which
 
64
      the object types and JavaScript resources provided by the module will be
 
65
      installed, if given.  If omitted, the object types and JavaScript
 
66
      resources provided by the module will be installed into the global
 
67
      namespace.
 
68
\endlist
 
69
 
 
70
An example of an unqualified module import is as follows:
 
71
\code
 
72
import QtQuick 2.0
 
73
\endcode
 
74
 
 
75
This import allows the use of all of the types provided by the \c QtQuick
 
76
module without needing to specify a qualifier.  For example, the client code to
 
77
create a rectangle is as follows:
 
78
 
 
79
\qml
 
80
import QtQuick 2.0
 
81
 
 
82
Rectangle {
 
83
    width: 200
 
84
    height: 100
 
85
    color: "red"
 
86
}
 
87
\endqml
 
88
 
 
89
An example of a qualified module import is as follows:
 
90
\code
 
91
import QtQuick 2.0 as Quick
 
92
\endcode
 
93
 
 
94
This import allows multiple modules which provide conflicting type names to be
 
95
imported at the same time, however since each usage of a type provided by a
 
96
module which was imported into a qualified namespace must be preceded by the
 
97
qualifier, the conflict is able to be resolved unambiguously by the QML engine.
 
98
 
 
99
An example of client code which creates a rectangle after using a qualified
 
100
module import is as follows:
 
101
 
 
102
\qml
 
103
import QtQuick 2.0 as Quick
 
104
 
 
105
Quick.Rectangle {
 
106
    width: 200
 
107
    height: 100
 
108
    color: "red"
 
109
}
 
110
\endqml
 
111
 
 
112
For more information about qualified imports, see the upcoming section on
 
113
\l{Importing Into A Qualified Local Namespace}.
 
114
 
 
115
Note that if a QML document does not import a module which provides a
 
116
particular QML object type, but attempts to use that object type anyway,
 
117
an error will occur.  For example, the following QML document does not
 
118
import \c QtQuick and thus attempting to use the \c Rectangle type will fail:
 
119
 
 
120
\qml
 
121
Rectangle {
 
122
    width: 200
 
123
    height: 100
 
124
    color: "red"
 
125
}
 
126
\endqml
 
127
 
 
128
In this case, the engine will emit an error and refuse to load the file.
 
129
 
 
130
\section4 Non-module Namespace Imports
 
131
 
 
132
Types can also be registered into namespaces directly via the various
 
133
registration functions in C++ (such as qmlRegisterType()).  The types which
 
134
have been registered into a namespace in this way may be imported by importing
 
135
the namespace, as if the namespace was a module identifier.
 
136
 
 
137
This is most common in client applications which define their own QML object
 
138
types in C++ and register them with the QML type system manually.
 
139
 
 
140
\section4 Importing into a Qualified Local Namespace
 
141
 
 
142
The \c import statement may optionally use the \c as keyword to specify that
 
143
the types should be imported into a particular document-local namespace. If a
 
144
namespace is specified, then any references to the types made available by the
 
145
import must be prefixed by the local namespace qualifier.
 
146
 
 
147
Below, the QtQuick module is imported into the namespace "CoreItems". Now, any
 
148
references to types from the \c QtQuick module must be prefixed with the
 
149
\c CoreItems name:
 
150
 
 
151
\qml
 
152
import QtQuick 2.0 as CoreItems
 
153
 
 
154
CoreItems.Rectangle {
 
155
    width: 100; height: 100
 
156
 
 
157
    CoreItems.Text { text: "Hello, world!" }
 
158
 
 
159
    // WRONG! No namespace prefix - the Text type won't be found
 
160
    Text { text: "Hello, world!" }
 
161
}
 
162
\endqml
 
163
 
 
164
A namespace acts as an identifier for a module within the scope of the file.
 
165
The namespace does not become an attribute of the root object that can be
 
166
referred to externally as can be done with properties, signals and methods.
 
167
 
 
168
The namespaced import is useful if there is a requirement to use two QML types
 
169
that have the same name but are located in different modules. In this case the
 
170
two modules can be imported into different namespaces to ensure the code is
 
171
referring to the correct type:
 
172
 
 
173
\qml
 
174
import QtQuick 2.0 as CoreItems
 
175
import "../textwidgets" as MyModule
 
176
 
 
177
CoreItems.Rectangle {
 
178
    width: 100; height: 100
 
179
 
 
180
    MyModule.Text { text: "Hello from my custom text item!" }
 
181
    CoreItems.Text { text: "Hello from QtQuick!" }
 
182
}
 
183
\endqml
 
184
 
 
185
Note that multiple modules can be imported into the same namespace in the same
 
186
way that multiple modules can be imported into the global namespace. For example:
 
187
 
 
188
\snippet qml/imports/merged-named-imports.qml imports
 
189
 
 
190
\section3 Directory Imports
 
191
 
 
192
A directory which contains QML documents may also be imported directly in a
 
193
QML document.  This provides a simple way for QML types to be segmented into
 
194
reusable groupings: directories on the filesystem.
 
195
 
 
196
The generic form of a directory import is as follows:
 
197
\qml
 
198
import "<DirectoryPath>" [as <Qualifier>]
 
199
\endqml
 
200
 
 
201
\note Import paths are network transparent: applications can import documents
 
202
from remote paths just as simply as documents from local paths. See the general
 
203
URL resolution rules for \l{qtqml-documents-networktransparency.html}
 
204
{Network Transparency} in QML documents.  If the directory is remote, it must
 
205
contain a \l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
 
206
{directory import listing qmldir file} as the QML engine cannot determine
 
207
the contents of a remote directory if that \c qmldir file does not exist.
 
208
 
 
209
Similar semantics for the \c <Qualifier> apply to directory imports as for
 
210
module imports; for more information on the topic, please see the previous
 
211
section about \l{Importing into a Qualified Local Namespace}.
 
212
 
 
213
For more information about directory imports, please see the in-depth
 
214
documentation about \l{qtqml-syntax-directoryimports.html}{directory imports}.
 
215
 
 
216
\section3 JavaScript Resource Imports
 
217
 
 
218
JavaScript resources may be imported directly in a QML document.  Every
 
219
JavaScript resource must have an identifier by which it is accessed.
 
220
 
 
221
The generic form of a JavaScript resource import is as follows:
 
222
\code
 
223
import "<JavaScriptFile>" as <Identifier>
 
224
\endcode
 
225
 
 
226
Note that the \c <Identifier> must be unique within a QML document, unlike the
 
227
local namespace qualifier which can be applied to module imports.
 
228
 
 
229
\section4 JavaScript Resources from Modules
 
230
 
 
231
Javascript files can be provided by modules, by adding identifier
 
232
definitions to the \c qmldir file which specifies the module.
 
233
 
 
234
For example, if the \c projects.MyQMLProject.MyFunctions module is specified
 
235
with the following \c qmldir file, and installed into the QML import path:
 
236
\code
 
237
module projects.MyQMLProject.MyFunctions
 
238
SystemFunctions 1.0 SystemFunctions.js
 
239
UserFunctions 1.0 UserFunctions.js
 
240
\endcode
 
241
 
 
242
a client application is able to import the JavaScript resources declared in the
 
243
module by importing the module and using the identifier associated with a
 
244
declared resource:
 
245
 
 
246
\qml
 
247
import QtQuick 2.0
 
248
import projects.MyQMLProject.MyFunctions 1.0
 
249
 
 
250
Item {
 
251
    Component.onCompleted: { SystemFunctions.cleanUp(); }
 
252
}
 
253
\endqml
 
254
 
 
255
If the module was imported into a document-local namespace, the JavaScript
 
256
resource identifiers must be prefixed with the namespace qualifier in order
 
257
to be used:
 
258
 
 
259
\qml
 
260
import QtQuick 2.0
 
261
import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
 
262
import org.example.Functions 1.0 as TheirFuncs
 
263
 
 
264
Item {
 
265
    Component.onCompleted: {
 
266
        MyFuncs.SystemFunctions.cleanUp();
 
267
        TheirFuncs.SystemFunctions.shutdown();
 
268
    }
 
269
}
 
270
\endqml
 
271
 
 
272
\section4 Further Information
 
273
 
 
274
For more information about JavaScript resources, please see the documentation
 
275
about \l{qtqml-javascript-resources.html}
 
276
{defining JavaScript resources in QML}, and for more information about how
 
277
to import JavaScript resources, and how imports can be used from within
 
278
JavaScript resources, please see the in-depth documentation about
 
279
\l{qtqml-javascript-imports.html}{importing JavaScript resources in QML}.
 
280
 
 
281
 
 
282
\section1 QML Import Path
 
283
 
 
284
When an \l{qtqml-modules-installedmodules.html}{installed module} is imported,
 
285
the QML engine searches the \e{import path} for a matching module.
 
286
 
 
287
This import path, as returned by QQmlEngine::importPathList(), defines the
 
288
default locations to be searched by the engine. By default, this list contains:
 
289
 
 
290
\list
 
291
\li The directory of the current file
 
292
\li The location specified by QLibraryInfo::Qml2ImportsPath
 
293
\li Paths specified by the \c QML2_IMPORT_PATH environment variable
 
294
\endlist
 
295
 
 
296
Additional import paths can be added through QQmlEngine::addImportPath() or the
 
297
\c QML2_IMPORT_PATH environment variable. When running the
 
298
\l{Prototyping with qmlscene}{qmlscene} tool, you can also use the \c -I option
 
299
to add an import path.
 
300
 
 
301
 
 
302
\section1 Debugging
 
303
 
 
304
The \c QML_IMPORT_TRACE environment variable can be useful for debugging
 
305
when there are problems with finding and loading modules. See
 
306
\l{Debugging module imports} for more information.
 
307
 
 
308
*/