//--------------------------------------------------------------------------
//
//  UIAnimation.idl
//
//  Windows Animation interface definitions and related types and enums
//
//  Copyright (c) Microsoft Corporation. All rights reserved.
//
//--------------------------------------------------------------------------

cpp_quote("//--------------------------------------------------------------------------")
cpp_quote("//")
cpp_quote("//  UIAnimation.h")
cpp_quote("//")
cpp_quote("//  Windows Animation interface definitions and related types and enums")
cpp_quote("//  (Generated from UIAnimation.idl)")
cpp_quote("//")
cpp_quote("//  Copyright (c) Microsoft Corporation. All rights reserved.")
cpp_quote("//")
cpp_quote("//--------------------------------------------------------------------------")

import "wtypes.idl";
import "unknwn.idl";
#include "sdkddkver.h"

interface IUIAnimationManager;
interface IUIAnimationVariable;
interface IUIAnimationStoryboard;
interface IUIAnimationTransition;
interface IUIAnimationManagerEventHandler;
interface IUIAnimationVariableChangeHandler;
interface IUIAnimationVariableIntegerChangeHandler;
interface IUIAnimationStoryboardEventHandler;
interface IUIAnimationPriorityComparison;
interface IUIAnimationTransitionLibrary;

interface IUIAnimationInterpolator;
interface IUIAnimationTransitionFactory;

interface IUIAnimationTimer;
interface IUIAnimationTimerUpdateHandler;
interface IUIAnimationTimerClientEventHandler;
interface IUIAnimationTimerEventHandler;

// Annotations on methods are not supported by earlier versions of MIDL
#ifdef NTDDI_WIN7
#define UI_CHECKRETURN                              [annotation("__checkReturn")] 
#else
#define UI_CHECKRETURN                    
#endif


//////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Animation API

// The units of time used for all animations
typedef DOUBLE UI_ANIMATION_SECONDS;

// Special value to indicate that any predetermined time in the future will be acceptable
const UI_ANIMATION_SECONDS UI_ANIMATION_SECONDS_EVENTUALLY = -1.0;

// Defines results for animation updates
typedef [v1_enum] enum
{
    UI_ANIMATION_UPDATE_NO_CHANGE                   = 0,                                    // No animation variables changed
    UI_ANIMATION_UPDATE_VARIABLES_CHANGED           = 1                                     // One or more animation variables changed
} UI_ANIMATION_UPDATE_RESULT;

// Defines activity status for an animation manager
typedef [v1_enum] enum
{
    UI_ANIMATION_MANAGER_IDLE                       = 0,                                    // The animation manager is idle; no animations are currently playing
    UI_ANIMATION_MANAGER_BUSY                       = 1                                     // The animation manager is busy; one or more animations are currently playing
} UI_ANIMATION_MANAGER_STATUS;

// Defines animation modes
typedef [v1_enum] enum
{
    UI_ANIMATION_MODE_DISABLED                      = 0,                                    // Animation is disabled
    UI_ANIMATION_MODE_SYSTEM_DEFAULT                = 1,                                    // Animation is system managed
    UI_ANIMATION_MODE_ENABLED                       = 2                                     // Animation is enabled
} UI_ANIMATION_MODE;

// Defines the animation manager, which provides a central interface for creating and managing UI animations
[
    local,
    object,
    uuid(9169896C-AC8D-4e7d-94E5-67FA4DC2F2E8),
    helpstring("IUIAnimationManager Interface"),
    pointer_default(unique)
]
interface IUIAnimationManager : IUnknown
{
    // Creates a new animation variable
    UI_CHECKRETURN HRESULT
    CreateAnimationVariable
    (
                        [in, annotation("__in")] DOUBLE initialValue,                       // The initial value for the variable
        [out, retval, annotation("__deref_out")] IUIAnimationVariable **variable            // The new animation variable
    );
    
    // Creates and schedules a single-transition storyboard
    UI_CHECKRETURN HRESULT
    ScheduleTransition
    (
        [in, annotation("__in")] IUIAnimationVariable *variable,                            // The variable to schedule for transition
        [in, annotation("__in")] IUIAnimationTransition *transition,                        // The transition to apply to the variable
        [in, annotation("__in")] UI_ANIMATION_SECONDS timeNow                               // The current time
    );
    
    // Creates a new storyboard
    UI_CHECKRETURN HRESULT
    CreateStoryboard
    (
        [out, retval, annotation("__deref_out")] IUIAnimationStoryboard **storyboard        // The new storyboard
    );
    
    // Directs the animation manager to finish all active storyboards
    UI_CHECKRETURN HRESULT
    FinishAllStoryboards
    (
        [in, annotation("__in")] UI_ANIMATION_SECONDS completionDeadline                    // The maximum amount of time any storyboard is allowed
    );
    
    // Directs the animation manager to abandon all active storyboards
    UI_CHECKRETURN HRESULT
    AbandonAllStoryboards
    (
    );
    
    // Directs the animation manager to update the elapsed time for all scheduled storyboards
    UI_CHECKRETURN HRESULT 
    Update
    (
            [in, annotation("__in")] UI_ANIMATION_SECONDS timeNow,                          // The current time
        [out, defaultvalue(0),
            annotation("__out_opt")] UI_ANIMATION_UPDATE_RESULT *updateResult               // The update result
    );
    
