X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fanimation%2Fanimation.h;h=715c8ea49f364b745199b0bdc298ecd63ba5f7e2;hb=ec5b656de57a8a0606fd1624e3ed7ae1582523ee;hp=7ed8c610ff2e64e3ebfbdd188517809b9b402d4c;hpb=7bedd5c934115c17ad6178ac8f984ba5db1ac775;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/animation/animation.h b/dali/public-api/animation/animation.h index 7ed8c61..715c8ea 100644 --- a/dali/public-api/animation/animation.h +++ b/dali/public-api/animation/animation.h @@ -1,8 +1,8 @@ -#ifndef __DALI_ANIMATION_H__ -#define __DALI_ANIMATION_H__ +#ifndef DALI_ANIMATION_H +#define DALI_ANIMATION_H /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2017 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,37 +18,27 @@ * */ -// EXTERNAL INCLUDES -#include - // INTERNAL INCLUDES -#include +#include #include +#include #include #include #include #include -#include +#include -namespace Dali DALI_IMPORT_API +namespace Dali { +/** + * @addtogroup dali_core_animation + * @{ + */ class Actor; -struct Degree; -class Quaternion; -struct Radian; -class ShaderEffect; struct Property; struct Vector2; struct Vector3; -struct Vector4; - -typedef boost::function AnimatorFunctionBool; ///< Animator function signature for boolean properties. -typedef boost::function AnimatorFunctionFloat; ///< Animator function signature for float properties. -typedef boost::function AnimatorFunctionVector2; ///< Animator function signature for Vector2 properties. -typedef boost::function AnimatorFunctionVector3; ///< Animator function signature for Vector3 properties. -typedef boost::function AnimatorFunctionVector4; ///< Animator function signature for Vector4 properties. -typedef boost::function AnimatorFunctionQuaternion;///< Animator function signature for Quaternion properties. namespace Internal DALI_INTERNAL { @@ -71,7 +61,7 @@ class Animation; * // ...To play the animation * * mAnimation = Animation::New(3.0f); // duration 3 seconds - * mAnimation.MoveTo(mActor, 10.0f, 50.0f, 0.0f); + * mAnimation.AnimateTo(Property(mActor, Actor::Property::POSITION), Vector3(10.0f, 50.0f, 0.0f)); * mAnimation.Play(); * * @endcode @@ -89,8 +79,8 @@ class Animation; * void ExampleAnimation( Actor actor ) * { * Animation animation = Animation::New(2.0f); // duration 2 seconds - * animation.MoveTo(actor, 10.0f, 50.0f, 0.0f); - * animation.SignalFinished().Connect( ExampleCallback ); + * 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 * @@ -106,1043 +96,666 @@ class Animation; * * 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. + * + * The overall animation time is superseded by the values given in the TimePeriod structure used when calling the AnimateTo(), AnimateBy(), AnimateBetween() and Animate() methods. + * If any of the individual calls to those functions exceeds the overall animation time, then the overall animation time is automatically extended. + * + * Using AnimateTo and AnimateBy for the same property of the same Actor will yield undefined behaviour especially if the TimePeriod overlaps. + * + * After calling Animation::Play(), Handle::GetProperty will return the target value of the animated property. + * + * Signals + * | %Signal Name | Method | + * |--------------|--------------------------| + * | finished | @ref FinishedSignal() | + * + * Actions + * | %Action Name | %Animation method called | + * |--------------|--------------------------| + * | play | Play() | + * | stop | Stop() | + * | pause | Pause() | + * @SINCE_1_0.0 */ class DALI_IMPORT_API Animation : public BaseHandle { public: - typedef SignalV2< void (Animation&) > AnimationSignalV2; ///< Animation finished signal type + typedef Signal< void (Animation&) > AnimationSignalType; ///< Animation finished signal type @SINCE_1_0.0 - typedef Any AnyFunction; ///< Interpolation function - typedef boost::function Vector3AnimatorFunc; ///< Interpolation function - typedef boost::function QuaternionAnimatorFunc; ///< Interpolation function + typedef Any AnyFunction; ///< Interpolation function @SINCE_1_0.0 /** - * @brief What to do when the animation ends, is stopped or is destroyed + * @brief Enumeration for what to do when the animation ends, is stopped, or is destroyed. + * @SINCE_1_0.0 */ enum EndAction { - Bake, ///< When the animation ends, the animated property values are saved. - Discard, ///< When the animation ends, the animated property values are forgotten. - BakeFinal ///< If the animation is stopped, the animated property values are saved as if the animation had run to completion, otherwise behaves like Bake. + Bake, ///< When the animation ends, the animated property values are saved. @SINCE_1_0.0 + Discard, ///< When the animation ends, the animated property values are forgotten. @SINCE_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_1_0.0 + }; + + /** + * @brief Enumeration for what interpolation method to use on key-frame animations. + * @SINCE_1_0.0 + */ + enum Interpolation + { + Linear, ///< Values in between key frames are interpolated using a linear polynomial. (Default) @SINCE_1_0.0 + Cubic ///< Values in between key frames are interpolated using a cubic polynomial. @SINCE_1_0.0 }; - //Signal Names - static const char* const SIGNAL_FINISHED; ///< name "finished" + /** + * @brief 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_1_1.21 + */ + enum State + { + STOPPED, ///< Animation has stopped @SINCE_1_1.21 + PLAYING, ///< The animation is playing @SINCE_1_1.21 + PAUSED ///< The animation is paused @SINCE_1_1.21 + }; - //Action Names - static const char* const ACTION_PLAY; ///< name "play" - static const char* const ACTION_STOP; ///< name "stop" - static const char* const ACTION_PAUSE; ///< name "pause" + /** + * @brief Enumeration for what looping mode is in. + * + * @SINCE_1_2.60 + */ + enum LoopingMode + { + RESTART, ///< When the animation arrives at the end in looping mode, the animation restarts from the beginning. @SINCE_1_2.60 + AUTO_REVERSE ///< When the animation arrives at the end in looping mode, the animation reverses direction and runs backwards again. @SINCE_1_2.60 + }; /** - * @brief Create an uninitialized Animation; this can be initialized with Animation::New(). + * @brief Creates an uninitialized Animation; this can be initialized with Animation::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized Animation handle is not allowed. + * @SINCE_1_0.0 */ Animation(); /** - * @brief Create an initialized Animation. + * @brief Creates an initialized Animation. * * The animation will not loop. * The default end action is "Bake". * The default alpha function is linear. - * @pre durationSeconds must be greater than zero. - * @param [in] durationSeconds The duration in seconds. - * @return A handle to a newly allocated Dali resource. + * @SINCE_1_0.0 + * @param[in] durationSeconds The duration in seconds + * @return A handle to a newly allocated Dali resource + * @note durationSeconds can not be negative. */ static Animation New(float durationSeconds); /** - * @brief Downcast an Object handle to Animation. + * @brief 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. + * If handle points to an Animation object, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * - * @param[in] handle to An object - * @return handle to a Animation object or an uninitialized handle + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return Handle to an Animation object or an uninitialized handle */ static Animation DownCast( BaseHandle handle ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~Animation(); /** - * @copydoc Dali::BaseHandle::operator= - */ - using BaseHandle::operator=; - - /** - * @brief Set the duration of an animation. + * @brief This copy constructor is required for (smart) pointer semantics. * - * @pre durationSeconds must be greater than zero. - * @param[in] seconds The duration in seconds. + * @SINCE_1_0.0 + * @param[in] handle A reference to the copied handle */ - void SetDuration(float seconds); + Animation(const Animation& handle); /** - * @brief Retrieve the duration of an animation. + * @brief This assignment operator is required for (smart) pointer semantics. * - * @return The duration in seconds. + * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle + * @return A reference to this */ - float GetDuration() const; + Animation& operator=(const Animation& rhs); /** - * @brief Set whether the animation will loop. + * @brief Sets the duration of an animation. * - * @param[in] looping True if the animation will loop. + * @SINCE_1_0.0 + * @param[in] seconds The duration in seconds + * @pre DurationSeconds must be greater than zero. */ - void SetLooping(bool looping); + void SetDuration(float seconds); /** - * @brief Query whether the animation will loop. + * @brief Retrieves the duration of an animation. * - * @return True if the animation will loop. + * @SINCE_1_0.0 + * @return The duration in seconds */ - bool IsLooping() const; + float GetDuration() const; /** - * @brief Set the end action of the animation. + * @brief Sets whether the animation will loop. * - * This action is performed when the animation ends. - * Default end action is bake - * @param[in] action The end action. - */ - void SetEndAction(EndAction action); - - /** - * @brief Returns the end action of the animation. + * This function resets the loop count and should not be used with SetLoopCount(int). + * Setting this parameter does not cause the animation to Play(). * - * @return The end action. + * @SINCE_1_0.0 + * @param[in] looping True if the animation will loop */ - EndAction GetEndAction() const; + void SetLooping(bool looping); /** - * @brief Set the destroy action of the animation. + * @brief Enables looping for 'count' repeats. * - * If the animation is destroyed this action is performed on the following update. - * Default destroy action is bake - * @param[in] action The destroy action. - */ - void SetDestroyAction(EndAction action); - - /** - * @brief Returns the destroy action of the animation. + * 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(). * - * @return The destroy action. + * @SINCE_1_1.20 + * @param[in] count The number of times to loop */ - EndAction GetDestroyAction() const; + void SetLoopCount(int count); /** - * @brief Set the default alpha function for an animation. + * @brief Gets the loop count. * - * This is applied to individual property animations, if no further alpha functions are supplied. - * @param[in] alpha The default alpha function. - */ - void SetDefaultAlphaFunction(AlphaFunction alpha); - - /** - * @brief Retrieve the default alpha function for an animation. + * A zero is the same as SetLooping(true) ie repeat forever. + * The loop count is initially 1 for play once. * - * @return The default alpha function. + * @SINCE_1_1.20 + * @return The number of times to loop */ - AlphaFunction GetDefaultAlphaFunction() const; + int GetLoopCount(); /** - * @brief Retrieve the current progress of the animation. - * - * @return The current progress as a normalized value between [0,1]. - */ - float GetCurrentProgress(); - - /* - * @brief Sets the progress of the animation. - * The animation will play (or continue playing) from this point + * @brief Gets the current loop count. * - * @param[in] progress The new progress as a normalized value between [0,1]. - */ - void SetCurrentProgress( float progress ); - - /** - * @brief Play the animation. - */ - void Play(); - - /** - * @brief Play the animation from a given point. - * @param[in] progress A value between [0,1] form where the animation should start playing - */ - void PlayFrom( float progress ); - - /** - * @brief Pause the animation. - */ - void Pause(); - - /** - * @brief Stop the animation. - */ - void Stop(); - - /** - * @brief Clear the animation. + * A value 0 to GetLoopCount() indicating the current loop count when looping. * - * This disconnects any objects that were being animated, effectively stopping the animation. + * @SINCE_1_1.20 + * @return The current number of loops that have occured */ - void Clear(); + int GetCurrentLoop(); /** - * @brief Connect to this signal to be notified when an Animation's animations have finished. + * @brief Queries whether the animation will loop. * - * @return A signal object to Connect() with. + * @SINCE_1_0.0 + * @return True if the animation will loop */ - AnimationSignalV2& FinishedSignal(); + bool IsLooping() const; /** - * @brief Animate a property value by a relative amount. + * @brief Sets the end action of the animation. * - * The default alpha function will be used. - * The effect will start & end when the animation begins & ends. - * @param [in] target The target object/property to animate. - * @param [in] relativeValue The property value will change by this amount. + * This action is performed when the animation ends or if it is stopped. + * Default end action is bake. + * @SINCE_1_0.0 + * @param[in] action The end action */ - void AnimateBy(Property target, Property::Value relativeValue); + void SetEndAction(EndAction action); /** - * @brief Animate a property value by a relative amount. + * @brief Returns the end action of the animation. * - * The effect will start & end when the animation begins & ends. - * @param [in] target The target object/property to animate. - * @param [in] relativeValue The property value will change by this amount. - * @param [in] alpha The alpha function to apply. + * @SINCE_1_0.0 + * @return The end action */ - void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha); + EndAction GetEndAction() const; /** - * @brief Animate a property value by a relative amount. + * @brief Sets the disconnect action. * - * The default alpha function will be used. - * @param [in] target The target object/property to animate. - * @param [in] relativeValue The property value will increase/decrease by this amount. - * @param [in] period The effect will occur during this time period. + * 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_1_0.0 + * @param[in] disconnectAction The disconnect action */ - void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period); + void SetDisconnectAction( EndAction disconnectAction ); /** - * @brief Animate a property value by a relative amount. + * @brief Returns the disconnect action. * - * @param [in] target The target object/property to animate. - * @param [in] relativeValue The property value will increase/decrease by this amount. - * @param [in] alpha The alpha function to apply. - * @param [in] period The effect will occur during this time period. + * @SINCE_1_0.0 + * @return The disconnect action */ - void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period); + EndAction GetDisconnectAction() const; /** - * @brief Animate a property to a destination value. + * @brief Sets the default alpha function for an animation. * - * The default alpha function will be used. - * The effect will start & end when the animation begins & ends. - * @param [in] target The target object/property to animate. - * @param [in] destinationValue The destination value. + * This is applied to individual property animations, if no further alpha functions are supplied. + * @SINCE_1_0.0 + * @param[in] alpha The default alpha function */ - void AnimateTo(Property target, Property::Value destinationValue); + void SetDefaultAlphaFunction(AlphaFunction alpha); /** - * @brief Animate a property to a destination value. + * @brief Retrieves the default alpha function for an animation. * - * The effect will start & end when the animation begins & ends. - * @param [in] target The target object/property to animate. - * @param [in] destinationValue The destination value. - * @param [in] alpha The alpha function to apply. + * @SINCE_1_0.0 + * @return The default alpha function */ - void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha); + AlphaFunction GetDefaultAlphaFunction() const; /** - * @brief Animate a property to a destination value. + * @brief Sets the progress of the animation. * - * The default alpha function will be used. - * @param [in] target The target object/property to animate. - * @param [in] destinationValue The destination value. - * @param [in] period The effect will occur during this time period. - */ - void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period); - - /** - * @brief Animate a property to a destination value. + * 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 @ref Animation::SetPlayRange ), + * otherwise, it will be ignored. * - * @param [in] target The target object/property to animate. - * @param [in] destinationValue The destination value. - * @param [in] alpha The alpha function to apply. - * @param [in] period The effect will occur during this time period. + * @SINCE_1_0.0 + * @param[in] progress The new progress as a normalized value between [0,1] + * or between the play range if specified */ - void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period); + void SetCurrentProgress( float progress ); /** - * @brief Animate a property between keyframes. - * - * @param [in] target The target object/property to animate. - * @param [in] keyFrames The key frames - */ - void AnimateBetween(Property target, KeyFrames& keyFrames); + * @brief Retrieves the current progress of the animation. + * + * @SINCE_1_0.0 + * @return The current progress as a normalized value between [0,1] + */ + float GetCurrentProgress(); /** - * @brief Animate a property between keyframes. + * @brief Specifies a speed factor for the animation. * - * @param [in] target The target object/property to animate. - * @param [in] keyFrames The key frames - * @param [in] alpha The alpha function to apply. - */ - void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha); - - /** - * @brief Animate a property between keyframes. + * 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. * - * @param [in] target The target object/property to animate. - * @param [in] keyFrames The key frames - * @param [in] period The effect will occur during this time period. + * @SINCE_1_0.0 + * @param[in] factor A value which will multiply the velocity */ - void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period); + void SetSpeedFactor( float factor ); /** - * @brief Animate a property between keyframes. + * @brief Retrieves the speed factor of the animation. * - * @param [in] target The target object/property to animate. - * @param [in] keyFrames The key frames - * @param [in] alpha The alpha function to apply. - * @param [in] period The effect will occur during this time period. + * @SINCE_1_0.0 + * @return Speed factor */ - void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period); + float GetSpeedFactor() const; /** - * @brief Animate a property using a custom function. + * @brief Sets the playing range. * - * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. - * @pre The property type is equal PropertyTypes::Get

