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.

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.

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.

See Also

Concepts

Animation Overview
Animation and Timing System Overview