Merge remote-tracking branch 'qt/4.8'
[qt:qt.git] / doc / src / declarative / modules.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
6 **
7 ** This file is part of the documentation of the Qt Toolkit.
8 **
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
14 ** this file.
15 **
16 ** Other Usage
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
19 ** and Nokia.
20 **
21 **
22 **
23 **
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \page qdeclarativemodules.html
30 \title Modules
31 \section1 QML Modules
32
33
34 A module is a set of QML content files that can be imported as a unit into a QML
35 application. Modules can be used to organize QML content into independent units,
36 and they can use a versioning mechanism that allows for independent
37 upgradability of the modules.
38
39 While QML component files within the same directory are automatically accessible
40 within the global namespace, components defined elsewhere must be imported
41 explicitly using the \c import statement to import them as modules. For
42 example, an \c import statement is required to use:
43
44 \list
45 \o A component defined in another QML file that is not in the same directory
46 \o A component defined in a QML file located on a remote server
47 \o A \l{QDeclarativeExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory)
48 \o A JavaScript file (note this must be imported using \l {#namespaces}{named imports})
49 \endlist
50
51 An \c import statement includes the module name, and possibly a version number.
52 This can be seen in the snippet commonly found at the top of QML files:
53
54 \snippet doc/src/snippets/declarative/imports/qtquick-1.0.qml import
55
56 This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML
57 library itself must be imported to use any of the \l {QML Elements}, as they
58 are not included in the global namespace by default.)
59
60 The \c Qt module is an \e installed module; it is found in the
61 \l{#import-path}{import path}. There are two types of QML modules:
62 located modules (defined by a URL) and installed modules (defined by a URI).
63
64
65 \section1 Located Modules
66
67 Located modules can reside on the local filesystem or a network resource,
68 and are referred to by a quoted location URL that specifies the filesystem
69 or network URL. They allow any directory with QML content to be imported
70 as a module, whether the directory is on the local filesystem or a remote
71 server.
72
73 For example, a QML project may have a separate directory for a set of
74 custom UI components. These components can be accessed by importing the
75 directory using a relative or absolute path, like this:
76
77 \table
78 \row
79 \o Directory structure
80 \o Contents of application.qml
81
82 \row
83 \o
84 \code
85 MyQMLProject
86     |- MyComponents
87         |- CheckBox.qml
88         |- Slider.qml
89         |- Window.qml
90     |- Main
91         |- application.qml
92 \endcode
93
94 \o
95 \qml
96 import "../MyComponents"
97
98 Window {
99     Slider {
100         // ...
101     }
102     CheckBox {
103         // ...
104     }
105 }
106 \endqml
107
108 \endtable
109
110 Similarly, if the directory resided on a network source, it could
111 be imported like this:
112
113 \snippet doc/src/snippets/declarative/imports/network-imports.qml imports
114
115 A located module can also be imported as a network resource if it has a
116 \l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files
117 to be made available by the module. For example, if the \c MyComponents directory
118 contained a \c qmldir file defined like this:
119
120 \code
121 Slider 1.0 Slider.qml
122 CheckBox 1.0 CheckBox.qml
123 Window 1.0 Window.qml
124 \endcode
125
126 If the \c MyComponents directory was then hosted as a network resource, it could
127 be imported as a module, like this:
128
129 \qml
130 import "http://the-server-name.com/MyQMLProject/MyComponents"
131
132 Window {
133     Slider {
134         // ...
135     }
136     CheckBox {
137         // ...
138     }
139 }
140 \endqml
141
142 with an optional "1.0" version specification. Notice the import would fail if
143 a later version was used, as the \c qmldir file specifies that these elements
144 are only available in the 1.0 version.
145
146 Note that modules imported as a network resource allow only access to components
147 defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins}
148 are not available.
149
150
151 \target import-path
152 \section1 Installed Modules
153
154 Installed modules are modules that are made available through the QML import path,
155 as defined by QDeclarativeEngine::importPathList(), or modules defined within
156 C++ application code. An installed module is referred to by a URI, which allows
157 the module to be imported from QML code without specifying a complete filesystem
158 path or network resource URL.
159
160 When importing an installed module, an un-quoted URI is
161 used, with a mandatory version number:
162
163 \snippet doc/src/snippets/declarative/imports/installed-module.qml imports
164
165 When a module is imported, the QML engine searches the QML import path for a matching
166 module. The root directory of the module must contain a
167 \l{Writing a qmldir file}{qmldir file} that defines the QML files
168 and/or C++ QML extension plugins that are made available to the module.
169
170 Modules that are installed into the import path translate the URI into
171 directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule
172 must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the
173 QML import path. In addition it is possible to store different versions of the
174 module in subdirectories of its own. For example, a version 2.1 of the
175 module could be located under \c com/nokia/qml/mymodule.2/qmldir or
176 \c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load
177 the module which matches best.
178
179 The import path, as returned by QDeclarativeEngine::importPathList(), defines the default
180 locations to be searched by the QML engine for a matching module. By default, this list
181 contains:
182
183 \list
184 \o The directory of the current file
185 \o The location specified by QLibraryInfo::ImportsPath
186 \o Paths specified by the \c QML_IMPORT_PATH environment variable
187 \endlist
188
189 Additional import paths can be added through QDeclarativeEngine::addImportPath() or the
190 \c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you
191 can also use the \c -I option to add an import path.
192
193
194 \section2 Creating Installed Modules
195
196 As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example}
197 was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents
198 subdirectory could be made available as an installed module by adding a
199 \l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this:
200
201 \code
202 Slider 1.0 Slider.qml
203 CheckBox 1.0 CheckBox.qml
204 Window 1.0 Window.qml
205 \endcode
206
207 Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously,
208 a QML file located anywhere on the local filesystem can then import the module as shown below,
209 without referring to the module's absolute filesystem location:
210
211 \qml
212 import projects.MyQMLProject.MyComponents 1.0
213
214 Window {
215     Slider {
216         // ...
217     }
218     CheckBox {
219         // ...
220     }
221 }
222 \endqml
223
224 Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted
225 as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above
226 QML code would work just the same.
227
228 Note that modules imported as a network resource allow only access to components
229 defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins}
230 are not available.
231
232
233 \section2 Creating Installed Modules in C++
234
235 C++ applications can define installed modules directly within the application using qmlRegisterType().
236 For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial}
237 defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType():
238
239 \code
240 qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
241 \endcode
242
243 This allows the application's QML files to use the \c PieChart type by importing the declared
244 \c Charts module:
245
246 \snippet doc/src/snippets/declarative/imports/chart.qml import
247
248 For \l{QDeclarativeExtensionPlugin}{QML plugins}, the
249 module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). This method
250 can be reimplemented by the developer to register the necessary types for the module. Below is the
251 \c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins}
252 example:
253
254 \snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin
255
256 Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file},
257 the module can be imported from QML, like this:
258
259 \snippet doc/src/snippets/declarative/imports/timeexample.qml import
260
261 Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by
262 a module that is imported as a network resource.
263
264
265
266 \target namespaces
267 \section1 Namespaces: Using Named Imports
268
269 By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability.
270
271 To import a module into a specific namespace, use the \e as keyword:
272
273 \snippet doc/src/snippets/declarative/imports/named-imports.qml imports
274
275 Types from these modules can then only be used when qualified by the namespace:
276
277 \snippet doc/src/snippets/declarative/imports/named-imports.qml imported items
278
279 Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:
280
281 \snippet doc/src/snippets/declarative/imports/merged-named-imports.qml imports
282
283 \section2 JavaScript Files
284
285 JavaScript files must always be imported with a named import:
286
287 \qml
288 import "somescript.js" as MyScript
289
290 Item {
291     //...
292     Component.onCompleted: MyScript.doSomething()
293 }
294 \endqml
295
296 The qualifier ("MyScript" in the above example) must be unique within the QML document.
297 Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
298
299
300 \section1 Writing a qmldir File
301
302 A \c qmldir file is a metadata file for a module that maps all type names in
303 the module to versioned QML files. It is required for installed modules, and
304 located modules that are loaded from a network source.
305
306 It is defined by a plain text file named "qmldir" that contains one or more lines of the form:
307
308 \code
309 # <Comment>
310 <TypeName> [<InitialVersion>] <File>
311 internal <TypeName> <File>
312 plugin <Name> [<Path>]
313 typeinfo <File>
314 \endcode
315
316 \bold {# <Comment>} lines are used for comments. They are ignored by the QML engine.
317
318 \bold {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types.
319 <TypeName> is the type being made available, the optional <InitialVersion> is a version
320 number, and <File> is the (relative) file name of the QML file defining the type.
321
322 Installed files do not need to import the module of which they are a part, as they can refer
323 to the other QML files in the module as relative (local) files, but
324 if the module is imported from a remote location, those files must nevertheless be listed in
325 the \c qmldir file. Types which you do not wish to export to users of your module
326 may be marked with the \c internal keyword: \bold {internal <TypeName> <File>}.
327
328 The same type can be provided by different files in different versions, in which
329 case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0),
330 since the \e first name-version match is used and a request for a version of a type
331 can be fulfilled by one defined in an earlier version of the module. If a user attempts
332 to import a version earlier than the earliest provided or later than the latest provided,
333 the import produces a runtime error, but if the user imports a version within the range of versions provided,
334 even if no type is specific to that version, no error will occur.
335
336 A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file).
337 If multiple are provided, only the first in the search path will be used (regardless of whether other versions
338 are provided by directories later in the search path).
339
340 The versioning system ensures that a given QML file will work regardless of the version
341 of installed software, since a versioned import \e only imports types for that version,
342 leaving other identifiers available, even if the actual installed version might otherwise
343 provide those identifiers.
344
345 \bold {plugin <Name> [<Path>]} lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library.  It is usually not the same as the file name
346 of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce
347 \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
348
349 <Path> is an optional argument specifying either an absolute path to the directory containing the
350 plugin file, or a relative path from the directory containing the \c qmldir file to the directory
351 containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir
352 file. The plugin search path can be queried with QDeclarativeEngine::pluginPathList() and modified using QDeclarativeEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path.
353
354 \bold {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to
355 the module that can be read by QML tools such as Qt Creator to get information about the
356 types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes
357 file.
358
359 Without such a file QML tools may be unable to offer features such as code completion
360 for the types defined in your plugins.
361
362
363 \section1 Debugging
364
365 The \c QML_IMPORT_TRACE environment variable can be useful for debugging
366 when there are problems with finding and loading modules. See
367 \l{Debugging module imports} for more information.
368
369
370 \section1 Writing a qmltypes file
371
372 QML modules may refer to one or more type information files in their
373 \l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes
374 extension and are read by external tools to gain information about
375 types defined in plugins.
376
377 As such qmltypes files have no effect on the functionality of a QML module.
378 Their only use is to allow tools such as Qt Creator to provide code completion,
379 error checking and other functionality to users of your module.
380
381 Any module that uses plugins should also ship a type description file.
382
383 The best way to create a qmltypes file for your module is to generate it
384 using the \c qmlplugindump tool that is provided with Qt.
385
386 Example:
387 If your module is in \c /tmp/imports/My/Module, you could run
388 \code
389 qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
390 \endcode
391 to generate type information for your module. Afterwards, add the line
392 \code
393 typeinfo mymodule.qmltypes
394 \endcode
395 to \c /tmp/imports/My/Module/qmldir to register it.
396
397 While the qmldump tool covers most cases, it does not work if:
398 \list
399 \o The plugin uses a \l{QDeclarativeCustomParser}. The component that uses
400    the custom parser will not get its members documented.
401 \o The plugin can not be loaded. In particular if you cross-compiled
402    the plugin for a different architecture, qmldump will not be able to
403    load it.
404 \endlist
405
406 In case you have to create a qmltypes file manually or need to adjust
407 an existing one, this is the file format:
408
409 \qml
410 import QtQuick.tooling 1.0
411
412 // There always is a single Module object that contains all
413 // Component objects.
414 Module {
415     // A Component object directly corresponds to a type exported
416     // in a plugin with a call to qmlRegisterType.
417     Component {
418
419         // The name is a unique identifier used to refer to this type.
420         // It is recommended you simply use the C++ type name.
421         name: "QDeclarativeAbstractAnimation"
422
423         // The name of the prototype Component.
424         prototype: "QObject"
425
426         // The name of the default property.
427         defaultProperty: "animations"
428
429         // The name of the type containing attached properties
430         // and methods.
431         attachedType: "QDeclarativeAnimationAttached"
432
433         // The list of exports determines how a type can be imported.
434         // Each string has the format "URI/Name version" and matches the
435         // arguments to qmlRegisterType. Usually types are only exported
436         // once, if at all.
437         // If the "URI/" part of the string is missing that means the
438         // type should be put into the package defined by the URI the
439         // module was imported with.
440         // For example if this module was imported with 'import Foo 4.8'
441         // the Animation object would be found in the package Foo and
442         // QtQuick.
443         exports: [
444             "Animation 4.7",
445             "QtQuick/Animation 1.0"
446         ]
447
448         Property {
449             name: "animations";
450             type: "QDeclarativeAbstractAnimation"
451             // defaults to false, whether this property is read only
452             isReadonly: true
453             // defaults to false, whether the type of this property was a pointer in C++
454             isPointer: true
455             // defaults to false: whether the type actually is a QDeclarativeListProperty<type>
456             isList: true
457         }
458         Property { name: "loops"; type: "int" }
459         Property { name: "name"; type: "string" }
460         Property { name: "loopsEnum"; type: "Loops" }
461
462         Enum {
463             name: "Loops"
464             values: {
465                 "Infinite": -2,
466                 "OnceOnly": 1
467             }
468         }
469
470         // Signal and Method work the same way. The inner Parameter
471         // declarations also support the isReadonly, isPointer and isList
472         // attributes which mean the same as for Property
473         Method { name: "restart" }
474         Signal { name: "started" }
475         Signal {
476             name: "runningChanged"
477             Parameter { type: "bool" }
478             Parameter { name: "foo"; type: "bool" }
479         }
480     }
481 }
482 \endqml
483
484 */
485 /