Tizen Native API
Public Types | Public Member Functions | Static Public Member Functions
Dali::Animation Class Reference
Animation

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
 What to do when the animation ends, is stopped or is destroyed. More...
enum  Interpolation
 What interpolation method to use on key-frame animations. More...
typedef Signal< void(Animation &) > AnimationSignalType
 Animation finished signal type.
typedef Any AnyFunction
 Interpolation function.

Public Member Functions

 Animation ()
 Create 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.
Animation & operator= (const Animation &rhs)
 This assignment operator is required for (smart) pointer semantics.
void SetDuration (float seconds)
 Set the duration of an animation.
float GetDuration () const
 Retrieve the duration of an animation.
void SetLooping (bool looping)
 Set whether the animation will loop.
bool IsLooping () const
 Query whether the animation will loop.
void SetEndAction (EndAction action)
 Set the end action of the animation.
EndAction GetEndAction () const
 Returns the end action of the animation.
void SetDisconnectAction (EndAction disconnectAction)
 Set the disconnect action.
EndAction GetDisconnectAction () const
 Returns the disconnect action.
void SetDefaultAlphaFunction (AlphaFunction alpha)
 Set the default alpha function for an animation.
AlphaFunction GetDefaultAlphaFunction () const
 Retrieve the default alpha function for an animation.
void SetCurrentProgress (float progress)
 Sets the progress of the animation.
float GetCurrentProgress ()
 Retrieve the current progress of the animation.
void SetSpeedFactor (float factor)
 Specifies an speed factor for the animation.
float GetSpeedFactor () const
 Retrieve the speed factor of the animation.
void SetPlayRange (const Vector2 &range)
 Set the playing range.
Vector2 GetPlayRange () const
 Get the playing range.
void Play ()
 Play the animation.
void PlayFrom (float progress)
 Play the animation from a given point.
void Pause ()
 Pause the animation.
void Stop ()
 Stop the animation.
void Clear ()
 Clear the animation.
AnimationSignalType & FinishedSignal ()
 Connect to this signal to be notified when an Animation's animations have finished.
void AnimateBy (Property target, Property::Value relativeValue)
 Animate a property value by a relative amount.
void AnimateBy (Property target, Property::Value relativeValue, AlphaFunction alpha)
 Animate a property value by a relative amount.
void AnimateBy (Property target, Property::Value relativeValue, TimePeriod period)
 Animate a property value by a relative amount.
void AnimateBy (Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period)
 Animate a property value by a relative amount.
void AnimateTo (Property target, Property::Value destinationValue)
 Animate a property to a destination value.
void AnimateTo (Property target, Property::Value destinationValue, AlphaFunction alpha)
 Animate a property to a destination value.
void AnimateTo (Property target, Property::Value destinationValue, TimePeriod period)
 Animate a property to a destination value.
void AnimateTo (Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period)
 Animate a property to a destination value.
void AnimateBetween (Property target, KeyFrames &keyFrames)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, Interpolation interpolation)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha, Interpolation interpolation)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, TimePeriod period)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, TimePeriod period, Interpolation interpolation)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha, TimePeriod period)
 Animate a property between keyframes.
void AnimateBetween (Property target, KeyFrames &keyFrames, AlphaFunction alpha, TimePeriod period, Interpolation interpolation)
 Animate a property between keyframes.
void Animate (Actor actor, Path path, const Vector3 &forward)
 Animate an actor's position and orientation through a predefined path.
void Animate (Actor actor, Path path, const Vector3 &forward, AlphaFunction alpha)
 Animate an actor's position and orientation through a predefined path.
void Animate (Actor actor, Path path, const Vector3 &forward, TimePeriod period)
 Animate an actor's position and orientation through a predefined path.
void Animate (Actor actor, Path path, const Vector3 &forward, AlphaFunction alpha, TimePeriod period)
 Animate an actor's position and orientation through a predefined path.
void Show (Actor actor, float delaySeconds)
 Show an actor during the animation.
void Hide (Actor actor, float delaySeconds)
 Hide an actor during the animation.

Static Public Member Functions

static Animation New (float durationSeconds)
 Create an initialized Animation.
static Animation DownCast (BaseHandle handle)
 Downcast 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.
Since :
2.4

Member Typedef Documentation

typedef Signal< void (Animation&) > Dali::Animation::AnimationSignalType

Animation finished signal type.

Since :
2.4
typedef Any Dali::Animation::AnyFunction

Interpolation function.

Since :
2.4

Member Enumeration Documentation

enum Dali::Animation::EndAction

What to do when the animation ends, is stopped or is destroyed.

Since :
2.4
Enumerator:
Bake 

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

Since :
2.4
Discard 

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

Since :
2.4
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
enum Dali::Animation::Interpolation

What interpolation method to use on key-frame animations.

Since :
2.4
Enumerator:
Linear 

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

Since :
2.4
Cubic 

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

Since :
2.4

Constructor & Destructor Documentation

Dali::Animation::Animation ( )

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

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

