From b32406ed8069352d2120aff11c0da172848bdda4 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Fri, 24 Aug 2012 14:09:36 +1000 Subject: [PATCH 1/1] 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 --- .../src/concepts/statesanimations/animations.qdoc | 70 +++++++++++++++++++--- .../doc/src/concepts/statesanimations/topic.qdoc | 24 -------- 2 files changed, 62 insertions(+), 32 deletions(-) diff --git a/src/quick/doc/src/concepts/statesanimations/animations.qdoc b/src/quick/doc/src/concepts/statesanimations/animations.qdoc index 65e3a01..b9dfdd2 100644 --- 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 { on } 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 { on } +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 { on } 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 --- 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 -- 2.7.4