These properties aren't the only place where a Storyboard is defined. The typical way that a Storyboard is used for a storyboarded animation is that the Storyboard is defined in a Resources collection (either Application.Resources or FrameworkElement.Resources, or possibly as a resource within a file such as Generic.xaml for a custom control). Whenever it's defined as a XAML resource, you should always assign an x:Name attribute value to your Storyboard. You can then reference the name as a programming variable later in code-behind. You'll need this reference to actually run the animations that the Storyboard contains, by calling the Begin method on that Storyboard instance. Storyboard also has other control methods such as Stop that can control the animation thereafter.

Storyboard XAML attached properties

Storyboard is the host service class for several XAML attached properties. Theses enable child animations under control by the Storyboard to each target separate target elements and target properties, while still following the same controlling timeline and triggering mechanism as the parent.

Storyboard.TargetPropertyStoryboard.TargetName is used to reference another element by its name. The element being referenced is the element/object where the animation should apply. This mechanism is part of the basic design of the animation system: it enables animation resources to be declared separately from UI declaration resources, and makes it possible to apply one animation definition to several different property behaviors. For the value of Storyboard.TargetName on a particular animation, you specify the target element's Name or x:Name attribute value, which is a string. That named element should already exist in some other area of XAML markup.

The meaning of Name /x:Name attribute strings is controlled by a XAML namescope concept. For most animation targeting scenarios you won't need to worry about the influence of XAML namescopes, but you might encounter XAML name resolution issues if you're trying to target template parts, or objects that were created using XamlReader.Load and subsequently added to the object tree. For more info, see XAML namescopes.

In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods. For example, the GetTargetName and SetTargetName methods support and provide the equivalent code-only support for Storyboard.TargetName. Alternatively, you can use the dependency property system to get or set the value of the attached property. Call GetValue or SetValue, passing the arguments of the dependency property identifier to set, and a reference to the target object on which to get or set the value.

Methods

Begin()Begin()Begin()Begin()

Remarks

Calling this method begins all the animations that are in the Children collection of the Storyboard.

Begin starts the animations within the Storyboard from their initial state, a clock time of zero. If you want to restart an animation where Pause had been called previously, and continue on from the clock time where it was paused, use Resume instead.

Remarks

This method is useful if you want to modify an animation's properties at runtime, before the animation is started. An animation that is stopped (GetCurrentState returns ClockState.Stopped) can still be modified. An animation that is running (GetCurrentState returns either ClockState.Active or ClockState.Filling) cannot be modified, and you'll get an error if you try.

Windows 8 behavior

An animation can have an optional BeginTime value, which modifies when the animation actually starts to affect values compared to when the controlling storyboard is started. Even if the running time has not reached the BeginTime yet, it's illegal to modify the properties of the animation once the storyboard starts it. For Windows 8, calling GetCurrentState for a running animation where the running time has not reached the BeginTime always returns ClockState.Stopped. Normally, it's legal to modify a Stopped animation's properties, but in this particular case it's not, so using GetCurrentState to determine whether it's legal to modify the animation is not always accurate. Starting with Windows 8.1, calling GetCurrentState for an animation that's been started by its storyboard always returns ClockState.Active, even if the BeginTime value exists and hasn't been reached. The circumstances in which GetCurrentState returns ClockState.Filling remain the same.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

The Storyboard.TargetProperty value of the target element to set. This specifies a qualification path that targets the dependency property where the animation applies. See Remarks.

Remarks

Using SetTargetProperty in code as opposed to targeting an animation in initial XAML definitions is rare. It's tricky to get all the targeting and timing correct in an animation, particularly if you're trying to incorporate values that are only available at run time. We recommend that you create your animations in XAML, which means you'll use the Storyboard.TargetProperty attached property, not the SetTargetProperty runtime method (which supports the XAML behind the scenes). Building up animations in code is an advanced scenario. Here's a very basic code example of what's involved:

Property paths for animation property targeting

The Storyboard.TargetName property can process a string syntax that enables targeting a subproperty of a property value. The syntax uses a "dot-down" metaphor for targeting a chain of object-property relationships until a particular subproperty is identified. This enables animations to apply to the value types where there is a supporting animation structure (Double, Color, Point, and Object for DiscreteObjectKeyFrameAnimation ). For example, you might want to animate the Background value of a Control, which takes an object type of Brush. There is no "BrushAnimation" animation type, so you cannot directly target an animation for Background . But what you can do instead is reference a SolidColorBrush subproperty that is named Color, which takes type Color and can thus be targeted by a ColorAnimation. The string syntax for this is:

(Control.Background).(SolidColorBrush.Color)

The parentheses around "(Control.Background)" inform the processing that the intermediate "dot" should not "dot down" and is instead part of the qualification name that finds the ownertype-qualified Background property for targeting. The following "dot" is treated as a "dot-down" instruction, which requests a subproperty of the Brush type. The final "(SolidColorBrush.Color)" fragment again includes the parentheses so that the interior "dot" is again used as ownertype.member qualification, not a "dot-down".

Note that for subproperty values, there can be some value inference. For example, the following string works by inference even though "Color" is actually a value of the particular Brush subclass SolidColorBrush:

Migration notes

When you specify a path value for the path parameter, you specify the string, and if you retrieve the value again using GetTargetProperty, you also get the value as a string. This is in contrast to some other implementations of animation property targeting concepts such as Microsoft Silverlight and Windows Presentation Foundation (WPF). These XAML technologies use a representative object type (a discrete PropertyPath object) to store the property path information for animation targeting, and the syntax for the SetTargetProperty methods use the PropertyPath type. The Windows Runtime also has a PropertyPath class; however that class is only used for data binding, which is another scenario for property path definitions. The Windows Runtime doesn't support modifying a property path in a Storyboard after it's defined using the string, so its implementation of Storyboard.TargetProperty takes a string. This distinction doesn't even matter for XAML syntax and attached property support. It only matters for creating dynamic storyboards in code, or programmatically modifying storyboard values after they are initially defined in XAML. If you have any need to retarget an animation to a different property at run time, create an entirely new Storyboard with the new property path string, run animations with the new Storyboard, and stop using the previous one.

SkipToFill()SkipToFill()SkipToFill()SkipToFill()

Advances the current time of the storyboard's clock to the end of its active period.

public : void SkipToFill()

void SkipToFill() const;

public void SkipToFill()

Public Function SkipToFill() As void

Remarks

If you call this method on an animation that doesn't have a FillBehavior value of HoldEnd, this has the same effect as calling Stop.

This method is mainly relevant for methods that are playing or paused, and which don't have infinite repeat. Calling SkipToFill on an infinite animation or an animation that's already stopped has no effect.