doc/src/declarative/animation.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qdeclarativeanimation.html
  30 \ingroup qml-features
  31 \contentspage QML Features
  32 \previouspage {QML States}{States}
  33 \nextpage {QML Data Models}{Structuring Data with Models}
  34 \title QML Animation and Transitions
  35
  36 \keyword qml-animation-elements
  37 \section1 Animation and Transitions Elements
  38 \list
  39 \o \l {Transition} - Animates transitions during state changes
  40 \o \l {SequentialAnimation} - Runs animations sequentially
  41 \o \l {ParallelAnimation} - Runs animations in parallel
  42 \o \l {Behavior} - Specifies a default animation for property changes
  43 \o \l {PropertyAction} - Sets immediate property changes during animation
  44 \o \l {PauseAnimation} - Introduces a pause in an animation
  45 \o \l {SmoothedAnimation} - Allows a property to smoothly track a value
  46 \o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
  47 \o \l {ScriptAction} - Runs scripts during an animation
  48 \endlist
  49
  50 \keyword qml-property-animation-elements
  51 Elements that animate properties based on data types
  52 \list
  53 \o \l {PropertyAnimation} - Animates property changes
  54 \o \l {NumberAnimation} - Animates properties of type qreal
  55 \o \l {Vector3dAnimation} - Animates properties of type QVector3d
  56 \o \l {ColorAnimation} - Animates color changes
  57 \o \l {RotationAnimation} - Animates rotations
  58 \o \l {ParentAnimation} - Animates parent changes
  59 \o \l {AnchorAnimation} - Animates anchor changes
  60 \endlist
  61
  62 In QML, animations are created by applying animation elements to property
  63 values. Animation elements will interpolate property values to create smooth
  64 transitions. As well, state transitions may assign animations to state changes.
  65
  66 To create an animation, use an appropriate animation element for the type of
  67 the property that is to be animated, and apply the animation depending on the
  68 type of behavior that is required.
  69
  70 \keyword qml-triggering-animations
  71 \section1 Triggering Animations
  72
  73 There are several ways of setting animation to an object.
  74
  75 \keyword qml-direct-animation
  76 \section2 Direct Property Animation
  77
  78 To create an immediate movement or animated movement, set the property value
  79 directly. This may be done in signal handlers or attached properties.
  80
  81 \snippet doc/src/snippets/declarative/animation.qml direct property change
  82
  83 However, to create more control, \e {property animations} apply smooth movements
  84 by interpolating values between property value changes. Property animations
  85 provide timing controls and allows different interpolations through
  86 \l{qml-easing-animation}{easing curves}.
  87
  88 \snippet doc/src/snippets/declarative/animation.qml property animation
  89
  90 Specialized \l{qml-property-animation-elements}{property animation elements}
  91 have more efficient implementations than the \l{PropertyAnimation} element. They
  92 are for setting animations to different QML types such as \c int, \c color, and
  93 rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
  94
  95 See the \l {qml-controlling-animations}{Controlling Animations} section for more
  96 information about the different animation properties.
  97
  98 \keyword qml-transition-animations
  99 \section2 Transitions during State Changes
 100
 101 \l{QML States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
 102 abrupt property changes; animations smooth transitions to produce visually
 103 appealing state changes.
 104
 105 The \l{Transition} element can contain
 106 \l{qml-animation-elements}{animation elements} to interpolate property changes
 107 caused by state changes. To assign the transition to an object, bind it to the
 108 \c transitions property.
 109
 110 A button might have two states, the \c pressed state when the user clicks on the
 111 button and a \c released state when the user releases the button. We can assign
 112 different property configurations for each state. A transition would animate the
 113 change from the \c pressed state to the \c released state. Likewise, there would
 114 be an animation during the change from the \c released state to the \c pressed
 115 state.
 116
 117 \snippet doc/src/snippets/declarative/animation.qml transition animation
 118
 119 Binding the \c to and \c from properties to the state's name will assign that
 120 particular transition to the state change. For simple or symmetric transitions,
 121 setting the to \c to property to the wild card symbol, "\c{*}", denotes
 122 that the transition applies to any state change.
 123
 124 \snippet doc/src/snippets/declarative/animation.qml wildcard animation
 125
 126 \section2 Default Animation as Behaviors
 127
 128 Default property animations are set using \e {behavior animations}. Animations
 129 declared in \l {Behavior} elements apply to the property and animates any
 130 property value changes. However, Behavior elements have an
 131 \c enabled property to purposely enable or disable the behavior animations.
 132
 133 A ball component might have a behavior animation assigned to its \c x, \c y, and
 134 \c color properties. The behavior animation could be set up to simulate an
 135 elastic effect. In effect, this behavior animation would apply the elastic
 136 effect to the properties whenever the ball moves.
 137
 138 \snippet doc/src/snippets/declarative/animation.qml behavior animation
 139
 140 There are several methods of assigning behavior animations to properties. The
 141 \c{Behavior on <property>} declaration is a convenient way of assigning a
 142 behavior animation onto a property.
 143
 144 See the \l {declarative/animation/behaviors}{Behaviors example} for a
 145 demonstration of behavioral animations.
 146
 147 \section1 Playing Animations in Parallel or in Sequence
 148
 149 Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
 150 will play a group of animations at the same time while sequential animations
 151 play a group of animations in order: one after the other. Grouping animations in
 152 \l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
 153 sequence or in parallel.
 154
 155 A banner component may have several icons or slogans to display, one after the
 156 other. The \c opacity property could transform to \c 1.0 denoting an opaque
 157 object. Using the \l{SequentialAnimation} element, the opacity animations will
 158 play after the preceding animation finishes. The \l{ParallelAnimation} element
 159 will play the animations at the same time.
 160
 161 \snippet doc/src/snippets/declarative/animation.qml sequential animation
 162
 163 Once individual animations are placed into a SequentialAnimation or
 164 ParallelAnimation, they can no longer be started and stopped independently. The
 165 sequential or parallel animation must be started and stopped as a group.
 166
 167 The \l SequentialAnimation element is also useful for playing
 168 \l{qml-transition-animations}{transition animations} because animations are
 169 played in parallel inside transitions.
 170
 171 See the \l {declarative/animation/basics}{Animation basics example} for a
 172 demonstration of creating and combining multiple animations in QML.
 173
 174 \keyword qml-controlling-animations
 175 \section1 Controlling Animations
 176
 177 There are different methods to control animations.
 178
 179 \section2 Animation Playback
 180 All \l{qml-animation-elements}{animation elements} inherit from the \l Animation element. It is not
 181 possible to create \l Animation objects; instead, this element provides the
 182 essential properties and methods for animation elements. Animation elements have
 183 \c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
 184 \c{complete()} -- all of these methods control the execution of animations.
 185
 186 \keyword qml-easing-animation
 187 \section2 Easing
 188
 189 Easing curves define how the animation will interpolate between the start value
 190 and the end value. Different easing curves might go beyond the defined range of
 191 interpolation. The easing curves simplify the creation of animation effects such
 192 as bounce effects, acceleration, deceleration, and cyclical animations.
 193
 194 A QML object may have different easing curve for each property animation. There
 195 are also different parameters to control the curve, some of which are exclusive
 196 to a particular curve. For more information about the easing curves, visit the
 197 \l {PropertyAnimation::easing.type}{easing} documentation.
 198
 199 The \l{declarative/animation/easing}{easing example} visually demonstrates each
 200 of the different easing types.
 201
 202 \section2 Other Animation Elements
 203
 204 In addition, QML provides several other elements useful for animation:
 205
 206 \list
 207 \o PauseAnimation: enables pauses during animations
 208 \o ScriptAction: allows JavaScript to be executed during an animation, and can
 209 be used together with StateChangeScript to reused existing scripts
 210 \o PropertyAction: changes a property \e immediately during an animation,
 211 without animating the property change
 212 \endlist
 213
 214 These are specialized animation elements that animate different property types
 215 \list
 216 \o SmoothedAnimation: a specialized NumberAnimation that provides smooth
 217 changes in animation when the target value changes
 218 \o SpringAnimation: provides a spring-like animation with specialized
 219 attributes such as \l {SpringAnimation::}{mass},
 220 \l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
 221 \o ParentAnimation: used for animating a parent change (see ParentChange)
 222 \o AnchorAnimation: used for animating an anchor change (see AnchorChanges)
 223 \endlist
 224
 225 */
 226
 227
 228
 229 \snippet doc/src/snippets/declarative/animation-elements.qml color
 230 \snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0
 231 \snippet doc/src/snippets/declarative/animation-signalhandler.qml 0
 232 \snippet doc/src/snippets/declarative/animation-standalone.qml 0
 233
 234 \snippet doc/src/snippets/declarative/animation-transitions.qml 0
 235 \snippet doc/src/snippets/declarative/animation-groups.qml 0
 236
 237 \snippet doc/src/snippets/declarative/animation-groups.qml 1
 238 \snippet doc/src/snippets/declarative/animation-groups.qml 0
 239 \image propanim.gif
 240