CAnimationController Class

Article
08/03/2021

Implements the animation controller, which provides a central interface for creating and managing animations.

Syntax

class CAnimationController : public CObject;

Members

Public Constructors

Name	Description
CAnimationController::CAnimationController	Constructs an animation controller.
CAnimationController::~CAnimationController	The destructor. Called when animation controller object is being destroyed.

Public Methods

Name	Description
CAnimationController::AddAnimationObject	Adds an animation object to a group that belongs to the animation controller.
CAnimationController::AddKeyframeToGroup	Adds a keyframe to group.
CAnimationController::AnimateGroup	Prepares a group to run animation and optionally schedules it.
CAnimationController::CleanUpGroup	Overloaded. Called by the framework to clean up the group when animation has been scheduled.
CAnimationController::CreateKeyframe	Overloaded. Creates a keyframe that depends on transition and adds it to the specified group.
CAnimationController::EnableAnimationManagerEvent	Sets or releases a handler to call when animation manager's status changes.
CAnimationController::EnableAnimationTimerEventHandler	Sets or releases a handler for timing events and handler for timing updates.
CAnimationController::EnablePriorityComparisonHandler	Sets or releases the priority comparison handler to call to determine whether a scheduled storyboard can be canceled, concluded, trimmed or compressed.
CAnimationController::EnableStoryboardEventHandler	Sets or releases a handler for storyboard status and update events.
CAnimationController::FindAnimationGroup	Overloaded. Finds an animation group by its storyboard.
CAnimationController::FindAnimationObject	Finds animation object containing a specified animation variable.
CAnimationController::GetKeyframeStoryboardStart	Returns a keyframe that identifies start of storyboard.
CAnimationController::GetUIAnimationManager	Provides access to encapsulated IUIAnimationManager object.
CAnimationController::GetUIAnimationTimer	Provides access to encapsulated IUIAnimationTimer object.
CAnimationController::GetUITransitionFactory	A pointer to IUIAnimationTransitionFactory interface or NULL, if creation of transition library failed.
CAnimationController::GetUITransitionLibrary	Provides access to encapsulated IUIAnimationTransitionLibrary object.
CAnimationController::IsAnimationInProgress	Tells whether at least one group is playing animation.
CAnimationController::IsValid	Tells whether animation controller is valid.
CAnimationController::OnAnimationIntegerValueChanged	Called by the framework when integer value of animation variable has changed.
CAnimationController::OnAnimationManagerStatusChanged	Called by the framework in response to StatusChanged event from animation manager.
CAnimationController::OnAnimationTimerPostUpdate	Called by the framework after an animation update is finished.
CAnimationController::OnAnimationTimerPreUpdate	Called by the framework before an animation update begins.
CAnimationController::OnAnimationTimerRenderingTooSlow	Called by the framework when the rendering frame rate for an animation falls below a minimum desirable frame rate.
CAnimationController::OnAnimationValueChanged	Called by the framework when value of animation variable has changed.
CAnimationController::OnBeforeAnimationStart	Called by the framework right before the animation is scheduled.
CAnimationController::OnHasPriorityCancel	Called by the framework to resolve scheduling conflicts.
CAnimationController::OnHasPriorityCompress	Called by the framework to resolve scheduling conflicts.
CAnimationController::OnHasPriorityConclude	Called by the framework to resolve scheduling conflicts.
CAnimationController::OnHasPriorityTrim	Called by the framework to resolve scheduling conflicts.
CAnimationController::OnStoryboardStatusChanged	Called by the framework when storyboard status has changed.
CAnimationController::OnStoryboardUpdated	Called by the framework when storyboard has been updated.
CAnimationController::RemoveAllAnimationGroups	Removes all animation groups from animation controller.
CAnimationController::RemoveAnimationGroup	Removes an animation group with specified ID from animation controller.
CAnimationController::RemoveAnimationObject	Remove an animation object from animation controller.
CAnimationController::RemoveTransitions	Removes transitions from animation objects that belong to the specified group.
CAnimationController::ScheduleGroup	Schedules an animation.
CAnimationController::SetRelatedWnd	Establishes a relationship between animation controller and a window.
CAnimationController::UpdateAnimationManager	Directs the animation manager to update the values of all animation variables.

