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