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
 632          *                      Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 633          */
 634         void SetOrientation(Orientation orientation);
 635
 636
 637         /**
 638          * @if OSPDEPREC
 639          * Sets an action ID of each softkey.
 640          *
 641          * @brief <i> [Deprecated]  </i>
 642          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 643          * @since   2.0
 644          *
 645          * @param[in]   softkey                 The softkey
 646          * @param[in]   actionId                The action ID to set
 647          * @endif
 648          */
 649         void SetSoftkeyActionId(Softkey softkey, int actionId);
 650
 651
 652         /**
 653          * @if OSPDEPREC
 654          * Enables or disables the specified softkey.
 655          *
 656          * @brief <i> [Deprecated]  </i>
 657          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 658          * @since   2.0
 659          *
 660          * @param[in]   softkey                 The softkey
 661          * @param[in]   enable                  Set to @c true to enable this softkey @n
 662          *                                                      else @c false
 663          * @endif
 664          */
 665         void SetSoftkeyEnabled(Softkey softkey, bool enable);
 666
 667
 668         /**
 669          * @if OSPDEPREC
 670          * Sets the title icon of the %Form control.
 671          *
 672          * @brief <i> [Deprecated]  </i>
 673          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 674          *                              use the %Header control.
 675          * @since           2.0
 676          *
 677          * @return                      An error code
 678          * @param[in]           pTitleBitmap                    The title icon to set, @n
 679          *                                                                                      else @c null if the title icon is removed
 680          * @exception           E_SUCCESS                       The method is successful.
 681          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of a specified operation (that is, this control cannot be displayed).
 682          * @exception           E_SYSTEM                        A system error has occurred.
 683          * @endif
 684          */
 685         result SetTitleIcon(const Tizen::Graphics::Bitmap* pTitleBitmap);
 686
 687
 688         /**
 689          * @if OSPDEPREC
 690          * Sets the title of this %Form control.
 691          *
 692          * @brief <i> [Deprecated]  </i>
 693          * @deprecated  This method is deprecated because the use of the Title control is no longer recommended. Instead of the %Title control,
 694          *                              use the Header control.
 695      * @since   2.0
 696          *
 697          * @return              An error code
 698          * @param[in]   title                           The title to set
 699          * @param[in]   alignment                   The horizontal alignment
 700          * @exception   E_SUCCESS                       The method is successful.
 701          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of a specified operation (that is, this control cannot be displayed).
 702          * @exception   E_SYSTEM                        A system error has occurred.
 703          * @remarks             If the size of the text exceeds the displayable area, the text slides automatically. @n
 704          *                              Note that when the title icon is set along with the title text, the title retains the left alignment.
 705          * @endif
 706          */
 707         result SetTitleText(const Tizen::Base::String& title, HorizontalAlignment alignment = ALIGNMENT_CENTER);
 708
 709
 710         /**
 711          * @if OSPDEPREC
 712          * Sets the icon of the softkey.
 713          *
 714          * @brief <i> [Deprecated]  </i>
 715          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 716      * @since   2.0
 717          *
 718          * @param[in]   softkey             The softkey
 719          * @param[in]   normalBitmap    The Bitmap of the normal icon
 720          * @param[in]   pPressedBitmap  The Bitmap of the pressed icon
 721          * @remarks             If both the icon and text are set for a softkey at the same time, the text takes precedence over the icon.
 722          * @endif
 723          */
 724         void SetSoftkeyIcon(Softkey softkey, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap);
 725
 726         /**
 727          * @if OSPDEPREC
 728          * Sets the text of the specified softkey.
 729          *
 730          * @brief <i> [Deprecated]  </i>
 731          * @deprecated This method is deprecated because the use of the Softkey control is no longer recommended.
 732          * @since   2.0
 733          *
 734          * @param[in]   softkey The softkey
 735          * @param[in]   text            The text to set
 736          * @remarks             If both the icon and text are set for a softkey at the same time, the text takes precedence over the icon. @n
 737          *                              To display text in multi-lines or to denote the end of line, use '\\n'.
 738          * @endif
 739          */
 740         void SetSoftkeyText(Softkey softkey, const Tizen::Base::String& text);
 741
 742         /**
 743          * Gets the pointer to the Footer control if it exists.
 744          *
 745          * @since               2.0
 746          *
 747          * @return              A pointer to the Footer control, @n
 748          *                              else @c null if there is no %Footer
 749          * @remarks             The retrieved pointer may be temporary. Therefore, it should not be stored after immediate use.
 750          */
 751         Footer* GetFooter(void) const;
 752
 753
 754         /**
 755          * Gets the pointer to the Header control if it exists.
 756          *
 757          * @since               2.0
 758          *
 759          * @return              A pointer to the Header control, @n
 760          *                              else @c null if there is no %Header
 761          * @remarks             The retrieved pointer may be temporary. Therefore, it should not be
 762          *              stored after immediate use.
 763          */
 764         Header* GetHeader(void) const;
 765
 766
 767         /**
 768          * Checks whether the %Form control has a Footer.
 769          *
 770          * @since               2.0
 771          *
 772          * @return              @c true if the %Form control has a Footer, @n
 773          *                              else @c false
 774          */
 775         bool HasFooter(void) const;
 776
 777
 778         /**
 779          * Checks whether the %Form control has a Header.
 780          *
 781          * @since               2.0
 782          *
 783          * @return              @c true if the %Form control has a Header, @n
 784          *                              else @c false
 785          */
 786         bool HasHeader(void) const;
 787
 788
 789         /**
 790          * Checks whether the Indicator control is visible.
 791          *
 792          * @since               2.0
 793          *
 794          * @return              @c true if the Indicator control is visible, @n
 795          *                              else @c false
 796          */
 797         bool IsIndicatorVisible(void) const;
 798
 799
 800         /**
 801          * Checks whether the Header control is visible.
 802          *
 803          * @since               2.0
 804          *
 805          * @return              @c true if the Header control is visible, @n
 806          *                              else @c false
 807          */
 808         bool IsHeaderVisible(void) const;
 809
 810
 811         /**
 812          * Checks whether the Footer control is visible.
 813          *
 814          * @since               2.0
 815          *
 816          * @return              @c true if the Footer control is visible, @n
 817          *                              else @c false
 818          */
 819         bool IsFooterVisible(void) const;
 820
 821
 822         /**
 823          * Checks whether the Indicator control is translucent.
 824          *
 825          * @since               2.0
 826          *
 827          * @return              @c true if the Indicator control is translucent, @n
 828          *                              else @c false
 829          */
 830         bool IsIndicatorTranslucent(void) const;
 831
 832
 833         /**
 834          * Checks whether the Header control is translucent.
 835          *
 836          * @since               2.0
 837          *
 838          * @return              @c true if the Header control is translucent, @n
 839          *                              else @c false
 840          */
 841         bool IsHeaderTranslucent(void) const;
 842
 843
 844         /**
 845          * Checks whether the Footer control is translucent.
 846          *
 847          * @since               2.0
 848          *
 849          * @return              @c true if the Footer control is translucent, @n
 850          *              else @c false
 851          */
 852         bool IsFooterTranslucent(void) const;
 853
 854
 855         /**
 856          * Sets the translucency of the action bars.
 857          *
 858          * @since               2.0
 859          *
 860          * @return              An error code
 861          * @param[in]   actionBars              The action bars @n
 862          *                                                                              Multiple action bars can be combined using bitwise OR (see Tizen::Ui::Controls::FormActionBar).
 863          * @param[in]   translucent                             Set to @c to make the action bars translucent, @n
 864          *                                                                              else @c false
 865          * @exception   E_SUCCESS               The method is successful.
 866          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of a specified operation, or
 867          *                                                                              the specified action bars do not exist.
 868          * @exception   E_UNSUPPORTED_OPERATION This operation is not supported.
 869          * @exception   E_SYSTEM                A system error has occurred.
 870          * @remarks             Modifying the translucency of the action bars causes the client area of the %Form to change. @n
 871          *              The translucency of multiple action bars can be modified at the same time by using logical OR for several values of FormActionBar.
 872          * @remarks             The method is not supported in 16-bit devices.
 873      * @see         FormActionBar
 874          */
 875         result SetActionBarsTranslucent(unsigned long actionBars, bool translucent);
 876
 877
 878         /**
 879          * Sets the visibility state of the action bars.
 880          *
 881          * @since               2.0
 882          *
 883          * @return              An error code
 884          * @param[in]   actionBars          The action bars @n
 885          *                                                                      Multiple action bars can be combined using bitwise OR (see Tizen::Ui::Controls::FormActionBar).
 886          * @param[in]   visible             Set to @c true to make the action bars visible, @n
 887          *                                                                      else @c false
 888          * @exception   E_SUCCESS           The method is successful.
 889          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, or
 890          *                                  the specified action bars does not exist.
 891          * @exception   E_SYSTEM                        A system error has occurred.
 892          * @remarks             Modifying the translucency of action bars causes the client area of the %Form to change. @n
 893          *              The visibility of multiple action bars can be modified at the same time by using logical OR for several values of FormActionBar.
 894      * @see         FormActionBar
 895          */
 896         result SetActionBarsVisible(unsigned long actionBars, bool visible);
 897
 898
 899         /**
 900          * Creates and returns an overlay region of the specified position and size. @n
 901          * Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 902          * The hardware capability for an overlay region is checked by using OverlayRegion::GetWidthUnit(), OverlayRegion::GetHeightUnit() and
 903          * OverlayRegion::GetMaxCount().
 904          * If the specified condition is not satisfied, E_INVALID_ARG exception is returned.
 905          *
 906          * @since               2.0
 907          *
 908          * @return              An overlay region instance
 909          * @param[in]   rect                            The x and y coordinates relative to the top-left corner of the form along with the width and height
 910          * @param[in]   regionType                              The type of the overlay region
 911          * @exception   E_SUCCESS                               The method is successful.
 912          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 913          * @exception   E_MAX_EXCEEDED                  The number of overlay regions has reached the maximum limit.
 914          * @exception   E_UNSUPPORTED_OPTION    The specified option of the overlay region type is not supported.
 915          * @exception   E_SYSTEM                                A system error has occurred.
 916          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 917          *                              If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. @n
 918          *              In such cases, GetOverlayRegionN() returns the E_INVALID_ARG exception. To prevent this problem, the application should use the
 919          *                      OverlayRegion::EvaluateBounds() method to get the validated bounds that can be used as the input bounds of the GetOverlayRegionN() method.
 920          * @remarks             Do not use OverlayRegion with OverlayPanel. If used, the E_SYSTEM exception is thrown.
 921          */
 922         OverlayRegion* GetOverlayRegionN(const Tizen::Graphics::Rectangle& rect, OverlayRegionType regionType);
 923
 924         /**
 925          * Creates and returns an overlay region of the specified position and size. @n
 926          * Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 927          * The hardware capability for an overlay region is checked by using OverlayRegion::GetWidthUnit(), OverlayRegion::GetHeightUnit() and
 928          * OverlayRegion::GetMaxCount().
 929          * If the specified condition is not satisfied, E_INVALID_ARG exception is returned.
 930          *
 931          * @since               2.1
 932          *
 933          * @return              An overlay region instance
 934          * @param[in]   rect                            The x and y coordinates relative to the top-left corner of the form along with the width and height
 935          * @param[in]   regionType                              The type of the overlay region
 936          * @exception   E_SUCCESS                               The method is successful.
 937          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 938          * @exception   E_MAX_EXCEEDED                  The number of overlay regions has reached the maximum limit.
 939          * @exception   E_UNSUPPORTED_OPTION    The specified option of the overlay region type is not supported.
 940          * @exception   E_SYSTEM                                A system error has occurred.
 941          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 942          *                              If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. @n
 943          *              In such cases, GetOverlayRegionNF() returns the E_INVALID_ARG exception. To prevent this problem, the application should use the
 944          *                      OverlayRegion::EvaluateBoundsF() method to get the validated bounds that can be used as the input bounds of the GetOverlayRegionNF() method.
 945          * @remarks             Do not use OverlayRegion with OverlayPanel. If used, the E_SYSTEM exception is thrown.
 946          */
 947         OverlayRegion* GetOverlayRegionN(const Tizen::Graphics::FloatRectangle& rect, OverlayRegionType regionType);
 948
 949
 950         /**
 951          * Creates and returns a graphics canvas whose bounds (position and size) are equal to the bounds of the client area of the %Form.
 952          *
 953          * @since         2.0
 954          *
 955          * @return      The graphic canvas of the %Form control, @n
 956          *                              else @c null if an error occurs
 957          * @exception   E_SUCCESS                                       The method is successful.
 958          * @exception   E_RESOURCE_UNAVAILABLE        The required resource is currently unavailable.
 959          * @remarks             The method allocates Tizen::Graphics::Canvas whose bounds are equal to that of the client area of the %Form. @n
 960          *                              It is the responsibility of the developers to deallocate the canvas after use.
 961          * @remarks             The canvas is valid only if the properties of the parent control of the canvas remain unchanged. @n
 962          *              Therefore, delete the previously allocated canvas and create a new canvas using the GetClientAreaCanvasN() method @n
 963          *              if the size or position of the control is changed.
 964          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 965          * @remarks     The Frame and %Form instances share a single frame-buffer. @n
 966          *                              Therefore, the custom drawing on the graphic canvas of the Frame and %Form controls appears on the screen regardless of whether the
 967          *                              control is currently visible on the screen.
 968          */
 969         Tizen::Graphics::Canvas* GetClientAreaCanvasN(void) const;
 970
 971         /**
 972          * Translates the specified position to the client coordinate.
 973          *
 974          * @since       2.0
 975          *
 976          * @return      The position relative to the top-left corner of the client area, @n
 977          *                              else @c (-1,-1) if the instance is invalid
 978          * @param[in]   position                The position relative to the top-left corner of the %Form control
 979          * @see         TranslateFromClientAreaPosition()
 980          */
 981         Tizen::Graphics::Point TranslateToClientAreaPosition(const Tizen::Graphics::Point& position) const;
 982
 983         /**
 984          * Translates the specified position to the client coordinate.
 985          *
 986          * @since       2.1
 987          *
 988          * @return      The position relative to the top-left corner of the client area, @n
 989          *                              else @c (-1,-1) if the instance is invalid
 990          * @param[in]   position                The position relative to the top-left corner of the %Form control
 991          * @see         TranslateFromClientAreaPosition()
 992          */
 993         Tizen::Graphics::FloatPoint TranslateToClientAreaPosition(const Tizen::Graphics::FloatPoint& position) const;
 994
 995         /**
 996          * Translates the specified client position to the control coordinate.
 997          *
 998          * @since       2.0
 999          *
1000          * @return      The position relative to the top-left corner of the %Form control, @n
1001          *                              else @c (-1,-1) if the instance is invalid
1002          * @param[in]   clientPosition     The position relative to the top-left corner of the client area
1003          * @see         TranslateToClientAreaPosition()
1004          */
1005         Tizen::Graphics::Point TranslateFromClientAreaPosition(const Tizen::Graphics::Point& clientPosition) const;
1006
1007         /**
1008          * Translates the specified client position to the control coordinate.
1009          *
1010          * @since       2.1
1011          *
1012          * @return      The position relative to the top-left corner of the %Form control, @n
1013          *                              else @c (-1,-1) if the instance is invalid
1014          * @param[in]   clientPosition     The position relative to the top-left corner of the client area
1015          * @see         TranslateToClientAreaPosition()
1016          */
1017         Tizen::Graphics::FloatPoint TranslateFromClientAreaPosition(const Tizen::Graphics::FloatPoint& clientPosition) const;
1018
1019         /**
1020      * Sets the %Form back event listener.
1021          *
1022          * @since       2.0
1023          *
1024      * @param[in]       pFormBackEventListener          The %Form back event listener to set
1025          * @see         Tizen::Ui::Controls::IFormBackEventListener.
1026          */
1027         void SetFormBackEventListener(IFormBackEventListener* pFormBackEventListener);
1028
1029
1030         /**
1031          * Gets the data binding context.
1032          *
1033          * @since 2.0
1034          *
1035          * @return        DataBindingContext        the data binding context
1036          * @exception    E_SUCCESS        The method is successful.
1037          * @exception    E_SYSTEM         A system error has occurred.
1038          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1039          */
1040         DataBindingContext* GetDataBindingContextN(void) const;
1041
1042         /**
1043         * Enables or disables the notification tray to be opened.
1044         *
1045         * @since 2.1
1046         *
1047         * @return       An error code
1048         * @param[in]    enable               Set to @c true to enable the notification tray to be opened, @n
1049         *                                      else @c false
1050         * @exception    E_SUCCESS            The method is successful.
1051         * @exception    E_INVALID_OPERATION        The current state of the instance prohibits the execution of a specified operation. @n
1052         *                              If the style of %Form isn’t FORM_STYLE_INDICATOR or FORM_STYLE_INDICATOR_AUTO_HIDE, the method returns E_INVALID_OPERATION.
1053         * @remarks      If this method is not explicitly called, the notification tray is opened.
1054         * @see            IsNotificationTrayOpenEnabled()
1055         */
1056         result SetNotificationTrayOpenEnabled(bool enable);
1057
1058
1059         /**
1060         * Checks whether the notification tray is opened or not.
1061         *
1062         * @since 2.1
1063         *
1064         * @return         @c true if the notification tray is opened, @n
1065         *                 else @c false
1066         * @exception      E_SUCCESS            The method is successful.
1067         * @exception     E_INVALID_OPERATION        The current state of the instance prohibits the execution of a specified operation. @n
1068         *                              If the style of %Form isn’t FORM_STYLE_INDICATOR or FORM_STYLE_INDICATOR_AUTO_HIDE, the method returns E_INVALID_OPERATION.
1069         * @remarks        The specific error code can be accessed using the GetLastResult() method.
1070         * @see            SetNotificationTrayOpenEnabled()
1071         */
1072         bool IsNotificationTrayOpenEnabled(void) const;
1073
1074 protected:
1075         friend class _FormImpl;
1076
1077         //
1078         //This method is for internal use only. Using this method can cause behavioral, security-related,
1079         //and consistency-related issues in the application.
1080         //
1081         // This method is reserved and may change its name at any time without
1082         // prior notice.
1083         //
1084         // @since 2.0
1085         //
1086         virtual void Form_Reserved1(void) { }
1087
1088         //
1089         //This method is for internal use only. Using this method can cause behavioral, security-related,
1090         //and consistency-related issues in the application.
1091         //
1092         // This method is reserved and may change its name at any time without
1093         // prior notice.
1094         //
1095         // @since 2.0
1096         //
1097         virtual void Form_Reserved2(void) { }
1098
1099         //
1100         //This method is for internal use only. Using this method can cause behavioral, security-related,
1101         //and consistency-related issues in the application.
1102         //
1103         // This method is reserved and may change its name at any time without
1104         // prior notice.
1105         //
1106         // @since 2.0
1107         //
1108         virtual void Form_Reserved3(void) { }
1109
1110 // Friend Class Declaration
1111 private:
1112         friend class UiBuilder;
1113         friend class Frame;
1114
1115 private:
1116         Form(const Form&);
1117         Form& operator =(const Form&);
1118
1119 }; // Form
1120
1121 } } } // Tizen::Ui::Controls
1122
1123 #endif // _FUI_CTRL_FORM_H_
1124