From b628a6dc1373fcfbc71a7668d39111c699396674 Mon Sep 17 00:00:00 2001
From: Bea Lam <bea.lam@nokia.com>
Date: Thu, 4 Nov 2010 15:18:08 +1000
Subject: Document list type operations

Task-number: QTBUG-14645
---
 doc/src/declarative/basictypes.qdoc | 85 ++++++++++++++++++++++++++++++++++---
 doc/src/declarative/extending.qdoc  |  9 +++-
 2 files changed, 87 insertions(+), 7 deletions(-)

diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc
index 6abe96f..8ab06ab 100644
--- a/doc/src/declarative/basictypes.qdoc
+++ b/doc/src/declarative/basictypes.qdoc
@@ -355,9 +355,11 @@
 
     \brief A list of objects.
 
-    A list of objects. While not technically a basic type, QML also
-    supports lists of object types. When used from QML, the engine
-    automatically appends each value to the list.
+    A list type contains a list of objects. While not technically
+    a basic type, QML supports lists of object types. When used
+    from QML, the engine automatically appends each value to the list.
+    Items in the list can be accessed by index using the usual
+    \c listName[index] syntax.
 
     For example, the \l Item class contains a list property named
     children that can be used like this:
@@ -366,14 +368,87 @@
     Item {
         children: [
             Item { id: child1 },
-            Rectangle { id: child2 },
+            Rectangle { id: child2; width: 200 },
             Text { id: child3 }
         ]
+
+        Component.onCompleted: {
+            console.log("Width of child rectangle:", children[1].width)
+        }
     }
     \endqml
-    \c child1, \c child2 and \c child3 will all be added to the children list
+    \c child1, \c child2 and \c child3 will be added to the children list
     in the order in which they appear.
 
+    List \l {Adding new properties}{properties} can be created as a
+    \c variant type, or as a \c list<Type> type, where \c Type is the
+    type of the object in the list:
+
+    \qml
+    Item {
+        property variant values: [ 10, 20, 'abc', 'xyz' ]
+
+        property list<Rectangle> rects: [
+            Rectangle { width: 100; height: 100},
+            Rectangle { width: 200; height: 200}
+        ]
+    }
+    \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 be cleared by setting it to an empty list:
+
+    \qml
+    Item {
+        children: []
+    }
+    \endqml
+
+    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.)
+
+    To create a modifiable list, 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:
+
+    \table
+    \row
+    \o
+    \qml
+    // QML
+    import "script.js" as Script
+
+    Item {
+        Component.onCompleted: {
+            Script.addItem('abc')
+            console.log("Added:", Script.getList()[0])
+        }
+    }
+    \endqml
+
+    \o
+    \code
+    // script.js
+    var myArray = new Array()
+
+    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.
+
     \sa {QML Basic Types}
 */
 
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 18887c7..5c1b977 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -647,7 +647,8 @@ language.
 
 \section1 Adding new properties
 
-New properties can be added to an existing type.  These new properties are
+New properties can be added to an existing type using the \c property keyword.
+These new properties are
 available for use within QML, and also appear as regular Qt properties on the
 C++ object, accessible through the regular property access mechanisms.
 
@@ -679,8 +680,12 @@ like this:
     property list<Item> listOfItemsProperty
 \endcode
 
+Custom types must be registered with qmlRegisterType() to be usable as a property
+type. Also note that list properties cannot be modified like ordinary JavaScript
+arrays; see the \l {list}{list type documentation} for details.
+
 QML supports two methods for adding a new property to a type: a new property
-definition, and a property alias.
+definition, and a property alias. These are shown below.
 
 \section2 Property definitions
 
-- 
cgit v0.12