From 89cdaa901d227bed35f6c5405ce5d62f352a659c Mon Sep 17 00:00:00 2001 From: Chris Adams Date: Mon, 16 Jul 2012 11:05:01 +1000 Subject: [PATCH] Improve documentation for var properties Previously, the initialization value assignment semantics of var properties wasn't explicitly documented. Since curly braces on the RHS of an initialization assignment denotes a binding (and curly braces have a different meaning in JavaScript) confusion could result. This commit clearly explains how to initialize a var property with an empty object value. Task-number: QTBUG-23734 Task-number: QTBUG-23388 Change-Id: Ifa94846b170919a0c893f7dda1421c9fb24bd0db Reviewed-by: Michael Brasser --- src/qml/doc/src/typesystem/basictypes.qdoc | 44 ++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/src/qml/doc/src/typesystem/basictypes.qdoc b/src/qml/doc/src/typesystem/basictypes.qdoc index 55438c3..e5f0c21 100644 --- a/src/qml/doc/src/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/typesystem/basictypes.qdoc @@ -699,6 +699,8 @@ property is only invoked when the property is reassigned to a different object v } \endqml + \section1 Change Notification Semantics + It is important to note that changes in regular properties of JavaScript objects assigned to a var property will \b{not} trigger updates of bindings that access them. The example below will display "The car has 4 wheels" as @@ -724,6 +726,48 @@ property is only invoked when the property is reassigned to a different object v car property itself would be changed, which causes a change notification to be emitted. + \section1 Property Value Initialization Semantics + + The QML syntax defines that curly braces on the right-hand-side of a + property value initialization assignment denote a binding assignment. + This can be confusing when initializing a \c var property, as empty curly + braces in JavaScript can denote either an expression block or an empty + object declaration. If you wish to initialize a \c var property to an + empty object value, you should wrap the curly braces in parentheses. + + For example: + \qml + Item { + property var first: {} // nothing = undefined + property var second: {{}} // empty expression block = undefined + property var third: ({}) // empty object + } + \endqml + + In the previous example, the \c first property is bound to an empty + expression, whose result is undefined. The \c second property is bound to + an expression which contains a single, empty expression block ("{}"), which + similarly has an undefined result. The \c third property is bound to an + expression which is evaluated as an empty object declaration, and thus the + property will be initialized with that empty object value. + + Similarly, a colon in JavaScript can be either an object property value + assignment, or a code label. Thus, initializing a var property with an + object declaration can also require parentheses: + + \qml + Item { + property var first: { example: 'true' } // example is interpreted as a label + property var second: ({ example: 'true' }) // example is interpreted as a property + property var third: { 'example': 'true' } // example is interpreted as a property + Component.onCompleted: { + console.log(first.example) // prints 'undefined', as "first" was assigned a string + console.log(second.example) // prints 'true' + console.log(third.example) // prints 'true' + } + } + \endqml + \section1 Using Scarce Resources with the var Type A \c var type property can also hold an image or pixmap. -- 2.7.4