Tizen Native API  3.0

Dali::Animation can be used to animate the properties of any number of objects, typically Actors. More...

Inheritance diagram for Dali::Animation:
Dali::BaseHandle

Public Types

enum  EndAction
 Enumeration for what to do when the animation ends, is stopped, or is destroyed. More...
enum  Interpolation
 Enumeration for what interpolation method to use on key-frame animations. More...
enum  State
 Enumeration for what state the animation is in. More...
typedef Signal< void(Animation &) > AnimationSignalType
 Animation finished signal type.
typedef Any AnyFunction
 Interpolation function.

Public Member Functions

 Animation ()
 Creates an uninitialized Animation; this can be initialized with Animation::New().
 ~Animation ()
 Destructor.
 Animation (const Animation &handle)
 This copy constructor is required for (smart) pointer semantics.
Animationoperator= (const Animation &rhs)
 This assignment operator is required for (smart) pointer semantics.
void SetDuration (float seconds)
 Sets the duration of an animation.
float GetDuration () const
 Retrieves the duration of an animation.
void SetLooping (bool looping)
 Sets whether the animation will loop.
void SetLoopCount (int count)
 Enables looping for 'count' repeats.
int GetLoopCount ()
 Gets the loop count.
int GetCurrentLoop ()
 Gets the current loop count.
bool IsLooping () const
 Queries whether the animation will loop.
void SetEndAction (EndAction action)
 Sets the end action of the animation.
EndAction GetEndAction () const
 Returns the end action of the animation.
void SetDisconnectAction (EndAction disconnectAction)
 Sets the disconnect action.
EndAction GetDisconnectAction () const
 Returns the disconnect action.
void SetDefaultAlphaFunction (AlphaFunction alpha)
 Sets the default alpha function for an animation.
AlphaFunction GetDefaultAlphaFunction () const
 Retrieves the default alpha function for an animation.
float GetCurrentProgress ()
 Retrieves the current progress of the animation.
void SetSpeedFactor (float factor)
 Specifies a speed factor for the animation.
float GetSpeedFactor () const
 Retrieves the speed factor of the animation.
void SetPlayRange (const Vector2 &range)
 Sets the playing range.
Vector2 GetPlayRange () const
 Gets the playing range.
void Play ()
 Play the animation.
void PlayFrom (float progress)
 Plays the animation from a given point.
void Pause ()
 Pauses the animation.
State GetState () const
 Queries the state of the animation.
void Stop ()
 Stops the animation.
void Clear ()
 Clears the animation.
AnimationSignalTypeFinishedSignal ()
 Connects to this signal to be notified when an Animation's animations have finished.
void AnimateBy (Property target, Property::Value relativeValue)
 Animates a property value by a relative amount.
void AnimateBy (Property target, Property::Value relativeValue, AlphaFunction alpha)
 Animates a property value by a relative amount.
void AnimateBy (Property target, Property::Value relativeValue, TimePeriod period)
 Animates a property value by a relative amount.
void AnimateBy (Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period)
 Animates a property value by a relative amount.
void AnimateTo (Property target, Property::Value destinationValue)
 Animates a property to a destination value.
void AnimateTo (Property target, Property::Value destinationValue, AlphaFunction alpha)
 Animates a property to a destination value.
void AnimateTo (Property target, Property::Value destinationValue, TimePeriod period)
 Animates a property to a destination value.
void AnimateTo (Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period)
 Animates a property to a destination value.
void AnimateBetween (Property target, KeyFrames &keyFrames)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, Interpolation interpolation)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha, Interpolation interpolation)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, TimePeriod period)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, TimePeriod period, Interpolation interpolation)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha, TimePeriod period)
 Animates a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha, TimePeriod period, Interpolation interpolation)
 Animates a property between keyframes.
void Animate (Actor actor, Path path, const Vector3 &forward)
 Animates an actor's position and orientation through a predefined path.
void Animate (Actor actor, Path path, const Vector3 &forward, AlphaFunction alpha)
 Animates an actor's position and orientation through a predefined path.
void Animate (Actor actor, Path path, const Vector3 &forward, TimePeriod period)
 Animates an actor's position and orientation through a predefined path.
void Animate (Actor actor, Path path, const Vector3 &forward, AlphaFunction alpha, TimePeriod period)
 Animates an actor's position and orientation through a predefined path.
void Show (Actor actor, float delaySeconds)
 Shows an actor during the animation.
void Hide (Actor actor, float delaySeconds)
 Hides an actor during the animation.

Static Public Member Functions

static Animation New (float durationSeconds)
 Creates an initialized Animation.
static Animation DownCast (BaseHandle handle)
 Downcasts a handle to Animation handle.

Detailed Description

Dali::Animation can be used to animate the properties of any number of objects, typically Actors.

