Controlling when your storyboard runs

Article
03/05/2013

You can control when a storyboard runs in your Blend for Visual Studio 2012 application in the following ways:

By dragging a behavior onto the object that you want to use to control the storyboard. You can use the ControlStoryboardAction behavior, or, if you are using states to create animation, you can use the GoToStateAction behavior. For more information, see Add a behavior to an object.
By creating a trigger that runs the storyboard when an event occurs (such as a button click) or, if your storyboard is in a control template, when a property changes.

Note

Triggers are not available in Microsoft Silverlight projects.
By creating an event handler method in a code-behind file that calls the Begin method of the storyboard.

You can also use these methods to control when the storyboard stops, pauses, resumes, removes itself, or skips to the end of the storyboard.

These methods differ slightly depending on the scope in which you are working.

Note

The following procedures refer to storyboards that contain visual animations. However, the procedures can also apply to audio or video storyboards. For more information, see Insert an audio or video file into the active document.

Storyboards in the main scope of your document

Create a storyboard in the main scope of your document if it will be a main feature of your document, and it will be triggered by the user interacting with a control that is also in the main scope of your document.

To control a storyboard in the main scope of your document using an event handler method

Close any open storyboards. For more information, see Open or close a storyboard.
If you are working in a WPF project, delete the default trigger that was created for the Window.Loaded event when you created your storyboard. For more information, see Add or remove a trigger from a WPF control (Blend SDK for WPF).
In the Objects and Timeline panel, select an object that, when interacted with, will run your storyboard. For example, if you want your storyboard to run when the user's pointer moves over a text block, select the text block.
In the Properties panel, click Events . A list of all available events for the selected object appears, in alphabetical order.

Tip

To see a short description of an event, move your pointer over the name of the event. A tooltip shows a description of the event.
Locate the event that you want to add programming logic to (for example, the MouseEnter event).
You have two ways to generate the empty event handler method:
- Double-click in the text block beside the event name. Blend generates a default name for your event handler method and enters it into the text block, and generates the code for the empty method.
- Type a name into the text block beside the event name, and then press ENTER or click elsewhere to move focus away from the text block. Event method names must begin with a letter. If the method name does not already exist in the code-behind file, Blend generates the code for the empty method and uses the name that you typed in.

Blend opens your code-behind file, and then pastes in the empty event handler method for you.

private void TextBlock_MouseEnter(object sender, System.Windows.Input.MouseEventArgs e)
{

}

Private Sub textBlock_MouseEnter(ByVal sender As System.Object, ByVal e As System.Windows.Input.MouseEventArgs)

End Sub

With your code-behind file open and the event handler method pasted in, add the following bold lines of code inside the event handler method:

private void TextBlock_MouseEnter(object sender, System.Windows.Input.MouseEventArgs e)
{
    Storyboard myStoryboard;   
    myStoryboard = (Storyboard)this.Resources["Storyboard1"];   
    myStoryboard.Begin(this);   
}

Private Sub textBlock_MouseEnter(ByVal sender As System.Object, ByVal e As System.Windows.Input.MouseEventArgs)
    Dim myStoryboard As New Storyboard   
    myStoryboard = CType(Me.Resources("Storyboard1"), Storyboard)   
    myStoryboard.Begin(Me)   
End Sub

Save all your files and then press F5 to build and test your application. For example, in your running application, move your mouse over the text block to see if your animation begins.

Note

If your animation does not return to the starting point when you move your mouse over your text block again, this could be because you did not set a keyframe at the 0-second mark.

Control a storyboard in the main scope of your document using an event trigger (WPF only)

In Blend, when you create a storyboard in the scope of the main document in a Windows Presentation Foundation (WPF) project, a new trigger is automatically created that will run your storyboard when your application window loads. You can view this trigger in the Triggers panel.

The default trigger that Blend sets when you create a storyboard

daa5d5de-713b-4d58-9f98-4ef65b217e9d

If you leave this trigger as is, your storyboard will run as soon as your application starts. Alternatively, you can modify this behavior by using the following procedure.

To control a storyboard in the main scope of your document using an event trigger (WPF only)

Close any open storyboards. For more information, see Open or close a storyboard.
If a default trigger was created for the Window.Loaded event when you created your storyboard, and you do not want your storyboard to run when your application starts, select Window.Loaded in the Triggers panel. Otherwise, click Add event trigger to create a new default event trigger.
In the Objects and Timeline panel, select an object that, when interacted with, will run your storyboard. For example, if you want your storyboard to run when the user's pointer moves over a text block, select the text block.
Change the event that triggers the animation (Window.Loaded) by using the drop-down menus in the Triggers panel. For example, change When Window.Loaded is raised to When textblock.MouseEnter is raised.
Define the action that will take place when the event is triggered. If no action is listed, click Add new action . Make sure that the action is set to the name of your storyboard (for example, Storyboard1), and that the method being called is Begin. Alternatively, you could select any of the methods that are valid for a storyboard. For more information, see Add or remove a trigger from a WPF control (Blend SDK for WPF).

Storyboards in control templates and styles

At times, Blend for Visual Studio 2012 creates a storyboard for you, such as when you add an action to a property trigger or event trigger when you modify a control template. For more information about how to work with styles and templates, see Styling objects.

Note

