inc/FUiAnimVisualElementAnimation.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiAnimVisualElementAnimation.h
  20  * @brief       This is the header file for the %VisualElementAnimation class.
  21  *
  22  * This header file contains the declarations of the %VisualElementAnimation class.
  23  */
  24
  25 #ifndef _FUI_ANIM_VISUAL_ELEMENT_ANIMATION_H_
  26 #define _FUI_ANIM_VISUAL_ELEMENT_ANIMATION_H_
  27
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace Ui { namespace Animations
  31 {
  32
  33
  34 class IVisualElementAnimationStatusEventListener;
  35 class IVisualElementAnimationTimingFunction;
  36 class IVisualElementAnimationValueInterpolator;
  37 class _VisualElementAnimationImpl;
  38
  39 /**
  40  * @class       VisualElementAnimation
  41  * @brief       This class is the base class for all the %VisualElementAnimation classes.
  42  *
  43  * @since       2.0
  44  *
  45  * The %VisualElementAnimation class defines the basic animation properties, such as the interpolator to be used,
  46  * the duration of the animation in milliseconds, the delay before the animation is started in milliseconds, and the repeat count.
  47  *
  48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/visual_element_animations.htm">Visual Element Animations</a>.
  49  *
  50  */
  51 class _OSP_EXPORT_ VisualElementAnimation
  52         : public Tizen::Base::Object
  53 {
  54 public:
  55
  56         /**
  57          * This is the default constructor for this class.
  58          *
  59          * @since       2.0
  60          *
  61          * @exception   E_SUCCESS               The method is successful.
  62          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
  63          * @remarks             The specific error code can be accessed using the GetLastResult() method.
  64          */
  65         VisualElementAnimation(void);
  66
  67
  68         /**
  69          * This is the destructor for this class.
  70          *
  71          * @since       2.0
  72          */
  73         virtual ~VisualElementAnimation(void);
  74
  75
  76         /**
  77          * This is the copy constructor for the %VisualElementAnimation class.
  78          *
  79          * @since       2.0
  80          *
  81          * @param[in]   animation       An instance of %VisualElementAnimation
  82          * @exception   E_SUCCESS               The method is successful.
  83          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
  84          * @remarks             The specific error code can be accessed using the GetLastResult() method.
  85          */
  86         VisualElementAnimation(const VisualElementAnimation& animation);
  87
  88
  89         /**
  90          * Assigns the value of the specified instance to the current instance of %VisualElementAnimation.
  91          *
  92          * @since       2.0
  93          *
  94          * @param[in]   rhs             An instance of %VisualElementAnimation
  95          */
  96         VisualElementAnimation& operator =(const VisualElementAnimation& rhs);
  97
  98
  99         /**
 100          * Checks whether the specified instance and current instance of %VisualElementAnimation have equal animation values.
 101          *
 102          * @since       2.0
 103          *
 104          * @return      @c true if the animation of the two instances of %VisualElementAnimation are equal, @n
 105          *                      else @c false
 106          * @param[in]   rhs             An instance of %VisualElementAnimation
 107          */
 108         bool operator ==(const VisualElementAnimation& rhs) const;
 109
 110
 111         /**
 112          * Checks whether the specified instance and current instance of %VisualElementAnimation have different animation values.
 113          *
 114          * @since       2.0
 115          *
 116          * @return      @c true if the values of the animations of the two instances of %VisualElementAnimation are not equal, @n
 117          *                      else @c false
 118          * @param[in]   rhs             An instance of %VisualElementAnimation
 119          */
 120         bool operator !=(const VisualElementAnimation& rhs) const;
 121
 122
 123         /**
 124          * Checks whether the value of the current instance of %VisualElementAnimation equals the value of the specified instance.
 125          *
 126          * @since       2.0
 127          *
 128          * @return      @c true if the value of the current instance equals the value of the specified instance, @n
 129          *                      else @c false
 130          * @param[in]   obj             An instance of %VisualElementAnimation
 131          * @remarks     The %VisualElementAnimation class has a semantic value which means that this method checks whether the two instances have the same animation.
 132          */
 133         virtual bool Equals(const Tizen::Base::Object& obj) const;
 134
 135
 136         /**
 137          * Gets the hash value of the current instance.
 138          *
 139          * @since       2.0
 140          *
 141          * @return      The hash value of the current instance
 142          * @remarks     The two equal instances must return the same hash value.
 143          *                              For better performance, the used hash function must generate a random distribution for all inputs.
 144          */
 145         virtual int GetHashCode(void) const;
 146
 147
 148         /**
 149          * Gets the copied instance of the class.
 150          *
 151          * @since   2.0
 152          *
 153          * @return      An instance of %VisualElementAnimation
 154          * @exception   E_SUCCESS               The method is successful.
 155          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 156          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 157          */
 158         virtual VisualElementAnimation* CloneN(void) const;
 159
 160
 161         /**
 162          * Sets an IVisualElementAnimationStatusEventListener listener instance to listen to the events of a particular animation. @n
 163          * The added listener, %IVisualElementAnimationStatusEventListener, can listen to events on the specified event dispatcher's context when they are fired.
 164          *
 165          * @since       2.0
 166          *
 167          * @param[in]   pListener               The listener instance to set
 168          * @remarks     When the animation which is listening to an animation status event is removed before starting, the platform skips to call @n
 169          *                      the IVisualElementAnimationStatusEventListener::OnVisualElementAnimationStarted() method and directly calls the IVisualElementAnimationStatusEventListener::OnVisualElementAnimationFinished() method.
 170          */
 171         void SetVisualElementAnimationStatusEventListener(IVisualElementAnimationStatusEventListener* pListener);
 172
 173
 174         /**
 175          * Gets the IVisualElementAnimationStatusEventListener listener.
 176          *
 177          * @since       2.0
 178          *
 179          * @return              A pointer to the IVisualElementAnimationStatusEventListener instance @n
 180          *                              If listener has not been set, @c null is returned.
 181          * @see                 SetVisualElementAnimationStatusEventListener()
 182          */
 183         IVisualElementAnimationStatusEventListener* GetVisualElementAnimationStatusEventListener(void) const;
 184
 185
 186         /**
 187          * Sets the timing function to calculate the animation pace.
 188          *
 189          * @since       2.0
 190          *
 191          * @param[in]   pTimingFunction         The timing function instance to set
 192          * @remarks     If @c pTimingFunction is @c null, the default timing function is used which is pre-defined by the UI framework.
 193          * @see                 GetTimingFunction()
 194          */
 195         void SetTimingFunction(const IVisualElementAnimationTimingFunction* pTimingFunction);
 196
 197
 198         /**
 199          * Gets the timing function.
 200          *
 201          * @since   2.0
 202          *
 203          * @return              A pointer to the timing function instance
 204          *                              If timing function has not been set, the default timing function is returned.
 205          * @see                 SetTimingFunction()
 206          */
 207         const IVisualElementAnimationTimingFunction* GetTimingFunction(void) const;
 208
 209
 210         /**
 211          * Sets the interpolator to calculate the current value for the specific time during the animation.
 212          *
 213          * @since       2.0
 214          *
 215          * @param[in]   pInterpolator   The interpolator instance to set
 216          * @remarks     If @c pInterpolator is @c null, the default interpolator is used which is pre-defined by the UI framework.
 217          * @see                 GetValueInterpolator()
 218          */
 219         void SetValueInterpolator(const IVisualElementAnimationValueInterpolator* pInterpolator);
 220
 221
 222         /**
 223          * Gets the value interpolator.
 224          *
 225          * @since       2.0
 226          *
 227          * @return              A pointer to the interpolator instance
 228          *                              If interpolator has not been set, the default interpolator is returned.
 229          * @see                 SetValueInterpolator()
 230          */
 231         const IVisualElementAnimationValueInterpolator* GetValueInterpolator(void) const;
 232
 233
 234         /**
 235          * Sets the duration of the animation.
 236          *
 237          * @since       2.0
 238          *
 239          * @return      An error code
 240          * @param[in]   milliseconds    The duration of the animation in milliseconds
 241          * @exception   E_SUCCESS               The method is successful.
 242          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or lesser than the offset of the animation.
 243          * @see         GetDuration()
 244          */
 245         result SetDuration(long milliseconds);
 246
 247
 248         /**
 249          * Gets the duration of the animation in milliseconds.
 250          *
 251          * @since       2.0
 252          *
 253          * @return      The duration value of the animation
 254          * @see         SetDuration()
 255          */
 256         long GetDuration(void) const;
 257
 258
 259         /**
 260          * Sets the offset value of the animation. @n
 261          * Additionally, the %SetOffset() alters the start value and duration for which an animation is played.
 262          *
 263          * @since       2.0
 264          *
 265          * @return      An error code
 266          * @param[in]   milliseconds            The offset of the animation in milliseconds
 267          * @exception   E_SUCCESS               The method is successful.
 268          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or greater than the duration of the animation.
 269          * @remarks     If the start value of the animation is @c 0.0, the end value is @c 1.0, the duration is @c 100 ms and the offset value is @c 20 ms,
 270          *              the actual animation starts at @c 0th ms and plays for @c 80 ms with a start value of @c 0.2. @n
 271          *              If @c autoReverse is set to @c true, the backward animation plays for @c 100ms, from @c 1.0 to @c 0.0.
 272          * @see         GetOffset()
 273          */
 274         result SetOffset(long milliseconds);
 275
 276
 277         /**
 278          * Gets the offset value in milliseconds after the animation starts.
 279          *
 280          * @since       2.0
 281          *
 282          * @return      The offset value of the animation in milliseconds @n
 283          *                      The default value of the offset is @c 0.
 284          * @see         SetOffset()
 285          */
 286         long GetOffset(void) const;
 287
 288
 289         /**
 290          * Sets the delay for the animation. @n
 291          * The animation starts after the duration of delay has passed.
 292          *
 293          * @since       2.0
 294          *
 295          * @return      An error code
 296          * @param[in]   milliseconds            The delay for the animation to start in milliseconds
 297          * @exception   E_SUCCESS               The method is successful.
 298          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 299          * @remarks     This method does not alter the start, end, and duration values of the animation.
 300          * @see         GetDelay()
 301          */
 302         result SetDelay(long milliseconds);
 303
 304
 305         /**
 306          * Gets the delay value in milliseconds before the animation starts.
 307          *
 308          * @since       2.0
 309          *
 310          * @return      The delay value in milliseconds @n
 311          *                      The default value of the delay is @c 0.
 312          * @see         SetDelay()
 313          */
 314         long GetDelay(void) const;
 315
 316
 317         /**
 318          * Sets the repeat count for the animation. @n
 319          * Repeats an animation for the specified number of times.
 320          *
 321          * @since       2.0
 322          *
 323          * @return      An error code
 324          * @param[in]   count                   The number of times the animation is repeated
 325          * @exception   E_SUCCESS               The method is successful.
 326          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 327          * @remarks     A delay and offset is applied to an animation only when the animation is played for the first time.
 328          *              If @c count is set to @c 0, the animation is repeated indefinitely.
 329          * @see         GetRepeatCount()
 330          */
 331         result SetRepeatCount(long count);
 332
 333
 334         /**
 335          * Gets the repeat count value of the animation.
 336          *
 337          * @since       2.0
 338          *
 339          * @return      The repeat count value of the animation @n
 340          *                      The default value of the repeat count is @c 1.
 341          * @see         SetRepeatCount()
 342          */
 343         long GetRepeatCount(void) const;
 344
 345
 346         /**
 347          * Sets the @c autoReverse property of the animation. @n
 348          * If enabled, the forward and backward animation can also be played.
 349          *
 350          * @since       2.0
 351          *
 352          * @param[in]   autoReverse             Set to @c true to enable the @c autoReverse property of the animation, @n
 353          *                                                              else @c false
 354          * @remarks             If @c autoReverse is set to @c true, the duration of the animation is doubled.
 355          *                              If the repeat count is more than @c 1, @c autoReverse is applied to each iteration. @n
 356          *              Note that if @c autoReverse is set to @c true, one forward animation play and
 357          *                              one backward animation play is one iteration.
 358          * @see         IsAutoReverseEnabled()
 359          */
 360         void SetAutoReverseEnabled(bool autoReverse);
 361
 362
 363         /**
 364          * Checks whether auto reverse is enabled.
 365          *
 366          * @since       2.0
 367          *
 368          * @return      @c true if auto reverse is enabled, @n
 369          *                      else @c false @n
 370          *                      The default auto reverse value is @c false.
 371          * @see         SetAutoReverseEnabled()
 372          */
 373         bool IsAutoReverseEnabled(void) const;
 374
 375
 376         /**
 377          * Sets the scale ratio of the animation.
 378          *
 379          * @since       2.0
 380          *
 381          * @return      An error code
 382          * @param[in]   scaleRatio              The scale ratio value of the animation
 383          * @exception   E_SUCCESS               The method is successful.
 384          * @exception   E_INVALID_ARG           The value of the specified parameter is below @c 0.
 385          * @remarks             If @c scaleRatio is @c 0.5, then the animation speed is 2 times faster.
 386          * @see         GetScaleRatio()
 387          */
 388         result SetScaleRatio(float scaleRatio);
 389
 390
 391         /**
 392          * Gets the scale ratio value of the animation.
 393          *
 394          * @since       2.0
 395          *
 396          * @return      The scale ratio value of the animation @n
 397          *                      The default value of scale ratio is @c 1.0f.
 398          * @see         SetScaleRatio()
 399          */
 400         float GetScaleRatio(void) const;
 401
 402
 403         /**
 404          * Sets the custom data of the animation.
 405          *
 406          * @since               2.0
 407          *
 408          * @param[in]   pUserData                       The user data associated with this instance
 409          * @see         GetUserData()
 410          */
 411         void SetUserData(void* pUserData);
 412
 413
 414         /**
 415          * Gets the custom data of the animation.
 416          *
 417          * @since               2.0
 418          *
 419          * @return              The user data associated with this instance
 420          * @see         SetUserData()
 421          */
 422         void* GetUserData(void) const;
 423
 424
 425         /**
 426          * Gets the predefined timing function by name.
 427          *
 428          * @since       2.0
 429          *
 430          * @return      The specified timing function
 431          * @param[in]   name                    The timing function name
 432          * @exception   E_SUCCESS               The method is successful.
 433          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 434          * @remarks             The parameter @c name must be "Linear", "EaseIn", "EaseOut", "EaseInOut", "EaseOutIn", "Discrete", "Bezier", "ExpIn", "ExpOut", "EaseElasticIn", or "EaseElasticOut".
 435          *                              The specific error code can be accessed using the GetLastResult() method.
 436          */
 437         static const IVisualElementAnimationTimingFunction* GetTimingFunctionByName(const Tizen::Base::String& name);
 438
 439
 440 protected:
 441
 442         //
 443         // This variable is for internal use only. Using this variable can cause behavioral, security-related,
 444         // and consistency-related issues in the application.
 445         //
 446         // This is the constructor for derived classes.
 447         //
 448         // @since  2.0
 449         //
 450         VisualElementAnimation(_VisualElementAnimationImpl* pImpl);
 451
 452
 453         //
 454         // This variable is for internal use only. Using this variable can cause behavioral, security-related,
 455         // and consistency-related issues in the application.
 456         //
 457         // @since  2.0
 458         //
 459         _VisualElementAnimationImpl* _pAnimationImpl;
 460
 461         friend class _VisualElementAnimationImpl;
 462 };              // VisualElementAnimation
 463
 464
 465 }}}             // Tizen::Ui::Animations
 466
 467 #endif  // _FUI_ANIM_VISUAL_ELEMENT_ANIMATION_H_