Timing Behaviors Overview
This topic describes the timing behaviors of animations and other Timeline objects.
- Prerequisites
- Timeline Types
- Properties that Control the Length of a Timeline
- The BeginTime Property
- The FillBehavior Property
- Properties that Control the Speed of a Timeline
- Related Topics
Prerequisites
To understand this topic, you should be familiar with basic animation features. For more information, see the Animation Overview.
Timeline Types
A Timeline represents a segment of time. It provides properties that enable you to specify the length of that segment, when it should start, how many times it will repeat, how fast time progresses in that segment, and more.
Classes that inherit from the timeline class provide additional functionality, such as animation and media playback. WPF provides the following Timeline types.
| Timeline type | Description |
|---|---|
Abstract base class for Timeline objects that generate output values for animating properties. |
|
Generates output from a media file. |
|
A type of TimelineGroup that groups and controls child Timeline objects. |
|
A type of ParallelTimeline that provides targeting information for the Timeline objects it contains. |
|
Timeline |
Abstract base class that defines timing behaviors. |
TimelineGroup |
Abstract class for Timeline objects that can contain other Timeline objects. |
Properties that Control the Length of a Timeline
A Timeline represents a segment of time, and the length of a timeline can be described in different ways. The following table defines several terms for describing the length of a timeline.
| Term | Description | Properties | |||
|---|---|---|---|---|---|
Simple duration |
The length of time a timeline takes to make a single forward iteration. |
||||
One repetition |
The length of time it takes for a timeline to play forward once and, if the AutoReverse property is true, play backwards once. |
Duration, AutoReverse |
|||
Active period |
The length of time it takes for a timeline to complete all the repetitions specified by its RepeatBehavior property. |
Duration, AutoReverse, RepeatBehavior |
The Duration Property
As previously mentioned, a timeline represents a segment of time. The length of that segment is determined by the timeline's Duration. When a timeline reaches the end of its duration, it stops playing. If the timeline has child timelines, they stop playing as well. In the case of an animation, the Duration specifies how long the animation takes to transition from its starting value to its ending value. A timeline's duration is sometimes called its simple duration, to distinguish between the duration of a single iteration and the total length of time the animation plays including repetitions. You can specify a duration using a finite time value or the special values Automatic or Forever. An animation's duration should resolve to a TimeSpan value, so it can transition between values.
The following example shows a DoubleAnimation with a Duration of five seconds.
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5" />
Container timelines, such as Storyboard and ParallelTimeline, have a default duration of Automatic, which means they automatically end when their last child stops playing. The following example shows a Storyboard whose Duration resolves to five seconds, the length of time it takes all its child DoubleAnimation objects to complete.
<Storyboard >
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5" />
<DoubleAnimation
Storyboard.TargetName="MyOtherRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:3" />
</Storyboard>
By setting the Duration of a container timeline to a TimeSpan value, you can force to play longer or shorter than its child Timeline objects would play. If you set the Duration to a value that's smaller than the length of the container timeline's child Timeline objects, the child Timeline objects stop playing when the container timeline does. The following example sets the Duration of the Storyboard from the preceding examples to three seconds. As a result, the first DoubleAnimation stops progressing after three seconds, when it has animated the target rectangle's width to 60.
<Storyboard Duration="0:0:3">
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5" />
<DoubleAnimation
Storyboard.TargetName="MyOtherRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:3" />
</Storyboard>
The RepeatBehavior Property
The RepeatBehavior property of a Timeline controls how many times it repeats its simple duration. Using the RepeatBehavior property, you can specify how many times the timeline plays (an iteration Count) or the total length of time it should play (a repeat Duration). In either case, the animation goes through as many beginning-to-end runs as necessary to fill the requested count or duration. By default, timelines have an iteration count of 1.0, which means they play once and do not repeat at all.
The following example uses the RepeatBehavior property to make a DoubleAnimation play for twice its simple duration by specifying an iteration count.
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
RepeatBehavior="2x" />
The next example uses the RepeatBehavior property to make the DoubleAnimation play for half its simple duration.
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
RepeatBehavior="0.5x" />
If you set the RepeatBehavior property of a Timeline to Forever, the Timeline repeats until stopped interactively or by the timing system. The following example uses the RepeatBehavior property to make the DoubleAnimation play indefinitely.
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
RepeatBehavior="Forever" />
For an additional example, see How to: Repeat an Animation.
The AutoReverse Property
The AutoReverse property specifies whether a Timeline will play backwards at the end of each forward iteration. The following example sets to the AutoReverse property of a DoubleAnimation to true; as a result, it animates from zero to 100, and then from 100 to zero. It plays for a total of 10 seconds.
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
AutoReverse="True" />
When you use a Count value to specify the RepeatBehavior of a Timeline and the AutoReverse property of that Timeline is true, a single repetition consists of one forward iteration followed by one backwards iteration. The following example sets the RepeatBehavior of the DoubleAnimation from the preceding example to a Count of two. As a result, the DoubleAnimation plays for 20 seconds: forward for five seconds, backwards for five seconds, forward for 5 seconds again, and then backwards for five seconds.
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
RepeatBehavior="2"
AutoReverse="True" />
If a container timeline has child Timeline objects, they reverse when the container timeline does. For additional examples, see How to: Specify Whether a Timeline Automatically Reverses.
The BeginTime Property
The BeginTime property enables you to specify when a timeline starts. A timeline's begin time is relative to its parent timeline. A begin time of zero seconds means the timeline starts as soon as it parent starts; any other value creates an offset between when the parent timeline starts playing and when the child timeline plays. For example, a begin time of two seconds means the timeline starts playing when its parent has reached a time of two seconds. By default, all timelines have a begin time of zero seconds. You may also set a timeline's begin time to null, which prevents the timeline from starting. In WPF, you specify null using the x:Null Markup Extension.
Note that the begin time is not applied each time a timeline repeats because of its RepeatBehavior setting. If you were to create an animation with a BeginTime of 10 seconds and a RepeatBehavior of Forever, there would be a 10-second delay before the animation played for the first time, but not for each successive repetition. However, if the animation's parent timeline were to restart or repeat, the 10-second delay would occur.
The BeginTime property is useful for staggering timelines. The following example creates a Storyboard that has two child DoubleAnimation objects. The first animation has a Duration of five seconds, and the second has a Duration of 3 seconds. The example sets the BeginTime of the second DoubleAnimation to 5 seconds, so that it begins playing after the first DoubleAnimation ends.
<Storyboard>
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
BeginTime="0:0:0" />
<DoubleAnimation
Storyboard.TargetName="MyOtherRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:3"
BeginTime="0:0:5" />
</Storyboard>
The FillBehavior Property
When a Timeline reaches the end of its total active duration, the FillBehavior property specifies whether it stops or holds its last value. An animation with a FillBehavior of HoldEnd "holds" its output value: the property being animated retains the last value of the animation. A value of Stop causes that the animation stop affecting its target property after it ends.
The following example creates a Storyboard that has two child DoubleAnimation objects. Both DoubleAnimation objects animate the Width of a Rectangle from 0 to 100. The Rectangle elements have non-animated Width values of 500 device independent pixels.
The FillBehavior property of the first DoubleAnimation is set to HoldEnd, the default value. As a result, the Width of the Rectangle stays at 100 after the DoubleAnimation ends.
The FillBehavior property of the second DoubleAnimation is set to Stop. As a result, the Width of the second Rectangle reverts to 500 after the DoubleAnimation ends.
<Rectangle Name="MyRectangle"
Width="500" Height="100"
Opacity="1" Fill="Red">
</Rectangle>
<Rectangle Name="MyOtherRectangle"
Width="500" Height="100"
Opacity="1" Fill="Orange">
</Rectangle>
<Button Content="Start FillBehavior Example">
<Button.Triggers>
<EventTrigger RoutedEvent="Button.Click">
<BeginStoryboard>
<Storyboard>
<DoubleAnimation
Storyboard.TargetName="MyRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
FillBehavior="HoldEnd" />
<DoubleAnimation
Storyboard.TargetName="MyOtherRectangle" Storyboard.TargetProperty="Width"
From="0" To="100" Duration="0:0:5"
FillBehavior="Stop" />
</Storyboard>
</BeginStoryboard>
</EventTrigger>
</Button.Triggers>
</Button>
Properties that Control the Speed of a Timeline
The Timeline class provides three properties for specifying its speed:
SpeedRatio – Specifies that rate, relative to its parent, at which time progresses for a Timeline. Values greater than one increase the speed of the Timeline and its child Timeline objects; values between zero and one slow it down. A value of one indicates that Timeline progresses at the same rate as its parent. The SpeedRatio setting of a container timeline affects all of its child Timeline objects as well.
AccelerationRatio – Specifies the percentage of the Duration of a Timeline spent accelerating. For an example, see How to: Accelerate or Decelerate an Animation.
DecelerationRatio - Specifies the percentage of the Duration of a Timeline spent decelerating. For an example, see How to: Accelerate or Decelerate an Animation.