inc/FUiControl.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiControl.h
  20  * @brief       This is the header file for the %Control class.
  21  *
  22  * This header file contains the declarations of the %Control class.
  23  */
  24
  25 #ifndef _FUI_CONTROL_H_
  26 #define _FUI_CONTROL_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FGrpCanvas.h>
  31 #include <FGrpColor.h>
  32 #include <FGrpPoint.h>
  33 #include <FGrpRectangle.h>
  34 #include <FUiIFocusEventListener.h>
  35 #include <FUiIKeyEventListener.h>
  36 #include <FUiITouchEventListener.h>
  37 #include <FUiITouchModeChangedEventListener.h>
  38 #include <FUiIDragDropEventListener.h>
  39 #include <FUiIDragDropEventListenerF.h>
  40 #include <FUiCompositeMode.h>
  41 #include <FUiIPropagatedKeyEventListener.h>
  42 #include <FUiIPropagatedTouchEventListener.h>
  43
  44 namespace Tizen { namespace Ui { namespace Animations {
  45 class ControlAnimator;
  46 class VisualElement;
  47 }}}
  48
  49 namespace Tizen { namespace Ui {
  50
  51 class AccessibilityContainer;
  52 class Container;
  53 class _ControlImpl;
  54 class TouchGestureDetector;
  55
  56 /**
  57  * @class       Control
  58  * @brief       This class is the abstract base class of all the UI control classes.
  59  *
  60  * @since       2.0
  61  *
  62  * @remarks     In order for a control to be displayed, it must first be bound to a window of the underlying window system. The control's window is
  63  * created when it (or its ancestor) is added to a valid control containment hierarchy. A containment hierarchy is valid if and
  64  * only if the root of the hierarchy is an instance of the Window class.
  65  *
  66  * The %Control class is the abstract base class of all user interface elements. It encapsulates a
  67  * "window" of the underlying window system, and provides the infrastructure necessary for the
  68  * elements to respond to user inputs. The %Control class also determines how a key event is dispatched
  69  * and processed.
  70  *
  71  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/controls.htm">UI Controls</a>.
  72  *
  73  *
  74  * The following examples demonstrate how to use the %Control class.
  75  *
  76  * Size and Position
  77  *
  78  * @code
  79  * // Sets the size
  80  * pControl->SetSize(100, 100); // 100 pixels wide and 100 pixels long
  81  *
  82  * // Sets the position
  83  * pControl->SetPosition(5, 5); // Control is drawn 5 pixels down and 5 pixels left from the top-left corner of its parent
  84  * @endcode
  85  *
  86  * Draw and Show
  87  *
  88  * @code
  89  * // Gets a instance of Canvas
  90  * Canvas* pCanvas = pControl->GetCanvasN();
  91  *
  92  * // Fills the canvas with white color
  93  * pCanvas->Clear(Tizen::Graphics::Color(255, 255, 255));
  94  *
  95  * // Shows changes on screen
  96  * pControl->Invalidate(true);
  97  *
  98  * delete pCanvas;
  99  * @endcode
 100  *
 101  * Key and input focus
 102  *
 103  * @code
 104  * // Implements MyKeyEventListener
 105  * IKeyEventListener* pKeyListener = new MyKeyEventListener();
 106  * pControl->SetFocus();
 107  *
 108  * // The added key listener should be deleted after use
 109  * pControl->AddKeyEventListener(*pKeyListener);
 110  * @endcode
 111  *
 112  */
 113 class _OSP_EXPORT_ Control
 114         : public Tizen::Base::Object
 115 {
 116
 117 public:
 118         /**
 119          * This destructor overrides Tizen::Base::Object::~Object().
 120          *
 121          * @since       2.0
 122          */
 123         virtual ~Control(void);
 124
 125         /**
 126          * Adds the IFocusEventListener instance to the %Control instance. @n
 127          * The added listener gets notified when the control gains or loses its focus.
 128          *
 129          * @since               2.0
 130          *
 131          * @param[in]   listener        The event listener to add
 132          * @see                 RemoveFocusEventListener()
 133          */
 134         void AddFocusEventListener(IFocusEventListener& listener);
 135
 136         /**
 137          * Adds the IKeyEventListener instance to the %Control instance. @n
 138          * The added listener gets notified when a key is pressed, released, or long pressed.
 139          *
 140          * @since               2.0
 141          *
 142          * @param[in]   listener    The event listener to add
 143          * @see                 RemoveKeyEventListener()
 144          */
 145         void AddKeyEventListener(IKeyEventListener& listener);
 146
 147         /**
 148          * Adds the ITouchEventListener instance to the %Control instance. @n
 149          * The added listener gets notified when a touch event such as a press or a release is fired.
 150          *
 151          * @since                2.0
 152          *
 153          * @param[in]   listener        The event listener to add
 154          * @see                 RemoveTouchEventListener()
 155          */
 156         void AddTouchEventListener(ITouchEventListener& listener);
 157
 158         /**
 159          * Adds the ITouchModeChangedEventListener instance to the %Control instance. @n
 160          * The added listener gets notified when the device's touch mode is changed.
 161          *
 162          * @since               2.0
 163          *
 164          * @param[in]   listener        The event listener to add
 165          * @see                 RemoveTouchModeChangedEventListener()
 166          */
 167         void AddTouchModeChangedEventListener(Tizen::Ui::ITouchModeChangedEventListener& listener);
 168
 169         /**
 170          * Adds the IDragDropEventListener instance to the %Control instance. @n
 171          * The added listener gets notified when a drag or a drop happens in the control.
 172          *
 173          * @since               2.0
 174          *
 175          * @param[in]   listener        The event listener to add
 176          * @see                 RemoveDragDropEventListener()
 177          */
 178         void AddDragDropEventListener(IDragDropEventListener& listener);
 179
 180         /**
 181          * Adds the IDragDropEventListenerF instance to the %Control instance. @n
 182          * The added listener gets notified when a drag or a drop happens in the control.
 183          *
 184          * @since               2.1
 185          *
 186          * @param[in]   listener        The event listener to add
 187          * @see                 RemoveDragDropEventListenerF()
 188          */
 189         void AddDragDropEventListener(IDragDropEventListenerF& listener);
 190
 191         /**
 192          * Removes the focus listener instance. @n
 193          * The removed listener is not notified even when focus events are fired.
 194          *
 195          * @since               2.0
 196          *
 197          * @param[in]   listener        The listener to remove
 198          * @see                 AddFocusEventListener()
 199          */
 200         void RemoveFocusEventListener(IFocusEventListener& listener);
 201
 202         /**
 203          * Removes the key event listener instance. @n
 204          * The removed listener is not notified even when key events are fired.
 205          *
 206          * @since               2.0
 207          *
 208          * @param[in]   listener        The listener to remove
 209          * @see                 AddKeyEventListener()
 210          */
 211         void RemoveKeyEventListener(IKeyEventListener& listener);
 212
 213         /**
 214          * Removes the touch event listener instance. @n
 215          * The removed listener is not notified even when touch events are fired.
 216          *
 217          * @since               2.0
 218          *
 219          * @param[in]   listener        The listener to remove
 220          * @see                 AddTouchEventListener()
 221          */
 222         void RemoveTouchEventListener(ITouchEventListener& listener);
 223
 224         /**
 225          * Removes the touch mode changed event listener instance. @n
 226          * The removed listener is not notified even when the touch mode changed events are fired.
 227          *
 228          * @since               2.0
 229          *
 230          * @param[in]   listener        The listener to remove
 231          * @see                 AddTouchModeChangedEventListener()
 232          */
 233         void RemoveTouchModeChangedEventListener(Tizen::Ui::ITouchModeChangedEventListener& listener);
 234
 235         /**
 236          * Adds the IDragDropEventListener instance to the %Control instance. @n
 237          * The added listener gets notified when a drag or a drop happens in the control.
 238          *
 239          * @since                2.0
 240          *
 241          * @param[in]   listener        The event listener to add
 242          * @see                 Tizen::Ui::IDragDropEventListener::OnTouchDragged()
 243          * @see                 Tizen::Ui::IDragDropEventListener::OnTouchDropped()
 244          * @see                 RemoveDragDropEventListener()
 245          */
 246         void RemoveDragDropEventListener(IDragDropEventListener& listener);
 247
 248         /**
 249          * Adds the IDragDropEventListenerF instance to the %Control instance. @n
 250          * The added listener gets notified when a drag or a drop happens in the control.
 251          *
 252          * @since                2.1
 253          *
 254          * @param[in]   listener        The event listener to add
 255          * @see                 Tizen::Ui::IDragDropEventListenerF::OnTouchDraggedF()
 256          * @see                 Tizen::Ui::IDragDropEventListenerF::OnTouchDroppedF()
 257          * @see                 RemoveDragDropEventListenerF()
 258          */
 259         void RemoveDragDropEventListenerF(IDragDropEventListenerF& listener);
 260
 261         /**
 262          * Overrides this method to provide user-specific initialization code before the control is added to a container.
 263          *
 264          * @since               2.0
 265          *
 266          * @return              An error code
 267          * @exception   E_SUCCESS       The method is successful.
 268          * @exception   E_FAILURE       The method has failed.
 269          * @remarks             This method is called when the control is about to be added to a container.
 270          * @remarks             To cancel adding this control to the parent, return @c E_FAILURE in this method.
 271          * @see                 OnTerminating()
 272          */
 273         virtual result OnInitializing(void);
 274
 275         /**
 276          * Overrides this method to provide user-specific termination code.
 277          *
 278          * @if OSPCOMPAT
 279          * @brief <i> [Compatibility] </i>
 280          * @endif
 281          * @since               2.0
 282          *
 283          * @if OSPCOMPAT
 284          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 285          *                       For more information, see @ref CompOnTerminatingPage "here".
 286          * @endif
 287          * @return              An error code
 288          * @exception   E_SUCCESS       The method is successful.
 289          * @exception   E_FAILURE       The method has failed.
 290          * @remarks             This method is called right before the control is removed from the container, or Destroy() method is being called.
 291          * @remarks             To cancel the removal or Destroy() operation, return any exception other than E_SUCCESS.
 292          * @see                 OnInitializing()
 293          */
 294         virtual result OnTerminating(void);
 295
 296         /**
 297          * @if OSPCOMPAT
 298          * @page               CompOnTerminatingPage        Compatibility for OnTerminating()
 299          * @section            CompOnterminatingPageIssueSection          Issues
 300          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
 301          * -# OnTerminating() callback is called from child to parent.
 302          *
 303          * @section            CompOnTerminatingPageSolutionSection               Resolutions
 304          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
 305          * -# OnTerminating() callback is called from parent to child.
 306          * @endif
 307          */
 308
 309         /**
 310          * Called asynchronously when the user event that is sent by SendUserEvent() method is
 311          * dispatched to the control.
 312          *
 313          * @since               2.0
 314          *
 315          * @param[in]   requestId       The user-defined event ID
 316          * @param[in]   pArgs  A pointer to the argument list
 317          * @see                 SendUserEvent()
 318          */
 319         virtual void OnUserEventReceivedN(RequestId requestId, Tizen::Base::Collection::IList* pArgs);
 320
 321         /**
 322          * Deallocates this instance after removing all child controls of this control
 323          *
 324          * @since 2.1
 325          *
 326          * @exception   E_SUCCESS       The method is successful.
 327          * @remarks             The control will be deleted from memory. Before it is deleted, OnTerminating() is called if it is attached to the main tree.
 328          * @remarks             If OnTerminating() method is overrided and returns an exception, that exception will be propagated.
 329          * @see                 Tizen::Ui::Control:OnTerminating()
 330          */
 331         result Destroy(void);
 332
 333         /**
 334          * Checks whether the control is movable.
 335          *
 336          * @since               2.0
 337          *
 338          * @return              @c true if the control is movable, @n
 339          *                              else @c false
 340          * @exception   E_SUCCESS                       The method is successful.
 341          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 342          * @remarks             When control is not movable SetPosition() and SetBounds() return @c E_UNSUPPORTED_OPERATION.
 343          * @see                 SetPosition()
 344          * @see                 SetBounds()
 345          */
 346         bool IsMovable(void) const;
 347
 348         /**
 349          * Checks whether the control is resizable.
 350          *
 351          * @since               2.0
 352          *
 353          * @return              @c true if the control is resizable, @n
 354          *                              else @c false
 355          * @exception   E_SUCCESS                       The method is successful.
 356          * @remarks             Even if this method returns @c true, the size can be changed internally.
 357          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 358          * @remarks             When control is not resizable,
 359          *                              SetSize(), SetBounds(), SetMinimumSize() and SetMaximumSize() return @c E_UNSUPPORTED_OPERATION.
 360          * @see                 SetSize()
 361          * @see                 SetBounds()
 362          * @see                 SetMinimumSize()
 363          * @see                 SetMaximumSize()
 364          */
 365         bool IsResizable(void) const;
 366
 367         /**
 368          * Gets the position and the size of the control.
 369          *
 370          * @since               2.0
 371          *
 372          * @return              An instance of the Tizen::Graphics::Rectangle that represents the position of top-left corner,
 373          *                              the width, and the height of the control
 374          * @remarks             The shape of the control is rectangular that is defined by the top-left point,
 375          *                              and the width or height. The position
 376          *                              of the top-left point is relative to the top-left corner of the parent container.
 377          * @see                 SetBounds()
 378          */
 379         Tizen::Graphics::Rectangle GetBounds(void) const;
 380
 381         /**
 382          * Gets the position and the size of the control.
 383          *
 384          * @since               2.1
 385          *
 386          * @return              An instance of the Tizen::Graphics::FloatRectangle that represents the position of top-left corner,
 387          *                              the width, and the height of the control
 388          * @remarks             The shape of the control is rectangular that is defined by the top-left point,
 389          *                              and the width or height. The position
 390          *                              of the top-left point is relative to the top-left corner of the parent container.
 391          * @see                 SetBounds()
 392          */
 393         Tizen::Graphics::FloatRectangle GetBoundsF(void) const;
 394
 395         /**
 396          * Gets the position and the size of the control.
 397          *
 398          * @since               2.0
 399          *
 400          * @param[out]  x               The x position of top-left corner of the control
 401          * @param[out]  y               The y position of top-left corner of the control
 402          * @param[out]  width   The width of the rectangular region
 403          * @param[out]  height  The height of the rectangular region
 404          * @remarks             The shape of the control is regarded as a rectangle that is defined
 405          *                              by the top-left point and the width or height.
 406          *                              The position of the top-left point is relative to the top-left corner of
 407          *                              the parent container.
 408          * @see                 SetBounds()
 409          */
 410         void GetBounds(int& x, int& y, int& width, int& height) const;
 411
 412         /**
 413          * Gets the position and the size of the control.
 414          *
 415          * @since               2.1
 416          *
 417          * @param[out]  x               The x position of top-left corner of the control
 418          * @param[out]  y               The y position of top-left corner of the control
 419          * @param[out]  width   The width of the rectangular region
 420          * @param[out]  height  The height of the rectangular region
 421          * @remarks             The shape of the control is regarded as a rectangle that is defined
 422          *                              by the top-left point and the width or height.
 423          *                              The position of the top-left point is relative to the top-left corner of
 424          *                              the parent container.
 425          * @see                 SetBounds()
 426          */
 427         void GetBounds(float& x, float& y, float& width, float& height) const;
 428
 429         /**
 430          * Gets the position of the control's top-left corner.
 431          *
 432          * @since               2.0
 433          *
 434          * @return              The position of the control's top-left corner
 435          * @remarks             The position of top-left corner is relative to the top-left corner of its parent container.
 436          * @see                 GetBounds()
 437          */
 438         Tizen::Graphics::Point GetPosition(void) const;
 439
 440         /**
 441          * Gets the position of the control's top-left corner.
 442          *
 443          * @since               2.1
 444          *
 445          * @return              The position of the control's top-left corner
 446          * @remarks             The position of top-left corner is relative to the top-left corner of its parent container.
 447          * @see                 GetBounds()
 448          */
 449         Tizen::Graphics::FloatPoint GetPositionF(void) const;
 450
 451         /**
 452          * Gets the position of the control's top-left corner.
 453          *
 454          * @since               2.0
 455          *
 456          * @param[out]  x The x position of the control's top-left corner
 457          * @param[out]  y The y position of the control's top-left corner
 458          * @remarks             The position of top-left corner is relative to the top-left corner of its parent container.
 459          * @see                 GetBounds()
 460          */
 461         void GetPosition(int& x, int& y) const;
 462
 463         /**
 464          * Gets the position of the control's top-left corner.
 465          *
 466          * @since               2.1
 467          *
 468          * @param[out]  x The x position of the control's top-left corner
 469          * @param[out]  y The y position of the control's top-left corner
 470          * @remarks             The position of top-left corner is relative to the top-left corner of its parent container.
 471          * @see                 GetBounds()
 472          */
 473         void GetPosition(float& x, float& y) const;
 474
 475         /**
 476          * Gets the size of the control.
 477          *
 478          * @since               2.0
 479          *
 480          * @return              The size of the control
 481          * @see                 GetBounds()
 482          */
 483         Tizen::Graphics::Dimension GetSize(void) const;
 484
 485         /**
 486          * Gets the size of the control.
 487          *
 488          * @since               2.1
 489          *
 490          * @return              The size of the control
 491          * @see                 GetBounds()
 492          */
 493         Tizen::Graphics::FloatDimension GetSizeF(void) const;
 494
 495         /**
 496          * Gets the size of the control.
 497          *
 498          * @since               2.0
 499          *
 500          * @param[out]  width   The width of the control
 501          * @param[out]  height  The height of the control
 502          * @see         GetBounds()
 503          */
 504         void GetSize(int& width, int& height) const;
 505
 506         /**
 507          * Gets the size of the control.
 508          *
 509          * @since               2.1
 510          *
 511          * @param[out]  width   The width of the control
 512          * @param[out]  height  The height of the control
 513          * @see         GetBounds()
 514          */
 515         void GetSize(float& width, float& height) const;
 516
 517         /**
 518          * Gets the x position of the control. @n
 519          * The position of control is relative to the top-left corner of its parent container.
 520          *
 521          * @since               2.0
 522          *
 523          * @return              The x position of the control
 524          * @see                 GetBounds()
 525          * @see                 GetPosition()
 526          * @see                 GetY()
 527          */
 528         int GetX(void) const;
 529
 530         /**
 531          * Gets the x position of the control. @n
 532          * The position of control is relative to the top-left corner of its parent container.
 533          *
 534          * @since               2.1
 535          *
 536          * @return              The x position of the control
 537          * @see                 GetBounds()
 538          * @see                 GetPosition()
 539          * @see                 GetYF()
 540          */
 541         float GetXF(void) const;
 542
 543         /**
 544          * Gets the y position of the control. @n
 545          * The position of control is relative to the top-left corner of its parent container.
 546          *
 547          * @since               2.0
 548          *
 549          * @return              The y position of the control
 550          * @see                 GetBounds()
 551          * @see                 GetPosition()
 552          * @see                 Get()
 553          */
 554         int GetY(void) const;
 555
 556         /**
 557          * Gets the y position of the control. @n
 558          * The position of control is relative to the top-left corner of its parent container.
 559          *
 560          * @since               2.1
 561          *
 562          * @return              The y position of the control
 563          * @see                 GetBounds()
 564          * @see                 GetPosition()
 565          * @see                 GetXF()
 566          */
 567         float GetYF(void) const;
 568
 569         /**
 570          * Gets the width of the control.
 571          *
 572          * @since               2.0
 573          *
 574          * @return              The width of the control
 575          * @see                 GetBounds()
 576          * @see                 GetSize()
 577          * @see                 GetHeight()
 578          */
 579         int GetWidth(void) const;
 580
 581         /**
 582          * Gets the width of the control.
 583          *
 584          * @since               2.1
 585          *
 586          * @return              The width of the control
 587          * @see                 GetBounds()
 588          * @see                 GetSizeF()
 589          * @see                 GetHeightF()
 590          */
 591         float GetWidthF(void) const;
 592
 593         /**
 594          * Gets the height of the control.
 595          *
 596          * @since               2.0
 597          *
 598          * @return              The height of the control
 599          * @see                 GetBounds()
 600          * @see                 GetSize()
 601          * @see                 GetWidth()
 602          */
 603         int GetHeight(void) const;
 604
 605         /**
 606          * Gets the height of the control.
 607          *
 608          * @since               2.1
 609          *
 610          * @return              The height of the control
 611          * @see                 GetBounds()
 612          * @see                 GetSizeF()
 613          * @see                 GetWidthF()
 614          */
 615         float GetHeightF(void) const;
 616
 617         /**
 618          * Gets the minimum size of the control.
 619          *
 620          * @since               2.0
 621          *
 622          * @return              The minimum size of the control
 623          * @exception   E_SUCCESS                               The method is successful.
 624          * @exception   E_SYSTEM                                A system error has occurred.
 625          * @remarks             The first call of the method returns the system-defined minimum size.
 626          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 627          */
 628         Tizen::Graphics::Dimension GetMinimumSize(void) const;
 629
 630         /**
 631          * Gets the minimum size of the control.
 632          *
 633          * @since               2.1
 634          *
 635          * @return              The minimum size of the control
 636          * @exception   E_SUCCESS                               The method is successful.
 637          * @exception   E_SYSTEM                                A system error has occurred.
 638          * @remarks             The first call of the method returns the system-defined minimum size.
 639          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 640          */
 641         Tizen::Graphics::FloatDimension GetMinimumSizeF(void) const;
 642
 643         /**
 644          * Gets the maximum size of the control.
 645          *
 646          * @since               2.0
 647          *
 648          * @return              The maximum size of the control
 649          * @exception   E_SUCCESS                               The method is successful.
 650          * @exception   E_SYSTEM                                A system error has occurred.
 651          * @remarks             The first call of the method returns the system-defined maximum size.
 652          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 653          */
 654         Tizen::Graphics::Dimension GetMaximumSize(void) const;
 655
 656         /**
 657          * Gets the maximum size of the control.
 658          *
 659          * @since               2.1
 660          *
 661          * @return              The maximum size of the control
 662          * @exception   E_SUCCESS                               The method is successful.
 663          * @exception   E_SYSTEM                                A system error has occurred.
 664          * @remarks             The first call of the method returns the system-defined maximum size.
 665          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 666          */
 667         Tizen::Graphics::FloatDimension GetMaximumSizeF(void) const;
 668
 669         /**
 670          * Gets a font of the control.
 671          *
 672          * @since 2.0
 673          *
 674          * @return                   The font name set in the control  @n
 675          *                                         else an empty string if the font is not set
 676          * @see         SetFont()
 677          */
 678         Tizen::Base::String GetFont(void) const;
 679
 680         /**
 681          * Sets the position and size of the control.
 682          *
 683          * @since               2.0
 684          *
 685          * @return              An error code
 686          * @param[in]   rect                                    The new bounds of the control
 687          * @exception   E_SUCCESS                               The method is successful.
 688          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 689          * @exception   E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
 690          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 691          * @exception   E_SYSTEM                                A system error has occurred.
 692          * @remarks             Do not override this method.
 693          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 694          * @see                 IsMovable()
 695          * @see                 IsResizable()
 696          * @see                 GetMinimumSize()
 697          * @see                 GetMaximumSize()
 698          * @see                 SetPosition()
 699          * @see                 SetSize()
 700          */
 701         result SetBounds(const Tizen::Graphics::Rectangle& rect);
 702
 703         /**
 704          * Sets the position and size of the control.
 705          *
 706          * @since               2.1
 707          *
 708          * @return              An error code
 709          * @param[in]   rect                                    The new bounds of the control
 710          * @exception   E_SUCCESS                               The method is successful.
 711          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 712          * @exception   E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
 713          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 714          * @exception   E_SYSTEM                                A system error has occurred.
 715          * @remarks             Do not override this method.
 716          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 717          * @see                 IsMovable()
 718          * @see                 IsResizable()
 719          * @see                 GetMinimumSize()
 720          * @see                 GetMaximumSize()
 721          * @see                 SetPosition()
 722          * @see                 SetSiz()
 723          */
 724         result SetBounds(const Tizen::Graphics::FloatRectangle& rect);
 725
 726         /**
 727          * Sets the position and size of the control. @n
 728          * The position is set at (x, y), and the @c width and @c height parameters contain
 729          * the width and height values of the object, respectively.
 730          *
 731          * @since               2.0
 732          *
 733          * @return              An error code
 734          * @param[in]   x                                               The new x position of the control
 735          * @param[in]   y                                               The new y position of the control
 736          * @param[in]   width                                   The new width of the control
 737          * @param[in]   height                                  The new height of the control
 738          * @exception   E_SUCCESS                               The method is successful.
 739          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 740          * @exception   E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
 741          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 742          * @exception   E_SYSTEM                                A system error has occurred.
 743          * @remarks             Do not override this method.
 744          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 745          * @see                 IsMovable()
 746          * @see                 IsResizable()
 747          * @see                 GetMinimumSize()
 748          * @see                 GetMaximumSize()
 749          * @see                 SetPosition()
 750          * @see                 SetSize()
 751          */
 752         result SetBounds(int x, int y, int width, int height);
 753
 754         /**
 755          * Sets the position and size of the control. @n
 756          * The position is set at (x, y), and the @c width and @c height parameters contain
 757          * the width and height values of the object, respectively.
 758          *
 759          * @since               2.1
 760          *
 761          * @return              An error code
 762          * @param[in]   x                                               The new x position of the control
 763          * @param[in]   y                                               The new y position of the control
 764          * @param[in]   width                                   The new width of the control
 765          * @param[in]   height                                  The new height of the control
 766          * @exception   E_SUCCESS                               The method is successful.
 767          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 768          * @exception   E_UNSUPPORTED_OPERATION This control is neither movable nor resizable.
 769          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 770          * @exception   E_SYSTEM                                A system error has occurred.
 771          * @remarks             Do not override this method.
 772          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 773          * @see                 IsMovable()
 774          * @see                 IsResizable()
 775          * @see                 GetMinimumSize()
 776          * @see                 GetMaximumSize()
 777          * @see                 SetPosition()
 778          * @see                 SetSize()
 779          */
 780         result SetBounds(float x, float y, float width, float height);
 781
 782         /**
 783          * Sets the relative position of the control.
 784          *
 785          * @since               2.0
 786          *
 787          * @return              An error code
 788          * @param[in]   position                                The new position
 789          * @exception   E_SUCCESS                               The method is successful.
 790          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 791          * @exception   E_UNSUPPORTED_OPERATION This control is not movable.
 792          * @exception   E_SYSTEM                                A system error has occurred.
 793          * @remarks             Do not override this method.
 794          * @remarks             The position of the control are relative to the top-left corner of its parent.
 795          * @see                 IsMovable()
 796          * @see                 SetBounds()
 797          */
 798         result SetPosition(const Tizen::Graphics::Point& position);
 799
 800         /**
 801          * Sets the relative position of the control.
 802          *
 803          * @since               2.1
 804          *
 805          * @return              An error code
 806          * @param[in]   position                                The new position
 807          * @exception   E_SUCCESS                               The method is successful.
 808          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 809          * @exception   E_UNSUPPORTED_OPERATION This control is not movable.
 810          * @exception   E_SYSTEM                                A system error has occurred.
 811          * @remarks             Do not override this method.
 812          * @remarks             The position of the control are relative to the top-left corner of its parent.
 813          * @see                 IsMovable()
 814          * @see                 SetBounds()
 815          */
 816         result SetPosition(const Tizen::Graphics::FloatPoint& position);
 817
 818         /**
 819          * Sets the position of the control.
 820          *
 821          * @since               2.0
 822          * @return              An error code
 823          * @param[in]   x                                               The new x position of the control
 824          * @param[in]   y                                               The new y position of the control
 825          * @exception   E_SUCCESS                               The method is successful.
 826          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 827          * @exception   E_UNSUPPORTED_OPERATION This control is not movable.
 828          * @exception   E_SYSTEM                                A system error has occurred.
 829          * @remarks             Do not override this method.
 830          * @remarks             The x,y position of the control are relative to the top-left corner of its parent.
 831          * @see                 IsMovable()
 832          * @see                 SetBounds()
 833          */
 834         result SetPosition(int x, int y);
 835
 836         /**
 837          * Sets the position of the control.
 838          *
 839          * @since               2.1
 840          * @return              An error code
 841          * @param[in]   x                                               The new x position of the control
 842          * @param[in]   y                                               The new y position of the control
 843          * @exception   E_SUCCESS                               The method is successful.
 844          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 845          * @exception   E_UNSUPPORTED_OPERATION This control is not movable.
 846          * @exception   E_SYSTEM                                A system error has occurred.
 847          * @remarks             Do not override this method.
 848          * @remarks             The x,y position of the control are relative to the top-left corner of its parent.
 849          * @see                 IsMovable()
 850          * @see                 SetBounds()
 851          */
 852         result SetPosition(float x, float y);
 853
 854         /**
 855          * Sets the size of the control. @n
 856          * The @c width and @c height parameters contain the width and height values of the object, respectively.
 857          *
 858          * @since               2.0
 859          *
 860          * @return              An error code
 861          * @param[in]   size                                    The new width and height
 862          * @exception   E_SUCCESS                               The method is successful.
 863          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 864          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 865          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 866          * @exception   E_SYSTEM                                A system error has occurred.
 867          * @remarks             Do not override this method.
 868          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 869          * @see                 IsResizable()
 870          * @see                 GetMinimumSize()
 871          * @see                 GetMaximumSize()
 872          * @see                 SetBounds()
 873          */
 874         result SetSize(const Tizen::Graphics::Dimension& size);
 875
 876         /**
 877          * Sets the size of the control.
 878          * The @c width and @c height parameters contain the width and height values of the object, respectively.
 879          *
 880          * @since               2.1
 881          *
 882          * @return              An error code
 883          * @param[in]   size                                    The new width and height
 884          * @exception   E_SUCCESS                               The method is successful.
 885          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 886          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 887          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 888          * @exception   E_SYSTEM                                A system error has occurred.
 889          * @remarks             Do not override this method.
 890          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 891          * @see                 IsResizable()
 892          * @see                 GetMinimumSize()
 893          * @see                 GetMaximumSize()
 894          * @see                 SetBounds()
 895          */
 896         result SetSize(const Tizen::Graphics::FloatDimension& size);
 897
 898         /**
 899          * Sets the size of the control. @n
 900          * The @c width and @c height parameters contain the width and height values of the object, respectively.
 901          *
 902          * @since       2.0
 903          *
 904          * @return              An error code
 905          * @param[in]   width                                   The new width of the control
 906          * @param[in]   height                                  The new height of the control
 907          * @exception   E_SUCCESS                               The method is successful.
 908          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 909          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 910          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 911          * @exception   E_SYSTEM                                A system error has occurred.
 912          * @remarks             Do not override this method.
 913          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 914          * @see                 IsResizable()
 915          * @see                 GetMinimumSize()
 916          * @see                 GetMaximumSize()
 917          * @see                 SetBounds()
 918          */
 919         result SetSize(int width, int height);
 920
 921         /**
 922          * Sets the size of the control.
 923          * The @c width and @c height parameters contain the width and height values of the object, respectively.
 924          *
 925          * @since       2.1
 926          *
 927          * @return              An error code
 928          * @param[in]   width                                   The new width of the control
 929          * @param[in]   height                                  The new height of the control
 930          * @exception   E_SUCCESS                               The method is successful.
 931          * @exception   E_INVALID_OPERATION             The control has not been constructed as yet.
 932          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 933          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 934          * @exception   E_SYSTEM                                A system error has occurred.
 935          * @remarks             Do not override this method.
 936          * @remarks             The size of the control must be within the range defined by the minimum size and the maximum size.
 937          * @see                 IsResizable()
 938          * @see                 GetMinimumSize()
 939          * @see                 GetMaximumSize()
 940          * @see                 SetBounds()
 941          */
 942         result SetSize(float width, float height);
 943
 944         /**
 945          * Sets the minimum size of the control.
 946          *
 947          * @since               2.0
 948          *
 949          * @return              An error code
 950          * @param[in]   newMinDim                               The new minimum size of the control
 951          * @exception   E_SUCCESS                               The method is successful.
 952          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 953          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 954          * @exception   E_SYSTEM                                A system error has occurred.
 955          * @remarks             This method can affect the maximum size and the current size of the control. @n
 956          *                              The control needs to be redrawn to reflect the change in its size. @n
 957          *                              If the current maximum size or the control size is smaller than the new minimum size,
 958          *                              it becomes the same as the new minimum size.
 959          * @see                 IsResizable()
 960          */
 961         result SetMinimumSize(const Tizen::Graphics::Dimension& newMinDim);
 962
 963         /**
 964          * Sets the minimum size of the control.
 965          *
 966          * @since               2.1
 967          *
 968          * @return              An error code
 969          * @param[in]   newMinDim                               The new minimum size of the control
 970          * @exception   E_SUCCESS                               The method is successful.
 971          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 972          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 973          * @exception   E_SYSTEM                                A system error has occurred.
 974          * @remarks             This method can affect the maximum size and the current size of the control. @n
 975          *                              The control needs to be redrawn to reflect the change in its size. @n
 976          *                              If the current maximum size or the control size is smaller than the new minimum size,
 977          *                              it becomes the same as the new minimum size.
 978          * @see                 IsResizable()
 979          */
 980         result SetMinimumSize(const Tizen::Graphics::FloatDimension& newMinDim);
 981
 982         /**
 983          * Sets the maximum size of the control.
 984          *
 985          * @since               2.0
 986          *
 987          * @return              An error code
 988          * @param[in]   newMaxDim                                       The new maximum size of the control
 989          * @exception   E_SUCCESS                               The method is successful.
 990          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
 991          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 992          * @exception   E_SYSTEM                                A system error has occurred.
 993          * @remarks             This method can affect the minimum size and the current size of the control. @n
 994          *                              The control needs to be redrawn to reflect the change in its size. @n
 995          *                              If the current minimum size or the control size is greater than the new maximum size,
 996          *                              it becomes the same as the new maximum size.
 997          * @see                 IsResizable()
 998          */
 999         result SetMaximumSize(const Tizen::Graphics::Dimension& newMaxDim);
1000
1001         /**
1002          * Sets the maximum size of the control.
1003          *
1004          * @since               2.1
1005          *
1006          * @return              An error code
1007          * @param[in]   newMaxDim                                       The new maximum size of the control
1008          * @exception   E_SUCCESS                               The method is successful.
1009          * @exception   E_UNSUPPORTED_OPERATION This control is not resizable.
1010          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
1011          * @exception   E_SYSTEM                                A system error has occurred.
1012          * @remarks             This method can affect the minimum size and the current size of the control. @n
1013          *                              The control needs to be redrawn to reflect the change in its size. @n
1014          *                              If the current minimum size or the control size is greater than the new maximum size,
1015          *                              it becomes the same as the new maximum size.
1016          * @see                 IsResizable()
1017          */
1018         result SetMaximumSize(const Tizen::Graphics::FloatDimension& newMaxDim);
1019
1020         /**
1021          * Converts the specified screen position to the position in control's coordinate system.
1022          *
1023          * @since 2.0
1024          *
1025          * @return      The position relative to the top-left corner of the control's client-area
1026          * @param[in]   screenPosition  The position relative to the top-left corner of the screen
1027          * @see         ConvertToScreenPosition()
1028          */
1029         Tizen::Graphics::Point ConvertToControlPosition(const Tizen::Graphics::Point& screenPosition) const;
1030
1031         /**
1032          * Converts the specified screen position to the position in control's coordinate system.
1033          *
1034          * @since 2.1
1035          *
1036          * @return      The position relative to the top-left corner of the control's client-area
1037          * @param[in]   screenPosition  The position relative to the top-left corner of the screen
1038          * @see         ConvertToScreenPosition()
1039          */
1040         Tizen::Graphics::FloatPoint ConvertToControlPosition(const Tizen::Graphics::FloatPoint& screenPosition) const;
1041
1042         /**
1043          * Converts the specified position in the control's coordinate system to the screen position.
1044          *
1045          * @since 2.0
1046          *
1047          * @return      The position relative to the top-left corner of the screen
1048          * @param[in]   controlPosition         The position relative to the top-left corner of the control's client-area
1049          * @see         ConvertToControlPosition()
1050          */
1051         Tizen::Graphics::Point ConvertToScreenPosition(const Tizen::Graphics::Point& controlPosition) const;
1052
1053         /**
1054          * Converts the specified position in the control's coordinate system to the screen position.
1055          *
1056          * @since 2.1
1057          *
1058          * @return      The position relative to the top-left corner of the screen
1059          * @param[in]   controlPosition         The position relative to the top-left corner of the control's client-area
1060          * @see         ConvertToControlPosition()
1061          */
1062         Tizen::Graphics::FloatPoint ConvertToScreenPosition(const Tizen::Graphics::FloatPoint& controlPosition) const;
1063
1064         /**
1065          * Sets the font of the control.
1066          *
1067          * @since 2.0
1068          *
1069          * @return      An error code
1070          * @param[in]   fontName                        The app font name or system font name @n
1071          *                                              The app font name is retrieved using Tizen::Graphics::Font::GetFaceName(Tizen::Base::String& filepath). @n
1072          *                                              The system font name is retrieved using Tizen::Graphics::Font::GetSystemFontListN().
1073          *                                              Sets an empty string to reset.
1074          * @exception   E_SUCCESS                       The method is successful.
1075          * @exception   E_FILE_NOT_FOUND                The specified font cannot be found or accessed.
1076          * @remarks     At first, the value of @c fontName is considered app font name if it matches one of the face names of the font files which are located in @b '/res/font'.
1077          *              If not, the value of @c fontName is considered system font name if it matches one of the retrieved values using Tizen::Graphics::Font::GetSystemFontListN().
1078          * @remarks     The control first attempts to find the control font. If it fails, then it searches for the application default font and the system font, in sequence.
1079          * @see         GetFont()
1080          */
1081         result SetFont(const Tizen::Base::String& fontName);
1082
1083         /**
1084          * Checks whether the specified @c point is inside the control.
1085          *
1086          * @since               2.0
1087          *
1088          * @return              @c true if the specified @c point is inside the control, @n
1089          *                              else @c false
1090          * @param[in]   point The point to check
1091          * @remarks             The specified @c point must be defined relative to the top-left corner of the control.
1092          */
1093         bool Contains(const Tizen::Graphics::Point& point) const;
1094
1095         /**
1096          * Checks whether the specified @c point is inside the control.
1097          *
1098          * @since               2.1
1099          *
1100          * @return              @c true if the specified @c point is inside the control, @n
1101          *                              else @c false
1102          * @param[in]   point The point to check
1103          * @remarks             The specified @c point must be defined relative to the top-left corner of the control.
1104          */
1105         bool Contains(const Tizen::Graphics::FloatPoint& point) const;
1106
1107         /**
1108          * Checks whether the specified point is inside the control.
1109          *
1110          * @since               2.0
1111          *
1112          * @return              @c true if the specified point is inside the control, @n
1113          *                              else @c false
1114          * @param[in]   x The x position of the point to check
1115          * @param[in]   y The y position of the point to check
1116          * @remarks             The specified point must be defined relative to the top-left corner of the control.
1117          */
1118         bool Contains(int x, int y) const;
1119
1120         /**
1121          * Checks whether the specified point is inside the control.
1122          *
1123          * @since               2.1
1124          *
1125          * @return              @c true if the specified point is inside the control, @n
1126          *                              else @c false
1127          * @param[in]   x The x position of the point to check
1128          * @param[in]   y The y position of the point to check
1129          * @remarks             The specified point must be defined relative to the top-left corner of the control.
1130          */
1131         bool Contains(float x, float y) const;
1132
1133         /**
1134          * Draws child controls recursively.
1135          *
1136          * @if OSPCOMPAT
1137          * @brief <i> [Compatibility] </i>
1138          * @endif
1139          * @since                    2.0
1140          *
1141          * @if OSPCOMPAT
1142          * @compatibility This method has compatibility issues with OSP compatible applications. @n
1143          *                       For more information, see @ref CompDrawPage "here".
1144          * @endif
1145          * @return                  An error code
1146          * @exception    E_SUCCESS           The method is successful.
1147          * @exception    E_INVALID_OPERATION    The current state of the instance prohibits the execution of the specified operation. @n
1148          *                                                                                             Note: This control cannot be displayed.
1149          * @exception    E_SYSTEM                              A system error has occurred.
1150          * @remarks     This method calls OnDraw() immediately in a synchronous way.
1151          * @see                      Show()
1152          */
1153         result Draw(void);
1154
1155         /**
1156          * @if OSPCOMPAT
1157          * @page               CompDrawPage        Compatibility for Draw()
1158          * @section            CompDrawPageIssueSection          Issues
1159          * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
1160          * -# Draw() method draws child controls in a recursive way regardless of the visibility of the parent.
1161          *
1162          * @section            CompDrawPageSolutionSection               Resolutions
1163          * The issue mentioned above is resolved in %Tizen API version 2.1 as follows: @n
1164          * -# Draw() method does not draw child controls if the control itself is not visible.
1165          * @endif
1166          */
1167
1168         /**
1169          * Draws the control.
1170          *
1171          * @since 2.0
1172          *
1173          * @param[in]   recursive               Set to @c true to draw child controls recursively, @n
1174          *                                                                              else @c false
1175          * @return      An error code
1176          * @exception   E_SUCCESS               The method is successful.
1177          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
1178          *              Note: This control cannot be displayed.
1179          * @exception   E_SYSTEM                              A system error has occurred.
1180          * @remarks     This method calls OnDraw() immediately in a synchronous way.
1181          * @see         Show()
1182          */
1183         result Draw(bool recursive);
1184
1185         /**
1186          * Shows the control on the screen.
1187          *
1188          * @since               2.0
1189          * @final       Although this method is virtual, it should not be overridden.
1190      * If overridden, it may not work as expected.
1191          *
1192          * @return              An error code
1193          * @exception   E_SUCCESS                       The method is successful.
1194          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
1195          *                                                                      Note: This control cannot be displayed.
1196          * @exception   E_SYSTEM                        A system error has occurred.
1197          * @remarks             Do not override this method.
1198          */
1199         virtual result Show(void);
1200
1201         /**
1202          * Invalidates the control.
1203          *
1204          * @since 2.0
1205          *
1206          * @param[in]   recursive       Set to @c true to invalidate child controls recursively, @n
1207          *                                                      else @c false
1208          * @exception   E_SUCCESS           The method is successful.
1209          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
1210          *                                                                      Note: This control cannot be displayed.
1211          * @exception   E_SYSTEM                        A system error has occurred.
1212          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1213          * @remarks             OnDraw() is not called immediately, but called asynchronously just before the screen is updated.
1214          * @see                 InvalidateBounds()
1215          * @see                 Show()
1216          */
1217         void Invalidate(bool recursive);
1218
1219         /**
1220          * Invalidates the control of the specified position and size.
1221          *
1222          * @since 2.0
1223          *
1224          * @param[in]    bounds                 The position relative to the top-left corner of the control
1225          * @exception   E_SUCCESS           The method is successful.
1226          * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation. @n
1227          *                                                                                             Note: This control cannot be displayed.
1228          * @remarks  The specific error code can be accessed using the GetLastResult() method.
1229          * @see                 Invalidate()
1230          * @see                 Show()
1231          */
1232         void InvalidateBounds(const Tizen::Graphics::Rectangle& bounds);
1233
1234         /**
1235          * Invalidates the control of the specified position and size.
1236          *
1237          * @since 2.1
1238          *
1239          * @param[in]    bounds                 The position relative to the top-left corner of the control
1240          * @exception   E_SUCCESS           The method is successful.
1241          * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation. @n
1242          *                                                                                             Note: This control cannot be displayed.
1243          * @remarks  The specific error code can be accessed using the GetLastResult() method.
1244          * @see                 Invalidate()
1245          * @see                 Show()
1246          */
1247         void InvalidateBounds(const Tizen::Graphics::FloatRectangle& bounds);
1248
1249         /**
1250          * Draws the control asynchronously.
1251          *
1252          * @since               2.0
1253          *
1254          * @param[in]   show    Set to @c true to also show the %Control, @n
1255          *                                              else @c false
1256          * @remarks             This method posts a draw event in the event queue. @n
1257          *                              Drawing requested by %RequestRedraw() occurs when the draw event is fired to the control.
1258          */
1259         void RequestRedraw(bool show = true) const;
1260
1261         /**
1262          * Creates and returns a graphics canvas whose bounds (that is, position and size) are equal to those
1263          * of the control.
1264          *
1265          * @since               2.0
1266          *
1267          * @return              The graphic canvas of the control, @n
1268          *                              else @c null if an exception occurs
1269          * @exception   E_SUCCESS                               The method is successful.
1270          * @exception   E_SYSTEM                        A system error has occurred.
1271          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1272          * @remarks             The method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the control.
1273          *                              It is the developer's responsibility to deallocate the canvas after use.
1274          *                              The canvas is guaranteed to be valid only if the properties of the parent controls of the canvas remain unchanged.
1275          *                              Therefore, one must delete previously allocated canvas and create a new canvas using the %GetCanvasN() method
1276          *                              if the size or position of the control is changed.
1277          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1278          * @remarks             The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
1279          *                              if custom drawing is performed on the graphic canvas of Frame and Form
1280          *                              then it will appear on the screen regardless of which control is currently visible on the screen.
1281          * @see                 GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const
1282          * @see                 GetCanvasN(int x, int y, int width, int height) const
1283          * @code
1284          * result
1285          * MyForm::OnDraw(void)
1286          * {
1287          *     result r = E_SUCCESS;
1288          *     Canvas* pCanvas = GetCanvasN();
1289          *     if (pCanvas != null)
1290          *     {
1291          *         // add your drawing code here
1292          *     }
1293          *     if (pCanvas)
1294          *         delete pCanvas;
1295          *         // Do not call Show(). It will be called automatically after OnDraw() callback.
1296          *     return r;
1297          * }
1298          * @endcode
1299          */
1300         Tizen::Graphics::Canvas* GetCanvasN(void) const;
1301
1302         /**
1303          * Creates and returns a graphic canvas of the control of the specified position and size.
1304          *
1305          * @since               2.0
1306          *
1307          * @return              The graphic canvas of the control, @n
1308          *                              else @c null if an exception occurs
1309          * @param[in]   bounds          The bounds of the graphic canvas
1310          * @exception   E_SUCCESS                               The method is successful.
1311          * @exception   E_OUT_OF_RANGE                  The specified bounds does not intercept with the bounds of the control.
1312          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1313          * @remarks             Only the graphic canvas of displayable controls can be obtained.
1314          *                              If the specified area is not inside the control,
1315          *                              the graphics canvas of overlapped area between the control and the specified bound is returned. @n
1316          * @remarks             The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
1317          *                              It is the developer's responsibility to deallocate the canvas after use.
1318          *                              The canvas is guaranteed to be valid only if the properties of the parent controls of the canvas remain unchanged.
1319          *                              Therefore, one must delete previously allocated canvas and create a new canvas using the %GetCanvasN() method
1320          *                              if the size or position of the control is changed.
1321          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1322          * @remarks             The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
1323          *                              if custom drawing is performed on the graphic canvas of Frame and Form
1324          *                              then it will appear on the screen regardless of which control is currently visible on the screen.
1325          * @see                 GetCanvasN(void) const
1326          * @see                 GetCanvasN(int x, int y, int width, int height) const
1327          */
1328         Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const;
1329
1330         /**
1331          * Creates and returns a graphic canvas of the control of the specified position and size.
1332          *
1333          * @since               2.1
1334          *
1335          * @return              The graphic canvas of the control, @n
1336          *                              else @c null if an exception occurs
1337          * @param[in]   bounds          The bounds of the graphic canvas
1338          * @exception   E_SUCCESS                               The method is successful.
1339          * @exception   E_OUT_OF_RANGE                  The specified bounds does not intercept with the bounds of the control.
1340          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1341          * @remarks             Only the graphic canvas of displayable controls can be obtained.
1342          *                              If the specified area is not inside the control,
1343          *                              the graphics canvas of overlapped area between the control and the specified bound is returned. @n
1344          * @remarks             The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
1345          *                              It is the developer's responsibility to deallocate the canvas after use.
1346          *                              The canvas is guaranteed to be valid only if the properties of the parent controls of the canvas remain unchanged.
1347          *                              Therefore, one must delete previously allocated canvas and create a new canvas using the %GetCanvasN() method
1348          *                              if the size or position of the control is changed.
1349          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1350          * @remarks             The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
1351          *                              if custom drawing is performed on the graphic canvas of Frame and Form
1352          *                              then it will appear on the screen regardless of which control is currently visible on the screen.
1353          * @see                 GetCanvasN(void) const
1354          * @see                 GetCanvasN(float x, float y, float width, float height) const
1355          */
1356         Tizen::Graphics::Canvas* GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const;
1357
1358         /**
1359          * Creates and returns a graphic canvas of the specified position and size in the control.
1360          *
1361          * @since               2.0
1362          *
1363          * @return              The graphic canvas of the control, @n
1364          *                              else @c null if an exception occurs
1365          * @param[in]   x  The x position relative to the top-left corner of the control
1366          * @param[in]   y  The y position relative to the top-left corner of the control
1367          * @param[in]   width   The width of a graphic canvas
1368          * @param[in]   height  The height of a graphic canvas
1369          * @exception   E_SUCCESS                               The method is successful.
1370          * @exception   E_OUT_OF_RANGE                  The specified bounds do not intercept with the bounds of the control.
1371          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1372          * @remarks             Only the graphic canvas of displayable controls can be obtained.
1373          *                              If the specified area is not inside the control,
1374          *                              the graphics canvas of the overlapped area between the control and the specified bound is returned. @n
1375          * @remarks             The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
1376          *                              It is the developer's responsibility to deallocate the canvas after use.
1377          *                              The canvas is guaranteed to be valid only if properties of the parent controls of the canvas remain unchanged.
1378          *                              Therefore, one must delete the previously allocated canvas and create a new canvas using the %GetCanvasN() method
1379          *                              if the size or position of the control is changed.
1380          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1381          * @remarks             The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
1382          *                              if custom drawing is performed on the graphic canvas of Frame and Form
1383          *                              then it will appear on the screen regardless of which control is currently visible on the screen.
1384          * @see                 GetCanvasN(void) const
1385          * @see                 GetCanvasN(const Tizen::Graphics::Rectangle& bounds) const
1386          */
1387         Tizen::Graphics::Canvas* GetCanvasN(int x, int y, int width, int height) const;
1388
1389         /**
1390          * Creates and returns a graphic canvas of the specified position and size in the control.
1391          *
1392          * @since               2.1
1393          *
1394          * @return              The graphic canvas of the control, @n
1395          *                              else @c null if an exception occurs
1396          * @param[in]   x  The x position relative to the top-left corner of the control
1397          * @param[in]   y  The y position relative to the top-left corner of the control
1398          * @param[in]   width   The width of a graphic canvas
1399          * @param[in]   height  The height of a graphic canvas
1400          * @exception   E_SUCCESS                               The method is successful.
1401          * @exception   E_OUT_OF_RANGE                  The specified bounds do not intercept with the bounds of the control.
1402          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1403          * @remarks             Only the graphic canvas of displayable controls can be obtained.
1404          *                              If the specified area is not inside the control,
1405          *                              the graphics canvas of the overlapped area between the control and the specified bound is returned. @n
1406          * @remarks             The method allocates an Tizen::Graphics::Canvas whose bounds are equal to that of the control.
1407          *                              It is the developer's responsibility to deallocate the canvas after use.
1408          *                              The canvas is guaranteed to be valid only if properties of the parent controls of the canvas remain unchanged.
1409          *                              Therefore, one must delete the previously allocated canvas and create a new canvas using the %GetCanvasN() method
1410          *                              if the size or position of the control is changed.
1411          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1412          * @remarks             The Frame and Form (and between different Form instances) share a single frame-buffer. Therefore,
1413          *                              if custom drawing is performed on the graphic canvas of Frame and Form
1414          *                              then it will appear on the screen regardless of which control is currently visible on the screen.
1415          * @see                 GetCanvasN(void) const
1416          * @see                 GetCanvasN(const Tizen::Graphics::FloatRectangle& bounds) const
1417          */
1418         Tizen::Graphics::Canvas* GetCanvasN(float x, float y, float width, float height) const;
1419
1420         /**
1421          * Checks whether the control is currently visible on the screen.
1422          *
1423          * @since               2.0
1424          *
1425          * @return              @c true if the control is currently visible on the screen, @n
1426          *                              else @c false
1427          * @remarks             If this method is called before the control is added to a parent, @c false is returned.
1428          * @see                 GetShowState()
1429          * @see                 SetShowState()
1430          */
1431         bool IsVisible(void) const;
1432
1433         /**
1434          * Gets the current show state of the control.
1435          *
1436          * @since               2.0
1437          *
1438          * @return              The show state of the control
1439          * @remarks             Even if the control's state is "show", the control may not be visible.
1440          * @see                 SetShowState()
1441          * @see                 IsVisible()
1442          */
1443         bool GetShowState(void) const;
1444
1445         /**
1446          * Sets the show state of the control.
1447          *
1448          * @since               2.0
1449          *
1450          * @return              An error code
1451          * @param[in]   state                           The new show state
1452          * @exception   E_SUCCESS                       The method is successful.
1453          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1454          *                                                                      Note: This control cannot be displayed.
1455          * @exception   E_SYSTEM                        A system error has occurred.
1456          * @remarks             Do not override this method.
1457          * @remarks             Even if this method is invoked, the control is not drawn or shown. @n
1458          *                              To display the control, use the Invalidate() methods. @n
1459          *                              Once the control's show state is set to @c false,
1460          *                              the show state needs to be set to @c true again before you invalidate the control.
1461          * @see                 GetShowState()
1462          * @see                 Invalidate()
1463          */
1464         result SetShowState(bool state);
1465
1466         /**
1467          * Gets the dedicated %VisualElement instance for this control.
1468          *
1469          * @since               2.0
1470          *
1471          * @return              An instance of the VisualElement
1472          * @remarks             If an application developer modifies the state of the returned VisualElement
1473          *                              and the host control is not aware of this change, then the control may behave egregiously.
1474          *                              It is highly recommended to restore the %VisualElement state to avoid such conflicts.
1475          */
1476         Tizen::Ui::Animations::VisualElement* GetVisualElement(void) const;
1477
1478         /**
1479          * Gets the parent of the control.
1480          *
1481          * @since               2.0
1482          *
1483          * @return              The current parent of the control
1484          */
1485         Container* GetParent(void) const;
1486
1487         /**
1488          * Gets the name of the control.
1489          *
1490          * @since               2.0
1491          *
1492          * @return              The name of the control
1493          */
1494         Tizen::Base::String GetName(void) const;
1495
1496         /**
1497          * Sets the name of the control.
1498          *
1499          * @since               2.0
1500          *
1501          * @param[in]   name    The name of the control
1502          */
1503         void SetName(const Tizen::Base::String& name);
1504
1505         /**
1506          * Checks whether the control is focusable.
1507          *
1508          * @since               2.0
1509          *
1510          * @return              @c true if control is focusable, @n
1511          *                              else @c false
1512          * @remarks             The focus ability of the container classes like Panel is @c false by default.
1513          */
1514         bool IsFocusable(void) const;
1515
1516         /**
1517          * Sets the focus ability of the control. @n
1518          * Non-Focusable controls cannot take the key focus.
1519          *
1520          * @since               2.0
1521          *
1522          * @return              An error code
1523          * @exception   E_SUCCESS                       The method is successful.
1524          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1525          *                                                                      Note: The control does not permit to change its focus ability.
1526          * @exception   E_SYSTEM                        A system error has occurred.
1527          * @remarks             The focus ability of the container classes like Panel is @c false by default.
1528          * @remarks             The RadioGroup class does not render the UI.
1529          *                              Therefore, RadioGroup::SetFocusable() returns @c E_SYSTEM.
1530          */
1531         result SetFocusable(bool focusable);
1532
1533         /**
1534          * Checks whether the control currently has the input focus.
1535          *
1536          * @since               2.0
1537          *
1538          * @return              @c true if the control currently has the input focus, @n
1539          *                              else @c false
1540          * @remarks             If this method is called before the control is added to a parent, @c false is returned.
1541          * @see                 SetFocus()
1542          */
1543         bool HasFocus(void) const;
1544
1545         /**
1546          * Sets the focus to the control. @n
1547          * This method is called if the control needs to listen to user input events such as key pressed.
1548          *
1549          * @since               2.0
1550          *
1551          * @return              An error code
1552          * @exception   E_SUCCESS                       The method is successful.
1553          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1554          *                                                                      Note: This control cannot be displayed.
1555          * @exception   E_INVALID_CONDITION     The control is not contained in, or is not the top z-order frame or form.
1556          * @remarks             Do not override this method.
1557          */
1558         result SetFocus(void);
1559
1560         /**
1561          * Checks whether the control is enabled.
1562          *
1563          * @since               2.0
1564          *
1565          * @return              @c true if the control is enabled, @n
1566          *                              else @c false
1567          * @remarks             If this method is called before the control is added to a parent, @c false is returned.
1568          * @see                 SetEnabled()
1569          */
1570         bool IsEnabled(void) const;
1571
1572         /**
1573          * Enables or disables the control. @n
1574          * Only an enabled control can respond to the user input. By default, the control is enabled.
1575          *
1576          * @since               2.0
1577          *
1578          * @return              An error code
1579          * @param[in]   enable                          The new state of the object
1580          * @exception   E_SUCCESS                       The method is successful.
1581          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
1582          * @exception   E_SYSTEM                        A system error has occurred.
1583          * @remarks             Do not override this method.
1584          */
1585         result SetEnabled(bool enable);
1586
1587         /**
1588          * Checks whether the device is in touch mode. @n
1589          * When the user interacts with the device by touching it, the device is in touch mode.
1590          *
1591          * @since               2.0
1592          *
1593          * @return              @c true if the device is in touch mode, @n
1594          *                              else @c false
1595          * @remarks             This method returns @c false, for devices with QWERTY keyboard.
1596          *                              The user can navigate the UI using directional keys.
1597          */
1598         bool IsInTouchMode(void) const;
1599
1600         /**
1601          * Enables or disables the drag operation in the %Control.
1602          *
1603          * @since               2.0
1604          *
1605          * @param[in]   enable  Set to @c true to enable the drag operation, @n
1606          *                                              else @c false
1607          * @see                 SetDropEnabled()
1608          */
1609         void SetDragEnabled(bool enable);
1610
1611         /**
1612          * Enables or disables the drop operations in the %Control.
1613          *
1614          * @since               2.0
1615          *
1616          * @param[in]   enable  Set to @c true to enable drop operations, @n
1617          *                              else @c false
1618          * @remarks             To receive drop event, control's drag property has to be enabled.
1619          * @see                 SetDragEnabled()
1620          */
1621         void SetDropEnabled(bool enable);
1622
1623         /**
1624          * Sends a user event to the control.
1625          *
1626          * @since               2.0
1627          *
1628          * @param[in]   requestId The user-defined event ID
1629          * @param[in]   pArgs  A pointer to the argument list
1630          * @remarks             This method posts a user event in the event queue
1631          *                              and returns immediately to support asynchronous actions of the framework.
1632          * @see                 OnUserEventReceived()
1633          */
1634         void SendUserEvent(RequestId requestId, const Tizen::Base::Collection::IList* pArgs) const;
1635
1636         /**
1637          * Stops the current UI event dispatch sequence by indicating the current input event is consumed.
1638          *
1639          * @brief <i> [Deprecated] </i>
1640          * @deprecated   This method is deprecated. Instead of using this method, use IPropagatedKeyEventListener or IPropagatedTouchEventListener to consume event. @n To propagate the event, return @c true inside the implementation of IPropagatedKeyEventListener or IPropagatedTouchEventListener.
1641          * @since                  2.0
1642          *
1643          * @return                 An error code
1644          * @exception E_SUCCESS                                   The method is successful.
1645          * @exception E_SYSTEM                                     A system error has occurred.
1646          * @remarks              If this method is invoked during an UI event (key or touch) propagation sequence,
1647          *                                        the method will stop the propagation and consequently the system will not be notified of the event.@n
1648          *                                        The method will not have any effect if no UI event is being dispatched. @n
1649          *                                        It is recommended that this method is called within IKeyEventListener or
1650          *                                        ITouchEventListener to stop the event from propagating to the next step.
1651          */
1652         result ConsumeInputEvent(void);
1653
1654         /**
1655          * Gets the control animator of the current instance of %Control.
1656          *
1657          * @since               2.0
1658          *
1659          * @return              A pointer to ControlAnimator, @n
1660          *                              else @c null if this instance is not constructed or not added to a parent or non-animatable
1661          */
1662         Tizen::Ui::Animations::ControlAnimator* GetControlAnimator(void) const;
1663
1664         /**
1665          * Adds the gesture detector to the %Control. @n
1666          * The added gesture detector receives touch events prior to %Control.
1667          *
1668          * @brief       <i> [Deprecated] </i>
1669          * @deprecated  This API is deprecated.
1670          * @since 2.0
1671          *
1672          * @return              An error code
1673          * @param[in]   gestureDetector                                 The gesture detector
1674          * @exception   E_SUCCESS                       The method is successful.
1675          * @see                 RemoveGestureDetector()
1676          */
1677         result AddGestureDetector(const TouchGestureDetector& gestureDetector);
1678
1679         /**
1680          * Adds the gesture detector to the %Control. @n
1681          * The added gesture detector receives touch events prior to %Control.
1682          *
1683          * @since 2.1
1684          *
1685          * @return      An error code
1686          * @param[in]   pGestureDetector         Pointer of gesture detector
1687          * @exception   E_SUCCESS                The method is successful.
1688          * @exception   E_INVALID_ARG            The specified @c pGestureDetector is null.
1689          * @see           RemoveGestureDetector()
1690          */
1691         result AddGestureDetector(TouchGestureDetector* pGestureDetector);
1692
1693         /**
1694          * Removes the gesture detector from the %Control.
1695          *
1696          * @brief       <i> [Deprecated] </i>
1697          * @deprecated  This API is deprecated.
1698          * @since 2.0
1699          *
1700          * @return                      An error code
1701          * @param[in]           gestureDetector         The gesture detector
1702          * @exception   E_SUCCESS                       The method is successful.
1703          * @see                 AddGestureDetector()
1704          */
1705         result RemoveGestureDetector(const TouchGestureDetector& gestureDetector);
1706
1707         /**
1708          * Removes the gesture detector from the %Control.
1709          *
1710          * @since 2.1
1711          *
1712          * @return      An error code
1713          * @param[in]   pGestureDetector                Pointer of gesture detector
1714          * @exception   E_SUCCESS              The method is successful.
1715          * @exception   E_INVALID_ARG                   The specified @c pGestureDetector is null.
1716          * @see         AddGestureDetector()
1717          */
1718         result RemoveGestureDetector(TouchGestureDetector* pGestureDetector);
1719
1720         /**
1721          * @if OSPDEPREC
1722          * Gets the composite mode for merging with other controls.
1723          *
1724          * @brief <i> [Deprecated] </i>
1725          * @deprecated  This method is deprecated because changing composition mode is not allowed any more.
1726          * @since               2.0
1727          *
1728          * @return              The composite mode
1729          * @exception   E_SUCCESS                               The method is successful.
1730          * @remarks             Since API version 2.1, this method only returns COMPOSITE_MODE_ALPHA_BLENDING.
1731          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1732          * @endif
1733          */
1734         Tizen::Ui::CompositeMode GetCompositeMode(void) const;
1735
1736         /**
1737          * @if OSPDEPREC
1738          * Sets the composite mode for merging with other controls.
1739          *
1740          * @brief <i> [Deprecated] </i>
1741          * @deprecated  This method is deprecated because changing composition mode is not allowed any more.
1742          * @since               2.0
1743          *
1744          * @return              An error code
1745          * @param[in]   compositeMode                   The composite mode
1746          * @exception   E_SUCCESS                               The method is successful.
1747          * @exception   E_UNSUPPORTED_OPERATION The method is not supported.
1748          * @remarks     In Tizen, only @c COMPOSITE_MODE_ALPHA_BLENDING is allowed.
1749          *              Otherwise, this method returns @c E_UNSUPPORTED_OPERATION.
1750          * @endif
1751          */
1752         result SetCompositeMode(Tizen::Ui::CompositeMode compositeMode);
1753
1754         /**
1755          * @if OSPDEPREC
1756          * Gets the chroma key color value that is used for the control composition.
1757          *
1758          * @brief <i> [Deprecated]  </i>
1759          * @deprecated  This method is deprecated because chromakey color is not supported any more.
1760          * @since               2.0
1761          *
1762          * @return              The chroma key color
1763          * @exception   E_UNSUPPORTED_OPERATION The method is not supported.
1764          * @remarks     In Tizen, this method always fails and returns Tizen::Graphics::Color(0, 0, 0, 0).
1765          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1766          * @endif
1767          */
1768         Tizen::Graphics::Color GetChromaKeyColor(void) const;
1769
1770         /**
1771          * @if OSPDEPREC
1772          * Sets the chroma key color value that is used for the control composition.
1773          *
1774          * @brief <i> [Deprecated]  </i>
1775          * @deprecated  This method is deprecated because chromakey color is not supported any more.
1776          * @since               2.0
1777          *
1778          * @return              An error code
1779          * @param[in]   chromaKeyColor                  The chroma key color
1780          * @exception   E_UNSUPPORTED_OPERATION The method is not supported.
1781          * @remarks     In Tizen, this method always fails.
1782          * @endif
1783          */
1784         result SetChromaKeyColor(Tizen::Graphics::Color chromaKeyColor);
1785
1786         /**
1787          * Sets the bounds of the content area.
1788          *
1789          * @since                    2.1
1790          *
1791          * @param[in]    rect      The bounds of the content area
1792          * @see                      GetContentAreaBounds()
1793          */
1794         void SetContentAreaBounds(const Tizen::Graphics::Rectangle& rect);
1795
1796         /**
1797          * Sets the bounds of the content area.
1798          *
1799          * @since                    2.1
1800          *
1801          * @param[in]    rect      The bounds of the content area
1802          * @see                      GetContentAreaBoundsF()
1803          */
1804         void SetContentAreaBounds(const Tizen::Graphics::FloatRectangle& rect);
1805
1806         /**
1807          * Gets the bounds of the content area.
1808          *
1809          * @since                     2.1
1810          *
1811          * @return        The bounds of the content area
1812          * @see                      SetContentAreaBounds()
1813          */
1814         Tizen::Graphics::Rectangle GetContentAreaBounds(void) const;
1815
1816         /**
1817          * Gets the bounds of the content area.
1818          *
1819          * @since                     2.1
1820          *
1821          * @return        The bounds of the content area
1822          * @see                      SetContentAreaBoundsF()
1823          */
1824         Tizen::Graphics::FloatRectangle GetContentAreaBoundsF(void) const;
1825
1826         /**
1827          * Captures the composited scene of the %Panel control.
1828          *
1829          * @since               2.0
1830          *
1831          * @return              A Tizen::Graphics::Bitmap instance that captures the current composited scene of the Panel control, @n
1832          *                              else @c null if an error occurs
1833          * @exception   E_SUCCESS                                       The method is successful.
1834          * @exception   E_UNSUPPORTED_OPERATION         This method is not supported.
1835          * @exception   E_SYSTEM                                        A system error has occurred.
1836          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1837          * @remarks             This method is not supported in the following class that is derived from Panel class:
1838          *                              @li OverlayPanel
1839          * @remarks             The bounds of the %Panel control must be within the client area of the Form control to get a valid composited scene.
1840          */
1841         Tizen::Graphics::Bitmap* GetCapturedBitmapN(void) const;
1842
1843         /**
1844          * Gets the position and the size of the invalidated bounds.
1845          *
1846          * @since 2.0
1847          *
1848          * @return              An instance of Tizen::Graphics::Rectangle that represents the position of top-left corner,
1849          *                                        the width, and the height of the invalidated bounds
1850          */
1851         Tizen::Graphics::Rectangle GetInvalidatedBounds(void) const;
1852
1853         /**
1854          * Gets the position and the size of the invalidated bounds.
1855          *
1856          * @since 2.1
1857          *
1858          * @return              An instance of Tizen::Graphics::Rectangle that represents the position of top-left corner,
1859          *                                        the width, and the height of the invalidated bounds
1860          */
1861         Tizen::Graphics::FloatRectangle GetInvalidatedBoundsF(void) const;
1862
1863         /**
1864          * Enables or disables the multi-point touch of the %Control.
1865          *
1866          * @since 2.0
1867          *
1868          * @param[in]   enable                          A Boolean flag indicating whether to enable the multi-point touch
1869          *
1870          * @see                 IsMultipointTouchEnabled()
1871          */
1872          void SetMultipointTouchEnabled(bool enable);
1873
1874         /**
1875          * Checks whether the multi-point touch is enabled.
1876          *
1877          * @since 2.0
1878          *
1879          * @return              @c true if the multi-point touch is enabled, @n
1880          *                              else @c false
1881          * @see                 SetMultipointTouchEnabled()
1882          */
1883         bool IsMultipointTouchEnabled(void) const;
1884
1885         /**
1886          * Gets the accessibility container.
1887          *
1888          * @since 2.0
1889          *
1890          * @return              The accessibility container of the control, if the control supports accessibility feature, @n
1891          *                              else @c null
1892          * @see                 AccessibilityContainer::GetOwner()
1893          */
1894         const AccessibilityContainer* GetAccessibilityContainer(void) const;
1895
1896         /**
1897          * Gets the accessibility container.
1898          *
1899          * @since 2.0
1900          *
1901          * @return              The accessibility container of the control, if the control supports accessibility feature, @n
1902          *                              else @c null
1903          * @see                 AccessibilityContainer::GetOwner()
1904          */
1905         AccessibilityContainer* GetAccessibilityContainer(void);
1906
1907         /**
1908          * Sets a propagated touch event listener to the %Control instance. @n
1909          * The registered listener is notified when a touch event occurs in the control. Using the propagated touch event listener, an application can control the touch event routing path.
1910          *
1911          * @since                    2.1
1912          *
1913          * @param[in]    pListener                                     The event listener to which the propagated touch events are dispatched
1914          * @remarks The specified event listener should be allocated in heap memory.
1915          *          To unregister the event listener, pass @c null to @c pListener.
1916
1917          */
1918         void SetPropagatedTouchEventListener(IPropagatedTouchEventListener* pListener);
1919
1920         /**
1921          * Sets a propagated key event listener to the %Control instance.
1922          * The registered listener is notified when a key event occurs in the control. Using the propagated key event listener, an application can control the key event routing path.
1923          *
1924          * @since                    2.1
1925          *
1926          * @param[in]    pListener                                     The event listener to which the propagated touch events are dispatched
1927          * @remarks The specified event listener should be allocated in heap memory.
1928          *          To unregister the event listener, pass @c null to @c pListener.
1929
1930          */
1931         void SetPropagatedKeyEventListener(IPropagatedKeyEventListener* pListener);
1932
1933
1934         /**
1935          * Sets the previous focus of the control.
1936          *
1937          * @since 2.1
1938          *
1939          * @param[in]   pPreviousFocus  The pointer to the previous focus of the control
1940          * @remarks             Focus UI supports linear navigation of controls from top-left to bottom-right direction. This method allows for customizing the default navigation behavior.
1941          * @remarks             The platform will not take the ownership of @c pPreviousFocus after this call.
1942          * @see                 SetNextFocus()
1943          * @see                 GetPreviousFocus()
1944          */
1945         void SetPreviousFocus(Control* pPreviousFocus);
1946
1947         /**
1948          * Sets the next focus of the control.
1949          *
1950          * @since 2.1
1951          *
1952          * @param[in]   pNextFocus      The pointer to the next focus of the control
1953          * @remarks             Focus UI supports linear navigation of controls from top-left to bottom-right direction. This method allows for customizing the default navigation behavior.
1954          * @remarks             The platform will not take the ownership of @c pNextFocus after this call.
1955          * @see                 SetPreviousFocus()
1956          * @see                 GetNextFocus()
1957         */
1958         void SetNextFocus(Control* pNextFocus);
1959
1960         /**
1961          * Gets the previous focus of the control.
1962          *
1963          * @since 2.1
1964          *
1965          * @return              The pointer to the previous focus of the control, @n
1966          *                              else  @c null if the previous focus of the control is not set
1967          * @see         GetNextFocus()
1968          * @see         SetNextFocus ()
1969         */
1970         Control* GetPreviousFocus(void) const;
1971
1972
1973         /**
1974          * Gets the next focus of the control.
1975          *
1976          * @since 2.1
1977          *
1978          * @return              The pointer to the next focus of the control, @n
1979          *                              else @c null if the next focus of the control is not set
1980          * @see         GetPreviousFocus()
1981          * @see         SetPreviousFocus ()
1982         */
1983         Control* GetNextFocus(void) const;
1984
1985         /**
1986          * Sets the touch press threshold of the Control in inch.
1987          *
1988          * @since               2.1
1989          *
1990          * @param[in]   distance        The logical threshold to fire touch move event
1991          * @remark              A touch move events will start to fire if the move distance exceeds the set allowance value.
1992          * For example, Set 0.5 if the distance is 0.5 inch.
1993          * This method is offered to control sensitivity of move events.
1994         */
1995         void SetTouchPressThreshold(float distance);
1996
1997         /**
1998          * Gets the touch press threshold of the Control in inch.
1999          * If the threshold has not been set, it returns the default value.
2000          *
2001          * @since                    2.1
2002          *
2003          * @return    The threshold to fire touch move event
2004          */
2005         float GetTouchPressThreshold(void) const;
2006
2007
2008         /**
2009          * Sets the font of the control with the specified file name.
2010          *
2011          * @since 2.1
2012          *
2013          * @return                      An error code
2014          * @param[in]           fileName                                        The file name of a font-resource located in @b ‘/res/font’, @n
2015          *                                                                                              else an empty string to reset
2016          * @exception           E_SUCCESS                                       The method is successful.
2017          * @exception           E_FILE_NOT_FOUND                        The specified font cannot be found or accessed.
2018          * @exception           E_UNSUPPORTED_FORMAT            The specified font format is not supported.
2019          * @see                 GetFontFile()
2020         */
2021         result SetFontFromFile(const Tizen::Base::String& fileName);
2022
2023         /**
2024          * Gets a font file name of the control.
2025          *
2026          * @since 2.1
2027          *
2028          * @return                              The font name set in the control, @n
2029          *                                              else an empty string if the font is not set
2030          * @see                         SetFontFromFile()
2031         */
2032         Tizen::Base::String GetFontFile(void) const;
2033
2034 protected:
2035         /**
2036          * Gets the default key event listener.
2037          *
2038          * @brief <i> [Deprecated] </i>
2039          * @deprecated  This method is deprecated.
2040          * @since               2.0
2041          *
2042          * @return              The default key event listener @n
2043          *                              If no listener has been set or a system error has occurred @c null is returned.
2044          * @see                 SetDefaultKeyEventListener()
2045          */
2046         IKeyEventListener* GetDefaultkeyEventListener(void) const;
2047
2048         /**
2049          * Gets the default touch event listener.
2050          *
2051          * @brief <i> [Deprecated] </i>
2052          * @deprecated   This method is deprecated.
2053          * @since               2.0
2054          *
2055          * @return             The default touch event listener @n
2056          *                                 If no listener has been set or a system error has occurred @c null is returned.
2057          * @see                         SetDefaultTouchEventListener()
2058          */
2059         ITouchEventListener* GetDefaultTouchEventListener(void) const;
2060
2061         /**
2062          * Sets the default key event listener.
2063          *
2064          * @brief <i> [Deprecated] </i>
2065          * @deprecated   This method is deprecated. Instead of using this method, use the SetPropagatedKeyEventListener() method.
2066          * @since               2.0
2067          *
2068          * @return             An error code
2069          * @param[in] pDefaultListener               The default key event listener
2070          * @exception         E_SUCCESS                               The method is successful.
2071          * @exception         E_SYSTEM                                A system error has occurred.
2072          * @remarks           The registered listener will be notified to handle the key events
2073          *                                 after all application event listeners has been notified.
2074          * @see                         GetDefaultkeyEventListener()
2075          */
2076         result SetDefaultKeyEventListener(IKeyEventListener* pDefaultListener);
2077
2078         /**
2079          * Sets the default touch event listener.
2080          *
2081          * @brief <i> [Deprecated] </i>
2082          * @deprecated   This method is deprecated. Instead of using this method, use the SetPropagatedTouchEventListener() method.
2083          * @since               2.0
2084          *
2085          * @return             An error code
2086          * @param[in] pDefaultListener               The default key event listener
2087          * @exception         E_SUCCESS                               The method is successful.
2088          * @exception         E_SYSTEM                                A system error has occurred.
2089          * @remarks           The registered listener will be notified to handle the touch events
2090          *                                 after all application event listeners has been notified.
2091          * @see                         GetDefaultTouchEventListener()
2092          */
2093         result SetDefaultTouchEventListener(ITouchEventListener* pDefaultListener);
2094
2095         /**
2096          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
2097          *
2098          * @since       2.0
2099          */
2100         Control(void);
2101
2102         /**
2103          * This method is for internal use only. Using this method can cause behavioral, security-related,
2104          * and consistency-related issues in the application.
2105          *
2106          * Initializes this instance of %Control.
2107          *
2108          * @since               2.0
2109          * @return              An error code
2110          * @exception   E_SUCCESS                       The method is successful.
2111          * @exception   E_SYSTEM                        A system error has occurred.
2112          */
2113         result Construct(void);
2114
2115         /**
2116          * Frees the resources allocated by Construct().
2117          *
2118          * @since 2.0
2119          */
2120         void Dispose(void);
2121
2122 protected:
2123         _ControlImpl* _pControlImpl;
2124
2125         //
2126         // This method is for internal use only. Using this method can cause behavioral, security-related,
2127         // and consistency-related issues in the application.
2128         //
2129         // This method is reserved and may change its name at any time without prior notice.
2130         //
2131         virtual void Control_Reserved1(void) {}
2132
2133         //
2134         // This method is for internal use only. Using this method can cause behavioral, security-related,
2135         // and consistency-related issues in the application.
2136         //
2137         // This method is reserved and may change its name at any time without prior notice.
2138         //
2139         virtual void Control_Reserved2(void) {}
2140
2141         //
2142         // This method is for internal use only. Using this method can cause behavioral, security-related,
2143         // and consistency-related issues in the application.
2144         //
2145         // This method is reserved and may change its name at any time without prior notice.
2146         //
2147         virtual void Control_Reserved3(void) {}
2148
2149         //
2150         // This method is for internal use only. Using this method can cause behavioral, security-related,
2151         // and consistency-related issues in the application.
2152         //
2153         // This method is reserved and may change its name at any time without prior notice.
2154         //
2155         virtual void Control_Reserved4(void) {}
2156
2157         //
2158         // This method is for internal use only. Using this method can cause behavioral, security-related,
2159         // and consistency-related issues in the application.
2160         //
2161         // This method is reserved and may change its name at any time without prior notice.
2162         //
2163
2164         virtual void Control_Reserved5(void) {}
2165
2166         //
2167         // This method is for internal use only. Using this method can cause behavioral, security-related,
2168         // and consistency-related issues in the application.
2169         //
2170         // This method is reserved and may change its name at any time without prior notice.
2171         //
2172         virtual void Control_Reserved6(void) {}
2173
2174 private:
2175         //
2176         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
2177         //
2178         Control(const Control& rhs);
2179
2180         //
2181         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
2182         //
2183         Control& operator =(const Control& rhs);
2184
2185 private:
2186         friend class _ControlImpl;
2187 }; // Control
2188
2189 }} // Tizen::Ui
2190
2191 #endif // _FUI_CONTROL_H_