An example animation setup is shown below:

 struct MyProgram
 {
   Actor mActor; // The object we wish to animate
   Animation mAnimation; // Keep this to control the animation
 }

 // ...To play the animation

 mAnimation = Animation::New(3.0f); // duration 3 seconds
 mAnimation.AnimateTo(Property(mActor, Actor::Property::POSITION), Vector3(10.0f, 50.0f, 0.0f));
 mAnimation.Play();

Dali::Animation supports "fire and forget" behaviour i.e. an animation continues to play if the handle is discarded. Note that in the following example, the "Finish" signal will be emitted:

 void ExampleCallback( Animation& source )
 {
   std::cout << "Animation has finished" << std::endl;
 }

 void ExampleAnimation( Actor actor )
 {
   Animation animation = Animation::New(2.0f); // duration 2 seconds
   animation.AnimateTo(Property(actor, Actor::Property::POSITION), 10.0f, 50.0f, 0.0f);
   animation.FinishedSignal().Connect( ExampleCallback );
   animation.Play();
 } // At this point the animation handle has gone out of scope

 Actor actor = Actor::New();
 Stage::GetCurrent().Add( actor );

 // Fire animation and forget about it
 ExampleAnimation( actor );

 // However the animation will continue, and "Animation has finished" will be printed after 2 seconds.

If the "Finish" signal is connected to a member function of an object, it must be disconnected before the object is destroyed. This is typically done in the object destructor, and requires either the Dali::Connection object or Dali::Animation handle to be stored.

Signals | Signal Name | Method | |--------------|--------------------------| | finished | FinishedSignal() |

Actions | Action Name | Animation method called | |--------------|--------------------------| | play | Play() | | stop | Stop() | | pause | Pause() |

Since:
2.4, DALi version 1.0.0

Member Typedef Documentation

Animation finished signal type.

Since:
2.4, DALi version 1.0.0

Interpolation function.

Since:
2.4, DALi version 1.0.0

Member Enumeration Documentation

Enumeration for what to do when the animation ends, is stopped, or is destroyed.

Since:
2.4, DALi version 1.0.0
Enumerator:
Bake 

When the animation ends, the animated property values are saved.

Since:
2.4, DALi version 1.0.0
Discard 

When the animation ends, the animated property values are forgotten.

Since:
2.4, DALi version 1.0.0
BakeFinal 

If the animation is stopped, the animated property values are saved as if the animation had run to completion, otherwise behaves like Bake.

Since:
2.4, DALi version 1.0.0

Enumeration for what interpolation method to use on key-frame animations.

Since:
2.4, DALi version 1.0.0
Enumerator:
Linear 

Values in between key frames are interpolated using a linear polynomial. (Default)

Since:
2.4, DALi version 1.0.0
Cubic 

Values in between key frames are interpolated using a cubic polynomial.

Since:
2.4, DALi version 1.0.0

Enumeration for what state the animation is in.

Note: Calling Reset() on this class will NOT reset the animation. It will call BaseHandle::Reset() which drops the object handle.

Since:
3.0, DALi version 1.1.21
Enumerator:
STOPPED 

Animation has stopped.

Since:
3.0, DALi version 1.1.21
PLAYING 

The animation is playing.

Since:
3.0, DALi version 1.1.21
PAUSED 

The animation is paused.

Since:
3.0, DALi version 1.1.21

Constructor & Destructor Documentation

Creates an uninitialized Animation; this can be initialized with Animation::New().

Calling member functions with an uninitialized Animation handle is not allowed.

Since:
2.4, DALi version 1.0.0

Destructor.

This is non-virtual since derived Handle types must not contain data or virtual methods.

Since:
2.4, DALi version 1.0.0

This copy constructor is required for (smart) pointer semantics.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]handleA reference to the copied handle

Member Function Documentation

void Dali::Animation::Animate ( Actor  actor,
Path  path,
const Vector3 forward 
)

Animates an actor's position and orientation through a predefined path.

The actor will rotate to orient the supplied forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actorThe actor to animate
[in]pathThe path. It defines position and orientation
[in]forwardThe vector (in local space coordinate system) that will be oriented with the path's tangent direction
void Dali::Animation::Animate ( Actor  actor,
Path  path,
const Vector3 forward,
AlphaFunction  alpha 
)

Animates an actor's position and orientation through a predefined path.

The actor will rotate to orient the supplied forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actorThe actor to animate
[in]pathThe path. It defines position and orientation
[in]forwardThe vector (in local space coordinate system) that will be oriented with the path's tangent direction
[in]alphaThe alpha function to apply
void Dali::Animation::Animate ( Actor  actor,
Path  path,
const Vector3 forward,
TimePeriod  period 
)

Animates an actor's position and orientation through a predefined path.

