Document the 'variant' basic type

This includes documentation on restrictions and considerations when
storing a JavaScript object with this type, since such properties
only hold a copy of the object's values and not the actual object.

Task-number: QTBUG-16196
Reviewed-by: Michael Brasser

2 files changed, 87 insertions, 12 deletions

diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc
index 939f328..e9d3a44 100644
--- a/doc/src/declarative/basictypes.qdoc
+++ b/doc/src/declarative/basictypes.qdoc
@@ -432,7 +432,8 @@
     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,
+    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:
 
@@ -472,6 +473,78 @@
     \sa {QML Basic Types}
 */
 
+
+/*!
+    \qmlbasictype variant
+    \ingroup qmlbasictypes
+
+    \brief A variant type is a generic property type.
+
+    A variant is a generic property type. A variant type property can hold any of the
+    \l {QML Basic Types}{basic type} values:
+
+    \qml
+    Item {
+        property variant aNumber : 100
+        property variant aString : "Hello world!"
+        property variant aList : [ 1, 2, "buckle my shoe" ]
+    }
+    \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.
+
+    \qml
+    Item {
+        property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 }
+
+        Component.onCompleted: {
+            for (var attribute in animal)
+                console.log(attribute, "=", animal[attribute])
+        }
+    }
+    \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:
+
+    \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
+
+    \sa {QML Basic Types}
+*/
+
+
 /*!
     \qmlbasictype vector3d
     \ingroup qmlbasictypes
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 748ec6c..ff519f6 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -753,15 +753,15 @@ with their default values and the corresponding C++ type:
 
 \table
 \header \o QML Type Name \o Default value \o C++ Type Name
-\row \o int \o 0 \o int
-\row \o bool \o \c false \o bool
-\row \o double \o 0.0 \o double
-\row \o real \o 0.0 \o double
-\row \o string \o "" (empty string) \o QString
-\row \o url \o "" (empty url) \o QUrl
-\row \o color \o #000000 (black) \o QColor
-\row \o date \o \c undefined \o QDateTime
-\row \o variant \o \c undefined \o QVariant
+\row \o \l int \o 0 \o int
+\row \o \l bool \o \c false \o bool
+\row \o \l double \o 0.0 \o double
+\row \o \l real \o 0.0 \o double
+\row \o \l string \o "" (empty string) \o QString
+\row \o \l url \o "" (empty url) \o QUrl
+\row \o \l color \o #000000 (black) \o QColor
+\row \o \l date \o \c undefined \o QDateTime
+\row \o \l variant \o \c undefined \o QVariant
 \endtable
 
 QML object types can also be used as property types. This includes
@@ -776,6 +776,10 @@ property MyCustomType customProperty
 
 Such object-type properties default to an \c undefined value.
 
+It is also possible to store a copy of a JavaScript object using the \c variant
+property type. This creates some restrictions on how the property should be used;
+see the \l {variant}{variant type documentation} for details.
+
 \l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty
 list:
 
@@ -786,8 +790,6 @@ property list<Item> listOfItems
 Note that list properties cannot be modified like ordinary JavaScript
 arrays. See the \l {list}{list type documentation} for details.
 
-For details about accessing and manipulating QML properties from C++, see \l {Using QML with C++}.
-
 
 \section2 Property change signals