Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt into 4.7

16 files changed, 388 insertions, 76 deletions

diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index 11a4386..316fe6b 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -62,10 +62,16 @@ To dynamically load a component defined in a QML file, call the
 This function takes the URL of the QML file as its only argument and creates
 a \l Component object from this URL.
 
-Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of
-the component. This function takes exactly one argument, which is the parent for the new item. Since graphical items will
-not appear on the scene without a parent, it is recommended that you set the parent this way. However, if you wish to set
-the parent later you can safely pass \c null to this function.
+Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of 
+the component. This function can take one or two arguments:
+\list
+\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is 
+  recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to 
+  this function. 
+\o The second is optional and is a script which assigns values to the item's properties during creation. This avoids warnings 
+  when certain properties have been bound to before they have been set by the code. Additionally, there are small performance 
+  benefits when instantiating objects in this way.
+\endlist
 
 Here is an example. First there is \c Sprite.qml, which defines a simple QML component:
 
diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc
index e03557b..be2d0c7 100644
--- a/doc/src/declarative/examples.qdoc
+++ b/doc/src/declarative/examples.qdoc
@@ -136,7 +136,8 @@ The examples can be found in Qt's \c examples/declarative directory.
 
 \section2 Positioners
 \list
-\o \l{declarative/positioners}{Example}
+\o \l{declarative/positioners/addandremove}{Adding and Removing Items}
+\o \l{declarative/positioners/layoutdirection}{Layout Direction}
 \endlist
 
 \section2 Key Interaction
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index b986d06..5a95551 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -112,6 +112,75 @@ Person {
 \l {Extending QML - Adding Types Example} shows the complete code used to create
 the \c Person type.
 
+\section1 QML Type Versioning
+
+In C++ adding a new method or property cannot break old applications.
+In QML, however, new methods and properties can change what a name previously
+resolved to to within a scope chain.
+
+For example, consider these two QML files
+
+\code
+// main.qml
+import QtQuick 1.0
+Item {
+    id: root
+    MyComponent {}
+}
+\endcode
+
+\code
+// MyComponent.qml
+import MyModule 1.0
+CppItem {
+    value: root.x
+}
+\endcode
+
+where CppItem maps to the C++ class QCppItem.
+
+If the author of QCppItem adds a "root" property to QCppItem in a new version of the module, 
+it will break the above program as \c root.x now resolves to a different value.
+The solution is to allow the author of QCppItem to state that the new \c root property is 
+only available from a particular version of QCppItem onwards. This permits new properties
+and features to be added to existing elements without breaking existing programs. 
+
+QML enables this by allowing the properties, methods and signals of a class to be tagged with
+a particular \e revision, so that they are only accessible if the relevant module version
+is imported.  In this case, the author can tag the \c root property as being added in
+\e {revision 1} of the class, and register that revision in version 1.1 of the module.
+
+The REVISION tag is used to mark the \c root property as added in revision 1 of the class.
+Methods such as Q_INVOKABLE's, signals and slots can also be tagged for a
+revision using the \c Q_REVISION(x) macro:
+
+\code
+class CppItem : public QObject
+{
+    Q_OBJECT
+    Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1)
+
+signals:
+    Q_REVISION(1) void rootChanged();
+};
+\endcode
+
+To register the new class revision to a particular version the following function is used:
+
+\code
+template<typename T, int metaObjectRevision>
+int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
+\endcode
+
+To register \c CppItem version 1 for \c {MyModule 1.1}:
+
+\code
+qmlRegisterType<QCppItem,1>("MyModule", 1, 1, "CppItem")
+\endcode
+
+\c root is only available when MyModule 1.1 is imported.
+
+
 \section1 Object and List Property Types
 
 \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index 2568f81..85a3a25 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -141,8 +141,9 @@ using the Offline Storage API.
 \section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db))
 
 Returns the database identified by \e identifier. If the database does not already exist, it
