Project Description

XNA Storyboard provides a Storyboard system for XNA similar to Silverlight's, using DependencyObjects and DependencyProperties developed in C#.

The purpose of this project is to provide an easy to use, yet robust mechanism for animating virtually any kind of value over time.

TargetAction usage

This method is the quickest to implement and will likely integrate the easiest into an existing code base since it does not require you to use DependencyObject/DependencyProperty.
The drawback to this method is that it requires consumption of the updated values on the developer's part, instead of updating a property directly

Basic Example

1. Create an instance of the Storyboard object
Storyboard sb = new Storyboard( yourGameInstance );
Note: Storyboard automatically adds itself to your game instance's Components collection, so it will receive Update messages automatically and simply do it's work after you call Begin

2. Create one or more animations you would like your Storyboard to perform
Storyboard sb = new Storyboard( yourGameInstance );

FloatAnimation fa = new FloatAnimation()
{
    Duration = TimeSpan.FromSeconds( 1.0 ),
    From = 0.0f,
    To = 1.0f
};

sb.Children.Add( fa );

3. Assign an Action that you would like to have called each time the animation updates, and in that Action use the updated value as you see fit
float someNumberToChange = 0.0f;

Storyboard sb = new Storyboard( yourGameInstance );

FloatAnimation fa = new FloatAnimation()
{
    Duration = TimeSpan.FromSeconds( 1.0 ),
    From = someNumberToChange,
    To = 1.0f, 
    TargetAction = ( value ) =>
    {
        someNumberToChange = value;
    }
};

sb.Children.Add( fa );
Note: the From property here is not optional when using TargetAction animation. In most cases, you will want to set it to the current value of whatever you're going to be updating.

4. Begin the animation and (optionally) get informed when the animation is finished
float someNumberToChange = 0.0f;

Storyboard sb = new Storyboard( yourGameInstance );

FloatAnimation fa = new FloatAnimation()
{
    Duration = TimeSpan.FromSeconds( 1.0 ),
    From = someNumberToChange,
    To = 1.0f, 
    TargetAction = ( value ) =>
    {
        someNumberToChange = value;
    }
};

sb.Children.Add( fa );

sb.Completed += YourEventHandlingMethod;  // Optional
sb.Begin();

DependencyProperty usage

This method will seem the most familiar for developer who have used Silverlight's animation system
  • In order for an object to be the target of an animation it must inherit from DependencyObject
  • For a property to be animated, it must be a DependencyProperty

Basic example

1. Create a class whose Property you would like to animate, and have it inherit from DependencyObject

using XNAStoryboard;

public class ExampleObject : DependencyObject
{

}

2. Add a new DependencyProperty to you object
using XNAStoryboard;

public class ExampleObject : DependencyObject
{
        #region Opacity
        static public readonly DependencyProperty OpacityProperty = DependencyProperty.Register( "Opacity", typeof( float ), typeof( ExampleObject) );

        public float Opacity
        {
            get
            {
                return this.GetValue<float>( ExampleObject.OpacityProperty );
            }
            set
            {
                this.SetValue( ExampleObject.OpacityProperty, value );
                this.NotifyPropertyChanged( "Opacity" );
            }
        }
        #endregion
}
Note: the syntax is similar to Silverlight, but with a slight difference in the parameters DependencyProperty.Register takes
Also Note: the call to NotifyPropertyChanged is optional, but DependencyObject does implement a PropertyChanged event for your convenience if you would like to broadcast when your DependencyProperty's value has changed.

3. Create an instance of the Storyboard object
Storyboard sb = new Storyboard( yourGameInstance );
Note: Storyboard automatically adds itself to your game instance's Components collection, so it will receive Update messages automatically and simply do it's work after you call Begin

4. Create one or more animations you would like your Storyboard to perform
Storyboard sb = new Storyboard( yourGameInstance );

FloatAnimation fa = new FloatAnimation()
{
    Duration = TimeSpan.FromSeconds( 1.0 ),
    From = 0.0f,
    To = 1.0f,
    Target = lr,
    TargetProperty = UserControl.OpacityProperty
};

sb.Children.Add( fa );
Note: I opted for a slightly different mechanism for setting up the animation's target than Silverlight uses, hence the use of Target and TargetProperty properties.
Also note: the From property here is optional when using DependencyProperty animation, since if you leave it null it will pull the current value from the DependencyProperty and use it.

5. Begin the animation and (optionally) get informed when the animation is finished
Storyboard sb = new Storyboard( yourGameInstance );

FloatAnimation fa = new FloatAnimation()
{
    Duration = TimeSpan.FromSeconds( 1.0 ),
    From = 0.0f,
    To = 1.0f,
    Target = lr,
    TargetProperty = UserControl.OpacityProperty
};

sb.Children.Add( fa );

sb.Completed += YourEventHandlingMethod;  // Optional
sb.Begin();

Easing

  • Easing can be accomplished by setting the EasingMode property on a given animation
FloatAnimation fa = new FloatAnimation()
{
    Duration = TimeSpan.FromSeconds( 1.0 ),
    From = 0.0f,
    To = 1.0f,
    Target = lr,
    TargetProperty = UserControl.OpacityProperty,
    EasingFunction = new Back()
    {
        EasingMode = EasingModes.EaseOut
    }
};
  • The currently available easing modes can be found in the XNAStoryboard.Tweens namespace and include:
    • Back
    • Bounce
    • Circular
    • Elastic
    • Exponential
    • Linear
    • Quadradic
    • Quartic
    • Quintic
    • Sinusoidal
  • The equations behind these easing functions are all adaptations of those provide by the excellent XNA Tweener project here on CodePlex

Currently planned updates

  • Add the ability to loop a storyboard
  • Add BeginTime to Storyboard and to animations, so you can add a delay
  • Add the ability to reverse a storyboard
  • Improve documentation

Last edited Sep 17, 2010 at 11:00 PM by instruo, version 57