Rest of 44ab46a6c5dcfb14395baf173a11179839003c4c

1 files changed, 71 insertions, 89 deletions

diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 60cf2a4..7c67f60 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -1,123 +1,105 @@
 /*! 
-\page qmlmodules.html
 \target qmlmodules
-\title Modules of Components
-
-A \bold module is a collection of \l Components.
-
-To use a module, include the following statement at the begining
-of your QML:
-
-\code
-import "path"
-\endcode
-
-This allows all components defined in the directory \c path to be used in
-the component where this statement appears.
-
-Currently, \c path may only be a directory relative to the directory containing
-the component issuing the import.
-
-The import statement cannot be used by remote content.
-*/
-
-/*
-
-Ideas for full module support....
-
-See QT-558.
-
-* Modularity within applications
-
-This is the currently-supported mechanism.
+\page qmlmodules.html
+\title Modules
 
-By using the "import" statement, a subdirectory of types can be added to the
-empty namespace. Alternatively, a type in a subdirectory can be referenced
-explicitly.
+A \bold module is a collection of QML types.
 
-So, given these files:
+To use types from a module it must be imported using the \c import statement. Successive
+import statements override earlier import statements.
 
-    ./SubModule1/Type1.qml
-    ./SubModule2/Type1.qml
+\section1 Importing Built-in Types
 
-This is valid QML:
+To use built-in types, you must import the module defining them.
+For example, to use types from Qt, import it:
 
-    import "SubModule1"
-    Type1 { ... }
-    SubModule2.Type1 { ... }
+\code
+import Qt 4.6
+\endcode
 
+This makes available all types in Qt that were available in Qt 4.6, regardless of the
+actual version of Qt executing the QML.
 
-* System-installed modules (dependencies)
+Modules can be compiled-in (such as the Qt module), or they can be
+defined in QML files.
 
-To use system-installed modules, the dependency must be explicitly stated
-using the "require" statement. Types in required modules must still be
-explicitly qualified. Dependencies cannot be added to the empty namespace.
+\section1 Importing QML Files
 
-    QMLPATH=/opt/Nokia/qml:/usr/share/lib/qml
-    /opt/Nokia/qml/Module1/Type1.qml
-    /usr/share/lib/qml/Module1/Type1.qml
+To import types defined in QML files in directories relative to the file importing them,
+a quoted import directory is used:
 
-    require "Module1"
-    Module1.Type1 { ... }
+\code
+import "path"
+\endcode
 
+This allows all components defined in the directory \c path to be used in
+the component where this statement appears.
 
-* Grouping of components within application modules
+To import types defined in QML files that are installed somewhere on the system,
+an unquoted URI is used:
 
-Sub-sub directories allow further grouping of types.
+\code
+import com.nokia.CoolStuff 1.0
+\endcode
 
-    ./SubModule1/Group1/*.qml
-    ./SubModule1/Group2/*.qml
+This will access file in the directory \c com/nokia/CoolStuff/, found in some
+location determined outside QML. See QmlEngine::addImportPath() and the \c -L option
+to the \l {qmlviewer}{viewer} application.
 
-    SubModule1.Group1.Type1 { ... }
-    SubModule1.Group1.Type2 { ... }
-    SubModule1.Group2.Type1 { ... }
-    SubModule1.Group2.Type2 { ... }
+The directory of installed files must include a file \c qmldir which specifies the
+mapping from all type names to versioned QML files. It is a list of lines of the form:
 
-    import "SubModule1/Group1"
-    Type1 { ... }
+\code
+# <Comment>
+<TypeName> <VersionRange> <File>
+\endcode
 
-    import "SubModule1"
-    Group1.Type1 { ... }
+<TypeName> is the type being made available; <VersionRange> is either a single version
+number like \c 4.0 or a range of minor versions like \c 4.0-2; <File> is the (relative)
+file name of the QML file defining the type.
+The same type can be provided by different files in different versions.
+If a type is in multiple major versions, it should be listed on a separate line.
 
+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.
 
-* Grouping of components within system-installed modules
+Installed files \e must be referred to by version information described above,
+local files \e may have it.
 
-System-installed types may also be grouped into types. The hierarchy is a
-global namespace, so such grouping is recommended to reduce clashes.
+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
+use those identifiers.
 
-    /opt/Nokia/qml/Module1/Group1/*.qml
-    /opt/Nokia/qml/Module1/Group2/*.qml
+\section1 Namespaces - Named Imports
 
-    require "Module1"
-    Module1.Group1.Type1 { ... }
-    Module1.Group1.Type2 { ... }
-    Module1.Group2.Type1 { ... }
-    Module1.Group2.Type2 { ... }
+When importing content it by default imports types 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.
 
-    require "Module1/Group1"
-    Group1.Type1 { ... }
+To import a module into a namespace:
 
-    // Alternative syntax
-    /opt/qml/com/nokia/qml/Module1/Group1/*.qml
-    require "com.nokia.qml.Module1.Group1"
-    Group1.Type1 { ... }
+\code
+import Qt 4.6 as TheQtLibrary
+\endcode
 
+Types from Qt 4.6 may then be used, but only by qualifying them with the namespace:
 
-* Private sub-components
+\code
+TheQtLibrary.Rectangle { ... }
+\endcode
 
-Directories begining with _ cannot be referenced except by types in the
-directory immediately containing it.
+Multiple modules can be imported into the same namespace in the same way that multiple
+modules can be imported into the global namespace:
 
-    /opt/Nokia/qml/Module1/_private/Type1.qml
-    ./SubModule1/_private/Type1.qml
+\code
+import Qt 4.6 as Nokia
+import Ovi 1.0 as Nokia
+\endcode
+*/
 
-    SubModule1._private.Type1 { ... } // Not allowed
-    import "SubModule1._private" // Not allowed
-    require "SubModule1._private" // Not allowed
-    require "SubModule1"
-    Module1._private.Type1 { ... } // Not allowed
+/*
 
-    import "_private" // allowed
-    Type1 { ... }
+See original requirement QT-558.
 
 */