inc/FUiCtrlForm.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an ”AS IS” BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FUiCtrlForm.h
  20  * @brief       This is the header file for the %Form class.
  21  *
  22  * This header file contains the declarations of the %Form class.
  23  */
  24 #ifndef _FUI_CTRL_FORM_H_
  25 #define _FUI_CTRL_FORM_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FBaseString.h>
  29 #include <FBaseColLinkedListT.h>
  30 #include <FUiIActionEventListener.h>
  31 #include <FUiContainer.h>
  32 #include <FUiIOrientationEventListener.h>
  33 #include <FUiCtrlControlsTypes.h>
  34 #include <FUiCtrlOverlayRegion.h>
  35
  36 namespace Tizen { namespace Ui
  37 {
  38 class DataBindingContext;
  39 }  } // Tizen::Ui
  40
  41 namespace Tizen { namespace Ui { namespace Controls
  42 {
  43 class Header;
  44 class Footer;
  45 class Tab;
  46 class IFormBackEventListener;
  47
  48 /**
  49  * @enum FormStyle
  50  *
  51  * Defines the %Form control style.
  52  *
  53  * @since               2.0
  54  */
  55 enum FormStyle
  56 {
  57         FORM_STYLE_NORMAL = 0x00000000,     /**< The basic form style */
  58         FORM_STYLE_TITLE = 0x00000001,      /**<@if OSPDEPREC @deprecated This enum value is deprecated because the use of the Title control is no longer recommended.@endif */
  59         FORM_STYLE_INDICATOR = 0x00000002,  /**< The form with the indicator area */
  60         FORM_STYLE_SOFTKEY_0 = 0x00000010,  /**<@if OSPDEPREC @deprecated This enum value is deprecated because the use of the Softkey control is no longer recommended.@endif */
  61         FORM_STYLE_SOFTKEY_1 = 0x00000020,  /**<@if OSPDEPREC @deprecated This enum value is deprecated because the use of the Softkey control is no longer recommended.@endif */
  62         FORM_STYLE_OPTIONKEY = 0x00000040,  /**<@if OSPDEPREC @deprecated This enum value is deprecated because the use of the Optionkey control is no longer recommended.@endif */
  63         FORM_STYLE_TEXT_TAB = 0x00000100,   /**<@if OSPDEPREC @deprecated This enum value is deprecated because the use of the Tab control is no longer recommended. @endif */
  64         FORM_STYLE_ICON_TAB = 0x00000200,   /**<@if OSPDEPREC @deprecated This enum value is deprecated because the use of the Tab control is no longer recommended. @endif */
  65         FORM_STYLE_HEADER = 0x00001000,     /**< The form with a header */
  66         FORM_STYLE_FOOTER = 0x00002000,      /**< The form with a footer */
  67         FORM_STYLE_INDICATOR_AUTO_HIDE = 0x00010000   /**< The form with a indicator which is hidden. @b Since: @b 2.1 */
  68 };
  69
  70
  71 /**
  72  * @if OSPDEPREC
  73  * @enum Softkey
  74  *
  75  * Defines the softkey.
  76  *
  77  * @brief <i> [Deprecated]  </i>
  78  * @deprecated This enum type is deprecated because the use of the Softkey control is no longer recommended.
  79  * @since               2.0
  80  * @endif
  81  */
  82 enum Softkey
  83 {
  84         SOFTKEY_0,      /**< @if OSPDEPREC The left softkey @endif */
  85         SOFTKEY_1,      /**< @if OSPDEPREC The right softkey @endif */
  86         SOFTKEY_COUNT   // This enum value is for internal use only. Using this enum value can cause behavioral, security-related, and consistency-related issues in the application.
  87 };
  88
  89
  90 /**
  91  * @enum FormActionBar
  92  *
  93  * Defines the action bars that can be attached to the %Form control.
  94  *
  95  * @since   2.0
  96  */
  97 enum FormActionBar
  98 {
  99         FORM_ACTION_BAR_INDICATOR = 0x0001, /**< The indicator */
 100         FORM_ACTION_BAR_HEADER = 0x0002,    /**< The header */
 101         FORM_ACTION_BAR_FOOTER = 0x0004,     /**< The footer */
 102         FORM_ACTION_BAR_TAB = 0x0008     /**< The tab */                        // Ki-Dong,Hong.Temp
 103 };
 104
 105
 106 /**
 107  * @class       Form
 108  * @brief       This class provides a container with general controls.
 109  *
 110  * @since       2.0
 111  *
 112  * The %Form class displays a full screen container. It can contain user-created controls and system UI components, such
 113  * as an indicator area, header, and footer. The application can have multiple forms that are all added to a single Frame.
 114  *
 115  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_form.htm">Form</a>.
 116  *
 117  * The following example demonstrates how to use the %Form class.
 118  *
 119  * @code
 120         // Creates an instance of Form
 121         Form* pForm = new Form();
 122         pForm->Construct(FORM_STYLE_NORMAL| FORM_STYLE_HEADER| FORM_STYLE_FOOTER);
 123
 124         // Gets a pointer of the frame
 125         Frame *pFrame = UiApp::GetInstance()->GetAppFrame()->GetFrame();
 126         pFrame->AddControl(*pForm);
 127         pFrame->SetCurrentForm(*pForm);
 128
 129         // Implements MyActionEventListener
 130         IActionEventListener* pListener = new MyActionEventListener();
 131
 132         // Adds a header
 133         Header * pHeader = GetHeader();
 134         pHeader->SetTitleText(L"FormSample");
 135
 136         // Adds a footer
 137         Footer * pFooter = GetFooter();
 138         pFooter->SetStyle(FOOTER_STYLE_TAB);
 139         pFooter->AddActionEventListener(*this);
 140
 141         // Calls Invalidate() to display the form
 142         pForm->Invalidate(true)
 143  * @endcode
 144  *
 145  * This is a simple UI application that uses a %Form.
 146  *@image html ui_controls_form.png
 147  *
 148  */
 149 class _OSP_EXPORT_ Form
 150         : public Tizen::Ui::Container
 151 {
 152 public:
 153 // Lifecycle
 154         /**
 155          * This is the default constructor for this class.
 156          * @since   2.0
 157          */
 158         Form(void);
 159
 160         /**
 161          *      This is the destructor for this class.
 162          * @since   2.0
 163          */
 164         virtual ~Form(void);
 165
 166         /**
 167          * Initializes this instance of %Form with the specified parameters.
 168          *
 169          * @since       2.0
 170          *
 171          * @return      An error code
 172          * @param[in]   formStyle           The form style @n
 173          *                                                                      Multiple form styles can be combined using bitwise OR.
 174          * @exception   E_SUCCESS           The method is successful.
 175          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 176          *                                                                      - ::FORM_STYLE_HEADER and ::FORM_STYLE_TITLE are specified at the same time.
 177          *                                                                      - ::FORM_STYLE_FOOTER and ::FORM_STYLE_SOFTKEY_0 are specified at the same time.
 178          *                                                                      - @c FORM_STYLE_FOOTER and ::FORM_STYLE_SOFTKEY_1 are specified at the same time.
 179          *                                                                      - @c FORM_STYLE_FOOTER and ::FORM_STYLE_OPTIONKEY are specified at the same time.
 180          * @exception   E_MAX_EXCEEDED      The total number of Frames and Forms exceeds the system limitation.
 181          * @exception   E_SYSTEM            A system error has occurred.
 182          * @remarks     The maximum number of Forms that an application can construct is limited by available memory.
 183          * @see         FormStyle
 184          */
 185         result Construct(unsigned long formStyle);
 186
 187
 188         /**
 189          * Initializes this instance of %Form with the specified resource ID. @n
 190          * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. If it fails to find the
 191          * appropriate resource file, the method tries searching in other folders. When AutoScaling is enabled, the method first searches the folder that
 192          * corresponds to the current screen size category and then searches the "res/screen-size-normal/" folder.
 193          *
 194          * @since      2.0
 195          *
 196          * @return     An error code
 197          * @param[in]  resourceId              The resource ID describing the %Form control
 198          * @exception  E_SUCCESS               The method is successful.
 199          * @exception  E_FILE_NOT_FOUND        The specified file cannot be found.
 200          * @exception  E_INVALID_FORMAT        The specified XML format is invalid.
 201          * @exception  E_OPERATION_FAILED      The operation has failed.
 202          */
 203         result Construct(const Tizen::Base::String& resourceId);
 204
 205         /**
 206          * Initializes this instance of %Form with the form style and layout.
 207          *
 208          * @since               2.0
 209          *
 210          * @return      An error code
 211          * @param[in]   layout                          The layout for both the portrait and landscape mode
 212          * @param[in]   formStyle           The form style @n
 213          *                                                                      Multiple form styles can be combined using bitwise OR.
 214          * @exception   E_SUCCESS           The method is successful.
 215          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or
 216          *                                                                      the specified layout is already bound to another container.
 217          * @exception   E_MAX_EXCEEDED      The total number of Frames and Forms exceeds the system limitation.
 218          * @exception   E_SYSTEM            A system error has occurred.
 219          * @remarks
 220          *                      - The maximum number of Forms that an application can construct is limited by available memory.
 221          *                      - The children are arranged within the client area bounds of the form area by @c layout.
 222          * @see         FormStyle
 223          */
 224         result Construct(const Tizen::Ui::Layout& layout, unsigned long formStyle);
 225
 226         /**
 227          * Initializes this instance of %Form with the specified parameters.
 228          *
 229          * @since               2.0
 230          *
 231          * @return      An error code
 232          * @param[in]   portraitLayout          The layout for the portrait mode
 233          * @param[in]   landscapeLayout         The layout for the landscape mode
 234          * @param[in]   formStyle           The form style @n
 235          *                                                                      Multiple form styles can be combined using bitwise OR.
 236          * @exception   E_SUCCESS           The method is successful.
 237          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or
 238          *                                                                      the specified layout is already bound to another container.
 239          * @exception   E_MAX_EXCEEDED      The total number of Frames and Forms exceeds the system limitation.
 240          * @exception   E_SYSTEM            A system error has occurred.
 241          * @remarks
 242          *                      - The maximum number of Forms that an application can construct is limited by available memory.
 243          *                      - The children are arranged within the bounds of the form area by @c layout.
 244          * @see         FormStyle
 245          */
 246         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, unsigned long formStyle);
 247
 248 // Operation
 249
 250         /**
 251          * Adds an IOrientationEventListener instance. @n
 252          * The added listener can listen to the orientation changed events that are fired when the orientation mode of the screen is changed.
 253          *
 254      * @since   2.0
 255          *
 256          * @param[in]   listener        The listener to add
 257          * @remarks         The %Form control can only listen to those changes to the orientation mode that are enabled by calling SetOrientation().
 258          * @see                 RemoveOrientationEventListener()
 259          */
 260         void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 261
 262
 263         /**
 264          * @if OSPDEPREC
 265          * Adds an IActionEventListener instance. @n
 266          * The added listener can listen to the action events that are fired when an option key is selected.
 267          *
 268          * @brief <i> [Deprecated]  </i>
 269          * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
 270      * @since   2.0
 271          *
 272          * @param[in]   listener        The listener to add
 273          * @see                 RemoveOptionkeyActionListener()
 274          * @endif
 275          */
 276         void AddOptionkeyActionListener(Tizen::Ui::IActionEventListener& listener);
 277
 278
 279         /**
 280          * @if OSPDEPREC
 281          * Adds an IActionEventListener instance. @n
 282          * The added listener can listen to the action events that are fired when a softkey is selected.
 283          *
 284          * @brief <i> [Deprecated]  </i>
 285          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 286          * @since   2.0
 287          *
 288          * @param[in]   softkey         The style of the softkey
 289          * @param[in]   listener        The listener to add
 290          * @see                 RemoveSoftkeyActionListener()
 291          * @endif
 292          */
 293         void AddSoftkeyActionListener(Softkey softkey, Tizen::Ui::IActionEventListener& listener);
 294
 295
 296         /**
 297          * @if OSPDEPREC
 298          * Removes an IActionEventListener instance. @n
 299          * The removed listener cannot listen to the events when they are fired.
 300          *
 301          * @brief <i> [Deprecated]  </i>
 302          * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
 303          * @since       2.0
 304          *
 305          * @param[in]   listener        The listener to remove
 306          * @see                 AddOptionkeyActionListener()
 307          * @endif
 308          */
 309         void RemoveOptionkeyActionListener(Tizen::Ui::IActionEventListener& listener);
 310
 311
 312         /**
 313          * Removes an IOrientationEventListener instance. @n
 314          * The removed listener cannot listen to the events when they are fired.
 315          *
 316          * @since   2.0
 317          *
 318          * @param[in]   listener        The listener to remove
 319          *
 320          * @see                 AddOrientationEventListener()
 321          */
 322         void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 323
 324
 325         /**
 326          * @if OSPDEPREC
 327          * Removes an IActionEventListener instance. @n
 328          * The removed listener cannot listen to the events when they are fired.
 329          *
 330          * @brief <i> [Deprecated]  </i>
 331          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 332          * @since   2.0
 333          *
 334          * @param[in]   softkey         The style of the softkey
 335          * @param[in]   listener        The listener to remove
 336          * @see                 AddSoftkeyActionListener()
 337          * @endif
 338          */
 339         void RemoveSoftkeyActionListener(Softkey softkey, Tizen::Ui::IActionEventListener& listener);
 340
 341
 342 // Accessor
 343         /**
 344          * Gets the background color of the %Form control.
 345          *
 346          * @since   2.0
 347          *
 348          * @return      The background color of the %Form control
 349          */
 350         Tizen::Graphics::Color GetBackgroundColor(void) const;
 351
 352
 353         /**
 354          * Gets the bounds of the client area.
 355          *
 356          * @since   2.0
 357          *
 358          * @return      The bounds of the client area
 359          * @remarks     The client area of the %Form control does not include the title, indicator, header and footer areas.
 360          *                      header and footer areas.
 361          *
 362          */
 363         Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
 364
 365         /**
 366          * Gets the bounds of the client area.
 367          *
 368          * @since   2.1
 369          *
 370          * @return      The bounds of the client area
 371          * @remarks     The client area of the %Form control does not include the title, indicator, header and footer areas.
 372          *                      header and footer areas.
 373          *
 374          */
 375         Tizen::Graphics::FloatRectangle GetClientAreaBoundsF(void) const;
 376
 377         /**
 378          * Gets the style of the %Form control.
 379          *
 380          * @since   2.0
 381          *
 382          * @return      An @c unsigned @c long value representing the style of the %Form control
 383          */
 384         unsigned long GetFormStyle(void) const;
 385
 386
 387         /**
 388          * Gets the orientation mode of the %Form control.
 389          *
 390          * @since   2.0
 391          *
 392          * @return      The orientation of the %Form control
 393          */
 394         Tizen::Ui::Orientation GetOrientation(void) const;
 395
 396
 397         /**
 398          * Gets the current orientation status of the %Form control.
 399          *
 400      * @since   2.0
 401          *
 402          * @return      The orientation status of the %Form control, @n
 403          *                      else @c ORIENTATION_NONE if the %Form control is not the current form of the Frame control
 404          */
 405         Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
 406
 407
 408         /**
 409          * @if OSPDEPREC
 410          * Gets the action ID of the specified softkey.
 411          *
 412          * @brief <i> [Deprecated]  </i>
 413          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 414          * @since       2.0
 415          *
 416          * @return              An integer value representing the action ID
 417          * @param[in]   softkey                 The softkey
 418          * @endif
 419          */
 420         int GetSoftkeyActionId(Softkey softkey) const;
 421
 422
 423         /**
 424          * @if OSPDEPREC
 425          * Gets the text of the specified softkey.
 426          *
 427          * @brief <i> [Deprecated]  </i>
 428          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 429          * @since       2.0
 430          *
 431          * @return              The text of the softkey
 432          * @param[in]   softkey                 The softkey
 433          * @endif
 434          */
 435         Tizen::Base::String GetSoftkeyText(Softkey softkey) const;
 436
 437
 438         /**
 439          * @if OSPDEPREC
 440          * Gets the pointer of the Tab control if it exists.
 441          *
 442          * @brief <i> [Deprecated]  </i>
 443          * @deprecated This method is deprecated because the use of the Tab control is no longer recommended.
 444      * @since           2.0
 445          *
 446          * @return              A pointer to the Tab control, @n
 447          *                              else @c null if there is no tab
 448          * @remarks             The retrieved pointer may be temporary. Therefore, it should not be stored after immediate use.
 449          * @endif
 450          */
 451         Tab* GetTab(void) const;
 452
 453
 454         /**
 455          * @if OSPDEPREC
 456          * Gets the title of the %Form control.
 457          *
 458          * @brief <i> [Deprecated]  </i>
 459          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 460          *                              use the Header control.
 461      * @since   2.0
 462          *
 463          * @return              The title of the %Form control
 464          * @endif
 465          */
 466         Tizen::Base::String GetTitleText(void) const;
 467
 468
 469         /**
 470          * @if OSPDEPREC
 471          * Gets the horizontal alignment of the title text.
 472          *
 473          * @brief <i> [Deprecated]  </i>
 474          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 475          *                              use the Header control.
 476      * @since   2.0
 477          *
 478          * @return  The horizontal alignment of the title text
 479          * @remarks             By default, the horizontal alignment is center aligned.
 480          * @endif
 481          */
 482         HorizontalAlignment GetTitleTextHorizontalAlignment(void) const;
 483
 484         /**
 485          * Checks whether the %Form control has an Indicator.
 486          *
 487          * @since   2.0
 488          *
 489          * @return      @c true if the %Form control has a title, @n
 490          *                      else @c false
 491          */
 492         bool HasIndicator(void) const;
 493
 494
 495         /**
 496          * @if OSPDEPREC
 497          * Checks whether the %Form control has an optionkey.
 498          *
 499          * @brief <i> [Deprecated]  </i>
 500          * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
 501      * @since   2.0
 502          *
 503          * @return              @c true if the %Form control has an optionkey, @n
 504          *                              else @c false
 505          * @endif
 506          */
 507         bool HasOptionkey(void) const;
 508
 509
 510         /**
 511          * @if OSPDEPREC
 512          * Checks whether the %Form control has the specified softkey.
 513          *
 514          * @brief <i> [Deprecated]  </i>
 515          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 516          * @since   2.0
 517          *
 518          * @return              @c true if the %Form control has the specified softkey, @n
 519          *                              else @c false
 520          * @param[in]   softkey                 The required softkey
 521          * @endif
 522          */
 523         bool HasSoftkey(Softkey softkey) const;
 524
 525
 526         /**
 527          * @if OSPDEPREC
 528          * Checks whether the %Form control has a tab.
 529          *
 530          * @brief <i> [Deprecated]  </i>
 531          * @deprecated This method is deprecated because the use of the Tab control is no longer recommended.
 532      * @since   2.0
 533          *
 534          * @return      @c true if the %Form control has a tab, @n
 535          *                      else @c false
 536          * @endif
 537          */
 538         bool HasTab(void) const;
 539
 540
 541         /**
 542          * @if OSPDEPREC
 543          * Checks whether the %Form control has a title.
 544          *
 545          * @brief <i> [Deprecated]  </i>
 546          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 547          *                              use the Header control.
 548      * @since   2.0
 549          *
 550          * @return              @c true if the %Form control has a title, @n
 551          *                              else @c false
 552          * @endif
 553          */
 554         bool HasTitle(void) const;
 555
 556
 557         /**
 558          * @if OSPDEPREC
 559          * Checks whether the softkey is enabled.
 560          *
 561          * @brief <i> [Deprecated]  </i>
 562          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 563          * @since   2.0
 564          *
 565          * @return              @c true if the softkey is enabled, @n
 566          *                              else @c false
 567          * @param[in]   softkey                 The softkey
 568          * @endif
 569          */
 570         bool IsSoftkeyEnabled(Softkey softkey) const;
 571
 572
 573         /**
 574          * Sets the background color of the %Form control.
 575          *
 576          * @since   2.0
 577          *
 578          * @param[in]   color   The background color to set
 579          */
 580         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 581
 582
 583         /**
 584          * Sets the style of the %Form control.
 585          *
 586          * @since       2.0
 587          *
 588          * @param[in]   formStyle               The form style to set @n
 589          *                                                              This parameter can be a combination of Tizen::Ui::Controls::FormStyle.
 590          * @exception   E_SUCCESS               The method is successful @if OSPCOMPAT @b Since: @b 2.0 @endif.
 591          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 592          *                                                              - ::FORM_STYLE_HEADER and ::FORM_STYLE_TITLE are specified at the same time.
 593          *                                                              - ::FORM_STYLE_FOOTER and ::FORM_STYLE_SOFTKEY_0 are specified at the same time.
 594          *                                                              - @c FORM_STYLE_FOOTER and ::FORM_STYLE_SOFTKEY_1 are specified at the same time.
 595          *                                                              - @c FORM_STYLE_FOOTER and ::FORM_STYLE_OPTIONKEY are specified at the same time.
 596          * @remarks
 597          *                              - The specific error code can be accessed using the GetLastResult() method.
 598          *                              - Note that you must not change the style of %Form control that is constructed with ::FORM_STYLE_TEXT_TAB
 599          *                              or ::FORM_STYLE_ICON_TAB style.
 600          *                              - A Form which is added to a container except Frame cannot have the style of ::FORM_STYLE_INDICATOR.
 601          */
 602         void SetFormStyle(unsigned long formStyle);
 603
 604
 605         /**
 606          * @if OSPDEPREC
 607          * Sets an action ID of the optionkey.
 608          *
 609          * @brief <i> [Deprecated]  </i>
 610          * @deprecated This method is deprecated because the use of the Optionkey control is no longer recommended.
 611          * @since   2.0
 612          *
 613          * @param[in]   actionId                The action ID of this button instance
 614          * @endif
 615          */
 616         void SetOptionkeyActionId(int actionId);
 617
 618
 619         /**
 620          * Sets the orientation of the %Form control.
 621          *
 622          * @since   2.0
 623          *
 624          * @feature %http://tizen.org/setting/screen.auto_rotation for the @c ORIENTATION_AUTOMATIC_FOUR_DIRECTION or
 625          *                      @c ORIENTATION_AUTOMATIC value of @c orientation
 626          * @param[in]  orientation                                  The orientation of the %Form control
 627          * @exception  E_UNSUPPORTED_OPERATION               The Emulator or target device does not support the required feature. @b Since: @b 2.1 @n
 628          * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 629          * @remarks
 630          *                              - The specific error code can be accessed using the GetLastResult() method.
 631          *                              - Before calling this method, check whether the feature is supported by
 632          *                              Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 633          */
 634         void SetOrientation(Orientation orientation);
 635
 636
 637         /**
 638          * @if OSPDEPREC
 639          * Sets an action ID of each softkey.
 640          *
 641          * @brief <i> [Deprecated]  </i>
 642          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 643          * @since   2.0
 644          *
 645          * @param[in]   softkey                 The softkey
 646          * @param[in]   actionId                The action ID to set
 647          * @endif
 648          */
 649         void SetSoftkeyActionId(Softkey softkey, int actionId);
 650
 651
 652         /**
 653          * @if OSPDEPREC
 654          * Enables or disables the specified softkey.
 655          *
 656          * @brief <i> [Deprecated]  </i>
 657          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 658          * @since   2.0
 659          *
 660          * @param[in]   softkey                 The softkey
 661          * @param[in]   enable                  Set to @c true to enable this softkey @n
 662          *                                                      else @c false
 663          * @endif
 664          */
 665         void SetSoftkeyEnabled(Softkey softkey, bool enable);
 666
 667
 668         /**
 669          * @if OSPDEPREC
 670          * Sets the title icon of the %Form control.
 671          *
 672          * @brief <i> [Deprecated]  </i>
 673          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 674          *                              use the %Header control.
 675          * @since           2.0
 676          *
 677          * @return                      An error code
 678          * @param[in]           pTitleBitmap                    The title icon to set, @n
 679          *                                                                                      else @c null if the title icon is removed
 680          * @exception           E_SUCCESS                       The method is successful.
 681          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of a specified operation
 682          *                                                                                      (that is, this control cannot be displayed).
 683          * @exception           E_SYSTEM                        A system error has occurred.
 684          * @endif
 685          */
 686         result SetTitleIcon(const Tizen::Graphics::Bitmap* pTitleBitmap);
 687
 688
 689         /**
 690          * @if OSPDEPREC
 691          * Sets the title of this %Form control.
 692          *
 693          * @brief <i> [Deprecated]  </i>
 694          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 695          *                              use the Header control.
 696      * @since   2.0
 697          *
 698          * @return              An error code
 699          * @param[in]   title                           The title to set
 700          * @param[in]   alignment                   The horizontal alignment
 701          * @exception   E_SUCCESS                       The method is successful.
 702          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of a specified operation
 703          *                                                                      (that is, this control cannot be displayed).
 704          * @exception   E_SYSTEM                        A system error has occurred.
 705          * @remarks
 706          *                              - If the size of the text exceeds the displayable area, the text slides automatically.
 707          *                              - Note that when the title icon is set along with the title text, the title retains the left alignment.
 708          * @endif
 709          */
 710         result SetTitleText(const Tizen::Base::String& title, HorizontalAlignment alignment = ALIGNMENT_CENTER);
 711
 712
 713         /**
 714          * @if OSPDEPREC
 715          * Sets the icon of the softkey.
 716          *
 717          * @brief <i> [Deprecated]  </i>
 718          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 719      * @since   2.0
 720          *
 721          * @param[in]   softkey             The softkey
 722          * @param[in]   normalBitmap    The Bitmap of the normal icon
 723          * @param[in]   pPressedBitmap  The Bitmap of the pressed icon
 724          * @remarks             If both the icon and text are set for a softkey at the same time, the text takes precedence over the icon.
 725          * @endif
 726          */
 727         void SetSoftkeyIcon(Softkey softkey, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap);
 728
 729         /**
 730          * @if OSPDEPREC
 731          * Sets the text of the specified softkey.
 732          *
 733          * @brief <i> [Deprecated]  </i>
 734          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 735          * @since   2.0
 736          *
 737          * @param[in]   softkey The softkey
 738          * @param[in]   text            The text to set
 739          * @remarks
 740          *                              - If both the icon and text are set for a softkey at the same time, the text takes precedence over the icon.
 741          *                              - To display text in multi-lines or to denote the end of line, use '\\n'.
 742          * @endif
 743          */
 744         void SetSoftkeyText(Softkey softkey, const Tizen::Base::String& text);
 745
 746         /**
 747          * Gets the pointer to the Footer control if it exists.
 748          *
 749          * @since               2.0
 750          *
 751          * @return              A pointer to the Footer control, @n
 752          *                              else @c null if there is no %Footer
 753          * @remarks             The retrieved pointer may be temporary. Therefore, it should not be stored after immediate use. @n
 754          *                              The optimal size of the control is defined in
 755          *                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 756          */
 757         Footer* GetFooter(void) const;
 758
 759
 760         /**
 761          * Gets the pointer to the Header control if it exists.
 762          *
 763          * @since               2.0
 764          *
 765          * @return              A pointer to the Header control, @n
 766          *                              else @c null if there is no %Header
 767          * @remarks             The retrieved pointer may be temporary. Therefore, it should not be
 768          *              stored after immediate use. @n
 769          *                              The optimal size of the control is defined in
 770          *                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 771          */
 772         Header* GetHeader(void) const;
 773
 774
 775         /**
 776          * Checks whether the %Form control has a Footer.
 777          *
 778          * @since               2.0
 779          *
 780          * @return              @c true if the %Form control has a Footer, @n
 781          *                              else @c false
 782          */
 783         bool HasFooter(void) const;
 784
 785
 786         /**
 787          * Checks whether the %Form control has a Header.
 788          *
 789          * @since               2.0
 790          *
 791          * @return              @c true if the %Form control has a Header, @n
 792          *                              else @c false
 793          */
 794         bool HasHeader(void) const;
 795
 796
 797         /**
 798          * Checks whether the Indicator control is visible.
 799          *
 800          * @since               2.0
 801          *
 802          * @return              @c true if the Indicator control is visible, @n
 803          *                              else @c false
 804          */
 805         bool IsIndicatorVisible(void) const;
 806
 807
 808         /**
 809          * Checks whether the Header control is visible.
 810          *
 811          * @since               2.0
 812          *
 813          * @return              @c true if the Header control is visible, @n
 814          *                              else @c false
 815          */
 816         bool IsHeaderVisible(void) const;
 817
 818
 819         /**
 820          * Checks whether the Footer control is visible.
 821          *
 822          * @since               2.0
 823          *
 824          * @return              @c true if the Footer control is visible, @n
 825          *                              else @c false
 826          */
 827         bool IsFooterVisible(void) const;
 828
 829
 830         /**
 831          * Checks whether the Indicator control is translucent.
 832          *
 833          * @since               2.0
 834          *
 835          * @return              @c true if the Indicator control is translucent, @n
 836          *                              else @c false
 837          */
 838         bool IsIndicatorTranslucent(void) const;
 839
 840
 841         /**
 842          * Checks whether the Header control is translucent.
 843          *
 844          * @since               2.0
 845          *
 846          * @return              @c true if the Header control is translucent, @n
 847          *                              else @c false
 848          */
 849         bool IsHeaderTranslucent(void) const;
 850
 851
 852         /**
 853          * Checks whether the Footer control is translucent.
 854          *
 855          * @since               2.0
 856          *
 857          * @return              @c true if the Footer control is translucent, @n
 858          *              else @c false
 859          */
 860         bool IsFooterTranslucent(void) const;
 861
 862
 863         /**
 864          * Sets the translucency of the action bars.
 865          *
 866          * @since               2.0
 867          *
 868          * @return              An error code
 869          * @param[in]   actionBars              The action bars @n
 870          *                                                                              Multiple action bars can be combined using bitwise OR (see Tizen::Ui::Controls::FormActionBar).
 871          * @param[in]   translucent                             Set to @c to make the action bars translucent, @n
 872          *                                                                              else @c false
 873          * @exception   E_SUCCESS               The method is successful.
 874          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of a specified operation, or
 875          *                                                                              the specified action bars do not exist.
 876          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 877          * @exception   E_SYSTEM                A system error has occurred.
 878          * @remarks
 879          *                              - Modifying the translucency of the action bars causes the client area of the %Form to change.
 880          *                              - The translucency of multiple action bars can be modified at the same time by using logical OR for several values of FormActionBar.
 881          *                              - The method is not supported in 16-bit devices.
 882          */
 883         result SetActionBarsTranslucent(unsigned long actionBars, bool translucent);
 884
 885
 886         /**
 887          * Sets the visibility state of the action bars.
 888          *
 889          * @since               2.0
 890          *
 891          * @return              An error code
 892          * @param[in]   actionBars          The action bars @n
 893          *                                                                      Multiple action bars can be combined using bitwise OR.
 894          * @param[in]   visible             Set to @c true to make the action bars visible, @n
 895          *                                                                      else @c false
 896          * @exception   E_SUCCESS           The method is successful.
 897          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 898          *                                  the specified action bars does not exist.
 899          * @exception   E_SYSTEM                        A system error has occurred.
 900          * @remarks
 901          *                              - Modifying the translucency of action bars causes the client area of the %Form to change.
 902          *                              - The visibility of multiple action bars can be modified at the same time by using logical OR for several values of FormActionBar.
 903          * @see                 FormActionBar
 904          */
 905         result SetActionBarsVisible(unsigned long actionBars, bool visible);
 906
 907
 908         /**
 909          * Creates and returns an overlay region of the specified position and size. @n
 910          * Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 911          * The hardware capability for an overlay region is checked by using OverlayRegion::GetWidthUnit(), OverlayRegion::GetHeightUnit() and
 912          * OverlayRegion::GetMaxCount().
 913          * If the specified condition is not satisfied, @c E_INVALID_ARG exception is returned.
 914          *
 915          * @since               2.0
 916          *
 917          * @return              An overlay region instance
 918          * @param[in]   rect                            The x and y coordinates relative to the top-left corner of the form along with the width and height
 919          * @param[in]   regionType                              The type of the overlay region
 920          * @exception   E_SUCCESS                               The method is successful.
 921          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 922          * @exception   E_MAX_EXCEEDED                  The number of overlay regions has reached the maximum limit.
 923          * @exception   E_UNSUPPORTED_OPTION    The specified option of the overlay region type is not supported.
 924          * @exception   E_SYSTEM                                A system error has occurred.
 925          * @remarks
 926          *                              - The specific error code can be accessed using the GetLastResult() method.
 927          *                              - If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations
 928          *                              of the overlay region. @n
 929          *                              In such cases, it returns the @c E_INVALID_ARG exception. To prevent this problem,
 930          *                              the application should use the OverlayRegion::EvaluateBounds() method to get the validated bounds that
 931          *                              can be used as the input bounds of this method.
 932          *                              - Do not use OverlayRegion with OverlayPanel. If used, the @c E_SYSTEM exception is thrown.
 933          */
 934         OverlayRegion* GetOverlayRegionN(const Tizen::Graphics::Rectangle& rect, OverlayRegionType regionType);
 935
 936         /**
 937          * Creates and returns an overlay region of the specified position and size. @n
 938          * Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 939          * The hardware capability for an overlay region is checked by using OverlayRegion::GetWidthUnit(), OverlayRegion::GetHeightUnit() and
 940          * OverlayRegion::GetMaxCount().
 941          * If the specified condition is not satisfied, @c E_INVALID_ARG exception is returned.
 942          *
 943          * @since               2.1
 944          *
 945          * @return              An overlay region instance
 946          * @param[in]   rect                            The x and y coordinates relative to the top-left corner of the form along with the width and height
 947          * @param[in]   regionType                              The type of the overlay region
 948          * @exception   E_SUCCESS                               The method is successful.
 949          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 950          * @exception   E_MAX_EXCEEDED                  The number of overlay regions has reached the maximum limit.
 951          * @exception   E_UNSUPPORTED_OPTION    The specified option of the overlay region type is not supported.
 952          * @exception   E_SYSTEM                                A system error has occurred.
 953          * @remarks
 954          *                              - The specific error code can be accessed using the GetLastResult() method.
 955          *                              - If the application runs on multi-screen resolutions, the specified bounds may
 956          *                              not meet the hardware limitations of the overlay region. @n
 957          *                              In such cases, it returns the @c E_INVALID_ARG exception. @n
 958          *                              To prevent this problem, the application should use the OverlayRegion::EvaluateBoundsF() method to
 959          *                              get the validated bounds that can be used as the input bounds of this method.
 960          *                              - Do not use OverlayRegion with OverlayPanel. If used, the @c E_SYSTEM exception is thrown.
 961          */
 962         OverlayRegion* GetOverlayRegionN(const Tizen::Graphics::FloatRectangle& rect, OverlayRegionType regionType);
 963
 964
 965         /**
 966          * Creates and returns a graphics canvas whose bounds (position and size) are equal to the bounds of the client area of the %Form.
 967          *
 968          * @since         2.0
 969          *
 970          * @return      The graphic canvas of the %Form control, @n
 971          *                              else @c null if an error occurs
 972          * @exception   E_SUCCESS                                       The method is successful.
 973          * @exception   E_RESOURCE_UNAVAILABLE        The required resource is currently unavailable.
 974          * @remarks
 975          *                              - The method allocates Tizen::Graphics::Canvas whose bounds are equal to that of the client area of the %Form.
 976          *                              - It is the responsibility of the developers to deallocate the canvas after use.
 977          *                              - The canvas is valid only if the properties of the parent control of the canvas remain unchanged. @n
 978          *                              Therefore, delete the previously allocated canvas and create a new canvas using this method
 979          *                              if the size or position of the control is changed.
 980          *                              - The specific error code can be accessed using the GetLastResult() method.
 981          *                              - The Frame and %Form instances share a single frame-buffer. @n
 982          *                              Therefore, the custom drawing on the graphic canvas of the Frame and %Form controls appears on the
 983          *                              screen regardless of whether the control is currently visible on the screen.
 984          */
 985         Tizen::Graphics::Canvas* GetClientAreaCanvasN(void) const;
 986
 987         /**
 988          * Translates the specified position to the client coordinate.
 989          *
 990          * @since       2.0
 991          *
 992          * @return      The position relative to the top-left corner of the client area, @n
 993          *                              else @c (-1,-1) if the instance is invalid
 994          * @param[in]   position                The position relative to the top-left corner of the %Form control
 995          * @see         TranslateFromClientAreaPosition()
 996          */
 997         Tizen::Graphics::Point TranslateToClientAreaPosition(const Tizen::Graphics::Point& position) const;
 998
 999         /**
1000          * Translates the specified position to the client coordinate.
1001          *
1002          * @since       2.1
1003          *
1004          * @return      The position relative to the top-left corner of the client area, @n
1005          *                              else @c (-1,-1) if the instance is invalid
1006          * @param[in]   position                The position relative to the top-left corner of the %Form control
1007          * @see         TranslateFromClientAreaPosition()
1008          */
1009         Tizen::Graphics::FloatPoint TranslateToClientAreaPosition(const Tizen::Graphics::FloatPoint& position) const;
1010
1011         /**
1012          * Translates the specified client position to the control coordinate.
1013          *
1014          * @since       2.0
1015          *
1016          * @return      The position relative to the top-left corner of the %Form control, @n
1017          *                              else @c (-1,-1) if the instance is invalid
1018          * @param[in]   clientPosition     The position relative to the top-left corner of the client area
1019          * @see         TranslateToClientAreaPosition()
1020          */
1021         Tizen::Graphics::Point TranslateFromClientAreaPosition(const Tizen::Graphics::Point& clientPosition) const;
1022
1023         /**
1024          * Translates the specified client position to the control coordinate.
1025          *
1026          * @since       2.1
1027          *
1028          * @return      The position relative to the top-left corner of the %Form control, @n
1029          *                              else @c (-1,-1) if the instance is invalid
1030          * @param[in]   clientPosition     The position relative to the top-left corner of the client area
1031          * @see         TranslateToClientAreaPosition()
1032          */
1033         Tizen::Graphics::FloatPoint TranslateFromClientAreaPosition(const Tizen::Graphics::FloatPoint& clientPosition) const;
1034
1035         /**
1036      * Sets the %Form back event listener.
1037          *
1038          * @since       2.0
1039          *
1040      * @param[in]       pFormBackEventListener          The %Form back event listener to set
1041          * @see         Tizen::Ui::Controls::IFormBackEventListener.
1042          */
1043         void SetFormBackEventListener(IFormBackEventListener* pFormBackEventListener);
1044
1045
1046         /**
1047          * Gets the data binding context.
1048          *
1049          * @since 2.0
1050          *
1051          * @return        DataBindingContext        the data binding context
1052          * @exception    E_SUCCESS        The method is successful.
1053          * @exception    E_SYSTEM         A system error has occurred.
1054          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1055          */
1056         DataBindingContext* GetDataBindingContextN(void) const;
1057
1058         /**
1059         * Enables or disables the notification tray to remain open.
1060         *
1061         * @since 2.1
1062         *
1063         * @return       An error code
1064         * @param[in]    enable               Set to @c true to enable the notification tray to remain open, @n
1065         *                                      else @c false
1066         * @exception    E_SUCCESS            The method is successful.
1067         * @exception    E_INVALID_OPERATION        The current state of the instance prohibits the execution of a specified operation. @n
1068         *                                       If the style of %Form is not ::FORM_STYLE_INDICATOR or ::FORM_STYLE_INDICATOR_AUTO_HIDE,
1069         *                                       the method returns @c E_INVALID_OPERATION.
1070         * @remarks      If this method is not explicitly called, the notification tray is opened.
1071         * @see            IsNotificationTrayOpenEnabled()
1072         */
1073         result SetNotificationTrayOpenEnabled(bool enable);
1074
1075
1076         /**
1077         * Checks whether the notification tray is open or not.
1078         *
1079         * @since 2.1
1080         *
1081         * @return         @c true if the notification tray is open, @n
1082         *                 else @c false
1083         * @exception      E_SUCCESS            The method is successful.
1084         * @exception     E_INVALID_OPERATION        The current state of the instance prohibits the execution of a specified operation. @n
1085         *                                       If the style of %Form is not ::FORM_STYLE_INDICATOR or ::FORM_STYLE_INDICATOR_AUTO_HIDE,
1086         *                                       the method returns @c E_INVALID_OPERATION.
1087         * @remarks        The specific error code can be accessed using the GetLastResult() method.
1088         * @see            SetNotificationTrayOpenEnabled()
1089         */
1090         bool IsNotificationTrayOpenEnabled(void) const;
1091
1092 protected:
1093         friend class _FormImpl;
1094
1095         //
1096         //This method is for internal use only. Using this method can cause behavioral, security-related,
1097         //and consistency-related issues in the application.
1098         //
1099         // This method is reserved and may change its name at any time without
1100         // prior notice.
1101         //
1102         // @since 2.0
1103         //
1104         virtual void Form_Reserved1(void) { }
1105
1106         //
1107         //This method is for internal use only. Using this method can cause behavioral, security-related,
1108         //and consistency-related issues in the application.
1109         //
1110         // This method is reserved and may change its name at any time without
1111         // prior notice.
1112         //
1113         // @since 2.0
1114         //
1115         virtual void Form_Reserved2(void) { }
1116
1117         //
1118         //This method is for internal use only. Using this method can cause behavioral, security-related,
1119         //and consistency-related issues in the application.
1120         //
1121         // This method is reserved and may change its name at any time without
1122         // prior notice.
1123         //
1124         // @since 2.0
1125         //
1126         virtual void Form_Reserved3(void) { }
1127
1128 // Friend Class Declaration
1129 private:
1130         friend class UiBuilder;
1131         friend class Frame;
1132
1133 private:
1134         Form(const Form&);
1135         Form& operator =(const Form&);
1136
1137 }; // Form
1138
1139 } } } // Tizen::Ui::Controls
1140
1141 #endif // _FUI_CTRL_FORM_H_