    // Gets the animation variable with a specified tag
    UI_CHECKRETURN HRESULT
    GetVariableFromTag
    (
            [in, unique, annotation("__in_opt")] IUnknown *object,                          // The tag object
                        [in, annotation("__in")] UINT32 id,                                 // The tag ID
        [out, retval, annotation("__deref_out")] IUIAnimationVariable **variable            // The animation variable that matches the specified tag, or NULL if no match is found
    );
    
    // Gets the storyboard with a specified tag
    UI_CHECKRETURN HRESULT
    GetStoryboardFromTag
    (
            [in, unique, annotation("__in_opt")] IUnknown *object,                          // The tag object
                        [in, annotation("__in")] UINT32 id,                                 // The tag ID
        [out, retval, annotation("__deref_out")] IUIAnimationStoryboard **storyboard        // The animation storyboard that matches the specified tag, or NULL if no match is found
    );
    
    // Gets the animation manager's status
    UI_CHECKRETURN HRESULT
    GetStatus
    (
        [out, retval, annotation("__out")] UI_ANIMATION_MANAGER_STATUS *status              // The animation manager's status
    );
    
    // Sets the animation mode for the animation manager
    UI_CHECKRETURN HRESULT
    SetAnimationMode
    (
        [in, annotation("__in")] UI_ANIMATION_MODE mode                                     // The animation mode
    );
    
    // Pauses all animations
    UI_CHECKRETURN HRESULT
    Pause
    (
    );
    
    // Resumes all animations
    UI_CHECKRETURN HRESULT
    Resume
    (
    );
    
    // Specifies a handler for animation manager status updates
    UI_CHECKRETURN HRESULT
    SetManagerEventHandler
    (
        [in, unique, annotation("__in_opt")] IUIAnimationManagerEventHandler *handler       // A handler for animation manager status update events
    );
    
    // Sets a priority comparison handler for cancellation
    UI_CHECKRETURN HRESULT
    SetCancelPriorityComparison
    (
        [in, unique, annotation("__in_opt")] IUIAnimationPriorityComparison *comparison     // The handler for priority comparisons to determine if a scheduled storyboard can be cancelled
    );
    
    // Sets a priority comparison handler for trimming
    UI_CHECKRETURN HRESULT
    SetTrimPriorityComparison
    (
        [in, unique, annotation("__in_opt")] IUIAnimationPriorityComparison *comparison     // The handler for priority comparisons to determine if a scheduled storyboard can be trimmed
    );
    
    // Sets a priority comparison handler for compression
    UI_CHECKRETURN HRESULT
    SetCompressPriorityComparison
    (
        [in, unique, annotation("__in_opt")]  IUIAnimationPriorityComparison *comparison    // The handler for priority comparisons to determine if a scheduled storyboard can be compressed
    );
    
    // Sets a priority comparison handler for conclusion
    UI_CHECKRETURN HRESULT
    SetConcludePriorityComparison
    (
        [in, unique, annotation("__in_opt")] IUIAnimationPriorityComparison *comparison     // The handler for priority comparisons to determine if a scheduled storyboard can be concluded
    );
    
    // Sets the default acceptable animation delay
    UI_CHECKRETURN HRESULT
    SetDefaultLongestAcceptableDelay
    (
        [in, annotation("__in")] UI_ANIMATION_SECONDS delay                                 // The default value for acceptable delay before scheduled storyboards start
    );
    
    // Shuts down the animation manager and all objects it has created
    UI_CHECKRETURN HRESULT
    Shutdown
    (
    );
};

// Defines rounding modes to use when converting values from floating point to integer
typedef [v1_enum] enum
{
    UI_ANIMATION_ROUNDING_NEAREST                   = 0,                                    // Round to the nearest integer
    UI_ANIMATION_ROUNDING_FLOOR                     = 1,                                    // Round down
    UI_ANIMATION_ROUNDING_CEILING                   = 2                                     // Round up
} UI_ANIMATION_ROUNDING_MODE;

// Defines an animation variable, which represents a value that may be animated
[
    local,
    object,
    uuid(8CEEB155-2849-4ce5-9448-91FF70E1E4D9),
    helpstring("IUIAnimationVariable Interface"),
    pointer_default(unique)
]
interface IUIAnimationVariable : IUnknown
{
    // Gets the animation variable's current value
    UI_CHECKRETURN HRESULT
    GetValue
    (
        [out, retval, annotation("__out")] DOUBLE *value                                    // The current value
    );
    
    // Gets the animation variable's final value, after all currently scheduled animations have finished
    UI_CHECKRETURN HRESULT
    GetFinalValue
    (
        [out, retval, annotation("__out")] DOUBLE *finalValue                               // The final value
    );
    
    // Gets the animation variable's value before the most recent update
    UI_CHECKRETURN HRESULT
    GetPreviousValue
    (
        [out, retval, annotation("__out")] DOUBLE *previousValue                            // The previous value
    );
    
    // Gets the animation variable's current value, converted to INT32
    UI_CHECKRETURN HRESULT
    GetIntegerValue
    (
        [out, retval, annotation("__out")] INT32 *value                                     // The animation variable's current value, converted to INT32 
    );
    
    // Gets the animation variable's final value, converted to INT32
    UI_CHECKRETURN HRESULT
    GetFinalIntegerValue
    (
        [out, retval, annotation("__out")] INT32 *finalValue                                // The animation variable's final value, converted to INT32
    );
    
