inc/FUiAnimAnimationBase.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
  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        FUiAnimAnimationBase.h
  20  * @brief       This is the header file for the %AnimationBase class.
  21  *
  22  * This header file contains the declarations of the %AnimationBase class and the enumerators related to it.
  23  */
  24
  25 #ifndef _FUI_ANIM_ANIMATION_BASE_H_
  26 #define _FUI_ANIM_ANIMATION_BASE_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FUiAnimTypes.h>
  31
  32 namespace Tizen { namespace Ui { namespace Animations
  33 {
  34
  35 /**
  36  * @class       AnimationBase
  37  * @brief       This class is the base class for all the Animation classes. @n
  38  *                      It is an abstract base class.
  39  *
  40  * @since       2.0
  41  *
  42  * The %AnimationBase class defines the basic animation properties, such as the interpolator to be used, the duration of the animation in milliseconds, the delay before the animation is started in milliseconds, and the repeat count.
  43  *
  44  */
  45 class _OSP_EXPORT_ AnimationBase
  46         : public Tizen::Base::Object
  47 {
  48 public:
  49
  50         /**
  51          * This is the destructor for this class.
  52          *
  53          * @since       2.0
  54          */
  55         virtual ~AnimationBase(void);
  56
  57
  58         /**
  59          * Sets the duration of the animation.
  60          *
  61          * @since               2.0
  62          *
  63          * @return              An error code
  64          * @param[in]   milliseconds            The duration of the animation in milliseconds
  65          * @exception   E_SUCCESS                       The method is successful.
  66          * @exception   E_INVALID_ARG       The value of the specified parameter is negative.
  67          */
  68         result SetDuration(long milliseconds);
  69
  70
  71         /**
  72          * Sets the offset value of the animation. @n
  73          * Additionally, the %SetOffset() method alters the start value and duration for which an animation is played.
  74          *
  75          * @since               2.0
  76          *
  77          * @return              An error code
  78          * @param[in]   milliseconds            The offset of the animation in milliseconds
  79          * @exception   E_SUCCESS                       The method is successful.
  80          * @exception   E_INVALID_ARG       The value of the specified parameter is negative or greater than the duration of the animation.
  81          * @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,
  82          *              the actual animation starts at @c 0th ms and plays for @c 80 ms with a start value of @c 0.2. @n
  83          *                              If @c autoReverseset is set to @c true, the Backward animation plays for 100ms, from @c 1.0 to @c 0.0.
  84          */
  85         result SetOffset(long milliseconds);
  86
  87
  88         /**
  89          * Sets the delay for the animation. @n
  90          * The animation starts after the duration of delay has passed.
  91          *
  92          * @since               2.0
  93          *
  94          * @return              An error code
  95          * @param[in]   milliseconds            The delay for the animation to start in milliseconds
  96          * @exception   E_SUCCESS                       The method is successful.
  97          * @exception   E_INVALID_ARG       The value of the specified parameter is negative.
  98          * @remarks             This method does not alter the start, end, and duration values of the animation.
  99          */
 100         result SetDelay(long milliseconds);
 101
 102
 103         /**
 104          * Sets the repeat count for the animation. @n
 105          * Repeats an animation for the specified number of times.
 106          *
 107          * @since               2.0
 108          *
 109          * @return              An error code
 110          * @param[in]   count                           The number of times the animation has to repeat
 111          * @exception   E_SUCCESS                       The method is successful.
 112          * @exception   E_INVALID_ARG       The value of the specified parameter is negative.
 113          * @remarks             A delay and offset is applied to an animation only when the animation is played for the first time.
 114          */
 115         result SetRepeatCount(long count);
 116
 117
 118         /**
 119          * Sets the AutoReverse property of the animation. @n
 120          * If enabled, the forward and backward animation can also be played.
 121          *
 122          * @since               2.0
 123          *
 124          * @param[in]   autoReverse                     Set to @c true to enable the AutoReverse property of the animation, @n
 125          *                                                                      else @c false
 126          * @remarks             If @c autoReverseset is set to @c true, the duration of the animation is doubled.
 127          *                              If the repeat count is more than 1, @n
 128          *                              @c autoReverse is applied to each iteration.
 129          *              Note that if @c autoReverse is set to @c true, one forward animation play and one backward animation play is one
 130          *                              iteration.
 131          */
 132         void SetAutoReverseEnabled(bool autoReverse);
 133
 134
 135         /**
 136          * Sets the scale ratio of the animation. @n
 137          * The %SetScaleRatio() method multiplies the duration, offset, and delay using the scale ratio.
 138          *
 139          * @since               2.0
 140          *
 141          * @return              An error code
 142          * @param[in]   scaleRatio                      The scale ratio property of the animation
 143          * @exception   E_SUCCESS                       The method is successful.
 144          * @exception   E_INVALID_ARG       The value of the specified parameter is negative.
 145          */
 146         result SetScaleRatio(float scaleRatio);
 147
 148
 149         /**
 150          * Sets the hold end value of the animation. @n
 151          * The %SetHoldEndEnabled() method retains the end values of an animation or goes to the start value of an animation.
 152          *
 153          * @since               2.0
 154          *
 155          * @param[in]   holdEnd         Set to @c true to hold the end values of the animation, @n
 156          *                                                      else @c false
 157          */
 158         void SetHoldEndEnabled(bool holdEnd);
 159
 160
 161         /**
 162          * Gets the duration of the animation in milliseconds.
 163          *
 164          * @since               2.0
 165          *
 166          * @return      The duration value of the animation
 167          */
 168         long GetDuration(void) const;
 169
 170
 171         /**
 172          * Gets the offset value in milliseconds after the animation starts.
 173          *
 174          * @since               2.0
 175          *
 176          * @return      The offset value of the animation in milliseconds @n
 177          *                              The default value of the offset is @c 0.
 178          */
 179         long GetOffset(void) const;
 180
 181
 182         /**
 183          * Gets the delay value in milliseconds before the animation starts.
 184          *
 185          * @since               2.0
 186          *
 187          * @return              The delay value in milliseconds @n
 188          *                              The default value of the delay is @c 0.
 189          */
 190         long GetDelay(void) const;
 191
 192
 193         /**
 194          * Gets the repeat count value of the animation.
 195          *
 196          * @since               2.0
 197          *
 198          * @return              The repeat count value of the animation @n
 199          *                              The default value of the repeat count is @c 1.
 200          */
 201         long GetRepeatCount(void) const;
 202
 203
 204         /**
 205          * Checks whether the auto reverse is enabled.
 206          *
 207          * @since               2.0
 208          *
 209          * @return              @c true if the auto reverse is enabled, @n
 210          *                              else @c false @n
 211          *                              The default auto reverse value is @c false.
 212          */
 213         bool IsAutoReverseEnabled(void) const;
 214
 215
 216         /**
 217          * Gets the scale ratio value of the animation.
 218          *
 219          * @since               2.0
 220          *
 221          * @return              The scale ratio value of the animation @n
 222          *                              The default value of scale ratio is @c 1.0f.
 223          */
 224         float GetScaleRatio(void) const;
 225
 226
 227         /**
 228          * Checks whether the hold end value of the animation is enabled.
 229          *
 230          * @since               2.0
 231          *
 232          * @return              @c true if the hold end value is enabled, @n
 233          *                              else @c false @n
 234          *                              The default hold end value is @c true.
 235          */
 236         bool IsHoldEndEnabled(void) const;
 237
 238
 239         /**
 240          * Sets the interpolator type.
 241          *
 242          * @since               2.0
 243          *
 244          * @param[in]   interpolatorType        The interpolator type used for the animation
 245          */
 246         void SetInterpolatorType(AnimationInterpolatorType interpolatorType);
 247
 248
 249         /**
 250          * Gets the interpolator type.
 251          *
 252          * @since               2.0
 253          *
 254          * @return      The interpolator type of an animation @n
 255          *                              The default interpolator type is @c ANIMATION_INTERPOLATOR_LINEAR.
 256          */
 257         AnimationInterpolatorType GetInterpolatorType(void) const;
 258
 259
 260         /**
 261          * Sets the control points for Bezier interpolator. @n
 262          * The %SetBezierControlPoints() method is supported only if the interpolator is ANIMATION_INTERPOLATOR_BEZIER.
 263          *
 264          * @since               2.0
 265          *
 266          * @return              An error code
 267          * @param[in]   time1                           The control point 1 - Time @n
 268          *                                                                      The time must be in the range @c 0.0 to @c 1.0. The time value is scaled relative to the duration of the animation.
 269          * @param[in]   value1                          The control point 1 - Value @n
 270          *                                                                      The value must be in the range @c 0.0 to @c 1.0. The value is scaled relative to the start and end value of the animation.
 271          * @param[in]   time2                           The control point 2 - Time @n
 272          *                                                                      The time must be in the range @c 0.0 to @c 1.0. The time value is scaled relative to the duration of the animation.
 273          * @param[in]   value2                          The control point 2 - Value @n
 274          *                                                                      The value must be in the range @c 0.0 to @c 1.0. The value is scaled relative to the start and end value of the animation.
 275          * @exception   E_SUCCESS                       The method is successful.
 276          * @exception   E_INVALID_OPERATION This method is not supported for the interpolator set of this instance.
 277          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 278          * @remarks             @c time1 can be greater than @c time2 and vice versa.
 279          */
 280         result SetBezierControlPoints(float time1, float value1, float time2, float value2);
 281
 282
 283         /**
 284          * Gets the control points of the Bezier interpolator. @n
 285          * The %GetBezierControlPoints() method is supported only if the interpolator is @c ANIMATION_INTERPOLATOR_BEZIER. @c 0 is returned for the other interpolators.
 286          *
 287          * @since               2.0
 288          *
 289          * @return              An error code
 290          * @param[out]  time1                           The control point 1 - Time @n
 291          *                                                                      The default value of control point 1 is @c 0.0.
 292          * @param[out]  value1                          The control point 1 - Value @n
 293          *                                                                      The default value of control point 1 is @c 0.0.
 294          * @param[out]  time2                           The control point 2 - Time @n
 295          *                                                                      The default value of control point 2 is @c 0.0.
 296          * @param[out]  value2                          The control point 2 - Value @n
 297          *                                                                      The default value of control point 2 is @c 0.0.
 298          * @exception   E_SUCCESS                       The method is successful.
 299          * @exception   E_INVALID_OPERATION This method is not supported for the interpolator set of this instance.
 300          *
 301          */
 302         result GetBezierControlPoints(float& time1, float& value1, float& time2, float& value2) const;
 303
 304
 305         /**
 306          * Gets the count of key frames added to this animation.
 307          *
 308          * @since               2.0
 309          *
 310          * @return              The key frame count
 311          */
 312         int GetKeyFrameCount(void) const;
 313
 314
 315         /**
 316          * Sets the name of the animation.
 317          *
 318          * @since               2.0
 319          *
 320          * @param[in]   name    The name of the animation
 321          */
 322         void SetName(const Tizen::Base::String& name);
 323
 324
 325         /**
 326          * Gets the name of the animation.
 327          *
 328          * @since               2.0
 329          *
 330          * @return              The name of the animation @n
 331          *                              The default value of the name is an empty string.
 332          */
 333         Tizen::Base::String GetName(void) const;
 334
 335
 336         /**
 337          * Gets the type information of this instance.
 338          *
 339          * @since               2.0
 340          *
 341          * @return              The type information of this instance
 342          */
 343         virtual AnimationType GetType(void) const = 0;
 344
 345
 346 protected:
 347
 348         //
 349         // This method is for internal use only. Using this method can cause behavioral, security-related,
 350         // and consistency-related issues in the application.
 351         //
 352         // This is the default constructor for this class.
 353         //
 354         // @since   2.0
 355         //
 356         AnimationBase(void);
 357
 358
 359         //
 360         // This method is for internal use only. Using this method can cause behavioral, security-related,
 361         // and consistency-related issues in the application.
 362         //
 363         // This is the copy constructor for the %AnimationBase class.
 364         //
 365         // @since        2.0
 366         //
 367         // @param[in]   animationBase           An instance of AnimationBase
 368         // @remarks             The animation name of the copied %AnimationBase object will be same as the %AnimationBase object passed.
 369         //              User must change the name using the SetName() method of this class in order to make animation name unique.
 370         //
 371         AnimationBase(const AnimationBase& animationBase);
 372
 373
 374         //
 375         // This method is for internal use only. Using this method can cause behavioral, security-related,
 376         // and consistency-related issues in the application.
 377         //
 378         // This is the constructor for this class.
 379         //
 380         // @since       2.0
 381         //
 382         // @param[in]   duration                        The duration of animation in milliseconds
 383         // @param[in]   interpolator            The type of Interpolation used for animation's intermediate value calculation
 384         //
 385         AnimationBase(long duration, AnimationInterpolatorType interpolator);
 386
 387
 388         //
 389         // This method is for internal use only. Using this method can cause behavioral, security-related,
 390         // and consistency-related issues in the application.
 391         //
 392         //  Assigns the value of the specified instance to the current instance of %AnimationBase.
 393         //
 394         // @since   2.0
 395         //
 396         // @param[in]   value   An instance of %AnimationBase
 397         // @remarks        The animation name of the returned %AnimationBase object will be same as the %AnimationBase object passed.
 398         //                         User must change the name using SetName() method of this class in order to make animation name unique.
 399         //
 400         AnimationBase& operator =(const AnimationBase& value);
 401
 402
 403         //
 404         // This method is for internal use only. Using this method can cause behavioral, security-related,
 405         // and consistency-related issues in the application.
 406         //
 407         // This method is reserved and may change its name at any time without
 408         // prior notice.
 409         //
 410         // @since       2.0
 411         //
 412         virtual void AnimationBase_Reserved1(void);
 413
 414
 415         //
 416         // This method is for internal use only. Using this method can cause behavioral, security-related,
 417         // and consistency-related issues in the application.
 418         //
 419         // This method is reserved and may change its name at any time without
 420         // prior notice.
 421         //
 422         // @since       2.0
 423         //
 424         virtual void AnimationBase_Reserved2(void);
 425
 426
 427         //
 428         // This method is for internal use only. Using this method can cause behavioral, security-related,
 429         // and consistency-related issues in the application.
 430         //
 431         // This method is reserved and may change its name at any time without
 432         // prior notice.
 433         //
 434         // @since       2.0
 435         //
 436         virtual void AnimationBase_Reserved3(void);
 437
 438
 439         friend class _AnimationBaseImpl;
 440
 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 variable is for internal usage.
 447         //
 448         // @since  2.0
 449         //
 450         class _AnimationBaseImpl* _pAnimationBaseImpl;
 451 };              // AnimationBase
 452
 453
 454 }}}             // Tizen::Ui::Animations
 455
 456 #endif  // _FUI_ANIM_ANIMATION_BASE_H_