inc/FUiAnimDimensionAnimation.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        FUiAnimDimensionAnimation.h
  20  * @brief       This is the header file for the %DimensionAnimation class.
  21  *
  22  * This header file contains the declarations of the %DimensionAnimation class.
  23  */
  24
  25 #ifndef _FUI_ANIM_DIMENSION_ANIMATION_H_
  26 #define _FUI_ANIM_DIMENSION_ANIMATION_H_
  27
  28 #include <FGrpDimension.h>
  29 #include <FGrpPoint.h>
  30
  31 #include <FUiAnimAnimationBase.h>
  32
  33 namespace Tizen { namespace Ui { namespace Animations
  34 {
  35
  36 /**
  37  * @class       DimensionAnimation
  38  * @brief       This class animates the %Tizen::Graphics::Dimension object.
  39  *
  40  * @since       2.0
  41  *
  42  * @final   This class is not intended for extension.
  43  *
  44  * The %DimensionAnimation class animates an object from a Tizen::Graphics::Dimension value to another %Tizen::Graphics::Dimension value
  45  * based on the specified interpolator type.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/animating_uicontrols.htm">Animating UI Controls</a>.
  48  */
  49 class _OSP_EXPORT_ DimensionAnimation
  50         : public AnimationBase
  51 {
  52 public:
  53         /**
  54          * Initializes this instance of %DimensionAnimation with the specified parameters.
  55          *
  56          * @since               2.0
  57          *
  58          * @param[in]   startValue                      The start value for the dimension animation
  59          * @param[in]   endValue                        The end value for the dimension animation
  60          * @param[in]   duration                        The duration of animation in milliseconds
  61          * @param[in]   interpolator            The type of interpolator used for the animation's intermediate value calculation
  62          * @exception   E_SUCCESS                       The method is successful.
  63          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or the interpolator is of an invalid type.
  64          * @remarks             The specific error code can be accessed using the GetLastResult() method.
  65          */
  66         DimensionAnimation(const Tizen::Graphics::Dimension& startValue, const Tizen::Graphics::Dimension& endValue, long duration, AnimationInterpolatorType interpolator);
  67
  68
  69         /**
  70          * This is the destructor for this class.
  71          *
  72          * @since       2.0
  73          */
  74         virtual ~DimensionAnimation(void);
  75
  76         /**
  77          * This is the copy constructor for the %DimensionAnimation class.
  78          *
  79          * @since       2.0
  80          *
  81          * @param[in]   dimensionAnimation      An instance of %DimensionAnimation
  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         DimensionAnimation(const DimensionAnimation& dimensionAnimation);
  87
  88
  89         /**
  90          * Assigns the value of the specified instance to the current instance of %DimensionAnimation.
  91          *
  92          * @since       2.0
  93          *
  94          * @param[in]   rhs             An instance of %DimensionAnimation
  95          * @exception   E_SUCCESS                       The method is successful.
  96          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  97          * @remarks             The specific error code can be accessed using the GetLastResult() method.
  98          */
  99         DimensionAnimation& operator =(const DimensionAnimation& rhs);
 100
 101
 102         /**
 103          * Checks whether the specified instance and current instance of %DimensionAnimation have equal animation values.
 104          *
 105          * @since       2.0
 106          *
 107          * @return              @c true if the animation of the two instances of %DimensionAnimation are equal, @n
 108          *                              else @c false
 109          * @param[in]   rhs             An instance of %DimensionAnimation
 110          */
 111         bool operator ==(const DimensionAnimation& rhs) const;
 112
 113
 114         /**
 115          * Checks whether the specified instance and current instance of %DimensionAnimation have different animation values.
 116          *
 117          * @since       2.0
 118          *
 119          * @return              @c true if the values of the animations of the two instances of %DimensionAnimation are not equal, @n
 120          *                              else @c false
 121          * @param[in]   rhs             An instance of %DimensionAnimation
 122          */
 123         bool operator !=(const DimensionAnimation& rhs) const;
 124
 125
 126         /**
 127          * Checks whether the value of the current instance of %DimensionAnimation equals the value of the specified instance.
 128          *
 129          * @since       2.0
 130          *
 131          * @return              @c true if the value of the current instance equals the value of the specified instance, @n
 132          *              else @c false
 133          * @param[in]   obj             An instance of %DimensionAnimation
 134          * @remarks     The %DimensionAnimation class has a semantic value that means this method checks whether the two instances have the same animation.
 135          */
 136         virtual bool Equals(const Tizen::Base::Object& obj) const;
 137
 138
 139         /**
 140          * Gets the hash value of the current instance.
 141          *
 142          * @since       2.0
 143          *
 144          * @return              The hash value of the current instance
 145          * @remarks     The two equal instances must return the same hash value. For better performance, the used hash function must generate a random
 146          *                              distribution for all inputs.
 147          */
 148         virtual int GetHashCode(void) const;
 149
 150
 151         /**
 152          * Sets the anchor points for the animation.
 153          *
 154          * @since       2.0
 155          *
 156          * @return      An error code
 157          * @param[in]   anchorX                         The X value of the anchor at which the control's animation is performed
 158          * @param[in]   anchorY                         The Y value of the anchor at which the control's animation is performed
 159          * @exception   E_SUCCESS                       The method is successful.
 160          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
 161          * @remarks     A default anchor point value is (0.0, 0.0). The range of an anchor point is @c 0.0 to @c 1.0. @n
 162          *              When the anchor point value is (0.0, 0.0), the object is scaled and the top-left corner of the object remains fixed. @n
 163          *              For all the other anchor point values, the position property is changed.
 164          *              If the anchor point value is (0.5, 0.5), the object is scaled with respect to the center.
 165          *              If the anchor point value is (1.0, 1.0), the object is scaled and the bottom-right corner of the object remains fixed.
 166          */
 167         result SetAnchor(float anchorX, float anchorY);
 168
 169
 170         /**
 171          * Gets the anchor point associated with the animation. @n
 172          * The default anchor point is (0.0, 0.0).
 173          *
 174          * @since               2.0
 175          *
 176          * @param[out]  anchorX         The X value of the anchor at which the control's animation is performed
 177          * @param[out]  anchorY         The Y value of the anchor at which the control's animation is performed
 178          */
 179         void GetAnchor(float& anchorX, float& anchorY) const;
 180
 181
 182         /**
 183          * Gets the animated value for the current time.
 184          *
 185          * @since               2.0
 186          *
 187          * @return      An error code
 188          * @param[in]   currentTime                     The current time value of the animation play @n
 189          *                                                                      The value must be between @c 0 and the duration of the animation.
 190          * @param[out]  animatedValue           The animated value for the current time passed as the input parameter
 191          * @exception   E_SUCCESS                       The method is successful.
 192          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
 193          * @exception   E_SYSTEM                        A system error has occurred.
 194          *
 195          */
 196         result GetAnimatedValue(long currentTime, Tizen::Graphics::Dimension& animatedValue) const;
 197
 198
 199         /**
 200          * Adds a keyframe to the animation.
 201          *
 202          * @since       2.0
 203          *
 204          * @return              An error code
 205          * @param[in]   time                            The time stamp
 206          * @param[in]   value                           The value at the specified @c time
 207          * @exception   E_SUCCESS                       The method is successful.
 208          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
 209          * @exception   E_SYSTEM                        A system error has occurred.
 210          * @remarks             If @c time is greater than the duration, it will become the new duration and @c value becomes the new @c endValue. @n
 211          *              Also, the old duration and @c endValue will be added as a new key frame entry in the list. @n
 212          *              If a key-value pair with the current key already exists, the old value will be overwritten with the new one. @n
 213          *              An exception will be returned if @c time is equal to @c 0 or the duration of the animation.
 214          */
 215         result AddKeyFrame(long time, const Tizen::Graphics::Dimension& value);
 216
 217
 218         /**
 219          * Gets the keyframe at a particular index in this animation.
 220          *
 221          * @since       2.0
 222          *
 223          * @return      An error code
 224          * @param[in]   index                           The index value in the keyframe list that is sorted in an increasing order of time
 225          * @param[out]  time                            The time stamp at the specified @c index
 226          * @param[out]  value                           The value at the specified @c index
 227          * @exception   E_SUCCESS                       The method is successful.
 228          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 229          * @exception   E_SYSTEM                        A system error has occurred.
 230          * @remarks             The @c time and @c value returned is the one present at the index of the sorted map list(sorted with respect to key). @n
 231          *              For example, if the user adds key-frame in the order (10,value1), (20,value2), (5,value3) and then GetKeyFrameAt(0,time,value) is called, the
 232          *                              pair returned is (5,value3).
 233          */
 234         result GetKeyFrameAt(int index, long& time, Tizen::Graphics::Dimension& value) const;
 235
 236
 237         /**
 238          * Removes the passed keyframe object from the keyframe list.
 239          *
 240          * @since       2.0
 241          *
 242          * @return              An error code
 243          * @param[in]   time                            The key frame time
 244          * @exception   E_SUCCESS                       The method is successful.
 245          * @exception   E_INVALID_ARG           The keyframe @c time value is invalid.
 246          * @exception   E_OBJ_NOT_FOUND         The keyframe @c time value is not found in the keyframe List.
 247          * @exception   E_SYSTEM                        A system error has occurred.
 248          */
 249         result RemoveKeyFrame(long time);
 250
 251
 252         /**
 253          * Removes the keyframe present at the specified @c index from the keyframe list.
 254          *
 255          * @since       2.0
 256          *
 257          * @return              An error code
 258          * @param[in]   index                           The index value in the Keyframe list @n
 259          *                                  The value is sorted in an increasing order of time.
 260          * @exception   E_SUCCESS                       The method is successful.
 261          * @exception   E_OUT_OF_RANGE          The specified @c index parameter is out of range.
 262          * @exception   E_SYSTEM                        A system error has occurred.
 263          */
 264         result RemoveKeyFrameAt(int index);
 265
 266
 267         /**
 268          * Removes all the keyframes from the animation.
 269          *
 270          * @since       2.0
 271          *
 272          * @return              An error code
 273          * @exception   E_SUCCESS                       The method is successful.
 274          * @exception   E_SYSTEM                        A system error has occurred.
 275          */
 276         result RemoveAllKeyFrames(void);
 277
 278
 279         /**
 280          * Sets the start value of the animation.
 281          *
 282          * @since       2.0
 283          *
 284          * @return              An error code
 285          * @param[in]   startValue                      The start value of the animation to set
 286          * @exception   E_SUCCESS                       The method is successful.
 287          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 288          * @exception   E_SYSTEM                        A system error has occurred.
 289          */
 290         result SetStartValue(const Tizen::Graphics::Dimension& startValue);
 291
 292
 293         /**
 294          * Sets the end value of the animation.
 295          *
 296          * @since       2.0
 297          *
 298          * @return      An error code
 299          * @param[in]   endValue                        The end value of the animation to set
 300          * @exception   E_SUCCESS                       The method is successful.
 301          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 302          * @exception   E_SYSTEM                        A system error has occurred.
 303          */
 304         result SetEndValue(const Tizen::Graphics::Dimension& endValue);
 305
 306
 307         /**
 308          * Gets the start value of the animation.
 309          *
 310          * @since       2.0
 311          *
 312          * @return      The start value
 313          */
 314         Tizen::Graphics::Dimension GetStartValue(void) const;
 315
 316
 317         /**
 318          * Gets the end value of the animation.
 319          *
 320          * @since       2.0
 321          *
 322          * @return      The end value
 323          */
 324         Tizen::Graphics::Dimension GetEndValue(void) const;
 325
 326
 327         /**
 328          * Gets the animation type information of this instance.
 329          *
 330          * @since       2.0
 331          *
 332          * @return  The animation type information of this instance
 333          */
 334         virtual AnimationType GetType(void) const;
 335
 336
 337 protected:
 338         friend class _DimensionAnimationImpl;
 339
 340
 341         //
 342         // This variable is for internal use only. Using this variable can cause behavioral, security-related,
 343         // and consistency-related issues in the application.
 344         //
 345         // The variable for internal usage.
 346         //
 347         // @since  2.0
 348         //
 349         class _DimensionAnimationImpl* _pDimensionAnimationImpl;
 350
 351
 352 private:
 353         //
 354         // This method is for internal use only. Using this method can cause behavioral, security-related,
 355         // and consistency-related issues in the application.
 356         //
 357         // This is the default constructor for this class.
 358         //
 359         // @since       2.0
 360         //
 361         DimensionAnimation(void);
 362 };      // DimensionAnimation
 363
 364
 365 }}}     // Tizen::Ui::Animations
 366
 367 #endif  // _FUI_ANIM_DIMENSION_ANIMATION_H_