    // Gets the animation variable's value before the most recent update, converted to INT32
    UI_CHECKRETURN HRESULT
    GetPreviousIntegerValue
    (
        [out, retval, annotation("__out")] INT32 *previousValue                             // The animation variable's previous value, converted to INT32
    );
    
    // Gets the storyboard that is currently animating the variable
    UI_CHECKRETURN HRESULT
    GetCurrentStoryboard
    (
        [out, retval, annotation("__deref_out")] IUIAnimationStoryboard **storyboard        // The current storyboard, or NULL if no storyboard is currently animating the variable
    );
    
    // Sets the lower bound (floor) for the animation variable's value
    UI_CHECKRETURN HRESULT
    SetLowerBound
    (
        [in, annotation("__in")] DOUBLE bound                                               // The lower bound
    );
    
    // Sets the upper bound (ceiling) for the animation variable's value
    UI_CHECKRETURN HRESULT
    SetUpperBound
    (
        [in, annotation("__in")] DOUBLE bound                                               // The upper bound
    );
    
    // Specifies a rounding mode for the animation variable
    UI_CHECKRETURN HRESULT
    SetRoundingMode
    (
        [in, annotation("__in")] UI_ANIMATION_ROUNDING_MODE mode                            // A rounding mode for the animation variable
    );
    
    // Sets the animation variable's object/ID tag
    UI_CHECKRETURN HRESULT
    SetTag
    (
        [in, unique, annotation("__in_opt")] IUnknown *object,                              // The tag object
                    [in, annotation("__in")] UINT32 id                                      // The tag ID
    );
    
    // Gets the animation variable's object/ID tag
    UI_CHECKRETURN HRESULT
    GetTag
    (
        [out, annotation("__deref_opt_out")] IUnknown **object,                             // The tag object
              [out, annotation("__out_opt")] UINT32 *id                                     // The tag ID
    );
    
    // Specifies a handler for value updates
    UI_CHECKRETURN HRESULT
    SetVariableChangeHandler
    (
        [in, unique, annotation("__in_opt")] IUIAnimationVariableChangeHandler *handler     // A handler for animation variable value updates
    );
    
    // Specifies a handler for value updates; values are converted to INT32
    UI_CHECKRETURN HRESULT
    SetVariableIntegerChangeHandler
    (
        [in, unique,
            annotation("__in_opt")] IUIAnimationVariableIntegerChangeHandler *handler       // A handler for animation variable value updates
    );
};

// Defines status for a storyboard
typedef [v1_enum] enum
{
    UI_ANIMATION_STORYBOARD_BUILDING                = 0,                                    // The storyboard has not yet been scheduled
    UI_ANIMATION_STORYBOARD_SCHEDULED               = 1,                                    // The storyboard is scheduled to play
    UI_ANIMATION_STORYBOARD_CANCELLED               = 2,                                    // The storyboard was cancelled
    UI_ANIMATION_STORYBOARD_PLAYING                 = 3,                                    // The storyboard is currently playing
    UI_ANIMATION_STORYBOARD_TRUNCATED               = 4,                                    // The storyboard was truncated
    UI_ANIMATION_STORYBOARD_FINISHED                = 5,                                    // The storyboard finished playing
    UI_ANIMATION_STORYBOARD_READY                   = 6,                                    // The storyboard is built and ready for re-scheduling
    UI_ANIMATION_STORYBOARD_INSUFFICIENT_PRIORITY   = 7                                     // Scheduling failed; a scheduling conflict occurred, and the currently scheduled storyboard has higher priority
} UI_ANIMATION_STORYBOARD_STATUS;

// Defines results for storyboard scheduling
typedef [v1_enum] enum
{
    UI_ANIMATION_SCHEDULING_UNEXPECTED_FAILURE      = 0,                                    // Scheduling failed for an unexpected reason
    UI_ANIMATION_SCHEDULING_INSUFFICIENT_PRIORITY   = 1,                                    // Scheduling failed; a scheduling conflict occurred, and the currently scheduled storyboard has higher priority
    UI_ANIMATION_SCHEDULING_ALREADY_SCHEDULED       = 2,                                    // Scheduling failed; the storyboard is already scheduled
    UI_ANIMATION_SCHEDULING_SUCCEEDED               = 3,                                    // Scheduling succeeded
    UI_ANIMATION_SCHEDULING_DEFERRED                = 4                                     // Scheduling will be attempted when the current operation completes
} UI_ANIMATION_SCHEDULING_RESULT;

// Defines a keyframe, which represents a time offset within a storyboard
typedef struct { int _; } *UI_ANIMATION_KEYFRAME;

// Special value representing the implicit keyframe at the start of every storyboard
const UI_ANIMATION_KEYFRAME UI_ANIMATION_KEYFRAME_STORYBOARD_START = (UI_ANIMATION_KEYFRAME)(-1);

// Special value to direct a storyboard to repeat the interval between two keyframes indefinitely
const INT32 UI_ANIMATION_REPEAT_INDEFINITELY = -1;