Protected Methods

Name	Description
CAnimationController::CleanUpGroup	Overloaded. A helper that cleans up the group.
CAnimationController::OnAfterSchedule	Called by the framework when an animation for the specified group has just been scheduled.

Protected Data Members

Name	Description
CAnimationController::gkeyframeStoryboardStart	A keyframe that represents start of storyboard.
CAnimationController::m_bIsValid	Specifies whether an animation controller is valid or not. This member is set to FALSE if current OS does not support Windows Animation API.
CAnimationController::m_lstAnimationGroups	A list of animation groups that belong to this animation controller.
CAnimationController::m_pAnimationManager	Stores a pointer to Animation Manager COM object.
CAnimationController::m_pAnimationTimer	Stores a pointer to Animation Timer COM object.
CAnimationController::m_pRelatedWnd	A pointer to a related CWnd object, which can be automatically redrawn when the status of animation manager has changed, or post update event has occurred. Can be NULL.
CAnimationController::m_pTransitionFactory	Stores a pointer to Transition Factory COM object.
CAnimationController::m_pTransitionLibrary	Stores a pointer to Transition Library COM object.

Remarks

The CAnimationController class is the key class that manages animations. You may create one or more instances of animation controller in an application and, optionally, connect an instance of animation controller to a CWnd object using CAnimationController::SetRelatedWnd. This connection is required to send WM_PAINT messages to the related window automatically when animation manager status has changed or animation timer has been updated. If you do not enable this relation, you must redraw a window that displays an animation manually. For this purpose you can derive a class from CAnimationController and override OnAnimationManagerStatusChanged and/or OnAnimationTimerPostUpdate and invalidate one or more windows when necessary.

Inheritance Hierarchy

CObject

CAnimationController

Requirements

Header: afxanimationcontroller.h

CAnimationController::~CAnimationController

The destructor. Called when animation controller object is being destroyed.

virtual ~CAnimationController(void);

CAnimationController::AddAnimationObject

Adds an animation object to a group that belongs to the animation controller.

CAnimationGroup* AddAnimationObject(CAnimationBaseObject* pObject);

Parameters

pObject
A pointer to an animation object.

Return Value

A pointer to existing or new animation group where pObject has been added if function succeeds; NULL if pObject has already been added to a group that belongs to another animation controller.

Remarks

Call this method to add an animation object to the animation controller. An object will be added to a group according to object's GroupID (see CAnimationBaseObject::SetID). The animation controller will create a new group if it's the first object being added with the specified GroupID. An animation object can be added to one animation controller only. If you need to add an object to another controller, call RemoveAnimationObject first. If you call SetID with new GroupID for an object that has been already added to a group, the object will be removed from the old group and added to another group with specified ID.

CAnimationController::AddKeyframeToGroup

Adds a keyframe to group.

BOOL AddKeyframeToGroup(
    UINT32 nGroupID,
    CBaseKeyFrame* pKeyframe);

Parameters

nGroupID
Specifies Group ID.

pKeyframe
A pointer to a keyframe.

Return Value

TRUE if the function succeeds; otherwise FALSE.

Remarks

Usually you don't need to call this method, use CAnimationController::CreateKeyframe instead, which creates and adds the created keyframe to a group automatically.

CAnimationController::AnimateGroup

Prepares a group to run animation and optionally schedules it.

BOOL AnimateGroup(
    UINT32 nGroupID,
    BOOL bScheduleNow = TRUE);

Parameters

nGroupID
Specifies GroupID.

bScheduleNow
Specifies whether to run animation right away.

Return Value

TRUE if animation was successfully scheduled and run.

Remarks

This method does the actual work creating storyboard, adding animation variables, applying transitions and setting keyframes. It's possible to delay scheduling if you set bScheduleNow to FALSE. In this case the specified group will hold a storyboard that has been set up for animation. At that point you can setup events for the storyboard and animation variables. When you actually need to run the animation call CAnimationController::ScheduleGroup.

CAnimationController::CAnimationController

Constructs an animation controller.

CAnimationController(void);

CAnimationController::CleanUpGroup

