Reorganize "concept" pages in QtQuick docs

This removes concepts/topic.qdoc and move this content into individual
concept topic pages under individual directories for each concept to
avoid having a really long "concepts" index page.

This change also:
- Moves components.qdoc ("Defining reusable components") into the
 appdevguide/ since it's not specific to QtQuick features - it's more
 about how to use a QtQml feature to build QML apps.
- Moves the part of qtqml/doc/src/cppintegration/data.qdoc that
 discusses how to use C++ models with QtQuick views into
 quick/doc/src/concepts/modelviewsdata/data-cppmodels.qdoc.

Change-Id: Id18a1d56acaaac41714c13cbc94bb3b80f337355
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

1 files changed, 207 insertions, 0 deletions

diff --git a/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc b/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc
new file mode 100644
index 0000000000..a513aaad0c
--- /dev/null
+++ b/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc
@@ -0,0 +1,207 @@
+/****************************************************************************
+**
+** 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:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtquick-statesanimations-behaviors.html
+\title Using Qt Quick Behaviors with States
+\brief animating property changes with behaviors
+
+\section1 Using Behaviors with States
+
+In some cases you may choose to use a Behavior to animate a property change caused by a state change. While this works well for some situations, in other situations it may lead to unexpected behavior.
+
+Here's an example that shows the problem:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Rectangle {
+        id: coloredRect
+        width: 100
+        height: 100
+        anchors.centerIn: parent
+
+        color: "red"
+        Behavior on color {
+            ColorAnimation {}
+        }
+
+        MouseArea {
+            id: mouser
+            anchors.fill: parent
+            hoverEnabled: true
+        }
+
+        states: State {
+            name: "GreenState"
+            when: mouser.containsMouse
+
+            PropertyChanges {
+                target: coloredRect
+                color: "green"
+            }
+        }
+    }
+}
+\endqml
+
+Testing the example by quickly and repeatedly moving the mouse in to and out of the colored rectangle shows that the colored rectangle will settle into a green color over time, never returning to full red. This is not what we wanted! The
+problem occurs because we have used a Behavior to animate the change in color, and our state change is trigged by the mouse entering or exiting the MouseArea, which is easily interrupted.
+
+To state the problem more formally, using States and Behaviors together can cause unexpected behavior when:
+\list
+\li a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and
+\li this Behavior can be interrupted to (re-)enter an explicitly defined state.
+\endlist
+
+The problem occurs because of the way the base state is defined for QML: as the "snapshot" state of the application just prior to entering an explicitly defined state. In this case, if we are in the process of animating from green back
+to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form.
+
+While future versions of QML should be able to handle this situation more gracefully, there are currently several ways to rework your application to avoid this problem.
+
+1. Use a transition to animate the change, rather than a Behavior.
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Rectangle {
+        id: coloredRect
+        width: 100
+        height: 100
+        anchors.centerIn: parent
+
+        color: "red"
+
+        MouseArea {
+            id: mouser
+            anchors.fill: parent
+            hoverEnabled: true
+        }
+
+        states: State {
+            name: "GreenState"
+            when: mouser.containsMouse
+
+            PropertyChanges {
+                target: coloredRect
+                color: "green"
+            }
+        }
+
+        transitions: Transition {
+            ColorAnimation {}
+        }
+    }
+}
+\endqml
+
+2. Use a conditional binding to change the property value, rather than a state
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Rectangle {
+        id: coloredRect
+        width: 100
+        height: 100
+        anchors.centerIn: parent
+
+        color: mouser.containsMouse ? "green" : "red"
+        Behavior on color {
+            ColorAnimation {}
+        }
+
+        MouseArea {
+            id: mouser
+            anchors.fill: parent
+            hoverEnabled: true
+        }
+    }
+}
+\endqml
+
+3. Use only explicitly defined states, rather than an implicit base state
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 400
+    height: 400
+
+    Rectangle {
+        id: coloredRect
+        width: 100
+        height: 100
+        anchors.centerIn: parent
+
+        Behavior on color {
+            ColorAnimation {}
+        }
+
+        MouseArea {
+            id: mouser
+            anchors.fill: parent
+            hoverEnabled: true
+        }
+
+        states: [
+        State {
+            name: "GreenState"
+            when: mouser.containsMouse
+
+            PropertyChanges {
+                target: coloredRect
+                color: "green"
+            }
+        },
+        State {
+            name: "RedState"
+            when: !mouser.containsMouse
+
+            PropertyChanges {
+                target: coloredRect
+                color: "red"
+            }
+        }]
+    }
+}
+\endqml
+
+*/