// Defines a storyboard, which combines animation variables and transitions to define an animation
[
    local,
    object, 
    uuid(A8FF128F-9BF9-4af1-9E67-E5E410DEFB84),
    helpstring("IUIAnimationStoryboard Interface"),
    pointer_default(unique)
]
interface IUIAnimationStoryboard : IUnknown
{
    // Adds a transition to the storyboard
    UI_CHECKRETURN HRESULT
    AddTransition
    (
        [in, annotation("__in")] IUIAnimationVariable *variable,                            // The animation variable to transition
        [in, annotation("__in")] IUIAnimationTransition *transition                         // The transition to apply to the variable
    );
    
    // Adds a keyfame offset from an existing keyframe
    UI_CHECKRETURN HRESULT
    AddKeyframeAtOffset
    (
                  [in, annotation("__in")] UI_ANIMATION_KEYFRAME existingKeyframe,          // An existing keyframe
                  [in, annotation("__in")] UI_ANIMATION_SECONDS offset,                     // The offset from existingKeyframe at which to add keyframe
        [out, retval, annotation("__out")] UI_ANIMATION_KEYFRAME *keyframe                  // The new keyframe
    );
    
    // Adds a keyfame at the end of a specified transition
    UI_CHECKRETURN HRESULT
    AddKeyframeAfterTransition
    (
                  [in, annotation("__in")] IUIAnimationTransition *transition,              // The transition to add a keyframe after
        [out, retval, annotation("__out")] UI_ANIMATION_KEYFRAME *keyframe                  // The new keyframe
    );
    
    // Adds a transition that starts at a specified keyframe
    UI_CHECKRETURN HRESULT
    AddTransitionAtKeyframe
    (
        [in, annotation("__in")] IUIAnimationVariable *variable,                            // The animation variable to transition
        [in, annotation("__in")] IUIAnimationTransition *transition,                        // The transition to apply to the variable
        [in, annotation("__in")] UI_ANIMATION_KEYFRAME startKeyframe                        // A keyframe that specifies the beginning of the new transition
    );
    
    // Adds a transition between two keyframes
    UI_CHECKRETURN HRESULT
    AddTransitionBetweenKeyframes
    (
        [in, annotation("__in")] IUIAnimationVariable *variable,                            // The animation variable to transition
        [in, annotation("__in")] IUIAnimationTransition *transition,                        // The transition to apply to the variable
        [in, annotation("__in")] UI_ANIMATION_KEYFRAME startKeyframe,                       // A keyframe that specifies the beginning of the new transition
        [in, annotation("__in")] UI_ANIMATION_KEYFRAME endKeyframe                          // A keyframe that specifies the end of the new transition
    );
    
    // Creates a play cycle between two specified keyframes
    UI_CHECKRETURN HRESULT
    RepeatBetweenKeyframes
    (
        [in, annotation("__in")] UI_ANIMATION_KEYFRAME startKeyframe,                       // The keyframe at which to start the cycle
        [in, annotation("__in")] UI_ANIMATION_KEYFRAME endKeyframe,                         // The keyframe at which to end the cycle
        [in, annotation("__in")] INT32 repetitionCount                                      // The number of times to repeat; must be 1 or more, or UI_ANIMATION_REPEAT_INDEFINITELY
    );
    
    // Directs the storyboard to hold an animation variable at its final value until the storyboard ends
    UI_CHECKRETURN HRESULT
    HoldVariable
    (
        [in, annotation("__in")] IUIAnimationVariable *variable                             // The animation variable to hold
    );
    
    // Sets the longest acceptable delay before the storyboard plays
    UI_CHECKRETURN HRESULT
    SetLongestAcceptableDelay
    (
        [in, annotation("__in")] UI_ANIMATION_SECONDS delay                                 // The longest acceptable delay before the storyboard plays
    );
    
    // Directs the storyboard to schedule for play
    UI_CHECKRETURN HRESULT
    Schedule
    (
            [in, annotation("__in")] UI_ANIMATION_SECONDS timeNow,                          // The current time
        [out, defaultvalue(0),
            annotation("__out_opt")] UI_ANIMATION_SCHEDULING_RESULT *schedulingResult       // The result of the scheduling request
    );
    
    // Directs the storyboard to conclude
    UI_CHECKRETURN HRESULT
    Conclude
    (
    );
    
    // Directs the storyboard to finish playing within a specified amount of time
    UI_CHECKRETURN HRESULT
    Finish
    (
        [in, annotation("__in")] UI_ANIMATION_SECONDS completionDeadline                    // The maximum time the storyboard has to finish playing
    );
    
    // Directs the storyboard to abandon playing
    UI_CHECKRETURN HRESULT
    Abandon
    (
    );
    
    // Sets the storyboard's object/ID tag
    UI_CHECKRETURN HRESULT
    SetTag
    (
        [in, unique, annotation("__in_opt")] IUnknown *object,                              // The tag object
                    [in, annotation("__in")] UINT32 id                                      // The tag ID
    );
    
    // Gets the storyboard's object/ID tag
    UI_CHECKRETURN HRESULT
    GetTag
    (
        [out, annotation("__deref_opt_out")] IUnknown **object,                             // The tag object
              [out, annotation("__out_opt")] UINT32 *id                                     // The tag ID
    );
    
    // Gets the storyboard's status
    UI_CHECKRETURN HRESULT
    GetStatus
    (
        [out, retval, annotation("__out")] UI_ANIMATION_STORYBOARD_STATUS *status           // The storyboard's status
    );
    
