A simple timing engine for running animations which calculate animated values and set them on target objects. More...

#include <SValueAnimator.h>

Inheritance diagram for SValueAnimator:

Public Member Functions
	SValueAnimator ()
	Creates a new SValueAnimator object.

	~SValueAnimator ()
	Destructor.

void	setDuration (long duration) OVERRIDE
	Sets the length of the animation.

long	getDuration () SCONST OVERRIDE
	Gets the length of the animation.

long	getTotalDuration () SCONST OVERRIDE
	Gets the total duration of the animation, including any repetitions.

void	setCurrentPlayTime (long playTime) OVERRIDE
	Sets the position of the animation to the specified point in time.

void	setCurrentFraction (float fraction) OVERRIDE
	Sets the position of the animation to the specified fraction.

long	getCurrentPlayTime () OVERRIDE
	Gets the current position of the animation in time.

long	getStartDelay () SCONST OVERRIDE
	Gets the amount of time, in milliseconds, to delay starting the animation after start() is called.

void	setStartDelay (long startDelay) OVERRIDE
	Sets the amount of time, in milliseconds, to delay starting the animation after start() is called.

void	setRepeatCount (int value) OVERRIDE
	Sets how many times the animation should be repeated.

int	getRepeatCount () SCONST OVERRIDE
	Defines how many times the animation should repeat.

void	setRepeatMode (RepeatMode value) OVERRIDE
	Defines what this animation should do when it reaches the end.

RepeatMode	getRepeatMode () SCONST OVERRIDE
	Defines what this animation should do when it reaches the end.

void	addUpdateListener (IAnimatorUpdateListener *listener) OVERRIDE
	Adds a listener to the set of listeners that are sent update events through the life of an animation.

void	removeAllUpdateListeners () OVERRIDE
	Removes all listeners from the set listening to frame updates for this animation.

void	removeUpdateListener (IAnimatorUpdateListener *listener) OVERRIDE
	Removes a listener from the set listening to frame updates for this animation.

void	setInterpolator (IInterpolator *value) OVERRIDE
	Sets the time interpolator used in calculating the elapsed fraction of this animation.

IInterpolator *	getInterpolator () SCONST OVERRIDE
	Returns the timing interpolator that this SValueAnimator uses.

void	addListener (IAnimatorListener *p) OVERRIDE
	Adds an animator listener.

void	removeListener (IAnimatorListener *p) OVERRIDE
	Removes an animator listener.

void	start (ITimelineHandlersMgr *pContainer) OVERRIDE
	Starts the animation playing.

void	end () OVERRIDE
	Ends the animation.

BOOL	isRunning () SCONST OVERRIDE
	Checks if the animation is running.

BOOL	isStarted () SCONST OVERRIDE
	Checks if the animation has been started.

void	reverse () OVERRIDE
	Plays the SValueAnimator in reverse.

IValueAnimator *	clone () SCONST OVERRIDE
	Creates a clone of the current animation.

void	copy (const IValueAnimator *pSrc) OVERRIDE
	Copies the properties of another animation to this animation.

void	commitAnimationFrame (long frameTime) OVERRIDE
	Applies an adjustment to the animation to compensate for jank between when the animation first ran and when the frame was drawn.

float	getAnimatedFraction () SCONST OVERRIDE
	Returns the current animation fraction.

void	OnNextFrame () OVERRIDE
	Handles the next frame of the animation.

Public Member Functions inherited from TObjRefImpl< SObjectImpl< IValueAnimator > >
	TObjRefImpl ()
	Constructor that initializes the reference count to 1.

virtual	~TObjRefImpl ()
	Virtual destructor.

long	AddRef () override
	Increments the reference count.

long	Release () override
	Decrements the reference count and deletes the object if the count reaches zero.

void	OnFinalRelease () override
	Deletes the object.

Public Member Functions inherited from SObjectImpl< IValueAnimator >
	SObjectImpl ()
	Constructor.

BOOL	InitFromXml (IXmlNode *pXmlNode) OVERRIDE
	Initializes the object from an XML node.

LPCWSTR	GetName () SCONST OVERRIDE
	Retrieves the object's name.

