diff options
| -rw-r--r-- | doc/src/declarative/basictypes.qdoc | 183 |
1 files changed, 84 insertions, 99 deletions
diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 463e4a3..eac509e 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -400,14 +400,11 @@ \c child1, \c child2 and \c child3 will be added to the children list in the order in which they appear. - List \l {Adding 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: + List \l {Adding Properties}{properties} can be declared as \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} @@ -415,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 |