    // Gets time elapsed since the storyboard started playing
    UI_CHECKRETURN HRESULT
    GetElapsedTime
    (
        [out, annotation("__out")] UI_ANIMATION_SECONDS *elapsedTime                        // Time elapsed since the storyboard started playing 
    );
    
    // Specifies a handler for storyboard status and update events
    UI_CHECKRETURN HRESULT
    SetStoryboardEventHandler
    (
        [in, unique, annotation("__in_opt")] IUIAnimationStoryboardEventHandler *handler    // A handler for storyboard status and update events
    );
};

// Defines a transition, which determines how an animation variable changes over time
[
    local,
    object,
    uuid(DC6CE252-F731-41cf-B610-614B6CA049AD),
    helpstring("IUIAnimationTransition Interface"),
    pointer_default(unique)
]
interface IUIAnimationTransition : IUnknown
{
    // Forces the transition to start at a given initial value
    UI_CHECKRETURN HRESULT
    SetInitialValue
    (
        [in, annotation("__in")] DOUBLE value                                               // The initial value
    );
    
    // Forces the transition to start with a given initial velocity
    UI_CHECKRETURN HRESULT
    SetInitialVelocity
    (
        [in, annotation("__in")] DOUBLE velocity                                            // The initial velocity
    );
    
    // Determines whether a transition's duration is currently known
    UI_CHECKRETURN HRESULT
    IsDurationKnown
    (
    );
    
    // Gets the transition's duration
    UI_CHECKRETURN HRESULT
    GetDuration
    (
        [out, retval, annotation("__out")] UI_ANIMATION_SECONDS *duration                   // The duration
    );
};

