Update Animation's public header comments
[platform/core/uifw/dali-core.git] / dali / public-api / animation / animation.h
1 #ifndef __DALI_ANIMATION_H__
2 #define __DALI_ANIMATION_H__
3
4 /*
5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  */
20
21 // INTERNAL INCLUDES
22 #include <dali/public-api/animation/alpha-function.h>
23 #include <dali/public-api/animation/key-frames.h>
24 #include <dali/public-api/animation/path.h>
25 #include <dali/public-api/animation/time-period.h>
26 #include <dali/public-api/object/any.h>
27 #include <dali/public-api/object/handle.h>
28 #include <dali/public-api/object/property.h>
29 #include <dali/public-api/signals/dali-signal.h>
30
31 namespace Dali
32 {
33 /**
34  * @addtogroup dali_core_animation
35  * @{
36  */
37
38 class Actor;
39 struct Property;
40 struct Vector2;
41 struct Vector3;
42
43 namespace Internal DALI_INTERNAL
44 {
45 class Animation;
46 }
47
48 /**
49  * @brief Dali::Animation can be used to animate the properties of any number of objects, typically Actors.
50  *
51  * An example animation setup is shown below:
52  *
53  * @code
54  *
55  * struct MyProgram
56  * {
57  *   Actor mActor; // The object we wish to animate
58  *   Animation mAnimation; // Keep this to control the animation
59  * }
60  *
61  * // ...To play the animation
62  *
63  * mAnimation = Animation::New(3.0f); // duration 3 seconds
64  * mAnimation.AnimateTo(Property(mActor, Actor::Property::POSITION), Vector3(10.0f, 50.0f, 0.0f));
65  * mAnimation.Play();
66  *
67  * @endcode
68  *
69  * Dali::Animation supports "fire and forget" behaviour i.e. an animation continues to play if the handle is discarded.
70  * Note that in the following example, the "Finish" signal will be emitted:
71  *
72  * @code
73  *
74  * void ExampleCallback( Animation& source )
75  * {
76  *   std::cout << "Animation has finished" << std::endl;
77  * }
78  *
79  * void ExampleAnimation( Actor actor )
80  * {
81  *   Animation animation = Animation::New(2.0f); // duration 2 seconds
82  *   animation.AnimateTo(Property(actor, Actor::Property::POSITION), 10.0f, 50.0f, 0.0f);
83  *   animation.FinishedSignal().Connect( ExampleCallback );
84  *   animation.Play();
85  * } // At this point the animation handle has gone out of scope
86  *
87  * Actor actor = Actor::New();
88  * Stage::GetCurrent().Add( actor );
89  *
90  * // Fire animation and forget about it
91  * ExampleAnimation( actor );
92  *
93  * // However the animation will continue, and "Animation has finished" will be printed after 2 seconds.
94  *
95  * @endcode
96  *
97  * If the "Finish" signal is connected to a member function of an object, it must be disconnected before the object is destroyed.
98  * This is typically done in the object destructor, and requires either the Dali::Connection object or Dali::Animation handle to be stored.
99  *
100  * Signals
101  * | %Signal Name | Method                   |
102  * |--------------|--------------------------|
103  * | finished     | @ref FinishedSignal()    |
104  *
105  * Actions
106  * | %Action Name | %Animation method called |
107  * |--------------|--------------------------|
108  * | play         | Play()                   |
109  * | stop         | Stop()                   |
110  * | pause        | Pause()                  |
111  * @SINCE_1_0.0
112  */
113 class DALI_IMPORT_API Animation : public BaseHandle
114 {
115 public:
116
117   typedef Signal< void (Animation&) > AnimationSignalType; ///< Animation finished signal type @SINCE_1_0.0
118
119   typedef Any AnyFunction; ///< Interpolation function @SINCE_1_0.0
120
121   /**
122    * @brief What to do when the animation ends, is stopped or is destroyed
123    * @SINCE_1_0.0
124    */
125   enum EndAction
126   {
127     Bake,     ///< When the animation ends, the animated property values are saved. @SINCE_1_0.0
128     Discard,  ///< When the animation ends, the animated property values are forgotten. @SINCE_1_0.0
129     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
130   };
131
132   /**
133    * @brief What interpolation method to use on key-frame animations
134    * @SINCE_1_0.0
135    */
136   enum Interpolation
137   {
138     Linear,   ///< Values in between key frames are interpolated using a linear polynomial. (Default) @SINCE_1_0.0
139     Cubic     ///< Values in between key frames are interpolated using a cubic polynomial. @SINCE_1_0.0
140   };
141
142   /**
143    * @brief Create an uninitialized Animation; this can be initialized with Animation::New().
144    *
145    * Calling member functions with an uninitialized Animation handle is not allowed.
146    * @SINCE_1_0.0
147    */
148   Animation();
149
150   /**
151    * @brief Create an initialized Animation.
152    *
153    * The animation will not loop.
154    * The default end action is "Bake".
155    * The default alpha function is linear.
156    * @SINCE_1_0.0
157    * @param [in] durationSeconds The duration in seconds.
158    * @return A handle to a newly allocated Dali resource.
159    * @pre DurationSeconds must be greater than zero.
160    */
161   static Animation New(float durationSeconds);
162
163   /**
164    * @brief Downcast a handle to Animation handle.
165    *
166    * If handle points to an Animation object the downcast produces
167    * valid handle. If not the returned handle is left uninitialized.
168    *
169    * @SINCE_1_0.0
170    * @param[in] handle Handle to an object
171    * @return Handle to a Animation object or an uninitialized handle
172    */
173   static Animation DownCast( BaseHandle handle );
174
175   /**
176    * @brief Destructor
177    *
178    * This is non-virtual since derived Handle types must not contain data or virtual methods.
179    * @SINCE_1_0.0
180    */
181   ~Animation();
182
183   /**
184    * @brief This copy constructor is required for (smart) pointer semantics.
185    *
186    * @SINCE_1_0.0
187    * @param [in] handle A reference to the copied handle
188    */
189   Animation(const Animation& handle);
190
191   /**
192    * @brief This assignment operator is required for (smart) pointer semantics.
193    *
194    * @SINCE_1_0.0
195    * @param [in] rhs  A reference to the copied handle
196    * @return A reference to this
197    */
198   Animation& operator=(const Animation& rhs);
199
200   /**
201    * @brief Set the duration of an animation.
202    *
203    * @SINCE_1_0.0
204    * @param[in] seconds The duration in seconds.
205    * @pre DurationSeconds must be greater than zero.
206    */
207   void SetDuration(float seconds);
208
209   /**
210    * @brief Retrieve the duration of an animation.
211    *
212    * @SINCE_1_0.0
213    * @return The duration in seconds.
214    */
215   float GetDuration() const;
216
217   /**
218    * @brief Set whether the animation will loop.
219    *
220    * This function resets the loop count and should not be used with SetLoopCount(int).
221    * Setting this parameter does not cause the animation to Play()
222    *
223    * @SINCE_1_0.0
224    * @param[in] looping True if the animation will loop.
225    */
226   void SetLooping(bool looping);
227
228   /**
229    * @brief Enable looping for 'count' repeats.
230    *
231    * A zero is the same as SetLooping(true) ie repeat forever.
232    * If Play() Stop() or 'count' loops is reached, the loop counter will reset.
233    * Setting this parameter does not cause the animation to Play()
234    *
235    * @SINCE_1_1.20
236    * @param[in] count The number of times to loop.
237    */
238   void SetLoopCount(int count);
239
240   /**
241    * @brief Get the loop count.
242    *
243    * A zero is the same as SetLooping(true) ie repeat forever.
244    * The loop count is initially 1 for play once.
245    *
246    * @SINCE_1_1.20
247    * @return The number of times to loop.
248    */
249   int GetLoopCount();
250
251   /**
252    * @brief Get the current loop count.
253    *
254    * A value 0 to GetLoopCount() indicating the current loop count when looping.
255    *
256    * @SINCE_1_1.20
257    * @return The current number of loops that have occured.
258    */
259   int GetCurrentLoop();
260
261   /**
262    * @brief Query whether the animation will loop.
263    *
264    * @SINCE_1_0.0
265    * @return True if the animation will loop.
266    */
267   bool IsLooping() const;
268
269   /**
270    * @brief Set the end action of the animation.
271    *
272    * This action is performed when the animation ends or if it is stopped.
273    * Default end action is bake
274    * @SINCE_1_0.0
275    * @param[in] action The end action.
276    */
277   void SetEndAction(EndAction action);
278
279   /**
280    * @brief Returns the end action of the animation.
281    *
282    * @SINCE_1_0.0
283    * @return The end action.
284    */
285   EndAction GetEndAction() const;
286
287   /**
288    * @brief Set the disconnect action.
289    *
290    * If any of the animated property owners are disconnected from the stage while the animation is being played, then this action is performed.
291    * Default action is to BakeFinal.
292    * @SINCE_1_0.0
293    * @param[in] disconnectAction The disconnect action.
294    */
295   void SetDisconnectAction( EndAction disconnectAction );
296
297   /**
298    * @brief Returns the disconnect action.
299    *
300    * @SINCE_1_0.0
301    * @return The disconnect action.
302    */
303   EndAction GetDisconnectAction() const;
304
305   /**
306    * @brief Set the default alpha function for an animation.
307    *
308    * This is applied to individual property animations, if no further alpha functions are supplied.
309    * @SINCE_1_0.0
310    * @param[in] alpha The default alpha function.
311    */
312   void SetDefaultAlphaFunction(AlphaFunction alpha);
313
314   /**
315    * @brief Retrieve the default alpha function for an animation.
316    *
317    * @SINCE_1_0.0
318    * @return The default alpha function.
319    */
320   AlphaFunction GetDefaultAlphaFunction() const;
321
322   /*
323    * @brief Sets the progress of the animation.
324    *
325    * The animation will play (or continue playing) from this point. The progress
326    * must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ),
327    * otherwise, it will be ignored.
328    *
329    * @SINCE_1_0.0
330    * @param[in] progress The new progress as a normalized value between [0,1]
331    * or between the play range if specified.
332    */
333   void SetCurrentProgress( float progress );
334
335   /**
336   * @brief Retrieve the current progress of the animation.
337   *
338   * @SINCE_1_0.0
339   * @return The current progress as a normalized value between [0,1].
340   */
341   float GetCurrentProgress();
342
343   /**
344    * @brief Specifies an speed factor for the animation.
345    *
346    * The speed factor is a multiplier of the normal velocity of the animation. Values between [0,1] will
347    * slow down the animation and values above one will speed up the animation. It is also possible to specify a negative multiplier
348    * to play the animation in reverse.
349    *
350    * @SINCE_1_0.0
351    * @param[in] factor A value which will multiply the velocity.
352    */
353   void SetSpeedFactor( float factor );
354
355   /**
356    * @brief Retrieve the speed factor of the animation
357    *
358    * @SINCE_1_0.0
359    * @return Speed factor
360    */
361   float GetSpeedFactor() const;
362
363   /**
364    * @brief Set the playing range.
365    *
366    * Animation will play between the values specified. Both values ( range.x and range.y ) should be between 0-1,
367    * otherwise they will be ignored. If the range provided is not in proper order ( minimum,maximum ), it will be reordered.
368    *
369    * @SINCE_1_0.0
370    * @param[in] range Two values between [0,1] to specify minimum and maximum progress. The
371    * animation will play between those values.
372    */
373   void SetPlayRange( const Vector2& range );
374
375   /**
376    * @brief Get the playing range
377    *
378    * @SINCE_1_0.0
379    * @return The play range defined for the animation.
380    */
381   Vector2 GetPlayRange() const;
382
383   /**
384    * @brief Play the animation.
385    * @SINCE_1_0.0
386    */
387   void Play();
388
389   /**
390    * @brief Play the animation from a given point.
391    *
392    * The progress must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ),
393    * otherwise, it will be ignored.
394    *
395    * @SINCE_1_0.0
396    * @param[in] progress A value between [0,1], or between the play range if specified, form where the animation should start playing
397    */
398   void PlayFrom( float progress );
399
400   /**
401    * @brief Pause the animation.
402    * @SINCE_1_0.0
403    */
404   void Pause();
405
406   /**
407    * @brief Stop the animation.
408    * @SINCE_1_0.0
409    */
410   void Stop();
411
412   /**
413    * @brief Clear the animation.
414    *
415    * This disconnects any objects that were being animated, effectively stopping the animation.
416    * @SINCE_1_0.0
417    */
418   void Clear();
419
420   /**
421    * @brief Connect to this signal to be notified when an Animation's animations have finished.
422    *
423    * @SINCE_1_0.0
424    * @return A signal object to @ref Signal::Connect() with.
425    */
426   AnimationSignalType& FinishedSignal();
427
428   /**
429    * @brief Animate a property value by a relative amount.
430    *
431    * The default alpha function will be used.
432    * The effect will start & end when the animation begins & ends.
433    * @SINCE_1_0.0
434    * @param [in] target The target object/property to animate.
435    * @param [in] relativeValue The property value will change by this amount.
436    */
437   void AnimateBy(Property target, Property::Value relativeValue);
438
439   /**
440    * @brief Animate a property value by a relative amount.
441    *
442    * The effect will start & end when the animation begins & ends.
443    * @SINCE_1_0.0
444    * @param [in] target The target object/property to animate.
445    * @param [in] relativeValue The property value will change by this amount.
446    * @param [in] alpha The alpha function to apply.
447    */
448   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha);
449
450   /**
451    * @brief Animate a property value by a relative amount.
452    *
453    * The default alpha function will be used.
454    * @SINCE_1_0.0
455    * @param [in] target The target object/property to animate.
456    * @param [in] relativeValue The property value will increase/decrease by this amount.
457    * @param [in] period The effect will occur during this time period.
458    */
459   void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period);
460
461   /**
462    * @brief Animate a property value by a relative amount.
463    *
464    * @SINCE_1_0.0
465    * @param [in] target The target object/property to animate.
466    * @param [in] relativeValue The property value will increase/decrease by this amount.
467    * @param [in] alpha The alpha function to apply.
468    * @param [in] period The effect will occur during this time period.
469    */
470   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period);
471
472   /**
473    * @brief Animate a property to a destination value.
474    *
475    * The default alpha function will be used.
476    * The effect will start & end when the animation begins & ends.
477    * @SINCE_1_0.0
478    * @param [in] target The target object/property to animate.
479    * @param [in] destinationValue The destination value.
480    */
481   void AnimateTo(Property target, Property::Value destinationValue);
482
483   /**
484    * @brief Animate a property to a destination value.
485    *
486    * The effect will start & end when the animation begins & ends.
487    * @SINCE_1_0.0
488    * @param [in] target The target object/property to animate.
489    * @param [in] destinationValue The destination value.
490    * @param [in] alpha The alpha function to apply.
491    */
492   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha);
493
494   /**
495    * @brief Animate a property to a destination value.
496    *
497    * The default alpha function will be used.
498    * @SINCE_1_0.0
499    * @param [in] target The target object/property to animate.
500    * @param [in] destinationValue The destination value.
501    * @param [in] period The effect will occur during this time period.
502    */
503   void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period);
504
505   /**
506    * @brief Animate a property to a destination value.
507    *
508    * @SINCE_1_0.0
509    * @param [in] target The target object/property to animate.
510    * @param [in] destinationValue The destination value.
511    * @param [in] alpha The alpha function to apply.
512    * @param [in] period The effect will occur during this time period.
513    */
514   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period);
515
516    /**
517    * @brief Animate a property between keyframes.
518    *
519    * @SINCE_1_0.0
520    * @param [in] target The target object property to animate.
521    * @param [in] keyFrames The set of time/value pairs between which to animate.
522    */
523   void AnimateBetween(Property target, KeyFrames& keyFrames);
524
525   /**
526    * @brief Animate a property between keyframes.
527    *
528    * @SINCE_1_0.0
529    * @param [in] target The target object property to animate
530    * @param [in] keyFrames The set of time/value pairs between which to animate.
531    * @param [in] interpolation The method used to interpolate between values.
532    */
533   void AnimateBetween(Property target, KeyFrames& keyFrames, Interpolation interpolation);
534
535   /**
536    * @brief Animate a property between keyframes.
537    *
538    * @SINCE_1_0.0
539    * @param [in] target The target object property to animate.
540    * @param [in] keyFrames The set of time/value pairs between which to animate.
541    * @param [in] alpha The alpha function to apply.
542    */
543   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha);
544
545   /**
546    * @brief Animate a property between keyframes.
547    *
548    * @SINCE_1_0.0
549    * @param [in] target The target object property to animate
550    * @param [in] keyFrames The set of time/value pairs between which to animate.
551    * @param [in] alpha The alpha function to apply.
552    * @param [in] interpolation The method used to interpolate between values.
553    */
554   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, Interpolation interpolation);
555
556   /**
557    * @brief Animate a property between keyframes.
558    *
559    * @SINCE_1_0.0
560    * @param [in] target The target object property to animate.
561    * @param [in] keyFrames The set of time/value pairs between which to animate.
562    * @param [in] period The effect will occur during this time period.
563    */
564   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period);
565
566   /**
567    * @brief Animate a property between keyframes.
568    *
569    * @SINCE_1_0.0
570    * @param [in] target The target object property to animate
571    * @param [in] keyFrames The set of time/value pairs between which to animate.
572    * @param [in] period The effect will occur duing this time period.
573    * @param [in] interpolation The method used to interpolate between values.
574    */
575   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period, Interpolation interpolation);
576
577   /**
578    * @brief Animate a property between keyframes.
579    *
580    * @SINCE_1_0.0
581    * @param [in] target The target object property to animate.
582    * @param [in] keyFrames The set of time/value pairs between which to animate.
583    * @param [in] alpha The alpha function to apply.
584    * @param [in] period The effect will occur during this time period.
585    */
586   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period);
587
588   /**
589    * @brief Animate a property between keyframes.
590    *
591    * @SINCE_1_0.0
592    * @param [in] target The target object property to animate
593    * @param [in] keyFrames The set of time/value pairs between which to animate.
594    * @param [in] alpha The alpha function to apply to the overall progress.
595    * @param [in] period The effect will occur duing this time period.
596    * @param [in] interpolation The method used to interpolate between values.
597    */
598   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period, Interpolation interpolation);
599
600
601   // Actor-specific convenience methods
602
603   /**
604    * @brief Animate an actor's position and orientation through a predefined path.
605    *
606    * The actor will rotate to orient the supplied
607    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
608    *
609    * @SINCE_1_0.0
610    * @param[in] actor The actor to animate
611    * @param[in] path The path. It defines position and orientation
612    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
613    */
614   void Animate( Actor actor, Path path, const Vector3& forward );
615
616   /**
617    * @brief Animate an actor's position and orientation through a predefined path.
618    *
619    * The actor will rotate to orient the supplied
620    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
621    *
622    * @SINCE_1_0.0
623    * @param[in] actor The actor to animate
624    * @param[in] path The path. It defines position and orientation
625    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
626    * @param [in] alpha The alpha function to apply.
627    */
628   void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha );
629
630   /**
631    * @brief Animate an actor's position and orientation through a predefined path.
632    *
633    * The actor will rotate to orient the supplied
634    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
635    *
636    * @SINCE_1_0.0
637    * @param[in] actor The actor to animate
638    * @param[in] path The path. It defines position and orientation
639    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
640    * @param [in] period The effect will occur during this time period.
641    */
642   void Animate( Actor actor, Path path, const Vector3& forward, TimePeriod period );
643
644   /**
645    * @brief Animate an actor's position and orientation through a predefined path.
646    *
647    * The actor will rotate to orient the supplied
648    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
649    *
650    * @SINCE_1_0.0
651    * @param[in] actor The actor to animate
652    * @param[in] path The path. It defines position and orientation
653    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
654    * @param [in] alpha The alpha function to apply.
655    * @param [in] period The effect will occur during this time period.
656    */
657   void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha, TimePeriod period);
658
659   /**
660    * @brief Show an actor during the animation.
661    *
662    * @SINCE_1_0.0
663    * @param [in] actor The actor to animate.
664    * @param [in] delaySeconds The initial delay from the start of the animation.
665    */
666   void Show(Actor actor, float delaySeconds);
667
668   /**
669    * @brief Hide an actor during the animation.
670    *
671    * @SINCE_1_0.0
672    * @param [in] actor The actor to animate.
673    * @param [in] delaySeconds The initial delay from the start of the animation.
674    */
675   void Hide(Actor actor, float delaySeconds);
676
677 public: // Not intended for use by Application developers
678
679   /**
680    * @brief This constructor is used by Animation::New() methods
681    * @SINCE_1_0.0
682    * @param [in] animation A pointer to a newly allocated Dali resource
683    */
684   explicit DALI_INTERNAL Animation(Internal::Animation* animation);
685
686 };
687
688 /**
689  * @}
690  */
691 } // namespace Dali
692
693 #endif // __DALI_ANIMATION_H__