--- /dev/null
+/****************************************************************************
+**
+** 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{Syntax of a qmldir file}{qmldir file},
+the module can be imported from QML, like this:
+
+\snippet qml/imports/timeexample.qml import
+
+*/
+
--- /dev/null
+/****************************************************************************
+**
+** 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-locatedmodules.html
+\title Located Modules
+\brief Creating and importing located modules
+
+Located modules are modules that reside on the the local file system or a
+network resource and can be referred to by a URL that specifies the file system
+path or network URL. This allows any directory with QML content to be
+\l{qtqml-syntax-imports.html}{imported} as a module, regardless of whether the
+directory is on the local file system or a remote server.
+
+
+\section1 Locally Located Modules
+
+A directory of QML files can immediately be shared as a module without any additional setup or
+configuration.
+
+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 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.
+
+\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 as a module 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
+
+It is not necessary to pass a version number to the \c import statement when importing a locally
+located module. Additionally, the module could be imported with a
+\l{qtqml-syntax-imports.html#namespaced-import}{namespaced import} to qualify any references to the
+types in the module:
+
+\qml
+import "../mycomponents" as MyComponents
+
+MyComponents.DialogBox {
+ // ...
+}
+\endqml
+
+A local file system module may optionally include a \l{qtqml-modules-qmldir.html}{qmldir file}. This
+allows the module to only expose certain QML types to external parties. Additionally, JavaScript
+files in the module directory are not exposed to external parties unless they are declared in a
+qmldir file.
+
+The ability to import a local module using its file system path is convenient for cases such as
+in-application modules and application prototyping, though 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-installedmodules.html}{installed modules} are used instead,
+as an installed module is imported with a unique identifier string rather than a file system path.
+
+
+\section1 Remotely Located Modules
+
+A directory of QML files can also be imported from a remote location if the directory contains a
+\l{qtqml-modules-qmldir.html}{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 1.0 CheckBox.qml
+DialogBox 1.0 DialogBox.qml
+Slider 1.0 Slider.qml
+\endcode
+
+Then, the module 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
+
+In this case the module could optionally be imported with a "1.0" version specification as that is
+the version specified in the \c qmldir file. The import would fail if any later version was used as
+the \c qmldir file specifies that these elements are only available in version 1.0.
+
+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.
+
+\warning When importing modules from a remote server, developers should always be careful to only
+load modules from trusted sources to avoid loading malicious code.
+
+*/
+
--- /dev/null
+/****************************************************************************
+**
+** 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-qmldir.html
+\title Adding Module Metadata with a qmldir File
+\brief How to write a qmldir file for a module
+
+A \e qmldir file is a metadata file for a module that maps all type names in the module to
+versioned QML files. It is required for \l{qtqml-modules-installedmodules.html}{installed modules},
+as well as \l{qtqml-modules-locatedmodules.html}{located modules} that are loaded from a network
+source.
+
+This file is defined by a plain text file named "qmldir" within the module. For
+\l{qtqml-modules-locatedmodules.html}{located modules}, this file should be in the module's root
+directory. For \l{qtqml-modules-installedmodules.html}{installed modules}, the file should be in a
+directory within the module according to the named identifier for the module; see the \l{Installed
+Modules} documentation for more information.
+
+
+\section1 Writing a qmldir file
+
+A \c qmldir file contains one or more lines of the following commands:
+
+\table
+ \header
+ \li Command Syntax
+ \li Usage
+
+ \row
+ \li
+ \code
+<TypeName> [<InitialVersion>] <File>
+ \endcode
+ \li Declares an \l{qtqml-typesystem-objecttypes.html}{object type} to be made available by
+ the module.
+ \list
+ \li \c <TypeName> is the type being made available
+ \li \c <InitialVersion> (optional) is the module version for which the type is to be
+ made available
+ \li \c <File> is the (relative) file name of the QML file that defines the type
+ \endlist
+
+ Example:
+ \code
+MyCustomType 1.0 MyCustomType.qml
+ \endcode
+ \row
+ \li
+ \code
+internal <TypeName> <File>
+ \endcode
+ \li Declares an object type that is in the module but should not be made available to users
+ of the module.
+
+ Example:
+ \code
+internal MyPrivateType MyPrivateType.qml
+ \endcode
+
+ This is necessary if the module may be imported remotely (see \l{Remotely Located
+ Modules} and \l{Remotely Installed Modules}) because if an exported type depends on an
+ non-exported type within the module, the engine must also load the non-exported type.
+
+ \row
+ \li
+ \code
+<Namespace> <InitialVersion> <File>
+ \endcode
+ \li Declares a JavaScript file to be made available by the module. The file will be made
+ available through the specified namespace and verison number.
+
+ Example:
+ \code
+MyScript 1.0 MyScript.js
+ \endcode
+
+ See \l{qtqml-javascript-imports.html}{Importing JavaScript Files In QML Documents} for
+ more information.
+
+ \row
+ \li
+ \code
+plugin <Name> [<Path>]
+ \endcode
+ \li Declares a plugin to be made available by the module.
+
+ \list
+ \li \c <Name> is the plugin library name. This is usually not the same as the file name
+ of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes
+ would produce \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
+ \li \c <Path> (optional) specifes either:
+ \list
+ \li an absolute path to the directory containing the plugin file, or
+ \li a relative path from the directory containing the \c qmldir file to the
+ directory containing the plugin file.
+ \endlist
+
+ By default the engine searches for the plugin library in the directory that contains
+ the \c qmldir file. (The plugin search path can be queried with
+ QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath().)
+ \endlist
+
+ Example:
+ \code
+plugin MyPluginLibrary
+ \endcode
+
+ \row
+ \li
+ \code
+typeinfo <File>
+ \endcode
+ \li Declares a \l{Writing a qmltypes file}{type description file} for the module that can be
+ read by QML tools such as Qt Creator to access information about the types defined by the module's plugins. \c <File> is the (relative) file name of a \c .qmltypes file.
+
+ Example:
+ \code
+typeinfo mymodule.qmltypes
+ \endcode
+
+ Without such a file, QML tools may be unable to offer features such as code completion
+ for the types defined in your plugins.
+
+ \row
+ \li
+ \code
+# <Comment>
+ \endcode
+ \li Declares a comment. These are ignored by the engine.
+
+ Example:
+ \code
+# this is a comment
+ \endcode
+\endtable
+
+For example, suppose a module's \c qmldir file should export a \c MyButton type in version 1.0, a \c
+MyWindow type in version 1.1 and a JavaScript file to a \c MyScript namespace in version 1.1.
+Providing the relevant files are in the same directory as the \c qmldir file, the contents of the \c
+qmldir file would look like this:
+
+\code
+MyButton 1.0 MyButton.qml
+MyWindow 1.1 MyWindow.qml
+MyScript 1.1 myscript.js
+\endcode
+
+If these files were part of an \l{qtqml-modules-installedmodules.html}{installed module} named \c
+com.mycompany.module then the module could be imported and its exported types used as follows:
+
+\qml
+import com.mycompany.module 1.1
+
+MyWindow {
+ function doStuff() {
+ MyScript.doSomething();
+ }
+
+ MyButton {
+ // ...
+ }
+}
+\endqml
+
+Types which are exported for a particular version are still made available if a later version is
+imported: in the above example, the code imports version 1.1 of the module but still has access to
+the \c MyButton type that was exported for version 1.0. However, the reverse is not true: a type
+exported for a particular version cannot be used if an earlier version is imported. If the code
+above imported version 1.0 of the module, it could not have used the \c MyWindow type and \c
+MyScript namespace as these are declared for version 1.1.
+
+A type can be defined by different files in different versions. In this case, later versions (e.g.
+1.2) must precede earlier versions (e.g. 1.0) within the \c qmldir file, since the engine loads the
+first type it finds with a matching name and version.
+
+The versioning system ensures that a given QML file will work regardless of the version
+of installed software, since a versioned import \e only imports types for that version,
+leaving other identifiers available, even if the actual installed version might otherwise
+provide those identifiers.
+
+See \l{Located Modules} and \l{Installed Modules} for more example \c qmldir file content, and see
+\l{examples/qml/cppextensions/plugins} for an example that uses C++ plugins.
+
+
+\section1 Writing a qmltypes file
+
+QML modules may refer to one or more type information files in their
+\c qmldir file. These usually have the \c .qmltypes
+extension and are read by external tools to gain information about
+types defined in plugins.
+
+As such qmltypes files have no effect on the functionality of a QML module.
+Their only use is to allow tools such as Qt Creator to provide code completion,
+error checking and other functionality to users of your module.
+
+Any module that uses plugins should also ship a type description file.
+
+The best way to create a qmltypes file for your module is to generate it
+using the \c qmlplugindump tool that is provided with Qt.
+
+Example:
+If your module is in \c /tmp/imports/My/Module, you could run
+\code
+qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
+\endcode
+to generate type information for your module. Afterwards, add the line
+\code
+typeinfo mymodule.qmltypes
+\endcode
+to \c /tmp/imports/My/Module/qmldir to register it.
+
+While the qmldump tool covers most cases, it does not work if:
+\list
+\li The plugin uses a \l{QQmlCustomParser}. The component that uses
+ the custom parser will not get its members documented.
+\li The plugin can not be loaded. In particular if you cross-compiled
+ the plugin for a different architecture, qmldump will not be able to
+ load it.
+\endlist
+
+In case you have to create a qmltypes file manually or need to adjust
+an existing one, this is the file format:
+
+\qml
+import QtQuick.tooling 1.1
+
+// There always is a single Module object that contains all
+// Component objects.
+Module {
+ // A Component object directly corresponds to a type exported
+ // in a plugin with a call to qmlRegisterType.
+ Component {
+
+ // The name is a unique identifier used to refer to this type.
+ // It is recommended you simply use the C++ type name.
+ name: "QQuickAbstractAnimation"
+
+ // The name of the prototype Component.
+ prototype: "QObject"
+
+ // The name of the default property.
+ defaultProperty: "animations"
+
+ // The name of the type containing attached properties
+ // and methods.
+ attachedType: "QDeclarativeAnimationAttached"
+
+ // The list of exports determines how a type can be imported.
+ // Each string has the format "URI/Name version" and matches the
+ // arguments to qmlRegisterType. Usually types are only exported
+ // once, if at all.
+ // If the "URI/" part of the string is missing that means the
+ // type should be put into the package defined by the URI the
+ // module was imported with.
+ // For example if this module was imported with 'import Foo 4.8'
+ // the Animation object would be found in the package Foo and
+ // QtQuick.
+ exports: [
+ "Animation 4.7",
+ "QtQuick/Animation 1.0"
+ ]
+
+ // The meta object revisions for the exports specified in 'exports'.
+ // Describes with revisioned properties will be visible in an export.
+ // The list must have exactly the same length as the 'exports' list.
+ // For example the 'animations' propery described below will only be
+ // available through the QtQuick/Animation 1.0 export.
+ exportMetaObjectRevisions: [0, 1]
+
+ Property {
+ name: "animations";
+ type: "QQuickAbstractAnimation"
+ // defaults to false, whether this property is read only
+ isReadonly: true
+ // defaults to false, whether the type of this property was a pointer in C++
+ isPointer: true
+ // defaults to false: whether the type actually is a QQmlListProperty<type>
+ isList: true
+ // defaults to 0: the meta object revision that introduced this property
+ revision: 1
+ }
+ Property { name: "loops"; type: "int" }
+ Property { name: "name"; type: "string" }
+ Property { name: "loopsEnum"; type: "Loops" }
+
+ Enum {
+ name: "Loops"
+ values: {
+ "Infinite": -2,
+ "OnceOnly": 1
+ }
+ }
+
+ // Signal and Method work the same way. The inner Parameter
+ // declarations also support the isReadonly, isPointer and isList
+ // attributes which mean the same as for Property
+ Method { name: "restart" }
+ Signal { name: "started"; revision: 2 }
+ Signal {
+ name: "runningChanged"
+ Parameter { type: "bool" }
+ Parameter { name: "foo"; type: "bool" }
+ }
+ }
+}
+\endqml
+
+*/
+
+++ /dev/null
-/****************************************************************************
-**
-** 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 qmllanguage-modules.html
-\title QML Modules
-\brief creating and importing QML modules
-
-\section1 Modules
-
-A module is a set of QML content files that can be imported as a unit into a QML
-application. Modules can be used to organize QML content into independent units,
-and they can use a versioning mechanism that allows for independent
-upgradability of the modules.
-
-While QML component files within the same directory are automatically accessible
-within the global namespace, components defined elsewhere must be imported
-explicitly using the \c import statement to import them as modules. For
-example, an \c import statement is required to use:
-
-\list
-\li A component defined in another QML file that is not in the same directory
-\li A component defined in a QML file located on a remote server
-\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory)
-\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports})
-\endlist
-
-An \c import statement includes the module name, and possibly a version number.
-This can be seen in the snippet commonly found at the top of QML files:
-
-\snippet qml/imports/qtquick-1.0.qml import
-
-This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML
-library itself must be imported to use any of the \l {QML Elements}, as they
-are not included in the global namespace by default.)
-
-The \c Qt module is an \e installed module; it is found in the
-\l{#import-path}{import path}. There are two types of QML modules:
-located modules (defined by a URL) and installed modules (defined by a URI).
-
-
-\section1 Located Modules
-
-Located modules can reside on the local filesystem or a network resource,
-and are referred to by a quoted location URL that specifies the filesystem
-or network URL. They allow any directory with QML content to be imported
-as a module, whether the directory is on the local filesystem or a remote
-server.
-
-For example, a QML project may have a separate directory for a set of
-custom UI components. These components can be accessed by importing the
-directory using a relative or absolute path, like this:
-
-\table
-\row
-\li Directory structure
-\li Contents of application.qml
-
-\row
-\li
-\code
-MyQMLProject
- |- MyComponents
- |- CheckBox.qml
- |- Slider.qml
- |- Window.qml
- |- Main
- |- application.qml
-\endcode
-
-\li
-\qml
-import "../MyComponents"
-
-Window {
- Slider {
- // ...
- }
- CheckBox {
- // ...
- }
-}
-\endqml
-
-\endtable
-
-Similarly, if the directory resided on a network source, it could
-be imported like this:
-
-\snippet qml/imports/network-imports.qml imports
-
-A located module can also be imported as a network resource if it has a
-\l{Syntax of a qmldir file}{qmldir file} in the directory that specifies the QML files
-to be made available by the module. For example, if the \c MyComponents directory
-contained a \c qmldir file defined like this:
-
-\code
-Slider 1.0 Slider.qml
-CheckBox 1.0 CheckBox.qml
-Window 1.0 Window.qml
-\endcode
-
-If the \c MyComponents directory was then hosted as a network resource, it could
-be imported as a module, like this:
-
-\qml
-import "http://the-server-name.com/MyQMLProject/MyComponents"
-
-Window {
- Slider {
- // ...
- }
- CheckBox {
- // ...
- }
-}
-\endqml
-
-with an optional "1.0" version specification. Notice the import would fail if
-a later version was used, as the \c qmldir file specifies that these elements
-are only available in the 1.0 version.
-
-Note that modules imported as a network resource allow only access to components
-defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins}
-are not available.
-
-
-\target import-path
-\section1 Installed Modules
-
-Installed modules are modules that are made available through the QML import path,
-as defined by QQmlEngine::importPathList(), or modules defined within
-C++ application code. An installed module is referred to by a URI, which allows
-the module to be imported from QML code without specifying a complete filesystem
-path or network resource URL.
-
-When importing an installed module, an un-quoted URI is
-used, with a mandatory version number:
-
-\snippet qml/imports/installed-module.qml imports
-
-When a module is imported, the QML engine searches the QML import path for a matching
-module. The root directory of the module must contain a
-\l{Syntax of a qmldir file}{qmldir file} that defines the QML files
-and/or C++ QML extension plugins that are made available to the module.
-
-Modules that are installed into the import path translate the URI into
-directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule
-must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the
-QML import path. In addition it is possible to store different versions of the
-module in subdirectories of its own. For example, a version 2.1 of the
-module could be located under \c com/nokia/qml/mymodule.2/qmldir or
-\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load
-the module which matches best.
-
-The import path, as returned by QQmlEngine::importPathList(), defines the default
-locations to be searched by the QML engine for a matching module. By default, this list
-contains:
-
-\list
-\li The directory of the current file
-\li The location specified by QLibraryInfo::ImportsPath
-\li Paths specified by the \c QML_IMPORT_PATH environment variable
-\endlist
-
-Additional import paths can be added through QQmlEngine::addImportPath() or the
-\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}, you
-can also use the \c -I option to add an import path.
-
-
-\section2 Creating Installed Modules
-
-As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example}
-was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents
-subdirectory could be made available as an installed module by adding a
-\l{Syntax of a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this:
-
-\code
-Slider 1.0 Slider.qml
-CheckBox 1.0 CheckBox.qml
-Window 1.0 Window.qml
-\endcode
-
-Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously,
-a QML file located anywhere on the local filesystem can then import the module as shown below,
-without referring to the module's absolute filesystem location:
-
-\qml
-import projects.MyQMLProject.MyComponents 1.0
-
-Window {
- Slider {
- // ...
- }
- CheckBox {
- // ...
- }
-}
-\endqml
-
-Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted
-as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above
-QML code would work just the same.
-
-Note that modules imported as a network resource allow only access to components
-defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins}
-are not available.
-
-
-\section2 Creating Installed Modules in C++
-
-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{Syntax of a qmldir file}{qmldir file},
-the module can be imported from QML, like this:
-
-\snippet qml/imports/timeexample.qml import
-
-Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by
-a module that is imported as a network resource.
-
-*/
-
****************************************************************************/
/*!
\page qtqml-modules-topic.html
-\title Writing Extension Modules For QML
-\brief Description of how to write extension modules for QML
+\title QML Modules
+\brief Description of how to write modules for QML
-A QML module is an extension to QML which can be imported by clients. A QML
-module can contain QML documents which provide type definitions, JavaScript
-files which provide functionality, and C++ plugins which can provide QML types,
-invokable functions, and other functionality. The module system provided by
-QML allows functionality to be grouped into modules which can be loaded by
-applications which need them, with zero impact upon applications which do not.
+A module is a collection of content files that can be imported as a unit into a QML
+application. Modules can be used to organize QML content into independent groups,
+and they use a versioning mechanism that allows modules to be independently upgraded.
-A QML module must be imported by client QML application developers using an
-\l{qtqml-syntax-imports.html}{Import Statements}. Some imports must be
-qualified (that is, the imported type or file must be given an identifier),
-while others do not.
+Modules may contain QML files, JavaScript files and/or QML plugins written in C++. Grouping files
+into modules enables:
-The Qt Quick module provides a QML module called QtQuick which can be imported
-via the familiar
-\code
-import QtQuick 2.0
-\endcode
+\list
+\li The sharing of common QML types within a project - for example, a group of UI components that
+ are used by different windows
+\li The distribution of QML-based libraries
+\li The modularization of distinct features, so that applications only load the libraries necessary
+ for their individual needs
+\endlist
-import statement.
+A module may contain QML, JavaScript and/or C++ files. To access the types and functionality within
+a module, the module must be imported with an \l{Import Statements}{import} statement.
-QML modules are exposed to the QML type system via a module description file
-called a "qmldir" file.
-\section1 Packaging QML and JavaScript Files
+\section1 Located Modules
-A QML document implicitly defines a QML object type. Clients can create
-reusable components by defining types as QML documents and exposing them
-to the type system directly. QML extension module developers can provide
-QML object types defined in QML documents to clients also.
+A located module is one that is imported by a quoted URL string that refers to the
+local file system path of the module or the network URL location of the module.
-QML extension module developers can also provide functionality in JavaScript
-files. When imported directly, JavaScript files must be imported with a
-qualifier; conversely, when providing a JavaScript file in a QML extension
-module, the module author must provide the qualifier.
+Using this mechanism, any directory of QML files can easily be shared as a module without any
+configuration or installation. Additionally, such modules can be loaded remotely as a network
+resource if it includes a qmldir file with the necessary metadata.
+
+See \l{qtqml-modules-locatedmodules.html}{Located Modules} for more information.
+
+
+\section1 Installed Modules
+
+An installed module is one that is imported by a URI in the form of a dotted identifier string - for
+example, "com.mycompany.mymodule" - that uniquely identifies the module to the QML engine. This
+allows a module to be imported by an identifier rather than a file system path.
+
+To enable the engine to find an installed module, the module should be available in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
+
+See \l{qtqml-modules-installedmodules.html}{Installed Modules} for more information.
+
+
+\section1 Adding Module Metadata with a qmldir File
+
+A qmldir file is a plain text file that describes a module's metadata and contents. This file and
+the associated module contents (QML documents, JavaScript files, and C++ plugins) must be placed
+somewhere into the \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
+
+This is required for a module if it is to be imported by URI or as a network resource. It is also
+necessary for exporting JavaScript files and object types defined in C++.
+
+See \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir File} for more information.
-See the documentation about \l{qtqml-javascript-topic.html}
-{integrating QML and JavaScript} for more information about what types of
-functionality can be implemented in JavaScript.
\section1 Providing Types And Functionality In A C++ Plugin
register any types that the plugin provides, but must not do anything else
(for example, instantiating QObjects is not allowed).
-\section1 Syntax Of A qmldir File
-
-The standard way to expose a QML extension module to the QML type system is to
-write a \c qmldir file which describes to the QML engine what the module
-contains. The qmldir file and the associated content (QML documents,
-JavaScript files, and C++ plugins) must be placed somewhere into the
-\l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
+See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.
*/
\li \l{qtqml-modules-topic.html}{QML Modules}
\list
- \li \l{qtqml-modules-topic.html#syntax-of-a-qmldir-file}{Packaging QML and JavaScript Files}
- \li \l{qtqml-modules-cppplugins.html#creating-a-plugin}{Providing Types and Functionality in a C++ Plugin}
- \li \l{qtqml-modules-qmldir.html}{Syntax of a qmldir File}
+ \li \l{qtqml-modules-locatedmodules.html}{Located Modules}
+ \li \l{qtqml-modules-installedmodules.html}{Installed Modules}
+ \li \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir file}
+ \li \l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin}
\endlist
\li \l{qtqml-documents-topic.html}{QML Documents}
\note Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for \l{qtqml-documents-networktransparency.html}{Network Transparency} in QML documents.
-\section2 Namespace Imports
+\section1 Debugging
+
+The \c QML_IMPORT_TRACE environment variable can be useful for debugging
+when there are problems with finding and loading modules. See
+\l{Debugging module imports} for more information.
+
+
+\section1 QML Import Path
+
+When an \l{qtqml-modules-installedmodules.html}{installed module} is imported, the QML engine
+searches the \e{import path} for a matching module.
+
+This import path, as returned by QQmlEngine::importPathList(), defines the default
+locations to be searched by the engine. By default, this list contains:
+
+\list
+\li The directory of the current file
+\li The location specified by QLibraryInfo::ImportsPath
+\li Paths specified by the \c QML_IMPORT_PATH environment variable
+\endlist
+
+Additional import paths can be added through QQmlEngine::addImportPath() or the
+\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}{qmlscene}
+tool, you can also use the \c -I option to add an import path.
+
+
+
+\section1 Namespaced Imports
-\section2 Relative Directory Imports
+\section1 Relative Directory Imports
-\section2 JavaScript File Imports
+\section1 JavaScript File Imports
JavaScript files must always be imported with a named import:
\endqml
-\section2 Version Specification
+\section1 Version Specification
-\section2 Import Qualifier
+\section1 Import Qualifier
*/
projects / platform / upstream / qtdeclarative.git / commitdiff