The following procedures apply to WPF projects, but you can use states to control storyboards in Silverlight projects. For more information, see Change states in response to user interaction and Add animation that will play after a change in state.

To control a storyboard in the scope of a template

Open a style or template for modification by using one of the following methods:

Note

To understand whether to use a style or a template, see Styling objects.

Note

Some objects do not support templates, such as path objects. Controls such as Button and RadioButton do support templates.
- To create a new template, select an object on the artboard or in the Objects and Timeline panel, and then, on the Object menu, click Edit Template, and then select Edit a Copy. The Create Style Resource dialog box appears. Select the location where you want to define your resource and then click OK. For more information, see Create a style.
- To create a new style, select an object on the artboard or in the Objects and Timeline panel, and then, on the Object menu, click Edit Style, and then select Edit a Copy. The Create Style Resource dialog box appears. Select the location where you want to define your resource and then click OK. For more information, see Create a style.
- To open an existing template, click Edit Resource , next to the style in the Resources panel, and then, in the Objects and Timeline panel, right-click the Style element, click Edit Template, and then select Edit Current. Alternatively, select a control to which a custom style is already applied, and then, on the Object menu, click Edit Template, and then select Edit Current.
- To open an existing style, click Edit Resource , next to the style in the Resources panel. Alternatively, select a control to which a custom style is already applied, and then, on the Object menu, click Edit Style, and then select Edit Current.
- To modify one of the simple styles that come with Blend, click Assets in the Tools panel, click the Styles category, click the Simple Styles resource dictionary, select a prestyled control, draw it on the artboard to make the Simple Styles.xaml resource dictionary available in the Resources panel, and then open the simple style or template using one of the preceding options. Modifying the Simple Styles.xaml resource dictionary in your current project does not affect the Simple Styles.xaml resource dictionary in another project unless you copy the Simple Styles.xaml file from your current project into the other project.
When in the editing scope of your style or template, notice the new Blend breadcrumb bar at the top of the artboard.

Breadcrumb bar with template-editing mode selected

By clicking the buttons on the breadcrumb bar, you can quickly move between template-editing mode, style-editing mode, and object-editing scope for the selected object. The breadcrumb bar appears for any selected object that has a custom style or template applied to it.
In the Objects and Timeline panel, click New .

The Create Storyboard Resource dialog box appears.
Enter a name and click OK. The Create Storyboard Resource dialog box closes and Blend enters timeline recording mode.
Create some animation that affects only the objects in the style or template that you are editing.

Note

You cannot animate objects outside the template or style that you are modifying. However, you can animate existing objects in the style or template. Additionally, when modifying a template, you can group the items under the Template node into a layout panel (such as a Grid), and then add more objects to the grid, which you can then animate.
Trigger the new storyboard by doing one of the following:
- To add the storyboard to an existing property trigger, select the trigger in the Triggers panel, and then, in the bottom half of the Triggers panel, click Add new action beside Actions when activating or Actions when deactivating, depending on whether you want your storyboard to run when the trigger is activated or when it is deactivated. Your new storyboard is automatically added as an action that will occur when the trigger is activated.
- To add the storyboard to a new property trigger, click Add property trigger , and then, in the bottom half of the Triggers panel, change the trigger from the default target-element.IsCancel = False to the property and value that you want (for example, target-element.IsPressed = True), and then click Add new action . Your new storyboard is automatically added as an action that will occur when the event is raised.
- To add the storyboard to a new event trigger, click Add event trigger , and then, in the bottom half of the Triggers panel, change the trigger from the default When target-element.Loaded is raised to the event that you want (for example When target-element.Click is raised), and then click Add new action . Your new storyboard is automatically added as an action that will occur when the event is raised.
Important

Always select the Default trigger to turn off trigger-recording mode before making general changes to the template. Otherwise, you might accidentally change an existing trigger.

Warning

When you modify styles and templates, it is possible to break the functionality of the system control to which the style or template is applied. For a list of cautions, see the Best Practices section in the Styling objects.
Save all your files and then press F5 to build and test your application.

For a more specific example of modifying a template, see Define different visual states and transition times for a user control.

Storyboards in user controls

By putting a storyboard in a user control, you can encapsulate the objects and storyboards that animate those objects into one XAML document and code-behind file. You can then instantiate the user control multiple times in other documents.

To control a storyboard that is contained in a user control

Create and open a user control for editing by doing one of the following:
- Create a user control from existing objects.
- On the File menu, select New Item. In the New Item dialog box, select UserControl, set the Name, and then click OK.
Create an animation storyboard and animate some of the objects in the user control.
You can now use either of the tasks under "Storyboards in the main scope of your document" to control your animation by using an event trigger or event handler method.

Note

If you create an event trigger on an object before converting the object to a user control by using the Make Into UserControl command, you will have to recreate the event trigger in the scope of the user control. This is because different events are available in the scope of the user control than in the scope of the main document. For example, you can configure events such as When UserControl.MouseDown is raised, with an action such as Storyboard1.Begin. When you use the Make Into UserControl command, resources and animations are refactored into the new control, so you do not have to recreate those.

Note

If you create an event handler method for an object before converting the object to a user control by using the Make Into UserControl command, the event handler method code in the code-behind file of your main document is not moved to the code-behind file of the user control. This is because there might be other objects that use the same event handler method. You can copy and paste the event handler method into the code-behind file of the user control.

Share via