Merge branch 'qt-master-from-4.7' of scm.dev.nokia.troll.no:qt/qt-integration into master-integration

* 'qt-master-from-4.7' of scm.dev.nokia.troll.no:qt/qt-integration: (182 commits)
  Fixes XPASS
  Revert part of commit 7c1ab9b6a8
  Fixed wrong casing of a Symbian library.
  Fixed wrong static library extension on Symbian.
  Fixed library casing.
  Remove dependencies to pre-Symbian3 platforms from Symbian3 packages
  My changes 4.7.2
  Don't accept input methods when a TextEdit or TextInput is read only.
  Correct error message
  On windows xp using a higher port makes the declarativedebug* tests work
  Correct assert
  Fix qt.sis platform dependencies for Symbian^3 builds.
  Fix few QFileDialog static method issues in Symbian^3
  Update QDeclarative DEF files for Symbian
  Export QDeclarativeRefCount so that symbian compiles.
  Make Flickable's wheel handling more like QAbstractScrollArea.
  Changing header or footer failed to delete the previous.
  Avoid index-out-of bounds related crash in Grid
  Move Qt.application docs into Qt global object page
  Add initial size to ListView in FolderListModel example
  ...

1 files changed, 84 insertions, 19 deletions

diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc
index 2fa95d4..379a4ec 100644
--- a/doc/src/declarative/propertybinding.qdoc
+++ b/doc/src/declarative/propertybinding.qdoc
@@ -95,44 +95,109 @@ Rectangle {
 \endcode
 
 
-\section1 Effects of Property Assignment in JavaScript
+\section1 Binding Properties from JavaScript
 
-Assigning a property value from JavaScript does \e not create a property binding.
-For example:
+When working with both QML and JavaScript, it is important to differentiate between
+\l {Property Binding} syntax in QML and simple \e {property assignment} in JavaScript. Take
+the example below, which uses property binding to ensure the item's \c height is always twice
+its \c width:
+
+\qml
+Item {
+    width: 100
+    height: width * 2
+}
+\endqml
+
+On the other hand, take the following JavaScript code snippet, which \e assigns, rather
+than \e binds, the value of the \c height property:
 
 \code
-Rectangle {
+Item {
+    width: 100
 
     Component.onCompleted: {
-        width = otherItem.width;
+        height = width * 2  // if width changes later, height is not updated!
     }
 }
 \endcode
 
-Instead of creating a property binding, this simply sets the \c width of the \l Rectangle
-to the value of \c other.width at the time the JavaScript code is invoked.  See 
-\l {Property Assignment vs Property Binding} for more details.
+Instead of creating a property binding, this simply sets the \c height property to the correct
+value \e {at the time that} the JavaScript code is invoked. Unlike the first example, the
+\c height will never change if \c width changes.
+
+The \e {property : value} syntax for property binding is QML-specific and cannot be used in
+JavaScript. Instead, to bind a property from JavaScript, assign a \e function to the property
+that returns the required value. The following code correctly sets the property binding
+created in the first example, but creates the binding in JavaScript rather than QML:
+
+\qml
+Item {
+    width: 100
+
+    Component.onCompleted: {
+        height = (function() { return width * 2 })
+    }
+}
+\endqml
+
+
+\section2 Using \c this to create a binding
+
+When creating a property binding from JavaScript, QML allows the use of the \c this keyword to
+refer to the object to which the property binding will be assigned. This allows one to
+explicitly refer to a property within an object when there may be ambiguity about the exact
+property that should be used for the binding.
 
-Also note that assigning a value to a property that is currently bound will remove the binding.
-A property can only have one value at a time, and if any code explicitly sets
-this value, the binding is removed.  The \l Rectangle in the example below will have
-a width of 13, regardless of the \c otherItem's width.
+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.
+
+\qml
+Item {
+    width: 500
+    height: 500
+
+    Rectangle {
+        id: rect
+        width: 100
+        color: "yellow"
+    }
+
+    Component.onCompleted: {
+        rect.height = (function() { return this.width * 2 })
+    }
+}
+\endqml
+
+(In this case, the function could also have referred to \c rect.width rather than \c this.width.)
+
+Note that the value of \c this is not defined outside of its use in property binding.
+See \l {QML JavaScript Restrictions} for details.
+
+
+\section2 Effects of property assignment
+
+Note that assigning a value to a property that is currently bound will remove the binding.
+A property can only have one value at a time, and if any code explicitly sets this value, the
+binding is removed. In the following example, although \c width has been bound to \c height,
+the binding is removed by the JavaScript code that assigns \c width to 50:
 
 \code
-Rectangle {
-    width: otherItem.width
+Item {
+    width: height * 2
+    height: 100
 
     Component.onCompleted: {
-        width = 13;
+        width = 50;
     }
 }
 \endcode
 
-There is no way to create a property binding directly from imperative JavaScript code,
-although it is possible to set up a \l Binding object (shown below).
-
 
-\section1 Binding Element
+\section1 The Binding Element
 
 The implicit binding syntax shown previously is easy to use and works perfectly for most uses
 of bindings.  In some advanced cases, it is necessary to create bindings explicitly using the