Since :
2.4
Dali::Animation::~Animation ( )

Destructor.

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

Since :
2.4
Dali::Animation::Animation ( const Animation &  handle)

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

Since :
2.4
Parameters:
[in]handleA reference to the copied handle

Member Function Documentation

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

Animate 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
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 
)

Animate 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
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 
)

Animate 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
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 
)

Animate 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
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate a property between keyframes.

Since :
2.4
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 
)

Animate 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
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 
)

Animate a property value by a relative amount.

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

Since :
2.4
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 
)

Animate a property value by a relative amount.

The default alpha function will be used.

Since :
2.4
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 
)

Animate a property value by a relative amount.

Since :
2.4
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 
)

Animate 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
Parameters:
[in]targetThe target object/property to animate.
[in]destinationValueThe destination value.
void Dali::Animation::AnimateTo ( Property  target,
Property::Value  destinationValue,
AlphaFunction  alpha 
)

Animate a property to a destination value.

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

Since :
2.4
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 
)

Animate a property to a destination value.

The default alpha function will be used.

Since :
2.4
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 
)

Animate a property to a destination value.

Since :
2.4
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.
void Dali::Animation::Clear ( )

Clear the animation.

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

Since :
2.4
static Animation Dali::Animation::DownCast ( BaseHandle  handle) [static]

Downcast 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
Parameters:
[in]handleHandle to an object
Returns:
Handle to a Animation object or an uninitialized handle
AnimationSignalType& Dali::Animation::FinishedSignal ( )

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

Since :
2.4
Returns:
A signal object to Signal::Connect() with.
float Dali::Animation::GetCurrentProgress ( )

Retrieve the current progress of the animation.

Since :
2.4
Returns:
The current progress as a normalized value between [0,1].
AlphaFunction Dali::Animation::GetDefaultAlphaFunction ( ) const

Retrieve the default alpha function for an animation.

Since :
2.4
Returns:
The default alpha function.
EndAction Dali::Animation::GetDisconnectAction ( ) const

Returns the disconnect action.

Since :
2.4
Returns:
The disconnect action.
float Dali::Animation::GetDuration ( ) const

Retrieve the duration of an animation.

Since :
2.4
Returns:
The duration in seconds.
EndAction Dali::Animation::GetEndAction ( ) const

Returns the end action of the animation.

Since :
2.4
Returns:
The end action.
Vector2 Dali::Animation::GetPlayRange ( ) const

Get the playing range.

Since :
2.4
Returns:
The play range defined for the animation.
float Dali::Animation::GetSpeedFactor ( ) const

Retrieve the speed factor of the animation.

Since :
2.4
Returns:
Speed factor
void Dali::Animation::Hide ( Actor  actor,
float  delaySeconds 
)

Hide an actor during the animation.

Since :
2.4
Parameters:
[in]actorThe actor to animate.
[in]delaySecondsThe initial delay from the start of the animation.
bool Dali::Animation::IsLooping ( ) const

Query whether the animation will loop.

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

Create an initialized Animation.

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

Since :
2.4
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
Parameters:
[in]rhsA reference to the copied handle
Returns:
A reference to this
void Dali::Animation::Pause ( )

Pause the animation.

Since :
2.4
void Dali::Animation::Play ( )

Play the animation.

Since :
2.4
void Dali::Animation::PlayFrom ( float  progress)

Play 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
Parameters:
[in]progressA value between [0,1], or between the play range if specified, form where the animation should start playing
void Dali::Animation::SetCurrentProgress ( float  progress)

Sets the progress of the animation.

The animation will play (or continue playing) from this 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
Parameters:
[in]progressThe new progress as a normalized value between [0,1] or between the play range if specified.
void Dali::Animation::SetDefaultAlphaFunction ( AlphaFunction  alpha)

Set the default alpha function for an animation.

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

Since :
2.4
Parameters:
[in]alphaThe default alpha function.
void Dali::Animation::SetDisconnectAction ( EndAction  disconnectAction)

Set 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
Parameters:
[in]disconnectActionThe disconnect action.
void Dali::Animation::SetDuration ( float  seconds)

Set the duration of an animation.

Since :
2.4
Parameters:
[in]secondsThe duration in seconds.
Precondition:
DurationSeconds must be greater than zero.
void Dali::Animation::SetEndAction ( EndAction  action)

Set 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
Parameters:
[in]actionThe end action.
void Dali::Animation::SetLooping ( bool  looping)

Set whether the animation will loop.

Since :
2.4
Parameters:
[in]loopingTrue if the animation will loop.
void Dali::Animation::SetPlayRange ( const Vector2 &  range)

Set 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
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 an 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
Parameters:
[in]factorA value which will multiply the velocity.
void Dali::Animation::Show ( Actor  actor,
float  delaySeconds 
)

Show an actor during the animation.

Since :
2.4
Parameters:
[in]actorThe actor to animate.
[in]delaySecondsThe initial delay from the start of the animation.
void Dali::Animation::Stop ( )

Stop the animation.

Since :
2.4