1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the documentation of the Qt Toolkit.
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
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qdeclarativemodules.html
30 \inqmlmodule QtQuick 2
35 A module is a set of QML content files that can be imported as a unit into a QML
36 application. Modules can be used to organize QML content into independent units,
37 and they can use a versioning mechanism that allows for independent
38 upgradability of the modules.
40 While QML component files within the same directory are automatically accessible
41 within the global namespace, components defined elsewhere must be imported
42 explicitly using the \c import statement to import them as modules. For
43 example, an \c import statement is required to use:
46 \o A component defined in another QML file that is not in the same directory
47 \o A component defined in a QML file located on a remote server
48 \o A \l{QDeclarativeExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory)
49 \o A JavaScript file (note this must be imported using \l {#namespaces}{named imports})
52 An \c import statement includes the module name, and possibly a version number.
53 This can be seen in the snippet commonly found at the top of QML files:
55 \snippet doc/src/snippets/declarative/imports/qtquick-1.0.qml import
57 This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML
58 library itself must be imported to use any of the \l {QML Elements}, as they
59 are not included in the global namespace by default.)
61 The \c Qt module is an \i installed module; it is found in the
62 \l{#import-path}{import path}. There are two types of QML modules:
63 located modules (defined by a URL) and installed modules (defined by a URI).
66 \section1 Located Modules
68 Located modules can reside on the local filesystem or a network resource,
69 and are referred to by a quoted location URL that specifies the filesystem
70 or network URL. They allow any directory with QML content to be imported
71 as a module, whether the directory is on the local filesystem or a remote
74 For example, a QML project may have a separate directory for a set of
75 custom UI components. These components can be accessed by importing the
76 directory using a relative or absolute path, like this:
80 \o Directory structure
81 \o Contents of application.qml
97 import "../MyComponents"
111 Similarly, if the directory resided on a network source, it could
112 be imported like this:
114 \snippet doc/src/snippets/declarative/imports/network-imports.qml imports
116 A located module can also be imported as a network resource if it has a
117 \l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files
118 to be made available by the module. For example, if the \c MyComponents directory
119 contained a \c qmldir file defined like this:
122 Slider 1.0 Slider.qml
123 CheckBox 1.0 CheckBox.qml
124 Window 1.0 Window.qml
127 If the \c MyComponents directory was then hosted as a network resource, it could
128 be imported as a module, like this:
131 import "http://the-server-name.com/MyQMLProject/MyComponents"
143 with an optional "1.0" version specification. Notice the import would fail if
144 a later version was used, as the \c qmldir file specifies that these elements
145 are only available in the 1.0 version.
147 Note that modules imported as a network resource allow only access to components
148 defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins}
153 \section1 Installed Modules
155 Installed modules are modules that are made available through the QML import path,
156 as defined by QDeclarativeEngine::importPathList(), or modules defined within
157 C++ application code. An installed module is referred to by a URI, which allows
158 the module to be imported from QML code without specifying a complete filesystem
159 path or network resource URL.
161 When importing an installed module, an un-quoted URI is
162 used, with a mandatory version number:
164 \snippet doc/src/snippets/declarative/imports/installed-module.qml imports
166 When a module is imported, the QML engine searches the QML import path for a matching
167 module. The root directory of the module must contain a
168 \l{Writing a qmldir file}{qmldir file} that defines the QML files
169 and/or C++ QML extension plugins that are made available to the module.
171 Modules that are installed into the import path translate the URI into
172 directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule
173 must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the
174 QML import path. In addition it is possible to store different versions of the
175 module in subdirectories of its own. For example, a version 2.1 of the
176 module could be located under \c com/nokia/qml/mymodule.2/qmldir or
177 \c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load
178 the module which matches best.
180 The import path, as returned by QDeclarativeEngine::importPathList(), defines the default
181 locations to be searched by the QML engine for a matching module. By default, this list
185 \o The directory of the current file
186 \o The location specified by QLibraryInfo::ImportsPath
187 \o Paths specified by the \c QML_IMPORT_PATH environment variable
190 Additional import paths can be added through QDeclarativeEngine::addImportPath() or the
191 \c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you
192 can also use the \c -I option to add an import path.
195 \section2 Creating Installed Modules
197 As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example}
198 was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents
199 subdirectory could be made available as an installed module by adding a
200 \l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this:
203 Slider 1.0 Slider.qml
204 CheckBox 1.0 CheckBox.qml
205 Window 1.0 Window.qml
208 Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously,
209 a QML file located anywhere on the local filesystem can then import the module as shown below,
210 without referring to the module's absolute filesystem location:
213 import projects.MyQMLProject.MyComponents 1.0
225 Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted
226 as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above
227 QML code would work just the same.
229 Note that modules imported as a network resource allow only access to components
230 defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins}
234 \section2 Creating Installed Modules in C++
236 C++ applications can define installed modules directly within the application using qmlRegisterType().
237 For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial}
238 defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType():
241 qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
244 This allows the application's QML files to use the \c PieChart type by importing the declared
247 \snippet doc/src/snippets/declarative/imports/chart.qml import
249 For \l{QDeclarativeExtensionPlugin}{QML plugins}, the
250 module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). This method
251 can be reimplemented by the developer to register the necessary types for the module. Below is the
252 \c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins}
255 \snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin
257 Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file},
258 the module can be imported from QML, like this:
260 \snippet doc/src/snippets/declarative/imports/timeexample.qml import
262 Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by
263 a module that is imported as a network resource.
268 \section1 Namespaces: Using Named Imports
270 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.
272 To import a module into a specific namespace, use the \i as keyword:
274 \snippet doc/src/snippets/declarative/imports/named-imports.qml imports
276 Types from these modules can then only be used when qualified by the namespace:
278 \snippet doc/src/snippets/declarative/imports/named-imports.qml imported items
280 Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:
282 \snippet doc/src/snippets/declarative/imports/merged-named-imports.qml imports
284 \section2 JavaScript Files
286 JavaScript files must always be imported with a named import:
289 import "somescript.js" as MyScript
293 Component.onCompleted: MyScript.doSomething()
297 The qualifier ("MyScript" in the above example) must be unique within the QML document.
298 Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
301 \section1 Writing a qmldir File
303 A \c qmldir file is a metadata file for a module that maps all type names in
304 the module to versioned QML files. It is required for installed modules, and
305 located modules that are loaded from a network source.
307 It is defined by a plain text file named "qmldir" that contains one or more lines of the form:
311 <TypeName> [<InitialVersion>] <File>
312 internal <TypeName> <File>
313 plugin <Name> [<Path>]
317 \bold {# <Comment>} lines are used for comments. They are ignored by the QML engine.
319 \bold {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types.
320 <TypeName> is the type being made available, the optional <InitialVersion> is a version
321 number, and <File> is the (relative) file name of the QML file defining the type.
323 Installed files do not need to import the module of which they are a part, as they can refer
324 to the other QML files in the module as relative (local) files, but
325 if the module is imported from a remote location, those files must nevertheless be listed in
326 the \c qmldir file. Types which you do not wish to export to users of your module
327 may be marked with the \c internal keyword: \bold {internal <TypeName> <File>}.
329 The same type can be provided by different files in different versions, in which
330 case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0),
331 since the \i first name-version match is used and a request for a version of a type
332 can be fulfilled by one defined in an earlier version of the module. If a user attempts
333 to import a version earlier than the earliest provided or later than the latest provided,
334 the import produces a runtime error, but if the user imports a version within the range of versions provided,
335 even if no type is specific to that version, no error will occur.
337 A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file).
338 If multiple are provided, only the first in the search path will be used (regardless of whether other versions
339 are provided by directories later in the search path).
341 The versioning system ensures that a given QML file will work regardless of the version
342 of installed software, since a versioned import \i only imports types for that version,
343 leaving other identifiers available, even if the actual installed version might otherwise
344 provide those identifiers.
346 \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
347 of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce
348 \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
350 <Path> is an optional argument specifying either an absolute path to the directory containing the
351 plugin file, or a relative path from the directory containing the \c qmldir file to the directory
352 containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir
353 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.
355 \bold {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to
356 the module that can be read by QML tools such as Qt Creator to get information about the
357 types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes
360 Without such a file QML tools may be unable to offer features such as code completion
361 for the types defined in your plugins.
366 The \c QML_IMPORT_TRACE environment variable can be useful for debugging
367 when there are problems with finding and loading modules. See
368 \l{Debugging module imports} for more information.
371 \section1 Writing a qmltypes file
373 QML modules may refer to one or more type information files in their
374 \l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes
375 extension and are read by external tools to gain information about
376 types defined in plugins.
378 As such qmltypes files have no effect on the functionality of a QML module.
379 Their only use is to allow tools such as Qt Creator to provide code completion,
380 error checking and other functionality to users of your module.
382 Any module that uses plugins should also ship a type description file.
384 The best way to create a qmltypes file for your module is to generate it
385 using the \c qmlplugindump tool that is provided with Qt.
388 If your module is in \c /tmp/imports/My/Module, you could run
390 qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
392 to generate type information for your module. Afterwards, add the line
394 typeinfo mymodule.qmltypes
396 to \c /tmp/imports/My/Module/qmldir to register it.
398 While the qmldump tool covers most cases, it does not work if:
400 \o The plugin uses a \l{QDeclarativeCustomParser}. The component that uses
401 the custom parser will not get its members documented.
402 \o The plugin can not be loaded. In particular if you cross-compiled
403 the plugin for a different architecture, qmldump will not be able to
407 In case you have to create a qmltypes file manually or need to adjust
408 an existing one, this is the file format:
411 import QtQuick.tooling 1.1
413 // There always is a single Module object that contains all
414 // Component objects.
416 // A Component object directly corresponds to a type exported
417 // in a plugin with a call to qmlRegisterType.
420 // The name is a unique identifier used to refer to this type.
421 // It is recommended you simply use the C++ type name.
422 name: "QDeclarativeAbstractAnimation"
424 // The name of the prototype Component.
427 // The name of the default property.
428 defaultProperty: "animations"
430 // The name of the type containing attached properties
432 attachedType: "QDeclarativeAnimationAttached"
434 // The list of exports determines how a type can be imported.
435 // Each string has the format "URI/Name version" and matches the
436 // arguments to qmlRegisterType. Usually types are only exported
438 // If the "URI/" part of the string is missing that means the
439 // type should be put into the package defined by the URI the
440 // module was imported with.
441 // For example if this module was imported with 'import Foo 4.8'
442 // the Animation object would be found in the package Foo and
446 "QtQuick/Animation 1.0"
449 // The meta object revisions for the exports specified in 'exports'.
450 // Describes with revisioned properties will be visible in an export.
451 // The list must have exactly the same length as the 'exports' list.
452 // For example the 'animations' propery described below will only be
453 // available through the QtQuick/Animation 1.0 export.
454 exportMetaObjectRevisions: [0, 1]
458 type: "QDeclarativeAbstractAnimation"
459 // defaults to false, whether this property is read only
461 // defaults to false, whether the type of this property was a pointer in C++
463 // defaults to false: whether the type actually is a QDeclarativeListProperty<type>
465 // defaults to 0: the meta object revision that introduced this property
468 Property { name: "loops"; type: "int" }
469 Property { name: "name"; type: "string" }
470 Property { name: "loopsEnum"; type: "Loops" }
480 // Signal and Method work the same way. The inner Parameter
481 // declarations also support the isReadonly, isPointer and isList
482 // attributes which mean the same as for Property
483 Method { name: "restart" }
484 Signal { name: "started"; revision: 2 }
486 name: "runningChanged"
487 Parameter { type: "bool" }
488 Parameter { name: "foo"; type: "bool" }