LPCSTR	GetNameA () SCONST OVERRIDE
	Retrieves the object's name in ANSI format.

void	SetName (LPCWSTR pszName) OVERRIDE
	Sets the object's name.

int	GetID () SCONST OVERRIDE
	Retrieves the object's ID.

void	SetID (int nID) OVERRIDE
	Sets the object's ID.

HRESULT	AfterAttribute (LPCWSTR strAttribName, LPCWSTR strValue, BOOL bLoading, HRESULT hr) OVERRIDE
	Handles attribute processing after setting an attribute.

HRESULT	SetAttributeA (LPCSTR pszAttr, LPCSTR pszValue, BOOL bLoading) OVERRIDE
	Sets an attribute using ANSI strings.

HRESULT	SetAttribute (LPCWSTR pszAttr, LPCWSTR pszValue, BOOL bLoading) OVERRIDE
	Sets an attribute using wide strings.

virtual HRESULT	SetAttribute (const SStringW &strAttr, const SStringW &strValue, BOOL bLoading)
	Sets an attribute using wide strings.

HRESULT	ISetAttribute (const IStringW strAttr, const IStringW strValue, BOOL bLoading) OVERRIDE
	Sets an attribute using IStringW objects.

LPCWSTR	GetObjectClass () SCONST OVERRIDE
	Retrieves the object's class name.

int	GetObjectType () SCONST OVERRIDE
	Retrieves the object's type.

BOOL	IsClass (LPCWSTR lpszName) SCONST OVERRIDE
	Checks if the object is of a specific class.

BOOL	GetAttribute (LPCWSTR strAttr, IStringW *pValue) SCONST OVERRIDE
	Retrieves an attribute value.

void	OnInitFinished (IXmlNode *xmlNode) OVERRIDE
	Handles initialization completion.

void	SetAttrHandler (FunAttrHandler attrHandler) OVERRIDE
	Sets the attribute handler.

virtual HRESULT	DefAttributeProc (const SStringW &strAttr, const SStringW &strValue, BOOL bLoading)
	Default attribute processing.

Protected Attributes
uint64_t	mStartTime
	The first time that the animation's animateFrame() method is called.

bool	mStartTimeCommitted
	Flag indicating whether the start time has been firmly committed.

float	mSeekFraction
	Set when setCurrentPlayTime() is called.

bool	mReversing
	Flag to indicate whether this animator is playing in reverse mode.

float	mOverallFraction
	Tracks the overall fraction of the animation, ranging from 0 to mRepeatCount + 1.

float	mCurrentFraction
	Tracks current elapsed/eased fraction, for querying in getAnimatedFraction().

uint64_t	mLastFrameTime
	Tracks the time (in milliseconds) when the last frame arrived.

uint64_t	mFirstFrameTime
	Tracks the time (in milliseconds) when the first frame arrived.

bool	mRunning
	Additional playing state to indicate whether an animator has been start()'d.

bool	mStarted
	Additional playing state to indicate whether an animator has been start()'d, whether or not there is a nonzero startDelay.

bool	mStartListenersCalled
	Tracks whether we've notified listeners of the onAnimationStart() event.

bool	mInitialized
	Flag that denotes whether the animation is set up and ready to go.

bool	mAnimationEndRequested
	Flag that tracks whether animation has been requested to end.

long	mDuration
	How long the animation should last in milliseconds.

long	mStartDelay
	The amount of time in milliseconds to delay starting the animation after start() is called.

int	mRepeatCount
	The number of times the animation will repeat.

float	sDurationScale
	Scaling factor for the duration.

RepeatMode	mRepeatMode
	The type of repetition that will occur when repeatMode is nonzero.

SAutoRefPtr< IInterpolator >	mInterpolator
	The time interpolator to be used.

SArray< IAnimatorUpdateListener * >	mUpdateListeners
	The set of listeners to be sent update events through the life of an animation.

SArray< IAnimatorListener * >	mListeners

ITimelineHandlersMgr *	mContainer
	The container managing the timeline handlers.

Protected Attributes inherited from TObjRefImpl< SObjectImpl< IValueAnimator > >
LONG	m_cRef
	Reference count.

Protected Attributes inherited from SObjectImpl< IValueAnimator >
SStringW	m_strName