-is created with the properties \e description and \e estimated_size and the function \e callback
-is called with the database as a parameter.
+is created, and the function \e callback is called with the database as a parameter. \e description
+and \e estimated_size are written to the INI file (described below), but are otherwise currently
+unused.
 
 May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.
 
@@ -153,7 +154,7 @@ When a database is first created, an INI file is also created specifying its cha
 \row \o Name \o The name of the database passed to \c openDatabase()
 \row \o Version \o The version of the database passed to \c openDatabase()
 \row \o Description \o The description of the database passed to \c openDatabase()
-\row \o EstimatedSize \o The estimated size of the database passed to \c openDatabase()
+\row \o EstimatedSize \o The estimated size (in bytes) of the database passed to \c openDatabase()
 \row \o Driver \o Currently "QSQLITE"
 \endtable
 
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc
index d221205..65877f9 100644
--- a/doc/src/declarative/javascriptblocks.qdoc
+++ b/doc/src/declarative/javascriptblocks.qdoc
@@ -200,37 +200,12 @@ Likewise, the \l {Component::onDestruction} attached property is triggered on
 component destruction.
 
 
-\section1 Property Assignment vs Property Binding
+\section1 JavaScript and Property Binding
 
-When working with both QML and JavaScript, it is important to differentiate between
-QML \l {Property Binding} and JavaScript value assignment. In QML, a property 
-binding is created using the \e {property: value} syntax:
+Property bindings can be created in JavaScript by assigning the property with a \c function
+that returns the required value.
 
-\code
-Rectangle {
-    width: otherItem.width
-}
-\endcode
-
-The \c width of the above \l Rectangle is updated whenever \c otherItem.width changes. On the other
-hand, take the following JavaScript code snippet, that runs when the \l Rectangle is created:
-
-\code
-Rectangle {
-
-    Component.onCompleted: {
-        width = otherItem.width;
-    }
-}
-\endcode
-
-The \c width of this \l Rectangle is \e assigned the value of \c otherItem.width using the
-\e {property = value} syntax in JavaScript. Unlike the QML \e {property: value} syntax, this
-does not invoke QML property binding; the \c rectangle.width property is set to the value
-of \c otherItem.width at the time of the assignment and will not be updated if that value
-changes.
-
-See \l {Property Binding} for more information.
+See \l {Binding Properties from JavaScript} for details.
 
 
 \section1 Receiving QML Signals in JavaScript
@@ -315,10 +290,13 @@ This restriction exists as the QML environment is not yet fully established.
 To run code after the environment setup has completed, refer to
 \l {Running JavaScript at Startup}.
 
-\o The value of \c this is currently undefined in QML
+\o The value of \c this is currently undefined in QML in the majority of contexts
+
+The \c this keyword is supported when \l {Binding Properties from JavaScript}
+{binding properties from JavaScript}. In all other situations, the value of
+\c this is undefined in QML.
 