Called by the framework to clean up the group when animation has been scheduled.

void CleanUpGroup(UINT32 nGroupID);
void CleanUpGroup(CAnimationGroup* pGroup);

Parameters

nGroupID
Specifies GroupID.

pGroup
A pointer to animation group to clean.

Remarks

This method removes all transitions and keyframes from the specified group, because they are not relevant after an animation has been scheduled.

CAnimationController::CreateKeyframe

Creates a keyframe that depends on transition and adds it to the specified group.

CKeyFrame* CreateKeyframe(
    UINT32 nGroupID,
    CBaseTransition* pTransition);

CKeyFrame* CreateKeyframe(
    UINT32 nGroupID,
    CBaseKeyFrame* pKeyframe,
    UI_ANIMATION_SECONDS offset = 0.0);

Parameters

nGroupID
Specifies Group ID for which keyframe is created.

pTransition
A pointer to transition. Keyframe will be inserted to storyboard after this transition.

pKeyframe
A pointer to base keyframe for this keyframe.

offset
Offset in seconds from the base keyframe specified by pKeyframe.

Return Value

A pointer to newly created keyframe if the function succeeds.

Remarks

You can store the returned pointer and base other keyframes on the newly created keyframe (see the second overload). It's possible to begin transitions at keyframes - see CBaseTransition::SetKeyframes. You don't need to delete keyframes created in this way, because they are deleted automatically by animation groups. Be careful when creating keyframes based on other keyframes and transitions and avoid circular references.

CAnimationController::EnableAnimationManagerEvent

Sets or releases a handler to call when animation manager's status changes.

virtual BOOL EnableAnimationManagerEvent(BOOL bEnable = TRUE);

Parameters

bEnable
Specifies whether to set or release a handler.

Return Value

TRUE if the handler was successfully set or released.

Remarks

When a handler is set (enabled) Windows Animation calls OnAnimationManagerStatusChanged when animation manager's status changes.

CAnimationController::EnableAnimationTimerEventHandler

Sets or releases a handler for timing events and handler for timing updates.

virtual BOOL EnableAnimationTimerEventHandler(
    BOOL bEnable = TRUE,
    UI_ANIMATION_IDLE_BEHAVIOR idleBehavior = UI_ANIMATION_IDLE_BEHAVIOR_DISABLE);

Parameters

bEnable
Specifies whether to set or release the handlers.

idleBehavior
Specifies idle behavior for timer update handler.

Return Value

TRUE if handlers were successfully set or released; FALSE if this method is called for a second time without releasing the handlers first, or if any other error occurs.

Remarks

When the handlers are set (enabled) Windows Animation API calls OnAnimationTimerPreUpdate, OnAnimationTimerPostUpdate, OnRenderingTooSlow methods. You need to enable animation timers to allow Windows Animation API update storyboards. Otherwise you'll need to call CAnimationController::UpdateAnimationManager in order to direct the animation manager to update the values of all animation variables.

CAnimationController::EnablePriorityComparisonHandler

Sets or releases the priority comparison handler to call to determine whether a scheduled storyboard can be canceled, concluded, trimmed or compressed.

virtual BOOL EnablePriorityComparisonHandler(DWORD dwHandlerType);

Parameters

dwHandlerType
A combination of UI_ANIMATION_PHT_ flags (see remarks), which specifies what handlers to set or release.

Return Value

TRUE if the handler was successfully set or released.

Remarks

When a handler is set (enabled) Windows Animation calls the following virtual methods depending on dwHandlerType: OnHasPriorityCancel, OnHasPriorityConclude, OnHasPriorityTrim, OnHasPriorityCompress. dwHandler can be a combination of the following flags: UI_ANIMATION_PHT_NONE - release all handlers UI_ANIMATION_PHT_CANCEL - set Cancel comparison handler UI_ANIMATION_PHT_CONCLUDE - set Conclude comparison handler UI_ANIMATION_PHT_COMPRESS - set Compress comparison handler UI_ANIMATION_PHT_TRIM - set Trim comparison handler UI_ANIMATION_PHT_CANCEL_REMOVE - remove Cancel comparison handler UI_ANIMATION_PHT_CONCLUDE_REMOVE - remove Conclude comparison handler UI_ANIMATION_PHT_COMPRESS_REMOVE - remove Compress comparison handler UI_ANIMATION_PHT_TRIM_REMOVE - remove Trim comparison handler

