inc/FUiAnimAnimationTransaction.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        FUiAnimAnimationTransaction.h
  20  * @brief       This is the header file for the %AnimationTransaction class.
  21  *
  22  * This header file contains the declarations of the %AnimationTransaction class.
  23  */
  24
  25 #ifndef _FUI_ANIM_ANIMATION_TRANSACTION_H_
  26 #define _FUI_ANIM_ANIMATION_TRANSACTION_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseObject.h>
  30
  31 #include <FUiAnimAnimationBase.h>
  32 #include <FUiAnimVisualElementAnimation.h>
  33 #include <FUiAnimIAnimationTransactionEventListener.h>
  34
  35
  36 namespace Tizen { namespace Ui { namespace Animations
  37 {
  38
  39 class IVisualElementAnimationTimingFunction;
  40 class IVisualElementAnimationValueInterpolator;
  41
  42 /**
  43  * @class       AnimationTransaction
  44  * @brief       This class defines the transaction operations of the animation.
  45  *
  46  * @since       2.0
  47  *
  48  * The %AnimationTransaction class enables the applications to define animation transactions that make a set of animations on one or more animators to start or stop at the same time.
  49  *
  50  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/transactions.htm">Transactions</a>.
  51  *
  52  */
  53 class _OSP_EXPORT_ AnimationTransaction
  54 {
  55 public:
  56
  57         /**
  58          * Initializes a transaction set. @n
  59          * Calls ControlAnimator::StartUserAnimation() or calls VisualElement::AddAnimation()
  60          * after calling the %Begin() method and before calling the CommitTransaction() method.
  61          * Nesting of the transaction set is allowed.
  62          *
  63          * @since               2.0
  64          *
  65          * @return              An error code
  66          * @exception   E_SUCCESS                       The method is successful.
  67          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
  68          */
  69         static result Begin(void);
  70
  71
  72         /**
  73          * Initializes a transaction set. @n
  74          * Calls ControlAnimator::StartUserAnimation() or calls VisualElement::AddAnimation()
  75          * after calling the %Begin() method and before calling the CommitTransaction() method.
  76          * Nesting of the transaction set is allowed.
  77          *
  78          * @since               2.0
  79          *
  80          * @return              An error code
  81          * @param[out]  transactionId           The transaction ID @n
  82          *                                  Use this transaction ID for further operations related to this transaction.
  83          * @exception   E_SUCCESS                       The method is successful.
  84          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
  85          */
  86         static result Begin(int& transactionId);
  87
  88
  89         /**
  90          * Commits a set of animation start commands that are added during the current transaction.
  91          *
  92          * @since               2.0
  93          *
  94          * @return              An error code
  95          * @exception   E_SUCCESS                       The method is successful.
  96          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
  97          */
  98         static result Commit(void);
  99
 100
 101         /**
 102          * Stops the transaction. @n
 103          * All the nested transactions also will be stopped.
 104          *
 105          * @since               2.0
 106          *
 107          * @return              An error code
 108          * @param[in]   transactionId   The transaction ID
 109          * @exception   E_SUCCESS               The method is successful.
 110          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 111          */
 112         static result Stop(int transactionId);
 113
 114
 115         /**
 116          * Discards all inactive transactions.
 117          *
 118          * @since       2.0
 119          *
 120          * @return      An error code
 121          * @exception   E_SUCCESS               The method is successful.
 122          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 123          * @see         Begin()
 124          */
 125         static result Discard(void);
 126
 127
 128         /**
 129          * Gets the status of the specified transaction.
 130          *
 131          * @since               2.0
 132          *
 133          * @return              The state of the transaction
 134          * @param[in]   transactionId   The transaction ID
 135          * @exception   E_SUCCESS               The method is successful.
 136          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 137          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 138          */
 139         static AnimationTransactionStatus GetStatus(int transactionId);
 140
 141
 142         /**
 143          * Sets a default event listener to listen to the events of transactions. @n
 144          * The set listener can listen to the events on the specified event dispatcher's context when they are fired.
 145          *
 146          * @since               2.0
 147          *
 148          * @return              An error code
 149          * @param[in]   pListener               The listener to add
 150          * @exception   E_SUCCESS               The method is successful.
 151          * @remarks             Only one event listener can be set. @n
 152          *              If @c pListener is @c null, the listener already set is unregistered. @n
 153          *              An application must deregister the registered listener if the listener object needs to be deleted.
 154          * @see                 SetCurrentTransactionEventListener()
 155          */
 156         static result SetTransactionEventListener(IAnimationTransactionEventListener* pListener);
 157
 158
 159         /**
 160          * Sets a listener instance to listen to the events of a current transaction. @n
 161          * The set listener can listen to the events on the specified event dispatcher's context when they are fired.
 162          *
 163          * @since               2.0
 164          *
 165          * @return              An error code
 166          * @param[in]   pListener               The listener to set
 167          * @exception   E_SUCCESS               The method is successful.
 168          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 169          * @remarks             If the listener is set using this method, the set default listener is not called.
 170          * @see                 SetTransactionEventListener()
 171          */
 172         static result SetCurrentTransactionEventListener(IAnimationTransactionEventListener* pListener);
 173
 174
 175         /**
 176          * Enables or disables the implicit animation on the current transaction. @n
 177          * If enabled, implicit animations may be created whenever animatable properties of this instance change.
 178          *
 179          * @since               2.0
 180          *
 181          * @return              An error code
 182          * @param[in]   enable  Set to @c true to enable the implicit animation, @n
 183          *                                              else @c false
 184          * @exception   E_SUCCESS                       The method is successful.
 185          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 186          * @remarks             The nested transaction created after invoking this method will inherit @c enable as the default value.
 187          * @remarks             Deciding whether to enable implicit animation depends on both the flag of transaction and the flag of VisualElement.
 188          *                              If both SetVisualElementImplicitAnimationEnabled() and VisualElement::SetImplicitAnimationEnabled() are set to @c true, @n
 189          *                              implicit animation is enabled.
 190          */
 191         static result SetVisualElementImplicitAnimationEnabled(bool enable);
 192
 193
 194         /**
 195          * Sets a default event listener to get the status of an animation. @n
 196          * The IVisualElementAnimationStatusEventListener listener is called for status changes of animation.
 197          * The added listener listens to events on the specified event dispatcher's context when they are fired.
 198          *
 199          * @since       2.0
 200          *
 201          * @return      An error code
 202          * @param[in]   pListener       The pointer of listener instance to set
 203          * @exception   E_SUCCESS       The method is successful.
 204          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 205          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 206          */
 207         static result SetVisualElementAnimationStatusEventListener(IVisualElementAnimationStatusEventListener* pListener);
 208
 209
 210         /**
 211          * Sets the default timing function of an animation.
 212          *
 213          * @since       2.0
 214          *
 215          * @return      An error code
 216          * @param[in]   pTimingFunction         The reference of interpolator instance to set
 217          * @exception   E_SUCCESS               The method is successful.
 218          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 219          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 220          */
 221         static result SetVisualElementAnimationTimingFunction(const IVisualElementAnimationTimingFunction* pTimingFunction);
 222
 223
 224         /**
 225          * Sets the default value interpolator of an animation.
 226          *
 227          * @since       2.0
 228          *
 229          * @return      An error code
 230          * @param[in]   pValueInterpolator      The reference of InterpolatorFunction instance to set
 231          * @exception   E_SUCCESS               The method is successful.
 232          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 233          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 234          */
 235         static result SetVisualElementAnimationValueInterpolator(const IVisualElementAnimationValueInterpolator* pValueInterpolator);
 236
 237
 238         /**
 239          * Sets the default duration of an animation in the current transaction.
 240          *
 241          * @since       2.0
 242          *
 243          * @return      An error code
 244          * @param[in]   milliseconds    The duration of the animation in milliseconds
 245          * @exception   E_SUCCESS               The method is successful.
 246          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 247          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or lesser than the offset of the animation.
 248          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 249          * @see         GetVisualElementAnimationDuration()
 250          */
 251         static result SetVisualElementAnimationDuration(long milliseconds);
 252
 253
 254         /**
 255          * Gets the default duration of an animation in milliseconds in the current transaction.
 256          *
 257          * @since       2.0
 258          *
 259          * @return      The duration value of the animation
 260          * @exception   E_SUCCESS               The method is successful.
 261          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 262          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 263          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 264          * @see         SetVisualElementAnimationDuration()
 265          */
 266         static long GetVisualElementAnimationDuration(void);
 267
 268
 269         /**
 270          * Sets the default offset value of an animation. @n
 271          * Additionally, the %SetVisualElementAnimationOffset() method alters the start value and duration for which an animation is played.
 272          *
 273          * @since       2.0
 274          *
 275          * @return      An error code
 276          * @param[in]   milliseconds            The offset value of the animation in milliseconds
 277          * @exception   E_SUCCESS               The method is successful.
 278          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 279          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or greater than the duration of the animation.
 280          * @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,
 281          *              the actual animation starts at @c 0th ms and plays for @c 80 ms with a start value of @c 0.2. @n
 282          *                              If @c autoReverse is set to @c true, the Backward animation plays for @c 100ms, from @c 1.0 to @c 0.0.
 283          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 284          * @see         GetVisualElementAnimationOffset()
 285          */
 286         static result SetVisualElementAnimationOffset(long milliseconds);
 287
 288
 289         /**
 290          * Gets the default offset value in milliseconds after an animation starts.
 291          *
 292          * @since       2.0
 293          *
 294          * @return      The offset value of the animation in milliseconds @n
 295          *                      The default value of the offset is @c 0.
 296          * @exception   E_SUCCESS               The method is successful.
 297          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 298          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 299          * @remarks     This is used as the default value for newly created VisualElementAnimation class or its descendant classes in the current transaction.
 300          * @see         SetVisualElementAnimationOffset()
 301          */
 302         static long GetVisualElementAnimationOffset(void);
 303
 304
 305         /**
 306          * Sets the default delay for an animation. @n
 307          * The animation starts after the duration of delay has passed.
 308          *
 309          * @since       2.0
 310          *
 311          * @return      An error code
 312          * @param[in]   milliseconds            The delay for the animation to start in milliseconds
 313          * @exception   E_SUCCESS               The method is successful.
 314          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 315          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 316          * @remarks     This method does not alter the start, end, and duration values of the animation.
 317          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 318          * @see         GetVisualElementAnimationDelay()
 319          */
 320         static result SetVisualElementAnimationDelay(long milliseconds);
 321
 322
 323         /**
 324          * Gets the default delay value in milliseconds before an animation starts.
 325          *
 326          * @since       2.0
 327          *
 328          * @return      The delay value in milliseconds @n
 329          *              The default value of the delay is @c 0.
 330          * @exception   E_SUCCESS               The method is successful.
 331          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 332          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 333          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 334          * @see         SetVisualElementAnimationDelay()
 335          */
 336         static long GetVisualElementAnimationDelay(void);
 337
 338
 339         /**
 340          * Sets the default repeat count for an animation. @n
 341          * Repeats an animation for the specified number of times.
 342          *
 343          * @since       2.0
 344          *
 345          * @return      An error code
 346          * @param[in]   count                   The number of times the animation has to repeat
 347          * @exception   E_SUCCESS               The method is successful.
 348          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 349          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 350          * @remarks     A delay and offset is applied to an animation only when the animation is played for the first time.
 351          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 352          * @see         GetVisualElementAnimationRepeatCount()
 353          */
 354         static result SetVisualElementAnimationRepeatCount(long count);
 355
 356
 357         /**
 358          * Gets the default repeat count value of an animation.
 359          *
 360          * @since       2.0
 361          *
 362          * @return      The repeat count value of the animation @n
 363          *              The default value of the repeat count is @c 1.
 364          * @exception   E_SUCCESS               The method is successful.
 365          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 366          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 367          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 368          * @see         SetVisualElementAnimationRepeatCount()
 369          */
 370         static long GetVisualElementAnimationRepeatCount(void);
 371
 372
 373         /**
 374          * Sets the default AutoReverse property of an animation. @n
 375          * If enabled, the forward and backward animation can also be played.
 376          *
 377          * @since       2.0
 378          *
 379          * @param[in]   autoReverse     Set to @c true to enable the AutoReverse property of the animation, @n
 380          *                              else @c false
 381          * @exception   E_SUCCESS               The method is successful.
 382          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 383          * @remarks     If @c autoReverse is set to @c true, the duration of the animation is doubled.
 384          *                              If the repeat count is more than @c 1, @c autoReverse is applied to each iteration.
 385          *              Note that if @c autoReverse is set to @c true, one forward animation play
 386          *                              and one backward animation play is one iteration.
 387          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 388          * @see         IsVisualElementAnimationAutoReverseEnabled()
 389          */
 390         static result SetVisualElementAnimationAutoReverseEnabled(bool autoReverse);
 391
 392
 393         /**
 394          * Checks whether the auto reverse is enabled.
 395          *
 396          * @since       2.0
 397          *
 398          * @return      @c true if the auto reverse is enabled, @n
 399          *              else @c false @n
 400          *              The default auto reverse value is @c false.
 401          * @exception   E_SUCCESS               The method is successful.
 402          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 403          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 404          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 405          * @see         SetVisualElementAnimationAutoReverseEnabled()
 406          */
 407         static bool IsVisualElementAnimationAutoReverseEnabled(void);
 408
 409
 410         /**
 411          * Sets the default scale ratio of an animation. @n
 412          * The %SetVisualElementAnimationScaleRatio() method multiplies the duration, offset and delay using the scale ratio.
 413          *
 414          * @since       2.0
 415          *
 416          * @return      An error code
 417          * @param[in]   scaleRatio              The scale ratio property of the animation
 418          * @exception   E_SUCCESS               The method is successful.
 419          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 420          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 421          * @remarks     This is used as the default value for the newly created VisualElementAnimation or its descendant classes in the current transaction.
 422          * @see         GetVisualElementAnimationScaleRatio()
 423          */
 424         static result SetVisualElementAnimationScaleRatio(float scaleRatio);
 425
 426
 427         /**
 428          * Gets the default scale ratio value of an animation.
 429          *
 430          * @since       2.0
 431          *
 432          * @return      The scale ratio value of the animation @n
 433          *              The default value of scale ratio is @c 1.0f.
 434          * @exception   E_SUCCESS               The method is successful.
 435          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 436          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 437          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 438          * @see         SetVisualElementAnimationScaleRatio()
 439          */
 440         static float GetVisualElementAnimationScaleRatio(void);
 441
 442
 443 private:
 444
 445         //
 446         // This method is for internal use only. Using this method can cause behavioral, security-related,
 447         // and consistency-related issues in the application.
 448         //
 449         // This is the default constructor for this class.
 450         //
 451         // @since       2.0
 452         //
 453         AnimationTransaction(void);
 454
 455
 456         //
 457         // This method is for internal use only. Using this method can cause behavioral, security-related,
 458         // and consistency-related issues in the application.
 459         //
 460         // This is the destructor for this class.
 461         //
 462         // @since       2.0
 463         //
 464         ~AnimationTransaction(void);
 465
 466
 467         //
 468         // This method is for internal use only. Using this method can cause behavioral, security-related,
 469         // and consistency-related issues in the application.
 470         //
 471         // This is the copy constructor for the %AnimationTransaction class.
 472         //
 473         // @since               2.0
 474         // @param[in]   transaction             An instance of %AnimationTransaction
 475         //
 476         AnimationTransaction(const AnimationTransaction& transaction);
 477
 478
 479         //
 480         // This method is for internal use only. Using this method can cause behavioral, security-related,
 481         // and consistency-related issues in the application.
 482         //
 483         // Assigns the value of the specified instance to the current instance of %AnimationTransaction.
 484         //
 485         // @since               2.0
 486         //
 487         // @param[in]   rhs                             An instance of %AnimationTransaction
 488         //
 489         AnimationTransaction& operator =(const AnimationTransaction& rhs);
 490 };              // AnimationTransaction
 491
 492
 493 }}}             // Tizen::Ui::Animations
 494
 495 #endif  // _FUI_ANIM_ANIMATION_TRANSACTION_H_