int	m_nID

FunAttrHandler	m_attrHandler

Additional Inherited Members
Static Public Member Functions inherited from SObjectImpl< IValueAnimator >
static int	GetClassType ()
	Retrieves the class type.

static LPCWSTR	GetClassName ()
	Retrieves the class name.

static LPCWSTR	GetClassAlias ()
	Retrieves the class alias.

static void	MarkAttributeHandled (SXmlAttr xmlAttr, bool bHandled)
	Marks an attribute as handled.

static bool	IsAttributeHandled (SXmlAttr xmlAttr)
	Checks if an attribute is handled.

Detailed Description

A simple timing engine for running animations which calculate animated values and set them on target objects.

This class provides a simple timing engine for running animations which calculate animated values and set them on target objects. There is a single timing pulse that all animations use. It runs in a custom handler to ensure that property changes happen on the UI thread. By default, SValueAnimator uses non-linear time interpolation, via the AccelerateDecelerateInterpolator class, which accelerates into and decelerates out of an animation. This behavior can be changed by calling setInterpolator(TimeInterpolator).

Definition at line 45 of file SValueAnimator.h.

Constructor & Destructor Documentation

◆ SValueAnimator()

SNSBEGIN SValueAnimator::SValueAnimator ( )

Creates a new SValueAnimator object.

This default constructor is primarily for use internally; the factory methods which take parameters are more generally useful.

Definition at line 8 of file SValueAnimator.cpp.

◆ ~SValueAnimator()

SValueAnimator::~SValueAnimator ( )

Destructor.

Definition at line 47 of file SValueAnimator.cpp.

Member Function Documentation

◆ addListener()

void SValueAnimator::addListener ( IAnimatorListener * p )

Adds an animator listener.

Parameters

p	The listener to be added.

Definition at line 440 of file SValueAnimator.cpp.

◆ addUpdateListener()

void SValueAnimator::addUpdateListener ( IAnimatorUpdateListener * listener )

Adds a listener to the set of listeners that are sent update events through the life of an animation.

Parameters

listener The listener to be added to the current set of listeners for this animation.

Definition at line 467 of file SValueAnimator.cpp.

◆ clone()

IValueAnimator * SValueAnimator::clone ( )

Creates a clone of the current animation.

Returns: A clone of the current animation.

Definition at line 635 of file SValueAnimator.cpp.

◆ commitAnimationFrame()

void SValueAnimator::commitAnimationFrame ( long frameTime )

Applies an adjustment to the animation to compensate for jank between when the animation first ran and when the frame was drawn.

Parameters

frameTime The current frame time.

Definition at line 245 of file SValueAnimator.cpp.

◆ copy()

void SValueAnimator::copy ( const IValueAnimator * pSrc )

Copies the properties of another animation to this animation.

Parameters

pSrc	The source animation to copy properties from.

Definition at line 58 of file SValueAnimator.cpp.

◆ end()

void SValueAnimator::end ( )

Ends the animation.

Definition at line 350 of file SValueAnimator.cpp.

◆ getAnimatedFraction()

float SValueAnimator::getAnimatedFraction ( )

Returns the current animation fraction.

This is the elapsed/interpolated fraction used in the most recent frame update on the animation.

Returns: The elapsed/interpolated fraction of the animation.

Definition at line 96 of file SValueAnimator.cpp.

◆ getCurrentPlayTime()

long SValueAnimator::getCurrentPlayTime ( )

Gets the current position of the animation in time.

Returns: The current position in time of the animation.

Definition at line 507 of file SValueAnimator.cpp.

◆ getDuration()

long SValueAnimator::getDuration ( )

Gets the length of the animation.

Returns: The length of the animation, in milliseconds.

Definition at line 617 of file SValueAnimator.cpp.

◆ getInterpolator()

IInterpolator * SValueAnimator::getInterpolator ( )

Returns the timing interpolator that this SValueAnimator uses.

Returns: The timing interpolator for this SValueAnimator.

Definition at line 445 of file SValueAnimator.cpp.

◆ getRepeatCount()

int SValueAnimator::getRepeatCount ( )

Defines how many times the animation should repeat.

