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 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 for getting the current state of the visual element in the tree. If you call the setter methods of the presentation instance, it can cause unexpected behavior.
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.
388 * @return @c true if this instance is a child or descendant of the specified one, @n
390 * @param[in] other An instance of %VisualElement to test relationship
392 bool IsChildOf(const VisualElement& other) const;
395 * Checks whether this instance is a child or descendant of the specified one.
399 * @return @c true if this instance is a child or descendant of the specified one, @n
401 * @param[in] pOther A Pointer to %VisualElement instance to test relationship
402 * @exception E_SUCCESS The method is successful.
403 * @exception E_INVALID_ARG The specified @c pOther is null.
404 * @remarks The specific error code can be accessed using the GetLastResult() method.
406 bool IsChildOf(const VisualElement* pOther) const;
409 * Attaches a child to this instance. @n
410 * The %AttachChild() method attaches the specified @c child at the highest position in the Z order group of the @c child.
411 * If you need to change Z-Order group, you can change it using the SetZOrderGroup() method.
415 * @return An error code
416 * @param[in] child The %VisualElement instance to attach to this instance
417 * @exception E_SUCCESS The method is successful.
418 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
419 * - The specified @c child is not instantiated successfully. @n
420 * - The specified @c child is this instance. @n
421 * - The specified @c child is already an ancestor of this instance.
422 * @see SetZOrderGroup()
425 * @see ChangeZOrder()
427 result AttachChild(const VisualElement& child);
430 * Attaches a child to this instance. @n
431 * The %AttachChild() method attaches the specified @c pChild at the highest position in the Z order group of the @c pChild.
432 * If you need to change Z-Order group, you can change it using the SetZOrderGroup() method.
436 * @return An error code
437 * @param[in] pChild A pointer to %VisualElement instance to attach to this instance
438 * @exception E_SUCCESS The method is successful.
439 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
440 * - The specified @c pChild is not instantiated successfully. @n
441 * - The specified @c pChild is this instance. @n
442 * - The specified @c pChild is already an ancestor of this instance.@n
443 * - The specified @c pChild is @c null.
444 * @see SetZOrderGroup()
447 * @see ChangeZOrder()
449 result AttachChild(VisualElement* pChild);
452 * Inserts a child to this instance. @n
453 * 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
454 * placed right above or below the @c pReference instance according to the @c above parameter.
458 * @return An error code
459 * @param[in] child The %VisualElement instance to attach to this instance
460 * @param[in] pReference A pointer to the %VisualElement instance that is referenced
461 * @param[in] above Specifies the position of @c child relative to the @c pReference
462 * @exception E_SUCCESS The method is successful.
463 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
464 * - The specified @c child is not instantiated successfully. @n
465 * - The specified @c child is this instance. @n
466 * - The specified @c child and @c pReference are same. @n
467 * - The specified @c child is already an ancestor of this instance. @n
468 * - The parent of @c pReference is not this instance if @c pReference is not @c null. @n
469 * @remarks If @c above is @c true, the @c child will be attached above @c pReference in Z order,
470 * else it will be attached below the @c pReference %VisualElement. @n
471 * If @c pReference is @c null, the @c child will be attached at the highest position in the @c child's Z order group,
472 * else the child will be attached at the lowest position in the @c child's Z order group.
473 * @see SetZOrderGroup()
476 * @see ChangeZOrder()
478 result InsertChild(const VisualElement& child, const VisualElement* pReference, bool above);
481 * Inserts a child to this instance. @n
482 * 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
483 * placed right above or below the @c pReference instance according to the @c above parameter.
487 * @return An error code
488 * @param[in] pChild A pointer to %VisualElement instance to attach to this instance
489 * @param[in] pReference A pointer to the %VisualElement instance that is referenced
490 * @param[in] above Specifies the position of @c pChild relative to the @c pReference
491 * @exception E_SUCCESS The method is successful.
492 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
493 * - The specified @c pChild is not instantiated successfully. @n
494 * - The specified @c pChild is this instance. @n
495 * - The specified @c pChild and @c pReference are same. @n
496 * - The specified @c pChild is already an ancestor of this instance. @n
497 * - The parent of @c pReference is not this instance if @c pReference is not @c null. @n
498 * - The specified @c pChild is @c null.
499 * @remarks If @c above is @c true, the @c pChild will be attached above @c pReference in Z order,
500 * else it will be attached below the @c pReference %VisualElement. @n
501 * If @c pReference is @c null, the @c pChild will be attached at the highest position in the @c pChild's Z order group,
502 * else the child will be attached at the lowest position in the @c pChild's Z order group.
503 * @see SetZOrderGroup()
506 * @see ChangeZOrder()
508 result InsertChild(VisualElement* pChild, const VisualElement* pReference, bool above);
511 * Detaches a child from this instance.
515 * @return An error code
516 * @param[in] child The %VisualElement instance to detach from this instance
517 * @exception E_SUCCESS The method is successful.
518 * @exception E_OBJ_NOT_FOUND The specified @c child is not a child of this instance.
519 * @remarks This method detaches @c child from this instance. If you need to deallocate %VisualElement, call Destroy() method, not C++ delete.
523 result DetachChild(const VisualElement& child);
526 * Detaches a child from this instance.
530 * @return An error code
531 * @param[in] pChild A pointer to %VisualElement instance to detach from this instance
532 * @exception E_SUCCESS The method is successful.
533 * @exception E_OBJ_NOT_FOUND The specified @c pChild is not a child of this instance.
534 * @exception E_INVALID_ARG The specified @c pChild is @c null.
535 * @remarks This method detaches @c pChild from this instance. If you need to deallocate %VisualElement, call Destroy() method, not C++ delete.
539 result DetachChild(VisualElement* pChild);
542 * Changes Z order of this instance.
546 * @return An error code
547 * @param[in] pReference A pointer to the %VisualElement instance that is referenced
548 * @param[in] above Specifies the position of this instance relative to the @c pReference
549 * @exception E_SUCCESS The method is successful.
550 * @exception E_INVALID_ARG The input parameter is incorrect. Either of the following conditions has occurred: @n
551 * - This instance does not have a parent (not attached). @n
552 * - This instance and @c pReference do not have same parent if @c pReference is not @c null. @n
553 * - The specified @c pReference is this instance. @n
554 * @remarks If @c above is @c true, this instance will be attached above @c pReference in Z order,
555 * else it will be attached below the @c pReference %VisualElement. @n
556 * If @c pReference is @c null, this instance will be attached at the highest position in the Z order group of this instance,
557 * else the child will be attached at the lowest position in the Z order group of this instance.
562 result ChangeZOrder(const VisualElement* pReference, bool above);
565 * Gets the child of the specified @c name. @n
566 * If there are multiple matches of the name, it returns the first match.
570 * @return The %VisualElement instance having the specified @c name @n
571 * else @c null if there is not %VisualElement with the specified @c name
572 * @param[in] name The name of the %VisualElement
573 * @param[in] searchDescendants @c true to find a match among all the descendants of this instance, @n
575 * @exception E_SUCCESS The method is successful.
576 * @exception E_OBJ_NOT_FOUND There is no %VisualElement with the specified @c name.
577 * @remarks The specific error code can be accessed using the GetLastResult() method.
578 * @remarks If an exception occurs, this method returns @c null.
582 VisualElement* GetChild(const Tizen::Base::String& name, bool searchDescendants) const;
585 * Gets the farthest (highest Z order) %VisualElement descendant including this instance that contains a specified @c point. @n
586 * The OnHitTest() method or [HitTest](@ref Tizen::Ui::Animations::IVisualElementContentProvider::HitTest) callback may be called
587 * for descendants of this instance including itself.
591 * @return The %VisualElement that contains @c point, @n
592 * else @c null if @c point is completely outside of this instance
593 * @param[in] point The position in coordinate space of this instance
594 * @exception E_SUCCESS The method is successful.
595 * @exception E_OBJ_NOT_FOUND There is no %VisualElement containing the specified @c point.
596 * @remarks The specific error code can be accessed using the GetLastResult() method.
597 * @remarks If an exception occurs, this method returns @c null.
598 * @remarks This method assumes that all ancestors of this instance do not clip children.
599 * @see IVisualElementContentProvider::HitTest()
601 * @see IsClipChildrenEnabled()
602 * @see SetClipChildrenEnabled()
604 VisualElement* GetChildAt(const Tizen::Graphics::FloatPoint& point) const;
607 * Adds an animation without key name.
611 * @return An error code
612 * @param[in] animation The animation instance
613 * @exception E_SUCCESS The method is successful.
614 * @exception E_INVALID_ARG The input parameter is incorrect.
615 * @exception E_INVALID_OPERATION This instance is not a model object. @n
616 * An animation can be added to the model instance only.
617 * @see RemoveAnimation()
618 * @see GetAnimationN()
620 result AddAnimation(const VisualElementAnimation& animation);
623 * Adds an animation with key name.
627 * @return An error code
628 * @param[in] keyName The name of the animation that is used to identify animations @n
629 * Empty @c keyName is allowed.
630 * @param[in] animation The animation instance
631 * @exception E_SUCCESS The method is successful.
632 * @exception E_INVALID_ARG The input parameter is incorrect.
633 * @exception E_OBJ_ALREADY_EXIST An animation with @c keyName already exists.
634 * @exception E_INVALID_OPERATION This instance is not a model object. @n
635 * An animation can be added to the model instance only.
636 * @see RemoveAnimation()
637 * @see GetAnimationN()
639 result AddAnimation(const Tizen::Base::String& keyName, const VisualElementAnimation& animation);
642 * Removes the animation with the specified @c keyName.
646 * @return An error code
647 * @param[in] keyName The name of the animation to remove
648 * @exception E_SUCCESS The method is successful.
649 * @exception E_OBJ_NOT_FOUND An animation with @c keyName does not exist.
650 * @see AddAnimation()
651 * @see GetAnimationN()
653 result RemoveAnimation(const Tizen::Base::String& keyName);
656 * Gets the animation playing for the specified property.
660 * @return A pointer to the animation
661 * @param[in] keyName The name of the animation
662 * @exception E_SUCCESS The method is successful.
663 * @exception E_OBJ_NOT_FOUND An animation with @c keyName does not exist.
664 * @remarks The specific error code can be accessed using the GetLastResult() method.
665 * @remarks If an exception occurs, this method returns @c null.
666 * @see AddAnimation()
667 * @see RemoveAnimation()
669 VisualElementAnimation* GetAnimationN(const Tizen::Base::String& keyName) const;
672 * Removes all animations.
676 * @see AddAnimation()
677 * @see RemoveAnimation()
679 void RemoveAllAnimations(void);
682 * Adds a rectangle to update region of this instance. @n
683 * The update region represents the portion of the %VisualElement's area that must be redrawn by the OnDraw() method.
687 * @return An error code
688 * @param[in] pRectangle The pointer to the rectangular region that contains the coordinates of the rectangle to add to the update region @n
689 * If @c pRectangle is @c null, entire area is added to the update region.
690 * @exception E_SUCCESS The method is successful.
691 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method.
694 result InvalidateRectangle(const Tizen::Graphics::FloatRectangle* pRectangle);
697 * Gets the smallest rectangle that completely encloses the update region of this instance. @n
698 * Applications can use the update region in the OnDraw() method to minimize the redrawing area to improve performance.
699 * The %GetUpdateRectangle() method returns an empty rectangle if it is not called inside OnDraw() method.
703 * @return The rectangle to update
704 * @see InvalidateRectangle()
706 Tizen::Graphics::FloatRectangle GetUpdateRectangle(void) const;
709 * Updates the content area of all the descendants including this instance.
710 * The %Draw() method will call OnDraw() or DrawContent() method only if there are regions invalidated by InvalidateRectangle().
711 * The platform will call this method later automatically if applications do not call explicitly.
715 * @return An error code
716 * @exception E_SUCCESS The method is successful.
717 * @exception E_INVALID_STATE This instance is not attached to the maintained tree for displaying. @n
718 * For displaying, this instance should be descendant of the root %VisualElement.
719 * @exception E_SYSTEM A system error has occurred.
720 * @see IVisualElementContentProvider
725 * Marks the entire area of this instance to be flushed.
729 * @return An error code
730 * @exception E_SUCCESS The method is successful.
734 result SetFlushNeeded(void);
737 * Creates and returns a graphics canvas whose bounds, position, and size are equal to those of this instance.
741 * @return The graphic canvas of the %VisualElement, @n
742 * else @c null if an exception occurs
743 * @exception E_SUCCESS The method is successful.
744 * @exception E_INVALID_STATE This instance is in an invalid state.
745 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method. @n
746 The canvas can be created for the model instance only.
747 * @remarks This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the %VisualElement.
748 * It is the developer's responsibility to deallocate the canvas after use.
749 * The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
750 * Therefore, one must delete previously allocated canvas and create a new canvas using this method,
751 * if the size or position of the %VisualElement is changed. @n
752 * @remarks The specific error code can be accessed using the GetLastResult() method.
753 * @remarks If an exception occurs, this method returns @c null.
754 * @see GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
755 * @see GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
757 Tizen::Graphics::Canvas* GetCanvasN(void) const;
760 * Creates and returns a graphic canvas of the specified area.
764 * @return The graphic canvas of the %VisualElement, @n
765 * else @c null if an exception occurs
766 * @param[in] bounds The position relative to the top-left corner of the %VisualElement and size
767 * @exception E_SUCCESS The method is successful.
768 * @exception E_INVALID_STATE This instance is in an invalid state.
769 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method. @n
770 The canvas can be created for the model instance only.
771 * @exception E_OUT_OF_RANGE The specified @c bounds do not intersect with the bounds of the %VisualElement. @n
772 * The width and height must be greater than or equal to @c 0.
773 * @remarks Only the graphic canvas of displayable %VisualElement can be obtained.
774 * If the specified area is not inside the %VisualElement,
775 * the graphics canvas of overlapped area between the %VisualElement and the specified @c bound is returned. @n
776 * This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the %VisualElement.
777 * It is the developer's responsibility to deallocate the canvas after use.
778 * The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
779 * Therefore, one must delete previously allocated canvas and create a new canvas using this method,
780 * if the size or position of the control is changed. @n
781 * @remarks The specific error code can be accessed using the GetLastResult() method.
782 * @remarks If an exception occurs, this method returns @c null.
784 * @see GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
786 Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const;
789 * Creates and returns a graphic canvas of the specified area.
793 * @return The graphic canvas of %VisualElement, @n
794 * else @c null if an exception occurs
795 * @param[in] bounds The position relative to the top-left corner of %VisualElement and size
796 * @exception E_SUCCESS The method is successful.
797 * @exception E_INVALID_STATE This instance is in an invalid state.
798 * @exception E_INVALID_OPERATION The contents of this instance is set by the SetSurface() method. @n
799 The canvas can be created for the model instance only.
800 * @exception E_OUT_OF_RANGE The specified @c bounds do not intersect with the bounds of %VisualElement. @n
801 * The width and height must be greater than or equal to @c 0.
802 * @remarks Only the graphic canvas of displayable %VisualElement can be obtained.
803 * If the specified area is not inside %VisualElement,
804 * the graphics canvas of overlapped area between %VisualElement and the specified @c bound is returned. @n
805 * This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of %VisualElement.
806 * It is the developer's responsibility to deallocate the canvas after use.
807 * The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
808 * Therefore, one must delete previously allocated canvas and create a new canvas using this method,
809 * if the size or position of the control is changed.
810 * @remarks The specific error code can be accessed using the GetLastResult() method.
811 * @remarks If an exception occurs, this method returns @c null.
813 * @see GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
815 Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const;
818 * Gets the name of this instance.
822 * @return The name of this instance
824 Tizen::Base::String GetName(void) const;
827 * Sets the name of this instance.
831 * @param[in] name The name of the %VisualElement instance @n
832 * Empty or duplicated name with other instances are also allowed.
834 void SetName(const Tizen::Base::String& name);
837 * Gets the value of the %VisualElement's property.
841 * @return The value of the specified property
842 * @param[in] property The %VisualElement's property
843 * @exception E_SUCCESS The method is successful.
844 * @exception E_KEY_NOT_FOUND The specified @c property is not found.
845 * @remarks The specific error code can be accessed using the GetLastResult() method.
846 * @remarks If an exception occurs, this method returns @c Variant::NULL_VARIANT.
847 * @remarks Additional exceptions can occur according to the behavior of subclasses.
849 * @see OnGetPropertyRequested()
851 Variant GetProperty(const Tizen::Base::String& property) const;
854 * Sets the value of the %VisualElement's property.
858 * @return An error code
859 * @param[in] property The %VisualElement's property
860 * @param[in] value The value of the %VisualElement's property to set
861 * @exception E_SUCCESS The method is successful.
862 * @exception E_KEY_NOT_FOUND The specified @c property is not found.
863 * @remarks Additional exceptions can occur according to the behavior of subclasses.
865 * @see OnSetPropertyRequested()
867 result SetProperty(const Tizen::Base::String& property, const Variant& value);
870 * Sets the Z order group of this instance.
874 * @return An error code
875 * @param[in] zOrderGroup The value of Z order which must be between @c Z_ORDER_GROUP_LOWEST and @c Z_ORDER_GROUP_HIGHEST @n
876 * The default value is @c Z_ORDER_GROUP_NORMAL.
877 * @exception E_SUCCESS The method is successful.
878 * @exception E_OUT_OF_RANGE The @c zOrderGroup is not between @c Z_ORDER_GROUP_LOWEST and @c Z_ORDER_GROUP_HIGHEST.
879 * @remarks You can choose the @c zOrderGroup value as follows: @n
880 * - Tizen::Ui::Animations::Z_ORDER_GROUP_LOWEST @n
881 * - Tizen::Ui::Animations::Z_ORDER_GROUP_NORMAL @n
882 * - Tizen::Ui::Animations::Z_ORDER_GROUP_HIGHEST @n
883 * Or you can specify an integer value between @c ZORDER_GROUP_LOWEST and @c ZORDER_GROUP_HIGHEST.
884 * @see GetZOrderGroup()
886 result SetZOrderGroup(int zOrderGroup);
889 * Gets the Z order group of this instance.
893 * @return The Z order group of this instance
894 * @see SetZOrderGroup()
896 int GetZOrderGroup(void) const;
899 * Checks whether the redraw-on-resize feature is enabled.
903 * @return @c true if the redraw-on-resize feature is enabled, @n
905 * @remarks The entire content area will be added to the update region when bounds are changed if redraw-on-resize is enabled. @n
906 * Otherwise, current contents will be scaled for the new bounds of this instance without redrawing.
907 * @see SetRedrawOnResizeEnabled()
909 bool IsRedrawOnResizeEnabled(void) const;
912 * Enables or disables the redraw-on-resize feature.
916 * @param[in] enable Set to @c true if invalidation is needed whenever resized, @n
918 * @see IsRedrawOnResizeEnabled()
920 void SetRedrawOnResizeEnabled(bool enable);
923 * Gets the position and the size of this instance.
927 * @return An instance of the Tizen::Graphics::FloatRectangle that represents the position of top-left corner, @n
928 * the width, and the height of this instance. @n It has relative coordinate space to the parent.
931 Tizen::Graphics::FloatRectangle GetBounds(void) const;
934 * Sets the position and the size of this instance.
938 * @return An error code
939 * @param[in] bounds The new bounds of this instance
940 * @exception E_SUCCESS The method is successful.
941 * @exception E_INVALID_STATE This instance is in an invalid state.
942 * @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.
944 * @see IsRedrawOnResizeEnabled()
945 * @see SetRedrawOnResizeEnabled()
947 result SetBounds(const Tizen::Graphics::FloatRectangle& bounds);
950 * Gets the position on the Z-axis.
954 * @return The position on the Z-axis
955 * @see SetZPosition()
957 float GetZPosition(void) const;
960 * Sets the position on the Z-axis.
964 * @param[in] zPosition The position on the Z-axis
965 * @see GetZPosition()
967 void SetZPosition(float zPosition);
970 * Checks whether this instance is visible or not. @n
971 * Even if the show state is @c true, this instance can be invisible when show state of one of the ancestors is @c false.
975 * @return @c true if this instance is visible, @n
977 * @see GetShowState()
978 * @see SetShowState()
980 bool IsVisible(void) const;
983 * Gets the show state of this instance.
987 * @return The show state of the %VisualElement instance, @n
989 * @remarks Even if the show state is @c true, the %VisualElement is invisible if it is not attached to a parent.
990 * @see SetShowState()
993 bool GetShowState(void) const;
996 * Sets the show state of this instance.
1000 * @param[in] show Set to @c true if this instance needs to show, @n
1002 * @see GetShowState()
1005 void SetShowState(bool show);
1008 * Gets the opacity of this instance.
1012 * @return The opacity of this instance
1015 float GetOpacity(void) const;
1018 * Sets the opacity of this instance.
1022 * @param[in] opacity The new opacity which must be within the range [0.0, 1.0]
1023 * @remarks The changing opacity affects all the descendants of this instance.
1026 void SetOpacity(float opacity);
1029 * Enables or disables the implicit animation. @n
1030 * If enabled, implicit animations may be created whenever animatable properties of this instance change.
1034 * @param[in] enable Set to @c true to enable the implicit animation, @n
1036 * @remarks The implicit animation is enabled by default.
1037 * @see IsImplicitAnimationEnabled()
1039 void SetImplicitAnimationEnabled(bool enable);
1042 * Checks whether the implicit animation is enabled.
1046 * @return @c true if the implicit animation is enabled, @n
1048 * @see SetImplicitAnimationEnabled()
1050 bool IsImplicitAnimationEnabled(void) const;
1053 * Gets the transform matrix of this instance.
1057 * @return The transform matrix of this instance
1058 * @see SetTransformMatrix()
1060 Tizen::Graphics::FloatMatrix4 GetTransformMatrix(void) const;
1063 * Sets the transform matrix of this instance.
1067 * @return An error code
1068 * @param[in] transform The transform matrix
1069 * @exception E_SUCCESS The method is successful.
1070 * @exception E_INVALID_ARG The input parameter is incorrect. @n
1071 * The E_INVALID_ARG exception occurs when the specified @c transform is not invertible.
1072 * @see GetTransformMatrix()
1074 result SetTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1077 * Gets the transform matrix applied to each child.
1081 * @return The transform matrix applied to each child
1082 * @remarks The transform matrix for children is typically used for the projection matrix to layout children in 3D space.
1083 * @see SetChildrenTransformMatrix()
1085 Tizen::Graphics::FloatMatrix4 GetChildrenTransformMatrix(void) const;
1088 * Sets the transform matrix applied to each child.
1092 * @return An error code
1093 * @param[in] transform The transform matrix
1094 * @exception E_SUCCESS The method is successful.
1095 * @exception E_INVALID_ARG The input parameter is incorrect. @n
1096 * The E_INVALID_ARG exception occurs when the specified @c transform is not invertible.
1097 * @see GetChildrenTransformMatrix()
1099 result SetChildrenTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1103 * Gets the anchor point for this instance's transform matrix in uniform coordinate space
1104 * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1108 * @return The anchor point of this instance
1111 Tizen::Graphics::FloatPoint GetAnchor(void) const;
1114 * Sets the anchor point of this instance's transform matrix in uniform coordinate space
1115 * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1119 * @param[in] anchor The anchor point in uniform coordinate space
1122 void SetAnchor(const Tizen::Graphics::FloatPoint& anchor);
1125 * Gets the Z component of this instance's anchor point for transform matrix.
1129 * @return The Z component of the anchor point
1132 float GetAnchorZ(void) const;
1135 * Sets the Z component of this instance's anchor point for transform matrix.
1139 * @param[in] anchorZ The Z component of anchor point
1142 void SetAnchorZ(float anchorZ);
1145 * Gets the custom data of this instance.
1149 * @return The user data associated with this instance
1150 * @see SetUserData()
1152 void* GetUserData(void) const;
1155 * Sets the custom data of this instance.
1159 * @param[in] pUserData The user data associated with this instance
1160 * @see GetUserData()
1162 void SetUserData(void* pUserData);
1165 * Sets the contents of this instance with the specified VisualElementSurface. @n
1166 * The contents of the @c pSurface is not copied by the %SetSurface() method, but shared with this instance.
1170 * @return An error code
1171 * @param[in] pSurface The pointer to VisualElementSurface @n
1172 * If @c pSurface is @c null, surface will be created internally by system.
1173 * @exception E_SUCCESS The method is successful.
1174 * @exception E_INVALID_OPERATION This instance does not allow VisualElementSurface for contents.
1175 * @remarks If applications modify the contents of @c pSurface, the modifications will be applied to all
1176 * the %VisualElements which share same VisualElementSurface. But in this case, applications need to call
1177 * the SetFlushNeeded() method for those %VisualElements because the modifications of the @c pSurface will not be applied on the screen automatically.
1178 * @see GetSurfaceN()
1180 result SetSurface(VisualElementSurface* pSurface);
1183 * Gets the VisualElementSurface this instance uses for its contents.
1187 * @return A pointer to VisualElementSurface
1188 * @exception E_SUCCESS The method is successful.
1189 * @exception E_SYSTEM A system error has occurred.
1190 * @remarks The specific error code can be accessed using the GetLastResult() method.
1191 * @remarks If an exception occurs, this method returns @c null.
1194 VisualElementSurface* GetSurfaceN(void) const;
1197 * Sets the render operation of this instance.
1201 * @return An error code
1202 * @param[in] renderOperation The new rendering operation
1203 * @exception E_SUCCESS The method is successful.
1204 * @exception E_INVALID_ARG The specified @c renderOperation is out of range.
1205 * @see GetRenderOperation()
1207 result SetRenderOperation(RenderOperation renderOperation);
1210 * Gets the render operation of this instance.
1214 * @return The render operation of this instance
1215 * @see SetRenderOperation()
1217 RenderOperation GetRenderOperation(void) const;
1220 * Checks whether all the descendants are clipped to the bounds of this instance.
1224 * @return @c true if this instance clips all the descendants, @n
1226 * @see SetClipChildrenEnabled()
1228 bool IsClipChildrenEnabled(void) const;
1231 * Enables or disables clipping of all the descendants.
1235 * @param[in] clipChildren Set to @c true if all the descendants are needed to clip to the bounds of this instance, @n
1237 * @see IsClipChildrenEnabled()
1239 void SetClipChildrenEnabled(bool clipChildren);
1242 * Converts the specified @c point in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1243 * The coordinate is converted by projecting it on the root coordinate space.
1247 * @return An error code
1248 * @param[in,out] point The point to convert
1249 * @param[in] pFromVisualElement The %VisualElement instance with @c point in its coordinate space
1250 * @exception E_SUCCESS The method is successful.
1251 * @exception E_INVALID_ARG The input parameter is incorrect.
1252 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1253 * The matrix for this conversion is singular that has a zero determinant.
1254 * @remarks This instance and @c pFromVisualElement must share a common ancestor. @n
1255 * If @c null, it is regarded that @c point is in the root coordinate space.
1256 * @see ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement)
1258 result ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement) const;
1261 * Converts the specified @c rectangle in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1262 * The coordinate is converted by projecting it on the root coordinate space.
1266 * @return An error code
1267 * @param[in,out] rectangle The rectangle to convert
1268 * @param[in] pFromVisualElement The %VisualElement instance with @c rectangle in its coordinate space
1269 * @exception E_SUCCESS The method is successful.
1270 * @exception E_INVALID_ARG The input parameter is incorrect.
1271 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1272 * The matrix for this conversion is singular that has a zero determinant.
1273 * @remarks This instance and @c pFromVisualElement must share a common ancestor. @n
1274 * If @c null, it is regarded that @c rectangle is in the root coordinate space.
1275 * @see ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement)
1277 result ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement) const;
1280 * Transforms point in @c pOriginVisualElement coordinate space into the specified vector in this instance's coordinate space.
1284 * @return The transformed vector
1285 * @param[in] originPoint The point in @c pOriginVisualElement coordinate space
1286 * @param[in] pOriginVisualElement The %VisualElement instance with @c originPoint in its coordinate space
1287 * @exception E_SUCCESS The method is successful.
1288 * @exception E_INVALID_ARG The input parameter is incorrect.
1289 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1290 The matrix for this conversion is singular which has zero determinant.
1291 * @remarks This instance and @c pOriginVisualElement must share a common ancestor.
1292 * @remarks The specific error code can be accessed using the GetLastResult() method.
1294 Tizen::Graphics::FloatPoint3 TransformVectorFromOrigin(const Tizen::Graphics::FloatPoint3& originPoint, const VisualElement* pOriginVisualElement) const;
1297 * Sets the sub-rectangle of contents which this instance must display.
1301 * @return An error code
1302 * @param[in] contentBounds The sub-rectangle of contents to display in uniform coordinate space
1303 * @exception E_SUCCESS The method is successful.
1304 * @exception E_INVALID_ARG The width and height of @c contentBounds must be greater than @c 0.0.
1305 * @remarks Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1306 * @remarks If each component of @c contentBounds is not within the range [0.0, 1.0], the integer portion of the coordinates are
1307 * ignored and only fractional part is used which creates a repeating contents.
1308 * @see GetContentBounds()
1310 result SetContentBounds(const Tizen::Graphics::FloatRectangle& contentBounds);
1313 * Gets the sub-rectangle of contents which this instance must display.
1317 * @return The sub-rectangle of contents to be displayed in uniform coordinate space
1318 * @remarks Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1319 * @see SetContentBounds()
1321 Tizen::Graphics::FloatRectangle GetContentBounds(void) const;
1324 * Acquires the %VisualElement instance for display.
1328 * @return The %VisualElement instance for display(readonly)
1329 * @remarks If this instance is a presentation object, this method returns itself.
1330 * @see ReleasePresentationInstance()
1332 const VisualElement* AcquirePresentationInstance(void);
1335 * Releases the %VisualElement instance for display.
1339 * @remarks This method should be called only after AcquirePresentationInstance() call.
1340 * @see AcquirePresentationInstance()
1342 void ReleasePresentationInstance(void);
1345 * Acquires the %VisualElement instance for model.
1349 * @return The %VisualElement instance for model(readonly)
1350 * @remarks If this instance is a model object, this method returns itself.
1351 * @see ReleaseModelInstance()
1354 const VisualElement* AcquireModelInstance(void);
1357 * Releases the %VisualElement instance for model.
1361 * @remarks This method should be called only after AcquireModelInstance() call.
1363 void ReleaseModelInstance(void);
1366 * Flushes %VisualElements on screen.
1370 * @return An error code
1371 * @exception E_SUCCESS The method is successful.
1372 * @exception E_SYSTEM A system error has occurred.
1373 * @remarks Because this method may degrade the performance of system, applications must use this method only when really needed.
1374 * @see SetFlushNeeded()
1376 static result Flush(void);
1381 * This is copy constructor for the %VisualElement class.
1385 * @param[in] rhs An instance of %VisualElement
1388 VisualElement(const VisualElement& rhs);
1391 * This is the destructor for this class.
1395 * @remarks The delete operator cannot be used to deallocate the %VisualElement instance.
1398 virtual ~VisualElement(void);
1401 * Creates and returns a polymorphic copy of this %VisualElement instance for the presentation. @n
1402 * All descendants of %VisualElement must implement the %CloneN() method and the copy constructor appropriately. @n
1403 * When the %VisualElement instance is created, the framework make a %VisualElement for the presentation with this method.
1407 * @return The clone of this instance
1409 virtual VisualElement* CloneN(void) const;
1413 // This method is for internal use only. Using this method can cause behavioral, security-related,
1414 // and consistency-related issues in the application.
1417 // This method is reserved and may change its name at any time without prior notice.
1421 virtual void VisualElement_Reserved1(void) {}
1425 // This method is for internal use only. Using this method can cause behavioral, security-related,
1426 // and consistency-related issues in the application.
1429 // This method is reserved and may change its name at any time without prior notice.
1433 virtual void VisualElement_Reserved2(void) {}
1437 // This method is for internal use only. Using this method can cause behavioral, security-related,
1438 // and consistency-related issues in the application.
1441 // This method is reserved and may change its name at any time without prior notice.
1445 virtual void VisualElement_Reserved3(void) {}
1449 // This method is for internal use only. Using this method can cause behavioral, security-related,
1450 // and consistency-related issues in the application.
1453 // This method is reserved and may change its name at any time without prior notice.
1457 virtual void VisualElement_Reserved4(void) {}
1461 // This method is for internal use only. Using this method can cause behavioral, security-related,
1462 // and consistency-related issues in the application.
1465 // This method is reserved and may change its name at any time without prior notice.
1469 virtual void VisualElement_Reserved5(void) {}
1475 // The implementation of this assignment constructor is intentionally blank to prohibit assignment of objects.
1479 VisualElement& operator =(const VisualElement& rhs);
1483 _VisualElementImpl* _pVisualElementImpl;
1485 friend class _VisualElementImpl;
1489 }}} // Tizen::Ui::Animations
1491 #endif //_FUIANIMVISUALELEMENT_H_