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