CAnimationController::EnableStoryboardEventHandler

Sets or releases a handler for storyboard status and update events.

virtual BOOL EnableStoryboardEventHandler(
    UINT32 nGroupID,
    BOOL bEnable = TRUE);

Parameters

nGroupID
Specifies Group ID.

bEnable
Specifies whether to set or release a handler.

Return Value

TRUE if the handler was successfully set or released; FALSE if the specified animation group is now found or animation for the specified group has not been initiated and its internal storyboard is NULL.

Remarks

When a handler is set (enabled) Windows Animation API calls OnStoryboardStatusChanges and OnStoryboardUpdated virtual methods. A handler must be set after CAnimationController::Animate has been called for the specified animation group, because it creates encapsulated IUIAnimationStoryboard object.

CAnimationController::FindAnimationGroup

Finds an animation group by its Group ID.

CAnimationGroup* FindAnimationGroup(UINT32 nGroupID);
CAnimationGroup* FindAnimationGroup(IUIAnimationStoryboard* pStoryboard);

Parameters

nGroupID
Specifies a GroupID.

pStoryboard
A pointer to a storyboard.

Return Value

A pointer to animation group or NULL if the group with specified ID is not found.

Remarks

Use this method to find an animation group at runtime. A group is created and added to the internal list of animation groups when a first animation object with particular GroupID is being added to animation controller.

CAnimationController::FindAnimationObject

Finds animation object containing a specified animation variable.

BOOL FindAnimationObject(
    IUIAnimationVariable* pVariable,
    CAnimationBaseObject** ppObject,
    CAnimationGroup** ppGroup);

Parameters

pVariable
A pointer to animation variable.

ppObject
Output. Contains a pointer to animation object or NULL.

ppGroup
Output. Contains a pointer to animation group that holds the animation object, or NULL.

Return Value

TRUE if object was found; otherwise FALSE.

Remarks

Called from event handlers when it's required to find an animation object from incoming animation variable.

CAnimationController::gkeyframeStoryboardStart

A keyframe that represents start of storyboard.

static CBaseKeyFrame gkeyframeStoryboardStart;

CAnimationController::GetKeyframeStoryboardStart

Returns a keyframe that identifies start of storyboard.

static CBaseKeyFrame* GetKeyframeStoryboardStart();

Return Value

A pointer to base keyframe, which identifies start of storyboard.

Remarks

Obtain this keyframe to base any other keyframes or transitions on the moment in time when a storyboard starts.

CAnimationController::GetUIAnimationManager

Provides access to encapsulated IUIAnimationManager object.

IUIAnimationManager* GetUIAnimationManager();

Return Value

A pointer to IUIAnimationManager interface or NULL, if creation of animation manager failed.

Remarks

If current OS does not support Windows Animation API, this method returns NULL and after that all subsequent calls on CAnimationController::IsValid return FALSE. You may need to access IUIAnimationManager in order to call its interface methods, which are not wrapped by animation controller.

CAnimationController::GetUIAnimationTimer

Provides access to encapsulated IUIAnimationTimer object.

IUIAnimationTimer* GetUIAnimationTimer();

Return Value

A pointer to IUIAnimationTimer interface or NULL, if creation of animation timer failed.

Remarks

If current OS does not support Windows Animation API, this method returns NULL and after that all subsequent calls on CAnimationController::IsValid return FALSE.

CAnimationController::GetUITransitionFactory

A pointer to IUIAnimationTransitionFactory interface or NULL, if creation of transition library failed.

IUIAnimationTransitionFactory* GetUITransitionFactory();

Return Value

A pointer to IUIAnimationTransitionFactory or NULL, if creation of transition factory failed.

Remarks

If current OS does not support Windows Animation API, this method returns NULL and after that all subsequent calls on CAnimationController::IsValid return FALSE.

CAnimationController::GetUITransitionLibrary

Provides access to encapsulated IUIAnimationTransitionLibrary object.

