[dali_1.2.40] Merge branch 'devel/master'
[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) 2017 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  * The overall animation time is superseded by the values given in the TimePeriod structure used when calling the AnimateTo(), AnimateBy(), AnimateBetween() and Animate() methods.
101  * If any of the individual calls to those functions exceeds the overall animation time, then the overall animation time is automatically extended.
102  *
103  * Using AnimateTo and AnimateBy for the same property of the same Actor will yield undefined behaviour especially if the TimePeriod overlaps.
104  *
105  * After calling Animation::Play(), Handle::GetProperty will return the target value of the animated property.
106  *
107  * Signals
108  * | %Signal Name | Method                   |
109  * |--------------|--------------------------|
110  * | finished     | @ref FinishedSignal()    |
111  *
112  * Actions
113  * | %Action Name | %Animation method called |
114  * |--------------|--------------------------|
115  * | play         | Play()                   |
116  * | stop         | Stop()                   |
117  * | pause        | Pause()                  |
118  * @SINCE_1_0.0
119  */
120 class DALI_IMPORT_API Animation : public BaseHandle
121 {
122 public:
123
124   typedef Signal< void (Animation&) > AnimationSignalType; ///< Animation finished signal type @SINCE_1_0.0
125
126   typedef Any AnyFunction; ///< Interpolation function @SINCE_1_0.0
127
128   /**
129    * @brief Enumeration for what to do when the animation ends, is stopped, or is destroyed.
130    * @SINCE_1_0.0
131    */
132   enum EndAction
133   {
134     Bake,     ///< When the animation ends, the animated property values are saved. @SINCE_1_0.0
135     Discard,  ///< When the animation ends, the animated property values are forgotten. @SINCE_1_0.0
136     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
137   };
138
139   /**
140    * @brief Enumeration for what interpolation method to use on key-frame animations.
141    * @SINCE_1_0.0
142    */
143   enum Interpolation
144   {
145     Linear,   ///< Values in between key frames are interpolated using a linear polynomial. (Default) @SINCE_1_0.0
146     Cubic     ///< Values in between key frames are interpolated using a cubic polynomial. @SINCE_1_0.0
147   };
148
149   /**
150    * @brief Enumeration for what state the animation is in.
151    *
152    * Note: Calling Reset() on this class will NOT reset the animation. It will call BaseHandle::Reset() which drops the object handle.
153    *
154    * @SINCE_1_1.21
155    */
156   enum State
157   {
158     STOPPED,   ///< Animation has stopped @SINCE_1_1.21
159     PLAYING,   ///< The animation is playing @SINCE_1_1.21
160     PAUSED     ///< The animation is paused @SINCE_1_1.21
161   };
162
163   /**
164    * @brief Creates an uninitialized Animation; this can be initialized with Animation::New().
165    *
166    * Calling member functions with an uninitialized Animation handle is not allowed.
167    * @SINCE_1_0.0
168    */
169   Animation();
170
171   /**
172    * @brief Creates an initialized Animation.
173    *
174    * The animation will not loop.
175    * The default end action is "Bake".
176    * The default alpha function is linear.
177    * @SINCE_1_0.0
178    * @param[in] durationSeconds The duration in seconds
179    * @return A handle to a newly allocated Dali resource
180    * @note durationSeconds can not be negative.
181    */
182   static Animation New(float durationSeconds);
183
184   /**
185    * @brief Downcasts a handle to Animation handle.
186    *
187    * If handle points to an Animation object, the downcast produces valid handle.
188    * If not, the returned handle is left uninitialized.
189    *
190    * @SINCE_1_0.0
191    * @param[in] handle Handle to an object
192    * @return Handle to an Animation object or an uninitialized handle
193    */
194   static Animation DownCast( BaseHandle handle );
195
196   /**
197    * @brief Destructor.
198    *
199    * This is non-virtual since derived Handle types must not contain data or virtual methods.
200    * @SINCE_1_0.0
201    */
202   ~Animation();
203
204   /**
205    * @brief This copy constructor is required for (smart) pointer semantics.
206    *
207    * @SINCE_1_0.0
208    * @param[in] handle A reference to the copied handle
209    */
210   Animation(const Animation& handle);
211
212   /**
213    * @brief This assignment operator is required for (smart) pointer semantics.
214    *
215    * @SINCE_1_0.0
216    * @param[in] rhs A reference to the copied handle
217    * @return A reference to this
218    */
219   Animation& operator=(const Animation& rhs);
220
221   /**
222    * @brief Sets the duration of an animation.
223    *
224    * @SINCE_1_0.0
225    * @param[in] seconds The duration in seconds
226    * @pre DurationSeconds must be greater than zero.
227    */
228   void SetDuration(float seconds);
229
230   /**
231    * @brief Retrieves the duration of an animation.
232    *
233    * @SINCE_1_0.0
234    * @return The duration in seconds
235    */
236   float GetDuration() const;
237
238   /**
239    * @brief Sets whether the animation will loop.
240    *
241    * This function resets the loop count and should not be used with SetLoopCount(int).
242    * Setting this parameter does not cause the animation to Play().
243    *
244    * @SINCE_1_0.0
245    * @param[in] looping True if the animation will loop
246    */
247   void SetLooping(bool looping);
248
249   /**
250    * @brief Enables looping for 'count' repeats.
251    *
252    * A zero is the same as SetLooping(true) i.e. repeat forever.
253    * If Play() Stop() or 'count' loops is reached, the loop counter will reset.
254    * Setting this parameter does not cause the animation to Play().
255    *
256    * @SINCE_1_1.20
257    * @param[in] count The number of times to loop
258    */
259   void SetLoopCount(int count);
260
261   /**
262    * @brief Gets the loop count.
263    *
264    * A zero is the same as SetLooping(true) ie repeat forever.
265    * The loop count is initially 1 for play once.
266    *
267    * @SINCE_1_1.20
268    * @return The number of times to loop
269    */
270   int GetLoopCount();
271
272   /**
273    * @brief Gets the current loop count.
274    *
275    * A value 0 to GetLoopCount() indicating the current loop count when looping.
276    *
277    * @SINCE_1_1.20
278    * @return The current number of loops that have occured
279    */
280   int GetCurrentLoop();
281
282   /**
283    * @brief Queries whether the animation will loop.
284    *
285    * @SINCE_1_0.0
286    * @return True if the animation will loop
287    */
288   bool IsLooping() const;
289
290   /**
291    * @brief Sets the end action of the animation.
292    *
293    * This action is performed when the animation ends or if it is stopped.
294    * Default end action is bake.
295    * @SINCE_1_0.0
296    * @param[in] action The end action
297    */
298   void SetEndAction(EndAction action);
299
300   /**
301    * @brief Returns the end action of the animation.
302    *
303    * @SINCE_1_0.0
304    * @return The end action
305    */
306   EndAction GetEndAction() const;
307
308   /**
309    * @brief Sets the disconnect action.
310    *
311    * If any of the animated property owners are disconnected from the stage while the animation is being played, then this action is performed.
312    * Default action is to BakeFinal.
313    * @SINCE_1_0.0
314    * @param[in] disconnectAction The disconnect action
315    */
316   void SetDisconnectAction( EndAction disconnectAction );
317
318   /**
319    * @brief Returns the disconnect action.
320    *
321    * @SINCE_1_0.0
322    * @return The disconnect action
323    */
324   EndAction GetDisconnectAction() const;
325
326   /**
327    * @brief Sets the default alpha function for an animation.
328    *
329    * This is applied to individual property animations, if no further alpha functions are supplied.
330    * @SINCE_1_0.0
331    * @param[in] alpha The default alpha function
332    */
333   void SetDefaultAlphaFunction(AlphaFunction alpha);
334
335   /**
336    * @brief Retrieves the default alpha function for an animation.
337    *
338    * @SINCE_1_0.0
339    * @return The default alpha function
340    */
341   AlphaFunction GetDefaultAlphaFunction() const;
342
343   /*
344    * @brief Sets the progress of the animation.
345    *
346    * The animation will play (or continue playing) from this point. The progress
347    * must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ),
348    * otherwise, it will be ignored.
349    *
350    * @SINCE_1_0.0
351    * @param[in] progress The new progress as a normalized value between [0,1]
352    * or between the play range if specified
353    */
354   void SetCurrentProgress( float progress );
355
356   /**
357   * @brief Retrieves the current progress of the animation.
358   *
359   * @SINCE_1_0.0
360   * @return The current progress as a normalized value between [0,1]
361   */
362   float GetCurrentProgress();
363
364   /**
365    * @brief Specifies a speed factor for the animation.
366    *
367    * The speed factor is a multiplier of the normal velocity of the animation. Values between [0,1] will
368    * slow down the animation and values above one will speed up the animation. It is also possible to specify a negative multiplier
369    * to play the animation in reverse.
370    *
371    * @SINCE_1_0.0
372    * @param[in] factor A value which will multiply the velocity
373    */
374   void SetSpeedFactor( float factor );
375
376   /**
377    * @brief Retrieves the speed factor of the animation.
378    *
379    * @SINCE_1_0.0
380    * @return Speed factor
381    */
382   float GetSpeedFactor() const;
383
384   /**
385    * @brief Sets the playing range.
386    *
387    * Animation will play between the values specified. Both values ( range.x and range.y ) should be between 0-1,
388    * otherwise they will be ignored. If the range provided is not in proper order ( minimum,maximum ), it will be reordered.
389    *
390    * @SINCE_1_0.0
391    * @param[in] range Two values between [0,1] to specify minimum and maximum progress. The
392    * animation will play between those values
393    */
394   void SetPlayRange( const Vector2& range );
395
396   /**
397    * @brief Gets the playing range.
398    *
399    * @SINCE_1_0.0
400    * @return The play range defined for the animation
401    */
402   Vector2 GetPlayRange() const;
403
404   /**
405    * @brief Play the animation.
406    * @SINCE_1_0.0
407    */
408   void Play();
409
410   /**
411    * @brief Plays the animation from a given point.
412    *
413    * The progress must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ),
414    * otherwise, it will be ignored.
415    *
416    * @SINCE_1_0.0
417    * @param[in] progress A value between [0,1], or between the play range if specified, from where the animation should start playing
418    */
419   void PlayFrom( float progress );
420
421   /**
422    * @brief Pauses the animation.
423    * @SINCE_1_0.0
424    */
425   void Pause();
426
427   /**
428    * @brief Queries the state of the animation.
429    * @SINCE_1_1.21
430    * @return The Animation::State
431    */
432   State GetState() const;
433
434   /**
435    * @brief Stops the animation.
436    * @SINCE_1_0.0
437    */
438   void Stop();
439
440   /**
441    * @brief Clears the animation.
442    *
443    * This disconnects any objects that were being animated, effectively stopping the animation.
444    * @SINCE_1_0.0
445    */
446   void Clear();
447
448   /**
449    * @brief Connects to this signal to be notified when an Animation's animations have finished.
450    *
451    * @SINCE_1_0.0
452    * @return A signal object to connect with
453    */
454   AnimationSignalType& FinishedSignal();
455
456   /**
457    * @brief Animates a property value by a relative amount.
458    *
459    * The default alpha function will be used.
460    * The effect will start & end when the animation begins & ends.
461    * @SINCE_1_0.0
462    * @param[in] target The target object/property to animate
463    * @param[in] relativeValue The property value will change by this amount
464    */
465   void AnimateBy(Property target, Property::Value relativeValue);
466
467   /**
468    * @brief Animates a property value by a relative amount.
469    *
470    * The effect will start & end when the animation begins & ends.
471    * @SINCE_1_0.0
472    * @param[in] target The target object/property to animate
473    * @param[in] relativeValue The property value will change by this amount
474    * @param[in] alpha The alpha function to apply
475    */
476   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha);
477
478   /**
479    * @brief Animates a property value by a relative amount.
480    *
481    * The default alpha function will be used.
482    * @SINCE_1_0.0
483    * @param[in] target The target object/property to animate
484    * @param[in] relativeValue The property value will increase/decrease by this amount
485    * @param[in] period The effect will occur during this time period
486    */
487   void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period);
488
489   /**
490    * @brief Animates a property value by a relative amount.
491    *
492    * @SINCE_1_0.0
493    * @param[in] target The target object/property to animate
494    * @param[in] relativeValue The property value will increase/decrease by this amount
495    * @param[in] alpha The alpha function to apply
496    * @param[in] period The effect will occur during this time period
497    */
498   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period);
499
500   /**
501    * @brief Animates a property to a destination value.
502    *
503    * The default alpha function will be used.
504    * The effect will start & end when the animation begins & ends.
505    * @SINCE_1_0.0
506    * @param[in] target The target object/property to animate
507    * @param[in] destinationValue The destination value
508    */
509   void AnimateTo(Property target, Property::Value destinationValue);
510
511   /**
512    * @brief Animates a property to a destination value.
513    *
514    * The effect will start & end when the animation begins & ends.
515    * @SINCE_1_0.0
516    * @param[in] target The target object/property to animate
517    * @param[in] destinationValue The destination value
518    * @param[in] alpha The alpha function to apply
519    */
520   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha);
521
522   /**
523    * @brief Animates a property to a destination value.
524    *
525    * The default alpha function will be used.
526    * @SINCE_1_0.0
527    * @param[in] target The target object/property to animate
528    * @param[in] destinationValue The destination value
529    * @param[in] period The effect will occur during this time period
530    */
531   void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period);
532
533   /**
534    * @brief Animates a property to a destination value.
535    *
536    * @SINCE_1_0.0
537    * @param[in] target The target object/property to animate
538    * @param[in] destinationValue The destination value
539    * @param[in] alpha The alpha function to apply
540    * @param[in] period The effect will occur during this time period
541    */
542   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period);
543
544    /**
545    * @brief Animates a property between keyframes.
546    *
547    * @SINCE_1_0.0
548    * @param[in] target The target object property to animate
549    * @param[in] keyFrames The set of time/value pairs between which to animate
550    */
551   void AnimateBetween(Property target, KeyFrames& keyFrames);
552
553   /**
554    * @brief Animates a property between keyframes.
555    *
556    * @SINCE_1_0.0
557    * @param[in] target The target object property to animate
558    * @param[in] keyFrames The set of time/value pairs between which to animate
559    * @param[in] interpolation The method used to interpolate between values
560    */
561   void AnimateBetween(Property target, KeyFrames& keyFrames, Interpolation interpolation);
562
563   /**
564    * @brief Animates a property between keyframes.
565    *
566    * @SINCE_1_0.0
567    * @param[in] target The target object property to animate
568    * @param[in] keyFrames The set of time/value pairs between which to animate
569    * @param[in] alpha The alpha function to apply
570    */
571   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha);
572
573   /**
574    * @brief Animates a property between keyframes.
575    *
576    * @SINCE_1_0.0
577    * @param[in] target The target object property to animate
578    * @param[in] keyFrames The set of time/value pairs between which to animate
579    * @param[in] alpha The alpha function to apply
580    * @param[in] interpolation The method used to interpolate between values
581    */
582   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, Interpolation interpolation);
583
584   /**
585    * @brief Animates a property between keyframes.
586    *
587    * @SINCE_1_0.0
588    * @param[in] target The target object property to animate
589    * @param[in] keyFrames The set of time/value pairs between which to animate
590    * @param[in] period The effect will occur during this time period
591    */
592   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period);
593
594   /**
595    * @brief Animates a property between keyframes.
596    *
597    * @SINCE_1_0.0
598    * @param[in] target The target object property to animate
599    * @param[in] keyFrames The set of time/value pairs between which to animate
600    * @param[in] period The effect will occur duing this time period
601    * @param[in] interpolation The method used to interpolate between values
602    */
603   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period, Interpolation interpolation);
604
605   /**
606    * @brief Animates a property between keyframes.
607    *
608    * @SINCE_1_0.0
609    * @param[in] target The target object property to animate
610    * @param[in] keyFrames The set of time/value pairs between which to animate
611    * @param[in] alpha The alpha function to apply
612    * @param[in] period The effect will occur during this time period
613    */
614   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period);
615
616   /**
617    * @brief Animates a property between keyframes.
618    *
619    * @SINCE_1_0.0
620    * @param[in] target The target object property to animate
621    * @param[in] keyFrames The set of time/value pairs between which to animate
622    * @param[in] alpha The alpha function to apply to the overall progress
623    * @param[in] period The effect will occur duing this time period
624    * @param[in] interpolation The method used to interpolate between values
625    */
626   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period, Interpolation interpolation);
627
628
629   // Actor-specific convenience methods
630
631   /**
632    * @brief Animates an actor's position and orientation through a predefined path.
633    *
634    * The actor will rotate to orient the supplied
635    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
636    *
637    * @SINCE_1_0.0
638    * @param[in] actor The actor to animate
639    * @param[in] path The path. It defines position and orientation
640    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
641    */
642   void Animate( Actor actor, Path path, const Vector3& forward );
643
644   /**
645    * @brief Animates 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    */
656   void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha );
657
658   /**
659    * @brief Animates an actor's position and orientation through a predefined path.
660    *
661    * The actor will rotate to orient the supplied
662    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
663    *
664    * @SINCE_1_0.0
665    * @param[in] actor The actor to animate
666    * @param[in] path The path. It defines position and orientation
667    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
668    * @param[in] period The effect will occur during this time period
669    */
670   void Animate( Actor actor, Path path, const Vector3& forward, TimePeriod period );
671
672   /**
673    * @brief Animates an actor's position and orientation through a predefined path.
674    *
675    * The actor will rotate to orient the supplied
676    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
677    *
678    * @SINCE_1_0.0
679    * @param[in] actor The actor to animate
680    * @param[in] path The path. It defines position and orientation
681    * @param[in] forward The vector (in local space coordinate system) that will be oriented with the path's tangent direction
682    * @param[in] alpha The alpha function to apply
683    * @param[in] period The effect will occur during this time period
684    */
685   void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha, TimePeriod period);
686
687   /**
688    * @brief Shows an actor during the animation.
689    *
690    * @SINCE_1_0.0
691    * @param[in] actor The actor to animate
692    * @param[in] delaySeconds The initial delay from the start of the animation
693    */
694   void Show(Actor actor, float delaySeconds);
695
696   /**
697    * @brief Hides an actor during the animation.
698    *
699    * @SINCE_1_0.0
700    * @param[in] actor The actor to animate
701    * @param[in] delaySeconds The initial delay from the start of the animation
702    */
703   void Hide(Actor actor, float delaySeconds);
704
705 public: // Not intended for use by Application developers
706
707   /// @cond internal
708   /**
709    * @brief This constructor is used by Animation::New() methods.
710    * @SINCE_1_0.0
711    * @param[in] animation A pointer to a newly allocated Dali resource
712    */
713   explicit DALI_INTERNAL Animation(Internal::Animation* animation);
714   /// @endcond
715
716 };
717
718 /**
719  * @}
720  */
721 } // namespace Dali
722
723 #endif // __DALI_ANIMATION_H__