diff options
author | Chris Adams <christopher.adams@nokia.com> | 2012-07-16 11:05:01 +1000 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-07-16 06:47:57 +0200 |
commit | 89cdaa901d227bed35f6c5405ce5d62f352a659c (patch) | |
tree | f9d630abcdfe28cd38902483780409bd5d1bae2a /src | |
parent | 50ec85e368a15236812776c274cdb10ac2be0ccd (diff) |
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 <michael.brasser@nokia.com>
Diffstat (limited to 'src')
-rw-r--r-- | src/qml/doc/src/typesystem/basictypes.qdoc | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/src/qml/doc/src/typesystem/basictypes.qdoc b/src/qml/doc/src/typesystem/basictypes.qdoc index 55438c3041..e5f0c21439 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. |