Returns: The number of times the animation should repeat, or INFINITE.

Definition at line 482 of file SValueAnimator.cpp.

◆ getRepeatMode()

RepeatMode SValueAnimator::getRepeatMode ( )

Defines what this animation should do when it reaches the end.

Returns: Either REVERSE or RESTART.

Definition at line 472 of file SValueAnimator.cpp.

◆ getStartDelay()

long SValueAnimator::getStartDelay ( )

Gets the amount of time, in milliseconds, to delay starting the animation after start() is called.

Returns: The number of milliseconds to delay running the animation.

Definition at line 502 of file SValueAnimator.cpp.

◆ getTotalDuration()

long SValueAnimator::getTotalDuration ( )

Gets the total duration of the animation, including any repetitions.

Returns: The total duration of the animation, in milliseconds.

Definition at line 605 of file SValueAnimator.cpp.

◆ isRunning()

BOOL SValueAnimator::isRunning ( )

Checks if the animation is running.

Returns: TRUE if the animation is running, FALSE otherwise.

Definition at line 345 of file SValueAnimator.cpp.

◆ isStarted()

BOOL SValueAnimator::isStarted ( )

Checks if the animation has been started.

Returns: TRUE if the animation has been started, FALSE otherwise.

Definition at line 340 of file SValueAnimator.cpp.

◆ OnNextFrame()

void SValueAnimator::OnNextFrame ( )

Handles the next frame of the animation.

Definition at line 79 of file SValueAnimator.cpp.

◆ removeAllUpdateListeners()

void SValueAnimator::removeAllUpdateListeners ( )

Removes all listeners from the set listening to frame updates for this animation.

Definition at line 462 of file SValueAnimator.cpp.

◆ removeListener()

void SValueAnimator::removeListener ( IAnimatorListener * p )

Removes an animator listener.

Parameters

p	The listener to be removed.

Definition at line 431 of file SValueAnimator.cpp.

◆ removeUpdateListener()

void SValueAnimator::removeUpdateListener ( IAnimatorUpdateListener * listener )

Removes a listener from the set listening to frame updates for this animation.

Parameters

listener The listener to be removed from the current set of update listeners for this animation.

Definition at line 455 of file SValueAnimator.cpp.

◆ reverse()

void SValueAnimator::reverse ( )

Plays the SValueAnimator in reverse.

If the animation is already running, it will stop itself and play backwards from the point reached when reverse was called. If the animation is not currently running, then it will start from the end and play backwards. This behavior is only set for the current animation; future playing of the animation will use the default behavior of playing forward.

Definition at line 318 of file SValueAnimator.cpp.

◆ setCurrentFraction()

void SValueAnimator::setCurrentFraction ( float fraction )

Sets the position of the animation to the specified fraction.

Parameters

fraction The fraction to which the animation is advanced or rewound. Values outside the range of 0 to the maximum fraction for the animator will be clamped to the correct range.

Definition at line 576 of file SValueAnimator.cpp.

◆ setCurrentPlayTime()

void SValueAnimator::setCurrentPlayTime ( long playTime )

Sets the position of the animation to the specified point in time.

Parameters

playTime The time, in milliseconds, to which the animation is advanced or rewound.

Definition at line 599 of file SValueAnimator.cpp.

◆ setDuration()

void SValueAnimator::setDuration ( long duration )

Sets the length of the animation.

Parameters

duration The length of the animation, in milliseconds. This value cannot be negative.

Returns: SValueAnimator The object called with setDuration(). This return value makes it easier to compose statements together that construct and then set the duration, as in SValueAnimator.ofInt(0, 10).setDuration(500).start().

Definition at line 627 of file SValueAnimator.cpp.

◆ setInterpolator()

void SValueAnimator::setInterpolator ( IInterpolator * value )

Sets the time interpolator used in calculating the elapsed fraction of this animation.

Parameters

value The interpolator to be used by this animation. A value of nullptr will result in linear interpolation.

Definition at line 450 of file SValueAnimator.cpp.

◆ setRepeatCount()

void SValueAnimator::setRepeatCount ( int value )

Sets how many times the animation should be repeated.

Parameters