-The value of \c this is undefined in QML.  To refer to any element, provide
-an \c id.  For example:
+To refer to any element, provide an \c id.  For example:
 
 \qml
 Item {
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 
diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc
index 744b4bd..9409eaf 100644
--- a/doc/src/declarative/qdeclarativemodels.qdoc
+++ b/doc/src/declarative/qdeclarativemodels.qdoc
@@ -161,7 +161,7 @@ while QAbstractItemModel provides a more flexible solution for more complex
 models.
 
 
-\section2 QStringList
+\section2 QStringList-based model
 
 A model may be a simple QStringList, which provides the contents of the list via the \e modelData role.
 
@@ -182,7 +182,7 @@ have changed.  If the QStringList changes, it will be necessary to reset
 the model by calling QDeclarativeContext::setContextProperty() again.
 
 
-\section2 QList<QObject*>
+\section2 QObjectList-based model
 
 A list of QObject* values can also be used as a model. A QList<QObject*> provides 
 the properties of the objects in the list as roles.
diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc
index cfb762c..585b402 100644
--- a/doc/src/declarative/qmlviewer.qdoc
+++ b/doc/src/declarative/qmlviewer.qdoc
@@ -192,6 +192,9 @@ Rectangle {
 }
 \endqml
 
+\note Since Qt Quick 1.1 this information is accessible outside of the QML Viewer,
+through the \c active property of the \l {QML:Qt::application}{Qt.application} object.
+
 \row
 
 \o \c runtime.orientation
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index e8a1c24..4a6f6a9 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -85,6 +85,21 @@
 
   Returns the QML type id.
 
+  There are two forms of this template function:
+
+  \code
+  template<typename T>
+  int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
+
+  template<typename T, int metaObjectRevision>
+  int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
+  \endcode
+
+  The former is the standard form which registers the type \e T as a new type.
+  The latter allows a particular revision of a class to be registered in
+  a specified version (see \l {QML Type Versioning}).
+
+
   For example, this registers a C++ class \c MySliderItem as a QML type
   named \c Slider for version 1.0 of a \l{QML Modules}{module} called
   "com.mycompany.qmlcomponents":
diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc
index a3ba522..f4359f9 100644
--- a/doc/src/declarative/whatsnew.qdoc
+++ b/doc/src/declarative/whatsnew.qdoc
@@ -29,7 +29,113 @@
 \title What's new in Qt Quick
 \page qtquick-whatsnew.html
 
-\section1 4.7.1
+\section1 Qt 4.7.3 includes QtQuick 1.1
+
+QtQuick 1.1 is a minor feature update.
+
+\section2 PinchArea
+
+PinchArea provides support for the common two finger pinch gesture.
+
+\section2 Text
+
+Added the following properties:
+\list
+\o lineSpacing
+\o lineCount
+\o maximumLineCount
+\o truncated
+\endlist
+
+horizontalAlignment now accepts Text.AlignJustify alignment mode.
+
+\section2 TextEdit
+
+Added the following properties, methods and signal handlers:
+\list
+\o canPaste
+\o lineCount
+\o deselect()
+\o moveCursorSelection(int pos, SelectionMode mode) to enable selection by word
+\o onLinkActivated(string link) 
+\endlist
+
+\section2 TextInput
+
+Added the following properties and methods:
+\list
+\o canPaste
+\o deselect()
+\o moveCursorSelection(int pos, SelectionMode mode) to enable selection by word
+\endlist
+
+\section2 Image, BorderImage and AnimatedImage
+
+Added the following properties:
+\list
+\o cache
+\o mirror
+\endlist
+
+\section2 Item
+
+Added the following properties:
+\list
+\o implicitWidth and implicitHeight
+\endlist
+
+\section2 Flickable
+
+Added the following methods:
+\list
+\o resizeContent(qreal w, qreal h, QPointF center)
+\o returnToBounds() 
+\endlist
+
+\section2 ListView and GridView
+
+Added the following methods:
+\list
+\o positionViewAtBeginning()
+\o positionViewAtEnd() 
+\endlist
+
+\section2 Flow, Grid, Row
+
+Added the following properties:
+\list
+\o layoutDirection
+\endlist
+
+\section2 Repeater
+
+Added the following methods and signal handlers:
+\list
+\o onItemAdded()
+\o onItemRemoved()
+\o itemAt(int index)
+\endlist
+
+\section2 Component
+
+The createObject() method now accepts a map of initial property values for the created object.
+
+\section2 Qt
+
+Added the following properties and methods:
+\list
+\o application.layoutDirection
+\o application.active
+\endlist
+
+\section2 Other changes
+
+\list
+\o Functions can be assigned to properties from JavaScript to create property bindings
+\endlist
+
+
+\section1 Qt 4.7.1
 
 \section2 QtQuick namespace
 
diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc
index cd1bbe7..bbea19b 100644
--- a/doc/src/examples/qml-examples.qdoc
+++ b/doc/src/examples/qml-examples.qdoc
@@ -270,16 +270,26 @@
 */
 
 /*!
-    \title Positioners Example
-    \example declarative/positioners
+    \title Positioners: Adding and Removing Items Example
+    \example declarative/positioners/addandremove
 
-    This example shows how to use positioner elements such as \l Row, \l Column,
-    \l Grid and \l Flow.
+    This example shows how to use the positioner elements such as \l Row, \l Column,
+    \l Grid and \l Flow, in particular how to add and remove items with appropriate transitions.
 
     \image qml-positioners-example.png
 */
 
 /*!
+    \title Positioners: Layout Direction Example
+    \example declarative/positioners/layoutdirection
+
+    This example shows how to control the horizontal layout direction of 
+    \l Row, \l Grid and \l Flow positioners.
+
+    \image qml-positioners-layoutdirection-example.png
+*/
+
+/*!
     \title Key Interaction: Focus Example
     \example declarative/keyinteraction/focus
 
diff --git a/doc/src/examples/qml-folderlistmodel.qdoc b/doc/src/examples/qml-folderlistmodel.qdoc
index c9d248e..0a01ce0 100644
--- a/doc/src/examples/qml-folderlistmodel.qdoc
+++ b/doc/src/examples/qml-folderlistmodel.qdoc
@@ -41,10 +41,15 @@ making the model available to QML.
 
 \section1 Usage from QML
 
-The type we are creating can be used from QML like this:
+The FolderListModel can be used from QML like this:
 
 \snippet doc/src/snippets/declarative/folderlistmodel.qml 0
 
+This displays a list of all subfolders and QML files in the current folder.
+
+The FolderListModel \c folder property can be set to change the folder that
+is currently displayed.
+
 \section1 Defining the Model
 
 We are subclassing QAbstractListModel which will allow us to give data to QML and
diff --git a/doc/src/images/qml-positioners-layoutdirection-example.png b/doc/src/images/qml-positioners-layoutdirection-example.png
new file mode 100644
index 0000000..2c42b09
--- /dev/null
+++ b/doc/src/images/qml-positioners-layoutdirection-example.png
diff --git a/doc/src/snippets/declarative/application.qml b/doc/src/snippets/declarative/application.qml
new file mode 100644
index 0000000..06f83f2
--- /dev/null
+++ b/doc/src/snippets/declarative/application.qml
@@ -0,0 +1,53 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** 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$
+**
+****************************************************************************/
+
+//! [document]
+import QtQuick 1.1
+
+Rectangle {
+    width: 300; height: 55
+    color: Qt.application.active ? "white" : "lightgray"
+    Text {
+        text: "Application " + (Qt.application.active ? "active" : "inactive")
+        opacity: Qt.application.active ? 1.0 : 0.5
+        anchors.centerIn: parent
+    }
+}
+//! [document]
diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js
index c29a1f9..cf59777 100644
--- a/doc/src/snippets/declarative/componentCreation.js
+++ b/doc/src/snippets/declarative/componentCreation.js
@@ -17,15 +17,11 @@ function createSpriteObjects() {
 
 //![local]
     component = Qt.createComponent("Sprite.qml");
-    sprite = component.createObject(appWindow);
+    sprite = component.createObject(appWindow, {"x": 100, "y": 100});
 
     if (sprite == null) {
         // Error Handling
         console.log("Error creating object");
-    } else {
-        sprite.x = 100;
-        sprite.y = 100;
-        // ...
     }
 //![local]
 
diff --git a/doc/src/snippets/declarative/folderlistmodel.qml b/doc/src/snippets/declarative/folderlistmodel.qml
index 3bddefb..8aeb72c 100644
--- a/doc/src/snippets/declarative/folderlistmodel.qml
+++ b/doc/src/snippets/declarative/folderlistmodel.qml
@@ -43,15 +43,19 @@ import QtQuick 1.0
 import Qt.labs.folderlistmodel 1.0
 
 ListView {
+    width: 200; height: 400
+
     FolderListModel {
-        id: foldermodel
+        id: folderModel
         nameFilters: ["*.qml"]
     }
+
     Component {
-        id: filedelegate
+        id: fileDelegate
         Text { text: fileName }
     }
-    model: foldermodel
-    delegate: filedelegate
+
+    model: folderModel
+    delegate: fileDelegate
 }
 //![0]