Merge commit 'refs/merge-requests/1108' of git://gitorious.org/qt/qt into merge-requests/1108

Conflicts:
	doc/src/declarative/basictypes.qdoc

2 files changed, 208 insertions, 164 deletions

diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc
index 02cd31a..cd10e2b 100644
--- a/doc/src/declarative/basictypes.qdoc
+++ b/doc/src/declarative/basictypes.qdoc
@@ -405,8 +405,6 @@
 
     \qml
     Item {
-        property variant values: [ 10, 20, 'abc', 'xyz' ]
-
         property list<Rectangle> rects: [
             Rectangle { width: 100; height: 100},
             Rectangle { width: 200; height: 200}
@@ -414,136 +412,124 @@
     }
     \endqml
 
-    A \c variant list can contain values of any of the \l {QML Basic Types}{basic QML types}
-    such as numbers, strings, etc. while a \c list<Type> list can only contain values
-    that match (or are derived from) the specified \c Type.
+    A list property can only contain values that match (or are derived from) the
+    specified \c Type.
 
-    A list property can be cleared by setting it to an empty list:
+    While the \c rects property can be reassigned to a different list value (including
+    an empty list), its individual values cannot be modified. See the \l variant type
+    documentation for details.
 
-    \qml
-    Item {
-        children: []
-    }
-    \endqml
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype variant
+    \ingroup qmlbasictypes
 
-    A list property cannot be modified in any other way. Items cannot be dynamically added to
-    or removed from the list through JavaScript operations; any \c push() operations on the
-    list only modify a \e copy of the list and not the actual list. (These current limitations
-    are due to restrictions on \l {Property Binding} where lists are involved.)
+    \brief A variant type is a generic property type.
 
-    You can, however, modify a copy of the list and then reassign the property to the modified
-    value. Other options are to create an array object from within a \c .js JavaScript file,
-    or implement a custom list element in C++. Here is a QML element that modifies the list in a
-    JavaScript file:
+    A variant is a generic property type. A variant type property can hold
+    any of the \l {QML Basic Types}{basic type} values:
 
-    \table
-    \row
-    \o
     \qml
-    // QML
-    import "script.js" as Script
-
     Item {
-        Component.onCompleted: {
-            Script.addItem('abc')
-            console.log("Added:", Script.getList()[0])
-        }
+        property variant aNumber: 100
+        property variant aString: "Hello world!"
+        property variant aBool: false
     }
     \endqml
 
-    \o
-    \code
-    // script.js
-    var myArray = new Array()
+    The \c variant type can also hold:
 
-    function getList() {
-        return myArray
-    }
-
-    function addItem(item) {
-        myArray.push(item)
-    }
-    \endcode
-    \endtable
-
-    However, note that a JavaScript list should not be used as a QML \c property value,
-    as the property is not updated when the list changes.
+    \list
+    \o An array of \l {QML Basic Types}{basic type} values
+    \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values
+    \endlist
 
-    \sa {QML Basic Types}
-*/
+    For example, below is an \c items array and an \c attributes map. Their
+    contents can be examined using JavaScript \c for loops. Individual array
+    values are accessible by index, and individual map values are accessible
+    by key:
 
+    \qml
+    Item {
+        property variant items: [1, 2, 3, "four", "five"]
+        property variant attributes: { 'color': 'red', 'width': 100 }
 
-/*!
-    \qmlbasictype variant
-    \ingroup qmlbasictypes
+        Component.onCompleted: {
+            for (var i=0; i<items.length; i++)
+                console.log(items[i])
 
-    \brief A variant type is a generic property type.
+            for (var prop in attributes)
+                console.log(prop, "=", attributes[prop])
+        }
+    }
+    \endqml
 
-    A variant is a generic property type. A variant type property can hold any of the
-    \l {QML Basic Types}{basic type} values:
+    While this is a convenient way to store array and map-type values, you
+    must be aware that the \c items and \c attributes properties above are \e not
+    QML objects (and certainly not JavaScript object either) and the key-value
+    pairs in \c attributes are \e not QML properties. Rather, the \c items
+    property holds an array of values, and \c attributes holds a set of key-value
+    pairs. Since they are stored as a set of values, instead of as an object,
+    their contents \e cannot be modified individually:
 
     \qml
     Item {
-        property variant aNumber : 100
-        property variant aString : "Hello world!"
-        property variant aList : [ 1, 2, "buckle my shoe" ]
+        property variant items: [1, 2, 3, "four", "five"]
+        property variant attributes: { 'color': 'red', 'width': 100 }
+
+        Component.onCompleted: {
+            items[0] = 10
+            console.log(items[0])     // This will still be '1'!
+            attributes.color = 'blue'
+            console.log(attributes.color)     // This will still be 'red'!
+        }
     }
     \endqml
 
-    The \c variant type can also hold a \e copy of a JavaScript object. For example, the
-    \c animal property below defines a JavaScript object defined with JSON notation. The
-    object's properties and values can be examined using the standard JavaScript syntax,
-    as shown in the \c Component.onCompleted handler.
+    Additionally, since \c items and \c attributes are not QML objects, changing
+    their individual values do not trigger property change notifications. If
+    the above example had \c onNumberChanged or \c onAnimalChanged signal
+    handlers, they would not have been called.  If, however, the \c items or
+    \c attributes properties themselves were reassigned to different values, then
+    such handlers would be called.
+
+    One way to "update" the contents of an array or map is to copy the property
+    to a JavaScript object, modify the copy as desired, and then reassign the
+    property to the updated copy. Note, however, that this is not efficient.
+    In the example below, which reassigns the \c attributes property, the \e entire
+    set of key-value pairs must be serialized and deserialized every time it is
+    copied between a JavaScript object and a QML property:
 
     \qml
     Item {
-        property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 }
+        property variant attributes: { ''color': 'red', 'width': 100 }
 
         Component.onCompleted: {
-            for (var attribute in animal)
-                console.log(attribute, "=", animal[attribute])
+            // Change the value of attributes.color to 'blue':
+            var temp = attributes     // copy all values to 'temp'
+            temp.color = 'blue'
+            attributes = temp         // copy all values back to 'attributes'
         }
     }
     \endqml
 
-    It must be noted that the \c animal property holds a \e copy of the defined object, and
-    not the object itself. (This is true even if the property refers to an object defined in
-    some JavaScript file; the property will hold a copy of the object, and not the actual
-    object.) The property essentially holds a copy of the contents within the object. This
-    has several implications:
+    Since this operation is inefficient, if a list or map should be modifiable,
+    it is better to use alternative approaches. For example, you could implement
+    a custom C++ list element, or write to a JavaScript object defined from
+    within a JavaScript file.
 
-    \list
-    \o Changes to any of the property's values (for example, the \c animal.type value
-       above) only modify the \e copy of the object, not the object itself. You can, however,
-       modify a copy of the object and then reassign the property to the modified value.
-    \o Because the property only holds a copy of the object, \l{Property Binding}{bindings} to
-       any of the property's individual values are not updated until the whole property is
-       reassigned to a new value. For example:
-
-       \qml
-       Item {
-           property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 }
-
-           Text { text: "Animal species: " + animal.species }
-
-           Component.onCompleted: {
-               animal.species = 'kookaburra'    // this has no effect on the displayed text
-
-               var newObj = animal
-               newObj.species = 'kookaburra'
-               animal = newObj  // this will update the displayed text
-           }
-       }
-       \endqml
-    \o Since the object values are copied, it does not hold any reference to the original
-       object, and extra data such as the object's JavaScript prototype chain is lost in the
-       process.
-    \endlist
+    JavaScript programmers should also note that when a JavaScript object is
+    copied to an array or map property, the \e contents of the object (that is,
+    its key-value properties) are copied, rather than the object itself. The
+    property does not hold a reference to the original JavaScript object, and
+    extra data such as the object's JavaScript prototype chain is also lost in
+    the process.
 
     \sa {QML Basic Types}
 */
 
-
 /*!
     \qmlbasictype vector3d
     \ingroup qmlbasictypes
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 3bb69da..f1ebd00 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -44,7 +44,7 @@ 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 C++ plugin} library (unless the plugin is installed in the same directory)
+\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
 
@@ -61,12 +61,12 @@ are not included in the global namespace by default.)
 
 The \c Qt module is an \e installed module; it is found in the
 \l{The QML import path}{import path}. There are two types of QML modules:
-location modules (defined by a URL) and installed modules (defined by a URI).
+located modules (defined by a URL) and installed modules (defined by a URI).
 
 
-\section1 Location Modules
+\section1 Located Modules
 
-Location modules can reside on the local filesystem or a network resource,
+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
@@ -86,8 +86,9 @@ directory using a relative or absolute path, like this:
 \code
 MyQMLProject
     |- MyComponents
-        |- Slider.qml
         |- CheckBox.qml
+        |- Slider.qml
+        |- Window.qml
     |- Main
         |- application.qml
 \endcode
@@ -96,8 +97,10 @@ MyQMLProject
 \code
 import "../MyComponents"
 
-Slider { ... }
-CheckBox { ... }
+Window {
+    Slider { ... }
+    CheckBox { ... }
+}
 \endcode
 
 \endtable
@@ -106,23 +109,51 @@ Similarly, if the directory resided on a network source, it could
 be imported like this:
 
 \code
-    import "https://qml.nokia.com/qml/qmlcomponents"
-    import "https://qml.nokia.com/qml/qmlcomponents" 1.0
+    import "http://www.my-server.com/MyQMLProject/MyComponents"
+    import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0
 \endcode
 
-Remote location modules must have a \l{Writing a qmldir file}{qmldir file} in the
-same directory to specify which QML files should be made available. See the
-\l {#qmldirexample}{example} below. The qmldir file is optional for modules on
-the local filesystem.
+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:
+
+\code
+import "http://the-server-name.com/MyQMLProject/MyComponents"
+
+Window {
+    Slider { ... }
+    CheckBox { ... }
+}
+\endcode
+
+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.
 
 
 \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.
 
-Installed modules are modules that are installed on the
-local filesystem within the QML import path, or modules defined in C++
-application code. When importing an installed module, an un-quoted URI is
+When importing an installed module, an un-quoted URI is
 used, with a mandatory version number:
 
 \code
@@ -130,15 +161,23 @@ used, with a mandatory version number:
     import com.nokia.qml.mymodule 1.0
 \endcode
 
-Installed modules that are installed into the import path or created
-as a \l{QDeclarativeExtensionPlugin}{QML C++ plugin} must define a
-\l{Writing a qmldir file}{qmldir file}.
-
+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.
 
-\section2 The QML import path
+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 QML engine will search the import path for a requested installed module.
-The default import path includes:
+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
@@ -146,30 +185,80 @@ The default import path includes:
 \o Paths specified by the \c QML_IMPORT_PATH environment variable
 \endlist
 
-The import path can be queried using QDeclarativeEngine::importPathList() and modified using QDeclarativeEngine::addImportPath().
+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.
 
-When running the \l {QML Viewer}, use the \c -I option to add paths to the import path.
+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 dynamically define installed modules using
-qmlRegisterType().
+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():
 
-For \l{QDeclarativeExtensionPlugin}{QML C++ plugins}, the
-module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes().
-The QDeclarativeExtensionPlugin documentation shows how to use this URI
-to call qmlRegisterType() to enable the plugin library to be built as
-an installed module. Once the plugin is built and installed, the module is importable
-in QML, like this:
+\qml
+qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
+\endqml
+
+This allows the application's QML files to use the \c PieChart type by importing the declared
+\c Charts module:
+
+\qml
+import Charts 1.0
+\endqml
+
+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:
 
 \code
 import com.nokia.TimeExample 1.0
 \endcode
 
-A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} also requires a
-\l{Writing a qmldir file}{qmldir file} to make it available to the
-QML engine.
+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.
 
 
 
@@ -224,7 +313,7 @@ Unlike ordinary modules, multiple scripts cannot be imported into the same names
 
 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
-location modules that are loaded from a network source.
+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:
 
@@ -274,37 +363,6 @@ containing the plugin file. By default the engine searches for the plugin librar
 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.
 
 
-\target qmldirexample
-\section2 Example
-
-If the components in the \c MyComponents directory from the
-\l{Location Modules}{earlier example} were to be made available as a network resource,
-the directory would need to contain a \c qmldir file similar to this:
-
-\code
-ComponentA 1.0 ComponentA.qml
-ComponentB 1.0 ComponentB.qml
-\endcode
-
-The \c MyComponents directory could then be imported as a module using:
-
-\code
-import "http://the-server-name.com/MyComponents"
-
-Slider { ... }
-CheckBox { ... }
-\endcode
-
-with an optional "1.0" version specification. Notice the import fails if
-a later version is used, as the \c qmldir file specifies that these elements
-are only available in the 1.0 version.
-
-
-For examples of \c qmldir files for plugins, see the
-\l {declarative/cppextensions/plugins}{Plugins} example and
-\l {Tutorial: Writing QML extensions with C++}.
-
-
 \section1 Debugging
 
 The \c QML_IMPORT_TRACE environment variable can be useful for debugging