IUIAnimationStoryboard::Schedule method (uianimation.h)

Article
02/22/2024

Directs the storyboard to schedule itself for play.

Syntax

HRESULT Schedule(
  [in]            UI_ANIMATION_SECONDS           timeNow,
  [out, optional] UI_ANIMATION_SCHEDULING_RESULT *schedulingResult
);

Parameters

[in] timeNow

The current time.

[out, optional] schedulingResult

The result of the scheduling request. This parameter can be omitted from calls to this method.

Return value

If the method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. See Windows Animation Error Codes for a list of error codes.

Remarks

This method directs a storyboard to attempt to add itself to the schedule of playing storyboards. The rules are as follows:

If there are no playing storyboards animating any of the same animation variables, the attempt succeeds and the storyboard starts playing immediately.
If the storyboard has priority to cancel, trim, conclude, or compress conflicting storyboards, the attempt to schedule succeeds and the storyboard begins playing as soon as possible.
If the storyboard does not have priority, the attempt fails and the schedulingResult parameter is set to UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY.

If this method is called from a handler for OnStoryboardStatusChanged events, the schedulingResult parameter is set to UI_ANIMATION_SCHEDULING_DEFERRED. The only way to determine whether the storyboard is successfully scheduled is to set a storyboard event handler and check whether the storyboard's status ever becomes UI_ANIMATION_STORYBOARD_INSUFFICIENT_PRIORITY.

It is possible reuse a storyboard by calling Schedule again after its status has reached UI_ANIMATION_STORYBOARD_READY. An attempt to schedule a storyboard when it is in any state other than UI_ANIMATION_STORYBOARD_BUILDING or UI_ANIMATION_STORYBOARD_READY fails, and schedulingResult is set to UI_ANIMATION_SCHEDULING_ALREADY_SCHEDULED.

Examples

The following example gets the current time and schedules the storyboard. For an additional example, see Schedule a Storyboard.

// Get the current time and schedule the storyboard
UI_ANIMATION_SECONDS secondsNow;
hr = m_pAnimationTimer->GetTime(
    &secondsNow
    );
if (SUCCEEDED(hr))
{
    UI_ANIMATION_SCHEDULING_RESULT schedulingResult;
    hr = pStoryboard->Schedule(
        secondsNow,
        &schedulingResult
        );
    if (SUCCEEDED(hr))
    {
        if (schedulingResult == UI_ANIMATION_SCHEDULING_SUCCEEDED)
        {
            ...
        }
        else
        {
            ...
        }
    }
}

Requirements

Requirement	Value
Minimum supported client	Windows 7, Windows Vista and Platform Update for Windows Vista [desktop apps \| UWP apps]
Minimum supported server	None supported
Target Platform	Windows
Header	uianimation.h
DLL	UIAnimation.dll