inc/FUiAnimControlAnimator.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        FUiAnimControlAnimator.h
  20  * @brief       This is the header file for the %ControlAnimator class.
  21  *
  22  * This header file contains the declarations of the %ControlAnimator class.
  23  */
  24
  25 #ifndef _FUI_ANIM_CONTROL_ANIMATOR_H_
  26 #define _FUI_ANIM_CONTROL_ANIMATOR_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FBaseObject.h>
  31 #include <FBaseColArrayList.h>
  32 #include <FBaseColArrayListT.h>
  33 #include <FGrpPoint.h>
  34 #include <FGrpRectangle.h>
  35 #include <FGrpDimension.h>
  36 #include <FUiControl.h>
  37 #include <FUiAnimAnimationBase.h>
  38 #include <FUiAnimSequentialAnimationGroup.h>
  39 #include <FUiAnimParallelAnimationGroup.h>
  40 #include <FUiAnimIControlAnimatorEventListener.h>
  41 #include <FUiAnimIControlAnimatorDetailedEventListener.h>
  42
  43 namespace Tizen { namespace Ui { namespace Animations
  44 {
  45
  46 /**
  47  * @class       ControlAnimator
  48  * @brief       This class defines the animation methods for Tizen::Ui::Control.
  49  *
  50  * @since       2.0
  51  *
  52  * @final   This class is not intended for extension.
  53  *
  54  * The %ControlAnimator class is used to control the animations operated in Tizen::Ui::Controls.
  55  *
  56  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/animating_uicontrols.htm">Animating UI Controls</a>.
  57  *
  58  */
  59 class _OSP_EXPORT_ ControlAnimator
  60         : public Tizen::Base::Object
  61 {
  62 public:
  63
  64         /**
  65          * This is the destructor for this class.
  66          *
  67          * @since       2.0
  68          */
  69         virtual ~ControlAnimator(void);
  70
  71
  72         /**
  73          * Starts an animation explicitly. @n
  74          * If multiple controls need to be animated simultaneously, the controls must be part of the AnimationTransaction class. @n
  75          * The %StartUserAnimation() method must be called after AnimationTransaction::Begin() and before AnimationTransaction::Commit().
  76          *
  77          * @since               2.0
  78          *
  79          * @return              An error code
  80          * @param[in]   animTarget                      The property to animate
  81          * @param[in]   animation                       An object of type AnimationBase
  82          * @exception   E_SUCCESS                       The method is successful.
  83          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
  84          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
  85          * @exception   E_SYSTEM                        A system error has occurred.
  86          * @remarks             An animation is deleted at the end of the animation playback. @n
  87          *              RectangleAnimation is used to animate only one animation target at a time.
  88          *              For example, if AnimationTarget is @c ANIMATION_TARGET_SIZE, RectangleAnimation performs only the dimension animation. @n
  89          *              To perform animation using the @c ANIMATION_TARGET_POSITION and @c ANIMATION_TARGET_SIZE properties, AnimationTransaction must be used with
  90          *                              a separate call for each animation target.
  91          */
  92         result StartUserAnimation(AnimationTargetType animTarget, const AnimationBase& animation);
  93
  94
  95         /**
  96          * Starts a group of animations explicitly. @n
  97          * If multiple controls need to be animated simultaneously, the control must be part of the AnimationTransaction class.
  98          * The %StartUserAnimation() method must be called after AnimationTransaction::Begin() and before AnimationTransaction::Commit().
  99          *
 100          * @since               2.0
 101          *
 102          * @return              An error code
 103          * @param[in]   animGroup                       An animation group having a list of animations
 104          * @exception   E_SUCCESS                       The method is successful.
 105          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 106          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 107          * @exception   E_SYSTEM                        A system error has occurred.
 108          * @remarks             The animations are deleted at the end of the animation playback. @n
 109          *              RectangleAnimation is used to animate only one animation target at a time.
 110          */
 111         result StartUserAnimation(const AnimationGroup& animGroup);
 112
 113
 114         /**
 115          * Stops all the animations that are currently playing and jumps to the final frame of the animation.
 116          *
 117          * @since               2.0
 118          *
 119          * @return              An error code
 120          * @exception   E_SUCCESS                       The method is successful.
 121          * @exception   E_SYSTEM                        A system error has occurred.
 122          */
 123         result StopAllAnimations(void);
 124
 125
 126         /**
 127          * Stops the animation with the specified trigger type.
 128          *
 129          * @since               2.0
 130          *
 131          * @return              An error code
 132          * @param[in]   animTrigger                 The animator trigger type
 133          * @exception   E_SUCCESS                       The method is successful.
 134          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 135          * @exception   E_SYSTEM                        A system error has occurred.
 136          */
 137         result StopAnimation(ControlAnimatorTriggerType animTrigger);
 138
 139
 140         /**
 141          * Gets the status of an animation with respect to a control.
 142          *
 143          * @since               2.0
 144          *
 145          * @return              The animation state
 146          */
 147         AnimatorStatus GetStatus(void) const;
 148
 149
 150         /**
 151          * Gets the status of an animation for the specified animation target type.
 152          *
 153          * @since               2.0
 154          *
 155          * @return              The state of an animation with type @c animTarget
 156          * @param[in]   animTarget              The animation target type
 157          */
 158         AnimatorStatus GetStatus(AnimationTargetType animTarget) const;
 159
 160
 161         /**
 162          * Adds the IControlAnimatorEventListener listener instance to the current instance of the control. @n
 163          * The %IControlAnimatorEventListener listener is called for status changes of animations associated with a control.
 164          * The added listener listens to events on the specified event dispatcher's context when they are fired.
 165          *
 166          * @since               2.0
 167          *
 168          * @return              An error code
 169          * @param[in]   listener                                The listener to add
 170          * @exception   E_SUCCESS                               The method is successful.
 171          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 172          * @exception   E_UNSUPPORTED_OPERATION The animation support is unavailable.
 173          * @exception   E_OBJ_ALREADY_EXIST             The specified @c listener is already added.
 174          * @exception   E_SYSTEM                                A system error has occurred.
 175          * @remarks             For animations that are part of AnimationTransaction, the applications need to listen to IAnimationTransactionEventListener events. @n
 176          *                              The IControlAnimatorEventListener events are not fired if the animation is part of a transaction.
 177          */
 178         result AddControlAnimatorEventListener(IControlAnimatorEventListener& listener);
 179
 180
 181         /**
 182          * Removes the IControlAnimatorEventListener listener instance from the current instance of the control. @n
 183          * The removed listener cannot listen to events when they are fired.
 184          *
 185          * @since               2.0
 186          *
 187          * @return              An error code
 188          * @param[in]   listener                                The listener to remove
 189          * @exception   E_SUCCESS                               The method is successful.
 190          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 191          * @exception   E_UNSUPPORTED_OPERATION The animation support is unavailable.
 192          * @exception   E_SYSTEM                                A system error has occurred.
 193          */
 194         result RemoveControlAnimatorEventListener(IControlAnimatorEventListener& listener);
 195
 196
 197         /**
 198          * Adds a IControlAnimatorDetailedEventListener listener instance to the current instance of the control. @n
 199          * The %IControlAnimatorDetailedEventListener listener is called for status changes of each animation associated with the control. @n
 200          * The added listener listens to events on the specified event dispatcher's context when they are fired.
 201          *
 202          * @since               2.0
 203          *
 204          * @return              An error code
 205          * @param[in]   listener                                The listener to add
 206          * @exception   E_SUCCESS                               The method is successful.
 207          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 208          * @exception   E_UNSUPPORTED_OPERATION The animation support is unavailable.
 209          * @exception   E_OBJ_ALREADY_EXIST             The specified @c listener is already added.
 210          * @exception   E_SYSTEM                                A system error has occurred.
 211          * @remarks             For animations that are part of AnimationTransaction, the applications need to listen to the IAnimationTransactionEventListener events. @n
 212          *                              The IControlAnimatorDetailedEventListener events are not fired if the animation is part of a transaction.
 213          */
 214         result AddControlAnimatorDetailedEventListener(IControlAnimatorDetailedEventListener& listener);
 215
 216
 217         /**
 218          * Removes an IControlAnimatorDetailedEventListener instance from the current instance of the control. @n
 219          * The removed listener cannot listen to events when they are fired.
 220          *
 221          * @since               2.0
 222          *
 223          * @return              An error code
 224          * @param[in]   listener                                The listener to remove
 225          * @exception   E_SUCCESS                               The method is successful.
 226          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 227          * @exception   E_UNSUPPORTED_OPERATION The animation support is unavailable.
 228          * @exception   E_SYSTEM                                A system error has occurred.
 229          */
 230         result RemoveControlAnimatorDetailedEventListener(IControlAnimatorDetailedEventListener& listener);
 231
 232
 233         /**
 234          * Sets an animation group for the specified trigger type.
 235          *
 236          * @since               2.0
 237          *
 238          * @return              An error code
 239          * @param[in]   animTrigger                             The animator trigger type to which the animation is applied
 240          * @param[in]   pAnimation                              An object of type AnimationBase @n
 241          *                                                                              If @c null is passed, the default animation values are used for animation with the specified trigger type.
 242          * @exception   E_SUCCESS                               The method is successful.
 243          * @exception   E_UNSUPPORTED_OPTION    The specified option is not supported.
 244          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 245          * @exception   E_SYSTEM                                A system error has occurred.
 246          * @remarks @c ANIMATION_TRIGGER_USER is not supported. @n
 247          *          The @c holdEnd value and @c AutoReverse value are set to @c true and @c false respectively. @n
 248          *          An exception is returned if the animation group does not contain an animation with the target type that is being animated for the specified
 249          *                      trigger type. The start value of an animation object of the associated target type for the specified trigger type is overwritten by the
 250          *                      current property value of the Tizen::Ui::Control instance and the end value is overwritten by the value that is being set by the user. @n
 251          *          The associated target types for each trigger are as below: @n
 252          *          \verbatim
 253          *                      Animation Trigger                   -   Target Type
 254          *                      ANIMATION_TRIGGER_POSITION_CHANGE   -   ANIMATION_TARGET_POSITION
 255          *                      ANIMATION_TRIGGER_SIZE_CHANGE       -   ANIMATION_TARGET_SIZE
 256          *                      ANIMATION_TRIGGER_SHOW_STATE_CHANGE -   ANIMATION_TARGET_ALPHA
 257          *                      \endverbatim
 258          */
 259         result SetAnimation(ControlAnimatorTriggerType animTrigger, const AnimationGroup* pAnimation);
 260
 261
 262         /**
 263          * Gets a group of animations.
 264          *
 265          * @since               2.0
 266          *
 267          * @return      An animation group object at the specified animation trigger type, @n
 268          *                              else @c null if the animation is empty or AnimationTriggerType is @c ANIMATION_TRIGGER_USER
 269          * @param[in]   animTrigger                     The animator trigger type to get an animation group object
 270          */
 271         AnimationGroup* GetAnimationN(ControlAnimatorTriggerType animTrigger) const;
 272
 273
 274         /**
 275          * Sets the position of the control. @n
 276          * An animation is played while changing the position of the control.
 277          *
 278          * @since               2.0
 279          *
 280          * @return              An error code
 281          * @param[in]   x                       The new X position of the object
 282          * @param[in]   y                       The new Y position of the object
 283          * @exception   E_SUCCESS               The method is successful.
 284          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 285          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 286          * @exception   E_SYSTEM                        A system error has occurred.
 287          * @remarks  The X and Y position of the object are relative to the top-left corner of its parent. @n
 288          *           Control::Invalidate() need not be called to display the control. The animation uses linear interpolator and is played for a default duration if
 289          *                       the user does not overwrite the values using SetAnimation().
 290          * @see         SetBounds()
 291          * @see     SetSize()
 292          */
 293         result SetPosition(int x, int y);
 294
 295
 296         /**
 297          * Sets the position of the control. @n
 298          * An animation is played while changing the position of the control.
 299          *
 300          * @since               2.0
 301          *
 302          * @return      An error code
 303          * @param[in]   Position                The new position
 304          * @exception   E_SUCCESS                       The method is successful.
 305          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 306          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 307          * @exception   E_SYSTEM                A system error has occurred.
 308          * @remarks             The position of the object is relative to the top-left corner of its parent. @n
 309          *              Control::Invalidate() need not be called to display the control. @n
 310          *                              The animation uses linear interpolator and is played for a default duration if the user does not overwrite the values using SetAnimation().
 311          * @see         SetPosition()
 312          * @see         SetBounds()
 313          * @see         SetSize()
 314          */
 315         result SetPosition(const Tizen::Graphics::Point& Position);
 316
 317
 318         /**
 319          * Sets the size of the control. @n
 320          * An animation is played while changing the size of the control. @n
 321          * The @c width and @c height parameters contain the width and height values of the object, respectively.
 322          *
 323          * @since               2.0
 324          *
 325          * @return      An error code
 326          * @param[in]   width                   The new width of the object
 327          * @param[in]   height                  The new height of the object
 328          * @exception   E_SUCCESS               The method is successful.
 329          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 330          *                                      The value of @c width or @c height is @c 0 or a negative value.
 331          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 332          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 333          * @exception   E_SYSTEM                A system error has occurred.
 334          * @remarks             Control::Invalidate() need not be called to display the control. @n
 335          *                              The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
 336          * @see         SetBounds()
 337          * @see         SetPosition()
 338          */
 339         result SetSize(int width, int height);
 340
 341
 342         /**
 343          * Sets the size of the control. @n
 344          * An animation is played while changing the size of the control. @n
 345          * The @c width becomes @c size.width, and the @c height becomes @c size.height.
 346          *
 347          * @since               2.0
 348          *
 349          * @return              An error code
 350          * @param[in]   size                    The new width and height
 351          * @exception   E_SUCCESS               The method is successful.
 352          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 353          *                                      The value @c size.width or @c size.height is @c 0 or a negative value.
 354          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 355          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 356          * @exception   E_SYSTEM                        A system error has occurred.
 357          * @remarks             Control::Invalidate() need not be called to display the control. @n
 358          *                              The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
 359          * @see                 SetSize()
 360          * @see         SetBounds()
 361          * @see         SetPosition()
 362          */
 363         result SetSize(const Tizen::Graphics::Dimension& size);
 364
 365
 366         /**
 367          * Sets the position and size of the control. @n
 368          * An animation is played while changing the position and size of the control. @n
 369          * The position is set to (x, y), and the @c width and @c height parameters contain the width and height values of the object, respectively.
 370          *
 371          * @since               2.0
 372          *
 373          * @return              An error code
 374          * @param[in]    x                      The new X position of the object
 375          * @param[in]    y                      The new Y position of the object
 376          * @param[in]   width                   The new width of the object
 377          * @param[in]   height                  The new height of the object
 378          * @exception   E_SUCCESS                               The method is successful.
 379          * @exception   E_INVALID_ARG                   A specified input parameter is invalid. @n
 380          *                                      The value of @c width or @c height is @c 0 or a negative value.
 381          * @exception   E_SYSTEM                                A system error has occurred.
 382          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 383          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 384          * @remarks     Changing the position of a parent object does not change the position of its children, the top-left position that is relative to the
 385          *                              top-left corner of the parent container. If calling this method causes re-positioning of an object or changes the size of the object, the
 386          *                              system redraws the object and all its children. @n
 387          *              Control::Invalidate() need not be called to display the control. @n
 388          *                              The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
 389          * @see         SetPosition()
 390          * @see         SetSize()
 391          */
 392         result SetBounds(int x, int y, int width, int height);
 393
 394
 395         /**
 396          * Sets the position and size of the control. @n
 397          * An animation is played while changing the position and size of the control.
 398          *
 399          * @since               2.0
 400          *
 401          * @return              An error code
 402          * @param[in]   rect                                    The new bounds of the object
 403          * @exception   E_SUCCESS                               The method is successful.
 404          * @exception   E_INVALID_ARG                   A specified input parameter is invalid. @n
 405          *                                      The value of @c rect.width or @c rect.height is @c 0 or a negative value.
 406          * @exception   E_SYSTEM                                A system error has occurred.
 407          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 408          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 409          * @remarks             Control::Invalidate() need not be called to display the control. @n
 410          *                              The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
 411          * @see         SetBounds()
 412          * @see         SetPosition()
 413          * @see         SetSize()
 414          */
 415         result SetBounds(const Tizen::Graphics::Rectangle& rect);
 416
 417
 418         /**
 419          * Sets the show state of the control with animation.
 420          *
 421          * @since               2.0
 422          *
 423          * @return              An error code
 424          * @param[in]   show                                    The show state of the object
 425          * @exception   E_SUCCESS                               The method is successful.
 426          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 427          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 428          * @exception   E_SYSTEM                                A system error has occurred.
 429          * @remarks             Control::Invalidate() need not be called to display the control. @n
 430          *                              The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
 431          */
 432         result SetShowState(bool show);
 433
 434
 435         /**
 436          * Checks whether animation is supported for the control with the specified target type.
 437          *
 438          * @since               2.0
 439          *
 440          * @return              @c true if animation is supported, @n
 441          *                              else @c false
 442          * @param[in]   animTarget      The animation target
 443          */
 444         bool IsAnimationSupported(AnimationTargetType animTarget) const;
 445
 446 protected:
 447
 448         friend class _ControlAnimatorImpl;
 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         // The variable for internal usage.
 456         //
 457         // @since  2.0
 458         //
 459         class _ControlAnimatorImpl* _pControlAnimatorImpl;
 460
 461
 462 private:
 463
 464         //
 465         // This method is for internal use only. Using this method can cause behavioral, security-related,
 466         // and consistency-related issues in the application.
 467         //
 468         // This is the constructor for this class.
 469         //
 470         // @since       2.0
 471         //
 472         ControlAnimator(void);
 473
 474
 475         //
 476         // This method is for internal use only. Using this method can cause behavioral, security-related,
 477         // and consistency-related issues in the application.
 478         //
 479         // Initializes this class.
 480         //
 481         // @since               2.0
 482         // @return              An error code
 483         // @param[in]   source                          An instance of control class
 484         // @exception   E_SUCCESS                       The method is successful.
 485         // @exception   E_SYSTEM                        A system error has occurred.
 486         //
 487         result Construct(const Tizen::Ui::Control& source);
 488
 489
 490         //
 491         // This method is for internal use only. Using this method can cause behavioral, security-related,
 492         // and consistency-related issues in the application.
 493         //
 494         // This is the copy constructor for this class.
 495         //
 496         // @since       2.0
 497         //
 498         ControlAnimator(const ControlAnimator& animator);
 499
 500
 501         //
 502         // This method is for internal use only. Using this method can cause behavioral, security-related,
 503         // and consistency-related issues in the application.
 504         //
 505         // Assigns the value of the specified instance to the current instance of %ControlAnimator.
 506
 507         //
 508         // @since        2.0
 509         //
 510         ControlAnimator& operator =(const ControlAnimator& rhs);
 511
 512
 513         friend class Tizen::Ui::_ControlImpl;
 514         friend class FrameAnimator;
 515 };              // ControlAnimator
 516
 517
 518 }}}             // Tizen::Ui::Animations
 519
 520 #endif //_FUI_ANIM_CONTROL_ANIMATOR_H_