The actor will rotate to orient the supplied forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actorThe actor to animate
[in]pathThe path. It defines position and orientation
[in]forwardThe vector (in local space coordinate system) that will be oriented with the path's tangent direction
[in]periodThe effect will occur during this time period
void Dali::Animation::Animate ( Actor  actor,
Path  path,
const Vector3 forward,
AlphaFunction  alpha,
TimePeriod  period 
)

Animates an actor's position and orientation through a predefined path.

The actor will rotate to orient the supplied forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actorThe actor to animate
[in]pathThe path. It defines position and orientation
[in]forwardThe vector (in local space coordinate system) that will be oriented with the path's tangent direction
[in]alphaThe alpha function to apply
[in]periodThe effect will occur during this time period
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
Interpolation  interpolation 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]interpolationThe method used to interpolate between values
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
AlphaFunction  alpha 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]alphaThe alpha function to apply
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
AlphaFunction  alpha,
Interpolation  interpolation 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]alphaThe alpha function to apply
[in]interpolationThe method used to interpolate between values
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
TimePeriod  period 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]periodThe effect will occur during this time period
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
TimePeriod  period,
Interpolation  interpolation 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]periodThe effect will occur duing this time period
[in]interpolationThe method used to interpolate between values
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
AlphaFunction  alpha,
TimePeriod  period 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]alphaThe alpha function to apply
[in]periodThe effect will occur during this time period
void Dali::Animation::AnimateBetween ( Property  target,
KeyFrames keyFrames,
AlphaFunction  alpha,
TimePeriod  period,
Interpolation  interpolation 
)

Animates a property between keyframes.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object property to animate
[in]keyFramesThe set of time/value pairs between which to animate
[in]alphaThe alpha function to apply to the overall progress
[in]periodThe effect will occur duing this time period
[in]interpolationThe method used to interpolate between values
void Dali::Animation::AnimateBy ( Property  target,
Property::Value  relativeValue 
)

Animates a property value by a relative amount.

The default alpha function will be used. The effect will start & end when the animation begins & ends.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]relativeValueThe property value will change by this amount
void Dali::Animation::AnimateBy ( Property  target,
Property::Value  relativeValue,
AlphaFunction  alpha 
)

Animates a property value by a relative amount.

The effect will start & end when the animation begins & ends.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]relativeValueThe property value will change by this amount
[in]alphaThe alpha function to apply
void Dali::Animation::AnimateBy ( Property  target,
Property::Value  relativeValue,
TimePeriod  period 
)

Animates a property value by a relative amount.

The default alpha function will be used.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]relativeValueThe property value will increase/decrease by this amount
[in]periodThe effect will occur during this time period
void Dali::Animation::AnimateBy ( Property  target,
Property::Value  relativeValue,
AlphaFunction  alpha,
TimePeriod  period 
)

Animates a property value by a relative amount.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]relativeValueThe property value will increase/decrease by this amount
[in]alphaThe alpha function to apply
[in]periodThe effect will occur during this time period
void Dali::Animation::AnimateTo ( Property  target,
Property::Value  destinationValue 
)

Animates a property to a destination value.

The default alpha function will be used. The effect will start & end when the animation begins & ends.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]destinationValueThe destination value
void Dali::Animation::AnimateTo ( Property  target,
Property::Value  destinationValue,
AlphaFunction  alpha 
)

Animates a property to a destination value.

The effect will start & end when the animation begins & ends.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]destinationValueThe destination value
[in]alphaThe alpha function to apply
void Dali::Animation::AnimateTo ( Property  target,
Property::Value  destinationValue,
TimePeriod  period 
)

Animates a property to a destination value.

The default alpha function will be used.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]destinationValueThe destination value
[in]periodThe effect will occur during this time period
void Dali::Animation::AnimateTo ( Property  target,
Property::Value  destinationValue,
AlphaFunction  alpha,
TimePeriod  period 
)

Animates a property to a destination value.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]targetThe target object/property to animate
[in]destinationValueThe destination value
[in]alphaThe alpha function to apply
[in]periodThe effect will occur during this time period

Clears the animation.

This disconnects any objects that were being animated, effectively stopping the animation.

Since:
2.4, DALi version 1.0.0
static Animation Dali::Animation::DownCast ( BaseHandle  handle) [static]

Downcasts a handle to Animation handle.

If handle points to an Animation object, the downcast produces valid handle. If not, the returned handle is left uninitialized.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]handleHandle to an object
Returns:
Handle to an Animation object or an uninitialized handle

Connects to this signal to be notified when an Animation's animations have finished.

Since:
2.4, DALi version 1.0.0
Returns:
A signal object to connect with

Gets the current loop count.

A value 0 to GetLoopCount() indicating the current loop count when looping.

