--- title: "Storyboards Overview" description: Organize and apply animations in storyboards. Use property-targeting syntax and combine timelines in Windows Presentation Foundation (WPF). ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" helpviewer_keywords: - "Storyboard syntax [WPF]" - "syntax [WPF], Storyboard" - "timelines [WPF]" ms.assetid: 1a698c3c-30f1-4b30-ae56-57e8a39811bd --- # Storyboards Overview This topic shows how to use objects to organize and apply animations. It describes how to interactively manipulate objects and describes indirect property targeting syntax. ## Prerequisites To understand this topic, you should be familiar with the different animation types and their basic features. For an introduction to animation, see the [Animation Overview](animation-overview.md). You should also know how to use attached properties. For more information about attached properties, see the [Attached Properties Overview](../advanced/attached-properties-overview.md). ## What Is a Storyboard Animations are not the only useful type of timeline. Other timeline classes are provided to help you organize sets of timelines, and to apply timelines to properties. Container timelines derive from the class, and include and . A is a type of container timeline that provides targeting information for the timelines it contains. A Storyboard can contain any type of , including other container timelines and animations. objects enable you to combine timelines that affect a variety of objects and properties into a single timeline tree, making it easy to organize and control complex timing behaviors. For example, suppose you want a button that does these three things. - Grow and change color when the user selects the button. - Shrink away and then grow back to its original size when clicked. - Shrink and fade to 50 percent opacity when it becomes disabled. In this case, you have multiple sets of animations that apply to the same object, and you want to play at different times, dependent on the state of the button. objects enable you to organize animations and apply them in groups to one or more objects. ## Where Can You Use a Storyboard A can be used to animate dependency properties of animatable classes (for more information about what makes a class animatable, see the [Animation Overview](animation-overview.md)). However, because storyboarding is a framework-level feature, the object must belong to the of a or a . For example, you could use a to do the following: - Animate a (Non-framework element) that paints the Background of a Button (a type of ), - Animate a (Non-framework element) that paints the fill of a (Non-framework element) displayed using an (). - In code, animate a declared by a class that also contains a , if the registered its name with that . However, you could not use a to animate a that did not register its name with a or , or was not used to set a property of a or . ## How to Apply Animations with a Storyboard To use a to organize and apply animations, you add the animations as child timelines of the . The class provides the and attached properties. You set these properties on an animation to specify its target object and property. To apply animations to their targets, you begin the using a trigger action or a method. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you use a object with an , , or . In code, you can also use the method. The following table shows the different places where each begin technique is supported: per-instance, style, control template, and data template. "Per-Instance" refers to the technique of applying an animation or storyboard directly to instances of an object, rather than in a style, control template, or data template. |Storyboard is begun using…|Per-instance|Style|Control template|Data template|Example| |--------------------------------|-------------------|-----------|----------------------|-------------------|-------------| | and an |Yes|Yes|Yes|Yes|[Animate a Property by Using a Storyboard](how-to-animate-a-property-by-using-a-storyboard.md)| | and a property |No|Yes|Yes|Yes|[Trigger an Animation When a Property Value Changes](how-to-trigger-an-animation-when-a-property-value-changes.md)| | and a property |No|Yes|Yes|Yes|[MultiTrigger class example](/dotnet/api/system.windows.multitrigger#examples)| | and a |No|Yes|Yes|Yes|[How to: Trigger an Animation When Data Changes](/previous-versions/dotnet/netframework-3.5/aa970679(v=vs.90))| | and a |No|Yes|Yes|Yes|[MultiDataTrigger class example](/dotnet/api/system.windows.multidatatrigger#examples)| | method|Yes|No|No|No|[Animate a Property by Using a Storyboard](how-to-animate-a-property-by-using-a-storyboard.md)| The following example uses a to animate the of a element and the of a used to paint that . [!code-xaml[storyboards_ovw_snip_XAML#1](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/StoryboardsExample.xaml#1)] [!code-csharp[storyboards_ovw_snip#100](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/StoryboardsExample.cs#100)] The following sections describe the and attached properties in more detail. ## Targeting Framework Elements, Framework Content Elements, and Freezables The previous section mentioned that, for an animation to find its target, it must know the target's name and the property to animate. Specifying the property to animate is straight forward: simply set `TargetProperty` with the name of the property to animate. You specify the name of the object whose property you want to animate by setting the property on the animation. > [!CAUTION] > While you can use the `Target` property to bind directly to an object as an alternative to `TargetName`, it isn't serializable. There is no guaranteed that the `Target` object can be correctly referenced in XAML. For the property to work, the targeted object must have a name. Assigning a name to a or a in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is different than assigning a name to a object. Framework elements are those classes that inherit from the class. Examples of framework elements include , , , and . Essentially all windows, panels, and controls are elements. Framework content elements are those classes that inherit from the class. Examples of framework content elements include and . If you're not sure whether a type is a framework element or a framework content element, check to see whether it has a Name property. If it does, it's probably a framework element or a framework content element. To be sure, check the Inheritance Hierarchy section of its type page. To enable the targeting of a framework element or a framework content element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you set its property. In code, you also need to use the method to register the element's name with the element for which you've created a . The following example, taken from the preceding example, assigns the name `MyRectangle` a , a type of . [!code-xaml[storyboards_ovw_snip_XAML#2](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/StoryboardsExample.xaml#2)] [!code-csharp[storyboards_ovw_snip#102](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/StoryboardsExample.cs#102)] After it has a name, you can animate a property of that element. [!code-xaml[storyboards_ovw_snip_XAML#5](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/StoryboardsExample.xaml#5)] [!code-csharp[storyboards_ovw_snip#105](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/StoryboardsExample.cs#105)] types are those classes that inherit from the class. Examples of include , , and . To enable the targeting of a by an animation in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you use the [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) to assign it a name. In code, you use the method to register its name with the element for which you've created a . The following example assigns a name to a object. [!code-xaml[storyboards_ovw_snip_XAML#3](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/StoryboardsExample.xaml#3)] [!code-csharp[storyboards_ovw_snip#103](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/StoryboardsExample.cs#103)] The object can then be targeted by an animation. [!code-xaml[storyboards_ovw_snip_XAML#7](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/StoryboardsExample.xaml#7)] [!code-csharp[storyboards_ovw_snip#107](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/StoryboardsExample.cs#107)] objects use name scopes to resolve the property. For more information about WPF name scopes, see [WPF XAML Namescopes](../advanced/wpf-xaml-namescopes.md). If the property is omitted, the animation targets the element on which it is defined, or, in the case of styles, the styled element. Sometimes a name can't be assigned to a object. For example, if a is declared as a resource or used to set a property value in a style, it can't be given a name. Because it doesn't have a name, it can't be targeted directly—but it can be targeted indirectly. The following sections describe how to use indirect targeting. ## Indirect Targeting There are times a can't be targeted directly by an animation, such as when the is declared as a resource or used to set a property value in a style. In these cases, even though you can't target it directly, you can still animate the object. Instead of setting the property with the name of the , you give it the name of the element to which the "belongs." For example, a used to set the of a rectangle element belongs to that rectangle. To animate the brush, you would set the animation's with a chain of properties that starts at the property of the framework element or framework content element the was used to set and ends with the property to animate. [!code-xaml[storyboards_ovw_snip_XAML#33](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/IndirectTargetingExample.xaml#33)] [!code-csharp[storyboards_ovw_snip#134](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml.cs#134)] Note that, if the is frozen, a clone will be made, and that clone will be animated. When this happens, the original object's property continues to return `false`, because the original object is not actually animated. For more information about cloning, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md). Also note that, when using indirect property targeting, it's possible to target objects that don't exist. For example, you might assume that the of a particular button was set with a and try to animate its Color, when in fact a was used to set the button's Background. In these cases, no exception is thrown; the animation fails to have a visible effect because does not react to changes to the property. The following sections describe indirect property targeting syntax in more detail. ### Indirectly Targeting a Property of a Freezable in XAML To target a property of a freezable in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], use the following syntax. | | |-| |*ElementPropertyName* `.` *FreezablePropertyName*| Where - *ElementPropertyName* is the property of the which the is used to set, and - *FreezablePropertyName* is the property of the to animate. The following code shows how to animate the of a used to set the of a rectangle element. [!code-xaml[storyboards_ovw_snip_XAML#32](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/IndirectTargetingExample.xaml#32)] Sometimes you need to target a freezable contained in a collection or array. To target a freezable contained in a collection, you use the following path syntax. | | |-| |*ElementPropertyName* `.Children[` *CollectionIndex* `].` *FreezablePropertyName*| Where *CollectionIndex* is the index of the object in its array or collection. For example, suppose that a rectangle has a resource applied to its property, and you want to animate one of the transforms it contains. [!code-xaml[storyboards_ovw_snip_XAML#34](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/IndirectTargetingExample.xaml#34)] The following code shows how to animate the property of the shown in the previous example. [!code-xaml[storyboards_ovw_snip_XAML#35](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip_XAML/CS/IndirectTargetingExample.xaml#35)] ### Indirectly Targeting a Property of a Freezable in Code In code, you create a object. When you create the , you specify a and . To create , you create an array of type that contains a list of dependency property identifier fields. The first identifier field is for the property of the or that the is used to set. The next identifier field represents the property of the to target. Think of it as a chain of properties that connects the to the object. The following is an example of a dependency property chain that targets the of a used to set the of a rectangle element. [!code-csharp[storyboards_ovw_snip#135](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml.cs#135)] You also need to specify a . A is a that tells the how to interpret its . It uses the following syntax. | | |-| |`(` *OwnerPropertyArrayIndex* `).(` *FreezablePropertyArrayIndex* `)`| Where - *OwnerPropertyArrayIndex* is the index of the array that contains the identifier of the object's property that the is used to set, and - *FreezablePropertyArrayIndex* is the index of the array that contains the identifier of property to target. The following example shows the that would accompany the defined in the preceding example. [!code-csharp[storyboards_ovw_snip#PropertyChainAndPath](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml.cs#propertychainandpath)] The following example combines the code in the previous examples to animate the of a used to set the of a rectangle element. [!code-csharp[storyboards_ovw_snip#137](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml.cs#137)] Sometimes you need to target a freezable contained in a collection or array. For example, suppose that a rectangle has a resource applied to its property, and you want to animate one of the transforms it contains. [!code-xaml[storyboards_ovw_snip#142](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml#142)] To target a contained in a collection, you use the following path syntax. | | |-| |`(` *OwnerPropertyArrayIndex* `).(` *CollectionChildrenPropertyArrayIndex* `)` `[` *CollectionIndex* `].(` *FreezablePropertyArrayIndex* `)`| Where *CollectionIndex* is the index of the object in its array or collection. To target the property of the , the second transform in the , you would use the following and . [!code-csharp[storyboards_ovw_snip#139](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml.cs#139)] The following example shows the complete code for animating the of a contained within a . [!code-csharp[storyboards_ovw_snip#138](~/samples/snippets/csharp/VS_Snippets_Wpf/storyboards_ovw_snip/CSharp/IndirectTargetingExample.xaml.cs#138)] ### Indirectly Targeting with a Freezable as the Starting Point The previous sections described how to indirectly target a by starting with a or and creating a property chain to a sub-property. You can also use a as a starting point and indirectly target one of its sub-properties. One additional restriction applies when using a as a starting point for indirect targeting: the starting and every between it and the indirectly targeted sub-property must not be frozen. ## Interactively Controlling a Storyboard in XAML To start a storyboard in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you use a trigger action. distributes the animations to the objects and properties they animate, and starts the storyboard. (For details about this process, see the [Animation and Timing System Overview](animation-and-timing-system-overview.md).) If you give the a name by specifying its property, you make it a controllable storyboard. You can then interactively control the storyboard after it's started. The following is a list of controllable storyboard actions that you use with event triggers to control a storyboard. - : Pauses the storyboard. - : Resumes a paused storyboard. - : Changes the storyboard's speed. - : Advances a storyboard to the end of its fill period, if it has one. - : Stops the storyboard. - : Removes the storyboard. In the following example, controllable storyboard actions are used to interactively control a storyboard. [!code-xaml[animation_ovws_snip#ControllableStoryboardExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/animation_ovws_snip/CS/ControllableStoryboardExample.xaml#controllablestoryboardexamplewholepage)] ## Interactively Controlling a Storyboard by Using Code The previous examples have shown how to animate using trigger actions. In code, you may also control a storyboard using interactive methods of the class. For a to be made interactive in code, you must use the appropriate overload of the storyboard's method and specify `true` to make it controllable. See the page for more information. The following list shows the methods that can be used to manipulate a after it has started: - - - - - - The advantage to using these methods is that you don't need to create or objects; you just need a reference to the controllable you want to manipulate. > [!NOTE] > All interactive actions taken on a , and therefore also on a will occur on the next tick of the timing engine which will happen shortly before the next render. For example, if you use the method to jump to another point in an animation, the property value does not change instantly, rather, the value changes on the next tick of the timing engine. The following example shows how to apply and control animations using the interactive methods of the class. [!code-csharp[animation_ovws_procedural_snip#ControllableStoryboardExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/animation_ovws_procedural_snip/CSharp/ControllableStoryboardExample.cs#controllablestoryboardexamplewholepage)] [!code-vb[animation_ovws_procedural_snip#ControllableStoryboardExampleWholePage](~/samples/snippets/visualbasic/VS_Snippets_Wpf/animation_ovws_procedural_snip/visualbasic/controllablestoryboardexample.vb#controllablestoryboardexamplewholepage)] ## Animate in a Style You can use objects to define animations in a . Animating with a in a is similar to using a elsewhere, with the following three exceptions: - You don't specify a ; the always targets the element to which the is applied. To target objects, you must use indirect targeting. For more information about indirect targeting, see the [Indirect Targeting](#pathsyntaxforchangeable) section. - You can't specify a for an or a . - You can't use dynamic resource references or data binding expressions to set or animation property values. That's because everything inside a must be thread-safe, and the timing system must objects to make them thread-safe. A cannot be frozen if it or its child timelines contain dynamic resource references or data binding expressions. For more information about freezing and other features, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md). - In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can't declare event handlers for or animation events. For an example showing how to define a storyboard in a style, see the [Animate in a Style](how-to-animate-in-a-style.md) example. ## Animate in a ControlTemplate You can use objects to define animations in a . Animating with a in a is similar to using a elsewhere, with the following two exceptions: - The may only refer to child objects of the . If is not specified, the animation targets the element to which the is applied. - The for an or a may only refer to child objects of the . - You can't use dynamic resource references or data binding expressions to set or animation property values. That's because everything inside a must be thread-safe, and the timing system must objects to make them thread-safe. A cannot be frozen if it or its child timelines contain dynamic resource references or data binding expressions. For more information about freezing and other features, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md). - In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can't declare event handlers for or animation events. For an example showing how to define a storyboard in a , see the [Animate in a ControlTemplate](how-to-animate-in-a-controltemplate.md) example. ## Animate When a Property Value Changes In styles and control templates, you can use Trigger objects to start a storyboard when a property changes. For examples, see [Trigger an Animation When a Property Value Changes](how-to-trigger-an-animation-when-a-property-value-changes.md) and [Animate in a ControlTemplate](how-to-animate-in-a-controltemplate.md). Animations applied by property objects behave in a more complex fashion than animations or animations started using methods. They "handoff" with animations defined by other objects, but compose with and method-triggered animations. ## See also - [Animation Overview](animation-overview.md) - [Property Animation Techniques Overview](property-animation-techniques-overview.md) - [Freezable Objects Overview](../advanced/freezable-objects-overview.md)