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>

4 files changed, 753 insertions, 0 deletions

diff --git a/src/quick/doc/src/concepts/statesanimations/animations.qdoc b/src/quick/doc/src/concepts/statesanimations/animations.qdoc
new file mode 100644
index 0000000000..bb0a6506e5
--- /dev/null
+++ b/src/quick/doc/src/concepts/statesanimations/animations.qdoc
@@ -0,0 +1,278 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\group qtquick-transitions-animations
+\page qtquick-statesanimations-animations.html
+\title Animation and Transitions In Qt Quick
+\brief the animation system in Qt Quick
+
+\section1 Animation and Transitions Elements
+\generatelist{related}
+\list
+\li \l {Transition} - Animates transitions during state changes
+\li \l {SequentialAnimation} - Runs animations sequentially
+\li \l {ParallelAnimation} - Runs animations in parallel
+\li \l {Behavior} - Specifies a default animation for property changes
+\li \l {PropertyAction} - Sets immediate property changes during animation
+\li \l {PauseAnimation} - Introduces a pause in an animation
+\li \l {SmoothedAnimation} - Allows a property to smoothly track a value
+\li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
+\li \l {ScriptAction} - Runs scripts during an animation
+\endlist
+
+Elements that animate properties based on data types
+\annotatedlist qtquick-animation-properties
+\list
+\li \l {PropertyAnimation} - Animates property changes
+\li \l {NumberAnimation} - Animates properties of type qreal
+\li \l {Vector3dAnimation} - Animates properties of type QVector3d
+\li \l {ColorAnimation} - Animates color changes
+\li \l {RotationAnimation} - Animates rotations
+\li \l {ParentAnimation} - Animates parent changes
+\li \l {AnchorAnimation} - Animates anchor changes
+\endlist
+
+Animations are created by applying animation elements to property
+values. Animation elements will interpolate property values to create smooth
+transitions. As well, state transitions may assign animations to state changes.
+
+To create an animation, use an appropriate animation element for the type of
+the property that is to be animated, and apply the animation depending on the
+type of behavior that is required.
+
+\section1 Triggering Animations
+
+There are several ways of setting animation to an object.
+
+\section2 Direct Property Animation
+
+To create an immediate movement or animated movement, set the property value
+directly. This may be done in signal handlers or attached properties.
+
+\snippet qml/animation.qml direct property change
+
+However, to create more control, \e {property animations} apply smooth movements
+by interpolating values between property value changes. Property animations
+provide timing controls and allows different interpolations through
+\l{qml-easing-animation}{easing curves}.
+
+\snippet qml/animation.qml property animation
+
+Specialized \l{qml-property-animation-elements}{property animation elements}
+have more efficient implementations than the \l{PropertyAnimation} element. They
+are for setting animations to different QML types such as \c int, \c color, and
+rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
+
+See the \l {qml-controlling-animations}{Controlling Animations} section for more
+information about the different animation properties.
+
+\keyword qml-transition-animations
+\section2 Transitions during State Changes
+
+\l{State}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
+abrupt property changes; animations smooth transitions to produce visually
+appealing state changes.
+
+The \l{Transition} element can contain
+\l{qml-animation-elements}{animation elements} to interpolate property changes
+caused by state changes. To assign the transition to an object, bind it to the
+\c transitions property.
+
+A button might have two states, the \c pressed state when the user clicks on the
+button and a \c released state when the user releases the button. We can assign
+different property configurations for each state. A transition would animate the
+change from the \c pressed state to the \c released state. Likewise, there would
+be an animation during the change from the \c released state to the \c pressed
+state.
+
+\snippet qml/animation.qml transition animation
+
+Binding the \c to and \c from properties to the state's name will assign that
+particular transition to the state change. For simple or symmetric transitions,
+setting the to \c to property to the wild card symbol, "\c{*}", denotes
+that the transition applies to any state change.
+
+\snippet qml/animation.qml wildcard animation
+
+\section2 Default Animation as Behaviors
+
+Default property animations are set using \e {behavior animations}. Animations
+declared in \l {Behavior} elements apply to the property and animates any
+property value changes. However, Behavior elements have an
+\c enabled property to purposely enable or disable the behavior animations.
+
+A ball component might have a behavior animation assigned to its \c x, \c y, and
+\c color properties. The behavior animation could be set up to simulate an
+elastic effect. In effect, this behavior animation would apply the elastic
+effect to the properties whenever the ball moves.
+
+\snippet qml/animation.qml behavior animation
+
+There are several methods of assigning behavior animations to properties. The
+\c{Behavior on <property>} declaration is a convenient way of assigning a
+behavior animation onto a property.
+
+See the \l {declarative/animation/behaviors}{Behaviors example} for a
+demonstration of behavioral animations.
+
+\section1 Playing Animations in Parallel or in Sequence
+
+Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
+will play a group of animations at the same time while sequential animations
+play a group of animations in order: one after the other. Grouping animations in
+\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
+sequence or in parallel.
+
+A banner component may have several icons or slogans to display, one after the
+other. The \c opacity property could transform to \c 1.0 denoting an opaque
+object. Using the \l{SequentialAnimation} element, the opacity animations will
+play after the preceding animation finishes. The \l{ParallelAnimation} element
+will play the animations at the same time.
+
+\snippet qml/animation.qml sequential animation
+
+Once individual animations are placed into a SequentialAnimation or
+ParallelAnimation, they can no longer be started and stopped independently. The
+sequential or parallel animation must be started and stopped as a group.
+
+The \l SequentialAnimation element is also useful for playing
+\l{qml-transition-animations}{transition animations} because animations are
+played in parallel inside transitions.
+
+See the \l {declarative/animation/basics}{Animation basics example} for a
+demonstration of creating and combining multiple animations in QML.
+
+\keyword qml-controlling-animations
+\section1 Controlling Animations
+
+There are different methods to control animations.
+
+\section2 Animation Playback
+All animation types inherit from the \l Animation element. It is not
+possible to create \l Animation objects; instead, this element provides the
+essential properties and methods for animation elements. Animation elements have
+\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
+\c{complete()} -- all of these methods control the execution of animations.
+
+\keyword qml-easing-animation
+\section2 Easing
+
+Easing curves define how the animation will interpolate between the start value
+and the end value. Different easing curves might go beyond the defined range of
+interpolation. The easing curves simplify the creation of animation effects such
+as bounce effects, acceleration, deceleration, and cyclical animations.
+
+A QML object may have different easing curve for each property animation. There
+are also different parameters to control the curve, some of which are exclusive
+to a particular curve. For more information about the easing curves, visit the
+\l {PropertyAnimation::easing.type}{easing} documentation.
+
+The \l{declarative/animation/easing}{easing example} visually demonstrates each
+of the different easing types.
+
+\section2 Other Animation Elements
+
+In addition, QML provides several other elements useful for animation:
+
+\list
+\li PauseAnimation: enables pauses during animations
+\li ScriptAction: allows JavaScript to be executed during an animation, and can
+be used together with StateChangeScript to reused existing scripts
+\li PropertyAction: changes a property \e immediately during an animation,
+without animating the property change
+\endlist
+
+These are specialized animation elements that animate different property types
+\list
+\li SmoothedAnimation: a specialized NumberAnimation that provides smooth
+changes in animation when the target value changes
+\li SpringAnimation: provides a spring-like animation with specialized
+attributes such as \l {SpringAnimation::}{mass},
+\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
+\li ParentAnimation: used for animating a parent change (see ParentChange)
+\li AnchorAnimation: used for animating an anchor change (see AnchorChanges)
+\endlist
+
+\section1 Sharing Animation Instances
+
+Sharing animation instances between Transitions or Behaviors is not
+supported, and may lead to undefined behavior. In the following example,
+changes to the Rectangle's position will most likely not be correctly animated.
+
+\qml
+Rectangle {
+    // NOT SUPPORTED: this will not work correctly as both Behaviors
+    // try to control a single animation instance
+    NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
+    Behavior on x { animation: anim }
+    Behavior on y { animation: anim }
+}
+\endqml
+
+The easiest fix is to repeat the NumberAnimation for both Behaviors. If the repeated
+animation is rather complex, you might also consider creating a custom animation
+component and assigning an instance to each Behavior, for example:
+
+\qml
+// MyNumberAnimation.qml
+NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
+\endqml
+
+\qml
+// main.qml
+Rectangle {
+    Behavior on x { MyNumberAnimation {} }
+    Behavior on y { MyNumberAnimation {} }
+}
+\endqml
+
+*/
+
+/*!
+\group qtquick-animation-properties
+\title Qt Quick Property Animation
+\brief Animate property changes
+
+\generatelist{related}
+*/
+
+/*!
+\group qtquick-animation-control
+\title Qt Quick Animation Controls
+\brief Control animation sequences
+
+\generatelist{related}
+*/
+
+/*!
+\group qtquick-animation-modifiers
+\title Qt Quick Animation Modifiers
+\brief Modify animation sequences
+
+\generatelist{related}
+*/
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
+
+*/
diff --git a/src/quick/doc/src/concepts/statesanimations/states.qdoc b/src/quick/doc/src/concepts/statesanimations/states.qdoc
new file mode 100644
index 0000000000..e3ac12549c
--- /dev/null
+++ b/src/quick/doc/src/concepts/statesanimations/states.qdoc
@@ -0,0 +1,150 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+\group qtquick-states
+\page qtquick-statesanimations-states.html
+\title Qt Quick States
+\brief Creating and setting states
+
+\section1 Related Types
+\generatelist{related}
+
+Many user interface designs are \e{state driven}; interfaces have configurations
+that differ depending on the current state. For example, a traffic signal will
+configure its flags or lights depending on its state. While in the signal's
+\c stop state, a red light will turn on while the yellow and the green lights
+will turn off. In the \c caution state, the yellow light is on while the other
+lights are turned off.
+
+In QML, \e states are a set of property configurations defined in a \l State
+element. Different configurations could, for example:
+
+\list
+\li Show some UI elements and hide others
+\li Present different available actions to the user
+\li Start, stop, or pause animations
+\li Execute some script required in the new state
+\li Change a property value for a particular item
+\li Show a different view or screen
+\endlist
+
+All \l {Item}-based objects have a \c state property, and can specify additional
+states by adding new \c State objects to the item's \l {Item::}{states}
+property. Each state within a component has a unique \c name, an empty string
+being the default. To change the current state
+of an item, set the \l {Item::}{state} property to the name of the state.
+
+Non-Item objects may use states through the \l StateGroup element.
+
+\section1 Creating States
+
+To create a state, add a \l State object to the item's \l {Item::}{states} property,
+which holds a list of states for that item.
+
+A warning \c signal component may have two states, the \c NORMAL and the
+\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the
+signal should be \c green and the warning \c flag is down. Meanwhile, in the
+\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may
+model the states using the \c State element and the color and flag
+configurations with the \c PropertyChanges element.
+\snippet qml/states.qml signal states
+The \l PropertyChanges element will change the values of object properties.
+Objects are referenced through their
+\l{qtqml-syntax-objectattributes.html#the-id-assignment}{id}. Objects outside
+the component are also referenced using the \c id property, exemplified by the
+property change to the external \c flag object.
+
+Further, the state may change by assigning the \c state property with the
+appropriate signal state. A state switch could be in a \l MouseArea element,
+assigning a different state whenever the signal receives a mouse click.
+\snippet qml/states.qml switch states
+
+The State element is not limited to performing modifications on property values.
+It can also:
+\list
+\li Run some script using \l StateChangeScript
+\li Override an existing signal handler for an object using \l PropertyChanges
+\li Re-parent an \l Item using \l ParentChange
+\li Modify anchor values using \l AnchorChanges
+\endlist
+
+\section1 The Default State
+
+Every \l Item based component has a \c state property and a \e{default state}.
+The default state is the empty string (\c{""}) and contains all of an item's
+initial property values. The default state is useful for managing property
+values before state changes. Setting the \c state property to an empty string
+will load the default state.
+
+\section1 The \c when Property
+
+For convenience, the \l State element has a \c when property that can bind to
+expressions to change the state whenever the bound expression evaluates to
+\c true. The \c when property will revert the state back to the
+\l {The Default State}{default state} when the expression evaluates to false.
+
+\snippet qml/states.qml when property
+The \c bell component will change to the \c RINGING state whenever the
+\c signal.state is \c CRITICAL.
+
+\section1 Animating State Changes
+
+State changes induce abrupt value changes. The \l Transition element allow
+smoother changes during state changes. In transitions, animations and
+interpolation behaviors are definable. The
+\l{qtquick-statesanimations-animations.html}
+{Animation and Transitions} article has more information about creating state
+animations.
+
+The \l {declarative/animation/states}{States and Transitions example}
+demonstrates how to declare a basic set of states and apply animated
+transitions between them.
+
+\l{qtquick-statesanimations-behaviors.html}{Using QML Behaviors with States}
+explains a common problem when using Behaviors to animate state changes.
+
+\section1 State Fast Forwarding
+
+In order for Transition to correctly animate state changes, it is sometimes necessary
+for the engine to fast forward and rewind a state (that is, internally set and unset the state)
+before it is finally applied. The process is as follows:
+
+\list 1
+\li The state is fast forwarded to determine the complete set of end values.
+\li The state is rewound.
+\li The state is fully applied, with transitions.
+\endlist
+
+In some cases this may cause unintended behavior. For example, a state that changes
+a view's \e model or a Loader's \e sourceComponent will set these properties
+multiple times (to apply, rewind, and then reapply), which can be relatively expensive.
+
+State fast forwarding should be considered an implementation detail,
+and may change in later versions.
+
+*/
diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
new file mode 100644
index 0000000000..8ca02fd444
--- /dev/null
+++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
@@ -0,0 +1,118 @@
+/****************************************************************************
+**
+** 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-topic.html
+\title Concepts - States And Animations
+\brief Description of the concepts of states, transitions and animations in Qt Quick
+
+In any modern user-interface, transitioning between states and animating
+the user-interface is highly beneficial.  These are first-class concepts in
+Qt Quick.
+
+This page describes the concept of states, state transitions, and property
+animations.  It details which concepts are important and why, and how those
+concepts interrelate.  It also provides links to in-depth detail about the QML
+types that Qt Quick provides to implement those concepts.
+
+\section1 States
+
+The state of a particular visual item is the set of information which describes
+how and where the individual component parts of the visual item are displayed
+within it, and all the data associated with that state.  Most visual items in a
+user-interface will have a limited number of states, each with well-defined
+properties.
+
+For example, an element in a list may be either selected or not, and if
+selected, it may either be the currently active single selection or it may be
+part of a selection group.
+
+Each of those states may have certain associated visual appearance (neutral,
+highlighted, expanded, and so forth).
+
+Qt Quick provides a \c{State} element with properties which define its semantics
+and can be used to trigger behavior or animations.  See the documentation about
+\l{qtquick-statesanimations-states.html}{Qt Quick States} for more
+information.
+
+\section1 Transitions
+
+When a visual item transitions from one state to another, the appearance of
+that item will change.  A transition is an "edge" between two states.  It may
+trigger other events to occur, as other parts of the application may have
+behavior which is triggered when a certain state is entered or left.
+
+Qt Quick provides the \c{Transition} element which has properties which define
+what will occur when the application changes from one state to another.  See
+the documentation on
+\l{qtquick-statesanimations-animations.html#transitions-during-state-changes}
+{Transitions during State Changes} for more information about transitions.
+
+\section1 Animations
+
+When transitioning between states, a fluid animation can be used to aid the
+user during the transition.  Abrupt and unexpected changes to the visual
+canvas result in a suboptimal user-experience and should be avoided.
+
+If an element in a list becomes selected, the color change (from neutral to
+highlighted) can be animated.  If the position of the element in the list is
+changed, it can be moved in an fluidly animated fashion so that the eye of the
+user can track the change.
+
+These types of animations are supported in Qt Quick through various animation
+and transition elements.  See the documentation on
+\l{qtquick-statesanimations-animations.html}
+{Animations and Transitions In Qt Quick} for information about these elements
+and how to use them.
+
+Animations are not only related to states and transitions between states; for
+example, an animation might be triggered by other events, which are not
+associated with a distinct state.  It is often beneficial to always animate
+changes to certain properties of visual items, regardless of the cause of the
+change (for example, opacity effects).
+
+This type of animation is supported in Qt Quick with the \c{Behavior} element
+through the \tt{"Behavior on <Property>"} syntax.  Please see the documentation
+about
+\l{qtquick-statesanimations-animations.html#default-animation-as-behaviors}
+{default property animation behaviors} for more information about the Behavior
+element and how to use it.
+
+It is important to note, however, that using default property animations
+(using Behavior elements) as well as state-transition animations can sometimes
+results in undefined behavior occurring.  Please see the documentation about
+\l{qtquick-statesanimations-behaviors.html}
+{using Qt Quick Behaviors with States} for more information about this topic.
+
+\section1 Animated Sprites
+
+The concept of animated sprites is separate to the concept of animations as
+used elsewhere on this page.  If you want to create or use an animated image
+or sprite, please see the documentation about
+\l{qtquick-effects-sprites.html}{sprite animations}.
+
+*/