// Defines methods for handling animation manager status change events
[
    local,
    object,
    uuid(783321ED-78A3-4366-B574-6AF607A64788),
    helpstring("IUIAnimationManagerEventHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationManagerEventHandler  : IUnknown
{
    // Handles OnManagerStatusChanged events, which occur when the animation manager's status changes
    UI_CHECKRETURN HRESULT
    OnManagerStatusChanged
    (
        [in, annotation("__in")] UI_ANIMATION_MANAGER_STATUS newStatus,                     // The new status
        [in, annotation("__in")] UI_ANIMATION_MANAGER_STATUS previousStatus                 // The previous status
    );
};

// Defines methods for handling animation variable update events
[
    local,
    object,
    uuid(6358B7BA-87D2-42d5-BF71-82E919DD5862),
    helpstring("IUIAnimationVariableChangeHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationVariableChangeHandler  : IUnknown
{
    // Handles OnValueChanged events, which occur when an animation variable's value changes; receives value updates as DOUBLE
    UI_CHECKRETURN HRESULT
    OnValueChanged
    (
        [in, annotation("__in")] IUIAnimationStoryboard *storyboard,                        // The storyboard that is animating the variable
        [in, annotation("__in")] IUIAnimationVariable *variable,                            // The animation variable that was updated
        [in, annotation("__in")] DOUBLE newValue,                                           // The new value
        [in, annotation("__in")] DOUBLE previousValue                                       // The previous value
    );
};

// Defines methods for handling animation variable update events
[
    local,
    object,
    uuid(BB3E1550-356E-44b0-99DA-85AC6017865E),
    helpstring("IUIAnimationVariableIntegerChangeHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationVariableIntegerChangeHandler  : IUnknown
{
    // Handles OnIntegerValueChanged events, which occur when an animation variable's rounded value changes; receives value updates as INT32
    UI_CHECKRETURN HRESULT
    OnIntegerValueChanged
    (
        [in, annotation("__in")] IUIAnimationStoryboard *storyboard,                        // The storyboard that is animating the variable 
        [in, annotation("__in")] IUIAnimationVariable *variable,                            // The animation variable that was updated
        [in, annotation("__in")] INT32 newValue,                                            // The new rounded value
        [in, annotation("__in")] INT32 previousValue                                        // The previous rounded value
    );                                                              
};

// Defines methods for handling animation variable update events
[
    local,
    object,
    uuid(3D5C9008-EC7C-4364-9F8A-9AF3C58CBAE6),
    helpstring("IUIAnimationStoryboardEventHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationStoryboardEventHandler  : IUnknown
{
    // Handles OnStoryboardStatusChanged events, which occur when a storyboard's status changes
    UI_CHECKRETURN HRESULT
    OnStoryboardStatusChanged
    (
        [in, annotation("__in")] IUIAnimationStoryboard *storyboard,                        // The storyboard that changed status
        [in, annotation("__in")] UI_ANIMATION_STORYBOARD_STATUS newStatus,                  // The new status
        [in, annotation("__in")] UI_ANIMATION_STORYBOARD_STATUS previousStatus              // The previous status 
    );
    
    // Handles OnStoryboardUpdated events, which occur when a storyboard is updated
    UI_CHECKRETURN HRESULT
    OnStoryboardUpdated
    (
        [in, annotation("__in")] IUIAnimationStoryboard *storyboard                         // The storyboard that was updated
    );
};

// Defines the effect on the current attempt to schedule a storyboard if a priority comparison were to return S_FALSE
typedef [v1_enum] enum
{
    UI_ANIMATION_PRIORITY_EFFECT_FAILURE            = 0,                                    // The attempt to schedule the storyboard will fail
    UI_ANIMATION_PRIORITY_EFFECT_DELAY              = 1                                     // The storyboard will be schedule later than it would if the priority comparion were to return S_OK
} UI_ANIMATION_PRIORITY_EFFECT;

// Defines a priority comparison that the animation manager uses to resolve scheduling conflicts
[
    local,
    object,
    uuid(83FA9B74-5F86-4618-BC6A-A2FAC19B3F44),
    helpstring("IUIAnimationPriorityComparison Interface"),
    pointer_default(unique)
]
interface IUIAnimationPriorityComparison : IUnknown
{
    // Determines the relative priority between a scheduled storyboard and a new storyboard
    UI_CHECKRETURN HRESULT
    HasPriority
    (
        [in, annotation("__in")] IUIAnimationStoryboard *scheduledStoryboard,               // The currently scheduled storyboard
        [in, annotation("__in")] IUIAnimationStoryboard *newStoryboard,                     // The new storyboard that is in scheduling conflict with scheduledStoryboard
        [in, annotation("__in")] UI_ANIMATION_PRIORITY_EFFECT priorityEffect                // The effect on newStoryboard if scheduledStoryboard has priority
    );
};


// Defines animation slope characteristics
typedef [v1_enum] enum
{
    UI_ANIMATION_SLOPE_INCREASING                   = 0,                                    // The slope is increasing
    UI_ANIMATION_SLOPE_DECREASING                   = 1                                     // The slope is decreasing
} UI_ANIMATION_SLOPE;

// Defines a library of standard transitions
[
    local,
    object,
    uuid(CA5A14B1-D24F-48b8-8FE4-C78169BA954E),
    helpstring("IUIAnimationTransitionLibrary Interface"),
    pointer_default(unique)
]
interface IUIAnimationTransitionLibrary : IUnknown
{
    // Creates an instantaneous transition
    UI_CHECKRETURN HRESULT
    CreateInstantaneousTransition
    (
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new instantaneous transition
    );
    
    // Creates a constant-value transition
    UI_CHECKRETURN HRESULT
    CreateConstantTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new constant-value transition
    );
    
    // Creates a discrete transition
    UI_CHECKRETURN HRESULT
    CreateDiscreteTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS delay,                // The delay before the variable changes value
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
                        [in, annotation("__in")] UI_ANIMATION_SECONDS hold,                 // The hold time at the final value
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new discrete transition
    );
    
    // Creates a linear transition
    UI_CHECKRETURN HRESULT
    CreateLinearTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new linear transition
    );
    
    // Creates a linear transition with a given speed
    UI_CHECKRETURN HRESULT
    CreateLinearTransitionFromSpeed
    (
                        [in, annotation("__in")] DOUBLE speed,                              // The speed, in units/second, at which the variable will transition to the final value
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new linear transition
    );
    
    // Creates a sinusoidal transition with an amplitude determined by its initial velocity
    UI_CHECKRETURN HRESULT
    CreateSinusoidalTransitionFromVelocity
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
                        [in, annotation("__in")] UI_ANIMATION_SECONDS period,               // The duration of each cycle
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new sinusoidal transition
    );
    
    // Creates a sinusoidal transition with a given range of oscillation
    UI_CHECKRETURN HRESULT
    CreateSinusoidalTransitionFromRange
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
                        [in, annotation("__in")] DOUBLE minimumValue,                       // The value at each trough of the sine wave
                        [in, annotation("__in")] DOUBLE maximumValue,                       // The value at each peak of the sine wave
                        [in, annotation("__in")] UI_ANIMATION_SECONDS period,               // The duration of each cycle
                        [in, annotation("__in")] UI_ANIMATION_SLOPE slope,                  // The slope at the start of the transition
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new sinusoidal transition
    );
    
    // Creates an accelerate-decelerate transition
    UI_CHECKRETURN HRESULT
    CreateAccelerateDecelerateTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
                        [in, annotation("__in")] DOUBLE accelerationRatio,                  // The fraction of the duration to spend accelerating
                        [in, annotation("__in")] DOUBLE decelerationRatio,                  // The fraction of the duration to spend decelerating
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new accelerate-decelerate transition
    );
    
    // Creates a reversal transition
    UI_CHECKRETURN HRESULT
    CreateReversalTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new reversal transition
    );
    
    // Creates a cubic transition
    UI_CHECKRETURN HRESULT
    CreateCubicTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS duration,             // The transition duration
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
                        [in, annotation("__in")] DOUBLE finalVelocity,                      // The final velocity
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new cubic transition
    );
    
    // Creates a smooth-stop transition
    UI_CHECKRETURN HRESULT
    CreateSmoothStopTransition
    (
                        [in, annotation("__in")] UI_ANIMATION_SECONDS maximumDuration,      // The maximum duration for the transition
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new smooth-stop transition
    );
    
    // Creates a parabolic transition with a given acceleration    
    UI_CHECKRETURN HRESULT
    CreateParabolicTransitionFromAcceleration
    (
                        [in, annotation("__in")] DOUBLE finalValue,                         // The final value this transition leads to when applied to an animation variable
                        [in, annotation("__in")] DOUBLE finalVelocity,                      // The final velocity
                        [in, annotation("__in")] DOUBLE acceleration,                       // The rate of change of the velocity
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new parabolic transition
    );
};


//////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Interpolator API

