2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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.
19 * @file FUiAnimAnimationTransaction.h
20 * @brief This is the header file for the %AnimationTransaction class.
22 * This header file contains the declarations of the %AnimationTransaction class.
25 #ifndef _FUI_ANIM_ANIMATION_TRANSACTION_H_
26 #define _FUI_ANIM_ANIMATION_TRANSACTION_H_
28 #include <FBaseTypes.h>
29 #include <FBaseObject.h>
31 #include <FUiAnimAnimationBase.h>
32 #include <FUiAnimVisualElementAnimation.h>
33 #include <FUiAnimIAnimationTransactionEventListener.h>
36 namespace Tizen { namespace Ui { namespace Animations
39 class IVisualElementAnimationTimingFunction;
40 class IVisualElementAnimationValueInterpolator;
43 * @class AnimationTransaction
44 * @brief This class defines the transaction operations of the animation.
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.
50 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/transactions.htm">Transactions</a>.
53 class _OSP_EXPORT_ AnimationTransaction
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.
65 * @return An error code
66 * @exception E_SUCCESS The method is successful.
67 * @exception E_OUT_OF_MEMORY The memory is insufficient.
69 static result Begin(void);
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.
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.
86 static result Begin(int& transactionId);
90 * Commits a set of animation start commands that are added during the current transaction.
94 * @return An error code
95 * @exception E_SUCCESS The method is successful.
96 * @exception E_OUT_OF_MEMORY The memory is insufficient.
98 static result Commit(void);
102 * Stops the transaction. @n
103 * All the nested transactions also will be stopped.
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.
112 static result Stop(int transactionId);
116 * Discards all inactive transactions.
120 * @return An error code
121 * @exception E_SUCCESS The method is successful.
122 * @exception E_INVALID_OPERATION An uncommitted transaction does not exist.
125 static result Discard(void);
129 * Gets the status of the specified transaction.
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.
139 static AnimationTransactionStatus GetStatus(int transactionId);
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.
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()
156 static result SetTransactionEventListener(IAnimationTransactionEventListener* pListener);
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.
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()
172 static result SetCurrentTransactionEventListener(IAnimationTransactionEventListener* pListener);
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.
181 * @return An error code
182 * @param[in] enable Set to @c true to enable the implicit animation, @n
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.
191 static result SetVisualElementImplicitAnimationEnabled(bool enable);
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.
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.
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.
210 static result SetVisualElementAnimationStatusEventListener(IVisualElementAnimationStatusEventListener* pListener);
214 * Sets the default timing function of an animation.
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.
224 static result SetVisualElementAnimationTimingFunction(const IVisualElementAnimationTimingFunction* pTimingFunction);
228 * Sets the default value interpolator of an animation.
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.
238 static result SetVisualElementAnimationValueInterpolator(const IVisualElementAnimationValueInterpolator* pValueInterpolator);
242 * Sets the default duration of an animation in the current transaction.
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()
254 static result SetVisualElementAnimationDuration(long milliseconds);
258 * Gets the default duration of an animation in milliseconds in the current transaction.
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()
269 static long GetVisualElementAnimationDuration(void);
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.
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()
289 static result SetVisualElementAnimationOffset(long milliseconds);
293 * Gets the default offset value in milliseconds after an animation starts.
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()
305 static long GetVisualElementAnimationOffset(void);
309 * Sets the default delay for an animation. @n
310 * The animation starts after the duration of delay has passed.
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()
323 static result SetVisualElementAnimationDelay(long milliseconds);
327 * Gets the default delay value in milliseconds before an animation starts.
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()
339 static long GetVisualElementAnimationDelay(void);
343 * Sets the default repeat count for an animation. @n
344 * Repeats an animation for the specified number of times.
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()
357 static result SetVisualElementAnimationRepeatCount(long count);
361 * Gets the default repeat count value of an animation.
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()
373 static long GetVisualElementAnimationRepeatCount(void);
377 * Sets the default AutoReverse property of an animation. @n
378 * If enabled, the forward and backward animation can also be played.
382 * @param[in] autoReverse Set to @c true to enable the AutoReverse property of the animation, @n
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()
393 static result SetVisualElementAnimationAutoReverseEnabled(bool autoReverse);
397 * Checks whether the auto reverse is enabled.
401 * @return @c true if the auto reverse is enabled, @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()
410 static bool IsVisualElementAnimationAutoReverseEnabled(void);
414 * Sets the default scale ratio of an animation. @n
415 * The %SetVisualElementAnimationScaleRatio() method multiplies the duration, offset and delay using the scale ratio.
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()
427 static result SetVisualElementAnimationScaleRatio(float scaleRatio);
431 * Gets the default scale ratio value of an animation.
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()
443 static float GetVisualElementAnimationScaleRatio(void);
449 // This method is for internal use only. Using this method can cause behavioral, security-related,
450 // and consistency-related issues in the application.
452 // This is the default constructor for this class.
456 AnimationTransaction(void);
460 // This method is for internal use only. Using this method can cause behavioral, security-related,
461 // and consistency-related issues in the application.
463 // This is the destructor for this class.
467 ~AnimationTransaction(void);
471 // This method is for internal use only. Using this method can cause behavioral, security-related,
472 // and consistency-related issues in the application.
474 // This is the copy constructor for the %AnimationTransaction class.
477 // @param[in] transaction An instance of %AnimationTransaction
479 AnimationTransaction(const AnimationTransaction& transaction);
483 // This method is for internal use only. Using this method can cause behavioral, security-related,
484 // and consistency-related issues in the application.
486 // Assigns the value of the specified instance to the current instance of %AnimationTransaction.
490 // @param[in] rhs An instance of %AnimationTransaction
492 AnimationTransaction& operator =(const AnimationTransaction& rhs);
493 }; // AnimationTransaction
496 }}} // Tizen::Ui::Animations
498 #endif // _FUI_ANIM_ANIMATION_TRANSACTION_H_