Since:
3.0, DALi version 1.1.20
Returns:
The current number of loops that have occured

Retrieves the current progress of the animation.

Since:
2.4, DALi version 1.0.0
Returns:
The current progress as a normalized value between [0,1]

Retrieves the default alpha function for an animation.

Since:
2.4, DALi version 1.0.0
Returns:
The default alpha function

Returns the disconnect action.

Since:
2.4, DALi version 1.0.0
Returns:
The disconnect action

Retrieves the duration of an animation.

Since:
2.4, DALi version 1.0.0
Returns:
The duration in seconds

Returns the end action of the animation.

Since:
2.4, DALi version 1.0.0
Returns:
The end action

Gets the loop count.

A zero is the same as SetLooping(true) ie repeat forever. The loop count is initially 1 for play once.

Since:
3.0, DALi version 1.1.20
Returns:
The number of times to loop

Gets the playing range.

Since:
2.4, DALi version 1.0.0
Returns:
The play range defined for the animation

Retrieves the speed factor of the animation.

Since:
2.4, DALi version 1.0.0
Returns:
Speed factor

Queries the state of the animation.

Since:
3.0, DALi version 1.1.21
Returns:
The Animation::State
void Dali::Animation::Hide ( Actor  actor,
float  delaySeconds 
)

Hides an actor during the animation.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actorThe actor to animate
[in]delaySecondsThe initial delay from the start of the animation

Queries whether the animation will loop.

Since:
2.4, DALi version 1.0.0
Returns:
True if the animation will loop
static Animation Dali::Animation::New ( float  durationSeconds) [static]

Creates an initialized Animation.

The animation will not loop. The default end action is "Bake". The default alpha function is linear.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]durationSecondsThe duration in seconds
Returns:
A handle to a newly allocated Dali resource
Precondition:
DurationSeconds must be greater than zero.
Animation& Dali::Animation::operator= ( const Animation rhs)

This assignment operator is required for (smart) pointer semantics.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]rhsA reference to the copied handle
Returns:
A reference to this

Pauses the animation.

Since:
2.4, DALi version 1.0.0

Play the animation.

Since:
2.4, DALi version 1.0.0
void Dali::Animation::PlayFrom ( float  progress)

Plays the animation from a given point.

The progress must be in the 0-1 interval or in the play range interval if defined ( See Animation::SetPlayRange ), otherwise, it will be ignored.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]progressA value between [0,1], or between the play range if specified, from where the animation should start playing

Sets the default alpha function for an animation.

This is applied to individual property animations, if no further alpha functions are supplied.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]alphaThe default alpha function
void Dali::Animation::SetDisconnectAction ( EndAction  disconnectAction)

Sets the disconnect action.

If any of the animated property owners are disconnected from the stage while the animation is being played, then this action is performed. Default action is to BakeFinal.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]disconnectActionThe disconnect action
void Dali::Animation::SetDuration ( float  seconds)

Sets the duration of an animation.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]secondsThe duration in seconds
Precondition:
DurationSeconds must be greater than zero.

Sets the end action of the animation.

This action is performed when the animation ends or if it is stopped. Default end action is bake.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actionThe end action
void Dali::Animation::SetLoopCount ( int  count)

Enables looping for 'count' repeats.

A zero is the same as SetLooping(true) i.e. repeat forever. If Play() Stop() or 'count' loops is reached, the loop counter will reset. Setting this parameter does not cause the animation to Play().

Since:
3.0, DALi version 1.1.20
Parameters:
[in]countThe number of times to loop
void Dali::Animation::SetLooping ( bool  looping)

Sets whether the animation will loop.

This function resets the loop count and should not be used with SetLoopCount(int). Setting this parameter does not cause the animation to Play().

Since:
2.4, DALi version 1.0.0
Parameters:
[in]loopingTrue if the animation will loop
void Dali::Animation::SetPlayRange ( const Vector2 range)

Sets the playing range.

Animation will play between the values specified. Both values ( range.x and range.y ) should be between 0-1, otherwise they will be ignored. If the range provided is not in proper order ( minimum,maximum ), it will be reordered.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]rangeTwo values between [0,1] to specify minimum and maximum progress. The animation will play between those values
void Dali::Animation::SetSpeedFactor ( float  factor)

Specifies a speed factor for the animation.

The speed factor is a multiplier of the normal velocity of the animation. Values between [0,1] will slow down the animation and values above one will speed up the animation. It is also possible to specify a negative multiplier to play the animation in reverse.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]factorA value which will multiply the velocity
void Dali::Animation::Show ( Actor  actor,
float  delaySeconds 
)

Shows an actor during the animation.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]actorThe actor to animate
[in]delaySecondsThe initial delay from the start of the animation

Stops the animation.

Since:
2.4, DALi version 1.0.0