X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fanimation%2Fanimation.h;h=29160c33ffe01824d83e694748cb6e965808da86;hb=462cbee2270984cdca45488f3733d664dcf49187;hp=17a2789993538804e97cfcac83c79de6ea8be3fb;hpb=89eca940d00c7c1ef06e1800a3dad0c55be5ce4d;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/animation/animation.h b/dali/public-api/animation/animation.h index 17a2789..29160c3 100644 --- a/dali/public-api/animation/animation.h +++ b/dali/public-api/animation/animation.h @@ -2,7 +2,7 @@ #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. @@ -19,27 +19,26 @@ */ // INTERNAL INCLUDES -#include +#include #include #include #include #include #include #include -#include +#include namespace Dali { +/** + * @addtogroup dali_core_animation + * @{ + */ class Actor; -struct Degree; -class Quaternion; -struct Radian; -class ShaderEffect; struct Property; struct Vector2; struct Vector3; -struct Vector4; namespace Internal DALI_INTERNAL { @@ -62,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 @@ -80,7 +79,7 @@ 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.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 @@ -97,414 +96,532 @@ 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 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 What interpolation method to use on key-frame animations + * @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) - Cubic ///< Values in between key frames are interpolated using a cubic polynomial. + 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" - - //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 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 + }; /** - * @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(); /** * @brief This copy constructor is required for (smart) pointer semantics. * - * @param [in] handle A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] handle A reference to the copied handle */ Animation(const Animation& handle); /** * @brief This assignment operator is required for (smart) pointer semantics. * - * @param [in] rhs A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle * @return A reference to this */ Animation& operator=(const Animation& rhs); /** - * @brief Set the duration of an animation. + * @brief Sets the duration of an animation. * - * @pre durationSeconds must be greater than zero. - * @param[in] seconds The duration in seconds. + * @SINCE_1_0.0 + * @param[in] seconds The duration in seconds + * @pre DurationSeconds must be greater than zero. */ void SetDuration(float seconds); /** - * @brief Retrieve the duration of an animation. + * @brief Retrieves the duration of an animation. * - * @return The duration in seconds. + * @SINCE_1_0.0 + * @return The duration in seconds */ float GetDuration() const; /** - * @brief Set whether the animation will loop. + * @brief 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(). * - * @param[in] looping True if the animation will loop. + * @SINCE_1_0.0 + * @param[in] looping True if the animation will loop */ void SetLooping(bool looping); /** - * @brief Query whether the animation will loop. + * @brief Enables looping for 'count' repeats. * - * @return True if the animation will loop. + * 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_1_1.20 + * @param[in] count The number of times to loop + */ + void SetLoopCount(int count); + + /** + * @brief 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_1_1.20 + * @return The number of times to loop + */ + int GetLoopCount(); + + /** + * @brief Gets the current loop count. + * + * A value 0 to GetLoopCount() indicating the current loop count when looping. + * + * @SINCE_1_1.20 + * @return The current number of loops that have occured + */ + int GetCurrentLoop(); + + /** + * @brief Queries whether the animation will loop. + * + * @SINCE_1_0.0 + * @return True if the animation will loop */ bool IsLooping() const; /** - * @brief Set the end action of the animation. + * @brief 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 - * @param[in] action The end action. + * Default end action is bake. + * @SINCE_1_0.0 + * @param[in] action The end action */ void SetEndAction(EndAction action); /** * @brief Returns the end action of the animation. * - * @return The end action. + * @SINCE_1_0.0 + * @return The end action */ EndAction GetEndAction() const; /** - * @brief Set the disconnect action. + * @brief 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. - * @param[in] disconnectAction The disconnect action. + * @SINCE_1_0.0 + * @param[in] disconnectAction The disconnect action */ void SetDisconnectAction( EndAction disconnectAction ); /** * @brief Returns the disconnect action. * - * @return The disconnect action. + * @SINCE_1_0.0 + * @return The disconnect action */ EndAction GetDisconnectAction() const; /** - * @brief Set the default alpha function for an animation. + * @brief Sets the default alpha function for an animation. * * This is applied to individual property animations, if no further alpha functions are supplied. - * @param[in] alpha The default alpha function. + * @SINCE_1_0.0 + * @param[in] alpha The default alpha function */ void SetDefaultAlphaFunction(AlphaFunction alpha); /** - * @brief Retrieve the default alpha function for an animation. + * @brief Retrieves the default alpha function for an animation. * - * @return The default alpha function. + * @SINCE_1_0.0 + * @return The default alpha function */ AlphaFunction GetDefaultAlphaFunction() const; /* * @brief 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 SetPlayRange ), + * 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] progress The new progress as a normalized value between [0,1] or between the - * play range if specified. + * @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 SetCurrentProgress( float progress ); /** - * @brief Retrieve the current progress of the animation. + * @brief Retrieves the current progress of the animation. * - * @return The current progress as a normalized value between [0,1]. + * @SINCE_1_0.0 + * @return The current progress as a normalized value between [0,1] */ float GetCurrentProgress(); /** - * @brief Specifies an speed factor for the animation. + * @brief 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. * - * @param[in] factor A value which will multiply the velocity. + * @SINCE_1_0.0 + * @param[in] factor A value which will multiply the velocity */ void SetSpeedFactor( float factor ); /** - * @brief Retrieve the speed factor of the animation + * @brief Retrieves the speed factor of the animation. * - * @return speed factor + * @SINCE_1_0.0 + * @return Speed factor */ float GetSpeedFactor() const; /** - * @brief Set the playing range. + * @brief 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_1_0.0 * @param[in] range Two values between [0,1] to specify minimum and maximum progress. The - * animation will play between those values. + * animation will play between those values */ void SetPlayRange( const Vector2& range ); /** - * @brief Get the playing range + * @brief Gets the playing range. * - * @return The play range defined for the animation. + * @SINCE_1_0.0 + * @return The play range defined for the animation */ Vector2 GetPlayRange() const; /** * @brief Play the animation. + * @SINCE_1_0.0 */ void Play(); /** - * @brief 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 SetPlayRange ), + * @brief 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 @ref Animation::SetPlayRange ), * otherwise, it will be ignored. * - * @param[in] progress A value between [0,1], or between the play range if specified, form where the animation should start playing + * @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 PlayFrom( float progress ); /** - * @brief Pause the animation. + * @brief Pauses the animation. + * @SINCE_1_0.0 */ void Pause(); /** - * @brief Stop the animation. + * @brief Queries the state of the animation. + * @SINCE_1_1.21 + * @return The Animation::State + */ + State GetState() const; + + /** + * @brief Stops the animation. + * @SINCE_1_0.0 */ void Stop(); /** - * @brief Clear the animation. + * @brief Clears the animation. * * This disconnects any objects that were being animated, effectively stopping the animation. + * @SINCE_1_0.0 */ void Clear(); /** - * @brief Connect to this signal to be notified when an Animation's animations have finished. + * @brief Connects to this signal to be notified when an Animation's animations have finished. * - * @return A signal object to Connect() with. + * @SINCE_1_0.0 + * @return A signal object to connect with */ - AnimationSignalV2& FinishedSignal(); + AnimationSignalType& FinishedSignal(); /** - * @brief Animate a property value by a relative amount. + * @brief 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. - * @param [in] target The target object/property to animate. - * @param [in] relativeValue The property value will change by this amount. + * @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 AnimateBy(Property target, Property::Value relativeValue); /** - * @brief Animate a property value by a relative amount. + * @brief Animates a property value by a relative amount. * * 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 + * @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 AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha); /** - * @brief Animate a property value by a relative amount. + * @brief Animates a property value by a relative amount. * * 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. + * @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 AnimateBy(Property target, Property::Value relativeValue, TimePeriod period); /** - * @brief Animate a property value by a relative amount. + * @brief Animates a property value by a relative amount. * - * @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 + * @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 AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period); /** - * @brief Animate a property to a destination value. + * @brief Animates a property to a destination value. * * 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. + * @SINCE_1_0.0 + * @param[in] target The target object/property to animate + * @param[in] destinationValue The destination value */ void AnimateTo(Property target, Property::Value destinationValue); /** - * @brief Animate a property to a destination value. + * @brief Animates a property to a destination value. * * 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 + * @param[in] target The target object/property to animate + * @param[in] destinationValue The destination value + * @param[in] alpha The alpha function to apply */ void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha); /** - * @brief Animate a property to a destination value. + * @brief Animates a property to a destination value. * * 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. + * @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 AnimateTo(Property target, Property::Value destinationValue, TimePeriod period); /** - * @brief Animate a property to a destination value. + * @brief Animates a property to a destination value. * - * @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] 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 AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @param [in] target The target object/property to animate. - * @param [in] keyFrames The key frames + * @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 AnimateBetween(Property target, KeyFrames& keyFrames); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @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. + * @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 AnimateBetween(Property target, KeyFrames& keyFrames, Interpolation interpolation); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @param [in] target The target object/property to animate. - * @param [in] keyFrames The key frames - * @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 */ void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @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. + * @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 AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, Interpolation interpolation); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @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] 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 AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @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. + * @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 AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period, Interpolation interpolation); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @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 + * @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 AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period); /** - * @brief Animate a property between keyframes. + * @brief Animates a property between keyframes. * - * @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. + * @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 AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period, Interpolation interpolation); @@ -512,9 +629,12 @@ public: // Actor-specific convenience methods /** - * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied + * @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 @@ -522,616 +642,82 @@ public: void Animate( Actor actor, Path path, const Vector3& forward ); /** - * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied + * @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. + * @param[in] alpha The alpha function to apply */ void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha ); /** - * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied + * @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. + * @param[in] period The effect will occur during this time period */ void Animate( Actor actor, Path path, const Vector3& forward, TimePeriod period ); /** - * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied + * @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. - * @param [in] period The effect will occur during this time period. + * @param[in] alpha The alpha function to apply + * @param[in] period The effect will occur during this time period */ void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha, TimePeriod period); /** - * @brief Move an actor relative to its position. - * - * 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. - * - * 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. - */ - void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Move an actor to a target position. - * - * 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. - */ - void MoveTo(Actor actor, float x, float y, float z); - - /** - * @brief Move an actor to a target position. + * @brief Shows an actor during the animation. * - * 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. - */ - void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha); - - /** - * @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. - */ - void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Rotate an actor around an arbitrary axis. - * - * 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 - */ - void RotateBy(Actor actor, Degree angle, Vector3 axis); - - /** - * @brief Rotate an actor around an arbitrary axis. - * - * 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. - */ - void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha); - - /** - * @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. - */ - void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @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. - */ - void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Rotate an actor to a target orientation. - * - * 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. - */ - void RotateTo(Actor actor, Degree angle, Vector3 axis); - - /** - * @brief Rotate an actor to a target orientation. - * - * 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. - */ - void RotateTo(Actor actor, Radian angle, Vector3 axis); - - /** - * @brief Rotate an actor to a target orientation. - * - * 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. - */ - void RotateTo(Actor actor, Radian 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] 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 Scale an actor. - * - * 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. - */ - void ScaleBy(Actor actor, float x, float y, float z); - - /** - * @brief Scale an actor. - * - * 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. - */ - void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Scale an actor to a target scale factor. - * - * 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. - */ - void ScaleTo(Actor actor, float x, float y, float z); - - /** - * @brief Scale an actor to a target scale factor. - * - * 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. - */ - void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Show an actor during the animation. - * - * @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] actor The actor to animate + * @param[in] delaySeconds The initial delay from the start of the animation */ void Show(Actor actor, float delaySeconds); /** - * @brief Hide an actor during the animation. + * @brief Hides an actor during the animation. * - * @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] actor The actor to animate + * @param[in] delaySeconds The initial delay from the start of the animation */ void Hide(Actor actor, float delaySeconds); - /** - * @brief Animate the opacity of an actor. - * - * 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. - */ - void OpacityBy(Actor actor, float opacity); - - /** - * @brief Animate the opacity of an actor. - * - * 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. - */ - void OpacityBy(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Animate an actor to a target opacity. - * - * 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. - */ - void OpacityTo(Actor actor, float opacity); - - /** - * @brief Animate an actor to a target opacity. - * - * 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. - */ - void OpacityTo(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Animate the color of an actor. - * - * 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. - */ - void ColorBy(Actor actor, Vector4 color); - - /** - * @brief Animate the color of an actor. - * - * 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. - */ - void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha); - - /** - * @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); - - /** - * @brief Animate an actor to a target color. - * - * 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 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. - */ - void Resize(Actor actor, float width, float height); - - /** - * @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. - */ - void Resize(Actor actor, float width, float height, 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. - */ - void Resize(Actor actor, float width, float height, AlphaFunction alpha, float delaySeconds, float durationSeconds); - - /** - * @brief Resize an actor. - * - * 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. - */ - void Resize(Actor actor, Vector3 size); - - /** - * @brief Resize an actor. - * - * 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. - */ - void Resize(Actor actor, Vector3 size, AlphaFunction alpha); - - /** - * @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. - */ - void Resize(Actor actor, Vector3 size, AlphaFunction alpha, float delaySeconds, float durationSeconds); - 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 }; +/** + * @} + */ } // namespace Dali #endif // __DALI_ANIMATION_H__