IUIAnimationTransitionLibrary* GetUITransitionLibrary();

Return Value

A pointer to IUIAnimationTransitionLibrary interface or NULL, if creation of transition library failed.

Remarks

If current OS does not support Windows Animation API, this method returns NULL and after that all subsequent calls on CAnimationController::IsValid return FALSE.

CAnimationController::IsAnimationInProgress

Tells whether at least one group is playing animation.

virtual BOOL IsAnimationInProgress();

Return Value

TRUE if there is an animation in progress for this animation controller; otherwise FALSE.

Remarks

Checks status of animation manager and returns TRUE if the status is UI_ANIMATION_MANAGER_BUSY.

CAnimationController::IsValid

Tells whether animation controller is valid.

BOOL IsValid() const;

Return Value

TRUE if animation controller is valid; otherwise FALSE.

Remarks

This method returns FALSE only if Windows Animation API is not supported on the current OS and creation of animation manager failed because it's not registered. You need to call GetUIAnimationManager at least once after initialization of COM libraries to cause setting of this flag.

CAnimationController::m_bIsValid

Specifies whether an animation controller is valid or not. This member is set to FALSE if current OS does not support Windows Animation API.

BOOL m_bIsValid;

CAnimationController::m_lstAnimationGroups

A list of animation groups that belong to this animation controller.

CList<CAnimationGroup*, CAnimationGroup*> m_lstAnimationGroups;

CAnimationController::m_pAnimationManager

Stores a pointer to Animation Manager COM object.

ATL::CComPtr<IUIAnimationManager> m_pAnimationManager;

CAnimationController::m_pAnimationTimer

Stores a pointer to Animation Timer COM object.

ATL::CComPtr<IUIAnimationTimer> m_pAnimationTimer;

CAnimationController::m_pRelatedWnd

A pointer to a related CWnd object, which can be automatically redrawn when the status of animation manager has changed, or post update event has occurred. Can be NULL.

CWnd* m_pRelatedWnd;

CAnimationController::m_pTransitionFactory

Stores a pointer to Transition Factory COM object.

ATL::CComPtr<IUIAnimationTransitionFactory> m_pTransitionFactory;

CAnimationController::m_pTransitionLibrary

Stores a pointer to Transition Library COM object.

ATL::CComPtr<IUIAnimationTransitionLibrary> m_pTransitionLibrary;

CAnimationController::OnAfterSchedule

Called by the framework when an animation for the specified group has just been scheduled.

virtual void OnAfterSchedule(CAnimationGroup* pGroup);

Parameters

pGroup
A pointer to an animation group, which has been scheduled.

Remarks

The default implementation removes keyframes from the specified group and transitions from animation variables that belong to the specified group. Can be overridden in a derived class to take any additional actions upon animation schedule.

CAnimationController::OnAnimationIntegerValueChanged

Called by the framework when integer value of animation variable has changed.

virtual void OnAnimationIntegerValueChanged(
    CAnimationGroup* pGroup,
    CAnimationBaseObject* pObject,
    IUIAnimationVariable* variable,
    INT32 newValue,
    INT32 prevValue);

Parameters

pGroup
A pointer to an animation group that holds an animation object whose value has changed.

pObject
A pointer to an animation object that contains an animation variable whose value has changed.

variable
A pointer to an animation variable.

newValue
Specifies new value.

prevValue
Specifies previous value.

Remarks

This method is called if you enable animation variable events with EnableIntegerValueChangedEvent called for a specific animation variable or animation object. It can be overridden in a derived class to take application-specific actions.

CAnimationController::OnAnimationManagerStatusChanged

Called by the framework in response to StatusChanged event from animation manager.

virtual void OnAnimationManagerStatusChanged(
    UI_ANIMATION_MANAGER_STATUS newStatus,
    UI_ANIMATION_MANAGER_STATUS previousStatus);

Parameters

newStatus
New animation manager status.

previousStatus
Previous animation manager status.

Remarks

This method is called if you enable animation manager events with EnableAnimationManagerEvent. It can be overridden in a derived class to take application-specific actions. The default implementation updates a related window if it has been set with SetRelatedWnd.

