2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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 FUiAnimControlAnimator.h
20 * @brief This is the header file for the %ControlAnimator class.
22 * This header file contains the declarations of the %ControlAnimator class.
25 #ifndef _FUI_ANIM_CONTROL_ANIMATOR_H_
26 #define _FUI_ANIM_CONTROL_ANIMATOR_H_
28 #include <FBaseTypes.h>
29 #include <FBaseString.h>
30 #include <FBaseObject.h>
31 #include <FBaseColArrayList.h>
32 #include <FBaseColArrayListT.h>
33 #include <FGrpPoint.h>
34 #include <FGrpRectangle.h>
35 #include <FGrpDimension.h>
36 #include <FUiControl.h>
37 #include <FUiAnimAnimationBase.h>
38 #include <FUiAnimSequentialAnimationGroup.h>
39 #include <FUiAnimParallelAnimationGroup.h>
40 #include <FUiAnimIControlAnimatorEventListener.h>
41 #include <FUiAnimIControlAnimatorDetailedEventListener.h>
43 namespace Tizen { namespace Ui { namespace Animations
47 * @class ControlAnimator
48 * @brief This class defines the animation methods for Tizen::Ui::Control.
52 * @final This class is not intended for extension.
54 * @remarks This class doesn't support APIs for float type.
56 * The %ControlAnimator class is used to control the animations operated in Tizen::Ui::Controls.
58 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/animating_uicontrols.htm">Animating UI Controls</a>.
61 class _OSP_EXPORT_ ControlAnimator
62 : public Tizen::Base::Object
67 * This is the destructor for this class.
71 virtual ~ControlAnimator(void);
75 * Starts an animation explicitly. @n
76 * If multiple controls need to be animated simultaneously, the controls must be part of the AnimationTransaction class. @n
77 * The %StartUserAnimation() method must be called after AnimationTransaction::Begin() and before AnimationTransaction::Commit().
81 * @return An error code
82 * @param[in] animTarget The property to animate
83 * @param[in] animation An object of type AnimationBase
84 * @exception E_SUCCESS The method is successful.
85 * @exception E_INVALID_ARG A specified input parameter is invalid.
86 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
87 * @exception E_SYSTEM A system error has occurred.
88 * @remarks An animation is deleted at the end of the animation playback. @n
89 * RectangleAnimation is used to animate only one animation target at a time.
90 * For example, if AnimationTarget is @c ANIMATION_TARGET_SIZE, RectangleAnimation performs only the dimension animation. @n
91 * To perform animation using the @c ANIMATION_TARGET_POSITION and @c ANIMATION_TARGET_SIZE properties, AnimationTransaction must be used with
92 * a separate call for each animation target.
94 result StartUserAnimation(AnimationTargetType animTarget, const AnimationBase& animation);
98 * Starts a group of animations explicitly. @n
99 * If multiple controls need to be animated simultaneously, the control must be part of the AnimationTransaction class.
100 * The %StartUserAnimation() method must be called after AnimationTransaction::Begin() and before AnimationTransaction::Commit().
104 * @return An error code
105 * @param[in] animGroup An animation group having a list of animations
106 * @exception E_SUCCESS The method is successful.
107 * @exception E_INVALID_ARG The specified input parameter is invalid.
108 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
109 * @exception E_SYSTEM A system error has occurred.
110 * @remarks The animations are deleted at the end of the animation playback. @n
111 * RectangleAnimation is used to animate only one animation target at a time.
113 result StartUserAnimation(const AnimationGroup& animGroup);
117 * Stops all the animations that are currently playing and jumps to the final frame of the animation.
121 * @return An error code
122 * @exception E_SUCCESS The method is successful.
123 * @exception E_SYSTEM A system error has occurred.
125 result StopAllAnimations(void);
129 * Stops the animation with the specified trigger type.
133 * @return An error code
134 * @param[in] animTrigger The animator trigger type
135 * @exception E_SUCCESS The method is successful.
136 * @exception E_INVALID_ARG The specified input parameter is invalid.
137 * @exception E_SYSTEM A system error has occurred.
139 result StopAnimation(ControlAnimatorTriggerType animTrigger);
143 * Gets the status of an animation with respect to a control.
147 * @return The animation state
149 AnimatorStatus GetStatus(void) const;
153 * Gets the status of an animation for the specified animation target type.
157 * @return The state of an animation with type @c animTarget
158 * @param[in] animTarget The animation target type
160 AnimatorStatus GetStatus(AnimationTargetType animTarget) const;
164 * Adds the IControlAnimatorEventListener listener instance to the current instance of the control. @n
165 * The %IControlAnimatorEventListener listener is called for status changes of animations associated with a control.
166 * The added listener listens to events on the specified event dispatcher's context when they are fired.
170 * @return An error code
171 * @param[in] listener The listener to add
172 * @exception E_SUCCESS The method is successful.
173 * @exception E_INVALID_ARG The specified input parameter is invalid.
174 * @exception E_UNSUPPORTED_OPERATION The animation support is unavailable.
175 * @exception E_OBJ_ALREADY_EXIST The specified @c listener is already added.
176 * @exception E_SYSTEM A system error has occurred.
177 * @remarks For animations that are part of AnimationTransaction, the applications need to listen to IAnimationTransactionEventListener events. @n
178 * The IControlAnimatorEventListener events are not fired if the animation is part of a transaction.
180 result AddControlAnimatorEventListener(IControlAnimatorEventListener& listener);
184 * Removes the IControlAnimatorEventListener listener instance from the current instance of the control. @n
185 * The removed listener cannot listen to events when they are fired.
189 * @return An error code
190 * @param[in] listener The listener to remove
191 * @exception E_SUCCESS The method is successful.
192 * @exception E_INVALID_ARG The specified input parameter is invalid.
193 * @exception E_UNSUPPORTED_OPERATION The animation support is unavailable.
194 * @exception E_SYSTEM A system error has occurred.
196 result RemoveControlAnimatorEventListener(IControlAnimatorEventListener& listener);
200 * Adds a IControlAnimatorDetailedEventListener listener instance to the current instance of the control. @n
201 * The %IControlAnimatorDetailedEventListener listener is called for status changes of each animation associated with the control. @n
202 * The added listener listens to events on the specified event dispatcher's context when they are fired.
206 * @return An error code
207 * @param[in] listener The listener to add
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_INVALID_ARG The specified input parameter is invalid.
210 * @exception E_UNSUPPORTED_OPERATION The animation support is unavailable.
211 * @exception E_OBJ_ALREADY_EXIST The specified @c listener is already added.
212 * @exception E_SYSTEM A system error has occurred.
213 * @remarks For animations that are part of AnimationTransaction, the applications need to listen to the IAnimationTransactionEventListener events. @n
214 * The IControlAnimatorDetailedEventListener events are not fired if the animation is part of a transaction.
216 result AddControlAnimatorDetailedEventListener(IControlAnimatorDetailedEventListener& listener);
220 * Removes an IControlAnimatorDetailedEventListener instance from the current instance of the control. @n
221 * The removed listener cannot listen to events when they are fired.
225 * @return An error code
226 * @param[in] listener The listener to remove
227 * @exception E_SUCCESS The method is successful.
228 * @exception E_INVALID_ARG The specified input parameter is invalid.
229 * @exception E_UNSUPPORTED_OPERATION The animation support is unavailable.
230 * @exception E_SYSTEM A system error has occurred.
232 result RemoveControlAnimatorDetailedEventListener(IControlAnimatorDetailedEventListener& listener);
236 * Sets an animation group for the specified trigger type.
240 * @return An error code
241 * @param[in] animTrigger The animator trigger type to which the animation is applied
242 * @param[in] pAnimation An object of type AnimationBase @n
243 * If @c null is passed, the default animation values are used for animation with the specified trigger type.
244 * @exception E_SUCCESS The method is successful.
245 * @exception E_UNSUPPORTED_OPTION The specified option is not supported.
246 * @exception E_INVALID_ARG A specified input parameter is invalid.
247 * @exception E_SYSTEM A system error has occurred.
248 * @remarks @c ANIMATION_TRIGGER_USER is not supported. @n
249 * The @c holdEnd value and @c AutoReverse value are set to @c true and @c false respectively. @n
250 * An exception is returned if the animation group does not contain an animation with the target type that is being animated for the specified
251 * trigger type. The start value of an animation object of the associated target type for the specified trigger type is overwritten by the
252 * current property value of the Tizen::Ui::Control instance and the end value is overwritten by the value that is being set by the user. @n
253 * The associated target types for each trigger are as below: @n
255 * Animation Trigger - Target Type
256 * ANIMATION_TRIGGER_POSITION_CHANGE - ANIMATION_TARGET_POSITION
257 * ANIMATION_TRIGGER_SIZE_CHANGE - ANIMATION_TARGET_SIZE
258 * ANIMATION_TRIGGER_SHOW_STATE_CHANGE - ANIMATION_TARGET_ALPHA
261 result SetAnimation(ControlAnimatorTriggerType animTrigger, const AnimationGroup* pAnimation);
265 * Gets a group of animations.
269 * @return An animation group object at the specified animation trigger type, @n
270 * else @c null if the animation is empty or AnimationTriggerType is @c ANIMATION_TRIGGER_USER
271 * @param[in] animTrigger The animator trigger type to get an animation group object
273 AnimationGroup* GetAnimationN(ControlAnimatorTriggerType animTrigger) const;
277 * Sets the position of the control. @n
278 * An animation is played while changing the position of the control.
282 * @return An error code
283 * @param[in] x The new X position of the object
284 * @param[in] y The new Y position of the object
285 * @exception E_SUCCESS The method is successful.
286 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
287 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
288 * @exception E_SYSTEM A system error has occurred.
289 * @remarks The X and Y position of the object are relative to the top-left corner of its parent. @n
290 * Control::Invalidate() need not be called to display the control. The animation uses linear interpolator and is played for a default duration if
291 * the user does not overwrite the values using SetAnimation().
295 result SetPosition(int x, int y);
299 * Sets the position of the control. @n
300 * An animation is played while changing the position of the control.
304 * @return An error code
305 * @param[in] Position The new position
306 * @exception E_SUCCESS The method is successful.
307 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
308 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
309 * @exception E_SYSTEM A system error has occurred.
310 * @remarks The position of the object is relative to the top-left corner of its parent. @n
311 * Control::Invalidate() need not be called to display the control. @n
312 * The animation uses linear interpolator and is played for a default duration if the user does not overwrite the values using SetAnimation().
317 result SetPosition(const Tizen::Graphics::Point& Position);
321 * Sets the size of the control. @n
322 * An animation is played while changing the size of the control. @n
323 * The @c width and @c height parameters contain the width and height values of the object, respectively.
327 * @return An error code
328 * @param[in] width The new width of the object
329 * @param[in] height The new height of the object
330 * @exception E_SUCCESS The method is successful.
331 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
332 * The value of @c width or @c height is @c 0 or a negative value.
333 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
334 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
335 * @exception E_SYSTEM A system error has occurred.
336 * @remarks Control::Invalidate() need not be called to display the control. @n
337 * The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
341 result SetSize(int width, int height);
345 * Sets the size of the control. @n
346 * An animation is played while changing the size of the control. @n
347 * The @c width becomes @c size.width, and the @c height becomes @c size.height.
351 * @return An error code
352 * @param[in] size The new width and height
353 * @exception E_SUCCESS The method is successful.
354 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
355 * The value @c size.width or @c size.height is @c 0 or a negative value.
356 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
357 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
358 * @exception E_SYSTEM A system error has occurred.
359 * @remarks Control::Invalidate() need not be called to display the control. @n
360 * The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
365 result SetSize(const Tizen::Graphics::Dimension& size);
369 * Sets the position and size of the control. @n
370 * An animation is played while changing the position and size of the control. @n
371 * The position is set to (x, y), and the @c width and @c height parameters contain the width and height values of the object, respectively.
375 * @return An error code
376 * @param[in] x The new X position of the object
377 * @param[in] y The new Y position of the object
378 * @param[in] width The new width of the object
379 * @param[in] height The new height of the object
380 * @exception E_SUCCESS The method is successful.
381 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
382 * The value of @c width or @c height is @c 0 or a negative value.
383 * @exception E_SYSTEM A system error has occurred.
384 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
385 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
386 * @remarks Changing the position of a parent object does not change the position of its children, the top-left position that is relative to the
387 * top-left corner of the parent container. If calling this method causes re-positioning of an object or changes the size of the object, the
388 * system redraws the object and all its children. @n
389 * Control::Invalidate() need not be called to display the control. @n
390 * The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
394 result SetBounds(int x, int y, int width, int height);
398 * Sets the position and size of the control. @n
399 * An animation is played while changing the position and size of the control.
403 * @return An error code
404 * @param[in] rect The new bounds of the object
405 * @exception E_SUCCESS The method is successful.
406 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
407 * The value of @c rect.width or @c rect.height is @c 0 or a negative value.
408 * @exception E_SYSTEM A system error has occurred.
409 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
410 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
411 * @remarks Control::Invalidate() need not be called to display the control. @n
412 * The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
417 result SetBounds(const Tizen::Graphics::Rectangle& rect);
421 * Sets the show state of the control with animation.
425 * @return An error code
426 * @param[in] show The show state of the object
427 * @exception E_SUCCESS The method is successful.
428 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
429 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
430 * @exception E_SYSTEM A system error has occurred.
431 * @remarks Control::Invalidate() need not be called to display the control. @n
432 * The animation uses linear interpolator and is played for a duration of @c 250 ms if the user does not overwrite the values using SetAnimation().
434 result SetShowState(bool show);
438 * Checks whether animation is supported for the control with the specified target type.
442 * @return @c true if animation is supported, @n
444 * @param[in] animTarget The animation target
446 bool IsAnimationSupported(AnimationTargetType animTarget) const;
450 friend class _ControlAnimatorImpl;
454 // This variable is for internal use only. Using this variable can cause behavioral, security-related,
455 // and consistency-related issues in the application.
457 // The variable for internal usage.
461 class _ControlAnimatorImpl* _pControlAnimatorImpl;
467 // This method is for internal use only. Using this method can cause behavioral, security-related,
468 // and consistency-related issues in the application.
470 // This is the constructor for this class.
474 ControlAnimator(void);
478 // This method is for internal use only. Using this method can cause behavioral, security-related,
479 // and consistency-related issues in the application.
481 // Initializes this class.
484 // @return An error code
485 // @param[in] source An instance of control class
486 // @exception E_SUCCESS The method is successful.
487 // @exception E_SYSTEM A system error has occurred.
489 result Construct(const Tizen::Ui::Control& source);
493 // This method is for internal use only. Using this method can cause behavioral, security-related,
494 // and consistency-related issues in the application.
496 // This is the copy constructor for this class.
500 ControlAnimator(const ControlAnimator& animator);
504 // This method is for internal use only. Using this method can cause behavioral, security-related,
505 // and consistency-related issues in the application.
507 // Assigns the value of the specified instance to the current instance of %ControlAnimator.
512 ControlAnimator& operator =(const ControlAnimator& rhs);
515 friend class Tizen::Ui::_ControlImpl;
516 friend class FrameAnimator;
517 }; // ControlAnimator
520 }}} // Tizen::Ui::Animations
522 #endif //_FUI_ANIM_CONTROL_ANIMATOR_H_