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          */
 169         void SetVisualElementAnimationStatusEventListener(IVisualElementAnimationStatusEventListener* pListener);
 170
 171
 172         /**
 173          * Gets the IVisualElementAnimationStatusEventListener listener.
 174          *
 175          * @since       2.0
 176          *
 177          * @return              A pointer to the IVisualElementAnimationStatusEventListener instance @n
 178          *                              If listener has not been set, @c null is returned.
 179          * @see                 SetVisualElementAnimationStatusEventListener()
 180          */
 181         IVisualElementAnimationStatusEventListener* GetVisualElementAnimationStatusEventListener(void) const;
 182
 183
 184         /**
 185          * Sets the timing function to calculate the animation pace.
 186          *
 187          * @since       2.0
 188          *
 189          * @param[in]   pTimingFunction         The timing function instance to set
 190          * @remarks     If @c pTimingFunction is @c null, the default timing function is used which is pre-defined by the UI framework.
 191          * @see                 GetTimingFunction()
 192          */
 193         void SetTimingFunction(const IVisualElementAnimationTimingFunction* pTimingFunction);
 194
 195
 196         /**
 197          * Gets the timing function.
 198          *
 199          * @since   2.0
 200          *
 201          * @return              A pointer to the timing function instance
 202          *                              If timing function has not been set, the default timing function is returned.
 203          * @see                 SetTimingFunction()
 204          */
 205         const IVisualElementAnimationTimingFunction* GetTimingFunction(void) const;
 206
 207
 208         /**
 209          * Sets the interpolator to calculate the current value for the specific time during the animation.
 210          *
 211          * @since       2.0
 212          *
 213          * @param[in]   pInterpolator   The interpolator instance to set
 214          * @remarks     If @c pInterpolator is @c null, the default interpolator is used which is pre-defined by the UI framework.
 215          * @see                 GetValueInterpolator()
 216          */
 217         void SetValueInterpolator(const IVisualElementAnimationValueInterpolator* pInterpolator);
 218
 219
 220         /**
 221          * Gets the value interpolator.
 222          *
 223          * @since       2.0
 224          *
 225          * @return              A pointer to the interpolator instance
 226          *                              If interpolator has not been set, the default interpolator is returned.
 227          * @see                 SetValueInterpolator()
 228          */
 229         const IVisualElementAnimationValueInterpolator* GetValueInterpolator(void) const;
 230
 231
 232         /**
 233          * Sets the duration of the animation.
 234          *
 235          * @since       2.0
 236          *
 237          * @return      An error code
 238          * @param[in]   milliseconds    The duration of the animation in milliseconds
 239          * @exception   E_SUCCESS               The method is successful.
 240          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or lesser than the offset of the animation.
 241          * @see         GetDuration()
 242          */
 243         result SetDuration(long milliseconds);
 244
 245
 246         /**
 247          * Gets the duration of the animation in milliseconds.
 248          *
 249          * @since       2.0
 250          *
 251          * @return      The duration value of the animation
 252          * @see         SetDuration()
 253          */
 254         long GetDuration(void) const;
 255
 256
 257         /**
 258          * Sets the offset value of the animation. @n
 259          * Additionally, the %SetOffset() alters the start value and duration for which an animation is played.
 260          *
 261          * @since       2.0
 262          *
 263          * @return      An error code
 264          * @param[in]   milliseconds            The offset of the animation in milliseconds
 265          * @exception   E_SUCCESS               The method is successful.
 266          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or greater than the duration of the animation.
 267          * @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,
 268          *              the actual animation starts at @c 0th ms and plays for @c 80 ms with a start value of @c 0.2. @n
 269          *              If @c autoReverse is set to @c true, the backward animation plays for @c 100ms, from @c 1.0 to @c 0.0.
 270          * @see         GetOffset()
 271          */
 272         result SetOffset(long milliseconds);
 273
 274
 275         /**
 276          * Gets the offset value in milliseconds after the animation starts.
 277          *
 278          * @since       2.0
 279          *
 280          * @return      The offset value of the animation in milliseconds @n
 281          *                      The default value of the offset is @c 0.
 282          * @see         SetOffset()
 283          */
 284         long GetOffset(void) const;
 285
 286
 287         /**
 288          * Sets the delay for the animation. @n
 289          * The animation starts after the duration of delay has passed.
 290          *
 291          * @since       2.0
 292          *
 293          * @return      An error code
 294          * @param[in]   milliseconds            The delay for the animation to start in milliseconds
 295          * @exception   E_SUCCESS               The method is successful.
 296          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 297          * @remarks     This method does not alter the start, end, and duration values of the animation.
 298          * @see         GetDelay()
 299          */
 300         result SetDelay(long milliseconds);
 301
 302
 303         /**
 304          * Gets the delay value in milliseconds before the animation starts.
 305          *
 306          * @since       2.0
 307          *
 308          * @return      The delay value in milliseconds @n
 309          *                      The default value of the delay is @c 0.
 310          * @see         SetDelay()
 311          */
 312         long GetDelay(void) const;
 313
 314
 315         /**
 316          * Sets the repeat count for the animation. @n
 317          * Repeats an animation for the specified number of times.
 318          *
 319          * @since       2.0
 320          *
 321          * @return      An error code
 322          * @param[in]   count                   The number of times the animation is repeated
 323          * @exception   E_SUCCESS               The method is successful.
 324          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 325          * @remarks     A delay and offset is applied to an animation only when the animation is played for the first time.
 326          *              If @c count is set to @c 0, the animation is repeated indefinitely.
 327          * @see         GetRepeatCount()
 328          */
 329         result SetRepeatCount(long count);
 330
 331
 332         /**
 333          * Gets the repeat count value of the animation.
 334          *
 335          * @since       2.0
 336          *
 337          * @return      The repeat count value of the animation @n
 338          *                      The default value of the repeat count is @c 1.
 339          * @see         SetRepeatCount()
 340          */
 341         long GetRepeatCount(void) const;
 342
 343
 344         /**
 345          * Sets the @c autoReverse property of the animation. @n
 346          * If enabled, the forward and backward animation can also be played.
 347          *
 348          * @since       2.0
 349          *
 350          * @param[in]   autoReverse             Set to @c true to enable the @c autoReverse property of the animation, @n
 351          *                                                              else @c false
 352          * @remarks             If @c autoReverse is set to @c true, the duration of the animation is doubled.
 353          *                              If the repeat count is more than @c 1, @c autoReverse is applied to each iteration. @n
 354          *              Note that if @c autoReverse is set to @c true, one forward animation play and
 355          *                              one backward animation play is one iteration.
 356          * @see         IsAutoReverseEnabled()
 357          */
 358         void SetAutoReverseEnabled(bool autoReverse);
 359
 360
 361         /**
 362          * Checks whether auto reverse is enabled.
 363          *
 364          * @since       2.0
 365          *
 366          * @return      @c true if auto reverse is enabled, @n
 367          *                      else @c false @n
 368          *                      The default auto reverse value is @c false.
 369          * @see         SetAutoReverseEnabled()
 370          */
 371         bool IsAutoReverseEnabled(void) const;
 372
 373
 374         /**
 375          * Sets the scale ratio of the animation.
 376          *
 377          * @since       2.0
 378          *
 379          * @return      An error code
 380          * @param[in]   scaleRatio              The scale ratio value of the animation
 381          * @exception   E_SUCCESS               The method is successful.
 382          * @exception   E_INVALID_ARG           The value of the specified parameter is below @c 0.
 383          * @remarks             If @c scaleRatio is @c 0.5, then the animation speed is 2 times faster.
 384          * @see         GetScaleRatio()
 385          */
 386         result SetScaleRatio(float scaleRatio);
 387
 388
 389         /**
 390          * Gets the scale ratio value of the animation.
 391          *
 392          * @since       2.0
 393          *
 394          * @return      The scale ratio value of the animation @n
 395          *                      The default value of scale ratio is @c 1.0f.
 396          * @see         SetScaleRatio()
 397          */
 398         float GetScaleRatio(void) const;
 399
 400
 401         /**
 402          * Sets the custom data of the animation.
 403          *
 404          * @since               2.0
 405          *
 406          * @param[in]   pUserData                       The user data associated with this instance
 407          * @see         GetUserData()
 408          */
 409         void SetUserData(void* pUserData);
 410
 411
 412         /**
 413          * Gets the custom data of the animation.
 414          *
 415          * @since               2.0
 416          *
 417          * @return              The user data associated with this instance
 418          * @see         SetUserData()
 419          */
 420         void* GetUserData(void) const;
 421
 422
 423         /**
 424          * Gets the predefined timing function by name.
 425          *
 426          * @since       2.0
 427          *
 428          * @return      The specified timing function
 429          * @param[in]   name                    The timing function name
 430          * @exception   E_SUCCESS               The method is successful.
 431          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 432          * @remarks             The parameter @c name must be "Linear", "EaseIn", "EaseOut", "EaseInOut", "EaseOutIn", "Discrete", "Bezier", "ExpIn", "ExpOut", "EaseElasticIn", or "EaseElasticOut".
 433          *                              The specific error code can be accessed using the GetLastResult() method.
 434          */
 435         static const IVisualElementAnimationTimingFunction* GetTimingFunctionByName(const Tizen::Base::String& name);
 436
 437
 438 protected:
 439
 440         //
 441         // This variable is for internal use only. Using this variable can cause behavioral, security-related,
 442         // and consistency-related issues in the application.
 443         //
 444         // This is the constructor for derived classes.
 445         //
 446         // @since  2.0
 447         //
 448         VisualElementAnimation(_VisualElementAnimationImpl* pImpl);
 449
 450
 451         //
 452         // This variable is for internal use only. Using this variable can cause behavioral, security-related,
 453         // and consistency-related issues in the application.
 454         //
 455         // @since  2.0
 456         //
 457         _VisualElementAnimationImpl* _pAnimationImpl;
 458
 459         friend class _VisualElementAnimationImpl;
 460 };              // VisualElementAnimation
 461
 462
 463 }}}             // Tizen::Ui::Animations
 464
 465 #endif  // _FUI_ANIM_VISUAL_ELEMENT_ANIMATION_H_