value The number of times the animation should be repeated. If the repeat count is 0, the animation is never repeated. If the repeat count is greater than 0 or INFINITE, the repeat mode will be taken into account. The repeat count is 0 by default.

Definition at line 487 of file SValueAnimator.cpp.

◆ setRepeatMode()

void SValueAnimator::setRepeatMode ( RepeatMode value )

Defines what this animation should do when it reaches the end.

Parameters

value Either RESTART or REVERSE. Defaults to RESTART.

Definition at line 477 of file SValueAnimator.cpp.

◆ setStartDelay()

void SValueAnimator::setStartDelay ( long startDelay )

Sets the amount of time, in milliseconds, to delay starting the animation after start() is called.

Parameters

startDelay The amount of the delay, in milliseconds.

Definition at line 492 of file SValueAnimator.cpp.

◆ start()

void SValueAnimator::start ( ITimelineHandlersMgr * pContainer )

Starts the animation playing.

Parameters

pContainer The container managing the timeline handlers.

Definition at line 363 of file SValueAnimator.cpp.

Member Data Documentation

◆ mAnimationEndRequested

bool SValueAnimator::mAnimationEndRequested

protected

Flag that tracks whether animation has been requested to end.

Definition at line 130 of file SValueAnimator.h.

◆ mContainer

ITimelineHandlersMgr* SValueAnimator::mContainer

protected

The container managing the timeline handlers.

Definition at line 175 of file SValueAnimator.h.

◆ mCurrentFraction

float SValueAnimator::mCurrentFraction

protected

Tracks current elapsed/eased fraction, for querying in getAnimatedFraction().

This is calculated by interpolating the fraction (range: [0, 1]) in the current iteration.

Definition at line 88 of file SValueAnimator.h.

◆ mDuration

long SValueAnimator::mDuration

protected

How long the animation should last in milliseconds.

Definition at line 135 of file SValueAnimator.h.

◆ mFirstFrameTime

uint64_t SValueAnimator::mFirstFrameTime

protected

Tracks the time (in milliseconds) when the first frame arrived.

Note the frame may arrive during the start delay.

Definition at line 99 of file SValueAnimator.h.

◆ mInitialized

bool SValueAnimator::mInitialized

protected

Flag that denotes whether the animation is set up and ready to go.

Used to set up animation that has not yet been started.

Definition at line 125 of file SValueAnimator.h.

◆ mInterpolator

SAutoRefPtr<IInterpolator> SValueAnimator::mInterpolator

protected

The time interpolator to be used.

The elapsed fraction of the animation will be passed through this interpolator to calculate the interpolated fraction, which is then used to calculate the animated values.

Definition at line 164 of file SValueAnimator.h.

◆ mLastFrameTime

uint64_t SValueAnimator::mLastFrameTime

protected

Tracks the time (in milliseconds) when the last frame arrived.

Definition at line 93 of file SValueAnimator.h.

◆ mListeners

SArray<IAnimatorListener *> SValueAnimator::mListeners

protected

Definition at line 170 of file SValueAnimator.h.

◆ mOverallFraction

float SValueAnimator::mOverallFraction

protected

Tracks the overall fraction of the animation, ranging from 0 to mRepeatCount + 1.

Definition at line 82 of file SValueAnimator.h.

◆ mRepeatCount

int SValueAnimator::mRepeatCount

protected

The number of times the animation will repeat.

The default is 0, which means the animation will play only once.

Definition at line 147 of file SValueAnimator.h.

◆ mRepeatMode

RepeatMode SValueAnimator::mRepeatMode

protected

The type of repetition that will occur when repeatMode is nonzero.

RESTART means the animation will start from the beginning on every new cycle. REVERSE means the animation will reverse directions on each iteration.

Definition at line 158 of file SValueAnimator.h.

◆ mReversing

bool SValueAnimator::mReversing

protected

Flag to indicate whether this animator is playing in reverse mode.

This flag is different than mPlayingBackwards, which indicates merely whether the current iteration of the animator is playing in reverse. It is used in corner cases to determine proper end behavior.

Definition at line 77 of file SValueAnimator.h.

◆ mRunning

bool SValueAnimator::mRunning

protected

Additional playing state to indicate whether an animator has been start()'d.

