1 files changed, 308 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc
new file mode 100644
index 0000000000..1496a1e5c9
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc
@@ -0,0 +1,308 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-syntax-imports.html
+\title Import Statements
+\brief Description of import statements in QML
+
+\section1 Syntax of an Import Statement
+
+An import statement allows clients to tell the engine which modules, JavaScript
+resources and component directories are used within a QML document.  The types
+which may be used within a document depends on which modules, resources and
+directories are imported by the document.
+
+\section2 Import Types
+
+There are three different types of imports.  Each import type has a slightly
+different syntax, and different semantics apply to different import types.
+
+\section3 Module (Namespace) Imports
+
+The most common type of import is a module import.  Clients can import
+\l{qtqml-modules-identifiedmodules.html}{QML modules} which register QML object
+types and JavaScript resources into a given namespace.
+
+The generic form of a module import is as follows:
+\code
+import <ModuleIdentifier> <Version.Number> [as <Qualifier>]
+\endcode
+
+\list
+  \li The \c <ModuleIdentifier> is an identifier specified in dotted URI
+      notation, which uniquely identifies the type namespace provided by the
+      module.
+  \li The \c <Version.Number> is a version of the form
+      \c {MajorVersion.MinorVersion} which specifies which definitions of
+      various object types and JavaScript resources will be made available due
+      to the import.
+  \li The \c <Qualifier> is an optional local namespace identifier into which
+      the object types and JavaScript resources provided by the module will be
+      installed, if given.  If omitted, the object types and JavaScript
+      resources provided by the module will be installed into the global
+      namespace.
+\endlist
+
+An example of an unqualified module import is as follows:
+\code
+import QtQuick 2.0
+\endcode
+
+This import allows the use of all of the types provided by the \c QtQuick
+module without needing to specify a qualifier.  For example, the client code to
+create a rectangle is as follows:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 200
+    height: 100
+    color: "red"
+}
+\endqml
+
+An example of a qualified module import is as follows:
+\code
+import QtQuick 2.0 as Quick
+\endcode
+
+This import allows multiple modules which provide conflicting type names to be
+imported at the same time, however since each usage of a type provided by a
+module which was imported into a qualified namespace must be preceded by the
+qualifier, the conflict is able to be resolved unambiguously by the QML engine.
+
+An example of client code which creates a rectangle after using a qualified
+module import is as follows:
+
+\qml
+import QtQuick 2.0 as Quick
+
+Quick.Rectangle {
+    width: 200
+    height: 100
+    color: "red"
+}
+\endqml
+
+For more information about qualified imports, see the upcoming section on
+\l{Importing Into A Qualified Local Namespace}.
+
+Note that if a QML document does not import a module which provides a
+particular QML object type, but attempts to use that object type anyway,
+an error will occur.  For example, the following QML document does not
+import \c QtQuick and thus attempting to use the \c Rectangle type will fail:
+
+\qml
+Rectangle {
+    width: 200
+    height: 100
+    color: "red"
+}
+\endqml
+
+In this case, the engine will emit an error and refuse to load the file.
+
+\section4 Non-module Namespace Imports
+
+Types can also be registered into namespaces directly via the various
+registration functions in C++ (such as qmlRegisterType()).  The types which
+have been registered into a namespace in this way may be imported by importing
+the namespace, as if the namespace was a module identifier.
+
+This is most common in client applications which define their own QML object
+types in C++ and register them with the QML type system manually.
+
+\section4 Importing into a Qualified Local Namespace
+
+The \c import statement may optionally use the \c as keyword to specify that
+the types should be imported into a particular document-local namespace. If a
+namespace is specified, then any references to the types made available by the
+import must be prefixed by the local namespace qualifier.
+
+Below, the \c QtQuick module is imported into the namespace "CoreItems". Now, any
+references to types from the \c QtQuick module must be prefixed with the
+\c CoreItems name:
+
+\qml
+import QtQuick 2.0 as CoreItems
+
+CoreItems.Rectangle {
+    width: 100; height: 100
+
+    CoreItems.Text { text: "Hello, world!" }
+
+    // WRONG! No namespace prefix - the Text type won't be found
+    Text { text: "Hello, world!" }
+}
+\endqml
+
+A namespace acts as an identifier for a module within the scope of the file.
+The namespace does not become an attribute of the root object that can be
+referred to externally as can be done with properties, signals and methods.
+
+The namespaced import is useful if there is a requirement to use two QML types
+that have the same name but are located in different modules. In this case the
+two modules can be imported into different namespaces to ensure the code is
+referring to the correct type:
+
+\qml
+import QtQuick 2.0 as CoreItems
+import "../textwidgets" as MyModule
+
+CoreItems.Rectangle {
+    width: 100; height: 100
+
+    MyModule.Text { text: "Hello from my custom text item!" }
+    CoreItems.Text { text: "Hello from Qt Quick!" }
+}
+\endqml
+
+Note that multiple modules can be imported into the same namespace in the same
+way that multiple modules can be imported into the global namespace. For example:
+
+\snippet qml/imports/merged-named-imports.qml imports
+
+\section3 Directory Imports
+
+A directory which contains QML documents may also be imported directly in a
+QML document.  This provides a simple way for QML types to be segmented into
+reusable groupings: directories on the filesystem.
+
+The generic form of a directory import is as follows:
+\qml
+import "<DirectoryPath>" [as <Qualifier>]
+\endqml
+
+\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.  If the directory is remote, it must
+contain a \l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
+{directory import listing qmldir file} as the QML engine cannot determine
+the contents of a remote directory if that \c qmldir file does not exist.
+
+Similar semantics for the \c <Qualifier> apply to directory imports as for
+module imports; for more information on the topic, please see the previous
+section about \l{Importing into a Qualified Local Namespace}.
+
+For more information about directory imports, please see the in-depth
+documentation about \l{qtqml-syntax-directoryimports.html}{directory imports}.
+
+\section3 JavaScript Resource Imports
+
+JavaScript resources may be imported directly in a QML document.  Every
+JavaScript resource must have an identifier by which it is accessed.
+
+The generic form of a JavaScript resource import is as follows:
+\code
+import "<JavaScriptFile>" as <Identifier>
+\endcode
+
+Note that the \c <Identifier> must be unique within a QML document, unlike the
+local namespace qualifier which can be applied to module imports.
+
+\section4 JavaScript Resources from Modules
+
+Javascript files can be provided by modules, by adding identifier
+definitions to the \c qmldir file which specifies the module.
+
+For example, if the \c projects.MyQMLProject.MyFunctions module is specified
+with the following \c qmldir file, and installed into the QML import path:
+\code
+module projects.MyQMLProject.MyFunctions
+SystemFunctions 1.0 SystemFunctions.js
+UserFunctions 1.0 UserFunctions.js
+\endcode
+
+a client application is able to import the JavaScript resources declared in the
+module by importing the module and using the identifier associated with a
+declared resource:
+
+\qml
+import QtQuick 2.0
+import projects.MyQMLProject.MyFunctions 1.0
+
+Item {
+    Component.onCompleted: { SystemFunctions.cleanUp(); }
+}
+\endqml
+
+If the module was imported into a document-local namespace, the JavaScript
+resource identifiers must be prefixed with the namespace qualifier in order
+to be used:
+
+\qml
+import QtQuick 2.0
+import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
+import org.example.Functions 1.0 as TheirFuncs
+
+Item {
+    Component.onCompleted: {
+        MyFuncs.SystemFunctions.cleanUp();
+        TheirFuncs.SystemFunctions.shutdown();
+    }
+}
+\endqml
+
+\section4 Further Information
+
+For more information about JavaScript resources, please see the documentation
+about \l{qtqml-javascript-resources.html}
+{defining JavaScript resources in QML}, and for more information about how
+to import JavaScript resources, and how imports can be used from within
+JavaScript resources, please see the in-depth documentation about
+\l{qtqml-javascript-imports.html}{importing JavaScript resources in QML}.
+
+
+\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::Qml2ImportsPath
+\li Paths specified by the \c QML2_IMPORT_PATH environment variable
+\endlist
+
+Additional import paths can be added through QQmlEngine::addImportPath() or the
+\c QML2_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 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.
+
+*/