How to: Accumulate Animation Values During Repeat Cycles

This example shows how to use the IsCumulative property to accumulate animation values across repeating cycles.

Example

Use the IsCumulative property to accumulate base values of an animation across repeating cycles. For example, if you set an animation to repeat 9 times (RepeatBehavior = “9x”) and you set the property to animate between 10 and 15 (From = 10 To = 15), the property animates from 10 to 15 during the first cycle, from 15 to 20 during the second cycle, from 20 to 25 during the third cycle, and so on. Hence, each animation cycle uses the ending animation value from the previous animation cycle as its base value.

You can use the IsCumulative property with most basic animations and most key frame animations. For more information, see Animation Overview and Key-Frame Animations Overview.

The following example shows this behavior by animating the width of four rectangles. The example:

  • Animates the first rectangle with DoubleAnimation and sets the IsCumulative property to true.

  • Animates the second rectangle with DoubleAnimation and sets the IsCumulative property to the default value of false.

  • Animates the third rectangle with DoubleAnimationUsingKeyFrames and sets the IsCumulative property to true.

  • Animates the last rectangle with DoubleAnimationUsingKeyFrames and sets the IsCumulative property to false.

<Page 
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">
  <StackPanel Margin="20" >

    <!-- This rectangle is animated with DoubleAnimation and IsCumulative set to "True". -->
    <Rectangle Name="withIsCumulative"
      Width="100" Height="20" Margin="12,0,0,5" Fill="#AA3333FF" HorizontalAlignment="Left" />

    <!-- This rectangle is animated with DoubleAnimation and IsCumulative set to "False". -->
    <Rectangle Name="withoutIsCumulative"
      Width="100" Height="20" Margin="12,0,0,5" Fill="#AA3333FF" HorizontalAlignment="Left" />

    <!-- This rectangle is animated with DoubleAnimationUsingKeyFrames and IsCumulative set to "True". -->
    <Rectangle Name="withIsCumulativeUsingKeyFrames"
      Width="100" Height="20" Margin="12,0,0,5" Fill="#AA3333FF" HorizontalAlignment="Left" />

    <!-- This rectangle is animated with DoubleAnimationUsingKeyFrames and IsCumulative set to "False". -->
    <Rectangle Name="withoutIsCumulativeUsingKeyFrames"
      Width="100" Height="20" Margin="12,0,0,5" Fill="#AA3333FF" HorizontalAlignment="Left" />

    <!-- Create a button to restart the animations. -->
    <Button Margin="0,30,0,0" HorizontalAlignment="Left">
      Restart Animations
      <Button.Triggers>
        <EventTrigger RoutedEvent="Button.Click">
          <BeginStoryboard>
            <Storyboard>

              <!-- DoubleAnimation with IsCumulative set to "True". Because IsCumulative is set to "True", 
                   the base values of the animation will accumulate over repeat cycles. In this example, the
                   first iteration will be from 100 to 200, the second will be from 200 to 300, the third from
                   300 to 400, etc. -->
              <DoubleAnimation 
                Storyboard.TargetName="withIsCumulative" 
                Storyboard.TargetProperty="Width" 
                RepeatBehavior="4x"
                AutoReverse="True"
                IsCumulative="True"
                Duration="0:0:3" From="100" To="200" />

              <!-- DoubleAnimation with IsCumulative set to "False". The starting value 100 pixels and repeat 
                   cycles do not build on earlier ones. -->
              <DoubleAnimation 
                Storyboard.TargetName="withoutIsCumulative" 
                Storyboard.TargetProperty="Width" 
                RepeatBehavior="4x"
                AutoReverse="True"
                IsCumulative="False"
                Duration="0:0:3" From="100" To="200" />

              <!-- DoubleAnimationUsingKeyFrames with IsCumulative set to "True". Similar to the DoubleAnimation
                   above, the base value of each cycle builds on the last one. Note that the output value
                   is the total output value from all the key frames for a total output of 100 pixels. -->
              <DoubleAnimationUsingKeyFrames
                Storyboard.TargetName="withIsCumulativeUsingKeyFrames"
                Storyboard.TargetProperty="Width"
                RepeatBehavior="4x"
                AutoReverse="True"
                IsCumulative="True" >
                <DoubleAnimationUsingKeyFrames.KeyFrames>
                  <LinearDoubleKeyFrame Value="100" KeyTime="0:0:0" />
                  <LinearDoubleKeyFrame Value="130" KeyTime="0:0:1" />
                  <SplineDoubleKeyFrame KeySpline="0.6,0.0 0.9,0.00" Value="200" KeyTime="0:0:3" />
                </DoubleAnimationUsingKeyFrames.KeyFrames>
              </DoubleAnimationUsingKeyFrames>

              <!-- DoubleAnimationUsingKeyFrames with IsCumulative set to "False". The base value of each cycle
                   does not build on the last one. -->
              <DoubleAnimationUsingKeyFrames
                Storyboard.TargetName="withoutIsCumulativeUsingKeyFrames"
                Storyboard.TargetProperty="Width"
                RepeatBehavior="4x"
                AutoReverse="True"
                IsCumulative="False" >
                <DoubleAnimationUsingKeyFrames.KeyFrames>
                  <LinearDoubleKeyFrame Value="100" KeyTime="0:0:0" />
                  <LinearDoubleKeyFrame Value="130" KeyTime="0:0:1" />
                  <SplineDoubleKeyFrame KeySpline="0.6,0.0 0.9,0.00" Value="200" KeyTime="0:0:3" />
                </DoubleAnimationUsingKeyFrames.KeyFrames>
              </DoubleAnimationUsingKeyFrames>

            </Storyboard>

          </BeginStoryboard>
        </EventTrigger>
      </Button.Triggers>
    </Button>
  </StackPanel>
</Page>

See Also

Tasks

How to: Add an Animation Output Value to an Animation Starting Value
How to: Repeat an Animation

Concepts

Animation Overview
Key-Frame Animations Overview

Other Resources

Animation and Timing How-to Topics
Animation and Timing Samples