CAnimationController::OnAnimationTimerPostUpdate

Called by the framework after an animation update is finished.

virtual void OnAnimationTimerPostUpdate();

Remarks

This method is called if you enable timer event handlers using EnableAnimationTimerEventHandler. It can be overridden in a derived class to take application-specific actions.

CAnimationController::OnAnimationTimerPreUpdate

Called by the framework before an animation update begins.

virtual void OnAnimationTimerPreUpdate();

Remarks

This method is called if you enable timer event handlers using EnableAnimationTimerEventHandler. It can be overridden in a derived class to take application-specific actions.

CAnimationController::OnAnimationTimerRenderingTooSlow

Called by the framework when the rendering frame rate for an animation falls below a minimum desirable frame rate.

virtual void OnAnimationTimerRenderingTooSlow(UINT32 fps);

Parameters

fps
The current frame rate in frames per second.

Remarks

This method is called if you enable timer event handlers using EnableAnimationTimerEventHandler. It can be overridden in a derived class to take application-specific actions. The minimum desirable frame rate is specified by calling IUIAnimationTimer::SetFrameRateThreshold.

CAnimationController::OnAnimationValueChanged

Called by the framework when value of animation variable has changed.

virtual void OnAnimationValueChanged(
    CAnimationGroup* pGroup,
    CAnimationBaseObject* pObject,
    IUIAnimationVariable* variable,
    DOUBLE newValue,
    DOUBLE prevValue);

Parameters

pGroup
A pointer to an animation group that holds an animation object whose value has changed.

pObject
A pointer to an animation object that contains an animation variable whose value has changed.

variable
A pointer to an animation variable.

newValue
Specifies new value.

prevValue
Specifies previous value.

Remarks

This method is called if you enable animation variable events with EnableValueChangedEvent called for a specific animation variable or animation object. It can be overridden in a derived class to take application-specific actions.

CAnimationController::OnBeforeAnimationStart

Called by the framework right before the animation is scheduled.

virtual void OnBeforeAnimationStart(CAnimationGroup* pGroup);

Parameters

pGroup
A pointer to an animation group whose animation is about to start.

Remarks

This call is routed to related CWnd and can be overridden in a derived class to perform any additional actions before the animation starts for the specified group.

CAnimationController::OnHasPriorityCancel

Called by the framework to resolve scheduling conflicts.

virtual BOOL OnHasPriorityCancel(
    CAnimationGroup* pGroupScheduled,
    CAnimationGroup* pGroupNew,
    UI_ANIMATION_PRIORITY_EFFECT priorityEffect);

Parameters

pGroupScheduled
The group that owns the currently scheduled storyboard.

pGroupNew
The group that owns the new storyboard that is in scheduling conflict with the scheduled storyboard owned by pGroupScheduled.

priorityEffect
The potential effect on pGroupNew if pGroupScheduled has a higher priority.

Return Value

Should return TRUE if storyboard owned by pGroupNew has priority. Should return FALSE if storyboard owned by pGroupScheduled has priority.

Remarks

This method is called if you enable priority comparison events using CAnimationController::EnablePriorityComparisonHandler and specify UI_ANIMATION_PHT_CANCEL. It can be overridden in a derived class to take application-specific actions. Read Windows Animation API documentation for more information about Conflict Management.

CAnimationController::OnHasPriorityCompress

Called by the framework to resolve scheduling conflicts.

virtual BOOL OnHasPriorityCompress(
    CAnimationGroup* pGroupScheduled,
    CAnimationGroup* pGroupNew,
    UI_ANIMATION_PRIORITY_EFFECT priorityEffect);

Parameters

pGroupScheduled
The group that owns the currently scheduled storyboard.

pGroupNew
The group that owns the new storyboard that is in scheduling conflict with the scheduled storyboard owned by pGroupScheduled.

priorityEffect
The potential effect on pGroupNew if pGroupScheduled has a higher priority.

Return Value

Should return TRUE if storyboard owned by pGroupNew has priority. Should return FALSE if storyboard owned by pGroupScheduled has priority.

Remarks

