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          * @remarks     When the animation which is listening to an animation status event is removed before starting, the platform skips to call @n
 207          *                      the IVisualElementAnimationStatusEventListener::OnVisualElementAnimationStarted() method and directly calls the IVisualElementAnimationStatusEventListener::OnVisualElementAnimationFinished() method.
 208          */
 209         static result SetVisualElementAnimationStatusEventListener(IVisualElementAnimationStatusEventListener* pListener);
 210
 211
 212         /**
 213          * Sets the default timing function of an animation.
 214          *
 215          * @since       2.0
 216          *
 217          * @return      An error code
 218          * @param[in]   pTimingFunction         The reference of interpolator instance to set
 219          * @exception   E_SUCCESS               The method is successful.
 220          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 221          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 222          */
 223         static result SetVisualElementAnimationTimingFunction(const IVisualElementAnimationTimingFunction* pTimingFunction);
 224
 225
 226         /**
 227          * Sets the default value interpolator of an animation.
 228          *
 229          * @since       2.0
 230          *
 231          * @return      An error code
 232          * @param[in]   pValueInterpolator      The reference of InterpolatorFunction instance to set
 233          * @exception   E_SUCCESS               The method is successful.
 234          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 235          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 236          */
 237         static result SetVisualElementAnimationValueInterpolator(const IVisualElementAnimationValueInterpolator* pValueInterpolator);
 238
 239
 240         /**
 241          * Sets the default duration of an animation in the current transaction.
 242          *
 243          * @since       2.0
 244          *
 245          * @return      An error code
 246          * @param[in]   milliseconds    The duration of the animation in milliseconds
 247          * @exception   E_SUCCESS               The method is successful.
 248          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 249          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or lesser than the offset of the animation.
 250          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 251          * @see         GetVisualElementAnimationDuration()
 252          */
 253         static result SetVisualElementAnimationDuration(long milliseconds);
 254
 255
 256         /**
 257          * Gets the default duration of an animation in milliseconds in the current transaction.
 258          *
 259          * @since       2.0
 260          *
 261          * @return      The duration value of the animation
 262          * @exception   E_SUCCESS               The method is successful.
 263          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 264          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 265          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 266          * @see         SetVisualElementAnimationDuration()
 267          */
 268         static long GetVisualElementAnimationDuration(void);
 269
 270
 271         /**
 272          * Sets the default offset value of an animation. @n
 273          * Additionally, the %SetVisualElementAnimationOffset() method alters the start value and duration for which an animation is played.
 274          *
 275          * @since       2.0
 276          *
 277          * @return      An error code
 278          * @param[in]   milliseconds            The offset value of the animation in milliseconds
 279          * @exception   E_SUCCESS               The method is successful.
 280          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 281          * @exception   E_INVALID_ARG           The value of the specified parameter is negative or greater than the duration of the animation.
 282          * @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,
 283          *              the actual animation starts at @c 0th ms and plays for @c 80 ms with a start value of @c 0.2. @n
 284          *                              If @c autoReverse is set to @c true, the Backward animation plays for @c 100ms, from @c 1.0 to @c 0.0.
 285          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 286          * @see         GetVisualElementAnimationOffset()
 287          */
 288         static result SetVisualElementAnimationOffset(long milliseconds);
 289
 290
 291         /**
 292          * Gets the default offset value in milliseconds after an animation starts.
 293          *
 294          * @since       2.0
 295          *
 296          * @return      The offset value of the animation in milliseconds @n
 297          *                      The default value of the offset is @c 0.
 298          * @exception   E_SUCCESS               The method is successful.
 299          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 300          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 301          * @remarks     This is used as the default value for newly created VisualElementAnimation class or its descendant classes in the current transaction.
 302          * @see         SetVisualElementAnimationOffset()
 303          */
 304         static long GetVisualElementAnimationOffset(void);
 305
 306
 307         /**
 308          * Sets the default delay for an animation. @n
 309          * The animation starts after the duration of delay has passed.
 310          *
 311          * @since       2.0
 312          *
 313          * @return      An error code
 314          * @param[in]   milliseconds            The delay for the animation to start in milliseconds
 315          * @exception   E_SUCCESS               The method is successful.
 316          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 317          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 318          * @remarks     This method does not alter the start, end, and duration values of the animation.
 319          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 320          * @see         GetVisualElementAnimationDelay()
 321          */
 322         static result SetVisualElementAnimationDelay(long milliseconds);
 323
 324
 325         /**
 326          * Gets the default delay value in milliseconds before an animation starts.
 327          *
 328          * @since       2.0
 329          *
 330          * @return      The delay value in milliseconds @n
 331          *              The default value of the delay is @c 0.
 332          * @exception   E_SUCCESS               The method is successful.
 333          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 334          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 335          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 336          * @see         SetVisualElementAnimationDelay()
 337          */
 338         static long GetVisualElementAnimationDelay(void);
 339
 340
 341         /**
 342          * Sets the default repeat count for an animation. @n
 343          * Repeats an animation for the specified number of times.
 344          *
 345          * @since       2.0
 346          *
 347          * @return      An error code
 348          * @param[in]   count                   The number of times the animation has to repeat
 349          * @exception   E_SUCCESS               The method is successful.
 350          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 351          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 352          * @remarks     A delay and offset is applied to an animation only when the animation is played for the first time.
 353          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 354          * @see         GetVisualElementAnimationRepeatCount()
 355          */
 356         static result SetVisualElementAnimationRepeatCount(long count);
 357
 358
 359         /**
 360          * Gets the default repeat count value of an animation.
 361          *
 362          * @since       2.0
 363          *
 364          * @return      The repeat count value of the animation @n
 365          *              The default value of the repeat count is @c 1.
 366          * @exception   E_SUCCESS               The method is successful.
 367          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 368          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 369          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 370          * @see         SetVisualElementAnimationRepeatCount()
 371          */
 372         static long GetVisualElementAnimationRepeatCount(void);
 373
 374
 375         /**
 376          * Sets the default AutoReverse property of an animation. @n
 377          * If enabled, the forward and backward animation can also be played.
 378          *
 379          * @since       2.0
 380          *
 381          * @param[in]   autoReverse     Set to @c true to enable the AutoReverse property of the animation, @n
 382          *                              else @c false
 383          * @exception   E_SUCCESS               The method is successful.
 384          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 385          * @remarks     If @c autoReverse is set to @c true, the duration of the animation is doubled.
 386          *                              If the repeat count is more than @c 1, @c autoReverse is applied to each iteration.
 387          *              Note that if @c autoReverse is set to @c true, one forward animation play
 388          *                              and one backward animation play is one iteration.
 389          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 390          * @see         IsVisualElementAnimationAutoReverseEnabled()
 391          */
 392         static result SetVisualElementAnimationAutoReverseEnabled(bool autoReverse);
 393
 394
 395         /**
 396          * Checks whether the auto reverse is enabled.
 397          *
 398          * @since       2.0
 399          *
 400          * @return      @c true if the auto reverse is enabled, @n
 401          *              else @c false @n
 402          *              The default auto reverse value is @c false.
 403          * @exception   E_SUCCESS               The method is successful.
 404          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 405          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 406          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 407          * @see         SetVisualElementAnimationAutoReverseEnabled()
 408          */
 409         static bool IsVisualElementAnimationAutoReverseEnabled(void);
 410
 411
 412         /**
 413          * Sets the default scale ratio of an animation. @n
 414          * The %SetVisualElementAnimationScaleRatio() method multiplies the duration, offset and delay using the scale ratio.
 415          *
 416          * @since       2.0
 417          *
 418          * @return      An error code
 419          * @param[in]   scaleRatio              The scale ratio property of the animation
 420          * @exception   E_SUCCESS               The method is successful.
 421          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 422          * @exception   E_INVALID_ARG           The value of the specified parameter is negative.
 423          * @remarks     This is used as the default value for the newly created VisualElementAnimation or its descendant classes in the current transaction.
 424          * @see         GetVisualElementAnimationScaleRatio()
 425          */
 426         static result SetVisualElementAnimationScaleRatio(float scaleRatio);
 427
 428
 429         /**
 430          * Gets the default scale ratio value of an animation.
 431          *
 432          * @since       2.0
 433          *
 434          * @return      The scale ratio value of the animation @n
 435          *              The default value of scale ratio is @c 1.0f.
 436          * @exception   E_SUCCESS               The method is successful.
 437          * @exception   E_INVALID_OPERATION     An uncommitted transaction does not exist.
 438          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 439          * @remarks     This is used as the default value for the newly created VisualElementAnimation class or its descendant classes in the current transaction.
 440          * @see         SetVisualElementAnimationScaleRatio()
 441          */
 442         static float GetVisualElementAnimationScaleRatio(void);
 443
 444
 445 private:
 446
 447         //
 448         // This method is for internal use only. Using this method can cause behavioral, security-related,
 449         // and consistency-related issues in the application.
 450         //
 451         // This is the default constructor for this class.
 452         //
 453         // @since       2.0
 454         //
 455         AnimationTransaction(void);
 456
 457
 458         //
 459         // This method is for internal use only. Using this method can cause behavioral, security-related,
 460         // and consistency-related issues in the application.
 461         //
 462         // This is the destructor for this class.
 463         //
 464         // @since       2.0
 465         //
 466         ~AnimationTransaction(void);
 467
 468
 469         //
 470         // This method is for internal use only. Using this method can cause behavioral, security-related,
 471         // and consistency-related issues in the application.
 472         //
 473         // This is the copy constructor for the %AnimationTransaction class.
 474         //
 475         // @since               2.0
 476         // @param[in]   transaction             An instance of %AnimationTransaction
 477         //
 478         AnimationTransaction(const AnimationTransaction& transaction);
 479
 480
 481         //
 482         // This method is for internal use only. Using this method can cause behavioral, security-related,
 483         // and consistency-related issues in the application.
 484         //
 485         // Assigns the value of the specified instance to the current instance of %AnimationTransaction.
 486         //
 487         // @since               2.0
 488         //
 489         // @param[in]   rhs                             An instance of %AnimationTransaction
 490         //
 491         AnimationTransaction& operator =(const AnimationTransaction& rhs);
 492 };              // AnimationTransaction
 493
 494
 495 }}}             // Tizen::Ui::Animations
 496
 497 #endif  // _FUI_ANIM_ANIMATION_TRANSACTION_H_