inc/FUiAnimVisualElement.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  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 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.
  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 an instance is a child or descendant of a specified one.
 396          *
 397          * @since               2.1
 398          *
 399          * @return              @c true if this instance is a child or descendant of a specified one, @n
 400          *                              else @c false
 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.
 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 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.
 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 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.
 484          *
 485          * @since               2.1
 486          *
 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()
 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 an instance.
 527          *
 528          * @since               2.1
 529          *
 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.
 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.
1071          * @see                 GetTransformMatrix()
1072          */
1073         result SetTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1074
1075         /**
1076          * Gets the transform matrix applied to each child.
1077          *
1078          * @since               2.0
1079          *
1080          * @return              The transform matrix applied to each child
1081          * @remarks             The transform matrix for children is typically used for the projection matrix to layout children in 3D space.
1082          * @see                 SetChildrenTransformMatrix()
1083          */
1084         Tizen::Graphics::FloatMatrix4 GetChildrenTransformMatrix(void) const;
1085
1086         /**
1087          * Sets the transform matrix applied to each child.
1088          *
1089          * @since               2.0
1090          *
1091          * @return              An error code
1092          * @param[in]   transform                       The transform matrix
1093          * @exception   E_SUCCESS                       The method is successful.
1094          * @exception   E_INVALID_ARG           The input parameter is incorrect.
1095          * @see                 GetChildrenTransformMatrix()
1096          */
1097         result SetChildrenTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1098
1099
1100         /**
1101          * Gets the anchor point for this instance's transform matrix in uniform coordinate space
1102          * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1103          *
1104          * @since               2.0
1105          *
1106          * @return              The anchor point of this instance
1107          * @see                 SetAnchor()
1108          */
1109         Tizen::Graphics::FloatPoint GetAnchor(void) const;
1110
1111         /**
1112          * Sets the anchor point of this instance's transform matrix in uniform coordinate space
1113          * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1114          *
1115          * @since               2.0
1116          *
1117          * @param[in]   anchor                          The anchor point in uniform coordinate space
1118          * @see                 GetAnchor()
1119          */
1120         void SetAnchor(const Tizen::Graphics::FloatPoint& anchor);
1121
1122         /**
1123          * Gets the Z component of this instance's anchor point for transform matrix.
1124          *
1125          * @since               2.0
1126          *
1127          * @return              The Z component of the anchor point
1128          * @see                 SetAnchorZ()
1129          */
1130         float GetAnchorZ(void) const;
1131
1132         /**
1133          * Sets the Z component of this instance's anchor point for transform matrix.
1134          *
1135          * @since               2.0
1136          *
1137          * @param[in]   anchorZ                         The Z component of anchor point
1138          * @see                 GetAnchorZ()
1139          */
1140         void SetAnchorZ(float anchorZ);
1141
1142         /**
1143          * Gets the custom data of this instance.
1144          *
1145          * @since               2.0
1146          *
1147          * @return              The user data associated with this instance
1148          * @see                 SetUserData()
1149          */
1150         void* GetUserData(void) const;
1151
1152         /**
1153          * Sets the custom data of this instance.
1154          *
1155          * @since               2.0
1156          *
1157          * @param[in]   pUserData                       The user data associated with this instance
1158          * @see                 GetUserData()
1159          */
1160         void SetUserData(void* pUserData);
1161
1162         /**
1163          * Sets the contents of this instance with the specified VisualElementSurface. @n
1164          * The contents of the @c pSurface is not copied by the %SetSurface() method, but shared with this instance.
1165          *
1166          * @since               2.0
1167          *
1168          * @return              An error code
1169          * @param[in]   pSurface                        The pointer to VisualElementSurface @n
1170          *                                                                      If @c pSurface is @c null, surface will be created internally by system.
1171          * @exception   E_SUCCESS                       The method is successful.
1172          * @exception   E_INVALID_OPERATION     This instance does not allow VisualElementSurface for contents.
1173          * @remarks             If applications modify the contents of @c pSurface, the modifications will be applied to all
1174          *                              the %VisualElements which share same VisualElementSurface. But in this case, applications need to call
1175          *                              the SetFlushNeeded() method for those %VisualElements because the modifications of the @c pSurface will not be applied on the screen automatically.
1176          * @see                 GetSurfaceN()
1177          */
1178         result SetSurface(VisualElementSurface* pSurface);
1179
1180         /**
1181          * Gets the VisualElementSurface this instance uses for its contents.
1182          *
1183          * @since               2.0
1184          *
1185          * @return              A pointer to VisualElementSurface
1186          * @exception   E_SUCCESS                       The method is successful.
1187          * @exception   E_SYSTEM                        A system error has occurred.
1188          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1189          * @remarks             If an exception occurs, this method returns @c null.
1190          * @see                 SetSurface()
1191          */
1192         VisualElementSurface* GetSurfaceN(void) const;
1193
1194         /**
1195          * Sets the render operation of this instance.
1196          *
1197          * @since               2.0
1198          *
1199          * @return              An error code
1200          * @param[in]   renderOperation         The new rendering operation
1201          * @exception   E_SUCCESS                       The method is successful.
1202          * @exception   E_INVALID_ARG           The specified @c renderOperation is out of range.
1203          * @see                 GetRenderOperation()
1204          */
1205         result SetRenderOperation(RenderOperation renderOperation);
1206
1207         /**
1208          * Gets the render operation of this instance.
1209          *
1210          * @since               2.0
1211          *
1212          * @return              The render operation of this instance
1213          * @see                 SetRenderOperation()
1214          */
1215         RenderOperation GetRenderOperation(void) const;
1216
1217         /**
1218          * Checks whether all the descendants are clipped to the bounds of this instance.
1219          *
1220          * @since               2.0
1221          *
1222          * @return              @c true if this instance clips all the descendants, @n
1223          *              else @c false
1224          * @see                 SetClipChildrenEnabled()
1225          */
1226         bool IsClipChildrenEnabled(void) const;
1227
1228         /**
1229          * Enables or disables clipping of all the descendants.
1230          *
1231          * @since               2.0
1232          *
1233          * @param[in]   clipChildren            Set to @c true if all the descendants are needed to clip to the bounds of this instance, @n
1234          *                                      else @c false
1235          * @see                 IsClipChildrenEnabled()
1236          */
1237         void SetClipChildrenEnabled(bool clipChildren);
1238
1239         /**
1240          * Converts the specified @c point in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1241          * The coordinate is converted by projecting it on the root coordinate space.
1242          *
1243          * @since                       2.0
1244          *
1245          * @return                      An error code
1246          * @param[in,out]       point                           The point to convert
1247          * @param[in]           pFromVisualElement      The %VisualElement instance with @c point in its coordinate space
1248          * @exception           E_SUCCESS                       The method is successful.
1249          * @exception           E_INVALID_ARG           The input parameter is incorrect.
1250          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
1251          *                                                                                      The matrix for this conversion is singular that has a zero determinant.
1252          * @remarks                     This instance and @c pFromVisualElement must share a common ancestor. @n
1253          *                                      If @c null, it is regarded that @c point is in the root coordinate space.
1254          * @see                         ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement)
1255          */
1256         result ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement) const;
1257
1258         /**
1259          * Converts the specified @c rectangle in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1260          * The coordinate is converted by projecting it on the root coordinate space.
1261          *
1262          * @since                       2.0
1263          *
1264          * @return                      An error code
1265          * @param[in,out]       rectangle                       The rectangle to convert
1266          * @param[in]           pFromVisualElement      The %VisualElement instance with @c rectangle in its coordinate space
1267          * @exception           E_SUCCESS                       The method is successful.
1268          * @exception           E_INVALID_ARG           The input parameter is incorrect.
1269          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
1270          *                                                                                      The matrix for this conversion is singular that has a zero determinant.
1271          * @remarks                     This instance and @c pFromVisualElement must share a common ancestor. @n
1272          *                                      If @c null, it is regarded that @c rectangle is in the root coordinate space.
1273          * @see                         ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement)
1274          */
1275         result ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement) const;
1276
1277         /**
1278          * Transforms a point in @c pOriginVisualElement coordinate space into a specified vector in calling instance's coordinate space.
1279          *
1280          * @since                       2.1
1281          *
1282          * @return                      The transformed vector
1283          * @param[in]           originPoint                     The point in @c pOriginVisualElement coordinate space
1284          * @param[in]           pOriginVisualElement    The %VisualElement instance with @c originPoint in its coordinate space
1285          * @exception           E_SUCCESS                       The method is successful.
1286          * @exception           E_INVALID_ARG           The input parameter is incorrect.
1287          * @exception           E_INVALID_OPERATION                     The current state of the instance prohibits the execution of the specified operation. @n
1288                                                                                                 The matrix for this conversion is singular which has zero determinant.
1289          * @remarks                     - This instance and @c pOriginVisualElement must share a common ancestor.
1290          *                              - The specific error code can be accessed using the GetLastResult() method.
1291          */
1292         Tizen::Graphics::FloatPoint3 TransformVectorFromOrigin(const Tizen::Graphics::FloatPoint3& originPoint, const VisualElement* pOriginVisualElement) const;
1293
1294         /**
1295          * Sets the sub-rectangle of contents which this instance must display.
1296          *
1297          * @since               2.0
1298          *
1299          * @return              An error code
1300          * @param[in]   contentBounds                   The sub-rectangle of contents to display in uniform coordinate space
1301          * @exception   E_SUCCESS                               The method is successful.
1302          * @exception   E_INVALID_ARG                   The width and height of @c contentBounds must be greater than @c 0.0.
1303          * @remarks             Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1304          * @remarks             If each component of @c contentBounds is not within the range [0.0, 1.0], the integer portion of the coordinates are
1305          *                              ignored and only fractional part is used which creates a repeating contents.
1306          * @see                 GetContentBounds()
1307          */
1308         result SetContentBounds(const Tizen::Graphics::FloatRectangle& contentBounds);
1309
1310         /**
1311          * Gets the sub-rectangle of contents which this instance must display.
1312          *
1313          * @since               2.0
1314          *
1315          * @return              The sub-rectangle of contents to be displayed in uniform coordinate space
1316          * @remarks             Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1317          * @see                 SetContentBounds()
1318          */
1319         Tizen::Graphics::FloatRectangle GetContentBounds(void) const;
1320
1321         /**
1322          * Acquires the %VisualElement instance for display.
1323          *
1324          * @since               2.0
1325          *
1326          * @return              The %VisualElement instance for display(readonly)
1327          * @remarks             If this instance is a presentation object, this method returns itself.
1328          * @see                ReleasePresentationInstance()
1329          */
1330         const VisualElement* AcquirePresentationInstance(void);
1331
1332         /**
1333          * Releases the %VisualElement instance for display.
1334          *
1335          * @since               2.0
1336          *
1337          * @remarks             This method should be called only after AcquirePresentationInstance() call.
1338          * @see                AcquirePresentationInstance()
1339          */
1340         void ReleasePresentationInstance(void);
1341
1342         /**
1343          * Acquires the %VisualElement instance for model.
1344          *
1345          * @since               2.0
1346          *
1347          * @return              The %VisualElement instance for model(readonly)
1348          * @remarks             If this instance is a model object, this method returns itself.
1349          * @see                ReleaseModelInstance()
1350          */
1351
1352         const VisualElement* AcquireModelInstance(void);
1353
1354         /**
1355          * Releases the %VisualElement instance for model.
1356          *
1357          * @since               2.0
1358          *
1359          * @remarks             This method should be called only after AcquireModelInstance() call.
1360          */
1361         void ReleaseModelInstance(void);
1362
1363         /**
1364          * Flushes %VisualElements on screen.
1365          *
1366          * @since               2.0
1367          *
1368          * @return              An error code
1369          * @exception   E_SUCCESS                       The method is successful.
1370          * @exception   E_SYSTEM                        A system error has occurred.
1371          * @remarks             Because this method may degrade the performance of system, applications must use this method only when really needed.
1372          * @see                 SetFlushNeeded()
1373          */
1374         static result Flush(void);
1375
1376
1377 protected:
1378         /**
1379          * This is copy constructor for the %VisualElement class.
1380          *
1381          * @since               2.0
1382          *
1383          * @param[in]   rhs                     An instance of %VisualElement
1384          * @see         CloneN()
1385          */
1386         VisualElement(const VisualElement& rhs);
1387
1388         /**
1389          * This is the destructor for this class.
1390          *
1391          * @since               2.0
1392          *
1393          * @remarks             The delete operator cannot be used to deallocate the %VisualElement instance.
1394          * @see         Destroy()
1395          */
1396         virtual ~VisualElement(void);
1397
1398         /**
1399          * Creates and returns a polymorphic copy of this %VisualElement instance for the presentation. @n
1400          * All descendants of %VisualElement must implement the %CloneN() method and the copy constructor appropriately. @n
1401          * When the %VisualElement instance is created, the framework make a %VisualElement for the presentation with this method.
1402          *
1403          * @since               2.0
1404          *
1405          * @return              The clone of this instance
1406          */
1407         virtual VisualElement* CloneN(void) const;
1408
1409
1410         //
1411         // This method is for internal use only. Using this method can cause behavioral, security-related,
1412         // and consistency-related issues in the application.
1413         //
1414         //
1415         // This method is reserved and may change its name at any time without prior notice.
1416         //
1417         // @since               2.0
1418         //
1419         virtual void VisualElement_Reserved1(void) {}
1420
1421
1422         //
1423         // This method is for internal use only. Using this method can cause behavioral, security-related,
1424         // and consistency-related issues in the application.
1425         //
1426         //
1427         // This method is reserved and may change its name at any time without prior notice.
1428         //
1429         // @since               2.0
1430         //
1431         virtual void VisualElement_Reserved2(void) {}
1432
1433
1434         //
1435         // This method is for internal use only. Using this method can cause behavioral, security-related,
1436         // and consistency-related issues in the application.
1437         //
1438         //
1439         // This method is reserved and may change its name at any time without prior notice.
1440         //
1441         // @since               2.0
1442         //
1443         virtual void VisualElement_Reserved3(void) {}
1444
1445
1446         //
1447         // This method is for internal use only. Using this method can cause behavioral, security-related,
1448         // and consistency-related issues in the application.
1449         //
1450         //
1451         // This method is reserved and may change its name at any time without prior notice.
1452         //
1453         // @since               2.0
1454         //
1455         virtual void VisualElement_Reserved4(void) {}
1456
1457
1458         //
1459         // This method is for internal use only. Using this method can cause behavioral, security-related,
1460         // and consistency-related issues in the application.
1461         //
1462         //
1463         // This method is reserved and may change its name at any time without prior notice.
1464         //
1465         // @since               2.0
1466         //
1467         virtual void VisualElement_Reserved5(void) {}
1468
1469
1470 private:
1471
1472         //
1473         // The implementation of this assignment constructor is intentionally blank to prohibit assignment of objects.
1474         //
1475         // @since               2.0
1476         //
1477         VisualElement& operator =(const VisualElement& rhs);
1478
1479
1480 protected:
1481         _VisualElementImpl* _pVisualElementImpl;
1482
1483         friend class _VisualElementImpl;
1484 };              // VisualElement
1485
1486
1487 }}}             // Tizen::Ui::Animations
1488
1489 #endif //_FUIANIMVISUALELEMENT_H_