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          * @brief       <i> [Deprecated] </i>
 387          * @deprecated  This method is deprecated.
 388          * @since               2.0
 389          *
 390          * @return              @c true if this instance is a child or descendant of the specified one, @n
 391          *                              else @c false
 392          * @param[in]   other                           An instance of %VisualElement to test relationship
 393          */
 394         bool IsChildOf(const VisualElement& other) const;
 395
 396         /**
 397          * Checks whether an instance is a child or descendant of a specified one.
 398          *
 399          * @since               2.1
 400          *
 401          * @return              @c true if this instance is a child or descendant of a specified one, @n
 402          *                              else @c false
 403          * @param[in]           pOther                          A pointer to %VisualElement instance to check its relationship
 404          * @exception           E_SUCCESS The method is successful.
 405         * @exception            E_INVALID_ARG  The specified @c pOther is @c null.
 406         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 407          */
 408         bool IsChildOf(const VisualElement* pOther) const;
 409
 410         /**
 411          * Attaches a child to this instance. @n
 412          * The %AttachChild() method attaches the specified @c child at the highest position in the Z order group of the @c child.
 413          * If you need to change Z-Order group, you can change it using the SetZOrderGroup() method.
 414          *
 415          * @brief       <i> [Deprecated] </i>
 416          * @deprecated  This method is deprecated.
 417          * @since               2.0
 418          *
 419          * @return              An error code
 420          * @param[in]   child                           The %VisualElement instance to attach to this instance
 421          * @exception   E_SUCCESS                       The method is successful.
 422          * @exception   E_INVALID_ARG           The input parameter is incorrect. Either of the following conditions has occurred: @n
 423          *                                                                      - The specified @c child is not instantiated successfully. @n
 424          *                                                                      - The specified @c child is this instance. @n
 425          *                                                                      - The specified @c child is already an ancestor of this instance.
 426          * @see         SetZOrderGroup()
 427          * @see         InsertChild()
 428          * @see         DetachChild()
 429          * @see         ChangeZOrder()
 430          */
 431         result AttachChild(const VisualElement& child);
 432
 433         /**
 434          * Attaches a child to an instance. @n
 435          * The %AttachChild() method attaches the specified @c pChild at the highest position in the Z order group of the @c pChild.
 436          * Z-Order group can be changed using the SetZOrderGroup() method.
 437          *
 438          * @since               2.1
 439          *
 440          * @return              An error code
 441          * @param[in]   pChild                          A pointer to %VisualElement instance to attach to this instance
 442          * @exception           E_SUCCESS                       The method is successful.
 443          * @exception           E_INVALID_ARG           The input parameter is incorrect. Either of the following conditions has occurred: @n
 444          *                                                                      - The specified @c pChild is not instantiated successfully. @n
 445          *                                                                      - The specified @c pChild is this instance. @n
 446          *                                                                      - The specified @c pChild is already an ancestor of this instance.@n
 447          *                                                                      - The specified @c pChild is @c null.
 448          * @see         SetZOrderGroup()
 449          * @see         InsertChild()
 450          * @see         DetachChild()
 451          * @see         ChangeZOrder()
 452          */
 453         result AttachChild(VisualElement* pChild);
 454
 455         /**
 456          * Inserts a child to this instance. @n
 457          * If @c pReference is not @c null, the Z order group of @c child will be changed into that of @c pReference and @c child will be
 458          * placed right above or below the @c pReference instance according to the @c above parameter.
 459          *
 460          * @brief       <i> [Deprecated] </i>
 461          * @deprecated  This method is deprecated.
 462          * @since               2.0
 463          *
 464          * @return              An error code
 465          * @param[in]   child                           The %VisualElement instance to attach to this instance
 466          * @param[in]   pReference                      A pointer to the %VisualElement instance that is referenced
 467          * @param[in]   above                           Specifies the position of @c child relative to the @c pReference
 468          * @exception   E_SUCCESS                       The method is successful.
 469          * @exception   E_INVALID_ARG           The input parameter is incorrect. Either of the following conditions has occurred: @n
 470          *                                                                      - The specified @c child is not instantiated successfully. @n
 471          *                                                                      - The specified @c child is this instance. @n
 472          *                                                                      - The specified @c child and @c pReference are same. @n
 473          *                                                                      - The specified @c child is already an ancestor of this instance. @n
 474          *                                                                      - The parent of @c pReference is not this instance if @c pReference is not @c null. @n
 475          * @remarks             If @c above is @c true, the @c child will be attached above @c pReference in Z order,
 476          *                              else it will be attached below the @c pReference %VisualElement. @n
 477          *                              If @c pReference is @c null, the @c child will be attached at the highest position in the @c child's Z order group,
 478          *                              else the child will be attached at the lowest position in the @c child's Z order group.
 479          * @see         SetZOrderGroup()
 480          * @see         AttachChild()
 481          * @see         DetachChild()
 482          * @see         ChangeZOrder()
 483          */
 484         result InsertChild(const VisualElement& child, const VisualElement* pReference, bool above);
 485
 486         /**
 487          * Inserts a child to an instance. @n
 488          * If @c pReference is not @c null, the Z order group of @c pChild will be changed into that of @c pReference and @c child will be
 489          * placed right above or below the @c pReference instance according to the @c above parameter.
 490          *
 491          * @since               2.1
 492          *
 493          * @return              An error code
 494          * @param[in]   pChild                          A pointer to %VisualElement instance to insert
 495          * @param[in]   pReference                      A pointer to the %VisualElement instance to refer
 496          * @param[in]   above                           The position of @c pChild relative to @c pReference
 497          * @exception   E_SUCCESS                       The method is successful.
 498          * @exception   E_INVALID_ARG           The input parameter is incorrect. Either of the following conditions has occurred: @n
 499          *                                                                      - The specified @c pChild is not instantiated successfully. @n
 500          *                                                                      - The specified @c pChild is this instance. @n
 501          *                                                                      - The specified @c pChild and @c pReference are same. @n
 502          *                                                                      - The specified @c pChild is already an ancestor of this instance. @n
 503          *                                                                      - The parent of @c pReference is not this instance if @c pReference is not @c null. @n
 504          *                                                                      - The specified @c pChild is @c null.
 505          * @remarks             If @c above is @c true, the @c pChild is attached above @c pReference in Z order,
 506          *                              else it is attached below the @c pReference %VisualElement. @n
 507          *                              If @c pReference is @c null, the @c pChild is attached at the highest position in the @c pChild's Z order group,
 508          *                              else the child is attached at the lowest position in the @c pChild's Z order group.
 509          * @see         SetZOrderGroup()
 510          * @see         AttachChild()
 511          * @see         DetachChild()
 512          * @see         ChangeZOrder()
 513          */
 514         result InsertChild(VisualElement* pChild, const VisualElement* pReference, bool above);
 515
 516         /**
 517          * Detaches a child from this instance.
 518          *
 519          * @brief       <i> [Deprecated] </i>
 520          * @deprecated  This method is deprecated.
 521          * @since               2.0
 522          *
 523          * @return              An error code
 524          * @param[in]   child                           The %VisualElement instance to detach from this instance
 525          * @exception   E_SUCCESS                       The method is successful.
 526          * @exception   E_OBJ_NOT_FOUND         The specified @c child is not a child of this instance.
 527          * @remarks             This method detaches @c child from this instance. If you need to deallocate %VisualElement, call Destroy() method, not C++ delete.
 528          * @see         InsertChild()
 529          * @see         AttachChild()
 530          */
 531         result DetachChild(const VisualElement& child);
 532
 533         /**
 534          * Detaches a child from an instance.
 535          *
 536          * @since               2.1
 537          *
 538          * @return              An error code
 539          * @param[in]   pChild                          A pointer to %VisualElement instance to detach
 540          * @exception           E_SUCCESS                       The method is successful.
 541          * @exception           E_OBJ_NOT_FOUND The specified @c pChild is not a child of this instance.
 542          * @exception           E_INVALID_ARG           The specified @c pChild is @c null.
 543          * @remarks             This method detaches @c pChild from this instance. To deallocate %VisualElement, call Destroy() method, and not C++ delete.
 544          * @see                InsertChild()
 545          * @see         AttachChild()
 546          */
 547         result DetachChild(VisualElement* pChild);
 548
 549         /**
 550          * Changes Z order of this instance.
 551          *
 552          * @since               2.0
 553          *
 554          * @return              An error code
 555          * @param[in]   pReference                      A pointer to the %VisualElement instance that is referenced
 556          * @param[in]   above                           Specifies the position of this instance relative to the @c pReference
 557          * @exception   E_SUCCESS                       The method is successful.
 558          * @exception   E_INVALID_ARG           The input parameter is incorrect. Either of the following conditions has occurred: @n
 559          *                                                                      - This instance does not have a parent (not attached). @n
 560          *                                                                      - This instance and @c pReference do not have same parent if @c pReference is not @c null. @n
 561          *                                                                      - The specified @c pReference is this instance. @n
 562          * @remarks             If @c above is @c true, this instance will be attached above @c pReference in Z order,
 563          *                              else it will be attached below the @c pReference %VisualElement. @n
 564          *                              If @c pReference is @c null, this instance will be attached at the highest position in the Z order group of this instance,
 565          *                              else the child will be attached at the lowest position in the Z order group of this instance.
 566          * @see         InsertChild()
 567          * @see         AttachChild()
 568          * @see         DetachChild()
 569          */
 570         result ChangeZOrder(const VisualElement* pReference, bool above);
 571
 572         /**
 573          * Gets the child of the specified @c name. @n
 574          * If there are multiple matches of the name, it returns the first match.
 575          *
 576          * @since               2.0
 577          *
 578          * @return              The %VisualElement instance having the specified @c name @n
 579          *                              else @c null if there is not %VisualElement with the specified @c name
 580          * @param[in]   name                            The name of the %VisualElement
 581          * @param[in]   searchDescendants       @c true to find a match among all the descendants of this instance, @n
 582          *                                                                      else @c false
 583          * @exception   E_SUCCESS                       The method is successful.
 584          * @exception   E_OBJ_NOT_FOUND  There is no %VisualElement with the specified @c name.
 585          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 586          * @remarks             If an exception occurs, this method returns @c null.
 587          * @see         GetName()
 588          * @see         SetName()
 589          */
 590         VisualElement* GetChild(const Tizen::Base::String& name, bool searchDescendants) const;
 591
 592         /**
 593          * Gets the farthest (highest Z order) %VisualElement descendant including this instance that contains a specified @c point. @n
 594          * The OnHitTest() method or [HitTest](@ref Tizen::Ui::Animations::IVisualElementContentProvider::HitTest) callback may be called
 595          * for descendants of this instance including itself.
 596          *
 597          * @since               2.0
 598          *
 599          * @return              The %VisualElement that contains @c point, @n
 600          *                              else @c null if @c point is completely outside of this instance
 601          * @param[in]   point                           The position in coordinate space of this instance
 602          * @exception   E_SUCCESS                       The method is successful.
 603          * @exception   E_OBJ_NOT_FOUND         There is no %VisualElement containing the specified @c point.
 604          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 605          * @remarks             If an exception occurs, this method returns @c null.
 606          * @remarks             This method assumes that all ancestors of this instance do not clip children.
 607          * @see         IVisualElementContentProvider::HitTest()
 608          * @see         OnHitTest()
 609          * @see         IsClipChildrenEnabled()
 610          * @see         SetClipChildrenEnabled()
 611          */
 612         VisualElement* GetChildAt(const Tizen::Graphics::FloatPoint& point) const;
 613
 614         /**
 615          * Adds an animation without key name.
 616          *
 617          * @since               2.0
 618          *
 619          * @return              An error code
 620          * @param[in]   animation                       The animation instance
 621          * @exception   E_SUCCESS                       The method is successful.
 622          * @exception   E_INVALID_ARG           The input parameter is incorrect.
 623          * @exception   E_INVALID_OPERATION     This instance is not a model object. @n
 624          *                                                                      An animation can be added to the model instance only.
 625          * @see                 RemoveAnimation()
 626          * @see                 GetAnimationN()
 627          */
 628         result AddAnimation(const VisualElementAnimation& animation);
 629
 630         /**
 631          * Adds an animation with key name.
 632          *
 633          * @since               2.0
 634          *
 635          * @return              An error code
 636          * @param[in]   keyName                         The name of the animation that is used to identify animations @n
 637          *                                                                      Empty @c keyName is allowed.
 638          * @param[in]   animation                       The animation instance
 639          * @exception   E_SUCCESS                       The method is successful.
 640          * @exception   E_INVALID_ARG           The input parameter is incorrect.
 641          * @exception   E_OBJ_ALREADY_EXIST     An animation with @c keyName already exists.
 642          * @exception   E_INVALID_OPERATION     This instance is not a model object. @n
 643          *                                                                      An animation can be added to the model instance only.
 644          * @see                 RemoveAnimation()
 645          * @see                 GetAnimationN()
 646          */
 647         result AddAnimation(const Tizen::Base::String& keyName, const VisualElementAnimation& animation);
 648
 649         /**
 650          * Removes the animation with the specified @c keyName.
 651          *
 652          * @since               2.0
 653          *
 654          * @return              An error code
 655          * @param[in]   keyName                         The name of the animation to remove
 656          * @exception   E_SUCCESS                       The method is successful.
 657          * @exception   E_OBJ_NOT_FOUND         An animation with @c keyName does not exist.
 658          * @see                 AddAnimation()
 659          * @see                 GetAnimationN()
 660          */
 661         result RemoveAnimation(const Tizen::Base::String& keyName);
 662
 663         /**
 664          * Gets the animation playing for the specified property.
 665          *
 666          * @since               2.0
 667          *
 668          * @return              A pointer to the animation
 669          * @param[in]   keyName                         The name of the animation
 670          * @exception   E_SUCCESS                       The method is successful.
 671          * @exception   E_OBJ_NOT_FOUND         An animation with @c keyName does not exist.
 672          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 673          * @remarks             If an exception occurs, this method returns @c null.
 674          * @see                 AddAnimation()
 675          * @see                 RemoveAnimation()
 676          */
 677         VisualElementAnimation* GetAnimationN(const Tizen::Base::String& keyName) const;
 678
 679         /**
 680          * Removes all animations.
 681          *
 682          * @since               2.0
 683          *
 684          * @see                 AddAnimation()
 685          * @see                 RemoveAnimation()
 686          */
 687         void RemoveAllAnimations(void);
 688
 689         /**
 690          * Adds a rectangle to update region of this instance. @n
 691          * The update region represents the portion of the %VisualElement's area that must be redrawn by the OnDraw() method.
 692          *
 693          * @since               2.0
 694          *
 695          * @return              An error code
 696          * @param[in]   pRectangle                      The pointer to the rectangular region that contains the coordinates of the rectangle to add to the update region @n
 697          *                                              If @c pRectangle is @c null, entire area is added to the update region.
 698          * @exception   E_SUCCESS                       The method is successful.
 699          * @exception   E_INVALID_OPERATION     The contents of this instance is set by the SetSurface() method.
 700          * @see                 SetSurface()
 701          */
 702         result InvalidateRectangle(const Tizen::Graphics::FloatRectangle* pRectangle);
 703
 704         /**
 705          * Gets the smallest rectangle that completely encloses the update region of this instance. @n
 706          * Applications can use the update region in the OnDraw() method to minimize the redrawing area to improve performance.
 707          * The %GetUpdateRectangle() method returns an empty rectangle if it is not called inside OnDraw() method.
 708          *
 709          * @since               2.0
 710          *
 711          * @return              The rectangle to update
 712          * @see                 InvalidateRectangle()
 713          */
 714         Tizen::Graphics::FloatRectangle GetUpdateRectangle(void) const;
 715
 716         /**
 717          * Updates the content area of all the descendants including this instance.
 718          * The %Draw() method will call OnDraw() or DrawContent() method only if there are regions invalidated by InvalidateRectangle().
 719          * The platform will call this method later automatically if applications do not call explicitly.
 720          *
 721          * @since               2.0
 722          *
 723          * @return              An error code
 724          * @exception   E_SUCCESS                       The method is successful.
 725          * @exception   E_INVALID_STATE         This instance is not attached to the maintained tree for displaying. @n
 726          *                                              For displaying, this instance should be descendant of the root %VisualElement.
 727          * @exception   E_SYSTEM                        A system error has occurred.
 728          * @see IVisualElementContentProvider
 729          */
 730         result Draw(void);
 731
 732         /**
 733          * Marks the entire area of this instance to be flushed.
 734          *
 735          * @since               2.0
 736          *
 737          * @return              An error code
 738          * @exception   E_SUCCESS                       The method is successful.
 739          *
 740          * @see         Flush()
 741          */
 742         result SetFlushNeeded(void);
 743
 744         /**
 745          * Creates and returns a graphics canvas whose bounds, position, and size are equal to those of this instance.
 746          *
 747          * @since               2.0
 748          *
 749          * @return              The graphic canvas of the %VisualElement, @n
 750          *                              else @c null if an exception occurs
 751          * @exception   E_SUCCESS                       The method is successful.
 752          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 753          * @exception   E_INVALID_OPERATION     The contents of this instance is set by the SetSurface() method. @n
 754                                                                                 The canvas can be created for the model instance only.
 755          * @remarks             This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the %VisualElement.
 756          *                              It is the developer's responsibility to deallocate the canvas after use.
 757          *                              The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
 758          *                              Therefore, one must delete previously allocated canvas and create a new canvas using this method,
 759          *                              if the size or position of the %VisualElement is changed. @n
 760          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 761          * @remarks             If an exception occurs, this method returns @c null.
 762          * @see                 GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
 763          * @see                 GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
 764          */
 765         Tizen::Graphics::Canvas* GetCanvasN(void) const;
 766
 767         /**
 768          * Creates and returns a graphic canvas of the specified area.
 769          *
 770          * @since               2.0
 771          *
 772          * @return              The graphic canvas of the %VisualElement, @n
 773          *                              else @c null if an exception occurs
 774          * @param[in]   bounds                          The position relative to the top-left corner of the %VisualElement and size
 775          * @exception   E_SUCCESS                       The method is successful.
 776          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 777          * @exception   E_INVALID_OPERATION     The contents of this instance is set by the SetSurface() method. @n
 778                                                                                 The canvas can be created for the model instance only.
 779          * @exception   E_OUT_OF_RANGE          The specified @c bounds do not intersect with the bounds of the %VisualElement. @n
 780          *                                                                      The width and height must be greater than or equal to @c 0.
 781          * @remarks             Only the graphic canvas of displayable %VisualElement can be obtained.
 782          *                              If the specified area is not inside the %VisualElement,
 783          *                              the graphics canvas of overlapped area between the %VisualElement and the specified @c bound is returned. @n
 784          *                              This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the %VisualElement.
 785          *                              It is the developer's responsibility to deallocate the canvas after use.
 786          *                              The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
 787          *                              Therefore, one must delete previously allocated canvas and create a new canvas using this method,
 788          *                              if the size or position of the control is changed. @n
 789          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 790          * @remarks             If an exception occurs, this method returns @c null.
 791          * @see                 GetCanvasN()
 792          * @see                 GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds)
 793          */
 794         Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const;
 795
 796         /**
 797          * Creates and returns a graphic canvas of the specified area.
 798          *
 799          * @since               2.1
 800          *
 801          * @return              The graphic canvas of %VisualElement, @n
 802          *                              else @c null if an exception occurs
 803          * @param[in]   bounds                          The position relative to the top-left corner of %VisualElement and size
 804          * @exception   E_SUCCESS                       The method is successful.
 805          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 806          * @exception   E_INVALID_OPERATION     The contents of this instance is set by the SetSurface() method. @n
 807                                                                                 The canvas can be created for the model instance only.
 808          * @exception   E_OUT_OF_RANGE          The specified @c bounds do not intersect with the bounds of %VisualElement. @n
 809          *                                                                      The width and height must be greater than or equal to @c 0.
 810          * @remarks             Only the graphic canvas of displayable %VisualElement can be obtained.
 811          *                              If the specified area is not inside %VisualElement,
 812          *                              the graphics canvas of overlapped area between %VisualElement and the specified @c bound is returned. @n
 813          *                              This method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of %VisualElement.
 814          *                              It is the developer's responsibility to deallocate the canvas after use.
 815          *                              The canvas is guaranteed to be valid only if the properties of the parent %VisualElement of the canvas remain unchanged.
 816          *                              Therefore, one must delete previously allocated canvas and create a new canvas using this method,
 817          *                              if the size or position of the control is changed.
 818          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 819          * @remarks             If an exception occurs, this method returns @c null.
 820          * @see                 GetCanvasN()
 821          * @see                 GetCanvasN(const Tizen::Graphics::Rectangle& bounds)
 822          */
 823         Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const;
 824
 825         /**
 826          * Gets the name of this instance.
 827          *
 828          * @since               2.0
 829          *
 830          * @return              The name of this instance
 831          */
 832         Tizen::Base::String GetName(void) const;
 833
 834         /**
 835          * Sets the name of this instance.
 836          *
 837          * @since               2.0
 838          *
 839          * @param[in]   name                            The name of the %VisualElement instance @n
 840          *                                  Empty or duplicated name with other instances are also allowed.
 841          */
 842         void SetName(const Tizen::Base::String& name);
 843
 844         /**
 845          * Gets the value of the %VisualElement's property.
 846          *
 847          * @since               2.0
 848          *
 849          * @return              The value of the specified property
 850          * @param[in]   property                        The %VisualElement's property
 851          * @exception   E_SUCCESS                       The method is successful.
 852          * @exception   E_KEY_NOT_FOUND         The specified @c property is not found.
 853          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 854          * @remarks             If an exception occurs, this method returns @c Variant::NULL_VARIANT.
 855          * @remarks             Additional exceptions can occur according to the behavior of subclasses.
 856          * @see                 SetProperty()
 857          * @see                 OnGetPropertyRequested()
 858          */
 859         Variant GetProperty(const Tizen::Base::String& property) const;
 860
 861         /**
 862          * Sets the value of the %VisualElement's property.
 863          *
 864          * @since               2.0
 865          *
 866          * @return              An error code
 867          * @param[in]   property                        The %VisualElement's property
 868          * @param[in]   value                           The value of the %VisualElement's property to set
 869          * @exception   E_SUCCESS                       The method is successful.
 870          * @exception   E_KEY_NOT_FOUND         The specified @c property is not found.
 871          * @remarks             Additional exceptions can occur according to the behavior of subclasses.
 872          * @see                 GetProperty()
 873          * @see                 OnSetPropertyRequested()
 874          */
 875         result SetProperty(const Tizen::Base::String& property, const Variant& value);
 876
 877         /**
 878          * Sets the Z order group of this instance.
 879          *
 880          * @since               2.0
 881          *
 882          * @return              An error code
 883          * @param[in]   zOrderGroup                     The value of Z order which must be between @c Z_ORDER_GROUP_LOWEST and @c Z_ORDER_GROUP_HIGHEST @n
 884          *                                                                      The default value is @c Z_ORDER_GROUP_NORMAL.
 885          * @exception   E_SUCCESS                       The method is successful.
 886          * @exception   E_OUT_OF_RANGE          The @c zOrderGroup is not between @c Z_ORDER_GROUP_LOWEST and @c Z_ORDER_GROUP_HIGHEST.
 887          * @remarks             You can choose the @c zOrderGroup value as follows: @n
 888          *                              - Tizen::Ui::Animations::Z_ORDER_GROUP_LOWEST @n
 889          *                              - Tizen::Ui::Animations::Z_ORDER_GROUP_NORMAL @n
 890          *                              - Tizen::Ui::Animations::Z_ORDER_GROUP_HIGHEST @n
 891          *                              Or you can specify an integer value between @c ZORDER_GROUP_LOWEST and @c ZORDER_GROUP_HIGHEST.
 892          * @see GetZOrderGroup()
 893          */
 894         result SetZOrderGroup(int zOrderGroup);
 895
 896         /**
 897          * Gets the Z order group of this instance.
 898          *
 899          * @since               2.0
 900          *
 901          * @return              The Z order group of this instance
 902          * @see SetZOrderGroup()
 903          */
 904         int GetZOrderGroup(void) const;
 905
 906         /**
 907          * Checks whether the redraw-on-resize feature is enabled.
 908          *
 909          * @since               2.0
 910          *
 911          * @return              @c true if the redraw-on-resize feature is enabled, @n
 912          *                              else @c false
 913          * @remarks             The entire content area will be added to the update region when bounds are changed if redraw-on-resize is enabled. @n
 914          *                              Otherwise, current contents will be scaled for the new bounds of this instance without redrawing.
 915          * @see SetRedrawOnResizeEnabled()
 916          */
 917         bool IsRedrawOnResizeEnabled(void) const;
 918
 919         /**
 920          * Enables or disables the redraw-on-resize feature.
 921          *
 922          * @since               2.0
 923          *
 924          * @param[in]   enable                          Set to @c true if invalidation is needed whenever resized, @n
 925          *                                                                      else @c false
 926          * @see IsRedrawOnResizeEnabled()
 927          */
 928         void SetRedrawOnResizeEnabled(bool enable);
 929
 930         /**
 931          * Gets the position and the size of this instance.
 932          *
 933          * @since               2.0
 934          *
 935          * @return              An instance of the Tizen::Graphics::FloatRectangle that represents the position of top-left corner, @n
 936          *                              the width, and the height of this instance. @n It has relative coordinate space to the parent.
 937          * @see                 SetBounds()
 938          */
 939         Tizen::Graphics::FloatRectangle GetBounds(void) const;
 940
 941         /**
 942          * Sets the position and the size of this instance.
 943          *
 944          * @since               2.0
 945          *
 946          * @return              An error code
 947          * @param[in]   bounds                          The new bounds of this instance
 948          * @exception   E_SUCCESS                       The method is successful.
 949          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 950          * @remarks             When the size of @c bounds is changed, the entire content area will be added to the update region of this instance if redraw-on-resize feature is enabled.
 951          * @see                 GetBounds()
 952          * @see                 IsRedrawOnResizeEnabled()
 953          * @see                 SetRedrawOnResizeEnabled()
 954          */
 955         result SetBounds(const Tizen::Graphics::FloatRectangle& bounds);
 956
 957         /**
 958          * Gets the position on the Z-axis.
 959          *
 960          * @since               2.0
 961          *
 962          * @return              The position on the Z-axis
 963          * @see                 SetZPosition()
 964          */
 965         float GetZPosition(void) const;
 966
 967         /**
 968          * Sets the position on the Z-axis.
 969          *
 970          * @since               2.0
 971          *
 972          * @param[in]   zPosition                       The position on the Z-axis
 973          * @see                 GetZPosition()
 974          */
 975         void SetZPosition(float zPosition);
 976
 977         /**
 978          * Checks whether this instance is visible or not. @n
 979          * Even if the show state is @c true, this instance can be invisible when show state of one of the ancestors is @c false.
 980          *
 981          * @since               2.0
 982          *
 983          * @return              @c true if this instance is visible, @n
 984          *                              else @c false
 985          * @see                 GetShowState()
 986          * @see                 SetShowState()
 987          */
 988         bool IsVisible(void) const;
 989
 990         /**
 991          * Gets the show state of this instance.
 992          *
 993          * @since               2.0
 994          *
 995          * @return              The show state of the %VisualElement instance, @n
 996          *                              else @c false
 997          * @remarks             Even if the show state is @c true, the %VisualElement is invisible if it is not attached to a parent.
 998          * @see                 SetShowState()
 999          * @see                 IsVisible()
1000          */
1001         bool GetShowState(void) const;
1002
1003         /**
1004          * Sets the show state of this instance.
1005          *
1006          * @since               2.0
1007          *
1008          * @param[in]   show                            Set to @c true if this instance needs to show, @n
1009          *                                                                      else @c false
1010          * @see                 GetShowState()
1011          * @see                 IsVisible()
1012          */
1013         void SetShowState(bool show);
1014
1015         /**
1016          * Gets the opacity of this instance.
1017          *
1018          * @since               2.0
1019          *
1020          * @return              The opacity of this instance
1021          * @see                 SetOpacity()
1022          */
1023         float GetOpacity(void) const;
1024
1025         /**
1026          * Sets the opacity of this instance.
1027          *
1028          * @since               2.0
1029          *
1030          * @param[in]   opacity                         The new opacity which must be within the range [0.0, 1.0]
1031          * @remarks             The changing opacity affects all the descendants of this instance.
1032          * @see                 GetOpacity()
1033          */
1034         void SetOpacity(float opacity);
1035
1036         /**
1037          * Enables or disables the implicit animation. @n
1038          * If enabled, implicit animations may be created whenever animatable properties of this instance change.
1039          *
1040          * @since               2.0
1041          *
1042          * @param[in]   enable  Set to @c true to enable the implicit animation, @n
1043          *                                              else @c false
1044          * @remarks             The implicit animation is enabled by default.
1045          * @see                 IsImplicitAnimationEnabled()
1046          */
1047         void SetImplicitAnimationEnabled(bool enable);
1048
1049         /**
1050          * Checks whether the implicit animation is enabled.
1051          *
1052          * @since               2.0
1053          *
1054          * @return              @c true if the implicit animation is enabled, @n
1055          *                              else @c false
1056          * @see                 SetImplicitAnimationEnabled()
1057          */
1058         bool IsImplicitAnimationEnabled(void) const;
1059
1060         /**
1061          * Gets the transform matrix of this instance.
1062          *
1063          * @since               2.0
1064          *
1065          * @return              The transform matrix of this instance
1066          * @see                 SetTransformMatrix()
1067          */
1068         Tizen::Graphics::FloatMatrix4 GetTransformMatrix(void) const;
1069
1070         /**
1071          * Sets the transform matrix of this instance.
1072          *
1073          * @since               2.0
1074          *
1075          * @return              An error code
1076          * @param[in]   transform                       The transform matrix
1077          * @exception   E_SUCCESS                       The method is successful.
1078          * @exception   E_INVALID_ARG           The input parameter is incorrect.
1079          * @see                 GetTransformMatrix()
1080          */
1081         result SetTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1082
1083         /**
1084          * Gets the transform matrix applied to each child.
1085          *
1086          * @since               2.0
1087          *
1088          * @return              The transform matrix applied to each child
1089          * @remarks             The transform matrix for children is typically used for the projection matrix to layout children in 3D space.
1090          * @see                 SetChildrenTransformMatrix()
1091          */
1092         Tizen::Graphics::FloatMatrix4 GetChildrenTransformMatrix(void) const;
1093
1094         /**
1095          * Sets the transform matrix applied to each child.
1096          *
1097          * @since               2.0
1098          *
1099          * @return              An error code
1100          * @param[in]   transform                       The transform matrix
1101          * @exception   E_SUCCESS                       The method is successful.
1102          * @exception   E_INVALID_ARG           The input parameter is incorrect.
1103          * @see                 GetChildrenTransformMatrix()
1104          */
1105         result SetChildrenTransformMatrix(const Tizen::Graphics::FloatMatrix4& transform);
1106
1107
1108         /**
1109          * Gets the anchor point for this instance's transform matrix in uniform coordinate space
1110          * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1111          *
1112          * @since               2.0
1113          *
1114          * @return              The anchor point of this instance
1115          * @see                 SetAnchor()
1116          */
1117         Tizen::Graphics::FloatPoint GetAnchor(void) const;
1118
1119         /**
1120          * Sets the anchor point of this instance's transform matrix in uniform coordinate space
1121          * (0.0 and 1.0 mean left/top and right/bottom of the bounds, respectively).
1122          *
1123          * @since               2.0
1124          *
1125          * @param[in]   anchor                          The anchor point in uniform coordinate space
1126          * @see                 GetAnchor()
1127          */
1128         void SetAnchor(const Tizen::Graphics::FloatPoint& anchor);
1129
1130         /**
1131          * Gets the Z component of this instance's anchor point for transform matrix.
1132          *
1133          * @since               2.0
1134          *
1135          * @return              The Z component of the anchor point
1136          * @see                 SetAnchorZ()
1137          */
1138         float GetAnchorZ(void) const;
1139
1140         /**
1141          * Sets the Z component of this instance's anchor point for transform matrix.
1142          *
1143          * @since               2.0
1144          *
1145          * @param[in]   anchorZ                         The Z component of anchor point
1146          * @see                 GetAnchorZ()
1147          */
1148         void SetAnchorZ(float anchorZ);
1149
1150         /**
1151          * Gets the custom data of this instance.
1152          *
1153          * @since               2.0
1154          *
1155          * @return              The user data associated with this instance
1156          * @see                 SetUserData()
1157          */
1158         void* GetUserData(void) const;
1159
1160         /**
1161          * Sets the custom data of this instance.
1162          *
1163          * @since               2.0
1164          *
1165          * @param[in]   pUserData                       The user data associated with this instance
1166          * @see                 GetUserData()
1167          */
1168         void SetUserData(void* pUserData);
1169
1170         /**
1171          * Sets the contents of this instance with the specified VisualElementSurface. @n
1172          * The contents of the @c pSurface is not copied by the %SetSurface() method, but shared with this instance.
1173          *
1174          * @since               2.0
1175          *
1176          * @return              An error code
1177          * @param[in]   pSurface                        The pointer to VisualElementSurface @n
1178          *                                                                      If @c pSurface is @c null, surface will be created internally by system.
1179          * @exception   E_SUCCESS                       The method is successful.
1180          * @exception   E_INVALID_OPERATION     This instance does not allow VisualElementSurface for contents.
1181          * @remarks             If applications modify the contents of @c pSurface, the modifications will be applied to all
1182          *                              the %VisualElements which share same VisualElementSurface. But in this case, applications need to call
1183          *                              the SetFlushNeeded() method for those %VisualElements because the modifications of the @c pSurface will not be applied on the screen automatically.
1184          * @see                 GetSurfaceN()
1185          */
1186         result SetSurface(VisualElementSurface* pSurface);
1187
1188         /**
1189          * Gets the VisualElementSurface this instance uses for its contents.
1190          *
1191          * @since               2.0
1192          *
1193          * @return              A pointer to VisualElementSurface
1194          * @exception   E_SUCCESS                       The method is successful.
1195          * @exception   E_SYSTEM                        A system error has occurred.
1196          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1197          * @remarks             If an exception occurs, this method returns @c null.
1198          * @see                 SetSurface()
1199          */
1200         VisualElementSurface* GetSurfaceN(void) const;
1201
1202         /**
1203          * Sets the render operation of this instance.
1204          *
1205          * @since               2.0
1206          *
1207          * @return              An error code
1208          * @param[in]   renderOperation         The new rendering operation
1209          * @exception   E_SUCCESS                       The method is successful.
1210          * @exception   E_INVALID_ARG           The specified @c renderOperation is out of range.
1211          * @see                 GetRenderOperation()
1212          */
1213         result SetRenderOperation(RenderOperation renderOperation);
1214
1215         /**
1216          * Gets the render operation of this instance.
1217          *
1218          * @since               2.0
1219          *
1220          * @return              The render operation of this instance
1221          * @see                 SetRenderOperation()
1222          */
1223         RenderOperation GetRenderOperation(void) const;
1224
1225         /**
1226          * Checks whether all the descendants are clipped to the bounds of this instance.
1227          *
1228          * @since               2.0
1229          *
1230          * @return              @c true if this instance clips all the descendants, @n
1231          *              else @c false
1232          * @see                 SetClipChildrenEnabled()
1233          */
1234         bool IsClipChildrenEnabled(void) const;
1235
1236         /**
1237          * Enables or disables clipping of all the descendants.
1238          *
1239          * @since               2.0
1240          *
1241          * @param[in]   clipChildren            Set to @c true if all the descendants are needed to clip to the bounds of this instance, @n
1242          *                                      else @c false
1243          * @see                 IsClipChildrenEnabled()
1244          */
1245         void SetClipChildrenEnabled(bool clipChildren);
1246
1247         /**
1248          * Converts the specified @c point in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1249          * The coordinate is converted by projecting it on the root coordinate space.
1250          *
1251          * @since                       2.0
1252          *
1253          * @return                      An error code
1254          * @param[in,out]       point                           The point to convert
1255          * @param[in]           pFromVisualElement      The %VisualElement instance with @c point in its coordinate space
1256          * @exception           E_SUCCESS                       The method is successful.
1257          * @exception           E_INVALID_ARG           The input parameter is incorrect.
1258          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
1259          *                                                                                      The matrix for this conversion is singular that has a zero determinant.
1260          * @remarks                     This instance and @c pFromVisualElement must share a common ancestor. @n
1261          *                                      If @c null, it is regarded that @c point is in the root coordinate space.
1262          * @see                         ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement)
1263          */
1264         result ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement) const;
1265
1266         /**
1267          * Converts the specified @c rectangle in @c pFromVisualElement coordinate space to this instance's coordinate space. @n
1268          * The coordinate is converted by projecting it on the root coordinate space.
1269          *
1270          * @since                       2.0
1271          *
1272          * @return                      An error code
1273          * @param[in,out]       rectangle                       The rectangle to convert
1274          * @param[in]           pFromVisualElement      The %VisualElement instance with @c rectangle in its coordinate space
1275          * @exception           E_SUCCESS                       The method is successful.
1276          * @exception           E_INVALID_ARG           The input parameter is incorrect.
1277          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
1278          *                                                                                      The matrix for this conversion is singular that has a zero determinant.
1279          * @remarks                     This instance and @c pFromVisualElement must share a common ancestor. @n
1280          *                                      If @c null, it is regarded that @c rectangle is in the root coordinate space.
1281          * @see                         ConvertCoordinates(Tizen::Graphics::FloatPoint& point, const VisualElement* pFromVisualElement)
1282          */
1283         result ConvertCoordinates(Tizen::Graphics::FloatRectangle& rectangle, const VisualElement* pFromVisualElement) const;
1284
1285         /**
1286          * Transforms a point in @c pOriginVisualElement coordinate space into a specified vector in calling instance's coordinate space.
1287          *
1288          * @since                       2.1
1289          *
1290          * @return                      The transformed vector
1291          * @param[in]           originPoint                     The point in @c pOriginVisualElement coordinate space
1292          * @param[in]           pOriginVisualElement    The %VisualElement instance with @c originPoint in its coordinate space
1293          * @exception           E_SUCCESS                       The method is successful.
1294          * @exception           E_INVALID_ARG           The input parameter is incorrect.
1295          * @exception           E_INVALID_OPERATION                     The current state of the instance prohibits the execution of the specified operation. @n
1296                                                                                                 The matrix for this conversion is singular which has zero determinant.
1297          * @remarks
1298          *                              - This instance and @c pOriginVisualElement must share a common ancestor.
1299          *                              - The specific error code can be accessed using the GetLastResult() method.
1300          */
1301         Tizen::Graphics::FloatPoint3 TransformVectorFromOrigin(const Tizen::Graphics::FloatPoint3& originPoint, const VisualElement* pOriginVisualElement) const;
1302
1303         /**
1304          * Sets the sub-rectangle of contents which this instance must display.
1305          *
1306          * @since               2.0
1307          *
1308          * @return              An error code
1309          * @param[in]   contentBounds                   The sub-rectangle of contents to display in uniform coordinate space
1310          * @exception   E_SUCCESS                               The method is successful.
1311          * @exception   E_INVALID_ARG                   The width and height of @c contentBounds must be greater than @c 0.0.
1312          * @remarks             Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1313          * @remarks             If each component of @c contentBounds is not within the range [0.0, 1.0], the integer portion of the coordinates are
1314          *                              ignored and only fractional part is used which creates a repeating contents.
1315          * @see                 GetContentBounds()
1316          */
1317         result SetContentBounds(const Tizen::Graphics::FloatRectangle& contentBounds);
1318
1319         /**
1320          * Gets the sub-rectangle of contents which this instance must display.
1321          *
1322          * @since               2.0
1323          *
1324          * @return              The sub-rectangle of contents to be displayed in uniform coordinate space
1325          * @remarks             Default @c contentBounds is FloatRectangle(0.0, 0.0, 1.0, 1.0).
1326          * @see                 SetContentBounds()
1327          */
1328         Tizen::Graphics::FloatRectangle GetContentBounds(void) const;
1329
1330         /**
1331          * Acquires the %VisualElement instance for display.
1332          *
1333          * @since               2.0
1334          *
1335          * @return              The %VisualElement instance for display(readonly)
1336          * @remarks             If this instance is a presentation object, this method returns itself.
1337          * @see                ReleasePresentationInstance()
1338          */
1339         const VisualElement* AcquirePresentationInstance(void);
1340
1341         /**
1342          * Releases the %VisualElement instance for display.
1343          *
1344          * @since               2.0
1345          *
1346          * @remarks             This method should be called only after AcquirePresentationInstance() call.
1347          * @see                AcquirePresentationInstance()
1348          */
1349         void ReleasePresentationInstance(void);
1350
1351         /**
1352          * Acquires the %VisualElement instance for model.
1353          *
1354          * @since               2.0
1355          *
1356          * @return              The %VisualElement instance for model(readonly)
1357          * @remarks             If this instance is a model object, this method returns itself.
1358          * @see                ReleaseModelInstance()
1359          */
1360
1361         const VisualElement* AcquireModelInstance(void);
1362
1363         /**
1364          * Releases the %VisualElement instance for model.
1365          *
1366          * @since               2.0
1367          *
1368          * @remarks             This method should be called only after AcquireModelInstance() call.
1369          */
1370         void ReleaseModelInstance(void);
1371
1372         /**
1373          * Flushes %VisualElements on screen.
1374          *
1375          * @since               2.0
1376          *
1377          * @return              An error code
1378          * @exception   E_SUCCESS                       The method is successful.
1379          * @exception   E_SYSTEM                        A system error has occurred.
1380          * @remarks             Because this method may degrade the performance of system, applications must use this method only when really needed.
1381          * @see                 SetFlushNeeded()
1382          */
1383         static result Flush(void);
1384
1385
1386 protected:
1387         /**
1388          * This is copy constructor for the %VisualElement class.
1389          *
1390          * @since               2.0
1391          *
1392          * @param[in]   rhs                     An instance of %VisualElement
1393          * @see         CloneN()
1394          */
1395         VisualElement(const VisualElement& rhs);
1396
1397         /**
1398          * This is the destructor for this class.
1399          *
1400          * @since               2.0
1401          *
1402          * @remarks             The delete operator cannot be used to deallocate the %VisualElement instance.
1403          * @see         Destroy()
1404          */
1405         virtual ~VisualElement(void);
1406
1407         /**
1408          * Creates and returns a polymorphic copy of this %VisualElement instance for the presentation. @n
1409          * All descendants of %VisualElement must implement the %CloneN() method and the copy constructor appropriately. @n
1410          * When the %VisualElement instance is created, the framework make a %VisualElement for the presentation with this method.
1411          *
1412          * @since               2.0
1413          *
1414          * @return              The clone of this instance
1415          */
1416         virtual VisualElement* CloneN(void) const;
1417
1418
1419         //
1420         // This method is for internal use only. Using this method can cause behavioral, security-related,
1421         // and consistency-related issues in the application.
1422         //
1423         //
1424         // This method is reserved and may change its name at any time without prior notice.
1425         //
1426         // @since               2.0
1427         //
1428         virtual void VisualElement_Reserved1(void) {}
1429
1430
1431         //
1432         // This method is for internal use only. Using this method can cause behavioral, security-related,
1433         // and consistency-related issues in the application.
1434         //
1435         //
1436         // This method is reserved and may change its name at any time without prior notice.
1437         //
1438         // @since               2.0
1439         //
1440         virtual void VisualElement_Reserved2(void) {}
1441
1442
1443         //
1444         // This method is for internal use only. Using this method can cause behavioral, security-related,
1445         // and consistency-related issues in the application.
1446         //
1447         //
1448         // This method is reserved and may change its name at any time without prior notice.
1449         //
1450         // @since               2.0
1451         //
1452         virtual void VisualElement_Reserved3(void) {}
1453
1454
1455         //
1456         // This method is for internal use only. Using this method can cause behavioral, security-related,
1457         // and consistency-related issues in the application.
1458         //
1459         //
1460         // This method is reserved and may change its name at any time without prior notice.
1461         //
1462         // @since               2.0
1463         //
1464         virtual void VisualElement_Reserved4(void) {}
1465
1466
1467         //
1468         // This method is for internal use only. Using this method can cause behavioral, security-related,
1469         // and consistency-related issues in the application.
1470         //
1471         //
1472         // This method is reserved and may change its name at any time without prior notice.
1473         //
1474         // @since               2.0
1475         //
1476         virtual void VisualElement_Reserved5(void) {}
1477
1478
1479 private:
1480
1481         //
1482         // The implementation of this assignment constructor is intentionally blank to prohibit assignment of objects.
1483         //
1484         // @since               2.0
1485         //
1486         VisualElement& operator =(const VisualElement& rhs);
1487
1488
1489 protected:
1490         _VisualElementImpl* _pVisualElementImpl;
1491
1492         friend class _VisualElementImpl;
1493 };              // VisualElement
1494
1495
1496 }}}             // Tizen::Ui::Animations
1497
1498 #endif //_FUIANIMVISUALELEMENT_H_