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 \group 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 To create an immediate movement or animated movement, set the property value
  75 directly. This may be done in signal handlers or attached properties.
  76
  77 \snippet qml/animation.qml direct property change
  78
  79 However, to create more control, \e {property animations} apply smooth movements
  80 by interpolating values between property value changes. Property animations
  81 provide timing controls and allows different interpolations through
  82 \l{qml-easing-animation}{easing curves}.
  83
  84 \snippet qml/animation.qml property animation
  85
  86 Specialized \l{qml-property-animation-elements}{property animation elements}
  87 have more efficient implementations than the \l{PropertyAnimation} element. They
  88 are for setting animations to different QML types such as \c int, \c color, and
  89 rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
  90
  91 See the \l {qml-controlling-animations}{Controlling Animations} section for more
  92 information about the different animation properties.
  93
  94 \keyword qml-transition-animations
  95 \section2 Transitions during State Changes
  96
  97 \l{State}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
  98 abrupt property changes; animations smooth transitions to produce visually
  99 appealing state changes.
 100
 101 The \l{Transition} element can contain
 102 \l{qml-animation-elements}{animation elements} to interpolate property changes
 103 caused by state changes. To assign the transition to an object, bind it to the
 104 \c transitions property.
 105
 106 A button might have two states, the \c pressed state when the user clicks on the
 107 button and a \c released state when the user releases the button. We can assign
 108 different property configurations for each state. A transition would animate the
 109 change from the \c pressed state to the \c released state. Likewise, there would
 110 be an animation during the change from the \c released state to the \c pressed
 111 state.
 112
 113 \snippet qml/animation.qml transition animation
 114
 115 Binding the \c to and \c from properties to the state's name will assign that
 116 particular transition to the state change. For simple or symmetric transitions,
 117 setting the to \c to property to the wild card symbol, "\c{*}", denotes
 118 that the transition applies to any state change.
 119
 120 \snippet qml/animation.qml wildcard animation
 121
 122 \section2 Default Animation as Behaviors
 123
 124 Default property animations are set using \e {behavior animations}. Animations
 125 declared in \l {Behavior} elements apply to the property and animates any
 126 property value changes. However, Behavior elements have an
 127 \c enabled property to purposely enable or disable the behavior animations.
 128
 129 A ball component might have a behavior animation assigned to its \c x, \c y, and
 130 \c color properties. The behavior animation could be set up to simulate an
 131 elastic effect. In effect, this behavior animation would apply the elastic
 132 effect to the properties whenever the ball moves.
 133
 134 \snippet qml/animation.qml behavior animation
 135
 136 There are several methods of assigning behavior animations to properties. The
 137 \c{Behavior on <property>} declaration is a convenient way of assigning a
 138 behavior animation onto a property.
 139
 140 See the \l {declarative/animation/behaviors}{Behaviors example} for a
 141 demonstration of behavioral animations.
 142
 143 \section1 Playing Animations in Parallel or in Sequence
 144
 145 Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
 146 will play a group of animations at the same time while sequential animations
 147 play a group of animations in order: one after the other. Grouping animations in
 148 \l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
 149 sequence or in parallel.
 150
 151 A banner component may have several icons or slogans to display, one after the
 152 other. The \c opacity property could transform to \c 1.0 denoting an opaque
 153 object. Using the \l{SequentialAnimation} element, the opacity animations will
 154 play after the preceding animation finishes. The \l{ParallelAnimation} element
 155 will play the animations at the same time.
 156
 157 \snippet qml/animation.qml sequential animation
 158
 159 Once individual animations are placed into a SequentialAnimation or
 160 ParallelAnimation, they can no longer be started and stopped independently. The
 161 sequential or parallel animation must be started and stopped as a group.
 162
 163 The \l SequentialAnimation element is also useful for playing
 164 \l{qml-transition-animations}{transition animations} because animations are
 165 played in parallel inside transitions.
 166
 167 See the \l {declarative/animation/basics}{Animation basics example} for a
 168 demonstration of creating and combining multiple animations in QML.
 169
 170 \keyword qml-controlling-animations
 171 \section1 Controlling Animations
 172
 173 There are different methods to control animations.
 174
 175 \section2 Animation Playback
 176 All animation types inherit from the \l Animation element. It is not
 177 possible to create \l Animation objects; instead, this element provides the
 178 essential properties and methods for animation elements. Animation elements have
 179 \c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
 180 \c{complete()} -- all of these methods control the execution of animations.
 181
 182 \keyword qml-easing-animation
 183 \section2 Easing
 184
 185 Easing curves define how the animation will interpolate between the start value
 186 and the end value. Different easing curves might go beyond the defined range of
 187 interpolation. The easing curves simplify the creation of animation effects such
 188 as bounce effects, acceleration, deceleration, and cyclical animations.
 189
 190 A QML object may have different easing curve for each property animation. There
 191 are also different parameters to control the curve, some of which are exclusive
 192 to a particular curve. For more information about the easing curves, visit the
 193 \l {PropertyAnimation::easing.type}{easing} documentation.
 194
 195 The \l{declarative/animation/easing}{easing example} visually demonstrates each
 196 of the different easing types.
 197
 198 \section2 Other Animation Elements
 199
 200 In addition, QML provides several other elements useful for animation:
 201
 202 \list
 203 \li PauseAnimation: enables pauses during animations
 204 \li ScriptAction: allows JavaScript to be executed during an animation, and can
 205 be used together with StateChangeScript to reused existing scripts
 206 \li PropertyAction: changes a property \e immediately during an animation,
 207 without animating the property change
 208 \endlist
 209
 210 These are specialized animation elements that animate different property types
 211 \list
 212 \li SmoothedAnimation: a specialized NumberAnimation that provides smooth
 213 changes in animation when the target value changes
 214 \li SpringAnimation: provides a spring-like animation with specialized
 215 attributes such as \l {SpringAnimation::}{mass},
 216 \l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
 217 \li ParentAnimation: used for animating a parent change (see ParentChange)
 218 \li AnchorAnimation: used for animating an anchor change (see AnchorChanges)
 219 \endlist
 220
 221 \section1 Sharing Animation Instances
 222
 223 Sharing animation instances between Transitions or Behaviors is not
 224 supported, and may lead to undefined behavior. In the following example,
 225 changes to the Rectangle's position will most likely not be correctly animated.
 226
 227 \qml
 228 Rectangle {
 229     // NOT SUPPORTED: this will not work correctly as both Behaviors
 230     // try to control a single animation instance
 231     NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
 232     Behavior on x { animation: anim }
 233     Behavior on y { animation: anim }
 234 }
 235 \endqml
 236
 237 The easiest fix is to repeat the NumberAnimation for both Behaviors. If the repeated
 238 animation is rather complex, you might also consider creating a custom animation
 239 component and assigning an instance to each Behavior, for example:
 240
 241 \qml
 242 // MyNumberAnimation.qml
 243 NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
 244 \endqml
 245
 246 \qml
 247 // main.qml
 248 Rectangle {
 249     Behavior on x { MyNumberAnimation {} }
 250     Behavior on y { MyNumberAnimation {} }
 251 }
 252 \endqml
 253
 254 */
 255
 256 /*!
 257 \group qtquick-animation-properties
 258 \title Qt Quick Property Animation
 259 \brief Animate property changes
 260
 261 \generatelist{related}
 262 */
 263
 264 /*!
 265 \group qtquick-animation-control
 266 \title Qt Quick Animation Controls
 267 \brief Control animation sequences
 268
 269 \generatelist{related}
 270 */
 271
 272 /*!
 273 \group qtquick-animation-modifiers
 274 \title Qt Quick Animation Modifiers
 275 \brief Modify animation sequences
 276
 277 \generatelist{related}
 278 */