This method is called if you enable priority comparison events using CAnimationController::EnablePriorityComparisonHandler and specify UI_ANIMATION_PHT_COMPRESS. It can be overridden in a derived class to take application-specific actions. Read Windows Animation API documentation for more information about Conflict Management.

CAnimationController::OnHasPriorityConclude

Called by the framework to resolve scheduling conflicts.

virtual BOOL OnHasPriorityConclude(
    CAnimationGroup* pGroupScheduled,
    CAnimationGroup* pGroupNew,
    UI_ANIMATION_PRIORITY_EFFECT priorityEffect);

Parameters

pGroupScheduled
The group that owns the currently scheduled storyboard.

pGroupNew
The group that owns the new storyboard that is in scheduling conflict with the scheduled storyboard owned by pGroupScheduled.

priorityEffect
The potential effect on pGroupNew if pGroupScheduled has a higher priority.

Return Value

Should return TRUE if storyboard owned by pGroupNew has priority. Should return FALSE if storyboard owned by pGroupScheduled has priority.

Remarks

This method is called if you enable priority comparison events using CAnimationController::EnablePriorityComparisonHandler and specify UI_ANIMATION_PHT_CONCLUDE. It can be overridden in a derived class to take application-specific actions. Read Windows Animation API documentation for more information about Conflict Management.

CAnimationController::OnHasPriorityTrim

Called by the framework to resolve scheduling conflicts.

virtual BOOL OnHasPriorityTrim(
    CAnimationGroup* pGroupScheduled,
    CAnimationGroup* pGroupNew,
    UI_ANIMATION_PRIORITY_EFFECT priorityEffect);

Parameters

pGroupScheduled
The group that owns the currently scheduled storyboard.

pGroupNew
The group that owns the new storyboard that is in scheduling conflict with the scheduled storyboard owned by pGroupScheduled.

priorityEffect
The potential effect on pGroupNew if pGroupScheduled has a higher priority.

Return Value

Should return TRUE if storyboard owned by pGroupNew has priority. Should return FALSE if storyboard owned by pGroupScheduled has priority.

Remarks

This method is called if you enable priority comparison events using CAnimationController::EnablePriorityComparisonHandler and specify UI_ANIMATION_PHT_TRIM. It can be overridden in a derived class to take application-specific actions. Read Windows Animation API documentation for more information about Conflict Management.

CAnimationController::OnStoryboardStatusChanged

Called by the framework when storyboard status has changed.

virtual void OnStoryboardStatusChanged(
    CAnimationGroup* pGroup,
    UI_ANIMATION_STORYBOARD_STATUS newStatus,
    UI_ANIMATION_STORYBOARD_STATUS previousStatus);

Parameters

pGroup
A pointer to an animation group that owns the storyboard whose status has changed.

newStatus
Specifies the new status.

previousStatus
Specifies the previous status.

Remarks

This method is called if you enable storyboard events using CAnimationController::EnableStoryboardEventHandler. It can be overridden in a derived class to take application-specific actions.

CAnimationController::OnStoryboardUpdated

Called by the framework when storyboard has been updated.

virtual void OnStoryboardUpdated(CAnimationGroup* pGroup);

Parameters

pGroup
A pointer to a group that owns the storyboard.

Remarks

This method is called if you enable storyboard events using CAnimationController::EnableStoryboardEventHandler. It can be overridden in a derived class to take application-specific actions.

CAnimationController::RemoveAllAnimationGroups

Removes all animation groups from animation controller.

void RemoveAllAnimationGroups();

Remarks

All groups will be deleted, their pointer, if stored at the application level, must be invalidated. If CAnimationGroup::m_bAutodestroyAnimationObjects for a group being deleted is TRUE, all animation objects that belong to that group will be deleted; otherwise their references to parent animation controller will be set to NULL and they can be added to another controller.

CAnimationController::RemoveAnimationGroup

Removes an animation group with specified ID from animation controller.

void RemoveAnimationGroup(UINT32 nGroupID);

Parameters

nGroupID
Specifies animation group ID.

Remarks

This method removes an animation group from the internal list of groups and deletes it, therefore if you stored a pointer to that animation group, it must be invalidated. If CAnimationGroup::m_bAutodestroyAnimationObjects is TRUE, all animation objects that belong to that group will be deleted; otherwise their references to parent animation controller will be set to NULL and they can be added to another controller.