// Defines the aspects of an interpolator that depend on a given input
typedef [v1_enum] enum
{
    UI_ANIMATION_DEPENDENCY_NONE                    = 0x00000000,                           // No aspects depend on the input
    UI_ANIMATION_DEPENDENCY_INTERMEDIATE_VALUES     = 0x00000001,                           // The intermediate values depend on the input
    UI_ANIMATION_DEPENDENCY_FINAL_VALUE             = 0x00000002,                           // The final value depends on the input
    UI_ANIMATION_DEPENDENCY_FINAL_VELOCITY          = 0x00000004,                           // The final velocity depends on the input
    UI_ANIMATION_DEPENDENCY_DURATION                = 0x00000008                            // The duration depends on the input
} UI_ANIMATION_DEPENDENCIES;

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(UI_ANIMATION_DEPENDENCIES);")

// Defines methods for creating a custom interpolator
[
    local,
    object,
    uuid(7815CBBA-DDF7-478c-A46C-7B6C738B7978),
    helpstring("IUIAnimationInterpolator Interface"),
    pointer_default(unique)
]
interface IUIAnimationInterpolator : IUnknown
{
    // Sets the interpolator's initial value and velocity
    UI_CHECKRETURN HRESULT
    SetInitialValueAndVelocity
    (
        [in, annotation("__in")] DOUBLE initialValue,                                       // The initial value
        [in, annotation("__in")] DOUBLE initialVelocity                                     // The initial velocity
    );
    
    // Sets the interpolator's duration
    UI_CHECKRETURN HRESULT
    SetDuration
    (
        [in, annotation("__in")] UI_ANIMATION_SECONDS duration                              // The interpolator duration
    );
    
    // Gets the interpolator's duration
    UI_CHECKRETURN HRESULT
    GetDuration
    (
        [out, retval, annotation("__out")] UI_ANIMATION_SECONDS *duration                   // The interpolator duration
    );
    
    // Gets the final value to which the interpolator leads
    UI_CHECKRETURN HRESULT
    GetFinalValue
    (
        [out, retval, annotation("__out")] DOUBLE *value                                    // The final value
    ); 
    
    // Interpolates the value at a given offset
    UI_CHECKRETURN HRESULT
    InterpolateValue
    (
                  [in, annotation("__in")] UI_ANIMATION_SECONDS offset,                     // The offset
        [out, retval, annotation("__out")] DOUBLE *value                                    // The interpolated value
    );
    
    // Interpolates the velocity at a given offset
    UI_CHECKRETURN HRESULT
    InterpolateVelocity
    (
                  [in, annotation("__in")] UI_ANIMATION_SECONDS offset,                     // The offset
        [out, retval, annotation("__out")] DOUBLE *velocity                                 // The interpolated velocity
    );
    
    // Get's the interpolator's dependencies
    UI_CHECKRETURN HRESULT
    GetDependencies
    (
        [out, annotation("__out")] UI_ANIMATION_DEPENDENCIES *initialValueDependencies,     // The aspects of the interpolator that depend on its initial value
        [out, annotation("__out")] UI_ANIMATION_DEPENDENCIES *initialVelocityDependencies,  // The aspects of the interpolator that depend on its initial velocity
        [out, annotation("__out")] UI_ANIMATION_DEPENDENCIES *durationDependencies          // The aspects of the interpolator that depend on its duration
    );
};

// Defines methods for creating transitions from custom interpolators
[
    local,
    object,
    uuid(FCD91E03-3E3B-45ad-BBB1-6DFC8153743D),
    helpstring("IUIAnimationTransitionFactory Interface"),
    pointer_default(unique)
]
interface IUIAnimationTransitionFactory : IUnknown
{
    // Creates a transition from a custom interpolator
    UI_CHECKRETURN HRESULT
    CreateTransition
    (
                        [in, annotation("__in")] IUIAnimationInterpolator *interpolator,    // The interpolator to create a transition from
        [out, retval, annotation("__deref_out")] IUIAnimationTransition **transition        // The new transition
    );
};


//////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Timer API

// Defines behaviors for a timer when its client is idle
typedef [v1_enum] enum
{
    UI_ANIMATION_IDLE_BEHAVIOR_CONTINUE             = 0,                                    // The timer continues to generate timer events (is enabled) when the client is idle
    UI_ANIMATION_IDLE_BEHAVIOR_DISABLE              = 1                                     // The timer is suspended (disabled) when the animation manager is idle
} UI_ANIMATION_IDLE_BEHAVIOR;

// Defines an animation timer, which provides services for managing animation timing
[
    local,
    object,
    uuid(6B0EFAD1-A053-41d6-9085-33A689144665),
    helpstring("IUIAnimationTimer Interface"),
    pointer_default(unique)
]
interface IUIAnimationTimer : IUnknown
{
    // Specifies a handler for timing updates
    UI_CHECKRETURN HRESULT
    SetTimerUpdateHandler
    (
        [in, unique, annotation("__in_opt")] IUIAnimationTimerUpdateHandler *updateHandler, // A handler for timing events
                    [in, annotation("__in")] UI_ANIMATION_IDLE_BEHAVIOR idleBehavior        // The desired behavior of the timer when it is idle
    );
    
    // Specifies a handler for timing events
    UI_CHECKRETURN HRESULT
    SetTimerEventHandler
    (
        [in, unique, annotation("__in_opt")] IUIAnimationTimerEventHandler *handler         // A handler for timing events
    );
    
