fixes, improvements for various docs and example code

10 files changed, 544 insertions, 20 deletions

diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc
index b44e6f2..e02575d 100644
--- a/doc/src/declarative/qdeclarativemodels.qdoc
+++ b/doc/src/declarative/qdeclarativemodels.qdoc
@@ -208,7 +208,10 @@ Models can be defined in C++ and then made available to QML. This is useful
 for exposing existing C++ data models or otherwise complex datasets to QML.
 
 A C++ model class can be defined as a QStringList, a QList<QObject*> or a
-QAbstractItemModel. 
+QAbstractItemModel. The first two are useful for exposing simpler datasets,
+while QAbstractItemModel provides a more flexible solution for more complex
+models.
+
 
 \section2 QStringList
 
@@ -268,7 +271,10 @@ the model by calling QDeclarativeContext::setContextProperty() again.
 
 \section2 QAbstractItemModel
 
-A model can be defined by subclassing QAbstractItemModel.
+A model can be defined by subclassing QAbstractItemModel. This is the
+best approach if you have a more complex model that cannot be supported
+by the other approaches. A QAbstractItemModel can also automatically 
+notify a QML view when the model data has changed.
 
 The roles of a QAbstractItemModel subclass can be exposed to QML by calling 
 QAbstractItemModel::setRoleNames(). The default role names set by Qt are:
@@ -305,6 +311,12 @@ roles:
 
 \snippet examples/declarative/modelviews/abstractitemmodel/view.qml 0
 
+QML views are automatically updated when the model changes. Remember the model
+must follow the standard rules for model changes and notify the view when
+the model has changed by using QAbstractItemModel::dataChanged(), 
+QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for
+more information.
+
 The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory.
 
 QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML
diff --git a/doc/src/snippets/declarative/coloranimation.qml b/doc/src/snippets/declarative/coloranimation.qml
new file mode 100644
index 0000000..4e35f22
--- /dev/null
+++ b/doc/src/snippets/declarative/coloranimation.qml
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import Qt 4.7
+
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+
+    ColorAnimation on color { to: "yellow"; duration: 1000 }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/numberanimation.qml b/doc/src/snippets/declarative/numberanimation.qml
new file mode 100644
index 0000000..57d23b1
--- /dev/null
+++ b/doc/src/snippets/declarative/numberanimation.qml
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import Qt 4.7
+
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+
+    NumberAnimation on x { to: 50; duration: 1000 }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/propertyanimation.qml b/doc/src/snippets/declarative/propertyanimation.qml
new file mode 100644
index 0000000..059cde5
--- /dev/null
+++ b/doc/src/snippets/declarative/propertyanimation.qml
@@ -0,0 +1,101 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import Qt 4.7
+
+Row {
+
+//![transition]
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    states: State {
+        name: "moved"
+        PropertyChanges { target: rect; x: 50 }
+    }
+
+    transitions: Transition { 
+        PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } 
+    }
+}
+//![transition]
+
+//![behavior]
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+
+    Behavior on x { PropertyAnimation {} }
+
+    MouseArea { anchors.fill: parent; onClicked: parent.x = 50 }
+}
+//![behavior]
+
+//![propertyvaluesource]
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+
+    SequentialAnimation on x {
+        loops: Animation.Infinite
+        PropertyAnimation { to: 50 }
+        PropertyAnimation { to: 0 }
+    }
+}
+//![propertyvaluesource]
+
+//![standalone]
+Rectangle {
+    id: theRect
+    width: 100; height: 100
+    color: "red"
+
+    // this is a standalone animation, it's not running by default
+    PropertyAnimation { id: animation; target: theRect; property: "width"; to: 30; duration: 500 }
+
+    MouseArea { anchors.fill: parent; onClicked: animation.running = true }
+}
+//![standalone]
+
+
+}
diff --git a/doc/src/snippets/declarative/smoothedanimation.qml b/doc/src/snippets/declarative/smoothedanimation.qml
new file mode 100644
index 0000000..20c90b5
--- /dev/null
+++ b/doc/src/snippets/declarative/smoothedanimation.qml
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module 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 Qt 4.7
+
+Rectangle {
+    width: 800; height: 600
+    color: "blue"
+
+    Rectangle {
+        width: 60; height: 60
+        x: rect1.x - 5; y: rect1.y - 5
+        color: "green"
+
+        Behavior on x { SmoothedAnimation { velocity: 200 } }
+        Behavior on y { SmoothedAnimation { velocity: 200 } }
+    }
+
+    Rectangle {
+        id: rect1
+        width: 50; height: 50
+        color: "red"
+    }
+
+    focus: true
+    Keys.onRightPressed: rect1.x = rect1.x + 100
+    Keys.onLeftPressed: rect1.x = rect1.x - 100
+    Keys.onUpPressed: rect1.y = rect1.y - 100
+    Keys.onDownPressed: rect1.y = rect1.y + 100
+}
+//![0]
diff --git a/doc/src/snippets/declarative/springanimation.qml b/doc/src/snippets/declarative/springanimation.qml
new file mode 100644
index 0000000..b73a9d2
--- /dev/null
+++ b/doc/src/snippets/declarative/springanimation.qml
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module 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 Qt 4.7
+
+Rectangle {
+    width: 300; height: 300
+
+    Rectangle {
+        id: rect
+        width: 50; height: 50
+        color: "red"
+
+        Behavior on x { SpringAnimation { spring: 2; damping: 0.2 } }
+        Behavior on y { SpringAnimation { spring: 2; damping: 0.2 } }
+    }
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: {
+            rect.x = mouse.x
+            rect.y = mouse.y
+        }
+    }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/state.qml b/doc/src/snippets/declarative/state.qml
index a99c2e2..af6b103 100644
--- a/doc/src/snippets/declarative/state.qml
+++ b/doc/src/snippets/declarative/state.qml
@@ -44,26 +44,13 @@ import Qt 4.7
 Rectangle {
     id: myRect
     width: 100; height: 100
-    color: "black"
+    color: "red"
 
-    states: [
-        State {
-            name: "clicked"
-            PropertyChanges {
-                target: myRect
-                color: "red"
-            }
-        }
-    ]
+    MouseArea { id: mouseArea; anchors.fill: parent }
 
-    MouseArea {
-        anchors.fill: parent
-        onClicked: {
-            if (myRect.state == "")     // i.e. the default state
-                myRect.state = "clicked";
-            else
-                myRect.state = "";
-        }
+    states: State {
+        name: "hidden"; when: mouseArea.pressed
+        PropertyChanges { target: myRect; opacity: 0 }
     }
 }
 //![0]
diff --git a/doc/src/snippets/declarative/transition-from-to.qml b/doc/src/snippets/declarative/transition-from-to.qml
new file mode 100644
index 0000000..615de17
--- /dev/null
+++ b/doc/src/snippets/declarative/transition-from-to.qml
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+import Qt 4.7
+
+//![0]
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    MouseArea { id: mouseArea; anchors.fill: parent }
+
+    states: State {
+        name: "brighter"; when: mouseArea.pressed
+        PropertyChanges { target: rect; color: "yellow" }
+    }
+
+    transitions: Transition { 
+        ColorAnimation { duration: 1000 }
+    }
+}
+//![0]
+
+
diff --git a/doc/src/snippets/declarative/transition-reversible.qml b/doc/src/snippets/declarative/transition-reversible.qml
new file mode 100644
index 0000000..8a7b69a
--- /dev/null
+++ b/doc/src/snippets/declarative/transition-reversible.qml
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+import Qt 4.7
+
+//![0]
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    MouseArea { id: mouseArea; anchors.fill: parent }
+
+    states: State {
+        name: "brighter"
+        when: mouseArea.pressed
+        PropertyChanges { target: rect; color: "yellow"; x: 50 }
+    }
+
+    transitions: Transition { 
+        SequentialAnimation {
+            PropertyAnimation { property: "x"; duration: 1000 }
+            ColorAnimation { duration: 1000 }
+        }
+    }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/transition.qml b/doc/src/snippets/declarative/transition.qml
new file mode 100644
index 0000000..b884750
--- /dev/null
+++ b/doc/src/snippets/declarative/transition.qml
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    states: State {
+        name: "moved"
+        PropertyChanges { target: rect; x: 50; y: 50 }
+    }
+
+    transitions: Transition { 
+        PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } 
+    }
+}
+//![0]
+