CAnimationController::RemoveAnimationObject

Remove an animation object from animation controller.

void RemoveAnimationObject(
    CAnimationBaseObject* pObject,
    BOOL bNoDelete = FALSE);

Parameters

pObject
A pointer to an animation object.

bNoDelete
If this parameter is TRUE the object will not be deleted upon remove.

Remarks

Removes an animation object from animation controller and animation group. Call this function if a particular object should not be animated anymore, or if you need to move the object to another animation controller. In the last case bNoDelete must be TRUE.

CAnimationController::RemoveTransitions

Removes transitions from animation objects that belong to the specified group.

void RemoveTransitions(UINT32 nGroupID);

Parameters

nGroupID
Specifies Group ID.

Remarks

The group loops over its animation objects and calls ClearTransitions(FALSE) for each animation object. This method is called by the framework after animation has been scheduled.

CAnimationController::ScheduleGroup

Schedules an animation.

BOOL ScheduleGroup(
    UINT32 nGroupID,
    UI_ANIMATION_SECONDS time = 0.0);

Parameters

nGroupID
Specifies animation Group ID to schedule.

time
Specifies time to schedule.

Return Value

TRUE if animation was scheduled successfully. FALSE if storyboard has not been created, or other error occurs.

Remarks

You must call AnimateGroup with parameter bScheduleNow set to FALSE prior ScheduleGroup. You can specify the desired animation time obtained from IUIAnimationTimer::GetTime. If the time parameter is 0.0, the animation is scheduled for the current time.

CAnimationController::SetRelatedWnd

Establishes a relationship between animation controller and a window.

void SetRelatedWnd(CWnd* pWnd);

Parameters

pWnd
A pointer to window object to set.

Remarks

If a related CWnd object is set, the animation controller can automatically update it (send WM_PAINT message) when the status of animation manager has changed or timer post update event has occurred.

CAnimationController::UpdateAnimationManager

Directs the animation manager to update the values of all animation variables.

virtual void UpdateAnimationManager();

Remarks

Calling this method advances the animation manager to current time, changing statuses of storyboards as necessary and updating any animation variables to appropriate interpolated values. Internally this method calls IUIAnimationTimer::GetTime(timeNow) and IUIAnimationManager::Update(timeNow). Override this method in a derived class to customize this behavior.

Share via

CAnimationController Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Protected Data Members

Remarks

Inheritance Hierarchy

Requirements

CAnimationController::~CAnimationController

CAnimationController::AddAnimationObject

Parameters

Return Value

Remarks

CAnimationController::AddKeyframeToGroup

Parameters

Return Value

Remarks

CAnimationController::AnimateGroup

Parameters

Return Value

Remarks

CAnimationController::CAnimationController

CAnimationController::CleanUpGroup

Parameters

Remarks

CAnimationController::CreateKeyframe

Parameters

Return Value

Remarks

CAnimationController::EnableAnimationManagerEvent

Parameters

Return Value

Remarks

CAnimationController::EnableAnimationTimerEventHandler

Parameters

Return Value

Remarks

CAnimationController::EnablePriorityComparisonHandler

Parameters

Return Value

Remarks

CAnimationController::EnableStoryboardEventHandler

Parameters

Return Value

Remarks

CAnimationController::FindAnimationGroup

Parameters

Return Value

Remarks

CAnimationController::FindAnimationObject

Parameters

Return Value

Remarks

CAnimationController::gkeyframeStoryboardStart

CAnimationController::GetKeyframeStoryboardStart

Return Value

Remarks

CAnimationController::GetUIAnimationManager

Return Value

Remarks

CAnimationController::GetUIAnimationTimer

Return Value

Remarks

CAnimationController::GetUITransitionFactory

Return Value

Remarks

CAnimationController::GetUITransitionLibrary

Return Value

Remarks

CAnimationController::IsAnimationInProgress

Return Value

Remarks

CAnimationController::IsValid

Return Value

Remarks

CAnimationController::m_bIsValid

CAnimationController::m_lstAnimationGroups