inc/FUiAnimVisualElement.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://floralicense.org/license/
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file        FUiAnimVisualElement.h
  20  * @brief       This is the header file for the %VisualElement class.
  21  *
  22  * This header file contains the declarations of the %VisualElement class.
  23  */
  24
  25 #ifndef _FUI_ANIM_VISUAL_ELEMENT_H_
  26 #define _FUI_ANIM_VISUAL_ELEMENT_H_
  27
  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>
  39
  40 namespace Tizen { namespace Graphics {
  41 class Canvas;
  42 }}
  43
  44 namespace Tizen { namespace Ui { namespace Animations
  45 {
  46
  47 class VisualElementSurface;
  48 class _VisualElementImpl;
  49
  50
  51 /**
  52  * @class       VisualElement
  53  * @brief       This class is a base class for all displayable objects on screen with animations.
  54  *
  55  * @since       2.0
  56  *
  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.
  66  *
  67  * This class also provides interfaces such as IVisualElementContentProvider, IVisualElementEventListener, and IVisualElementAnimationProvider to override default behaviors
  68  * without inheritances.
  69  *
  70  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/visualelement.htm">Visual Elements</a>.
  71  *
  72  */
  73
  74 class _OSP_EXPORT_ VisualElement
  75         : public Tizen::Base::Object
  76 {
  77 public:
  78         /**
  79          * The lowest drawing group, such as, background element.
  80          *
  81          * @since               2.0
  82          */
  83         static const int Z_ORDER_GROUP_LOWEST   = -1000;
  84
  85
  86         /**
  87          * The level of the default group.
  88          *
  89          * @since               2.0
  90          */
  91         static const int Z_ORDER_GROUP_NORMAL   = 0;
  92
  93
  94         /**
  95          * The highest drawing group, such as, top-most element.
  96          *
  97          * @since               2.0
  98          */
  99         static const int Z_ORDER_GROUP_HIGHEST  = 1000;
 100
 101
 102         /**
 103          *      @enum RenderOperation
 104          *      Defines the render operation for %VisualElement. @n
 105          *      The contents of %VisualElement will be composited on screen using this operation.
 106          */
 107         enum RenderOperation
 108         {
 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 */
 111         };
 112
 113
 114         /**
 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.
 117          *
 118          * @since               2.0
 119          */
 120         VisualElement(void);
 121
 122         /**
 123          * Initializes this instance of %VisualElement.
 124          *
 125          * @since               2.0
 126          *
 127          * @return              An error code
 128          * @exception   E_SUCCESS                       The method is successful.
 129          * @exception   E_SYSTEM                        A system error has occurred.
 130          */
 131         result Construct(void);
 132
 133         /**
 134          * Deallocates this instance and all descendants of %VisualElement.
 135          *
 136          * @since               2.0
 137          *
 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.
 148          * @see Construct()
 149          */
 150         void Destroy(void);
 151
 152         /**
 153          * Sets the animation provider which creates implicit animations.
 154          *
 155          * @since               2.0
 156          *
 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.
 162          *
 163          * @see         IVisualElementAnimationProvider
 164          * @see         GetAnimationProvider()
 165          */
 166         result SetAnimationProvider(IVisualElementAnimationProvider* pProvider);
 167
 168         /**
 169          * Gets the assigned animation provider.
 170          *
 171          * @since               2.0
 172          *
 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()
 179          */
 180         IVisualElementAnimationProvider* GetAnimationProvider(void) const;
 181
 182         /**
 183          * Sets the content provider which customizes information on contents.
 184          *
 185          * @since               2.0
 186          *
 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()
 194          */
 195         result SetContentProvider(IVisualElementContentProvider* pProvider);
 196
 197         /**
 198          * Gets the assigned content provider.
 199          *
 200          * @since               2.0
 201          *
 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()
 208          */
 209         IVisualElementContentProvider* GetContentProvider(void) const;
 210
 211         /**
 212          * Sets the %VisualElement event listener.
 213          *
 214          * @since               2.0
 215          *
 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()
 223          */
 224         result SetVisualElementEventListener(IVisualElementEventListener* pListener);
 225
 226         /**
 227          * Gets the assigned %VisualElement event listener.
 228          *
 229          * @since               2.0
 230          *
 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()
 237          */
 238         IVisualElementEventListener* GetVisualElementEventListener(void) const;
 239
 240
 241         /**
 242          * Overrides the OnConstructed() method to provide user-specific initialization code.
 243          *
 244          * @since               2.0
 245          *
 246          * @remarks             This method is called after the instance is initialized by the Construct() method successfully.
 247          * @see Construct()
 248          * @see Destroy()
 249          * @see OnDestructing()
 250          */
 251         virtual void OnConstructed(void);
 252
 253         /**
 254          * Overrides the OnDestructing() method to provide user-specific termination code.
 255          *
 256          * @since               2.0
 257          *
 258          * @remarks             This method is called before deallocating the %VisualElement instance by the Destroy() method.
 259          * @see Destroy()
 260          * @see Construct()
 261          * @see OnConstructed()
 262          */
 263         virtual void OnDestructing(void);
 264
 265         /**
 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.
 269          *
 270          * @since               2.0
 271          *
 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
 277          * @see GetChildAt()
 278          * @see IVisualElementContentProvider::HitTest()
 279          */
 280         virtual HitTestResult OnHitTest(const Tizen::Graphics::FloatPoint& point);
 281
 282         /**
 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.
 286          *
 287          * @since               2.0
 288          *
 289          * @return              @c true if OnDraw() can be called, @n
 290          *              else @c false
 291          * @see IVisualElementContentProvider::PrepareDraw()
 292          */
 293         virtual bool OnPrepareDraw(void);
 294
 295         /**
 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.
 299          *
 300          * @since               2.0
 301          *
 302          * @param[in]   canvas                  The canvas to fill the contents of %VisualElement
 303          * @see IVisualElementContentProvider::DrawContent()
 304          */
 305         virtual void OnDraw(Tizen::Graphics::Canvas& canvas);
 306
 307         /**
 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.
 311          *
 312          * @since               2.0
 313          *
 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()
 320          */
 321         virtual VisualElementAnimation* OnCreateAnimationForProperty(const Tizen::Base::String& property);
 322
 323         /**
 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.
 326          *
 327          * @since               2.0
 328          *
 329          * @return              The property's value
 330          * @param[in]   property                        The property name
 331          * @see                 SetProperty()
 332          * @see                 GetProperty()
 333          * @see                 OnSetPropertyRequested()
 334          */
 335         virtual Tizen::Ui::Variant OnGetPropertyRequested(const Tizen::Base::String& property) const;
 336
 337         /**
 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.
 340          *
 341          * @since               2.0
 342          *
 343          * @return              An error code
 344          * @param[in]   property                        The property name
 345          * @param[in]   value                           The value of the property to set
 346          * @see                 SetProperty()
 347          * @see                 GetProperty()
 348          * @see                 OnGetPropertyRequested()
 349          */
 350         virtual result OnSetPropertyRequested(const Tizen::Base::String& property, const Tizen::Ui::Variant& value);
 351
 352         /**
 353          * Gets the parent of this instance.
 354          *
 355          * @since               2.0
 356          *
 357          * @return              The parent of the this instance
 358          */
 359         VisualElement* GetParent(void) const;
 360
 361         /**
 362          * Gets a list of children of this instance.
 363          *
 364          * @since               2.0
 365          *
 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.
 371          */
 372         Tizen::Base::Collection::IList* GetChildrenN(void) const;
 373
 374         /**
 375          * Gets the count of children.
 376          *
 377          * @since               2.0
 378          *
 379          * @return              The count of children
 380          */
 381         int GetChildrenCount(void) const;
 382
 383         /**
 384          * Checks whether this instance is a child or descendant of the specified one.
 385          *
 386          * @since               2.0
 387          *
 388          * @return              @c true if this instance is a child or descendant of the specified one, @n
 389          *                              else @c false
 390          * @param[in]   other                           An instance of %VisualElement to test relationship
 391          */
 392         bool IsChildOf(const VisualElement& other) const;
 393
 394         /**
 395          * Checks whether this instance is a child or descendant of the specified one.
 396          *
 397          * @since               2.1
 398          *
 399          * @return              @c true if this instance is a child or descendant of the specified one, @n
 400          *                              else @c false
 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.
 405          */
 406         bool IsChildOf(const VisualElement* pOther) const;
 407
 408         /**
 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.
 412          *
 413          * @since               2.0
 414          *
 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()
 423          * @see         InsertChild()
 424          * @see         DetachChild()
 425          * @see         ChangeZOrder()
 426          */
 427         result AttachChild(const VisualElement& child);
 428
 429         /**
 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.
 433          *
 434          * @since               2.1
 435          *
 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()
 445          * @see         InsertChild()
 446          * @see         DetachChild()
 447          * @see         ChangeZOrder()
 448          */
 449         result AttachChild(VisualElement* pChild);
 450
 451         /**
 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.
 455          *
 456          * @since               2.0
 457          *
 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()
 474          * @see         AttachChild()
 475          * @see         DetachChild()
 476          * @see         ChangeZOrder()
 477          */
 478         result InsertChild(const VisualElement& child, const VisualElement* pReference, bool above);
 479
 480         /**
 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.
 484          *
 485          * @since               2.1
 486          *
 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()
 504          * @see         AttachChild()
 505          * @see         DetachChild()
 506          * @see         ChangeZOrder()
 507          */
 508         result InsertChild(VisualElement* pChild, const VisualElement* pReference, bool above);
 509
 510         /**
 511          * Detaches a child from this instance.
 512          *
 513          * @since               2.0
 514          *
 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.
 520          * @see         InsertChild()
 521          * @see         AttachChild()
 522          */
 523         result DetachChild(const VisualElement& child);
 524
 525         /**
 526          * Detaches a child from this instance.
 527          *
 528          * @since               2.1
 529          *
 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.
 536          * @see                InsertChild()
 537          * @see         AttachChild()
 538          */
 539         result DetachChild(VisualElement* pChild);
 540
 541         /**
 542          * Changes Z order of this instance.
 543          *
 544          * @since               2.0
 545          *
 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.
 558          * @see         InsertChild()
 559          * @see         AttachChild()
 560          * @see         DetachChild()
 561          */
 562         result ChangeZOrder(const VisualElement* pReference, bool above);
 563
 564         /**
 565          * Gets the child of the specified @c name. @n
 566          * If there are multiple matches of the name, it returns the first match.
 567          *
 568          * @since               2.0
 569          *
 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
 574          *                                                                      else @c false
 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.
 579          * @see         GetName()
 580          * @see         SetName()
 581          */
 582         VisualElement* GetChild(const Tizen::Base::String& name, bool searchDescendants) const;
 583
 584         /**
 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.
 588          *
 589          * @since               2.0
 590          *
 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()
 600          * @see         OnHitTest()
 601          * @see         IsClipChildrenEnabled()
 602          * @see         SetClipChildrenEnabled()
 603          */
 604         VisualElement* GetChildAt(const Tizen::Graphics::FloatPoint& point) const;
 605
 606         /**
 607          * Adds an animation without key name.
 608          *
 609          * @since               2.0
 610          *
 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()
 619          */
 620         result AddAnimation(const VisualElementAnimation& animation);
 621
 622         /**
 623          * Adds an animation with key name.
 624          *
 625          * @since               2.0
 626          *
 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()
 638          */
 639         result AddAnimation(const Tizen::Base::String& keyName, const VisualElementAnimation& animation);
 640
 641         /**
 642          * Removes the animation with the specified @c keyName.
 643          *
 644          * @since               2.0
 645          *
 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()
 652          */
 653         result RemoveAnimation(const Tizen::Base::String& keyName);
 654
 655         /**
 656          * Gets the animation playing for the specified property.
 657          *
 658          * @since               2.0
 659          *
 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()
 668          */
 669         VisualElementAnimation* GetAnimationN(const Tizen::Base::String& keyName) const;
 670
 671         /**
 672          * Removes all animations.
 673          *
 674          * @since               2.0
 675          *
 676          * @see                 AddAnimation()
 677          * @see                 RemoveAnimation()
 678          */
 679         void RemoveAllAnimations(void);
 680
 681         /**
 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.
 684          *
 685          * @since               2.0
 686          *
 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.
 692          * @see                 SetSurface()
 693          */
 694         result InvalidateRectangle(const Tizen::Graphics::FloatRectangle* pRectangle);
 695
 696         /**
 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.
 700          *
 701          * @since               2.0
 702          *
 703          * @return              The rectangle to update
 704          * @see                 InvalidateRectangle()
 705          */
 706         Tizen::Graphics::FloatRectangle GetUpdateRectangle(void) const;
 707
 708         /**
 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.
 712          *
 713          * @since               2.0
 714          *
 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
 721          */
 722         result Draw(void);
 723
 724         /**
 725          * Marks the entire area of this instance to be flushed.
 726          *
 727          * @since               2.0
 728          *
 729          * @return              An error code
 730          * @exception   E_SUCCESS                       The method is successful.
 731          *
 732          * @see         Flush()
 733          */
 734         result SetFlushNeeded(void);
 735
 736         /**
 737          * Creates and returns a graphics canvas whose bounds, position, and size are equal to those of this instance.
 738          *
 739          * @since               2.0
 740          *
 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)
 756          */
 757         Tizen::Graphics::Canvas* GetCanvasN(void) const;
 758
 759         /**
 760          * Creates and returns a graphic canvas of the specified area.
 761          *
 762          * @since               2.0
 763          *
 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.
 783          * @see                 GetCanvasN()
 784          * @see                 GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
 785          */
 786         Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const;
 787
 788         /**
 789          * Creates and returns a graphic canvas of the specified area.
 790          *
 791          * @since               2.1
 792          *
 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.
 812          * @see                 GetCanvasN()
 813          * @see                 GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
 814          */
 815         Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const;
 816
 817         /**
 818          * Gets the name of this instance.
 819          *
 820          * @since               2.0
 821          *
 822          * @return              The name of this instance
 823          */
 824         Tizen::Base::String GetName(void) const;
 825
 826         /**
 827          * Sets the name of this instance.
 828          *
 829          * @since               2.0
 830          *
 831          * @param[in]   name                            The name of the %VisualElement instance @n
 832          *                                  Empty or duplicated name with other instances are also allowed.
 833          */
 834         void SetName(const Tizen::Base::String& name);
 835
 836         /**
 837          * Gets the value of the %VisualElement's property.
 838          *
 839          * @since               2.0
 840          *
 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.
 848          * @see                 SetProperty()
 849          * @see                 OnGetPropertyRequested()
 850          */
 851         Variant GetProperty(const Tizen::Base::String& property) const;
 852
 853         /**
 854          * Sets the value of the %VisualElement's property.
 855          *
 856          * @since               2.0
 857          *
 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.
 864          * @see                 GetProperty()
 865          * @see                 OnSetPropertyRequested()
 866          */
 867         result SetProperty(const Tizen::Base::String& property, const Variant& value);
 868
 869         /**
 870          * Sets the Z order group of this instance.
 871          *
 872          * @since               2.0
 873          *
 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()
 885          */
 886         result SetZOrderGroup(int zOrderGroup);
 887
 888         /**
 889          * Gets the Z order group of this instance.
 890          *
 891          * @since               2.0
 892          *
 893          * @return              The Z order group of this instance
 894          * @see SetZOrderGroup()
 895          */
 896         int GetZOrderGroup(void) const;
 897
 898         /**
 899          * Checks whether the redraw-on-resize feature is enabled.
 900          *
 901          * @since               2.0
 902          *
 903          * @return              @c true if the redraw-on-resize feature is enabled, @n
 904          *                              else @c false
 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()
 908          */
 909         bool IsRedrawOnResizeEnabled(void) const;
 910
 911         /**
 912          * Enables or disables the redraw-on-resize feature.
 913          *
 914          * @since               2.0
 915          *
 916          * @param[in]   enable                          Set to @c true if invalidation is needed whenever resized, @n
 917          *                                                                      else @c false
 918          * @see IsRedrawOnResizeEnabled()
 919          */
 920         void SetRedrawOnResizeEnabled(bool enable);
 921
 922         /**
 923          * Gets the position and the size of this instance.
 924          *
 925          * @since               2.0
 926          *
 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.
 929          * @see                 SetBounds()
 930          */
 931         Tizen::Graphics::FloatRectangle GetBounds(void) const;
 932
 933         /**
 934          * Sets the position and the size of this instance.
 935          *
 936          * @since               2.0
 937          *
 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.
 943          * @see                 GetBounds()
 944          * @see                 IsRedrawOnResizeEnabled()
 945          * @see                 SetRedrawOnResizeEnabled()
 946          */
 947         result SetBounds(const Tizen::Graphics::FloatRectangle& bounds);
 948
 949         /**
 950          * Gets the position on the Z-axis.
 951          *
 952          * @since               2.0
 953          *
 954          * @return              The position on the Z-axis
 955          * @see                 SetZPosition()
 956          */
 957         float GetZPosition(void) const;
 958
 959         /**
 960          * Sets the position on the Z-axis.
 961          *
 962          * @since               2.0
 963          *
 964          * @param[in]   zPosition                       The position on the Z-axis
 965          * @see                 GetZPosition()
 966          */
 967         void SetZPosition(float zPosition);
 968
 969         /**
 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.
 972          *
 973          * @since               2.0
 974          *
 975          * @return              @c true if this instance is visible, @n
 976          *                              else @c false
 977          * @see                 GetShowState()
 978          * @see                 SetShowState()
 979          */
 980         bool IsVisible(void) const;
 981
 982         /**
 983          * Gets the show state of this instance.
 984          *
 985          * @since               2.0
 986          *
 987          * @return              The show state of the %VisualElement instance, @n
 988          *                              else @c false
 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()
 991          * @see                 IsVisible()
 992          */
 993         bool GetShowState(void) const;
 994
 995         /**
 996          * Sets the show state of this instance.
 997          *
 998          * @since               2.0
 999          *
1000          * @param[in]   show                            Set to @c true if this instance needs to show, @n
1001          *                                                                      else @c false
1002          * @see                 GetShowState()
1003          * @see                 IsVisible()
1004          */
1005         void SetShowState(bool show);
1006
1007         /**
1008          * Gets the opacity of this instance.
1009          *
1010          * @since               2.0
1011          *
1012          * @return              The opacity of this instance
1013          * @see                 SetOpacity()
1014          */
1015         float GetOpacity(void) const;
1016
1017         /**
1018          * Sets the opacity of this instance.
1019          *
1020          * @since               2.0
1021          *
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.
1024          * @see                 GetOpacity()
1025          */
1026         void SetOpacity(float opacity);
1027
1028         /**
1029          * Enables or disables the implicit animation. @n
1030          * If enabled, implicit animations may be created whenever animatable properties of this instance change.
1031          *
1032          * @since               2.0
1033          *
1034          * @param[in]   enable  Set to @c true to enable the implicit animation, @n
1035          *                                              else @c false
1036          * @remarks             The implicit animation is enabled by default.
1037          * @see                 IsImplicitAnimationEnabled()
1038          */
1039         void SetImplicitAnimationEnabled(bool enable);
1040
1041         /**
1042          * Checks whether the implicit animation is enabled.
1043          *
1044          * @since               2.0
1045          *
1046          * @return              @c true if the implicit animation is enabled, @n
1047          *                              else @c false
1048          * @see                 SetImplicitAnimationEnabled()
1049          */
1050         bool IsImplicitAnimationEnabled(void) const;
1051
1052         /**
1053          * Gets the transform matrix of this instance.
1054          *
1055          * @since               2.0
1056          *
1057          * @return              The transform matrix of this instance
1058          * @see                 SetTransformMatrix()
1059          */
1060         Tizen::Graphics::FloatMatrix4 GetTransformMatrix(void) const;
1061
1062         /**
1063          * Sets the transform matrix of this instance.
1064          *
1065          * @since               2.0
1066          *
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()
1073          */
1074         result SetTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1075
1076         /**
1077          * Gets the transform matrix applied to each child.
1078          *
1079          * @since               2.0
1080          *
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()
1084          */
1085         Tizen::Graphics::FloatMatrix4 GetChildrenTransformMatrix(void) const;
1086
1087         /**
1088          * Sets the transform matrix applied to each child.
1089          *
1090          * @since               2.0
1091          *
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()
1098          */
1099         result SetChildrenTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1100
1101
1102         /**
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).
1105          *
1106          * @since               2.0
1107          *
1108          * @return              The anchor point of this instance
1109          * @see                 SetAnchor()
1110          */
1111         Tizen::Graphics::FloatPoint GetAnchor(void) const;
1112
1113         /**
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).
1116          *
1117          * @since               2.0
1118          *
1119          * @param[in]   anchor                          The anchor point in uniform coordinate space
1120          * @see                 GetAnchor()
1121          */
1122         void SetAnchor(const Tizen::Graphics::FloatPoint& anchor);
1123
1124         /**
1125          * Gets the Z component of this instance's anchor point for transform matrix.
1126          *
1127          * @since               2.0
1128          *
1129          * @return              The Z component of the anchor point
1130          * @see                 SetAnchorZ()
1131          */
1132         float GetAnchorZ(void) const;
1133
1134         /**
1135          * Sets the Z component of this instance's anchor point for transform matrix.
1136          *
1137          * @since               2.0
1138          *
1139          * @param[in]   anchorZ                         The Z component of anchor point
1140          * @see                 GetAnchorZ()
1141          */
1142         void SetAnchorZ(float anchorZ);
1143
1144         /**
1145          * Gets the custom data of this instance.
1146          *
1147          * @since               2.0
1148          *
1149          * @return              The user data associated with this instance
1150          * @see                 SetUserData()
1151          */
1152         void* GetUserData(void) const;
1153
1154         /**
1155          * Sets the custom data of this instance.
1156          *
1157          * @since               2.0
1158          *
1159          * @param[in]   pUserData                       The user data associated with this instance
1160          * @see                 GetUserData()
1161          */
1162         void SetUserData(void* pUserData);
1163
1164         /**
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.
1167          *
1168          * @since               2.0
1169          *
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()
1179          */
1180         result SetSurface(VisualElementSurface* pSurface);
1181
1182         /**
1183          * Gets the VisualElementSurface this instance uses for its contents.
1184          *
1185          * @since               2.0
1186          *
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.
1192          * @see                 SetSurface()
1193          */
1194         VisualElementSurface* GetSurfaceN(void) const;
1195
1196         /**
1197          * Sets the render operation of this instance.
1198          *
1199          * @since               2.0
1200          *
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()
1206          */
1207         result SetRenderOperation(RenderOperation renderOperation);
1208
1209         /**
1210          * Gets the render operation of this instance.
1211          *
1212          * @since               2.0
1213          *
1214          * @return              The render operation of this instance
1215          * @see                 SetRenderOperation()
1216          */
1217         RenderOperation GetRenderOperation(void) const;
1218
1219         /**
1220          * Checks whether all the descendants are clipped to the bounds of this instance.
1221          *
1222          * @since               2.0
1223          *
1224          * @return              @c true if this instance clips all the descendants, @n
1225          *              else @c false
1226          * @see                 SetClipChildrenEnabled()
1227          */
1228         bool IsClipChildrenEnabled(void) const;
1229
1230         /**
1231          * Enables or disables clipping of all the descendants.
1232          *
1233          * @since               2.0
1234          *
1235          * @param[in]   clipChildren            Set to @c true if all the descendants are needed to clip to the bounds of this instance, @n
1236          *                                      else @c false
1237          * @see                 IsClipChildrenEnabled()
1238          */
1239         void SetClipChildrenEnabled(bool clipChildren);
1240
1241         /**
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.
1244          *
1245          * @since                       2.0
1246          *
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)
1257          */
1258         result ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement) const;
1259
1260         /**
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.
1263          *
1264          * @since                       2.0
1265          *
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)
1276          */
1277         result ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement) const;
1278
1279         /**
1280          * Transforms point in @c pOriginVisualElement coordinate space into the specified vector in this instance's coordinate space.
1281          *
1282          * @since                       2.1
1283          *
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.
1293          */
1294         Tizen::Graphics::FloatPoint3 TransformVectorFromOrigin(const Tizen::Graphics::FloatPoint3& originPoint, const VisualElement* pOriginVisualElement) const;
1295
1296         /**
1297          * Sets the sub-rectangle of contents which this instance must display.
1298          *
1299          * @since               2.0
1300          *
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()
1309          */
1310         result SetContentBounds(const Tizen::Graphics::FloatRectangle& contentBounds);
1311
1312         /**
1313          * Gets the sub-rectangle of contents which this instance must display.
1314          *
1315          * @since               2.0
1316          *
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()
1320          */
1321         Tizen::Graphics::FloatRectangle GetContentBounds(void) const;
1322
1323         /**
1324          * Acquires the %VisualElement instance for display.
1325          *
1326          * @since               2.0
1327          *
1328          * @return              The %VisualElement instance for display(readonly)
1329          * @remarks             If this instance is a presentation object, this method returns itself.
1330          * @see                ReleasePresentationInstance()
1331          */
1332         const VisualElement* AcquirePresentationInstance(void);
1333
1334         /**
1335          * Releases the %VisualElement instance for display.
1336          *
1337          * @since               2.0
1338          *
1339          * @remarks             This method should be called only after AcquirePresentationInstance() call.
1340          * @see                AcquirePresentationInstance()
1341          */
1342         void ReleasePresentationInstance(void);
1343
1344         /**
1345          * Acquires the %VisualElement instance for model.
1346          *
1347          * @since               2.0
1348          *
1349          * @return              The %VisualElement instance for model(readonly)
1350          * @remarks             If this instance is a model object, this method returns itself.
1351          * @see                ReleaseModelInstance()
1352          */
1353
1354         const VisualElement* AcquireModelInstance(void);
1355
1356         /**
1357          * Releases the %VisualElement instance for model.
1358          *
1359          * @since               2.0
1360          *
1361          * @remarks             This method should be called only after AcquireModelInstance() call.
1362          */
1363         void ReleaseModelInstance(void);
1364
1365         /**
1366          * Flushes %VisualElements on screen.
1367          *
1368          * @since               2.0
1369          *
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()
1375          */
1376         static result Flush(void);
1377
1378
1379 protected:
1380         /**
1381          * This is copy constructor for the %VisualElement class.
1382          *
1383          * @since               2.0
1384          *
1385          * @param[in]   rhs                     An instance of %VisualElement
1386          * @see         CloneN()
1387          */
1388         VisualElement(const VisualElement& rhs);
1389
1390         /**
1391          * This is the destructor for this class.
1392          *
1393          * @since               2.0
1394          *
1395          * @remarks             The delete operator cannot be used to deallocate the %VisualElement instance.
1396          * @see         Destroy()
1397          */
1398         virtual ~VisualElement(void);
1399
1400         /**
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.
1404          *
1405          * @since               2.0
1406          *
1407          * @return              The clone of this instance
1408          */
1409         virtual VisualElement* CloneN(void) const;
1410
1411
1412         //
1413         // This method is for internal use only. Using this method can cause behavioral, security-related,
1414         // and consistency-related issues in the application.
1415         //
1416         //
1417         // This method is reserved and may change its name at any time without prior notice.
1418         //
1419         // @since               2.0
1420         //
1421         virtual void VisualElement_Reserved1(void) {}
1422
1423
1424         //
1425         // This method is for internal use only. Using this method can cause behavioral, security-related,
1426         // and consistency-related issues in the application.
1427         //
1428         //
1429         // This method is reserved and may change its name at any time without prior notice.
1430         //
1431         // @since               2.0
1432         //
1433         virtual void VisualElement_Reserved2(void) {}
1434
1435
1436         //
1437         // This method is for internal use only. Using this method can cause behavioral, security-related,
1438         // and consistency-related issues in the application.
1439         //
1440         //
1441         // This method is reserved and may change its name at any time without prior notice.
1442         //
1443         // @since               2.0
1444         //
1445         virtual void VisualElement_Reserved3(void) {}
1446
1447
1448         //
1449         // This method is for internal use only. Using this method can cause behavioral, security-related,
1450         // and consistency-related issues in the application.
1451         //
1452         //
1453         // This method is reserved and may change its name at any time without prior notice.
1454         //
1455         // @since               2.0
1456         //
1457         virtual void VisualElement_Reserved4(void) {}
1458
1459
1460         //
1461         // This method is for internal use only. Using this method can cause behavioral, security-related,
1462         // and consistency-related issues in the application.
1463         //
1464         //
1465         // This method is reserved and may change its name at any time without prior notice.
1466         //
1467         // @since               2.0
1468         //
1469         virtual void VisualElement_Reserved5(void) {}
1470
1471
1472 private:
1473
1474         //
1475         // The implementation of this assignment constructor is intentionally blank to prohibit assignment of objects.
1476         //
1477         // @since               2.0
1478         //
1479         VisualElement& operator =(const VisualElement& rhs);
1480
1481
1482 protected:
1483         _VisualElementImpl* _pVisualElementImpl;
1484
1485         friend class _VisualElementImpl;
1486 };              // VisualElement
1487
1488
1489 }}}             // Tizen::Ui::Animations
1490
1491 #endif //_FUIANIMVISUALELEMENT_H_