(). - * @param [in] target The target object/property to animate. - * @param [in] animatorFunc The function to call during the animation. - */ - template - void Animate( Property target, boost::function

animatorFunc ) - { - Animate( target, PropertyTypes::Get

(), animatorFunc ); - } - - /** - * @brief Animate a property using a custom function. + * 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. * - * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. - * @pre The property type is equal PropertyTypes::Get

(). - * @param [in] target The target object/property to animate. - * @param [in] animatorFunc The function to call during the animation. - * @param [in] alpha The alpha function to apply. + * @SINCE_1_0.0 + * @param[in] range Two values between [0,1] to specify minimum and maximum progress. The + * animation will play between those values */ - template - void Animate( Property target, boost::function

animatorFunc, AlphaFunction alpha ) - { - Animate( target, PropertyTypes::Get

(), animatorFunc, alpha ); - } + void SetPlayRange( const Vector2& range ); /** - * @brief Animate a property using a custom function. + * @brief Gets the playing range. * - * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. - * @pre The property type is equal PropertyTypes::Get

(). - * @param [in] target The target object/property to animate. - * @param [in] animatorFunc The function to call during the animation. - * @param [in] period The effect will occur during this time period. + * @SINCE_1_0.0 + * @return The play range defined for the animation */ - template - void Animate( Property target, boost::function

animatorFunc, TimePeriod period ) - { - Animate( target, PropertyTypes::Get

(), animatorFunc, period ); - } + Vector2 GetPlayRange() const; /** - * @brief Animate a property using a custom function. - * - * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. - * @pre The property type is equal PropertyTypes::Get

(). - * @param [in] target The target object/property to animate. - * @param [in] animatorFunc The function to call during the animation. - * @param [in] alpha The alpha function to apply. - * @param [in] period The effect will occur during this time period. + * @brief Play the animation. + * @SINCE_1_0.0 */ - template - void Animate( Property target, boost::function

animatorFunc, AlphaFunction alpha, TimePeriod period ) - { - Animate( target, PropertyTypes::Get

(), animatorFunc, alpha, period ); - } - - // Actor-specific convenience methods + void Play(); /** - * @brief Move an actor relative to its position. + * @brief Plays the animation from a given point. * - * The default alpha function will be used. - * The move will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] x axis displacement. - * @param [in] y axis displacement. - * @param [in] z axis displacement. - */ - void MoveBy(Actor actor, float x, float y, float z); - - /** - * @brief Move an actor relative to its position. + * The progress must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ), + * otherwise, it will be ignored. * - * This overload allows the alpha function to be customized. - * The move will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] displacement relative to current position. - * @param [in] alpha The alpha function to apply. - */ - void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha); - - /** - * @brief Move an actor relative to its position. - * - * This overload allows the translation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] displacement relative to current position. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the translation. + * @SINCE_1_0.0 + * @param[in] progress A value between [0,1], or between the play range if specified, from where the animation should start playing */ - void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void PlayFrom( float progress ); /** - * @brief Move an actor to a target position. + * @brief Play the animation after a given delay time. * - * The default alpha function will be used. - * The move will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] x axis position. - * @param [in] y axis position. - * @param [in] z axis position. + * The delay time is not included in the looping time. + * When the delay time is negative value, it would treat as play immediately. + * @SINCE_1_2.60 + * @param[in] delaySeconds The delay time */ - void MoveTo(Actor actor, float x, float y, float z); + void PlayAfter( float delaySeconds ); /** - * @brief Move an actor to a target position. - * - * This overload allows the alpha function to be customized. - * The move will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] position to move to - * @param [in] alpha The alpha function to apply. + * @brief Pauses the animation. + * @SINCE_1_0.0 */ - void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha); + void Pause(); /** - * @brief Move an actor to a target position. - * - * This overload allows the translation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] position to move to - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the translation. + * @brief Queries the state of the animation. + * @SINCE_1_1.21 + * @return The Animation::State */ - void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha, float delaySeconds, float durationSeconds); + State GetState() const; /** - * @brief Move an actor using a custom function. - * - * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] animatorFunc The function to call during the animation. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the translation. + * @brief Stops the animation. + * @SINCE_1_0.0 */ - void Move(Actor actor, AnimatorFunctionVector3 animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void Stop(); /** - * @brief Rotate an actor around an arbitrary axis. + * @brief Clears the animation. * - * The default alpha function will be used. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The angle in degrees. - * @param [in] axis The axis to rotate around + * This disconnects any objects that were being animated, effectively stopping the animation. + * @SINCE_1_0.0 */ - void RotateBy(Actor actor, Degree angle, Vector3 axis); + void Clear(); /** - * @brief Rotate an actor around an arbitrary axis. + * @brief Sets the looping mode. * - * The default alpha function will be used. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The angle in radians. - * @param [in] axis The axis to rotate around - */ - void RotateBy(Actor actor, Radian angle, Vector3 axis); - - /** - * @brief Rotate an actor around an arbitrary axis. - * - * This overload allows the alpha function to be customized. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The angle in radians. - * @param [in] axis The axis to rotate around. - * @param [in] alpha The alpha function to apply. - */ - void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha); - - /** - * @brief Rotate an actor around an arbitrary axis. - * - * This overload allows the alpha function to be customized. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The angle in radians. - * @param [in] axis The axis to rotate around. - * @param [in] alpha The alpha function to apply. + * Animation plays forwards and then restarts from the beginning or runs backwards again. + * @SINCE_1_2.60 + * @param[in] loopingMode The looping mode is one of RESTART and AUTO_REVERSE */ - void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha); + void SetLoopingMode( LoopingMode loopingMode ); /** - * @brief Rotate an actor around an arbitrary axis. - * - * This overload allows the rotation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] angle The angle in degrees. - * @param [in] axis The axis to rotate around - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the rotation. + * @brief Gets one of the current looping mode. + * + * @SINCE_1_2.60 + * @return The current looping mode */ - void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); + LoopingMode GetLoopingMode() const; /** - * @brief Rotate an actor around an arbitrary axis. - * - * This overload allows the rotation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] angle The angle in radians. - * @param [in] axis The axis to rotate around - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the rotation. + * @brief Connects to this signal to be notified when an Animation's animations have finished. + * + * @SINCE_1_0.0 + * @return A signal object to connect with */ - void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); + AnimationSignalType& FinishedSignal(); /** - * @brief Rotate an actor to a target orientation. + * @brief Animates a property value by a relative amount. * * The default alpha function will be used. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The target rotation angle in degrees. - * @param [in] axis The target axis of rotation. + * The effect will start & end when the animation begins & ends. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] relativeValue The property value will change by this amount */ - void RotateTo(Actor actor, Degree angle, Vector3 axis); + void AnimateBy(Property target, Property::Value relativeValue); /** - * @brief Rotate an actor to a target orientation. + * @brief Animates a property value by a relative amount. * - * The default alpha function will be used. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The target rotation angle in radians. - * @param [in] axis The target axis of rotation. + * The effect will start & end when the animation begins & ends. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] relativeValue The property value will change by this amount + * @param[in] alpha The alpha function to apply */ - void RotateTo(Actor actor, Radian angle, Vector3 axis); + void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha); /** - * @brief Rotate an actor to a target orientation. + * @brief Animates a property value by a relative amount. * * The default alpha function will be used. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] orientation The target orientation. - */ - void RotateTo(Actor actor, Quaternion orientation); - - /** - * @brief Rotate an actor to a target orientation. - * - * This overload allows the alpha function to be customized. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The target rotation angle in degrees. - * @param [in] axis The target axis of rotation. - * @param [in] alpha The alpha function to apply. - */ - void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha); - - /** - * @brief Rotate an actor to a target orientation. - * - * This overload allows the alpha function to be customized. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] angle The target rotation angle in radians. - * @param [in] axis The target axis of rotation. - * @param [in] alpha The alpha function to apply. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] relativeValue The property value will increase/decrease by this amount + * @param[in] period The effect will occur during this time period */ - void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha); + void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period); /** - * @brief Rotate an actor to a target orientation. + * @brief Animates a property value by a relative amount. * - * This overload allows the alpha function to be customized. - * The rotation will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] orientation The target orientation. - * @param [in] alpha The alpha function to apply. - */ - void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha); - - /** - * @brief Rotate an actor to a target orientation. - * - * This overload allows the rotation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] angle The target rotation angle in degrees. - * @param [in] axis The target axis of rotation. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the rotation. - */ - void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Rotate an actor to a target orientation. - * - * This overload allows the rotation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] angle The target rotation angle in radians. - * @param [in] axis The target axis of rotation. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the rotation. - */ - void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Rotate an actor to a target orientation. - * - * This overload allows the rotation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] orientation The target orientation. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the rotation. - */ - void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Rotate an actor using a custom function. - * - * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] animatorFunc The function to call during the animation. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the rotation. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] relativeValue The property value will increase/decrease by this amount + * @param[in] alpha The alpha function to apply + * @param[in] period The effect will occur during this time period */ - void Rotate(Actor actor, AnimatorFunctionQuaternion animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period); /** - * @brief Scale an actor. + * @brief Animates a property to a destination value. * * The default alpha function will be used. - * The scaling will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] x Scale factor in the X-direction. - * @param [in] y Scale factor in the Y-direction. - * @param [in] z Scale factor in the Z-direction. + * The effect will start & end when the animation begins & ends. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] destinationValue The destination value */ - void ScaleBy(Actor actor, float x, float y, float z); + void AnimateTo(Property target, Property::Value destinationValue); /** - * @brief Scale an actor. + * @brief Animates a property to a destination value. * - * This overload allows the alpha function to be customized. - * The scaling will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] scale The scale factor. - * @param [in] alpha The alpha function to apply. - */ - void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha); - - /** - * @brief Scale an actor. - * - * This overload allows the scaling start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] scale The scale factor. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the scaling. + * The effect will start & end when the animation begins & ends. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] destinationValue The destination value + * @param[in] alpha The alpha function to apply */ - void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha); /** - * @brief Scale an actor to a target scale factor. + * @brief Animates a property to a destination value. * * The default alpha function will be used. - * The scaling will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] x Target scale-factor in the X-direction. - * @param [in] y Target scale-factor in the Y-direction. - * @param [in] z Target scale-factor in the Z-direction. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] destinationValue The destination value + * @param[in] period The effect will occur during this time period */ - void ScaleTo(Actor actor, float x, float y, float z); + void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period); /** - * @brief Scale an actor to a target scale factor. + * @brief Animates a property to a destination value. * - * This overload allows the alpha function to be customized. - * The scaling will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] scale The target scale factor. - * @param [in] alpha The alpha function to apply. - */ - void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha); - - /** - * @brief Scale an actor to a target scale factor. - * - * This overload allows the scaling start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] scale The target scale factor. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the scaling. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] destinationValue The destination value + * @param[in] alpha The alpha function to apply + * @param[in] period The effect will occur during this time period */ - void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period); - /** - * @brief Show an actor during the animation. + /** + * @brief Animates a property between keyframes. * - * @param [in] actor The actor to animate. - * @param [in] delaySeconds The initial delay from the start of the animation. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate */ - void Show(Actor actor, float delaySeconds); + void AnimateBetween(Property target, KeyFrames& keyFrames); /** - * @brief Hide an actor during the animation. + * @brief Animates a property between keyframes. * - * @param [in] actor The actor to animate. - * @param [in] delaySeconds The initial delay from the start of the animation. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] interpolation The method used to interpolate between values */ - void Hide(Actor actor, float delaySeconds); + void AnimateBetween(Property target, KeyFrames& keyFrames, Interpolation interpolation); /** - * @brief Animate the opacity of an actor. + * @brief Animates a property between keyframes. * - * The default alpha function will be used. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] opacity The relative change in opacity. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] alpha The alpha function to apply */ - void OpacityBy(Actor actor, float opacity); + void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha); /** - * @brief Animate the opacity of an actor. + * @brief Animates a property between keyframes. * - * This overload allows the alpha function to be customized. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] opacity The relative change in opacity. - * @param [in] alpha The alpha function to apply. - */ - void OpacityBy(Actor actor, float opacity, AlphaFunction alpha); - - /** - * @brief Animate the opacity of an actor. - * - * This overload allows the animation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] opacity The relative change in opacity. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the opacity animation. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] alpha The alpha function to apply + * @param[in] interpolation The method used to interpolate between values */ - void OpacityBy(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, Interpolation interpolation); /** - * @brief Animate an actor to a target opacity. + * @brief Animates a property between keyframes. * - * The default alpha function will be used. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] opacity The target opacity. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] period The effect will occur during this time period */ - void OpacityTo(Actor actor, float opacity); + void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period); /** - * @brief Animate an actor to a target opacity. + * @brief Animates a property between keyframes. * - * This overload allows the alpha function to be customized. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] opacity The target opacity. - * @param [in] alpha The alpha function to apply. - */ - void OpacityTo(Actor actor, float opacity, AlphaFunction alpha); - - /** - * @brief Animate an actor to a target opacity. - * - * This overload allows the animation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] opacity The target opacity. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the opacity animation. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] period The effect will occur duing this time period + * @param[in] interpolation The method used to interpolate between values */ - void OpacityTo(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period, Interpolation interpolation); /** - * @brief Animate the color of an actor. + * @brief Animates a property between keyframes. * - * The default alpha function will be used. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] color The relative change in color. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] alpha The alpha function to apply + * @param[in] period The effect will occur during this time period */ - void ColorBy(Actor actor, Vector4 color); + void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period); /** - * @brief Animate the color of an actor. + * @brief Animates a property between keyframes. * - * This overload allows the alpha function to be customized. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] color The relative change in color. - * @param [in] alpha The alpha function to apply. + * @SINCE_1_0.0 + * @param[in] target The target object property to animate + * @param[in] keyFrames The set of time/value pairs between which to animate + * @param[in] alpha The alpha function to apply to the overall progress + * @param[in] period The effect will occur duing this time period + * @param[in] interpolation The method used to interpolate between values */ - void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha); + void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period, Interpolation interpolation); - /** - * @brief Animate the color of an actor. - * - * This overload allows the animation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] color The relative change in color. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the color animation. - */ - void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds); - /** - * @brief Animate an actor to a target color. - * - * The default alpha function will be used. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] color The target color. - */ - void ColorTo(Actor actor, Vector4 color); + // Actor-specific convenience methods /** - * @brief Animate an actor to a target color. + * @brief Animates an actor's position and orientation through a predefined path. * - * This overload allows the alpha function to be customized. - * The effect will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] color The target color. - * @param [in] alpha The alpha function to apply. - */ - void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha); - - /** - * @brief Animate an actor to a target color. - * - * This overload allows the animation start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] color The target color. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the color animation. - */ - void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Resize an actor. + * 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. * - * The default alpha function will be used. - * The resizing will start & end when the animation begins & ends. - * The depth defaults to the minimum of width & height. - * @param [in] actor The actor to animate. - * @param [in] width The target width. - * @param [in] height The target height. + * @SINCE_1_0.0 + * @param[in] actor The actor to animate + * @param[in] path The path. It defines position and orientation + * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction */ - void Resize(Actor actor, float width, float height); + void Animate( Actor actor, Path path, const Vector3& forward ); /** - * @brief Resize an actor. - * - * This overload allows the alpha function to be customized. - * The resizing will start & end when the animation begins & ends. - * The depth defaults to the minimum of width & height. - * @param [in] actor The actor to animate. - * @param [in] width The target width. - * @param [in] height The target height. - * @param [in] alpha The alpha function to apply. + * @brief 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_1_0.0 + * @param[in] actor The actor to animate + * @param[in] path The path. It defines position and orientation + * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction + * @param[in] alpha The alpha function to apply */ - void Resize(Actor actor, float width, float height, AlphaFunction alpha); + void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha ); /** - * @brief Resize an actor. - * - * This overload allows the resizing start & end time to be customized. - * The depth defaults to the minimum of width & height. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] width The target width. - * @param [in] height The target height. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the resizing. + * @brief 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_1_0.0 + * @param[in] actor The actor to animate + * @param[in] path The path. It defines position and orientation + * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction + * @param[in] period The effect will occur during this time period */ - void Resize(Actor actor, float width, float height, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void Animate( Actor actor, Path path, const Vector3& forward, TimePeriod period ); /** - * @brief Resize an actor. + * @brief Animates an actor's position and orientation through a predefined path. * - * The default alpha function will be used. - * The resizing will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] size The target size. + * 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_1_0.0 + * @param[in] actor The actor to animate + * @param[in] path The path. It defines position and orientation + * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction + * @param[in] alpha The alpha function to apply + * @param[in] period The effect will occur during this time period */ - void Resize(Actor actor, Vector3 size); + void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha, TimePeriod period); /** - * @brief Resize an actor. + * @brief Shows an actor during the animation. * - * This overload allows the alpha function to be customized. - * The resizing will start & end when the animation begins & ends. - * @param [in] actor The actor to animate. - * @param [in] size The target size. - * @param [in] alpha The alpha function to apply. + * @SINCE_1_0.0 + * @param[in] actor The actor to animate + * @param[in] delaySeconds The initial delay from the start of the animation */ - void Resize(Actor actor, Vector3 size, AlphaFunction alpha); + void Show(Actor actor, float delaySeconds); /** - * @brief Resize an actor. - * - * This overload allows the resizing start & end time to be customized. - * @pre delaySeconds must be zero or greater. - * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values. - * @param [in] actor The actor to animate. - * @param [in] size The target size. - * @param [in] alpha The alpha function to apply. - * @param [in] delaySeconds The initial delay from the start of the animation. - * @param [in] durationSeconds The duration of the resizing. + * @brief Hides an actor during the animation. + * + * @SINCE_1_0.0 + * @param[in] actor The actor to animate + * @param[in] delaySeconds The initial delay from the start of the animation */ - void Resize(Actor actor, Vector3 size, AlphaFunction alpha, float delaySeconds, float durationSeconds); + void Hide(Actor actor, float delaySeconds); public: // Not intended for use by Application developers + /// @cond internal /** - * @brief This constructor is used by Dali New() methods - * @param [in] animation A pointer to a newly allocated Dali resource + * @brief This constructor is used by Animation::New() methods. + * @SINCE_1_0.0 + * @param[in] animation A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL Animation(Internal::Animation* animation); + /// @endcond -private: - - /** - * @brief Animate a property using a custom function. - * - * @pre The property type is equal expectedType. - * @param [in] target The target object/property to animate. - * @param [in] targetType The expected type of the property. - * @param [in] func The function to call during the animation. - */ - void Animate( Property target, - Property::Type targetType, - AnyFunction func ); - - /** - * @brief Animate a property using a custom function. - * - * @pre The property type is equal expectedType. - * @param [in] target The target object/property to animate. - * @param [in] targetType The expected type of the property. - * @param [in] func The function to call during the animation. - * @param [in] alpha The alpha function to apply. - */ - void Animate( Property target, - Property::Type targetType, - AnyFunction func, - AlphaFunction alpha ); - - /** - * @brief Animate a property using a custom function. - * - * @pre The property type is equal expectedType. - * @param [in] target The target object/property to animate. - * @param [in] targetType The expected type of the property. - * @param [in] func The function to call during the animation. - * @param [in] period The effect will occur during this time period. - */ - void Animate( Property target, - Property::Type targetType, - AnyFunction func, - TimePeriod period ); - - /** - * @brief Animate a property using a custom function. - * - * @pre The property type is equal expectedType. - * @param [in] target The target object/property to animate. - * @param [in] targetType The expected type of the property. - * @param [in] func The function to call during the animation. - * @param [in] alpha The alpha function to apply. - * @param [in] period The effect will occur during this time period. - */ - void Animate( Property target, - Property::Type targetType, - AnyFunction func, - AlphaFunction alpha, - TimePeriod period ); }; +/** + * @} + */ } // namespace Dali -#endif // __DALI_ANIMATION_H__ +#endif // DALI_ANIMATION_H