Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 362 insertions, 0 deletions

diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
new file mode 100644
index 0000000000..dbc8806742
--- /dev/null
+++ b/doc/src/declarative/modules.qdoc
@@ -0,0 +1,362 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qdeclarativemodules.html
+\title Modules
+\section1 QML 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
+\o A component defined in another QML file that is not in the same directory
+\o A component defined in a QML file located on a remote server
+\o A \l{QDeclarativeExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory)
+\o 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 doc/src/snippets/declarative/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
+\o Directory structure
+\o Contents of application.qml
+
+\row
+\o
+\code
+MyQMLProject
+    |- MyComponents
+        |- CheckBox.qml
+        |- Slider.qml
+        |- Window.qml
+    |- Main
+        |- application.qml
+\endcode
+
+\o
+\qml
+import "../MyComponents"
+
+Window {
+    Slider {
+        // ...
+    }
+    CheckBox {
+        // ...
+    }
+}
+\endqml
+
+\endtable
+
+Similarly, if the directory resided on a network source, it could
+be imported like this:
+
+\snippet doc/src/snippets/declarative/imports/network-imports.qml imports
+
+A located module can also be imported as a network resource if it has a
+\l{Writing 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{QDeclarativeExtensionPlugin}{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 QDeclarativeEngine::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 doc/src/snippets/declarative/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{Writing 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 QDeclarativeEngine::importPathList(), defines the default
+locations to be searched by the QML engine for a matching module. By default, this list
+contains:
+
+\list
+\o The directory of the current file
+\o The location specified by QLibraryInfo::ImportsPath
+\o Paths specified by the \c QML_IMPORT_PATH environment variable
+\endlist
+
+Additional import paths can be added through QDeclarativeEngine::addImportPath() or the
+\c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, 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{Writing 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{QDeclarativeExtensionPlugin}{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: Writing QML extensions 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 doc/src/snippets/declarative/imports/chart.qml import
+
+For \l{QDeclarativeExtensionPlugin}{QML plugins}, the
+module URI is automatically passed to QDeclarativeExtensionPlugin::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{declarative/cppextensions/plugins}{QML plugins}
+example:
+
+\snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin
+
+Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file},
+the module can be imported from QML, like this:
+
+\snippet doc/src/snippets/declarative/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.
+
+
+
+\target namespaces
+\section1 Namespaces: Using Named Imports
+
+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.
+
+To import a module into a specific namespace, use the \e as keyword:
+
+\snippet doc/src/snippets/declarative/imports/named-imports.qml imports
+
+Types from these modules can then only be used when qualified by the namespace:
+
+\snippet doc/src/snippets/declarative/imports/named-imports.qml imported items
+
+Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:
+
+\snippet doc/src/snippets/declarative/imports/merged-named-imports.qml imports
+
+\section2 JavaScript Files
+
+JavaScript files must always be imported with a named import:
+
+\qml
+import "somescript.js" as MyScript
+
+Item {
+    //...
+    Component.onCompleted: MyScript.doSomething()
+}
+\endqml
+
+The qualifier ("MyScript" in the above example) must be unique within the QML document.
+Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
+
+
+\section1 Writing a qmldir File
+
+A \c 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 installed modules, and
+located modules that are loaded from a network source.
+
+It is defined by a plain text file named "qmldir" that contains one or more lines of the form:
+
+\code
+# <Comment>
+<TypeName> [<InitialVersion>] <File>
+internal <TypeName> <File>
+plugin <Name> [<Path>]
+\endcode
+
+\bold {# <Comment>} lines are used for comments. They are ignored by the QML engine.
+
+\bold {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types.
+<TypeName> is the type being made available, the optional <InitialVersion> is a version
+number, and <File> is the (relative) file name of the QML file defining the type.
+
+Installed files do not need to import the module of which they are a part, as they can refer
+to the other QML files in the module as relative (local) files, but
+if the module is imported from a remote location, those files must nevertheless be listed in
+the \c qmldir file. Types which you do not wish to export to users of your module
+may be marked with the \c internal keyword: \bold {internal <TypeName> <File>}.
+
+The same type can be provided by different files in different versions, in which
+case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0),
+since the \e first name-version match is used and a request for a version of a type
+can be fulfilled by one defined in an earlier version of the module. If a user attempts
+to import a version earlier than the earliest provided or later than the latest provided,
+the import produces a runtime error, but if the user imports a version within the range of versions provided,
+even if no type is specific to that version, no error will occur.
+
+A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file).
+If multiple are provided, only the first in the search path will be used (regardless of whether other versions
+are provided by directories later in the search path).
+
+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.
+
+\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
+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.
+
+<Path> is an optional argument specifying either an absolute path to the directory containing the
+plugin file, or a relative path from the directory containing the \c qmldir file to the directory
+containing the plugin file. 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 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.
+
+
+\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.
+
+
+*/
+/