diff options
| -rw-r--r-- | doc/src/declarative/basictypes.qdoc | 75 | ||||
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 24 |
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 |