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