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