    // Enables the animation timer
    UI_CHECKRETURN HRESULT
    Enable
    (
    );
    
    // Disables the animation timer
    UI_CHECKRETURN HRESULT
    Disable
    (
    );
    
    // Determines whether the timer is currently enabled
    UI_CHECKRETURN HRESULT
    IsEnabled
    (
    );
    
    // Gets the current time
    UI_CHECKRETURN HRESULT
    GetTime
    (
        [out, annotation("__out")] UI_ANIMATION_SECONDS *seconds                            // Current update time
    );
    
    // Sets the frame rate below which the timer event handler will be called
    UI_CHECKRETURN HRESULT
    SetFrameRateThreshold
    (
        [in, annotation("__in")] UINT32 framesPerSecond                                     // The minimum acceptable frame rate, in frames-per-second
    );
};

// Defines methods for handling timing update events
[
    local,
    object,
    uuid(195509B7-5D5E-4e3e-B278-EE3759B367AD),
    helpstring("IUIAnimationTimerUpdateHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationTimerUpdateHandler : IUnknown
{
    // Handles OnUpdate events, which occur when it is time to update an animation
    UI_CHECKRETURN HRESULT
    OnUpdate
    (
                  [in, annotation("__in")] UI_ANIMATION_SECONDS timeNow,                    // The current time
        [out, retval, annotation("__out")] UI_ANIMATION_UPDATE_RESULT *result               // The result of the animation update
    );
    
    // Specifies a handler for timer client status change events
    UI_CHECKRETURN HRESULT
    SetTimerClientEventHandler
    (
        [in, annotation("__in")] IUIAnimationTimerClientEventHandler *handler               // A handler for timer client events
    );
    
    // Clears the handler for timer client status change events
    UI_CHECKRETURN HRESULT
    ClearTimerClientEventHandler
    (
    );
};

// Defines activity status for a timer's client
typedef [v1_enum] enum
{
    UI_ANIMATION_TIMER_CLIENT_IDLE                  = 0,                                    // The timer's client is idle
    UI_ANIMATION_TIMER_CLIENT_BUSY                  = 1                                     // The timer's client is busy
} UI_ANIMATION_TIMER_CLIENT_STATUS;

// Defines methods for handling events related to changes in timer client status
[
    local,
    object,
    uuid(BEDB4DB6-94FA-4bfb-A47F-EF2D9E408C25),
    helpstring("IUIAnimationTimerClientEventHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationTimerClientEventHandler  : IUnknown
{
    // Handles OnTimerClientStatusChanged events, which occur when the timer client's status changes
    UI_CHECKRETURN HRESULT
    OnTimerClientStatusChanged
    (
        [in, annotation("__in")] UI_ANIMATION_TIMER_CLIENT_STATUS newStatus,                // The new status
        [in, annotation("__in")] UI_ANIMATION_TIMER_CLIENT_STATUS previousStatus            // The previous status
    );
};

// Defines methods for handling timing events
[
    local,
    object,
    uuid(274A7DEA-D771-4095-ABBD-8DF7ABD23CE3),
    helpstring("IUIAnimationTimerEventHandler Interface"),
    pointer_default(unique)
]
interface IUIAnimationTimerEventHandler : IUnknown
{
    // Handles OnPreUpdate events, which occur before an animation update begins
    UI_CHECKRETURN HRESULT
    OnPreUpdate
    (
    );
    
    // Handles OnPostUpdate events, which occur after an animation update is finished
    UI_CHECKRETURN HRESULT
    OnPostUpdate
    (
    );
    
    // Handles OnRenderingTooSlow events, which occur when the rendering frame rate for an animation falls below the minimum acceptable frame rate
    UI_CHECKRETURN HRESULT
    OnRenderingTooSlow
    (
        [in, annotation("__in")] UINT32 framesPerSecond                                     // The current frame rate, in frames-per-second
    );
};


//////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Type Library

[
    uuid(44CA24DB-1A92-4149-BAB5-FB14D64B401E),
    version(1.0),
    helpstring("UIAnimation 1.0 Type Library")
]
library UIAnimation
{
    importlib("stdole32.tlb");

    [
        uuid(4C1FC63A-695C-47E8-A339-1A194BE3D0B8),
        helpstring("UIAnimationManager Class")
    ]
    coclass UIAnimationManager
    {
        [default] interface IUIAnimationManager;
    };

    [
        uuid(1D6322AD-AA85-4EF5-A828-86D71067D145),
        helpstring("UIAnimationTransitionLibrary Class")
    ]
    coclass UIAnimationTransitionLibrary
    {
        [default] interface IUIAnimationTransitionLibrary;
    };

    [
        uuid(8A9B1CDD-FCD7-419c-8B44-42FD17DB1887),
        helpstring("UIAnimationTransitionFactory Class")
    ]
    coclass UIAnimationTransitionFactory
    {
        [default] interface IUIAnimationTransitionFactory;
    };

    [
        uuid(BFCD4A0C-06B6-4384-B768-0DAA792C380E),
        helpstring("UIAnimationTimer Class")
    ]
    coclass UIAnimationTimer
    {
        [default] interface IUIAnimationTimer;
    };
};


#undef UI_CHECKRETURN

