IXRStoryboard (Compact 2013)

3/28/2014

This class controls the playback of animations with a timeline and provides information used to target objects and properties for its child animations.

Syntax

class IXRStoryboard : public IXRTimeline

Inheritance Hierarchy

IXRDependencyObject

    IXRTimeline

        IXRStoryboard

Methods

Thread Safety

Members of this class are thread-safe if you previously called IXRApplication::CreateHostFromXaml and supplied it with an XRWindowCreateParams structure that has AllowsMultipleThreadAccess set to true.

Remarks

You can use the interactive methods in the IXRStoryboard class to start, pause, resume, and stop an animation.

You can use an IXRStoryboard object as a container for both individual animation objects (for example, IXRColorAnimation) and also child storyboard objects that contain their own animation collections. When an IXRStoryboard contains IXRStoryboard objects in its child collection, this is referred to as nestingIXRStoryboard objects within one another.

Implementing nested storyboards can help you create complex animation sequences. Each child storyboard waits until its parent storyboard begins before it starts the countdown for its own start time. You can add a new storyboard object to another XAML for Windows Embedded object by using IXRBeginStoryboard::SetStoryboard or IXRVisualTransition::SetStoryboard, or by adding it to the collection retrieved by IXRFrameworkElement::GetResources.

You can retrieve a storyboard's IXRTimelineCollection object by calling IXRStoryboard::GetChildren, and then you can manipulate the collection by adding objects to it. Then you can specify begin-time values for each nested IXRStoryboard separately by using its inherited method IXRTimeline::SetBeginTime.

To create a collection of IXRStoryboard objects that play when a framework element raises the OnLoaded event, create IXRBeginStoryboard objects and add an IXRStoryboard to each one by calling IXRBeginStoryboard::SetStoryboard.

When you create a class instance, use an IXRStoryboardPtr smart pointer instead of a raw interface pointer. For more information, see XRPtr<Interface>.

You can also define a storyboard in Silverlight 3 XAML. For information about the differences between XAML in XAML for Windows Embedded and Silverlight 3, see Differences Between Microsoft Silverlight 3 and XAML for Windows Embedded. For more information about how to define this element in the source XAML for your application, see the Storyboard Class on MSDN.

Example

The following example code creates a new storyboard, adds animations to it, and then adds it as a new resource for an IXRCanvas object in the visual tree. It also shows how to start the storyboard within event handling code.

#include "windows.h"
#include "XamlRuntime.h"
#include "XRDelegate.h"
#include "XRPtr.h"


// Create an event handler that plays the storyboard. 
// The following code shows a simple event handler as a starting point

class CustomObject 
{
 public:
    IXRVisualHostPtr g_pHost;

    HRESULT  SetHost(IXRVisualHost* pHost)
       {
            HRESULT hr;
            ASSERT(! g_pHost);
            if(NULL == pHost)
            {
                 hr = S_FALSE;
                 return hr;
            
            }
            
            g_pHost = pHost;
            
           hr = S_OK;
            return hr;
       }


     HRESULT OnMouseEnter(IXRDependencyObject* pSender, XRMouseEventArgs* pArgs)
     {
            
        if((NULL == pSender) || (NULL == pArgs))
        {
           return E_INVALIDARG;
        }

        //Retrieve the animation storyboard for the MouseEnter event
        IXRFrameworkElementPtr pRoot;
        IXRStoryboardPtr pStoryboard;
        g_pHost->GetRootElement(&pRoot);
        pRoot->FindName(L"NewStoryboard", &pStoryboard);
       
      // play the storyboard on-screen
      
       // First make sure that the storyboard not playing
       pStoryboard->Stop();
       
       // Begin playing the storyboard animation
       pStoryboard->Begin();

            return S_OK;
     }
};

// Create the animation storyboard

void CreateStoryboard(IXRApplication* pApplication, IXRColorAnimation* pColorAnimation, 
  IXRPointAnimation* pPointAnimation, XRDuration* pDefinedDuration, 
  IXRCanvas* pCanvas, CustomObject* pObject)
{
   // Create a new storyboard for the child animations that were
   // provided as [in] parameters

   IXRStoryboardPtr pStoryboard;
   IXRTimelineCollectionPtr childAnimations;
   bool AutoReverseSetting = true;

   pApplication->CreateObject(&pStoryboard);

   pStoryboard->GetChildren(&childAnimations);

   childAnimations->Add(pColorAnimation, NULL);
   childAnimations->Add(pPointAnimation, NULL);
  
   pStoryboard->SetName(L"NewStoryboard");
   pStoryboard->SetDuration(pDefinedDuration);
   pStoryboard->SetAutoReverse(AutoReverseSetting);

   // Add the new storyboard to a canvas that is in the visual tree
   
   IXRResourceDictionaryPtr canvasResources;
   const WCHAR szResourceKey[12] = L"Storyboard1";
   pCanvas->GetResources(&canvasResources);
   canvasResources->Add(szResourceKey, pStoryboard);

   // Attach a delegate to an event in an event object that represents  
   // the animation event handler

   pCanvas->AddMouseEnterEventHandler(CreateDelegate(pObject, &CustomObject::OnMouseEnter));

}

To run the previous code sample, you must already have created an IXRCanvas object and added it to the visual tree, and both the IXRPointAnimation and IXRColorAnimation objects that this code example adds to the animation storyboard.

To begin a storyboard animation for a storyboard that was defined in the Silverlight 3 XAML, you can locate it from the event handling code by calling IXRFrameworkElement::FindName and passing in the x:Name string defined for the <Storyboard> element.

.NET Framework Equivalent

System.Windows.Media.Animation.Storyboard

Requirements

See Also

Reference

Classes for Animation Storyboards
Classes for Visual Appearance