Add docs for "animation on property" syntax and fix topic page

Also the "States and Animations" topic page doesn't need a section for
behaviors since these are described on the "Animations and
Transitions in Qt Quick" page.

Task-number: QTBUG-20324
Change-Id: I46259402b8790df3aba9717f77fafef9f27a8d44
Reviewed-by: Damian Jansen <damian.jansen@nokia.com>

diff --git a/src/quick/doc/src/concepts/statesanimations/animations.qdoc b/src/quick/doc/src/concepts/statesanimations/animations.qdoc
index 65e3a01..b9dfdd2 100644 (file)
--- a/src/quick/doc/src/concepts/statesanimations/animations.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/animations.qdoc
@@ -71,14 +71,10 @@ 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
+Animations are created by applying animation objects to property values to
+gradually change the properties over time. These \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
@@ -91,6 +87,64 @@ 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.
 
+
+\section2 Using Predefined Targets and Properties
+
+In the previous example, the PropertyAnimation and NumberAnimation objects needed
+to specify particular \l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{properties}
+values to specify the objects and properties that should be animated. This can be
+avoided by using the \e {<Animation> on <Property>} syntax, which specifies the
+animation is to be applied as a \e {property value source}.
+
+Below are two PropertyAnimation objects that are specified using this syntax:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    PropertyAnimation on x { to: 100 }
+    PropertyAnimation on y { to: 100 }
+}
+\endqml
+
+The animation starts as soon as the rectangle is loaded, and will automatically be
+applied to its \c x and \c y values. Since the \e {<Animation> on <Property>}
+syntax has been used, it is not necessary to set the
+\l {PropertyAnimation::}{target} value of the PropertyAnimation objects to
+\c rect, and neither is it necessary to set the \l {PropertyAnimation::}{property}
+values to \c x and \c y.
+
+This can also be used by \l{Playing Animations in Parallel or in Sequence}
+{grouped animations} to ensure that all animations within a group are applied to
+the same property.  For example, the previous example could instead use
+SequentialAnimation to animate the rectangle's \c color first to yellow, then
+to blue:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+
+    SequentialAnimation on color {
+        ColorAnimation { to: "yellow"; duration: 1000 }
+        ColorAnimation { to: "blue"; duration: 1000 }
+    }
+}
+\endqml
+
+Since the SequentialAnimation object has been specified on the \c color property
+using the \e {<Animation> on <Property>} syntax, its child ColorAnimation objects
+are also automatically applied to this property and do not need to specify
+\l {PropertyAnimation::}{target} or \l {PropertyAnimation::}{property} animation
+values.
+
+
 \keyword qml-transition-animations
 \section2 Transitions during State Changes
 

diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
index f4c5e89..e909dbc 100644 (file)
--- a/src/quick/doc/src/concepts/statesanimations/topic.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
@@ -90,30 +90,6 @@ and transition elements.  See the documentation on
 and how to use them.
 
 
-\section1 Animating Property Assignments
-
-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).  Qt Quick provides the \l Behavior type which allows the client to
-specify animation behavior for changes to properties.  The \l Behavior type
-is an example of a QML object
-\l{qtqml-typesystem-topic.html#property-modifier-types}{property modifier}.
-
-Please see the documentation about
-\l{qtquick-statesanimations-animations.html#default-animation-as-behaviors}
-{default property animations} for more information about using the \l Behavior
-element to provide default property change animations.
-
-It is important to note, that using default property animations (via the
-\l Behavior type) in combination with state-transition animations can sometimes
-result 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