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