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 FUiAnimVisualElement.h
20 * @brief This is the header file for the %VisualElement class.
22 * This header file contains the declarations of the %VisualElement class.
25 #ifndef _FUI_ANIM_VISUAL_ELEMENT_H_
26 #define _FUI_ANIM_VISUAL_ELEMENT_H_
28 #include <FBaseObject.h>
29 #include <FBaseString.h>
30 #include <FGrpFloatMatrix4.h>
31 #include <FGrpFloatPoint.h>
32 #include <FGrpFloatPoint3.h>
33 #include <FGrpFloatRectangle.h>
34 #include <FUiVariant.h>
35 #include <FUiAnimTypes.h>
36 #include <FUiAnimIVisualElementAnimationProvider.h>
37 #include <FUiAnimIVisualElementContentProvider.h>
38 #include <FUiAnimIVisualElementEventListener.h>
40 namespace Tizen { namespace Graphics {
44 namespace Tizen { namespace Ui { namespace Animations
47 class VisualElementSurface;
48 class _VisualElementImpl;
52 * @class VisualElement
53 * @brief This class is a base class for all displayable objects on screen with animations.
57 * The %VisualElement class is a base class for all displayable objects on screen with animations.
58 * It encapsulates properties about coordinates (bounds, transform matrix, children transform matrix and so on),
59 * contents (content bounds, clipping, opacity, show state and so on) and tree-hierarchy.
60 * It also provides infrastructure necessary for animations (AddAnimation(), RemoveAnimation() and so on).
61 * A %VisualElement object instantiated by applications works as a model object and may have a cloned counter part for presentation on screen which has a separated life-cycle.
62 * The presentation object is managed by system and applications must not change properties of it.
63 * Use the presentation instance only to get the current state of a visual element in a tree. Calling the setter methods of a presentation instance can cause unexpected behavior to occur.
64 * Most animations of %VisualElement are applied on presentation objects. Properties set by applications are stored in model objects while properties of presentation objects
65 * are changing during implicit or explicit animations.
67 * This class also provides interfaces such as IVisualElementContentProvider, IVisualElementEventListener, and IVisualElementAnimationProvider to override default behaviors
68 * without inheritances.
70 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/visualelement.htm">Visual Elements</a>.
74 class _OSP_EXPORT_ VisualElement
75 : public Tizen::Base::Object
79 * The lowest drawing group, such as, background element.
83 static const int Z_ORDER_GROUP_LOWEST = -1000;
87 * The level of the default group.
91 static const int Z_ORDER_GROUP_NORMAL = 0;
95 * The highest drawing group, such as, top-most element.
99 static const int Z_ORDER_GROUP_HIGHEST = 1000;
103 * @enum RenderOperation
104 * Defines the render operation for %VisualElement. @n
105 * The contents of %VisualElement will be composited on screen using this operation.
109 RENDER_OPERATION_BLEND = 0, /**< The contents will be displayed blended with underlying %VisualElements */
110 RENDER_OPERATION_COPY /**< The contents will be displayed obscuring other underlying %VisualElements */
115 * The object is not fully constructed after this constructor is called.
116 * For full construction, the Construct() method must be called right after calling this constructor.
123 * Initializes this instance of %VisualElement.
127 * @return An error code
128 * @exception E_SUCCESS The method is successful.
129 * @exception E_SYSTEM A system error has occurred.
131 result Construct(void);
134 * Deallocates this instance and all descendants of %VisualElement.
138 * @remarks This method must be used to destroy this instance. @n
139 * Do not use @c delete operator.
140 * @remarks This method first destroys children, and then it destroys the parent(this instance).
141 * @remarks This method will call OnDestructing() callback before deallocating the instance.
142 * @remarks The destructing sequence is as follows:
143 * 1. Destroy children recursively.
144 * 2. Calls %OnDestructing() callback.
145 * 3. Detaches from parent.
146 * 4. Removes all animations associated with this instance.
147 * 5. Deallocates this instance.
153 * Sets the animation provider which creates implicit animations.
157 * @return An error code
158 * @param[in] pProvider The animation provider to create implicit animations
159 * @exception E_SUCCESS The method is successful.
160 * @exception E_INVALID_OPERATION This instance does not allow to set an animation provider. @n
161 * The animation provider can be set to the model instance only.
163 * @see IVisualElementAnimationProvider
164 * @see GetAnimationProvider()
166 result SetAnimationProvider(IVisualElementAnimationProvider* pProvider);
169 * Gets the assigned animation provider.
173 * @return The animation provider
174 * @exception E_INVALID_OPERATION This instance does not allow to get an animation provider. @n
175 * The animation provider can be set to the model instance only.
176 * @remarks The specific error code can be accessed using the GetLastResult() method.
177 * @see IVisualElementAnimationProvider
178 * @see SetAnimationProvider()
180 IVisualElementAnimationProvider* GetAnimationProvider(void) const;
183 * Sets the content provider which customizes information on contents.
187 * @return An error code
188 * @param[in] pProvider The content provider to customize information on content
189 * @exception E_SUCCESS The method is successful.
190 * @exception E_INVALID_OPERATION This instance does not allow to set a content provider. @n
191 * The content provider can be set to the model instance only.
192 * @see IVisualElementContentProvider
193 * @see GetContentProvider()
195 result SetContentProvider(IVisualElementContentProvider* pProvider);
198 * Gets the assigned content provider.
202 * @return The content provider
203 * @exception E_INVALID_OPERATION This instance does not allow to get content provider. @n
204 * The content provider can be set to the model instance only.
205 * @remarks The specific error code can be accessed using the GetLastResult() method.
206 * @see IVisualElementContentProvider
207 * @see SetContentProvider()
209 IVisualElementContentProvider* GetContentProvider(void) const;
212 * Sets the %VisualElement event listener.
216 * @return An error code
217 * @param[in] pListener The %VisualElement event listener
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_INVALID_OPERATION This instance does not allow to set an event listener. @n
220 * The event listener can be set to the model instance only.
221 * @see IVisualElementEventListener
222 * @see GetVisualElementEventListener()
224 result SetVisualElementEventListener(IVisualElementEventListener* pListener);
227 * Gets the assigned %VisualElement event listener.
231 * @return The %VisualElement event listener
232 * @exception E_INVALID_OPERATION This instance does not allow to get an event listener. @n
233 * The event listener can be set to the model instance only.
234 * @remarks The specific error code can be accessed using the GetLastResult() method.
235 * @see IVisualElementEventListener
236 * @see SetVisualElementEventListener()
238 IVisualElementEventListener* GetVisualElementEventListener(void) const;
242 * Overrides the OnConstructed() method to provide user-specific initialization code.
246 * @remarks This method is called after the instance is initialized by the Construct() method successfully.
249 * @see OnDestructing()
251 virtual void OnConstructed(void);
254 * Overrides the OnDestructing() method to provide user-specific termination code.
258 * @remarks This method is called before deallocating the %VisualElement instance by the Destroy() method.
261 * @see OnConstructed()
263 virtual void OnDestructing(void);
266 * Called by the GetChildAt() method to check whether this instance contains the @c point specified. @n
267 * If the Tizen::Ui::Animations::IVisualElementAnimationProvider interface is set to this instance,
268 * the Tizen::Ui::Animations::IVisualElementContentProvider::HitTest() callback will be called instead.
272 * @return The hit test result
273 * @param[in] point The hit position in the coordinate space of this instance
274 * @remarks Hit test results must be one of the following values: @n
275 * - Tizen::Ui::Animations::HitTestResult::HIT_TEST_NOWHERE
276 * - Tizen::Ui::Animations::HitTestResult::HIT_TEST_MATCH
278 * @see IVisualElementContentProvider::HitTest()
280 virtual HitTestResult OnHitTest(const Tizen::Graphics::FloatPoint& point);
283 * Before the system calls OnDraw() method to fill the contents, the %OnPrepareDraw() method is called to give an opportunity to hook or prepare drawing. @n
284 * If the [IVisualElementContentProvider](@ref Tizen::Ui::Animations::IVisualElementContentProvider) interface is set to this instance,
285 * the [PrepareDraw()](@ref Tizen::Ui::Animations::IVisualElementContentProvider::PrepareDraw) callback will be called instead.
289 * @return @c true if OnDraw() can be called, @n
291 * @see IVisualElementContentProvider::PrepareDraw()
293 virtual bool OnPrepareDraw(void);
296 * Called to fill contents on the canvas provided by the system. @n
297 * If the [IVisualElementContentProvider](@ref Tizen::Ui::Animations::IVisualElementContentProvider) is set to this instance,
298 * the [DrawContent()](@ref Tizen::Ui::Animations::IVisualElementContentProvider::DrawContent) callback will be called instead.
302 * @param[in] canvas The canvas to fill the contents of %VisualElement
303 * @see IVisualElementContentProvider::DrawContent()
305 virtual void OnDraw(Tizen::Graphics::Canvas& canvas);
308 * Overrides the %OnCreateAnimationForProperty() method to provide user-specific implicit animation. @n
309 * If the [IVisualElementAnimationProvider](@ref Tizen::Ui::Animations::IVisualElementAnimationProvider) interface is set to this instance,
310 * the [CreateAnimationForProperty()](@ref Tizen::Ui::Animations::IVisualElementAnimationProvider::CreateAnimationForProperty) callback will be called instead.
314 * @return The VisualElementAnimation instance for the specified property, @n
315 else @c null to disable implicit animation for the property
316 * @param[in] property The property to animate implicitly
317 * @remarks The returned [Animation](@ref Tizen::Ui::Animations::VisualElementAnimation) instance must be allocated on the heap if needed. @n
318 * If you do not need an implicit animation for the @c property at the time this method is called, return @c null.
319 * @see IVisualElementAnimationProvider::CreateAnimationForProperty()
321 virtual VisualElementAnimation* OnCreateAnimationForProperty(const Tizen::Base::String& property);
324 * Overrides the %OnGetPropertyRequested() method to provide user-specific properties or to change default behaviors of %VisualElement class. @n
325 * This method is called whenever GetProperty() is called.
329 * @return The property's value
330 * @param[in] property The property name
333 * @see OnSetPropertyRequested()
335 virtual Tizen::Ui::Variant OnGetPropertyRequested(const Tizen::Base::String& property) const;
338 * Overrides the %OnSetPropertyRequested() method to provide user-specific properties or to change default behaviors of %VisualElement class. @n
339 * This method is called whenever SetProperty() is called.
343 * @return An error code
344 * @param[in] property The property name
345 * @param[in] value The value of the property to set
348 * @see OnGetPropertyRequested()
350 virtual result OnSetPropertyRequested(const Tizen::Base::String& property, const Tizen::Ui::Variant& value);
353 * Gets the parent of this instance.
357 * @return The parent of the this instance
359 VisualElement* GetParent(void) const;
362 * Gets a list of children of this instance.
366 * @return The list of children of this instance
367 * @exception E_SUCCESS The method is successful.
368 * @exception E_OUT_OF_MEMORY The memory is insufficient.
369 * @remarks The specific error code can be accessed using the GetLastResult() method.
370 * @remarks If an exception occurs, this method returns @c null.
372 Tizen::Base::Collection::IList* GetChildrenN(void) const;
375 * Gets the count of children.
379 * @return The count of children
381 int GetChildrenCount(void) const;
384 * Checks whether this instance is a child or descendant of the specified one.
386 * @brief <i> [Deprecated] </i>
387 * @deprecated This method is deprecated.
390 * @return @c true if this instance is a child or descendant of the specified one, @n
392 * @param[in] other An instance of %VisualElement to test relationship
394 bool IsChildOf(const VisualElement& other) const;
397 * Checks whether an instance is a child or descendant of a specified one.
401 * @return @c true if this instance is a child or descendant of a specified one, @n
403 * @param[in] pOther A pointer to %VisualElement instance to check its relationship
404 * @exception E_SUCCESS The method is successful.
405 * @exception E_INVALID_ARG The specified @c pOther is @c null.
406 * @remarks The specific error code can be accessed using the GetLastResult() method.
408 bool IsChildOf(const VisualElement* pOther) const;
411 * Attaches a child to this instance. @n
412 * The %AttachChild() method attaches the specified @c child at the highest position in the Z order group of the @c child.
413 * If you need to change Z-Order group, you can change it using the SetZOrderGroup() method.
415 * @brief <i> [Deprecated] </i>
416 * @deprecated This method is deprecated.
419 * @return An error code
420 * @param[in] child The %VisualElement instance to attach to this instance
421 * @exception E_SUCCESS The method is successful.
422 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
423 * - The specified @c child is not instantiated successfully. @n
424 * - The specified @c child is this instance. @n
425 * - The specified @c child is already an ancestor of this instance.
426 * @see SetZOrderGroup()
429 * @see ChangeZOrder()
431 result AttachChild(const VisualElement& child);
434 * Attaches a child to an instance. @n
435 * The %AttachChild() method attaches the specified @c pChild at the highest position in the Z order group of the @c pChild.
436 * Z-Order group can be changed using the SetZOrderGroup() method.
440 * @return An error code
441 * @param[in] pChild A pointer to %VisualElement instance to attach to this instance
442 * @exception E_SUCCESS The method is successful.
443 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
444 * - The specified @c pChild is not instantiated successfully. @n
445 * - The specified @c pChild is this instance. @n
446 * - The specified @c pChild is already an ancestor of this instance.@n
447 * - The specified @c pChild is @c null.
448 * @see SetZOrderGroup()
451 * @see ChangeZOrder()
453 result AttachChild(VisualElement* pChild);
456 * Inserts a child to this instance. @n
457 * If @c pReference is not @c null, the Z order group of @c child will be changed into that of @c pReference and @c child will be
458 * placed right above or below the @c pReference instance according to the @c above parameter.
460 * @brief <i> [Deprecated] </i>
461 * @deprecated This method is deprecated.
464 * @return An error code
465 * @param[in] child The %VisualElement instance to attach to this instance
466 * @param[in] pReference A pointer to the %VisualElement instance that is referenced
467 * @param[in] above Specifies the position of @c child relative to the @c pReference
468 * @exception E_SUCCESS The method is successful.
469 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
470 * - The specified @c child is not instantiated successfully. @n
471 * - The specified @c child is this instance. @n
472 * - The specified @c child and @c pReference are same. @n
473 * - The specified @c child is already an ancestor of this instance. @n
474 * - The parent of @c pReference is not this instance if @c pReference is not @c null. @n
475 * @remarks If @c above is @c true, the @c child will be attached above @c pReference in Z order,
476 * else it will be attached below the @c pReference %VisualElement. @n
477 * If @c pReference is @c null, the @c child will be attached at the highest position in the @c child's Z order group,
478 * else the child will be attached at the lowest position in the @c child's Z order group.
479 * @see SetZOrderGroup()
482 * @see ChangeZOrder()
484 result InsertChild(const VisualElement& child, const VisualElement* pReference, bool above);
487 * Inserts a child to an instance. @n
488 * If @c pReference is not @c null, the Z order group of @c pChild will be changed into that of @c pReference and @c child will be
489 * placed right above or below the @c pReference instance according to the @c above parameter.
493 * @return An error code
494 * @param[in] pChild A pointer to %VisualElement instance to insert
495 * @param[in] pReference A pointer to the %VisualElement instance to refer
496 * @param[in] above The position of @c pChild relative to @c pReference
497 * @exception E_SUCCESS The method is successful.
498 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
499 * - The specified @c pChild is not instantiated successfully. @n
500 * - The specified @c pChild is this instance. @n
501 * - The specified @c pChild and @c pReference are same. @n
502 * - The specified @c pChild is already an ancestor of this instance. @n
503 * - The parent of @c pReference is not this instance if @c pReference is not @c null. @n
504 * - The specified @c pChild is @c null.
505 * @remarks If @c above is @c true, the @c pChild is attached above @c pReference in Z order,
506 * else it is attached below the @c pReference %VisualElement. @n
507 * If @c pReference is @c null, the @c pChild is attached at the highest position in the @c pChild's Z order group,
508 * else the child is attached at the lowest position in the @c pChild's Z order group.
509 * @see SetZOrderGroup()
512 * @see ChangeZOrder()
514 result InsertChild(VisualElement* pChild, const VisualElement* pReference, bool above);
517 * Detaches a child from this instance.
519 * @brief <i> [Deprecated] </i>
520 * @deprecated This method is deprecated.
523 * @return An error code
524 * @param[in] child The %VisualElement instance to detach from this instance
525 * @exception E_SUCCESS The method is successful.
526 * @exception E_OBJ_NOT_FOUND The specified @c child is not a child of this instance.
527 * @remarks This method detaches @c child from this instance. If you need to deallocate %VisualElement, call Destroy() method, not C++ delete.
531 result DetachChild(const VisualElement& child);
534 * Detaches a child from an instance.
538 * @return An error code
539 * @param[in] pChild A pointer to %VisualElement instance to detach
540 * @exception E_SUCCESS The method is successful.
541 * @exception E_OBJ_NOT_FOUND The specified @c pChild is not a child of this instance.
542 * @exception E_INVALID_ARG The specified @c pChild is @c null.
543 * @remarks This method detaches @c pChild from this instance. To deallocate %VisualElement, call Destroy() method, and not C++ delete.
547 result DetachChild(VisualElement* pChild);
550 * Changes Z order of this instance.
554 * @return An error code
555 * @param[in] pReference A pointer to the %VisualElement instance that is referenced
556 * @param[in] above Specifies the position of this instance relative to the @c pReference
557 * @exception E_SUCCESS The method is successful.
558 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
559 * - This instance does not have a parent (not attached). @n
560 * - This instance and @c pReference do not have same parent if @c pReference is not @c null. @n
561 * - The specified @c pReference is this instance. @n
562 * @remarks If @c above is @c true, this instance will be attached above @c pReference in Z order,
563 * else it will be attached below the @c pReference %VisualElement. @n
564 * If @c pReference is @c null, this instance will be attached at the highest position in the Z order group of this instance,
565 * else the child will be attached at the lowest position in the Z order group of this instance.
570 result ChangeZOrder(const VisualElement* pReference, bool above);
573 * Gets the child of the specified @c name. @n
574 * If there are multiple matches of the name, it returns the first match.
578 * @return The %VisualElement instance having the specified @c name @n
579 * else @c null if there is not %VisualElement with the specified @c name
580 * @param[in] name The name of the %VisualElement
581 * @param[in] searchDescendants @c true to find a match among all the descendants of this instance, @n
583 * @exception E_SUCCESS The method is successful.
584 * @exception E_OBJ_NOT_FOUND There is no %VisualElement with the specified @c name.
585 * @remarks The specific error code can be accessed using the GetLastResult() method.
586 * @remarks If an exception occurs, this method returns @c null.
590 VisualElement* GetChild(const Tizen::Base::String& name, bool searchDescendants) const;
593 * Gets the farthest (highest Z order) %VisualElement descendant including this instance that contains a specified @c point. @n
594 * The OnHitTest() method or [HitTest](@ref Tizen::Ui::Animations::IVisualElementContentProvider::HitTest) callback may be called
595 * for descendants of this instance including itself.
599 * @return The %VisualElement that contains @c point, @n
600 * else @c null if @c point is completely outside of this instance
601 * @param[in] point The position in coordinate space of this instance
602 * @exception E_SUCCESS The method is successful.
603 * @exception E_OBJ_NOT_FOUND There is no %VisualElement containing the specified @c point.
604 * @remarks The specific error code can be accessed using the GetLastResult() method.
605 * @remarks If an exception occurs, this method returns @c null.
606 * @remarks This method assumes that all ancestors of this instance do not clip children.
607 * @see IVisualElementContentProvider::HitTest()
609 * @see IsClipChildrenEnabled()
610 * @see SetClipChildrenEnabled()
612 VisualElement* GetChildAt(const Tizen::Graphics::FloatPoint& point) const;
615 * Adds an animation without key name.
619 * @return An error code
620 * @param[in] animation The animation instance
621 * @exception E_SUCCESS The method is successful.
622 * @exception E_INVALID_ARG The input parameter is incorrect.
623 * @exception E_INVALID_OPERATION This instance is not a model object. @n
624 * An animation can be added to the model instance only.
625 * @see RemoveAnimation()
626 * @see GetAnimationN()
628 result AddAnimation(const VisualElementAnimation& animation);
631 * Adds an animation with key name.
635 * @return An error code
636 * @param[in] keyName The name of the animation that is used to identify animations @n
637 * Empty @c keyName is allowed.
638 * @param[in] animation The animation instance
639 * @exception E_SUCCESS The method is successful.
640 * @exception E_INVALID_ARG The input parameter is incorrect.
641 * @exception E_OBJ_ALREADY_EXIST An animation with @c keyName already exists.
642 * @exception E_INVALID_OPERATION This instance is not a model object. @n
643 * An animation can be added to the model instance only.
644 * @see RemoveAnimation()
645 * @see GetAnimationN()
647 result AddAnimation(const Tizen::Base::String& keyName, const VisualElementAnimation& animation);
650 * Removes the animation with the specified @c keyName.
654 * @return An error code
655 * @param[in] keyName The name of the animation to remove
656 * @exception E_SUCCESS The method is successful.
657 * @exception E_OBJ_NOT_FOUND An animation with @c keyName does not exist.
658 * @see AddAnimation()
659 * @see GetAnimationN()
661 result RemoveAnimation(const Tizen::Base::String& keyName);
664 * Gets the animation playing for the specified property.
668 * @return A pointer to the animation
669 * @param[in] keyName The name of the animation
670 * @exception E_SUCCESS The method is successful.
671 * @exception E_OBJ_NOT_FOUND An animation with @c keyName does not exist.
672 * @remarks The specific error code can be accessed using the GetLastResult() method.
673 * @remarks If an exception occurs, this method returns @c null.
674 * @see AddAnimation()
675 * @see RemoveAnimation()
677 VisualElementAnimation* GetAnimationN(const Tizen::Base::String& keyName) const;
680 * Removes all animations.
684 * @see AddAnimation()
685 * @see RemoveAnimation()
687 void RemoveAllAnimations(void);
690 * Adds a rectangle to update region of this instance. @n
691 * The update region represents the portion of the %VisualElement's area that must be redrawn by the OnDraw() method.
695 * @return An error code
696 * @param[in] pRectangle The pointer to the rectangular region that contains the coordinates of the rectangle to add to the update region @n
697 * If @c pRectangle is @c null, entire area is added to the update region.
698 * @exception E_SUCCESS The method is successful.
699 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method.
702 result InvalidateRectangle(const Tizen::Graphics::FloatRectangle* pRectangle);
705 * Gets the smallest rectangle that completely encloses the update region of this instance. @n
706 * Applications can use the update region in the OnDraw() method to minimize the redrawing area to improve performance.
707 * The %GetUpdateRectangle() method returns an empty rectangle if it is not called inside OnDraw() method.
711 * @return The rectangle to update
712 * @see InvalidateRectangle()
714 Tizen::Graphics::FloatRectangle GetUpdateRectangle(void) const;
717 * Updates the content area of all the descendants including this instance.
718 * The %Draw() method will call OnDraw() or DrawContent() method only if there are regions invalidated by InvalidateRectangle().
719 * The platform will call this method later automatically if applications do not call explicitly.
723 * @return An error code
724 * @exception E_SUCCESS The method is successful.
725 * @exception E_INVALID_STATE This instance is not attached to the maintained tree for displaying. @n
726 * For displaying, this instance should be descendant of the root %VisualElement.
727 * @exception E_SYSTEM A system error has occurred.
728 * @see IVisualElementContentProvider
733 * Marks the entire area of this instance to be flushed.
737 * @return An error code
738 * @exception E_SUCCESS The method is successful.
742 result SetFlushNeeded(void);
745 * Creates and returns a graphics canvas whose bounds, position, and size are equal to those of this instance.
749 * @return The graphic canvas of the %VisualElement, @n
750 * else @c null if an exception occurs
751 * @exception E_SUCCESS The method is successful.
752 * @exception E_INVALID_STATE This instance is in an invalid state.
753 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method. @n
754 The canvas can be created for the model instance only.
755 * @remarks This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the %VisualElement.
756 * It is the developer's responsibility to deallocate the canvas after use.
757 * The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
758 * Therefore, one must delete previously allocated canvas and create a new canvas using this method,
759 * if the size or position of the %VisualElement is changed. @n
760 * @remarks The specific error code can be accessed using the GetLastResult() method.
761 * @remarks If an exception occurs, this method returns @c null.
762 * @see GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
763 * @see GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
765 Tizen::Graphics::Canvas* GetCanvasN(void) const;
768 * Creates and returns a graphic canvas of the specified area.
772 * @return The graphic canvas of the %VisualElement, @n
773 * else @c null if an exception occurs
774 * @param[in] bounds The position relative to the top-left corner of the %VisualElement and size
775 * @exception E_SUCCESS The method is successful.
776 * @exception E_INVALID_STATE This instance is in an invalid state.
777 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method. @n
778 The canvas can be created for the model instance only.
779 * @exception E_OUT_OF_RANGE The specified @c bounds do not intersect with the bounds of the %VisualElement. @n
780 * The width and height must be greater than or equal to @c 0.
781 * @remarks Only the graphic canvas of displayable %VisualElement can be obtained.
782 * If the specified area is not inside the %VisualElement,
783 * the graphics canvas of overlapped area between the %VisualElement and the specified @c bound is returned. @n
784 * This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the %VisualElement.
785 * It is the developer's responsibility to deallocate the canvas after use.
786 * The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
787 * Therefore, one must delete previously allocated canvas and create a new canvas using this method,
788 * if the size or position of the control is changed. @n
789 * @remarks The specific error code can be accessed using the GetLastResult() method.
790 * @remarks If an exception occurs, this method returns @c null.
792 * @see GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
794 Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const;
797 * Creates and returns a graphic canvas of the specified area.
801 * @return The graphic canvas of %VisualElement, @n
802 * else @c null if an exception occurs
803 * @param[in] bounds The position relative to the top-left corner of %VisualElement and size
804 * @exception E_SUCCESS The method is successful.
805 * @exception E_INVALID_STATE This instance is in an invalid state.
806 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method. @n
807 The canvas can be created for the model instance only.
808 * @exception E_OUT_OF_RANGE The specified @c bounds do not intersect with the bounds of %VisualElement. @n
809 * The width and height must be greater than or equal to @c 0.
810 * @remarks Only the graphic canvas of displayable %VisualElement can be obtained.
811 * If the specified area is not inside %VisualElement,
812 * the graphics canvas of overlapped area between %VisualElement and the specified @c bound is returned. @n
813 * This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of %VisualElement.
814 * It is the developer's responsibility to deallocate the canvas after use.
815 * The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
816 * Therefore, one must delete previously allocated canvas and create a new canvas using this method,
817 * if the size or position of the control is changed.
818 * @remarks The specific error code can be accessed using the GetLastResult() method.
819 * @remarks If an exception occurs, this method returns @c null.
821 * @see GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
823 Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const;
826 * Gets the name of this instance.
830 * @return The name of this instance
832 Tizen::Base::String GetName(void) const;
835 * Sets the name of this instance.
839 * @param[in] name The name of the %VisualElement instance @n
840 * Empty or duplicated name with other instances are also allowed.
842 void SetName(const Tizen::Base::String& name);
845 * Gets the value of the %VisualElement's property.
849 * @return The value of the specified property
850 * @param[in] property The %VisualElement's property
851 * @exception E_SUCCESS The method is successful.
852 * @exception E_KEY_NOT_FOUND The specified @c property is not found.
853 * @remarks The specific error code can be accessed using the GetLastResult() method.
854 * @remarks If an exception occurs, this method returns @c Variant::NULL_VARIANT.
855 * @remarks Additional exceptions can occur according to the behavior of subclasses.
857 * @see OnGetPropertyRequested()
859 Variant GetProperty(const Tizen::Base::String& property) const;
862 * Sets the value of the %VisualElement's property.
866 * @return An error code
867 * @param[in] property The %VisualElement's property
868 * @param[in] value The value of the %VisualElement's property to set
869 * @exception E_SUCCESS The method is successful.
870 * @exception E_KEY_NOT_FOUND The specified @c property is not found.
871 * @remarks Additional exceptions can occur according to the behavior of subclasses.
873 * @see OnSetPropertyRequested()
875 result SetProperty(const Tizen::Base::String& property, const Variant& value);
878 * Sets the Z order group of this instance.
882 * @return An error code
883 * @param[in] zOrderGroup The value of Z order which must be between @c Z_ORDER_GROUP_LOWEST and @c Z_ORDER_GROUP_HIGHEST @n
884 * The default value is @c Z_ORDER_GROUP_NORMAL.
885 * @exception E_SUCCESS The method is successful.
886 * @exception E_OUT_OF_RANGE The @c zOrderGroup is not between @c Z_ORDER_GROUP_LOWEST and @c Z_ORDER_GROUP_HIGHEST.
887 * @remarks You can choose the @c zOrderGroup value as follows: @n
888 * - Tizen::Ui::Animations::Z_ORDER_GROUP_LOWEST @n
889 * - Tizen::Ui::Animations::Z_ORDER_GROUP_NORMAL @n
890 * - Tizen::Ui::Animations::Z_ORDER_GROUP_HIGHEST @n
891 * Or you can specify an integer value between @c ZORDER_GROUP_LOWEST and @c ZORDER_GROUP_HIGHEST.
892 * @see GetZOrderGroup()
894 result SetZOrderGroup(int zOrderGroup);
897 * Gets the Z order group of this instance.
901 * @return The Z order group of this instance
902 * @see SetZOrderGroup()
904 int GetZOrderGroup(void) const;
907 * Checks whether the redraw-on-resize feature is enabled.
911 * @return @c true if the redraw-on-resize feature is enabled, @n
913 * @remarks The entire content area will be added to the update region when bounds are changed if redraw-on-resize is enabled. @n
914 * Otherwise, current contents will be scaled for the new bounds of this instance without redrawing.
915 * @see SetRedrawOnResizeEnabled()
917 bool IsRedrawOnResizeEnabled(void) const;
920 * Enables or disables the redraw-on-resize feature.
924 * @param[in] enable Set to @c true if invalidation is needed whenever resized, @n
926 * @see IsRedrawOnResizeEnabled()
928 void SetRedrawOnResizeEnabled(bool enable);
931 * Gets the position and the size of this instance.
935 * @return An instance of the Tizen::Graphics::FloatRectangle that represents the position of top-left corner, @n
936 * the width, and the height of this instance. @n It has relative coordinate space to the parent.
939 Tizen::Graphics::FloatRectangle GetBounds(void) const;
942 * Sets the position and the size of this instance.
946 * @return An error code
947 * @param[in] bounds The new bounds of this instance
948 * @exception E_SUCCESS The method is successful.
949 * @exception E_INVALID_STATE This instance is in an invalid state.
950 * @remarks When the size of @c bounds is changed, the entire content area will be added to the update region of this instance if redraw-on-resize feature is enabled.
952 * @see IsRedrawOnResizeEnabled()
953 * @see SetRedrawOnResizeEnabled()
955 result SetBounds(const Tizen::Graphics::FloatRectangle& bounds);
958 * Gets the position on the Z-axis.
962 * @return The position on the Z-axis
963 * @see SetZPosition()
965 float GetZPosition(void) const;
968 * Sets the position on the Z-axis.
972 * @param[in] zPosition The position on the Z-axis
973 * @see GetZPosition()
975 void SetZPosition(float zPosition);
978 * Checks whether this instance is visible or not. @n
979 * Even if the show state is @c true, this instance can be invisible when show state of one of the ancestors is @c false.
983 * @return @c true if this instance is visible, @n
985 * @see GetShowState()
986 * @see SetShowState()
988 bool IsVisible(void) const;
991 * Gets the show state of this instance.
995 * @return The show state of the %VisualElement instance, @n
997 * @remarks Even if the show state is @c true, the %VisualElement is invisible if it is not attached to a parent.
998 * @see SetShowState()
1001 bool GetShowState(void) const;
1004 * Sets the show state of this instance.
1008 * @param[in] show Set to @c true if this instance needs to show, @n
1010 * @see GetShowState()
1013 void SetShowState(bool show);
1016 * Gets the opacity of this instance.
1020 * @return The opacity of this instance
1023 float GetOpacity(void) const;
1026 * Sets the opacity of this instance.
1030 * @param[in] opacity The new opacity which must be within the range [0.0, 1.0]
1031 * @remarks The changing opacity affects all the descendants of this instance.
1034 void SetOpacity(float opacity);
1037 * Enables or disables the implicit animation. @n
1038 * If enabled, implicit animations may be created whenever animatable properties of this instance change.
1042 * @param[in] enable Set to @c true to enable the implicit animation, @n
1044 * @remarks The implicit animation is enabled by default.
1045 * @see IsImplicitAnimationEnabled()
1047 void SetImplicitAnimationEnabled(bool enable);
1050 * Checks whether the implicit animation is enabled.
1054 * @return @c true if the implicit animation is enabled, @n
1056 * @see SetImplicitAnimationEnabled()
1058 bool IsImplicitAnimationEnabled(void) const;
1061 * Gets the transform matrix of this instance.
1065 * @return The transform matrix of this instance
1066 * @see SetTransformMatrix()
1068 Tizen::Graphics::FloatMatrix4 GetTransformMatrix(void) const;
1071 * Sets the transform matrix of this instance.
1075 * @return An error code
1076 * @param[in] transform The transform matrix
1077 * @exception E_SUCCESS The method is successful.
1078 * @exception E_INVALID_ARG The input parameter is incorrect.
1079 * @see GetTransformMatrix()
1081 result SetTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1084 * Gets the transform matrix applied to each child.
1088 * @return The transform matrix applied to each child
1089 * @remarks The transform matrix for children is typically used for the projection matrix to layout children in 3D space.
1090 * @see SetChildrenTransformMatrix()
1092 Tizen::Graphics::FloatMatrix4 GetChildrenTransformMatrix(void) const;
1095 * Sets the transform matrix applied to each child.
1099 * @return An error code
1100 * @param[in] transform The transform matrix
1101 * @exception E_SUCCESS The method is successful.
1102 * @exception E_INVALID_ARG The input parameter is incorrect.
1103 * @see GetChildrenTransformMatrix()
1105 result SetChildrenTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1109 * Gets the anchor point for this instance's transform matrix in uniform coordinate space
1110 * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1114 * @return The anchor point of this instance
1117 Tizen::Graphics::FloatPoint GetAnchor(void) const;
1120 * Sets the anchor point of this instance's transform matrix in uniform coordinate space
1121 * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1125 * @param[in] anchor The anchor point in uniform coordinate space
1128 void SetAnchor(const Tizen::Graphics::FloatPoint& anchor);
1131 * Gets the Z component of this instance's anchor point for transform matrix.
1135 * @return The Z component of the anchor point
1138 float GetAnchorZ(void) const;
1141 * Sets the Z component of this instance's anchor point for transform matrix.
1145 * @param[in] anchorZ The Z component of anchor point
1148 void SetAnchorZ(float anchorZ);
1151 * Gets the custom data of this instance.
1155 * @return The user data associated with this instance
1156 * @see SetUserData()
1158 void* GetUserData(void) const;
1161 * Sets the custom data of this instance.
1165 * @param[in] pUserData The user data associated with this instance
1166 * @see GetUserData()
1168 void SetUserData(void* pUserData);
1171 * Sets the contents of this instance with the specified VisualElementSurface. @n
1172 * The contents of the @c pSurface is not copied by the %SetSurface() method, but shared with this instance.
1176 * @return An error code
1177 * @param[in] pSurface The pointer to VisualElementSurface @n
1178 * If @c pSurface is @c null, surface will be created internally by system.
1179 * @exception E_SUCCESS The method is successful.
1180 * @exception E_INVALID_OPERATION This instance does not allow VisualElementSurface for contents.
1181 * @remarks If applications modify the contents of @c pSurface, the modifications will be applied to all
1182 * the %VisualElements which share same VisualElementSurface. But in this case, applications need to call
1183 * the SetFlushNeeded() method for those %VisualElements because the modifications of the @c pSurface will not be applied on the screen automatically.
1184 * @see GetSurfaceN()
1186 result SetSurface(VisualElementSurface* pSurface);
1189 * Gets the VisualElementSurface this instance uses for its contents.
1193 * @return A pointer to VisualElementSurface
1194 * @exception E_SUCCESS The method is successful.
1195 * @exception E_SYSTEM A system error has occurred.
1196 * @remarks The specific error code can be accessed using the GetLastResult() method.
1197 * @remarks If an exception occurs, this method returns @c null.
1200 VisualElementSurface* GetSurfaceN(void) const;
1203 * Sets the render operation of this instance.
1207 * @return An error code
1208 * @param[in] renderOperation The new rendering operation
1209 * @exception E_SUCCESS The method is successful.
1210 * @exception E_INVALID_ARG The specified @c renderOperation is out of range.
1211 * @see GetRenderOperation()
1213 result SetRenderOperation(RenderOperation renderOperation);
1216 * Gets the render operation of this instance.
1220 * @return The render operation of this instance
1221 * @see SetRenderOperation()
1223 RenderOperation GetRenderOperation(void) const;
1226 * Checks whether all the descendants are clipped to the bounds of this instance.
1230 * @return @c true if this instance clips all the descendants, @n
1232 * @see SetClipChildrenEnabled()
1234 bool IsClipChildrenEnabled(void) const;
1237 * Enables or disables clipping of all the descendants.
1241 * @param[in] clipChildren Set to @c true if all the descendants are needed to clip to the bounds of this instance, @n
1243 * @see IsClipChildrenEnabled()
1245 void SetClipChildrenEnabled(bool clipChildren);
1248 * Converts the specified @c point in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1249 * The coordinate is converted by projecting it on the root coordinate space.
1253 * @return An error code
1254 * @param[in,out] point The point to convert
1255 * @param[in] pFromVisualElement The %VisualElement instance with @c point in its coordinate space
1256 * @exception E_SUCCESS The method is successful.
1257 * @exception E_INVALID_ARG The input parameter is incorrect.
1258 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1259 * The matrix for this conversion is singular that has a zero determinant.
1260 * @remarks This instance and @c pFromVisualElement must share a common ancestor. @n
1261 * If @c null, it is regarded that @c point is in the root coordinate space.
1262 * @see ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement)
1264 result ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement) const;
1267 * Converts the specified @c rectangle in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1268 * The coordinate is converted by projecting it on the root coordinate space.
1272 * @return An error code
1273 * @param[in,out] rectangle The rectangle to convert
1274 * @param[in] pFromVisualElement The %VisualElement instance with @c rectangle in its coordinate space
1275 * @exception E_SUCCESS The method is successful.
1276 * @exception E_INVALID_ARG The input parameter is incorrect.
1277 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1278 * The matrix for this conversion is singular that has a zero determinant.
1279 * @remarks This instance and @c pFromVisualElement must share a common ancestor. @n
1280 * If @c null, it is regarded that @c rectangle is in the root coordinate space.
1281 * @see ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement)
1283 result ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement) const;
1286 * Transforms a point in @c pOriginVisualElement coordinate space into a specified vector in calling instance's coordinate space.
1290 * @return The transformed vector
1291 * @param[in] originPoint The point in @c pOriginVisualElement coordinate space
1292 * @param[in] pOriginVisualElement The %VisualElement instance with @c originPoint in its coordinate space
1293 * @exception E_SUCCESS The method is successful.
1294 * @exception E_INVALID_ARG The input parameter is incorrect.
1295 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1296 The matrix for this conversion is singular which has zero determinant.
1297 * @remarks - This instance and @c pOriginVisualElement must share a common ancestor.
1298 * - The specific error code can be accessed using the GetLastResult() method.
1300 Tizen::Graphics::FloatPoint3 TransformVectorFromOrigin(const Tizen::Graphics::FloatPoint3& originPoint, const VisualElement* pOriginVisualElement) const;
1303 * Sets the sub-rectangle of contents which this instance must display.
1307 * @return An error code
1308 * @param[in] contentBounds The sub-rectangle of contents to display in uniform coordinate space
1309 * @exception E_SUCCESS The method is successful.
1310 * @exception E_INVALID_ARG The width and height of @c contentBounds must be greater than @c 0.0.
1311 * @remarks Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1312 * @remarks If each component of @c contentBounds is not within the range [0.0, 1.0], the integer portion of the coordinates are
1313 * ignored and only fractional part is used which creates a repeating contents.
1314 * @see GetContentBounds()
1316 result SetContentBounds(const Tizen::Graphics::FloatRectangle& contentBounds);
1319 * Gets the sub-rectangle of contents which this instance must display.
1323 * @return The sub-rectangle of contents to be displayed in uniform coordinate space
1324 * @remarks Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1325 * @see SetContentBounds()
1327 Tizen::Graphics::FloatRectangle GetContentBounds(void) const;
1330 * Acquires the %VisualElement instance for display.
1334 * @return The %VisualElement instance for display(readonly)
1335 * @remarks If this instance is a presentation object, this method returns itself.
1336 * @see ReleasePresentationInstance()
1338 const VisualElement* AcquirePresentationInstance(void);
1341 * Releases the %VisualElement instance for display.
1345 * @remarks This method should be called only after AcquirePresentationInstance() call.
1346 * @see AcquirePresentationInstance()
1348 void ReleasePresentationInstance(void);
1351 * Acquires the %VisualElement instance for model.
1355 * @return The %VisualElement instance for model(readonly)
1356 * @remarks If this instance is a model object, this method returns itself.
1357 * @see ReleaseModelInstance()
1360 const VisualElement* AcquireModelInstance(void);
1363 * Releases the %VisualElement instance for model.
1367 * @remarks This method should be called only after AcquireModelInstance() call.
1369 void ReleaseModelInstance(void);
1372 * Flushes %VisualElements on screen.
1376 * @return An error code
1377 * @exception E_SUCCESS The method is successful.
1378 * @exception E_SYSTEM A system error has occurred.
1379 * @remarks Because this method may degrade the performance of system, applications must use this method only when really needed.
1380 * @see SetFlushNeeded()
1382 static result Flush(void);
1387 * This is copy constructor for the %VisualElement class.
1391 * @param[in] rhs An instance of %VisualElement
1394 VisualElement(const VisualElement& rhs);
1397 * This is the destructor for this class.
1401 * @remarks The delete operator cannot be used to deallocate the %VisualElement instance.
1404 virtual ~VisualElement(void);
1407 * Creates and returns a polymorphic copy of this %VisualElement instance for the presentation. @n
1408 * All descendants of %VisualElement must implement the %CloneN() method and the copy constructor appropriately. @n
1409 * When the %VisualElement instance is created, the framework make a %VisualElement for the presentation with this method.
1413 * @return The clone of this instance
1415 virtual VisualElement* CloneN(void) const;
1419 // This method is for internal use only. Using this method can cause behavioral, security-related,
1420 // and consistency-related issues in the application.
1423 // This method is reserved and may change its name at any time without prior notice.
1427 virtual void VisualElement_Reserved1(void) {}
1431 // This method is for internal use only. Using this method can cause behavioral, security-related,
1432 // and consistency-related issues in the application.
1435 // This method is reserved and may change its name at any time without prior notice.
1439 virtual void VisualElement_Reserved2(void) {}
1443 // This method is for internal use only. Using this method can cause behavioral, security-related,
1444 // and consistency-related issues in the application.
1447 // This method is reserved and may change its name at any time without prior notice.
1451 virtual void VisualElement_Reserved3(void) {}
1455 // This method is for internal use only. Using this method can cause behavioral, security-related,
1456 // and consistency-related issues in the application.
1459 // This method is reserved and may change its name at any time without prior notice.
1463 virtual void VisualElement_Reserved4(void) {}
1467 // This method is for internal use only. Using this method can cause behavioral, security-related,
1468 // and consistency-related issues in the application.
1471 // This method is reserved and may change its name at any time without prior notice.
1475 virtual void VisualElement_Reserved5(void) {}
1481 // The implementation of this assignment constructor is intentionally blank to prohibit assignment of objects.
1485 VisualElement& operator =(const VisualElement& rhs);
1489 _VisualElementImpl* _pVisualElementImpl;
1491 friend class _VisualElementImpl;
1495 }}} // Tizen::Ui::Animations
1497 #endif //_FUIANIMVISUALELEMENT_H_