src/quick/doc/src/concepts/statesanimations/animations.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \ingroup qtquick-transitions-animations
  30 \page qtquick-statesanimations-animations.html
  31 \title Animation and Transitions in Qt Quick
  32 \brief the animation system in Qt Quick
  33
  34 \section1 Animation and Transitions Elements
  35 \generatelist{related}
  36 \list
  37 \li \l {Transition} - Animates transitions during state changes
  38 \li \l {SequentialAnimation} - Runs animations sequentially
  39 \li \l {ParallelAnimation} - Runs animations in parallel
  40 \li \l {Behavior} - Specifies a default animation for property changes
  41 \li \l {PropertyAction} - Sets immediate property changes during animation
  42 \li \l {PauseAnimation} - Introduces a pause in an animation
  43 \li \l {SmoothedAnimation} - Allows a property to smoothly track a value
  44 \li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
  45 \li \l {ScriptAction} - Runs scripts during an animation
  46 \endlist
  47
  48 Elements that animate properties based on data types
  49 \annotatedlist qtquick-animation-properties
  50 \list
  51 \li \l {PropertyAnimation} - Animates property changes
  52 \li \l {NumberAnimation} - Animates properties of type qreal
  53 \li \l {Vector3dAnimation} - Animates properties of type QVector3d
  54 \li \l {ColorAnimation} - Animates color changes
  55 \li \l {RotationAnimation} - Animates rotations
  56 \li \l {ParentAnimation} - Animates parent changes
  57 \li \l {AnchorAnimation} - Animates anchor changes
  58 \endlist
  59
  60 Animations are created by applying animation elements to property
  61 values. Animation elements will interpolate property values to create smooth
  62 transitions. As well, state transitions may assign animations to state changes.
  63
  64 To create an animation, use an appropriate animation element for the type of
  65 the property that is to be animated, and apply the animation depending on the
  66 type of behavior that is required.
  67
  68 \section1 Triggering Animations
  69
  70 There are several ways of setting animation to an object.
  71
  72 \section2 Direct Property Animation
  73
  74 Animations are created by applying animation objects to property values to
  75 gradually change the properties over time. These \e {property animations} apply
  76 smooth movements by interpolating values between property value changes. Property
  77 animations provide timing controls and allows different interpolations through
  78 \l{qml-easing-animation}{easing curves}.
  79
  80 \snippet qml/animation.qml property animation
  81
  82 Specialized \l{qml-property-animation-elements}{property animation elements}
  83 have more efficient implementations than the \l{PropertyAnimation} element. They
  84 are for setting animations to different QML types such as \c int, \c color, and
  85 rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
  86
  87 See the \l {qml-controlling-animations}{Controlling Animations} section for more
  88 information about the different animation properties.
  89
  90
  91 \section2 Using Predefined Targets and Properties
  92
  93 In the previous example, the PropertyAnimation and NumberAnimation objects needed
  94 to specify particular \l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{properties}
  95 values to specify the objects and properties that should be animated. This can be
  96 avoided by using the \e {<Animation> on <Property>} syntax, which specifies the
  97 animation is to be applied as a \e {property value source}.
  98
  99 Below are two PropertyAnimation objects that are specified using this syntax:
 100
 101 \qml
 102 import QtQuick 2.0
 103
 104 Rectangle {
 105     id: rect
 106     width: 100; height: 100
 107     color: "red"
 108
 109     PropertyAnimation on x { to: 100 }
 110     PropertyAnimation on y { to: 100 }
 111 }
 112 \endqml
 113
 114 The animation starts as soon as the rectangle is loaded, and will automatically be
 115 applied to its \c x and \c y values. Since the \e {<Animation> on <Property>}
 116 syntax has been used, it is not necessary to set the
 117 \l {PropertyAnimation::}{target} value of the PropertyAnimation objects to
 118 \c rect, and neither is it necessary to set the \l {PropertyAnimation::}{property}
 119 values to \c x and \c y.
 120
 121 This can also be used by \l{Playing Animations in Parallel or in Sequence}
 122 {grouped animations} to ensure that all animations within a group are applied to
 123 the same property.  For example, the previous example could instead use
 124 SequentialAnimation to animate the rectangle's \c color first to yellow, then
 125 to blue:
 126
 127 \qml
 128 import QtQuick 2.0
 129
 130 Rectangle {
 131     width: 100; height: 100
 132     color: "red"
 133
 134     SequentialAnimation on color {
 135         ColorAnimation { to: "yellow"; duration: 1000 }
 136         ColorAnimation { to: "blue"; duration: 1000 }
 137     }
 138 }
 139 \endqml
 140
 141 Since the SequentialAnimation object has been specified on the \c color property
 142 using the \e {<Animation> on <Property>} syntax, its child ColorAnimation objects
 143 are also automatically applied to this property and do not need to specify
 144 \l {PropertyAnimation::}{target} or \l {PropertyAnimation::}{property} animation
 145 values.
 146
 147
 148 \keyword qml-transition-animations
 149 \section2 Transitions during State Changes
 150
 151 \l{State}{Qt Quick States} are property configurations where a property may have different values to reflect different states. State changes introduce
 152 abrupt property changes; animations smooth transitions to produce visually
 153 appealing state changes.
 154
 155 The \l{Transition} element can contain
 156 \l{qml-animation-elements}{animation elements} to interpolate property changes
 157 caused by state changes. To assign the transition to an object, bind it to the
 158 \c transitions property.
 159
 160 A button might have two states, the \c pressed state when the user clicks on the
 161 button and a \c released state when the user releases the button. We can assign
 162 different property configurations for each state. A transition would animate the
 163 change from the \c pressed state to the \c released state. Likewise, there would
 164 be an animation during the change from the \c released state to the \c pressed
 165 state.
 166
 167 \snippet qml/animation.qml transition animation
 168
 169 Binding the \c to and \c from properties to the state's name will assign that
 170 particular transition to the state change. For simple or symmetric transitions,
 171 setting the to \c to property to the wild card symbol, "\c{*}", denotes
 172 that the transition applies to any state change.
 173
 174 \snippet qml/animation.qml wildcard animation
 175
 176 \section2 Default Animation as Behaviors
 177
 178 Default property animations are set using \e {behavior animations}. Animations
 179 declared in \l {Behavior} elements apply to the property and animates any
 180 property value changes. However, Behavior elements have an
 181 \c enabled property to purposely enable or disable the behavior animations.
 182
 183 A ball component might have a behavior animation assigned to its \c x, \c y, and
 184 \c color properties. The behavior animation could be set up to simulate an
 185 elastic effect. In effect, this behavior animation would apply the elastic
 186 effect to the properties whenever the ball moves.
 187
 188 \snippet qml/animation.qml behavior animation
 189
 190 There are several methods of assigning behavior animations to properties. The
 191 \c{Behavior on <property>} declaration is a convenient way of assigning a
 192 behavior animation onto a property.
 193
 194 See the \l {declarative/animation/behaviors}{Behaviors example} for a
 195 demonstration of behavioral animations.
 196
 197 \section1 Playing Animations in Parallel or in Sequence
 198
 199 Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
 200 will play a group of animations at the same time while sequential animations
 201 play a group of animations in order: one after the other. Grouping animations in
 202 \l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
 203 sequence or in parallel.
 204
 205 A banner component may have several icons or slogans to display, one after the
 206 other. The \c opacity property could transform to \c 1.0 denoting an opaque
 207 object. Using the \l{SequentialAnimation} element, the opacity animations will
 208 play after the preceding animation finishes. The \l{ParallelAnimation} element
 209 will play the animations at the same time.
 210
 211 \snippet qml/animation.qml sequential animation
 212
 213 Once individual animations are placed into a SequentialAnimation or
 214 ParallelAnimation, they can no longer be started and stopped independently. The
 215 sequential or parallel animation must be started and stopped as a group.
 216
 217 The \l SequentialAnimation element is also useful for playing
 218 \l{qml-transition-animations}{transition animations} because animations are
 219 played in parallel inside transitions.
 220
 221 See the \l {declarative/animation/basics}{Animation basics example} for a
 222 demonstration of creating and combining multiple animations in QML.
 223
 224 \keyword qml-controlling-animations
 225 \section1 Controlling Animations
 226
 227 There are different methods to control animations.
 228
 229 \section2 Animation Playback
 230 All animation types inherit from the \l Animation element. It is not
 231 possible to create \l Animation objects; instead, this element provides the
 232 essential properties and methods for animation elements. Animation elements have
 233 \c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
 234 \c{complete()} -- all of these methods control the execution of animations.
 235
 236 \keyword qml-easing-animation
 237 \section2 Easing
 238
 239 Easing curves define how the animation will interpolate between the start value
 240 and the end value. Different easing curves might go beyond the defined range of
 241 interpolation. The easing curves simplify the creation of animation effects such
 242 as bounce effects, acceleration, deceleration, and cyclical animations.
 243
 244 A QML object may have different easing curve for each property animation. There
 245 are also different parameters to control the curve, some of which are exclusive
 246 to a particular curve. For more information about the easing curves, visit the
 247 \l {PropertyAnimation::easing.type}{easing} documentation.
 248
 249 The \l{declarative/animation/easing}{easing example} visually demonstrates each
 250 of the different easing types.
 251
 252 \section2 Other Animation Elements
 253
 254 In addition, QML provides several other elements useful for animation:
 255
 256 \list
 257 \li PauseAnimation: enables pauses during animations
 258 \li ScriptAction: allows JavaScript to be executed during an animation, and can
 259 be used together with StateChangeScript to reused existing scripts
 260 \li PropertyAction: changes a property \e immediately during an animation,
 261 without animating the property change
 262 \endlist
 263
 264 These are specialized animation elements that animate different property types
 265 \list
 266 \li SmoothedAnimation: a specialized NumberAnimation that provides smooth
 267 changes in animation when the target value changes
 268 \li SpringAnimation: provides a spring-like animation with specialized
 269 attributes such as \l {SpringAnimation::}{mass},
 270 \l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
 271 \li ParentAnimation: used for animating a parent change (see ParentChange)
 272 \li AnchorAnimation: used for animating an anchor change (see AnchorChanges)
 273 \endlist
 274
 275 \section1 Sharing Animation Instances
 276
 277 Sharing animation instances between Transitions or Behaviors is not
 278 supported, and may lead to undefined behavior. In the following example,
 279 changes to the Rectangle's position will most likely not be correctly animated.
 280
 281 \qml
 282 Rectangle {
 283     // NOT SUPPORTED: this will not work correctly as both Behaviors
 284     // try to control a single animation instance
 285     NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
 286     Behavior on x { animation: anim }
 287     Behavior on y { animation: anim }
 288 }
 289 \endqml
 290
 291 The easiest fix is to repeat the NumberAnimation for both Behaviors. If the repeated
 292 animation is rather complex, you might also consider creating a custom animation
 293 component and assigning an instance to each Behavior, for example:
 294
 295 \qml
 296 // MyNumberAnimation.qml
 297 NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
 298 \endqml
 299
 300 \qml
 301 // main.qml
 302 Rectangle {
 303     Behavior on x { MyNumberAnimation {} }
 304     Behavior on y { MyNumberAnimation {} }
 305 }
 306 \endqml
 307
 308 */
 309
 310 /*!
 311 \ingroup qtquick-animation-properties
 312 \title Qt Quick Property Animation
 313 \brief Animate property changes
 314
 315 \generatelist{related}
 316 */
 317
 318 /*!
 319 \ingroup qtquick-animation-control
 320 \title Qt Quick Animation Controls
 321 \brief Control animation sequences
 322
 323 \generatelist{related}
 324 */
 325
 326 /*!
 327 \ingroup qtquick-animation-modifiers
 328 \title Qt Quick Animation Modifiers
 329 \brief Modify animation sequences
 330
 331 \generatelist{related}
 332 */