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