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.
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 an instance is a child or descendant of a specified one.
399 * @return @c true if this instance is a child or descendant of a specified one, @n
401 * @param[in] pOther A pointer to %VisualElement instance to check its relationship
402 * @exception E_SUCCESS The method is successful.
403 * @exception E_INVALID_ARG The specified @c pOther is @c 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 an 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 * Z-Order group can be changed 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 an 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 insert
489 * @param[in] pReference A pointer to the %VisualElement instance to refer
490 * @param[in] above The position of @c pChild relative to @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 is attached above @c pReference in Z order,
500 * else it is attached below the @c pReference %VisualElement. @n
501 * If @c pReference is @c null, the @c pChild is attached at the highest position in the @c pChild's Z order group,
502 * else the child is 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 an instance.
530 * @return An error code
531 * @param[in] pChild A pointer to %VisualElement instance to detach
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. To deallocate %VisualElement, call Destroy() method, and 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 a point in @c pOriginVisualElement coordinate space into a specified vector in calling 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 * - 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_