IXRStoryboard (Compact 2013)

Article
04/19/2017

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

Method	Description
IXRStoryboard::Begin	Starts the set of animations associated with this storyboard.
IXRStoryboard::GetChildren	Retrieves the collection of child animations as objects derived from IXRTimeline.
IXRStoryboard::GetCurrentState	Retrieves the clock state of this storyboard.
IXRStoryboard::GetCurrentTime	Retrieves the current time span of this storyboard.
IXRStoryboard::Pause	Pauses the animation clock of this storyboard.
IXRStoryboard::Resume	Resumes the animation clock of this storyboard.
IXRStoryboard::Seek	Advances this storyboard to the specified position in the timeline. The storyboard performs the requested seek when the next clock tick occurs.
IXRStoryboard::SeekAlignedToLastTick	Advances this storyboard to a new position from the current position based on a specified time increment (synchronously).
IXRStoryboard::SkipToFill	Advances this storyboard's clock to the end of its active period.
IXRStoryboard::Stop	Stops the playback of this storyboard.

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.

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

#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

Header	XamlRuntime.h
sysgen	SYSGEN_XAML_RUNTIME