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