1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\ingroup qtquick-transitions-animations
6\page qtquick-statesanimations-animations.html
7\title Animation and Transitions in Qt Quick
8\brief the animation system in Qt Quick
10\section1 Animation and Transitions Types
13\li \l [QML] {Transition} - Animates transitions during state changes
14\li \l {SequentialAnimation} - Runs animations sequentially
15\li \l {ParallelAnimation} - Runs animations in parallel
16\li \l {Behavior} - Specifies a default animation for property changes
17\li \l {PropertyAction} - Sets immediate property changes during animation
18\li \l {PauseAnimation} - Introduces a pause in an animation
19\li \l {SmoothedAnimation} - Allows a property to smoothly track a value
20\li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
21\li \l {ScriptAction} - Runs scripts during an animation
24Types that animate properties based on data types
25\annotatedlist qtquick-animation-properties
27Animations are created by applying animation types to property
28values. Animation types will interpolate property values to create smooth
29transitions. As well, state transitions may assign animations to state changes.
31To create an animation, use an appropriate animation type for the type of
32the property that is to be animated, and apply the animation depending on the
33type of behavior that is required.
35\sa {Qt Quick Examples - Animation}
37\section1 Triggering Animations
39There are several ways of setting animation to an object.
41\section2 Direct Property Animation
43Animations are created by applying animation objects to property values to
44gradually change the properties over time. These \e {property animations} apply
45smooth movements by interpolating values between property value changes. Property
46animations provide timing controls and allows different interpolations through
47\l{qml-easing-animation}{easing curves}.
49\snippet qml/animation.qml property animation
51Specialized property animation types
52have more efficient implementations than the \l{PropertyAnimation} type. They
53are for setting animations to different QML types such as \c int, \c color, and
54rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
56See the \l {qml-controlling-animations}{Controlling Animations} section for more
57information about the different animation properties.
60\section2 Using Predefined Targets and Properties
62In the previous example, the PropertyAnimation and NumberAnimation objects needed
63to specify particular \l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{properties}
64values to specify the objects and properties that should be animated. This can be
65avoided by using the \e {<Animation> on <Property>} syntax, which specifies the
66animation is to be applied as a \e {property value source}.
68Below are two PropertyAnimation objects that are specified using this syntax:
75 width: 100; height: 100
78 PropertyAnimation on x { to: 100 }
79 PropertyAnimation on y { to: 100 }
83The animation starts as soon as the rectangle is loaded, and will automatically be
84applied to its \c x and \c y values. Since the \e {<Animation> on <Property>}
85syntax has been used, it is not necessary to set the
86\l {PropertyAnimation::}{target} value of the PropertyAnimation objects to
87\c rect, and neither is it necessary to set the \l {PropertyAnimation::}{property}
88values to \c x and \c y.
90This can also be used by \l{Playing Animations in Parallel or in Sequence}
91{grouped animations} to ensure that all animations within a group are applied to
92the same property. For example, the previous example could instead use
93SequentialAnimation to animate the rectangle's \c color first to yellow, then
100 width: 100; height: 100
103 SequentialAnimation on color {
104 ColorAnimation { to: "yellow"; duration: 1000 }
105 ColorAnimation { to: "blue"; duration: 1000 }
110Since the SequentialAnimation object has been specified on the \c color property
111using the \e {<Animation> on <Property>} syntax, its child ColorAnimation objects
112are also automatically applied to this property and do not need to specify
113\l {PropertyAnimation::}{target} or \l {PropertyAnimation::}{property} animation
117\target qml-transition-animations
118\section2 Transitions During State Changes
120\l{State}{Qt Quick States} are property configurations where a property may have different values to reflect different states. State changes introduce
121abrupt property changes; animations smooth transitions to produce visually
122appealing state changes.
124The \l [QML] {Transition} type can contain animation types to interpolate
125property changes caused by state changes. To assign the transition to an object,
126bind it to the \c transitions property.
128A button might have two states, the \c pressed state when the user clicks on the
129button and a \c released state when the user releases the button. We can assign
130different property configurations for each state. A transition would animate the
131change from the \c pressed state to the \c released state. Likewise, there would
132be an animation during the change from the \c released state to the \c pressed
135\snippet qml/animation.qml transition animation
137Binding the \c to and \c from properties to the state's name will assign that
138particular transition to the state change. For simple or symmetric transitions,
139setting the to \c to property to the wild card symbol, "\c{*}", denotes
140that the transition applies to any state change.
142\snippet qml/animation.qml wildcard animation
144\section2 Default Animation as Behaviors
146Default property animations are set using \e {behavior animations}. Animations
147declared in \l {Behavior} types apply to the property and animates any
148property value changes. However, Behavior types have an
149\c enabled property to purposely enable or disable the behavior animations.
151A ball component might have a behavior animation assigned to its \c x, \c y, and
152\c color properties. The behavior animation could be set up to simulate an
153elastic effect. In effect, this behavior animation would apply the elastic
154effect to the properties whenever the ball moves.
156\snippet qml/animation.qml behavior animation
158There are several methods of assigning behavior animations to properties. The
159\c{Behavior on <property>} declaration is a convenient way of assigning a
160behavior animation onto a property.
162See the \l {Qt Quick Examples - Animation} for a
163demonstration of behavioral animations.
165\section1 Playing Animations in Parallel or in Sequence
167Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
168will play a group of animations at the same time while sequential animations
169play a group of animations in order: one after the other. Grouping animations in
170\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
171sequence or in parallel.
173A banner component may have several icons or slogans to display, one after the
174other. The \c opacity property could transform to \c 1.0 denoting an opaque
175object. Using the \l{SequentialAnimation} type, the opacity animations will
176play after the preceding animation finishes. The \l{ParallelAnimation} type
177will play the animations at the same time.
179\snippet qml/animation.qml sequential animation
181Once individual animations are placed into a SequentialAnimation or
182ParallelAnimation, they can no longer be started and stopped independently. The
183sequential or parallel animation must be started and stopped as a group.
185The \l SequentialAnimation type is also useful for playing
186\l{qml-transition-animations}{transition animations} because animations are
187played in parallel inside transitions.
189\target qml-controlling-animations
190\section1 Controlling Animations
192There are different methods to control animations.
194\section2 Animation Playback
195All animation types inherit from the \l Animation type. It is not
196possible to create \l Animation objects; instead, this type provides the
197essential properties and methods for animation types. Animation types have
198\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
199\c{complete()} -- all of these methods control the execution of animations.
201\target qml-easing-animation
204Easing curves define how the animation will interpolate between the start value
205and the end value. Different easing curves might go beyond the defined range of
206interpolation. The easing curves simplify the creation of animation effects such
207as bounce effects, acceleration, deceleration, and cyclical animations.
209A QML object may have different easing curve for each property animation. There
210are also different parameters to control the curve, some of which are exclusive
211to a particular curve. For more information about the easing curves, visit the
212\l {PropertyAnimation::easing.type}{easing} documentation.
214The \l{animation/easing}{easing example} visually demonstrates each
215of the different easing types.
217\section2 Other Animation Types
219In addition, QML provides several other types useful for animation:
222\li PauseAnimation: enables pauses during animations
223\li ScriptAction: allows JavaScript to be executed during an animation, and can
224be used together with StateChangeScript to reused existing scripts
225\li PropertyAction: changes a property \e immediately during an animation,
226without animating the property change
229These are specialized animation types that animate different property types
231\li SmoothedAnimation: a specialized NumberAnimation that provides smooth
232changes in animation when the target value changes
233\li SpringAnimation: provides a spring-like animation with specialized
234attributes such as \l {SpringAnimation::}{mass},
235\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
236\li ParentAnimation: used for animating a parent change (see ParentChange)
237\li AnchorAnimation: used for animating an anchor change (see AnchorChanges)
240\section1 Sharing Animation Instances
242Sharing animation instances between Transitions or Behaviors is not
243supported, and may lead to undefined behavior. In the following example,
244changes to the Rectangle's position will most likely not be correctly animated.
248 // NOT SUPPORTED: this will not work correctly as both Behaviors
249 // try to control a single animation instance
250 NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack }
251 Behavior on x { animation: anim }
252 Behavior on y { animation: anim }
256The easiest fix is to repeat the NumberAnimation for both Behaviors. If the repeated
257animation is rather complex, you might also consider creating a custom animation
258component and assigning an instance to each Behavior, for example:
262 component MyNumberAnimation : NumberAnimation {
263 duration: 300; easing.type: Easing.InBack
265 Behavior on x { MyNumberAnimation {} }
266 Behavior on y { MyNumberAnimation {} }