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