summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBea Lam <bea.lam@nokia.com>2010-12-22 02:23:08 (GMT)
committerBea Lam <bea.lam@nokia.com>2010-12-22 02:24:13 (GMT)
commit2d4d125313d79fb80f513952bed675b7126392fd (patch)
tree777f9727e09655fa2a9a06979500113ec9d23177
parent22df95289adc5fca59cc0a42cf18e98c5cc433d9 (diff)
downloadQt-2d4d125313d79fb80f513952bed675b7126392fd.zip
Qt-2d4d125313d79fb80f513952bed675b7126392fd.tar.gz
Qt-2d4d125313d79fb80f513952bed675b7126392fd.tar.bz2
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
-rw-r--r--doc/src/declarative/basictypes.qdoc75
-rw-r--r--doc/src/declarative/extending.qdoc24
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