aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorChris Adams <christopher.adams@nokia.com>2012-02-06 14:24:42 +1000
committerQt by Nokia <qt-info@nokia.com>2012-03-05 09:01:47 +0100
commitb6e78b38367a23f0b053bbd2abe4ef161e4053b9 (patch)
tree022bb82553af5b96a31f6e1ba56944d0e7060437 /doc/src
parent0284817d6cd7e17afa8da26ee6e9199100754446 (diff)
Improve support for var properties
This commit changes the semantics of function assignment in QML. Previously, function assignment was interpreted as binding assignment. Now, function assignment is interpreted as function assignment, and therefore fails for all property types other than "var" properties. To support imperative binding assignment, a new function was added to the Qt object: Qt.binding(function) which takes a single function parameter and returns a function object which will be interpreted as an assignable binding expression by the QML engine. Finally, this commit also slightly changes the semantics of var properties in that the "special" JavaScript values of null and undefined may be assigned to var properties, rather than being interpreted as reset requests. Task-number: QTBUG-21842 Change-Id: Iee99a878b9badf0fb76e983da7ebfa493f55ceb5 Reviewed-by: Matthew Vogt <matthew.vogt@nokia.com>
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/qml/basictypes.qdoc17
-rw-r--r--doc/src/qml/javascriptblocks.qdoc13
-rw-r--r--doc/src/qml/propertybinding.qdoc19
-rw-r--r--doc/src/snippets/qml/DynamicText.qml52
-rw-r--r--doc/src/snippets/qml/qtBinding.1.qml55
-rw-r--r--doc/src/snippets/qml/qtBinding.2.qml58
-rw-r--r--doc/src/snippets/qml/qtBinding.3.qml63
-rw-r--r--doc/src/snippets/qml/qtBinding.4.qml54
8 files changed, 311 insertions, 20 deletions
diff --git a/doc/src/qml/basictypes.qdoc b/doc/src/qml/basictypes.qdoc
index 0f66a96731..c179cbff2e 100644
--- a/doc/src/qml/basictypes.qdoc
+++ b/doc/src/qml/basictypes.qdoc
@@ -436,10 +436,9 @@
\brief A var type is a generic property type.
A var is a generic property type capable of storing any data type.
- It is equivalent to a regular JavaScript variable, except that you
- cannot assign a JavaScript function to such a property.
- For example, var properties can store numbers, strings, objects and
- arrays:
+ It is equivalent to a regular JavaScript variable.
+ For example, var properties can store numbers, strings, objects,
+ arrays and functions:
\qml
Item {
@@ -454,13 +453,10 @@
property var aVector3d: Qt.vector3d(100, 100, 100)
property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
property var anObject: { "foo": 10, "bar": 20 }
+ property var aFunction: (function() { return "one"; })
}
\endqml
- Attempting to assign a JavaScript function to a var property will result in
- a binding assignment as per other property types. You can assign a JavaScript
- array containing a single function element instead.
-
It is important to note that changes in regular properties of JavaScript
objects assigned to a var property will \bold{not} trigger updates of bindings
that access them. The example below will display "The car has 4 wheels" as
@@ -481,6 +477,11 @@
}
\endqml
+ If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
+ then the text would be updated to say "The car has 6 wheels"., since the
+ car property itself would be changed, which causes a change notification
+ to be emitted.
+
A \c var type property can also hold an image or pixmap.
A \c var which contains a QPixmap or QImage is known as a
"scarce resource" and the declarative engine will attempt to
diff --git a/doc/src/qml/javascriptblocks.qdoc b/doc/src/qml/javascriptblocks.qdoc
index 0c1d4c284c..5a30324d1a 100644
--- a/doc/src/qml/javascriptblocks.qdoc
+++ b/doc/src/qml/javascriptblocks.qdoc
@@ -72,7 +72,7 @@ Rectangle {
id: button
width: 200; height: 80; color: "lightsteelblue"
- MouseArea {
+ MouseArea {
id: mousearea
anchors.fill: parent
@@ -103,7 +103,7 @@ Rectangle {
color: mousearea.pressed ? "steelblue" : "lightsteelblue"
- MouseArea {
+ MouseArea {
id: mousearea
anchors.fill: parent
}
@@ -366,6 +366,15 @@ Likewise, the \l {Component::onDestruction} attached property is triggered on
component destruction.
+\section1 JavaScript and Property Binding
+
+Property bindings can be created in JavaScript by assigning the property the value returned
+by calling Qt.binding() where the parameter to Qt.binding() is a \c function
+that returns the required value.
+
+See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details.
+
+
\section1 QML JavaScript Restrictions
QML executes standard JavaScript code, with the following restrictions:
diff --git a/doc/src/qml/propertybinding.qdoc b/doc/src/qml/propertybinding.qdoc
index 6dd862f55b..ce5ad0be4a 100644
--- a/doc/src/qml/propertybinding.qdoc
+++ b/doc/src/qml/propertybinding.qdoc
@@ -87,7 +87,7 @@ The property binding causes the width of the \c Rectangle to update whenever the
\c {parent}'s width changes.
Assigning a property value (using the equals sign "\c {=}") does not create a
-property binding.
+property binding (unless explicitly assigned, see below).
\snippet doc/src/snippets/qml/properties.qml property assignment
Instead of creating a property binding, the assignment simply sets the \c Rectangle
@@ -100,9 +100,9 @@ and if any code explicitly re-sets this value, the property binding is removed.
\section1 Binding to JavaScript Functions
The \c{property : value} syntax for property binding is QML-specific and cannot
-be used in JavaScript. Instead, to bind a property from JavaScript, assign a \c
-function to the property that returns the required value. The following code
-correctly creates
+be used in JavaScript. Instead, to bind a property from JavaScript, assign the
+result returned by the \c{Qt.binding()} function to the property. This will cause
+a binding assignment on the specified property. The following code correctly creates
the binding in JavaScript rather than QML:
\qml
@@ -110,7 +110,7 @@ Item {
width: 100
Component.onCompleted: {
- height = (function() { return width * 2 })
+ height = Qt.binding(function() { return width * 2 })
}
}
\endqml
@@ -124,10 +124,8 @@ binding.
For example, the \c Component.onCompleted handler below is defined within the
scope of the \l Item, and references to \c width within this scope would refer
to the \l Item's width, rather than that of the \l Rectangle. To bind the \l
-Rectangle's \c height to its own \c width, the function needs to explicitly
-refer to \c this.width rather than just \c width. Otherwise, the height of the
-\l Rectangle would be bound to the width of the \l Item and not the \l
-Rectangle.
+Rectangle's \c height to its own \c width, the function passed to Qt.binding()
+needs to explicitly refer to \c this.width rather than just \c width.
\qml
Item {
@@ -141,7 +139,8 @@ Item {
}
Component.onCompleted: {
- rect.height = (function() { return this.width * 2 })
+ rect.height = Qt.binding(function() { return this.width * 2 })
+ console.log("rect.height = " + rect.height) // prints 200
}
}
\endqml
diff --git a/doc/src/snippets/qml/DynamicText.qml b/doc/src/snippets/qml/DynamicText.qml
new file mode 100644
index 0000000000..9711702037
--- /dev/null
+++ b/doc/src/snippets/qml/DynamicText.qml
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import QtQuick 2.0
+
+Text {
+ id: textElement
+ width: 200
+ height: 200
+ text: "Default text"
+ property string dynamicText: "Dynamic text"
+ onTextChanged: console.log(text)
+}
+//![0]
diff --git a/doc/src/snippets/qml/qtBinding.1.qml b/doc/src/snippets/qml/qtBinding.1.qml
new file mode 100644
index 0000000000..acec88a47f
--- /dev/null
+++ b/doc/src/snippets/qml/qtBinding.1.qml
@@ -0,0 +1,55 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//![0]
+Item {
+ property bool someCondition: true
+ property int edgePosition
+
+ Component.onCompleted: {
+ if (someCondition == true) {
+ // bind to the result of the binding expression passed to Qt.binding()
+ edgePosition = Qt.binding(function() { return x + width })
+ }
+ }
+}
+//![0]
diff --git a/doc/src/snippets/qml/qtBinding.2.qml b/doc/src/snippets/qml/qtBinding.2.qml
new file mode 100644
index 0000000000..9b78bc395a
--- /dev/null
+++ b/doc/src/snippets/qml/qtBinding.2.qml
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//![0]
+Item {
+ id: root
+ property string dynamicText: "Root text"
+
+ Component.onCompleted: {
+ var c = Qt.createComponent("DynamicText.qml")
+
+ var obj1 = c.createObject(root, { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
+ root.dynamicText = "Modified root text"
+
+ var obj2 = c.createObject(root, { 'text': Qt.binding(function() { return this.dynamicText + ' extra text' }) })
+ obj2.dynamicText = "Modified text element text"
+ }
+}
+//![0]
diff --git a/doc/src/snippets/qml/qtBinding.3.qml b/doc/src/snippets/qml/qtBinding.3.qml
new file mode 100644
index 0000000000..a27914cc15
--- /dev/null
+++ b/doc/src/snippets/qml/qtBinding.3.qml
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//![0]
+Item {
+ id: root
+ property string dynamicText: "Root text"
+
+ Loader {
+ id: loaderOne
+ onLoaded: root.dynamicText = "Modified root text"
+ }
+
+ Loader {
+ id: loaderTwo
+ onLoaded: item.dynamicText = "Modified dynamic text"
+ }
+
+ Component.onCompleted: {
+ loaderOne.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
+ loaderTwo.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return this.dynamicText + ' extra text' }) })
+ }
+}
+//![0]
diff --git a/doc/src/snippets/qml/qtBinding.4.qml b/doc/src/snippets/qml/qtBinding.4.qml
new file mode 100644
index 0000000000..0155957a59
--- /dev/null
+++ b/doc/src/snippets/qml/qtBinding.4.qml
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//![0]
+Item {
+ width: 50
+ property var storedBindings: [ Qt.binding(function() { return x + width }) ] // stored
+ property int a: Qt.binding(function() { return x + width }) // error!
+ property int b
+
+ Component.onCompleted: {
+ b = storedBindings[0] // causes binding assignment
+ }
+}
+//![0]