inc/FUiCtrlForm.h

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