There is some lag between a call to start() and the first animation frame. We should still note that the animation has been started, even if its first animation frame has not yet happened, and reflect that state in isRunning(). Note that delayed animations are different: they are not started until their first animation frame, which occurs after their delay elapses.

Definition at line 107 of file SValueAnimator.h.

◆ mSeekFraction

float SValueAnimator::mSeekFraction

protected

Set when setCurrentPlayTime() is called.

If negative, animation is not currently seeked to a value.

Definition at line 70 of file SValueAnimator.h.

◆ mStartDelay

long SValueAnimator::mStartDelay

protected

The amount of time in milliseconds to delay starting the animation after start() is called.

Note that this start delay is unscaled. When there is a duration scale set on the animator, the scaling factor will be applied to this delay.

Definition at line 141 of file SValueAnimator.h.

◆ mStarted

bool SValueAnimator::mStarted

protected

Additional playing state to indicate whether an animator has been start()'d, whether or not there is a nonzero startDelay.

Definition at line 112 of file SValueAnimator.h.

◆ mStartListenersCalled

bool SValueAnimator::mStartListenersCalled

protected

Tracks whether we've notified listeners of the onAnimationStart() event.

This can be complex to keep track of since we notify listeners at different times depending on startDelay and whether start() was called before end().

Definition at line 119 of file SValueAnimator.h.

◆ mStartTime

uint64_t SValueAnimator::mStartTime

protected

The first time that the animation's animateFrame() method is called.

This time is used to determine elapsed time (and therefore the elapsed fraction) in subsequent calls to animateFrame(). Whenever mStartTime is set, you must also update mStartTimeCommitted.

Definition at line 56 of file SValueAnimator.h.

◆ mStartTimeCommitted

bool SValueAnimator::mStartTimeCommitted

protected

Flag indicating whether the start time has been firmly committed.

When true, the start time has been firmly committed as a chosen reference point in time by which the progress of the animation will be evaluated. When false, the start time may be updated when the first animation frame is committed so as to compensate for jank that may have occurred between when the start time was initialized and when the frame was actually drawn.

Definition at line 64 of file SValueAnimator.h.

◆ mUpdateListeners

SArray<IAnimatorUpdateListener *> SValueAnimator::mUpdateListeners

protected

The set of listeners to be sent update events through the life of an animation.

Definition at line 169 of file SValueAnimator.h.

◆ sDurationScale

float SValueAnimator::sDurationScale

protected

Scaling factor for the duration.

Definition at line 152 of file SValueAnimator.h.

The documentation for this class was generated from the following files:

SOUI/include/valueAnimator/SValueAnimator.h
SOUI/src/valueAnimator/SValueAnimator.cpp

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SValueAnimator()

◆ ~SValueAnimator()

Member Function Documentation

◆ addListener()

◆ addUpdateListener()

◆ clone()

◆ commitAnimationFrame()

◆ copy()

◆ end()

◆ getAnimatedFraction()

◆ getCurrentPlayTime()

◆ getDuration()

◆ getInterpolator()

◆ getRepeatCount()

◆ getRepeatMode()

◆ getStartDelay()

◆ getTotalDuration()

◆ isRunning()

◆ isStarted()

◆ OnNextFrame()

◆ removeAllUpdateListeners()

◆ removeListener()

◆ removeUpdateListener()

◆ reverse()

◆ setCurrentFraction()

◆ setCurrentPlayTime()

◆ setDuration()

◆ setInterpolator()

◆ setRepeatCount()

◆ setRepeatMode()

◆ setStartDelay()

◆ start()

Member Data Documentation

◆ mAnimationEndRequested

◆ mContainer

◆ mCurrentFraction

◆ mDuration

◆ mFirstFrameTime

◆ mInitialized

◆ mInterpolator

◆ mLastFrameTime

◆ mListeners

◆ mOverallFraction

◆ mRepeatCount

◆ mRepeatMode

◆ mReversing

◆ mRunning

◆ mSeekFraction

◆ mStartDelay

◆ mStarted

◆ mStartListenersCalled

◆ mStartTime

◆ mStartTimeCommitted

◆ mUpdateListeners

◆ sDurationScale