Controlling when your storyboard runs

You can control when a storyboard runs in your Microsoft Expression Blend application in the following ways:

• 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 1.0 or Silverlight 2 projects.

• By creating an event handler method in a code-behind file that calls the storyboard's Begin method.

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.

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. In Expression Blend, when you create a storyboard in the scope of the main document, a new trigger is automatically created that will run your storyboard when your application window loads. You can view this trigger under Triggers in the Interaction panel.

The default trigger that Expression Blend sets when you create a storyboard

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

1. 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 under Triggers. Otherwise, click the Add event trigger  button to create a new default event trigger.

2. Under Objects and Timeline, 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.

3. Change the event that triggers the animation (Window.Loaded) by using the drop-down menus in the lower half of the Triggers pane. For example, change When Window.Loaded is raised to When textblock.MouseEnter is raised.

4. Define the action that will take place when the event is triggered. If no action is listed, click the Add new action  button. 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.

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

1. 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 under Triggers, and then do one of the following:

   • If multiple actions are listed in the lower half of the Triggers window, then select the one that controls your storyboard (for example Storyboard1.Begin), and click the Delete this Action  button next to it.

   • If the only action listed is the one that controls your storyboard, then you can delete the entire trigger by clicking the Delete Trigger  button.

2. Under Objects and Timeline, 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.

3. In the Properties panel, click the Events  button. A list of all available events for the selected element 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. You can also see a list of the available events and their descriptions in the WPF events quick reference.

4. Locate the event that you want to add programming logic to (for example, the MouseEnter event).

5. You have two ways to generate the empty event handler method:

   • Double-click in the text block beside the event name. Expression 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, Expression Blend generates the code for the empty method and uses the name that you typed in.

   Note

   You can configure Expression Blend to use the Clipboard, even if Microsoft Visual Studio 2008 is installed. On the Tools menu, click Options, and then click Event Handlers. Under Editing experience, click Clipboard only.

6. From this point, Expression Blend will do one of the following things:

   • If you have Visual Studio 2008 Standard Edition or later installed, Expression Blend will open your project in Visual Studio 2008, open your code-behind file, and then paste in the empty event handler method for you.

     Note

     If you have both Visual Studio 2008 and Visual Studio 2005 installed, you might get an error if the Visual Studio version chooser tries to open Visual Studio 2005 instead of Visual Studio 2008. This is because Expression Blend creates Visual Studio 2008 projects that cannot be opened in Visual Studio 2005. If this happens, open your project in Visual Studio 2008 before you try to create the event handler in the Properties panel of Expression Blend.

   • If you do not have Visual Studio 2008 Standard Edition or later installed, Expression Blend copies the empty event handler method to the Clipboard and displays a pop-up window that describes what you can do next. In this case, you can open the code-behind file manually in another text editor to paste the method inside the class definition for the window, as follows:

     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
     

   Note

   If you have an application (such as Notepad) mapped to .cs or .vb files, you can open your code-behind file manually by double-clicking the file name under Files in the Project panel. Expression Blend will open the file in that application.

   If you do not have an application mapped to .cs or .vb files, Expression Blend will be unable to open the file externally. To open the file, locate it in Windows Explorer (or, if you have saved your project in Expression Blend, click ExploreProject on the Project menu), right-click the .cs or .vb file that you want to modify, select Open With, and then select Notepad (or another editing application). After you do this, you will be able to open code-behind files manually from the Project panel in Expression Blend.

7. With your code-behind file open and the event handler method pasted in, add the following bolded 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
   

8. 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.

Storyboards in control templates and styles

At times, Microsoft Expression Blend 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 Styles and templates.

To control a storyboard in the scope of a template

1. 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 Style and template overview.

   Note

   Some objects do not support templates, such as path objects. Controls such as the Button or RadioButton do support templates.

   • To create a new template, select an object on the artboard or under Objects and Timeline, and then, on the Object menu, click Edit Control Parts (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 resource.

   • To create a new style, select an object on the artboard or under Objects and Timeline, 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 resource.

   • To open an existing template, click the Edit Resource  button next to the style in the Resources panel, and then, under Objects and Timeline, right-click the Style element, click Edit Control Parts (Template), and then select Edit Template. Alternatively, select a control to which a custom style is already applied, and then, on the Object menu, click Edit Control Parts (Template), and then select Edit Template.

   • To open an existing style, click the Edit Resource  button 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 Style.

   • To modify one of the simple styles that come with Expression Blend, open the Asset Library  from the toolbox, click the Controls tab, 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.

2. When in the editing scope of your style or template, notice the new Expression Blend 2 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.

3. Under Objects and Timeline, click the New  button.

   

   The Create Storyboard Resource dialog box appears.

   

4. Enter a name and click OK. The Create Storyboard Resource dialog box closes and Expression Blend enters timeline recording mode.

5. 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.

6. Trigger the new storyboard by doing one of the following:

   • To add the storyboard to an existing property trigger, select the trigger under Triggers in the Interaction panel, and then, in the bottom half of the Triggers pane, click the Add new action  button 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 the Add property trigger  button, and then, in the bottom half of the Triggers pane, 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 the Add new action  button. 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 the Add event trigger  button, and then, in the bottom half of the Triggers pane, 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 the Add new action  button. 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 Style and template overview.

7. Save all your files and then press F5 to build and test your application.

   For a more specific example of modifying a template, see Try it: Add animation to a button.

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

1. Create and open a user control for editing by doing one of the following:

   • Create a 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.

2. Create an animation storyboard and animate some of the objects in the user control.

3. 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 Control 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 Control 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 Control 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.

Storyboards in Silverlight 1.0 applications

Storyboards in Silverlight 1.0 applications are resources, and like all resources in Silverlight 1.0, they are identified by a name, not by a key as in Windows Presentation Foundation applications.

To control a storyboard in a Silverlight 1.0 application

• See Create a button that controls a storyboard in a Silverlight application.

Storyboards in Silverlight 2 applications

Storyboards in Silverlight 2 applications can be controlled using event handlers or states.

To control a storyboard in a Silverlight 2 application

• In an event handler method, use the following code:

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

• In a state, Add animation that will play after a change in state.

See also

Concepts

Create, modify, or delete a storyboard

Create simple animation